DEV Community: Thomas Honeyman

Introducing Halogen Hooks

Thomas Honeyman — Tue, 19 May 2020 23:22:29 +0000

Components are the only way to use local state in PureScript's Halogen, but they come with strings attached: you have to render something. Components are therefore ideal for writing stateful UI code, but ill-suited for writing reusable stateful logic.

Read the original: Introducing Halogen Hooks on thomashoneyman.com

Stateful logic shows up everywhere in Halogen. State is used for UI concerns like persisting how many times a button has been clicked or whether a modal is open. But state is needed for many use cases which have nothing directly to do with rendering. That includes interacting with external data sources, managing subscriptions, handling forms, and many other things.

If you try to handle these non-UI use cases for state using components you usually end up with:

Types and logic duplicated among different components, which can be only reduced -- not eliminated -- with helper functions
Complex patterns like higher-order and renderless components, solutions so unwieldy that most Halogen developers use them only as a last resort

Inspired by React Hooks, Halogen Hooks are a new solution for writing reusable, stateful logic. Hooks are simple functions with access to Halogen features like local state. These stateful functions can produce values of any type, not just UI code. But they're no less powerful than components: we can turn a Hook that returns Halogen's ComponentHTML type into an ordinary component with a single function call.

Hooks are a simpler mental model for writing code in Halogen. In the Hooks model, applications are made up of ordinary PureScript functions and stateful Hooks functions. Components, in this model, are simply stateful functions that produce ComponentHTML.

You can start using Hooks today with the Halogen Hooks library.

Hooks In Action: UseWindowWidth

Let's say we need the current browser window width.

We will need to register an event listener on the window, store the width in state, update our state when the window resizes, and clean up our event listener when the component unmounts.

To implement this code we need component-only features like local state, initializers, and finalizers. But this code doesn't make sense as a component -- it's meant to be used by a component.

We do have some options: we could implement this code as a collection of helper functions and types for a component to import, or we could write a higher-order or renderless component.

But no existing solution in Halogen today can match this for convenience and readability:

myComponent :: forall q i o m. MonadAff m => H.Component HH.HTML q i o m
myComponent = Hooks.component \_ _ -> Hooks.do
  width <- useWindowWidth -- our custom Hook
  Hooks.pure do
    HH.p_ [ HH.text $ "Window width is " <> maybe "" show width ]

This code is readable: we use the window width and render it as paragraph text. When the width changes the text will re-render.

We've written a simple hook that returns ComponentHTML, so we can use the Hooks.component function to turn it into an ordinary component.

The underlying useWindowWidth hook takes care of all the complicated logic necessary to subscribe to the window width and it simply returns the width itself. One function call is all we need to use it.

We've now seen how to use a hook to reuse stateful logic, but how would you actually implement one?

Implementing UseWindowWidth

Hooks are functions that can opt in to component features like state, side effects, and queries. Let's break down what our useWindowWidth hook will need:

We need to use local state to persist the window width
We need to use a side effect to subscribe to window events when the component initializes and unsubscribe when it finalizes.

We can capture those two features using a newtype, which will also be used to uniquely identify our new Hook.

newtype UseWindowWidth hooks =
  UseWindowWidth (UseEffect (UseState (Maybe Int) hooks))

derive instance newtypeUseWindowWidth :: Newtype (UseWindowWidth hooks) _

This type represents using local state of the type Maybe Int, and then using a side effect. If we needed to, we could use more independent states and effects, or mix in other Hook types.

Next, let's turn to our new Hook's type signature.

useWindowWidth
  :: forall m
   . MonadAff m
  => Hook m UseWindowWidth (Maybe Int)
--   [1]    [2]            [3]

A Hook is a (possibly) stateful function which can run effects from some monad m, uses a particular set of hooks, and returns a value.
Our Hook type, UseWindowWidth, uniquely identifies this Hook and specifies what Hooks are used internally. The Hooks library will unwrap this newtype and verify the correct Hooks were used in the correct order in the implementation.
This Hook returns a Maybe Int: the current window width.

Now let's turn to our implementation, taken from the full implementation in the Hooks examples:

useWindowWidth = Hooks.wrap Hooks.do
  width /\ widthId <- Hooks.useState Nothing -- [1]

  Hooks.useLifecycleEffect do -- [2]
    subscriptionId <- subscribeToWindow (H.modify_ widthId)
    pure $ Just $ Hooks.unsubscribe subscriptionId -- [3]

  Hooks.pure width -- [4]
  where
  -- we'll define the `subscribeToWindow` function in the next section, as it's
  -- ordinary effectful code and not Hooks specific.
  subscribeToWindow modifyWidth = ...

Our new Hook is built out of other hooks, provided by the Hooks library as primitives:

First, we use useState to produce a new independent state which will hold the window width. Its initial state is Nothing, because we don't yet have a window width. We specified in our UseWindowWidth type that this Hook should return Maybe Int, so the compiler will ensure we use that type. The Hook returns the current value in state to us, and also a unique identifier we can use to update the state -- more on this soon.
Next, we use useLifecycleEffect to run an effect when the component initializes and another one when the component finalizes. Our initializer function subscribes to the window using subscribeToWindow, an effectful function we defined in a where block underneath the body of the Hook.
Here, we return our optional 'disposal' function to run when the component finalizes. (It's technically unnecessary to end Halogen subscriptions in a finalizer because they are automatically cleaned up when a component unmounts. But that's a special case: you would need to unsubscribe when using the other effect hook, useTickEffect, and it's common to run a cleanup function when a component is finalized.)
Finally, we return the window width from the hook.

The built-in useState and useLifecycleEffect hooks are basic building blocks you can use directly in Hooks components or to implement your own custom hooks like this one. There are several built-in Hooks you can use.

I omitted the definition of subscribeToWindow to keep our implementation concise, but we can now take a look:

subscribeToWindow
  :: ((Maybe Int -> Maybe Int) -> HookM m Unit)
  -- this is the same type variable `m` introduced by `useWindowWidth`
  -> HookM m H.SubscriptionId
subscribeToWindow modifyWidth = do
  let
    readWidth :: Window -> HookM _ _ _ Unit
    readWidth =
      modifyWidth <<< const <<< Just <=< liftEffect <<< Window.innerWidth

  window <- liftEffect HTML.window
  subscriptionId <- Hooks.subscribe do
    ES.eventListenerEventSource
      (EventType "resize")
      (Window.toEventTarget window)
      (Event.target >>> map (fromEventTarget >>> readWidth))

  readWidth window
  pure subscriptionId

This function sets up the subscription and ensures our state is updated every time the window resizes. It's almost identical to what you would write in HalogenM, but you may have noticed some differences:

This function runs in the HookM monad, not HalogenM. This monad is almost identical to HalogenM and it's used to implement effectful code in Hooks. You can do anything in HookM that you can do in HalogenM, such as start subscriptions, query child components, or fork threads.
There is no state type in the HookM monad, but we can still update state using the unique identifier returned by useState. You can pass this identifier to the modify, modify_, put, and get functions you're familiar with from HalogenM. This is a feature of Hooks that lets you have as many independent states as you would like, each with its own modify function.
There is no action type because Hooks don't need actions. Where you write actions in Halogen, you write HookM functions in Hooks. However, you can still manually implement the action / handler pattern from Halogen if you want to.
There is no slot type because slots only make sense in the context of components. You can only use functions that use a slot type if you have used the component function to turn your Hook into a component first.
There is no output type because outputs also only make sense in the context of components. Like the slot type, you must turn your Hook into a component before you can raise output messages.

If you are ready to learn more about using and implementing Hooks, please see the official Halogen Hooks guide.

What About Components?

Halogen Hooks is implemented on top of Halogen and it makes no changes to the underlying library. Components are here to stay, and Hooks make no effort to move away from them. Hooks-based components are still ordinary Halogen components.

In fact, while you can combine primitive and custom Hooks to your heart's delight, the only way to actually run a Hook is to interpret it into a Halogen component. This can be done for any Hook that returns Halogen's ComponentHTML type.

Halogen components are still the foundation everything stands on. Hooks themselves can only be executed as components. But you will likely find nested Hooks are much nicer to use than the equivalent tree of components, and that it's more convenient to write most components the Hooks way.

This means that Hooks can be adopted incrementally: you don't need to use Hooks everywhere in your code and Hooks-based components are still ordinary Halogen components. You don't have to update your existing components to begin using Hooks in new ones.

Next Steps

The Halogen Hooks repository contains plenty of documentation on how to get started with Hooks.

Hooks are brand-new for Halogen, and if you encounter trouble using them I hope you take the time to stop by the issue tracker and we can work together to make the library better for everyone.

Practical Profunctor Lenses & Optics In PureScript

Thomas Honeyman — Sat, 17 Aug 2019 21:26:36 +0000

Optics are among the most rewarding tools in functional programming. You can use them to manipulate values within data structures without boilerplate -- you just need a few types and functions from an optics library like profunctor-lenses.

Consider working with a deeply-nested data structure like this one:

type NestedData =
  Maybe (Array { foo :: Tuple String (Either Int Boolean), bar :: String })

Faced with this type, ask yourself:

What code would I write to update the deeply-nested Int value, given an index in the outer array? Would my code be terse, readable, and maintainable?
How many functions would it take to get, set, and modify the Array, foo, or bar values? The inner values within foo?
How quickly and easily could I update my code if this type changed -- if, for example, Maybe (Array { foo :: ... }) became Array { foo :: Maybe ... }? How many functions would I have to update?

If you disliked your answers, read on: profunctor optics help you manipulate any layer of even complex structures like this one with ease.

This article will teach you to be productive with profunctor lenses, even if you haven't used them before. You'll learn how to use the four most common optics -- lenses, prisms, traversals, and isos -- to solve practical problems.

If you're looking for a more thorough introduction, I recommend Brian Marick's book Lenses for the Mere Mortal.

Original article: Practical Profunctor Lenses & Optics in PureScript

Sections

A brief demonstration of profunctor optics in action
Cheatsheet: common types, functions, and constructors
Lens, lens functions, constructing lenses, and At lenses
Prism, prism functions, and constructing prisms
Tips for composing lenses, prisms, and other optics
Traversal, traversal functions, and Index traversals
Iso, iso functions, and constructing isos
Related resources & wrapping up

Profunctor Lenses & Optics In Action

Let's use our deeply-nested data type to prove the flexibility and power of profunctor optics.

type NestedData =
  Maybe (Array { foo :: Tuple String (Either Int Boolean), bar :: String })

To retrieve or update the Int value within NestedData, given an index in the outer array, we'd likely write a pair of functions like these:

getNestedInt :: Int -> NestedData -> Maybe Int
getNestedInt index nested = case nested >>= (_ !! index) of
  Nothing -> Nothing
  Just { foo: Tuple _ eitherInt } -> case eitherInt of
    Left int -> Just int
    Right _ -> Nothing

modifyNestedInt :: Int -> (Int -> Int) -> NestedData -> NestedData
modifyNestedInt index modifyFn nested = case _ of
  Nothing -> Nothing
  Just array -> Array.modifyAt index modifyFoo array
  where
  modifyFoo record@{ foo: Tuple str eitherInt } = case eitherInt of
    Left int -> record { foo = Tuple str (Left (modifyFn int)) }
    Right _ -> record

We can do better. Let's replace both functions with a single optic.

Our optic will support much more than just getting or setting values, and we'll construct it from several smaller optics in a single line of code.

Let's start with those small optics. Each optic below manages a single layer of structure. Except for _foo, they're all pre-defined in the profunctor-lenses library (along with most other common data types and type classes in PureScript). By convention, optics are prefixed with an underscore.

-- Access the second element of a tuple
_2 :: forall a b. Lens' (Tuple a b) b

-- Access the value of a record at the label "foo"
_foo :: forall a r. Lens' { foo :: a | r } a

-- Access the value within the `Just` constructor of a `Maybe`,
-- if it exists
_Just :: forall a. Prism' (Maybe a) a

-- Access the value within the `Left` constructor of an `Either`,
-- if it exists
_Left :: forall a b. Prism' (Either a b) a

-- Access the nth index of an `Array`, if it exists
ix :: forall a. Int -> Traversal' (Array a) a

We can use the above optics to deal with a single layer of structure at a time. To work with many layers of structure, we compose optics together. Most people read this composition left-to-right, where <<< represents moving a single layer deeper.

For example, you can read the composed optic below as "go through the Just layer, then the Left layer." You can also read it right-to-left: "The optic focuses on the value in a Left, which is itself within a Just."

_LeftWithinJust :: forall a b. Prism' (Maybe (Either a b)) a
_LeftWithinJust = _Just <<< _Left

We now know how to compose optics, so let's write one which focuses on the Int inside our NestedData type.

The function below produces the optic we want, given a particular index in the outer array. Notice how the composition, read left-to-right, lines up with the layers of structure in the type. _Just lines up with Maybe, ix lines up with Array, and so on.

-- the same type we've been working with, for reference
type NestedData =
  Maybe (Array { foo :: Tuple String (Either Int Boolean), bar :: String })

-- This function constructs an optic which accesses the `Int` value
-- within our deeply-nested type, if it exists
_NestedInt :: Int -> Traversal' NestedData Int
_NestedInt index = _Just <<< ix index <<< _foo <<< _2 <<< _Left

With this optic in hand, we can replace both of our previous functions with simple one-liners:

getNestedInt :: Int -> NestedData -> Maybe Int
getNestedInt index = preview (_NestedInt index)

modifyNestedInt :: Int -> (Int -> Int) -> NestedData -> NestedData
modifyNestedInt index = over (_NestedInt index)

...and that's it! We now have simple, maintainable replacements for our original functions.

Profunctor lenses also help us adapt to changes in our data types. Let's handle a significant change to NestedData:

 type NestedData =
-  Maybe (Array { foo :: Tuple String (Either Int Boolean), bar :: String })
+  Array { foo :: Maybe (Tuple String (Either Int Boolean)), bar :: String }

Our composition is adaptable -- unlike our original functions. When the underlying structure changes, we can simply shuffle around or replace the optics we composed. Even better, since we used functions that work with most optics (preview and over), we only have to update the underlying optic for our code to work.

One optic serves as the source of truth for an entire family of functions for manipulating a value within structure. Even this significant change to the NestedData type only requires a trivial change to our code.

 _NestedInt :: Int -> Traversal' NestedData Int
-_NestedInt index = _Just <<< ix index <<< _foo <<< _2 <<< _Left
+_NestedInt index = ix index <<< _foo <<< _Just <<< _2 <<< _Left

With this simple re-ordering, our optics-based getNestedInt and modifyNestedInt functions handle the new NestedData type. Compare this to the effort of refactoring the original functions!

Let's recap what we've learned so far:

Optics are a terse, flexible way to manipulate values within structure.
Individual optics usually deal with a single layer of structure.
Compose optics together to deal with many layers of structure, where the rightmost optic represents the deepest layer.
Adapt to changes in data structures by adjusting the composition used to work with that structure
Use an optic with optic functions like preview and over to perform tasks like getting, setting, modifying, and more.
By convention, optics are prefixed with an underscore.

Optics are a deep, fascinating topic, but this article focuses on their practical benefits. Over the next several sections you'll learn more about how to use them to write elegant solutions to practical problems in your code.

Cheatsheet: Types, Functions, and Constructors

PureScript's flagship optics library is profunctor-lenses, which encompasses a family of optic types, functions, and constructors. You should understand optics from each of these three angles.

View the profunctor optics cheatsheet

Setup

I wrote this article with PureScript v0.13.2, Spago v0.8.5, and the July 25, 2019 package set (psc-0.13.2-20190725). Code along by initializing a new project and installing the libraries I used:

spago init
spago install profunctor-lenses remotedata

You can start a repl with spago repl. I recommend using a .purs-repl file in the root of the project to automatically import the modules you need. I used this one.

I must warn you: lenses are highly general and, without type annotations, you're likely to run into obscure errors in the repl. I recommend you:

Define new lenses with the :paste command so you can give them the same type I did in this article (use Ctrl+D to end the paste)
Annotate the optic or result type inline if you get a type error
Or, write optics in a module in your editor (with type annotations), and then import the module into the repl
Review "Identifying an optic from type spewage" from Marick's Lenses for the Mere Mortal.

In real-world code, this is typically unnecessary because there is enough context for the compiler to infer all types. Now, let's turn to our first optic -- the namesake of the profunctor-lenses library!

Lenses

Lenses are for product types like records and tuples. The type Lens' s a means that the structure s contains a single value of type a. Lenses are used to get, set, or modify the value a within structure when you know it exists.

-- This lens focuses on the second element of a tuple and is implemented
-- in the Data.Lens.Lens.Tuple module.
_2 :: forall a b. Lens' (Tuple a b) b

-- This lens focuses on the "name" field of a record; we have to construct
-- this one ourselves.
_name :: forall a r. Lens' { name :: a | r } a
_name = prop (SProxy :: SProxy "name")

I will use these to demonstrate the common lens functions view, set, and over. Then, I'll show you how to construct lenses for your types by implementing the above optics from scratch.

Common Functions For Working With Lenses

Use view with a lens Lens' s a to get the value a from the structure s. Lenses always contain their focused value, so this operation will always succeed.

-- We can use our `_2` lens to retrieve the second element of a tuple
snd :: forall a b. Tuple a b -> b
snd = view _2

> view _2 (Tuple "five" 10)
10

-- We can use our `_name` lens to retrieve the value of the 'name' field
-- from a record.
getName :: forall a r. { name :: a | r } -> a
getName = view _name

> view _name { name: "Tim", age: 40 }
"Tim"

Use set with a lens Lens' s a and a value of type a to overwrite the focused value a within the structure s.

-- We can use our `_2` lens to replace the second element of a tuple.
setSnd :: forall a b. b -> Tuple a b -> Tuple a b
setSnd = set _2

> set _2 5 (Tuple "five" 10)
Tuple "five" 5

-- We can use our `_name` lens as an alternative to record update syntax when
-- replacing the value of a field
setName :: forall a r. a -> { name :: a | r } -> { name :: a | r }
setName = set _name

> set _name "John" { name: "Tim", age: 40 }
{ name: "John", age: 40 }

Use over with a lens Lens' s a and a modifying function (a -> a) to modify the value a within s.

-- We can use our `_2` lens to modify the second element of a tuple
modifySnd :: forall a b. (b -> b) -> Tuple a b -> Tuple a b
modifySnd = over _2

> over _2 (_ + 5) (Tuple "five" 10)
Tuple "five" 15

-- We can use our `_name` lens as an alternative to record update syntax when
-- modifying the value of a field
modifyName :: forall a r. (a -> a) -> { name :: a | r } -> { name :: a | r }
modifyName = over _name

> over _name (_ <> " Smitherson") { name: "Tim", age: 40 }
{ name: "Tim Smitherson", age: 40 }

Constructing Lenses

The lens' constructor produces a valid lens from a getter/setter function. This getter/setter function takes the structure s as its argument and produces a tuple containing the focused value a (the "getter") and a function which places a back within the structure (the "setter").

-- Note: this is a more concrete version of the type in `profunctor-lenses`
lens' :: forall s a. (s -> Tuple a (a -> s)) -> Lens' s a

We can use lens' to construct the _2 and _name lenses we've been using.

The first lens focuses on the second element of a tuple. That means our getter/setter function will take a tuple as its argument, the getter part of our function should retrieve the second element of the tuple, and the setter part should overwrite it.

_2 :: forall a b. Lens' (Tuple a b) b
_2 =
  lens' \(Tuple first second) ->
    Tuple
      second -- here we get the second element
      (\b -> Tuple first b) -- and here we set the second element

The second lens focuses on the "name" field of a record. Our getter/setter function will take a record containing this label as its argument. The getter should retrieve the value of the field and the setter should overwrite it, returning the record. We can accomplish both tasks with record syntax.

_name :: forall a r. Lens' { name :: a | r } a
_name = lens' \record -> Tuple record.name (\new -> record { name = new })

We now have two valid lenses, but we should improve the second. It's common to write lenses for custom record types, but lens' has a lot of boilerplate. Fortunately, the profunctor-lenses library has a much nicer helper function for record lenses called prop.

The prop function only requires the name of the field you want to focus on. The field name must be provided as a symbol proxy; if you're unfamiliar with proxies, don't worry -- you'll soon get used to the pattern. Almost all record lenses are written like these examples.

Let's construct a few record lenses, including _name, using prop.

_name :: forall a r. Lens' { name :: a | r } a
_name = prop (SProxy :: SProxy "name")

_age :: forall a r. Lens' { age :: a | r } a
_age = prop (SProxy :: SProxy "age")

_location :: forall a r. Lens' { location :: a | r } a
_location = prop (SProxy :: SProxy "location")

Related Classes: The `At` Lens

The At type class describes a special kind of lens used for keyed structures like maps and sets. This lens is different from the ones we've seen before; an At lens:

requires that the structure s is a keyed structure, like a map or set
must be constructed using the at constructor, which requires a key of the correct type for the structure
lets you get, set, and modify (like usual lenses)
also enables you to insert and delete elements
focuses on a value of type Maybe a, rather than the simple a we've seen so far

Consider this At lens, created using the at constructor:

-- This lens focuses on the specific key "Tim" in a string-keyed collection
_Tim :: forall a. At s String a => Lens' s (Maybe a)
_Tim = at "Tim"

-- We can simplify the type by specializing it
_Tim :: forall a. Lens' (Map String a) (Maybe a)

We can use this At lens with the same common functions like view:

-- We can use our `_Tim` lens as an alternative to the `lookup` function for
-- maps and sets.
getTim :: forall a. Map String a -> Maybe a
getTim = view _Tim

> view _Tim (Map.singleton "Tim" 40)
Just 40

-- We can also replace the `update` function for maps and sets with `over`
updateTim :: forall a. (a -> a) -> Map String a -> Map String a
updateTim f = over _Tim (map f)

> over _Tim (map (_ + 20)) (Map.singleton "Tim" 40)
fromFoldable [ Tuple "Tim" 60 ]

But we can now do more than we could with an ordinary lens: we can also insert and delete values from the structure. If the lens is used with a Just a value, then the value will be updated or inserted. If used with a Nothing value, then the key will be removed from the structure (if it existed).

-- We can use our `_Tim` lens as an alternative to `insert` function
insertTim :: forall a. a -> Map String a -> Map String a
insertTim = set _Tim <<< Just

> set _tim (Just 45) (Map.singleton "John" 20 ])
fromFoldable [ Tuple "John" 20, Tuple "Tim" 45 ]

-- In contrast, providing a `Nothing` value will delete the key (if it exists).
deleteTim :: forall a. Map String a -> Map String a
deleteTim = set _Tim Nothing

> set _Tim Nothing (Map.singleton "Tim" 40)
fromFoldable []

We're still using common lens functions, but the At lens has given us some extra capabilities. While normal Lens' gives us type-independent get, set, and modify operations, the At lens goes even further with insertion and deletion.

Prisms

Prisms are used for sum types like Maybe and Either. The type Prism' s a means that the type s might contain a value of type a. Consider this pair of simple prisms:

-- This prism focuses on the value within the `Left` data constructor. It's
-- defined in `Data.Lens.Either`.
_Left :: forall a b. Prism' (Either a b) a

-- The `RemoteData err a` data type is often used in PureScript to represent
-- requests. It's implemented like this in the `remotedata` library:
data RemoteData err a = NotAsked | Loading | Error err | Success a

-- The library exports prisms for the sum type. This prism focuses on the value
-- within the `Success` data constructor. If you are using the `.purs-repl` file
-- for this article then you already have this prism in scope.
_Success :: forall err a. Prism' (RemoteData err a) a

I'll use these to explore the preview and review functions for working with prisms, and then I'll demonstrate how to construct prisms for your types with the prism' function.

Common Functions For Working With Prisms

Use preview with a prism Prism' s a to retrieve a value of type a from a structure s, if it exists. The value will be returned as Just a if it exists, and Nothing otherwise.

-- Our `_Left` prism focuses on the left branch of an `Either`, which frequently
-- represents errors or failure cases.
getLeft :: forall a b. Either a b -> Maybe a
getLeft = preview _Left

> preview _Left (Left "five")
Just "five"

-- We can use our `_Success` prism to retrieve a successful result from a
-- request, if there is one.
getSuccess :: forall err a. RemoteData err a -> Maybe a
getSuccess = preview _Success

> preview _Success (Success { name: "Tim" })
Just { name: "Tim" }

I also use the helpful is function to test whether the focused value exists in the structure. For example:

-- check if the request succeeded, specializing the result to Boolean so it
-- can be shown in the repl
> is _Success (Success { name: "Tim" }) :: Boolean
true

-- this request has not been sent yet, so it did not succeed
> is _Success NotAsked :: Boolean
false

Next, use review with a prism Prism' s a to produce a structure s given a value a. It's a little like using pure to lift a value into an applicative or monadic context. It generalizes the idea of a data constructor; in the below cases we could also have used the Left and Success data constructors directly.

mkLeft :: forall a b. a -> Either a b
mkLeft = review _Left

-- create a `Left` from a `String`, specializing the right branch to a concrete
-- type so it can be shown in the repl
> (review _Left "Resource not found") :: Either String Void
Left "Resource not found"

mkSuccess :: forall err a. a -> RemoteData err a
mkSuccess = review _Success

> review _Success { name: "Tim" } :: RemoteData Void { name :: String }
Success { name: "Tim" }

Prisms can also use the lens functions we've already discussed: view, set, and over. These functions behave a little differently when used with a prism instead of a lens:

view must return the focused value from the structure, but the value may not exist in a prism. Therefore, view requires that the focused value a has a Monoid instance and returns the empty value if it does not exist.
over and set will manipulate the focused value if it exists, but will leave the structure unchanged if it does not exist.

Let's see each of these in practice:

-- view will return the focus value when it exists
> view _Success (Success { name: "Tim" })
{ name: "Tim" }

-- or `mempty` if it does not
> view _Success NotAsked :: { name :: String }
{ name: "" }

-- set and over will manipulate the focus value if it exists
> over _Left (_ <> " Smitherson") (Left "Tim") :: Either String Void
Left "Tim Smitherson"

-- and will leave the structure unchanged if it does not; contrast this to
-- the behavior of the `At` lens
> set _Left "John" (Right 10)
Right 10

Constructing Prisms

You can write prisms for your types using the prism' constructor. This function produces a Prism' s a given a constructor function a -> s and a retrieval function s -> Maybe a. Remember that the focused value, a, is not guaranteed to exist in a prism!

The constructor function is usually a data constructor like Left or Success.
The retrieval function is usually a case statement which uses pattern-matching to retrieve the focused value a

Almost every prism definition in the wild looks the same. Let's construct the two prisms we've been using so far:

_Left :: forall a b. Prism' (Either a b) a
_Left = prism' Left case _ of
  Left a -> Just a
  _ -> Nothing

_Success :: forall err a. Prism' (RemoteData err a) a
_Success = prism' Success case _ of
  Success a -> Just a
  _ -> Nothing

Tips For Composing Optics

Composition is what makes optics so flexible. Each optic focuses on a value within a single layer of structure. You can compose them one layer at a time to drill down through many layers of structure, and if the structure changes, you can simply remove, replace, or re-order the composed optics to accommodate the change. As a general rule, I recommend that you:

Define optics to focus on one layer of structure at a time, and compose them to work with multiple layers of structure
Define pre-composed optics to get and set data I use often; for example, I might define _uuid to retrieve a user's unique ID from a larger User type rather than write the composition over and over.
Don't define concrete getter or setter functions; a function like getUUID :: User -> UUID prevents composition with other optics. Instead, define optics, and then use common functions like view, preview, and over with the optic directly.

When reading composed optics, make sure to think of the optic as describing the location of the value, or how to access it, but not a as chain of operations like getting and setting. For example, consider this composition:

_Just <<< _name <<< _2

If you read this as "get the second element of the tuple, then get the name field of the record, then get the value within the Just constructor," then you are reading it backward.

Instead, think of the composition as describing the location of the value: "The focus is the second element of a tuple, which is within the name field of a record, which is within the Just constructor of a Maybe."

Three common compositions describe most optics:

Compose two optics of the same type, and you'll get the same type.
Compose a lens and a prism, and you'll get an affine traversal.
Compose almost anything with a traversal, and you'll get a traversal.

Finally, let's turn to traversals.

Traversals

The type Traversal' s a means that the type s contains zero, one, or many values of a. A traversal can refer to one of two things:

A traversal is used for collections like lists and maps, where the optic has zero, one, or many foci.
An affine traversal is a more general form of a lens, prism, or composed optic, which has only zero or one focus.

You have a traversal either way, but an affine traversal is more similar in its use to a prism. Affine traversals are more general than lenses or prisms, however, and can't be used with as many functions.

Traversals that operate on collections are especially useful for:

Applying a function to every focus in the collection (like map)
Collapsing every focus in the collection to a single value (like fold)

Affine traversals are useful when you compose lenses and prisms; you'll most often use prism functions like preview and over with them.

-- This pre-defined optic is valid for any `Traversable`, which includes
-- arrays, lists, and maps. It's defined in Data.Lens.Traversal.
traversed :: forall t a. Traversable t => Traversal' (t a) a

-- This affine traversal is the composition of lenses and prisms we've already
-- seen. Composing a lens and a prism will produce an affine traversal.
_city :: forall a b r. Traversal' (Maybe { city :: Maybe a | r }) a
_city = _Just <<< prop (SProxy :: _ "city") <<< _Just

Common Functions For Working With Traversals

Traversals can be used with many of the same lens and prism functions we've already seen, but can also be used with library functions meant for working with collections of values. Most of the traversal-specific functions you'll use are defined in the Data.Lens.Fold module.

Let's start with the familiar functions we've already worked with.

Be careful with view, which is defined to only return a single value a from a structure: traversals support zero, one, or many values of type a. Like a prism, if the focus doesn't exist then the monoidal empty value is returned. Like a lens, if a single focus exists, it is returned. What about collections like arrays, which contain many foci? In that case, the values are concatenated together to produce a single value.

By convention I:

use view with affine traversals, which have at most one focus.
use foldOf with traversals which may have many foci, like an array; it behaves the same as view, but has a more intuitive name for collections.

I'll follow this convention in the below examples.

-- when no element exists, the empty value is returned
> foldOf traversed [] :: String
""

> view _city (Just { city: Nothing }) :: String
""

-- when one element exists it is returned
> foldOf traversed [ "Gjelina" ]
"Gjelina"

> view _city (Just { city: Just "Los Angeles" })
"Los Angeles"

-- when many elements exist, they are concatenated
> foldOf traversed [ "Tim", " Smitherson" ]
"Tim Smitherson"

We can continue to use set, and over as we did with lenses and prisms; this time, however, the modification will apply to everything focused by the traversal, not just a single value of type a.

-- when no focus exists, the structure is unchanged
> set traversed 10 []
[]

> over _city (_ <> ", CA") Nothing
Nothing

-- when one focus exists, `set` and `over` behave exactly as they did with
-- lenses and prisms
> set traversed 10 [ 4 ]
[ 10 ]

> over _city (_ <> ", CA") (Just { city: Just "Los Angeles" })
Just { city: Just "Los Angeles, CA" }

-- when multiple foci exist, `set` and `over` will apply to every one
> set traversed 10 (Array.range 0 4)
[ 10, 10, 10, 10, 10 ]

> over traversed (\x -> x * x) (Array.range 0 4)
[ 0, 1, 4, 9, 16 ]

We can use preview, like with prisms, but we can't use review with a traversal. Be careful with preview: like view, it's designed to return at most one focus. When many foci exist, as they may in a traversal, it will return only the first one. I prefer to:

use preview for affine traversals, which have at most one focus
use firstOf for traversals which have many foci; it behaves the same as preview, but has a more intuitive name for collections

I'll use that convention with our two traversals.

-- when no focus exists, `preview` and `toFirstOf` return `Nothing`
> firstOf traversed [] :: Maybe Void
Nothing

> preview _city Nothing :: Maybe Void
Nothing

-- when one focus exists, it is returned in `Just`
> firstOf traversed [ 1 ]
Just 1

> preview _city (Just { city: Just "Los Angeles" })
Just "Los Angeles"

-- when many foci exist, only the first is returned
> firstOf traversed [ 1, 2, 3, 4, 5 ]
Just 1

Among the many library functions defined in Data.Lens.Fold, the most often used are lastOf, which returns the last of many foci, and toListOf, which places the foci in an list. For example:

> lastOf traversed [ 1, 2 ]
Just 2

> toListOf _city (Just { city: Just "Los Angeles" })
"Los Angeles" : Nil

Constructing Traversals

You usually don't need to construct a traversal directly, because:

the traversed optic works for any member of the Traversable type class
lenses and prisms are already traversals
many other optics become traversals when composed together.

The wander function helps you construct a traversal for a data type which does not conform to Traversable, but still has parts you want to focus. It's rarely used outside the profunctor-lenses library, but it's good to know it exists.

Related Classes: The `Index` Traversal

The Index type class describes a special kind of traversal which is used to focus on a single element within an indexed collection. This traversal is different from the ones we've seen before; an Index traversal:

requires that the structure s is indexed, like an array, list, or map
must be constructed using the ix constructor, which requires an index of the correct type for the structure
lets you get, set, and modify just one focus among many in the collection -- but does not let you insert or remove elements, as At does, which makes it well-suited for fixed-size collections

You can use all the regular traversal functions with an Index traversal, but remember that there is only one focus. Here's a sample:

-- This index traversal focuses on the third index of a Traversable
_3 :: Index t Int a => Traversal' t a
_3 = ix 3

-- We can simplify the type by specializing to an array of strings
_3 :: Traversal' (Array String) String

The most common operations I take with an index traversal include:

get values with preview
set and modify values with set and over

-- We can use `preview` to look up the value by its index
getIndex3 :: Array String -> Maybe String
getIndex3 = preview _3

> preview _3 [ "Preux & Proper", "Gjelina", "Sonoratown", "Republique", "Bavel" ]
Just "Republique"

-- Use `set` and `over` to modify the value (if it exists)
setIndex3 :: String -> Array String -> Array String
setIndex3 = set _3

> set _3 "Bavel" []
[]

> over _3 (_ <> "!") [ "Gjelina", "Republique", "Bavel", "Sonoratown" ]
[ "Gjelina", "Republique", "Bavel", "Sonoratown!" ]

Isos

Isos are the most constrained optic, simply enabling you to transform back and forth between two types without losing information. The type Iso' s a means that s and a are isomorphic -- the two types represent the same information. They're especially useful when you need to unwrap a newtype or transform an array to a list or otherwise convert between types. This optic is also useful for backward compatibility without boilerplate.

-- The most common iso used in practice is _Newtype, which allows you to
-- unwrap or wrap a newtype, usually composed with other optics. As usual,
-- this is simplified from the type in `profunctor-lenses`. The optic is
-- defined in Data.Lens.Iso.Newtype.
_Newtype :: forall s a. Newtype s a => Iso' s a

Common Functions

Isos share similarities with lenses and prisms. If you have an iso Iso' s a then you can use view to produce an a given an s, like a lens, and you can use review to produce an s given an a, like a prism.

-- `view` can act as a replacement for the `unwrap` function from the `Newtype`
-- type class
unwrap :: forall s a. Newtype s a => s -> a
unwrap = view _Newtype

-- We'll need a type annotation here
> view (_Newtype :: Iso' (Additive Int) Int) (Additive 10)
10

-- `review` can act as a replacement for the `wrap` function
wrap :: forall s a. Newtype s a => s -> a
wrap = review _Newtype

> review (_Newtype :: Iso' (Additive Int) Int) 10
Additive 10

Constructing Isos

Isos are constructed with the iso function. For a given Iso' s a it expects two conversion functions as arguments: one which converts an s to an a, and one which converts an a to an s. If you have written any conversion functions already, like fromFoldable or unwrap, then this is trivial; if not, start by writing conversion functions before constructing the iso.

-- we can re-use the `unwrap` and `wrap` functions from `Data.Newtype` to create
-- this iso
_Newtype :: forall s a. Newtype s a => Iso' s a
_Newtype = iso unwrap wrap

Wrapping up

Optics are a powerful tool. With just a few functions for constructing and using optics, you can write more elegant code to manage complex structures. As you continue using optics, consider referring back profunctor lenses cheatsheet.

If you're curious to learn more about optics, I recommend these resources:

Lenses for the Mere Mortal, a book by Brian Marick.
Lens over Tea, a series of tutorials on the Haskell lens library by Artyom Kazak (note: this uses a different formulation of lenses, but most of the ideas are the same)

If you've been helped by other resources, please suggest them for this list on this post's discussion on the PureScript Discourse.

How to Replace React Components With PureScript

Thomas Honeyman — Mon, 22 Jul 2019 18:10:59 +0000

I have twice experienced replacing large JavaScript apps with PureScript: first at CitizenNet, where we replaced Angular with Halogen, and then at Awake Security, where we've replaced most of a React app with PureScript React. Both companies saw a precipitous drop in bugs in their software.

The best way to rewrite any significant app from one language to another is incrementally, bit by bit, while it continues to run. At first the new language can simply take over logically separate parts of the app: the management dashboard, or the chat window, or a big form. But you will eventually want to intermix the languages: an autocomplete written in PureScript but used in a JavaScript form, or a PureScript component being passed a mix of components from both languages as children, or a shared global state.

Original: Replace React Components With PureScript's React Libraries

At this point the new language must be flexible enough to mix code from both languages together, not just take over a section of the app for itself. Fortunately, you can transform the interface of idiomatic PureScript into idiomatic JavaScript (and vice versa). Components written with any leading PureScript UI library can be interleaved with components written in JavaScript frameworks like Angular and React.

It's relatively easy to replace React apps with PureScript due to its react and react-basic libraries. Using the same underlying framework means the same idioms apply and components can be shared with little to no modification. We can share more than isolated components, too; at Awake Security we share internationalization, a Redux store and middleware, and other global context in an intermixed codebase where PureScript regularly imports JavaScript and JavaScript regularly imports PureScript.

In this article I will demonstrate how to replace part of a React application with simple components written in PureScript. Along the way, I'll share best practices for making this interop convenient and dependable. The examples will be simple, but the same techniques also apply to complex components.

Sections

Together, we will:

Write a tiny React application in JavaScript
Update the application to support PureScript
Replace a React component with PureScript React, with the same interface and behavior as the original
Replace the component again with React Basic

I encourage you to code along with this article; no code is omitted and dependencies are pinned to help ensure the examples are reproducible. This code uses Node v11.1.0, Yarn v1.12.0, and NPX v6.5.0 installed globally, and PureScript tooling installed locally. You can also view the original purescript react article.

Let's write a React app in JavaScript

We are going to write a tiny React application which shows a few counters, and then we're going to replace its components with PureScript. The resulting JavaScript code will be indistinguishable, aside from imports, from the original, and yet it will all be PureScript under the hood.

Let's follow the official React docs in using create-react-app to initialize the project and then trim our source code to the bare minimum.

# Create the app
npx create-react-app my-app && cd my-app

At the time of writing, create-react-app produces these React dependencies:

"dependencies": {
    "react": "^16.8.6",
    "react-dom": "^16.8.6",
    "react-scripts": "3.0.1"
  }

We have a handful of source files under src, but our application will need just two of them: index.js, the entrypoint for Webpack, and App.js, the root component of our application. We can delete the rest:

# Delete all the source files except for the entrypoint and
# root app component
find src -type f -not \( -name 'index.js' -or -name 'App.js' \) -delete

Finally, let's replace the contents of those two files with the bare minimum we'll need for this article. From here on out I'll supply diffs that you can supply to git apply to apply the same changes I did.

First, our entrypoint:

// src/index.js
import React from "react";
import ReactDOM from "react-dom";
import App from "./App";

ReactDOM.render(<App />, document.getElementById("root"));

Then our main app component:

// src/App.js
import React from "react";

function App() {
  return (
    <div>
      <h1>My App</h1>
    </div>
  );
}

export default App;

Writing a React component

Let's write our first React component: a counter. This is likely the first example of a React component you ever encountered; it's the first example in the PureScript React libraries as well. It's also small and simple enough to be replaced twice over the course of this article.

touch src/Counter.js

The counter will be a button which maintains the number of times it has been clicked. It will accept, as its only prop, a label to display on the button.

// src/Counter.js
import React from "react";

class Counter extends React.Component {
  constructor(props) {
    super(props);
    this.state = {
      count: 0
    };
  }

  render() {
    return (
      <button onClick={() => this.setState({ count: this.state.count + 1 })}>
        {this.props.label}: {this.state.count}
      </button>
    );
  }
}

export default Counter;

Then, we'll import our new counters into our main application:

--- a/src/App.js
+++ b/src/App.js
@@ -1,9 +1,13 @@
 import React from "react";
+import Counter from "./Counter";

 function App() {
   return (
     <div>
       <h1>My App</h1>
+      <Counter label="Count" />
+      <Counter label="Clicks" />
+      <Counter label="Interactions" />
     </div>
   );
 }

With yarn start we can run the dev server and see our app in action.

Setting up a shared PureScript & JavaScript project

We've written entirely too much JavaScript. Let's support PureScript in this project as well. Our goal is to write code in either language and freely import in either direction without friction. To accomplish that, we will install PureScript tooling, create a separate PureScript source directory, and rely on the compiler to generate JavaScript code.

1. Install the compiler and package manager

First we must install PureScript tooling. I recommend using Yarn to install local versions of the compiler and Spago (a package manager and build tool) which match those used in this article. I'll use NPX to ensure all commands are run using local copies of this software.

# Install the compiler and the Spago package manager
yarn add -D purescript@0.13.0 spago@0.8.4

2. Initialize the project and package set

We can create a new PureScript project with spago init. As of version 0.8.4, Spago always initializes with the same package set, which means you should have identical package versions to those used to write this article. I'm using the psc-0.13.0-20190607 package set.

# npx ensures we're using our local copy of Spago installed in node_modules.
npx spago init

Spago has created a packages.dhall file which points at the set of packages which can be installed and a spago.dhall file which lists the packages we've actually installed. We can now install any dependencies we need and we'll know for sure the versions are all compatible.

Before installing anything, let's update the existing .gitignore file to cover PureScript. For a Spago-based project this will work:

--- a/.gitignore
+++ b/.gitignore
@@ -21,3 +21,9 @@
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
+
+# purescript
+output
+.psc*
+.purs*
+.spago

3. Adjust the directory structure

Finally, let's organize our source code. It's typical to separate JavaScript source from PureScript source except when writing an FFI file for PureScript. Since we aren't doing that in this project, our source files will be entirely separated. Let's move all JavaScript code into a javascript subdirectory and create a new purescript folder next to it.

mkdir src/javascript src/purescript
mv src/App.js src/Counter.js src/javascript

Next, we'll adjust index.js to the new location of our root component:

--- a/src/index.js
+++ b/src/index.js
@@ -1,5 +1,5 @@
 import React from "react";
 import ReactDOM from "react-dom";
-import App from "./App";
+import App from "./javascript/App";

 ReactDOM.render(<App />, document.getElementById("root"));

We've just one task left. The PureScript compiler generates JavaScript into a directory named output in the root of the project. But create-react-app disables importing anything outside the src directory. While there are fancier solutions, for this project we'll get around the restriction by symlinking the output directory into the src directory.

# we can now import compiled PureScript from src/output/...
ln -s $PWD/output $PWD/src

Your src directory should now look like this:

src
├── index.js
├── javascript
│ ├── App.js
│ └── Counter.js
├── output -> ../output
└── purescript

Replacing a React component with PureScript React

I like to follow four simple steps when replacing a JavaScript React component with a PureScript one:

Write the component in idiomatic PureScript.
Write a separate interop module for the component. This module provides the JavaScript interface and conversion functions between PureScript and JavaScript types and idioms.
Use the PureScript compiler to generate JavaScript
Import the resulting code as if it were a regular JavaScript React component.

We'll start with the react library, which we use at Awake Security. It's similar to react-basic but maps more directly to the underlying React code and is less opinionated. Later, we'll switch to react-basic, which will demonstrate some differences between them.

As we take each step in this process I'll explain more about why it's necessary and some best practices to keep in mind. Let's start: install the react library and prepare to write our component:

# install the purescript-react library
npx spago install react

# build the project so editors can pick up the `output` directory
npx spago build

# create the component source file
touch src/purescript/Counter.purs

1. Write the React component in idiomatic PureScript

Even though we are writing a component to be used from JavaScript, we should still write ordinary PureScript. As we'll soon see, it's possible to adjust only the interface of the component for JavaScript but leave the internals untouched. This is especially important if this component is meant to be used by both PureScript and JavaScript; we don't want to introduce any interop-related awkwardness to either code base.

Below, I've written a version of the component with the same props, state, and rendering. Copy its contents into src/purescript/Counter.purs.

Note: It's not necessary to annotate this when creating a component, but doing so improves the quality of errors if you do something wrong.

module Counter where

import Prelude

import React (ReactClass, ReactElement, ReactThis, component, createLeafElement, getProps, getState, setState)
import React.DOM as D
import React.DOM.Props as P

type Props = { label :: String }

type State = { count :: Int }

counter :: Props -> ReactElement
counter = createLeafElement counterClass

counterClass :: ReactClass Props
counterClass = component "Counter" \(this :: ReactThis Props State) -> do
  let
    render = do
      state <- getState this
      props <- getProps this
      pure $ D.button
        [ P.onClick \_ -> setState this { count: state.count + 1 } ]
        [ D.text $ props.label <> ": " <> show state.count ]

  pure
    { state: { count: 0 }
    , render
    }

In a PureScript codebase this is all we need; we could use this component by importing counter and providing it with its props:

-- compare to our JavaScript main app
import Counter (counter)

renderApp :: ReactElement
renderApp =
  div'
    [ h1' [ text "My App" ]
    , counter { label: "Count" }
    , counter { label: "Count" }
    , counter { label: "Count" }
    ]

We can already use this component from JavaScript, too. The react library will generate a usable React component from this code which we can import like any other JavaScript React component. Let's go ahead and try it out, and then we'll make a few improvements.

First, we'll compile the project:

npx spago build

Then we'll import the component. Note how our implementation is close enough that we only have to change the import, nothing else! PureScript will generate files in output, so our counter component now resides at output/Counter.

--- a/src/javascript/App.js
+++ b/src/javascript/App.js
@@ -1,5 +1,5 @@
 import React from "react";
-import Counter from "./Counter";
+import { counter as Counter } from "../output/Counter";

 function App() {
   return (

Run yarn start and you ought to see the exact same set of counters as before. With our component now implemented in PureScript we don't need our JavaScript version anymore:

rm src/javascript/Counter.js

We've successfully taken over part of our JavaScript app with PureScript.

2. Write an interop module for the component

We were lucky our component worked right away. In fact, it only worked because we're using simple JavaScript types so far and the users of our counter component are trustworthy and haven't omitted the label prop, which we consider required. We can enforce correct types and no missing values in PureScript, but not in JavaScript.

What happens if a user forgets to provide a label to the component?

Well, setting undefined as a label is not good, but it's not as bad as the entire app crashing -- which is what happens if you attempt to use PureScript functions on the value you have pretended is a String. The problem is that the String type doesn't quite capture what values are likely to arrive from JavaScript. As a general rule, I expect people to write JavaScript they way they usually do, which means using builtin types, regular uncurried functions, and to sometimes omit information and supply null or undefined instead. That's why at Awake Security we usually provide an interop module for components that will be used in JavaScript code, which:

Provides a mapping between PureScript types used in the component and a simple JavaScript representation
Adds a layer of safety by marking all inputs that could reasonably be null or undefined with the Nullable type, which helps our code handle missing values gracefully
Translates functions in their curried form into usual JavaScript functions, and translates effectful functions (represented as thunks in generated code) into functions that run immediately when called
Serves as a canary for changes in PureScript code that will affect dependent JavaScript code so that you can be extra careful

Over the remainder of the article we'll explore each of these techniques. For now, all we need to do is mark the input string as Nullable and explicitly handle what should happen when it is omitted.

Let's create an interop module for our component named Counter.Interop:

mkdir src/purescript/Counter
touch src/purescript/Counter/Interop.purs

Typically, each interop module will contain at least three things:

A new JavaScript-compatible interface (JSProps)
A function converting from the new types to PureScript types (jsPropsToProps)
A new component which uses the new JavaScript-compatible types via the conversion function (jsComponentName)

In action:

module Counter.Interop where

import Prelude

import Counter (Props, counter)
import Data.Maybe (fromMaybe)
import Data.Nullable (Nullable, toMaybe)
import React (ReactElement)

type JSProps = { label :: Nullable String }

jsPropsToProps :: JSProps -> Props
jsPropsToProps { label } = { label: fromMaybe "Count" $ toMaybe label }

jsCounter :: JSProps -> ReactElement
jsCounter = counter <<< jsPropsToProps

We have created a new interface for our component, JSProps, which will be used in JavaScript instead of our PureScript interface, Props. We've also created a function which translates between the two interfaces, and produced a new component which uses the JavaScript interface instead of the PureScript one.

Marking the label prop as Nullable makes the compiler aware the string may not exist. It then forces us to explicitly handle the null or undefined case before we can treat the prop as a usual String. We'll need to handle the null case in order to map our new JSProps type to our component's expected Props type. To do that, we convert Nullable to Maybe and then provide a fallback value to use when the prop does not exist.

The Nullable type is explicitly for interop with JavaScript, but it doesn't always behave exactly the way you would expect. It does not map directly to the ordinary Maybe type. You should usually convert any Nullable types to Maybe as soon as possible. Check out the nullable library if you'd like to learn more about this.

Let's change the import in App.js and verify that the omitted label is handled gracefully.

--- a/src/javascript/App.js
+++ b/src/javascript/App.js
@@ -1,5 +1,5 @@
 import React from "react";
-import { counter as Counter } from "../output/Counter";
+import { jsCounter as Counter } from "../output/Counter.Interop";

 function App() {
   return (

Now, omitted props still render a reasonable label:

In this case our interop module simply marked a single field as Nullable. But it's common for the JavaScript interface to diverge slightly from the PureScript interface it is translating. Keeping a separate interop module makes it easy to do this without affecting the core component.

It also ensures that any changes to the underlying component are reflected as type errors in the interop file rather than (potentially) silently breaking JavaScript code. It's easy to become lazy about this when you're used to the compiler warning you of the effect changes in one file will have in another!

If you use TypeScript, Justin Woo has written a piece on transparently sharing types with Typescript from PureScript which is worth reading.

Replacing a React component with PureScript React Basic

Let's try replacing the counter again, but this time with the newer, more opinionated react-basic library. Along the way we'll use a few more complex types and build a more sophisticated interop module.

Install react-basic:

npx spago install react-basic

Next, replace the contents of Counter with an identical implementation written with react-basic:

module Counter where

import Prelude

import React.Basic (JSX, createComponent, make)
import React.Basic.DOM as R
import React.Basic.DOM.Events (capture_)

type Props = { label :: String }

counter :: Props -> JSX
counter = make (createComponent "Counter") { initialState, render }
  where
  initialState = { count: 0 }

  render self =
    R.button
      { onClick:
          capture_ $ self.setState \s -> s { count = s.count + 1 }
      , children:
          [ R.text $ self.props.label <> " " <> show self.state.count ]
      }

The two React libraries don't share types, so we'll change our interop module to describe producing JSX rather than a ReactElement.

--- a/src/purescript/Counter/Interop.purs
+++ b/src/purescript/Counter/Interop.purs
@@ -5,13 +5,13 @@ import Prelude
 import Counter (Props, counter)
 import Data.Maybe (fromMaybe)
 import Data.Nullable (Nullable, toMaybe)
-import React (ReactElement)
+import React.Basic (JSX)

 type JSProps = { label :: Nullable String }

 jsPropsToProps :: JSProps -> Props
 jsPropsToProps { label } = { label: fromMaybe "Count" $ toMaybe label }

-jsCounter :: JSProps -> ReactElement
+jsCounter :: JSProps -> JSX
 jsCounter = counter <<< jsPropsToProps

Making it usable from JavaScript

This component works perfectly well in a PureScript codebase. Unlike our react component, though, our react-basic component will not automatically work in JavaScript code also. Instead, we need to use make to construct a component meant for PureScript and toReactComponent to construct one for JavaScript.

Still, both functions use the same component spec type, so the new restriction is easy to work around. We'll simply move initialState and render out to the module scope. That way we can import them directly into our interop module to supply to toReactComponent.

--- a/src/purescript/Counter.purs
+++ b/src/purescript/Counter.purs
@@ -2,21 +2,28 @@ module Counter where

 import Prelude

-import React.Basic (JSX, createComponent, make)
+import React.Basic (Component, JSX, Self, createComponent, make)
 import React.Basic.DOM as R
 import React.Basic.DOM.Events (capture_)

 type Props = { label :: String }

+type State = { count :: Int }
+
+component :: Component Props
+component = createComponent "Counter"
+
 counter :: Props -> JSX
-counter = make (createComponent "Counter") { initialState, render }
-  where
-  initialState = { count: 0 }
-
-  render self =
-    R.button
-      { onClick:
-          capture_ $ self.setState \s -> s { count = s.count + 1 }
-      , children:
-          [ R.text $ self.props.label <> " " <> show self.state.count ]
-      }
+counter = make component { initialState, render }
+
+initialState :: State
+initialState = { count: 0 }
+
+render :: Self Props State -> JSX
+render self =
+  R.button
+    { onClick:
+        capture_ $ self.setState \s -> s { count = s.count + 1 }
+    , children:
+        [ R.text $ self.props.label <> " " <> show self.state.count ]
+    }

We'll leave the code otherwise unchanged. Next, let's turn to the interop module. It should now use toReactComponent to create a component usable from JavaScript. This function takes the component and component spec, exactly the same way that make does, but it also takes an additional argument: our jsPropsToProps function.

The react-basic library makes interop more explicit than react does, but ultimately we'll write nearly the same interop code.

--- a/src/purescript/Counter/Interop.purs
+++ b/src/purescript/Counter/Interop.purs
@@ -2,16 +2,15 @@ module Counter.Interop where

 import Prelude

-import Counter (Props, counter)
+import Counter (Props, component, initialState, render)
 import Data.Maybe (fromMaybe)
 import Data.Nullable (Nullable, toMaybe)
-import React (ReactElement)
-import React.Basic (JSX)
+import React.Basic (ReactComponent, toReactComponent)

 type JSProps = { label :: Nullable String }

 jsPropsToProps :: JSProps -> Props
 jsPropsToProps props = { label: fromMaybe "Count:" $ toMaybe props.label }

-jsCounter :: JSProps -> JSX
-jsCounter = counter <<< jsPropsToProps
+jsCounter :: ReactComponent JSProps
+jsCounter = toReactComponent jsPropsToProps component { initialState, render }

This component is now once again usable from JavaScript.

Introducing more complex types

What happens when you have a more complicated type you need to construct from JavaScript? Let's say, for example, that our counter component needs two new pieces of information:

An effectful callback function to run after the counter is clicked
A type which represents whether the function should increment or decrement on click

We can apply the same process to accommodate the new features. We will write idiomatic PureScript in our component module and then write a translation in the interop module. The end result will be a component equally usable in PureScript code or in JavaScript code, without compromising how you write code in either language.

--- a/src/purescript/Counter.purs
+++ b/src/purescript/Counter.purs
@@ -2,14 +2,35 @@ module Counter where

 import Prelude

-import React.Basic (Component, JSX, Self, createComponent, make)
+import Data.Maybe (Maybe(..))
+import Effect (Effect)
+import React.Basic (Component, JSX, Self, createComponent, make, readProps, readState)
 import React.Basic.DOM as R
 import React.Basic.DOM.Events (capture_)

-type Props = { label :: String }
+type Props =
+  { label :: String
+  , onClick :: Int -> Effect Unit
+  , counterType :: CounterType
+  }

 type State = { count :: Int }

+data CounterType
+  = Increment
+  | Decrement
+
+counterTypeToString :: CounterType -> String
+counterTypeToString = case _ of
+  Increment -> "increment"
+  Decrement -> "decrement"
+
+counterTypeFromString :: String -> Maybe CounterType
+counterTypeFromString = case _ of
+  "increment" -> Just Increment
+  "decrement" -> Just Decrement
+  _ -> Nothing
+
 component :: Component Props
 component = createComponent "Counter"

@@ -23,7 +44,15 @@ render :: Self Props State -> JSX
 render self =
   R.button
     { onClick:
-        capture_ $ self.setState \s -> s { count = s.count + 1 }
+        capture_ do
+          state <- readState self
+          props <- readProps self
+          let
+            newCount = case props.counterType of
+              Increment -> add state.count 1
+              Decrement -> sub state.count 1
+          self.setState _ { count = newCount }
+          props.onClick newCount
     , children:
         [ R.text $ self.props.label <> " " <> show self.state.count ]
     }

With these changes our counter can decrement or increment and can run an arbitrary effectful function after the click event occurs. But we can't run this from JavaScript: there is no such thing as a CounterType in JavaScript, and a normal JavaScript function like...

function onClick(ev) {
  console.log("clicked!");
}

will not work if supplied as the callback function. It's up to our interop module to smooth things out.

I'll make the code changes first and describe them afterwards:

--- a/src/purescript/Counter/Interop.purs
+++ b/src/purescript/Counter/Interop.purs
@@ -2,16 +2,27 @@ module Counter.Interop where

 import Prelude

-import Counter (Props, counter)
+import Counter (CounterType(..), Props, component, initialState, render, counterTypeFromString)
 import Data.Maybe (fromMaybe)
 import Data.Nullable (Nullable, toMaybe)
+import Effect.Uncurried (EffectFn1, runEffectFn1)
 import React.Basic (JSX)

-type JSProps = { label :: Nullable String }
+type JSProps =
+  { label :: Nullable String
+  , onClick :: Nullable (EffectFn1 Int Unit)
+  , counterType :: Nullable String
+  }

 jsPropsToProps :: JSProps -> Props
-jsPropsToProps props = { label: fromMaybe "Count:" $ toMaybe props.label }
+jsPropsToProps props =
+  { label:
+      fromMaybe "Count:" $ toMaybe props.label
+  , onClick:
+      fromMaybe mempty $ map runEffectFn1 $ toMaybe props.onClick
+  , counterType:
+      fromMaybe Increment $ counterTypeFromString =<< toMaybe props.counterType
+  }

First, I updated the JavaScript interface to include the two new fields our component accepts.

I decided to represent CounterType as a lowercase string "increment" or "decrement" and guard against both the case in which the value isn't provided (Nullable) or the provided value doesn't make sense (it can't be parsed by counterTypeFromString). In either case the component will default to incrementing.

I also decided to represent onClick as a potentially missing value. But instead of a usual function, I'm representing the value as an EffectFn1: an effectful, uncurried function of one argument.

That type merits a little extra explanation. In PureScript, functions are curried by default and effectful functions are represented as a thunk. Therefore, these two PureScript functions:

add :: Int -> Int -> Int
log :: String -> Effect Unit

...do not correspond to functions that can be called in JavaScript as add(a, b) or log(str). Instead, they translate more closely to:

// each function has only one argument, and multiple arguments are represented
// by nested functions of one argument each.
const add = a => b => a + b;

// effectful functions are thunked so they can be passed around and manipulated
// without being evaluated.
const log = str => () => console.log(str);

This is an unusual programming style for JavaScript. So PureScript provides helpers for exporting functions that feel more natural.

The Fn* family of functions handles pure functions of N arguments
The EffectFn* family of functions handles effectful functions of N arguments
A few other translating functions exist; for example, you can turn Aff asynchronous functions into JavaScript promises and vice versa.

If we rewrite our PureScript definitions to use these helpers:

add :: Fn2 Int Int Int
log :: EffectFn1 String Unit

then we will get a more usual JavaScript interface:

const add = (a, b) => a + b;
const log = str => console.log(str);

Without using EffectFn1, JavaScript code using our counter component would have to supply a thunked callback function like this:

<Counter onClick={count => () => console.log("clicked: ", n)} />

With EffectFn1 in place, however, we can provide usual code:

<Counter onClick={count => console.log("clicked: ", n)} />

Let's take advantage of our new component features by updating App.js. Our first component will omit all props except for the onClick callback, which will log the count to the console. The next one will specify a decrementing counter. The last component will stick to the original interface and just provide a label.

--- a/src/javascript/App.js
+++ b/src/javascript/App.js
@@ -5,8 +5,8 @@ function App() {
   return (
     <div>
       <h1>My App</h1>
-      <Counter />
-      <Counter label="Clicks:" />
+      <Counter onClick={n => console.log("clicked: ", n)} />
+      <Counter counterType="decrement" label="Clicks:" />
       <Counter label="Interactions:" />
     </div>
   );

Wrapping Up

We replaced a simple counter in this article, but the same steps apply to more complex components as well.

Write the PureScript component using whatever types and libraries you would like.
Then, write an interop module for the component which translates between JavaScript and PureScript.
Compile the result.
Import it into your JavaScript code like any other React component.

Interop between React and PureScript becomes more involved when you introduce global contexts like a Redux store, but it's bootstrapping work that remains largely out of view in day-to-day coding.

Interop between other frameworks like Angular or other PureScript UI libraries like Halogen is less transparent. That's not because of a limitation in these libraries, but simply because you're now mixing frameworks together. At CitizenNet we exported our Halogen components for Angular and React teams in the company to use.

The next time you're faced with a tangled JavaScript React app and wish you had better tools, try introducing PureScript.

DEV Community: Thomas Honeyman

Introducing Halogen Hooks

Hooks In Action: UseWindowWidth

Implementing UseWindowWidth

What About Components?

Next Steps

Practical Profunctor Lenses & Optics In PureScript

Sections

Profunctor Lenses & Optics In Action

Cheatsheet: Types, Functions, and Constructors

Setup

Lenses

Common Functions For Working With Lenses

Constructing Lenses

Related Classes: The At Lens

Prisms

Common Functions For Working With Prisms

Constructing Prisms

Tips For Composing Optics

Traversals

Common Functions For Working With Traversals

Constructing Traversals

Related Classes: The Index Traversal

Isos

Common Functions

Constructing Isos

Wrapping up

How to Replace React Components With PureScript

Sections

Let's write a React app in JavaScript

Writing a React component

Setting up a shared PureScript & JavaScript project

1. Install the compiler and package manager

2. Initialize the project and package set

3. Adjust the directory structure

Replacing a React component with PureScript React

1. Write the React component in idiomatic PureScript

2. Write an interop module for the component

Replacing a React component with PureScript React Basic

Making it usable from JavaScript

Introducing more complex types

Wrapping Up

Related Classes: The `At` Lens

Related Classes: The `Index` Traversal