We can use commands to execute operations that may cause side effects. Like messages, commands are also represented as data. Think of them as data structures that store information about an action we want to perform. We then hand that data structure over to the Elm runtime. The runtime will execute the action specified in the command and notify our application with a result. That sounds really vague, doesn’t it? Let’s look at an example for generating random numbers to make things a bit more concrete.
Generating Random Numbers
There are two main approaches to generating random numbers: True Random Number Generators (TRNGs) and Pseudo-Random Number Generators (PRNGs). TRNGs generate numbers from truly random physical phenomena, for example the little variations in someone’s mouse movements or the point in time at which a radioactive material decays or the atmospheric noise picked up by a radio.
Due to their reliance on a physical phenomena, TRNGs take considerably longer time to generate random numbers. Therefore, most computer programs that need random numbers quickly tend to rely on PRNGs which are much more efficient than TRNGs. Despite their efficiency, PRNGs are not suitable for applications that need truly unpredictable random numbers, such as encryption key generators.
PRNGs take an initial value (called seed) and apply an algorithm to generate a seemingly random number. The modern algorithms used by PRNGs are so good that the numbers generated by them look quite random.
However, if we use the same initial seed multiple times we will get the exact same number each time.
Generating Random Numbers without Side Effects
Let’s explore this behavior of PRNGs further by entering some code in
elm repl. But first we need to install the
elm/random package. Run the following command from the
beginning-elm directory in terminal.
elm-explorations/test package we used earlier in the Easy to Test section depends on
elm/random. That’s why when we installed it,
elm/random was automatically added as an
indirect dependency to the
test-dependencies field in
elm install is asking us if it’s okay to move it to the
dependencies field. Go ahead and answer
All packages in the
dependencies field are also available in tests, so we’ll still be able to run our tests without any issues. Run
elm repl from the
beginning-elm directory in terminal and import the
Random module included in
We’re now ready to generate an initial seed.
initialSeed function takes an integer and returns a seed. We randomly picked the number
31415 as an input. Here’s what the
initialSeed function’s type signature looks like:
Seed type is defined in the
Random module like this:
Seed is an opaque type. Opaque types use the same name for type and data constructors to hide internal details. Let’s explore this idea further by creating a new file called
Profile.elm in the
Add the following code to
Name is a type alias to a record with two fields. Since we exposed it in the module definition, any code outside of
Profile can access it. The
lastName fields are also accessible from outside. Let’s test that assertion in
What if we don’t want the outside code to know how the
Name type is implemented? We may want to add middle name to our definition in the future. The way things are right now, the code that uses
Name will certainly break if we introduce a new field. How about we re-implement
Name as an opaque type like this in
Now any code outside of
Profile.elm won’t be able to access the internal fields (
lastName) like it used to. Let’s try to create a name using the new opaque type.
Unfortunately, we lost the ability to create a name. We can expose the underlying data constructor by adding
(..) next to
Name in module definition like this:
And that will allow us to create a name using the
Name data constructor.
However, exposing the underlying data constructor defeats the purpose. We want to hide the internal details of our type and still be able to create a name. To do that, we need to introduce a new function whose sole purpose is to create a name. Remove
(..) from the module definition and add a new function called
elm repl and enter the following code.
Now we can create a name from outside
Profile without having to know the internal details of
Back to Seed
Random module applies the same technique used in
Profile.elm to hide the internal details of
Seed while also allowing us to create a seed using the
Now that we have an initial seed, we can use the
Random.step function to generate a random value.
The output is a tuple. The first element is a random number and the second element is the seed we can use to generate the next random number. As mentioned earlier, we need to provide a different seed to the
step function each time we want to generate a new random number. Otherwise, we keep getting the same number over and over again. That’s why the
step function returns a new seed in addition to a random number.
step takes a random number generator and a seed as inputs. Here’s what its type signature looks like:
Random.int 0 100 expression we typed into the repl earlier creates a generator that produces random 32-bit integers between
It’s important to understand that the
Random.int function itself doesn’t generate a random number. It returns a generator which can be passed to other functions such as
step that will in turn ask that generator to produce the actual random numbers.
Think of a generator as a recipe for generating certain types of random values. So
Random.int 0 100 describes how to create a recipe for generating integers between
Random.float 0 1 describes how to create a recipe for generating floating-point numbers between
Next, we’ll capture the new seed returned by the
step function so that we can use it to generate a different random number.
Now, we’re ready to generate a new random number.
This time we got
91 as the new number. Last time it was
35. The numbers inside the
Seed type also changed. If those numbers didn’t change we would get the same random number again and again. What this means is that
Random.step is a pure function and doesn’t generate any side effects. It returns the exact same output given the same input.
Generating Random Numbers with Side Effects
The process of manually providing seed values, as we’ve done so far, has some drawbacks. First, it is cumbersome. Second, it makes the random number sequence predictable. Elm provides a way to get rid of these hurdles by picking an unpredictable initial seed value by default. It does so by using the current time generated by a real-time clock embedded in our computers to produce seed values.
As soon as we transfer the responsibility of picking the initial seed value to the Elm runtime, the random number generation process causes side effects. To get the initial seed value, it has to now interact with a real-time clock, which is part of the outside world. This is where commands come in handy.
To generate random numbers with side effects we need to follow the Elm Architecture. It’s hard to write a full fledged program in repl, so we’ll create a new file called
RandomNumber.elm in the
The first thing we need to define is our model. Add the following code to
All we need to keep track of here is a number. The above model looks exactly like the one we defined for the counter app in Model View Update - Part 1. Next, we need to create an initial model. Add the following code to the bottom of
When commands are involved, the code for initializing our model becomes a little more complex. In the counter app, all we had to do was return an integer as shown below.
Let’s go through each change one by one.
Change #1: The function name changed from
init since we’re doing more than just initializing a model.
Change #2: The
init function now returns a tuple. The first element represents the model and the second element represents commands. In addition to providing an initial value for the model, we need to tell the runtime what commands to run when the app is being loaded. Since we don’t want to run any commands during initialization, we simply return
Cmd type represents commands in Elm. It’s defined in the
none is a constant which returns an empty list of commands. It’s also defined in the
Let’s say when our app is launched we need to restore its state from a remote server which lies outside the boundary of our app. In this scenario, we need to rely on the Elm runtime to retrieve the state by returning a command from
Change #3: The type annotation has also changed to
init : ( Model, Cmd msg ). We already know what
Cmd msg means a command that will
notify our app with results by sending messages of type
msg is just a type variable, so it doesn’t represent a concrete type. Later in this section, we’ll define a type called
Msg to be more specific about which messages our app can accept.
Next, we need to present the initial model to the user. Add the following code to the bottom of
Our view is very simple. All we’re displaying is a button and the string representation of a random number. We also need to import the
Html module in
Right now, the Generate Random Number button doesn’t do anything. Let’s define a message that will get triggered when that button is clicked. Add the following type definition to the bottom of
To respond to the
GenerateRandomNumber message, we need to introduce
update. Add the following code to the bottom of
initialModel in the previous sections) tend to have the same return types. Here is
update from the counter app for comparison:
Let’s understand what’s going on in the body of the new
update function. When the
GenerateRandomNumber message is received, we return an unmodified model and a command for generating a random number. The command is generated by using the
generate function defined in the
Note: In Elm, we don’t tend to use some constructor function defined in the
Platform.Cmd module to create commands. Instead, we rely on functions like
generate. Here’s another example: let’s say we want to create a command that sends an HTTP request to a remote server. We can use the
Http.send function to generate that command. We just look for an appropriate function in a module and use it to create a command.
generate tries to achieve the same goal as the
step function — generate a random number. The way it goes about achieving that goal, however, is very different.
step uses a generator and a seed to return a random number instantly.
generate on the other hand, takes a generator and tells the Elm runtime to run that generator. It also tells the runtime which message to send when a number is ready. We haven’t defined the
NewRandomNumber message yet; we’ll do that soon.
Why do we have to supply a message name to
generate? Why can’t it just return a random number immediately like
step did? It’s due to
the fact that we aren’t manually providing an initial seed value anymore. We need to generate a seed by using our computer’s clock, which produces side effects.
To run things that generate side effects, Elm requires us to create a command along with any pertinent information that command needs. We then hand that command over to the runtime. The runtime executes the command and notifies our application with the result by sending the message included in the command. The following diagram illustrates this process.
Here’s what the
generate function’s type signature looks like:
The first argument is a function that takes a value and wraps it in a message. In our case, that’s
NewRandomNumber. Remember, messages that take an argument are essentially functions. If you check the type of
NewRandomNumber in repl, you will see that it takes an integer and returns a message of type
The second argument to
generate is a random number generator. In our case, it’s
Random.int, which takes the range as inputs (e.g.,
0 100). Lastly,
generate returns a command that encapsulates the message and the generator. The next step is to add
NewRandomNumber to the
Msg type and also handle it in the
update function as shown below.
NewRandomNumber message is received, we simply return the number in payload as our model and an empty list of commands. Let’s import the
Random modules next and add an
onClick attribute to our button so that the
GenerateRandomNumber message gets triggered when it’s clicked.
Don’t forget to replace
view’s type annotation. We actually need to make that replacement in
init as well.
Wiring Everything Up
Let’s wire up everything we have built so far by adding
main to the bottom of
With the introduction of commands,
main also became slightly more complex. Here’s how it was in the counter app:
Let’s go through each change one by one.
Change #1: We’re now using
Browser.element instead of
Browser.sandbox to wire everything up. The former takes a record with four fields whereas the latter takes a record with only three fields.
- Browser.sandbox vs Browser.element
Browser.sandboxcreates an Elm program that cannot communicate with the outside world by issuing commands. That’s why the counter app’s update function returns only a model and no commands.
update : Msg -> Model -> Model
In contrast, Elm programs created with
Browser.elementare able to communicate with the outside world. That’s why the random number app’s update function returns a tuple containing a model and commands.
update : Msg -> Model -> ( Model, Cmd Msg )
When you’re building an Elm app, it’s good to start with
Browser.sandboxand wait for a use case that requires the app to communicate with the outside world. Once that use case arrives, you can upgrade to
Change #2: The
init field in
Browser.element expects a function that takes
flags and returns a tuple containing model and commands. The
init function we wrote earlier returns just the tuple. Let’s use it here, but before we do that let’s clean things up a bit by moving
flags to the
If we want to pass values to an Elm app during initialization we need to send them as
RandomNumber app doesn’t need
flags, but the
Browser.element function expects us to include it in our
init function anyway. In chapter 8, we’ll implement a feature that actually uses
Since we aren’t passing any flags to our app, we don’t know what its type should be. That’s why we used the
flagsType type variable to indicate it can be anything. Although a type variable is fine, it’s better to use
() — the unit type — instead for an unused parameter’s type. So let’s replace
(). Let’s also replace
_ since that parameter isn’t being used anywhere inside
Note: If you don’t remember the difference between
_, go ahead and refresh your memory by reviewing the Unit Type vs Underscore section from chapter 4.
Now replace the anonymous function in
subscriptions represents things we want to listen to, for example web socket messages and location changes. By assigning
\_ -> Sub.none, we let the Elm runtime know that we aren’t interested in listening to anything right now. We’ll cover subscriptions in detail later in chapter 8. The only thing remaining is to import the
We’re now ready to test our app. Run
elm reactor from the
beginning-elm directory in terminal if it’s not running already, and go to this URL in your browser:
http://localhost:8000/src/RandomNumber.elm. You should see a view that looks like this:
Click the Generate Random Number button multiple times and you should see a different number each time.
In this section, we learned how to use commands to execute operations that cause side effects. Here is how the Elm Architecture looks with the introduction of commands:
The interaction between the Elm runtime and our code has also become a bit more complex now that we are using commands. The sequence diagram below shows that interaction.
Commands are an important concept in Elm. We need to understand them well in order to build complex applications. In chapter 6, we’ll continue to explore how commands can help us execute one of the most common operations performed in web apps — sending and receiving data from an HTTP server — without sacrificing our application code’s purity. Here is the entire code from