Ports in Elm

Feb 26, 2016

Disclaimer: This post was written about Elm 0.16. Signals, the mechanism described in this post, have since been deprecated. The concepts in this post may still help understand how the Elm Architecture works internally, but the actual code has changed significantly

This is the third post in a series of posts about Elm. In my first post about Signals in Elm I briefly mentioned ports. Since they are the only way to communicate with “native” Javascript, they certainly warrant a closer look. If you haven’t checked out the last post in this series on tasks and effects I suggest you do that now as this post will build on these concepts.

So what are Ports, exactly?

They are basically a way to send messages from Elm to native JS or from JS to Elm. They are defined in Elm with their own keyword, port.

If a Port is defined to be of a Non-Signal type (e.g. port initialUrl : String) then it is a “one time” message (at init time of the Elm code), i.e. such ports can be used if you want to send initialization values from JS to Elm at init time (and never afterwards).

More frequently it will be a Signal of some type (e.g. a Signal String).

Ports can not send and receive values of any type but only a subset - the big two groups of values that can’t be used are "functions" and "union types" ("Maybe" is the only exception to this rule). All the details can be found on the elm guide page on interop .

As a simple example, let’s create a pair of ports to send Strings from Elm to Js, do something with it in native JS, and then send the Strings back.

One case where something like this might be useful would be to encrypt values using a native library (using one of the new Browser crypto APIs).

Outgoing ports

Since we want to send stuff several times, not just once, we need to declare both ports as Signals. Let’s start with the outgoing port and on the Elm side:

port requestEncryption : Signal String
port requestEncryption =
  -- how do we get a Signal here for the implementation?

This is a simple outgoing port definition, but somehow we have to implement this port - we need a way to get a Signal that we can “trigger” in our elm app and that will be received on the JS side. Let’s see how the JS side will look like before coming back to Elm:

var div = document.getElementById('root');
var myapp = Elm.embed(Elm.MyApp, div);
myapp.ports.requestEncryption.subscribe(encryptString);

function encryptString(message) {
    // do something with the string, send it to be encrypted etc
}

Pretty straigthforward. We use the subscribe method to register a callback that will be called with the message string value every time the Signal fires at the Elm side. Ok, but how do we finish implementing this on the Elm side?

There are two ways to do this - one is to create a new Mailbox and use Effects to send our messages, the other is to create a custom version of StartApp that returns an additional value for things to send to the port in update. I have implemented both attempts as gists, here is the one with the Mailbox and once with a modified StartApp. For the rest of the blogpost I will refer to the first version since it works with the vanilla StartApp. Ok, let’s hook up the Mailbox:

portRequestEncryptionMailbox : Mailbox String
portRequestEncryptionMailbox =
  mailbox ""

port requestEncryption : Signal String
port requestEncryption =
  portRequestEncryptionMailbox.signal

This initalizes the Mailbox and fills in the hole we had before - the Signal we use as a port will just be the Signal of our new Mailbox. But how do we actually send anything to this Mailbox? By creating an Effect, like so:

sendStringToBeEncrypted : String -> Effects Action
sendStringToBeEncrypted clearText =
  Signal.send portRequestEncryptionMailbox.address clearText
  |> Effects.task
  |> Effects.map (\_ -> Noop)

-- and this is our update function that now returns a tuple of (Model, Effect):
update : Action -> Model -> (Model, Effects Action)
update action model =
  case action of
    TextChanged text ->
      ( { model | clearText = text }
      , sendStringToBeEncrypted text -- create the Effect here
      )
    -- other cases ...

The last line in sendStringToBeEncrypted may be a bit confusing - what are we mapping there? Let’s take a look at the type of Mailbox.send:

send : Address a -> a -> Task x ()

This means that the success type of the task we get back from send is () (aka Unit) which acts a bit similar to void in C like languages, i.e. it represents “no actual value”. Let me desugar sendStringToBeEncrypted so it is clearer what types we are working with:

sendStringToBeEncrypted : String -> Effects Action
sendStringToBeEncrypted clearText =
  sendTask : Task x ()
  sendTask = Signal.send portRequestEncryptionMailbox.address clearText

  effectOfUnit : Effects ()
  effectOfUnit = Effects.task sendTask

  effectOfAction : Effects Action
  effectOfAction = Effects.map (\_ -> Noop)

(Note that instead of first converting to Effects () and then mapping that I could also have mapped the Task x () to Task x Action and then converted the Task to Effects). This may still seem a bit weird but it may help to realize that in this particular case of sending a message to a mailbox we are explicitly not interested in an actual Action value. We are only interested in performing the side effect of sending the message and it will not have a reasonable “payload” that should be routed through update. But because of how Effects are typed in StartApp, we do need to have an Effects Action in the end and so we introduce a Noop value that explicitly does nothing when it is processed in update.

At this point it is important to remember that StartApp.start returns a record that contains a tasks field and this has to be wired to an outgoing port - if you don’t do this, the Tasks you create via Effects will never be executed by the runtime:

app =
  StartApp.start
    { init = init
    , update = update
    , view = view
    , inputs = []
    }

port tasks : Signal (Task.Task Never ())
port tasks =
  app.tasks

Ok great, this is the outgoing part of the ports - how about handling stuff that comes into our Elm program?

Incoming Ports

Let’s start on the Javascript side. We will define an incoming port called encryptionCompleted on the Elm side, and here we see how to send messages to it from JS. (Note that this example simplifies the logic a little and immediately after receiving a message from the outgoing port it sends an encrypted value back to Elm via the incoming port - in practice encryptString would probably call an API that returns a promise and only when this is fullfilled call send to send a value back to Elm)

var div = document.getElementById('root');
var myapp = Elm.embed(Elm.MyApp, div, {encryptionCompleted : ""});
myapp.ports.requestEncryption.subscribe(encryptString);

function encryptString(message) {
    encryptedMessage = "Encypted: " + message; // actually encypting the message is ommited
    myapp.ports.encryptionCompleted.send(encryptedMessage);
}

Note that I not only had to modify encryptString but also pass in an initial value at the time when we initialize Elm with the call to Elm.embed. The third parameter takes the initial value of every incoming Signal we define on the Elm side - it is required because Signals in Elm always need an initial value. Let’s add this incoming port on the Elm side to complete the example:

port encryptionCompleted : Signal String

Note that this time the port we have defined has no “implementation” in Elm. That is because, viewed from Elm, this is just an external input - a Signal we can use to trigger behaviour in our app. But how can we do that? How can we wire up this Signal into our StartApp.start call?

In the last post, when we switched from StartApp.Simple to StartApp, I mentioned inputs. inputs is a List of (Signal of Action), i.e. Signals that fire Actions that will be combined with the Signal of the main mailbox that is administered by StartApp. So this is exactly what we want to have for this little program so it can react to the Signal that represents the port - the only thing that is missing is that we have defined encryptionCompleted as a Signal of String and we need a Signal of Action for inputs. Sounds like we need a map again:

encryptedString : Signal Action
encryptedString =
  Signal.map EncryptedValueReceived encryptionCompleted

app =
  StartApp.start
    { init = (init, Effects.none)
    , view = view
    , update = update
    , inputs = [ encryptedString ]  
    }

And voilà! We have a Signal of Actions that we can put into the inputs part of start.

So just to recap, let’s go through the example again: Whenever the user enters text we process the TextChanged value in our update function and not only update the model but also create a new Effects. This is then returned by update and, because we wired the tasks part returned by start to an outgoing port, it is handed to the runtime. This leads, on the native JS side, to a call of encryptString (because this is the function we registered with subscribe). In it we pretended to do some encryption and then sent the value back with encryptionCompleted.send (again, you can send values at any time, it only happens in our example that we send one value back for every value we receive on the JS side). This send call leads the encryptionCompleted Signal to fire, with the string value we sent from the JS side. This is than mapped into an Action value, namely EncryptedValueReceived, and because this is hooked up to the inputs part of StartApp it triggers the same chain through update as any other events. In update we then handle processing of this EncryptedValueReceived value and the whole exercise is complete.

Thanks for reading through this long post! I hope it was useful and I appreciate any feedback you might have!

Signals in Elm

Feb 12, 2016

Disclaimer: This post was written about Elm 0.16. Signals, the mechanism described in this post, have since been deprecated. The concepts in this post may still help understand how the Elm Architecture works internally, but the actual code has changed significantly

What are Signals?

Elm uses a very nice unidirectional architecture for the flow of:

displayed website ➞ user actions ➞ new application state ➞ displayed website

All the code you write in a typical Elm program comes together in just two pure functions: update and view.

Update takes a user action and the previous application state and creates a new application state, and view takes an application state and renders it into a virtual dom representation (that then gets efficiently displayed by batching diffs to the DOM a la React). For more background on unidirectional UIs in general see André Staltz’ excellent blog post Unidirectional User Interface Architectures

One of the key concepts in Elm is that of a Signal. A Signal is a value that can change over time. One of the conceptually simplest signals is the current time - every second the signal “fires” with the new time value (seconds passed since epoch or whatever). Another example could be the coordinates of the mouse cursor in the current window. When the mouse is still, no values are fired by the Signal - but whenever the user moves the mouse, new values are sent.

Signals are a bit similar to EventEmmitters or Observables in Javascript - the key difference is that they exist for the entire lifetime of the program and always have an initial value.

Signals don’t provide any access to their history - they only provide the current value. But even a simple counter example needs to track the number of clicks that happened so far. Since Elm is a pure language with no mutable state, how do you keep track of the current click-count?

StartApp hides a bit of wiring from you, but I think it helps to understand how StartApp.start does its magic. What the start function does is hook up a Mailbox (something where messages go when you send them to the address e.g. in an onClick handler) so that they lead to a new html emmited to main. This is the heart of the unidirectional UI approach.

The user clicks a button, this leads to a message being sent to the mailbox. The mailbox has a Signal that fires whenever a message is sent to it. This Signal is of your applications Action type, i.e. it fires Action values. Eventually this leads to a full cycle through your update/view functions and thus to a new version of your Virtual Dom.

Let’s look at the intermediary types more closely: we start with a Signal of Actions. This then gets turned into a Signal of Models (so everytime a new Action is fired this action value is run through update together with the last model state to get the new model state). This finally gets turned into a Signal of Html (whenever the Signal of Model fires, we run it through the view function to arrive at a new Html to display). This is then handed to main so that the Elm runtime can display it for us.

Note that when I wrote about the update function, I said “together with the last model state”. This brings us back to our question from above - how can you work with history or state in Elm? The answer is in the function called Signal.foldp (“fold from the past”).

If you aren’t familiar with folds yet, they are another name for reduce functions (as in map/reduce). It logically reduces all the values from the entire history with a given function and returns the value - in our case it uses the inital Model and reduces all Actions that were sent to our program to arrive at a current Model. (the implementation actually just caches the last current value and works from there of course).

Let’s look at how StartApp.Simple is actually implemented (I added comments and type annotation to every named value)

start : Config model action -> Signal Html
start config =
  let
      -- create the main Mailbox and initialize with an "empty" value of Nothing
      actions : Mailbox (Maybe action)
      actions = Signal.mailbox Nothing

      -- address is set up
      -- everything that is sent to address is "wrapped" in 
      -- the Just type constructor and forwarded to the Mailbox
      address : Address action
      address = Signal.forwardTo actions.address Just

      -- to  wrap config.update to take care of the Maybe part of the action
      -- that will be processed can simply operate as Action -> Model -> Model)
      update : Maybe action -> model -> model
      update maybeAction model =
        case maybeAction of
          Just action -> config.update action model
          Nothing -> Debug.crash "This should never happen."

      -- set up a signal of new models that foldp-s over the actions signal
      -- The update function will process one Action and the old Model state
      -- to the new model State, the Signal that triggers it all is
      -- the Mailbox' Signal we set up at the top
      model : Signal model
      model = Signal.foldp update config.model actions.signal
  in
     --  map over it with the view function
     --  This turns the Signal of Models into a Signal of Htmls that can be rendered    
      Signal.map (config.view address) model

StartApp.Simple is quite clever in how it uses a Signal under the hood but as a user who just wants to write some interactive web app you never need to deal with Signals directly and can just supply update and view.

It all works fine until you need to message back and forth with native javascript. For that, you will need to use Ports, and understanding Signals first will be very helpful for that.

The other thing StartApp.Simple does not let you do is perform long running operations, like e.g. send XHR requests.

Tasks and Effects in Elm

Feb 19, 2016

Disclaimer: This post was written about Elm 0.16. Signals have since been deprecated. The concepts in this post may still help understand how the Elm Architecture works internally, but the actual code has changed significantly

In this post I get into long running operations like XHRs (aka AJAX). There are two closely related types that are involved in this, Tasks and Effects, and the exact differences between can be confusing in the beginning

Tasks

A Task represents a long-running operation that can fail (with an error type) or succeed (with a success type). It’s type is thus:

Task errorType successType
-- (or, as it is actually written in the library:)
Task x a

There are only two values of Task you can create yourself in your code, without using a separate library. These two ways are two functions:

succeed : a -> Task x a
-- and
fail : x -> Task x a

These are ways to create task values without actually doing any long-running operations. This can be useful if you want to combine a long running task and a simple value in some way and process them further (you would then turn the simple value into a Task with succeed).

Most of the time you actually get in contact with tasks, these will be created for you by library functions that initialize the task so that it will perform some long running operation when the runtime executes it and handle the result of the operation according to Task semantics (I.e. that some native code will make sure to call fail or succed on the native representation of the task when the operation is finished).

Note that the operation doesn’t start right away! I said “when the runtime executes it”.

In purely functional programming languages, inside the language you can never just perform a side effect, and sending an "http request" surely is a side effect in that sense. This is one of the big mental shifts from imperative programming, where you can always do this, to working with purely functional languages where you can’t.

So how does this actually work?

The task you get back represents the long running action. When a library creates it for you, nothing “happens”, it just created a value (of type Task) that indicates what you would like to happen.

If you look at e.g. the implementation of the native part of the send function in http you will see that a Task is created in native JS code by handing it a callback. This callback is what will get called when the runtime actually executes the task. This is when the actual XHR request is created and performed - only when the runtime executes this callback.

So how do you get the runtime to run this task?

By passing it into an outgoing port. I will go into detail on ports in a later blogpost, but suffice to say that they are a way to send messages between “native” JS and Elm (called an incoming port) and from Elm to native JS (an outgoing port). The runtime has some special casing for Tasks that come to it via outgoing ports that make it execute the callback the Task represents.

When the long running native code is done, it will either call succeed or fail on the task.

In most real life code that uses the Elm Architecture you will set up a “chain” of task processing that will lead to the the end result of the task execution being that a value of your Action type is routed back through your update function. This value of your Action type is the usually tagged with the result of the task (e.g. the decoded Json response of an XHR).

Tasks can easily be chained togehter with andThen, much like promises in JS are chained together.

Effects

On to Effects! If you look at the definition for Effects it’s pretty simple:

type Effects a
    = Task (Task.Task Never a)
    | Tick (Time -> a)
    | None
    | Batch (List (Effects a))

None and Batch are helpers, so the basic things an Effect can represent are Tasks (with error type Never) and Ticks. The latter is used for animations if you want to do something at the next animation frame.

It’s very common to turn a Task into an Effect, whereas the inverse is usually only ever done by StartApp/the runtime.

Several libraries use Task to allow you to work with long running operations - Http is one, elm-history is another.

So how is this used? The Elm Architecture example 5 uses this very central piece of code:

getRandomGif : String -> Effects Action
getRandomGif topic =
  Http.get decodeImageUrl (randomUrl topic)
    |> Task.toMaybe
    |> Task.map NewGif
    |> Effects.task

Let’s look at what it does. It starts with creating a task that represents the Http get operation and then builds a chain on top of this. I will deconstruct this from using the pipe operator to normal function calls with type annotations to hopefully explain what’s happening:

getRandomGif topic =
  getTaskWithError : Task Http.Error String
  getTaskWithError = Http.get decodeImageUrl (randomUrl topic)

  getTaskWithNoErrorAndMaybe : Task Never (Maybe String)
  getTaskWithNoErrorAndMaybe = Task.toMaybe getTaskWithError

  getTaskWithNoErrorAndAction : Task Never (Action)
  getTaskWithNoErrorAndAction = Task.map NewGif getTaskWithNoErrorAndMaybe

  taskAsEffect : Effects Action
  Effects.task getTaskWithNoErrorAndAction

So in the end, Effects in this case just wraps the Task for us. Because we used toMaybe and then mapped it to the NewGif type constructor function, this will result in an Action coming back to us via update when it is done that is either (NewGif Nothing) if the http request failed, or (NewGif "some-url-here") if it succeeds. If you want to understand how this wiring happens I would suggest looking at the implementation of Effects.

One thing that is worth looking at is the return type of the function: Effects Action. Effects has a type variable, just like for example List. So this is an Effects that deals with the Action type you define in your application - and this is the really neat part of how to make sure that you can deal with the result of the Task/Effect - the result will just be a value of your Action type!

At this point you may wonder: why have Effects at all? Aren’t they just weird wrappers for Tasks? Let’s quickly take a look again at how the Task case of the Effects type is defined:

type Effects a = Task (Task.Task Never a)

The way StartApp is typed, going via Effects Action constraints all Tasks to come back with Actions and have the error type Never. This is really nice because it means that you don’t have to handle different task types to different ports, but you set up “pipelines” of tasks to effects like with getRandomGif above and it will all work out in a typesafe manner that the result of your tasks will be sent back to your program’s update function as Actions.

Ok, so finally, remember I wrote something about having to send Tasks off to an outgoing port. I you don’t do this, the Tasks will never be executed! If you want to use Effects, the easiest way is to switch from StartApp.Simple to StartApp. This brings three minor changes with it:

  1. start no longer directly returns a Signal of Html but a record of 3 Signals: one for the html, one for the model, and, crucially for us, one of tasks.
  2. The update function now returns not just the Model, but a tuple of (Model, Effects Action). I.e. that every case in your update function will have to return both the changed model and an Effect (which will often be Effects.none)
  3. start gets a fourth parameter, inputs, for incoming Signals.
  4. The tasks part of the record that is returned by start has to be handed to a port so that the Tasks/Effects are actually performed by the runtime like so:
app = StartApp.start
    { init   = init "funny cats"
    , update = update
    , view   = view
    , inputs = []
    }

main =  app.html

port tasks : Signal (Task.Task Never ())
port tasks = app.tasks

Phew, this got a little long again, but I hope it helps a little to understand how Tasks/Effects work!