In this full course from David Kopal, you will learn everything you need to know about ReasonML (aka Reason) and you will be able to start building awesome things with it.

You can watch the full video course on the freeCodeCamp.org YouTube channel (5.5 hour watch).

Are you using React to build user interfaces? Well, I am too. And now, you’ll learn why you should write your React applications using ReasonML.

React is a pretty cool way to write user interfaces. But, could we make it even cooler? Better?

To make it better, we need to identify its problems first. So, what is the main problem of React as a JavaScript library?

React wasn’t initially developed for JavaScript

If you take a closer look at React, you’ll see that some of its main principles are foreign to JavaScript. Let’s talk about immutability, functional programming principles, and type system in particular.

Immutability is one of the core principles of React. You don’t want to mutate your props or your state because if you do, you might experience unpredictable consequences. In JavaScript, we don’t have immutability out of the box. We are keeping our data structures immutable by a convention, or we use libraries such as immutableJS to achieve it.

React is based on the principles of functional programming since its applications are compositions of functions. Although JavaScript has some of these features, such as first-class functions, it’s not a functional programming language. When we want to write some nice declarative code, we need to use external libraries like Lodash/fp or Ramda.

So, what’s up with the type system? In React, we had PropTypes. We’ve used them to mimic the types in JavaScript since it isn’t a statically typed language itself. To take advantage of advanced static typing, we again need to use external dependencies, such as Flow and TypeScript.

React, and JavaScript comparison

As you can see, JavaScript isn’t compatible with React’s core principles.

Is there another programming language that would be more compatible with React than JavaScript?

Fortunately, we have ReasonML.

In Reason, we get immutability out of the box. Since it’s based on OCaml, the functional programming language, we have such features built into the language itself as well. Reason also provides us with a strong type system on its own.

React, JavaScript, and Reason comparison

Reason is compatible with React’s core principles.

Reason

It isn’t a new language. It’s an alternative JavaScript-like syntax and toolchain for OCaml, a functional programming language that’s been around for more than 20 years. Reason was created by Facebook developers who already used OCaml in their projects (Flow, Infer).

Reason, with its C-like syntax, makes OCaml approachable for people coming from mainstream languages such as JavaScript or Java. It provides you with better documentation (compared to OCaml) and a growing community around it. Plus, it makes it easier to integrate with your existing JavaScript codebase.

OCaml serves as a backing language for Reason. Reason has the same semantics as OCaml — only the syntax is different. This means that you can write OCaml using Reason’s JavaScript-like syntax. As a result, you can take advantage of OCaml’s awesome features, such as its strong type system and pattern matching.

Let’s take a look at an example of Reason’s syntax.

let fizzbuzz = (i) =>
  switch (i mod 3, i mod 5) {
  | (0, 0) => "FizzBuzz"
  | (0, _) => "Fizz"
  | (_, 0) => "Buzz"
  | _ => string_of_int(i)
  };
for (i in 1 to 100) {
  Js.log(fizzbuzz(i))
};

Although we’re using pattern matching in this example, it’s still pretty similar to JavaScript, right?

However, the only usable language for browsers is still JavaScript, meaning we need to compile to it.

BuckleScript

One of Reason’s powerful features is BuckleScript compiler, which takes your Reason code, and compiles it to readable and performant JavaScript with great dead code elimination. You’ll appreciate the readability if you’re working on a team where not everyone is familiar with Reason, since they’ll still be able to read the compiled JavaScript code.

The similarity with JavaScript is so close that some of Reason’s code doesn’t need to be changed by the compiler at all. So, you can enjoy the benefits of the statically typed language with no change to the code whatsoever.

let add = (a, b) => a + b;add(6, 9);

This is valid code in both Reason and JavaScript.

BuckleScript is shipped with four libraries: the standard library called Belt (OCaml standard library is insufficient), and bindings to JavaScript, Node.js and, DOM APIs.

Since BuckleScript is based on OCaml compiler, you’ll get a blazingly fast compilation that is much faster than Babel and several times faster than TypeScript.

Let’s compile our FizzBuzz algorithm written in Reason to JavaScript.

Reason’s code compilation to JavaScript through BuckleScript

As you can see, the resulting JavaScript code is pretty readable. It seems like it was written by a JavaScript developer.

Not only does Reason compile to JavaScript, but to native and bytecode as well. So, you can write a single application using Reason syntax and be able to run it in the browser on MacOS, Android, and iOS phones. There’s a game called Gravitron by Jared Forsyth which is written in Reason and it can be run on all the platforms I’ve just mentioned.

JavaScript interop

BuckleScript also provides us with JavaScript interoperability. Not only can you paste your working JavaScript code in your Reason codebase, but your Reason code can also interact with that JavaScript one. This means you can easily integrate Reason code into your existing JavaScript codebase. Moreover, you can use all the JavaScript packages from the NPM ecosystem in your Reason code. For example, you can combine Flow, TypeScript, and Reason together in a single project.

However, it’s not that simple. To use JavaScript libraries or code in Reason, you need to port it to Reason first via Reason bindings. In other words, you need types for your untyped JavaScript code to be able to take an advantage of Reason’ s strong type system.

Whenever you need to use a JavaScript library in your Reason code, check if the library was already ported to Reason by browsing the Reason Package Index (Redex) database. It’s a website that aggregates different libraries and tools written in Reason and JavaScript libraries with Reason bindings. If you found your library there, you can just install it as a dependency and use it in your Reason application.

However, if you didn’t find your library, you’ll need to write Reason bindings yourself. If you’re just starting with Reason, keep in mind that writing bindings aren’t a thing you want to start with, since it’s one of the more challenging things in Reason’s ecosystem.

Fortunately, I’m just writing a post about writing Reason bindings, so stay tuned!

When you need some functionality from a JavaScript library, you don’t need to write the Reason bindings for a library as a whole. You can do that only for the functions or components you need to use.

ReasonReact

This article is about writing React in Reason, which you can do thanks to the ReasonReact library.

Maybe you’re now thinking “I still don’t know why I should use React in Reason.”

We’ve already mentioned the main reason to do so — Reason is more compatible with React than JavaScript. Why is it more compatible? Because React was developed for Reason, or more precisely, for OCaml.

Road to ReasonReact

React’s first prototype was developed by Facebook and was written in Standard Meta Language (StandardML), a cousin of OCaml. Then, it was moved to OCaml. React was also transcribed to JavaScript.

This was because the whole web was using JavaScript, and it wasn’t probably smart to say, “Now we’ll build UI in OCaml.” And it worked — React in JavaScript has been widely adopted.

So, we became used to React as a JavaScript library. React together with other libraries and languages — Elm, Redux, Recompose, Ramda, and PureScript — made functional programming in JavaScript popular. And with the rise of Flow and TypeScript, static typing became popular as well. As a result, the functional programming paradigm with static types became mainstream in the world of the front-end.

In 2016, Bloomberg developed and open-sourced BuckleScript, the compiler that transforms OCaml to JavaScript. This enabled them to write safe code on the front-end using OCaml’s strong type system. They took the optimized and blazingly fast OCaml compiler and swapped its back-end generating native code for a JavaScript generating one.

The popularity of functional programming together with the release of the BuckleScript generated the ideal climate for Facebook to get back to the original idea of React, which was initially written in an ML language.

ReasonReact

They took OCaml semantics and JavaScript syntax, and created Reason. They also created the Reason wrapper around React — ReasonReact library — with additional functionalities such as the encapsulation of the Redux principles in stateful components. By doing so, they returned React to its original roots.

The power of React in Reason

When React came into JavaScript, we adjusted JavaScript to React’s needs by introducing various libraries and tools. This also meant more dependencies for our projects. Not to mention that these libraries are still under development and breaking changes are introduced regularly. So you need to maintain these dependencies with care in your projects.

This added another layer of complexity to JavaScript development.

Your typical React application will have at least these dependencies:

• static typing — Flow/TypeScript
• immutability — immutableJS
• routing — ReactRouter
• formatting — Prettier
• linting — ESLint
• helper function — Ramda/Lodash

Let’s now swap JavaScript React for ReasonReact.

Do we still need all these dependencies?

• static typing — built-in
• immutability — built-in
• routing — built-in
• formatting — built-in
• linting — built-in
• helper functions — built-in

You can learn more about these built-in features in my other post.

In the ReasonReact application, you don’t need these and many other dependencies since many crucial features that make your development easier are already included in the language itself. So, maintaining your packages will become easier and you don’t have an increase in complexity over time.

This is thanks to the OCaml, which is more than 20 years old. It’s a matured language with all of its core principles in place and stable.

Wrap-up

At the beginning, the creators of Reason had two options. To take JavaScript and somehow make it better. By doing that they’d also need to deal with its historical burdens.

However, they went a different path. They took OCaml as a matured language with great performance and modified it so it resembles JavaScript.

React is also based on the principles of OCaml. That’s why you’ll get a much better developer experience when you’re using it with Reason. React in Reason represents a safer way of building React components, since the strong type system has got your back and you don’t need to deal with most of the JavaScript (legacy) issues.

What’s next?

If you’re coming from the world of JavaScript, it’ll be easier for you to get started with Reason, due to its syntax similarity with JavaScript. If you’ve been programming in React, it’ll be even easier for you since you can use all your React knowledge as ReasonReact has the same mental model as React and very similar workflow. This means you don’t need to start from scratch. You’ll learn Reason as you develop.

The best way to start using Reason in your projects is to do it incrementally. I’ve already mentioned that you can take Reason code and use it in JavaScript, and the other way around. You can do the same thing with ReasonReact. You take your ReasonReact component and use it in your React JavaScript application, and vice versa.

This incremental approach has been chosen by Facebook developers who are using Reason extensively in the development of the Facebook Messenger app.

If you want to build an application using React in Reason and learn the basics of Reason in a practical way, check my other article where we’ll build a Tic Tac Toe game together.

If you have any questions, criticism, observations, or tips for improvement, feel free to write a comment below or reach me via Twitter or my blog.

3. 7. 2018: UPDATED to ReasonReact v0.4.2

You may have heard of Reason before. It’s a syntax on top of OCaml that compiles to both readable JavaScript code and to native and bytecode as well.

This means you could potentially write a single application using Reason syntax, and be able to run it in the browser, and on Android and iOS phones as well.

This is one of the reasons why Reason (ouch, pun) is becoming increasingly popular. This is especially true in the JavaScript community because of the syntax similarities.

If you were a JavaScript developer before Reason came out and wanted to learn a functional programming (FP) language, you would have had to also learn a whole new syntax and set of rules. This might’ve discouraged many people.

With Reason, you mainly need to understand the FP principles on which it’s based — such as immutability, currying, composition, and higher-order-functions.

Before I discovered Reason, I was trying to use FP principles in JavaScript as much as I could. However, JavaScript is limited in this sense, since it’s not meant to be an FP language. To take advantage of these principles effectively, you need to use a bunch of libraries that create complicated abstractions which are hidden from you.

Reason, on the other hand, opens the entire FP realm to all interested JavaScript developers. It provides us with an opportunity to use all those cool OCaml features using syntax we dearly know.

Last but not least, we can write our React or React Native apps using Reason.

Why should you give Reason a try?

I hope you’ll discover the answer for yourself by the time you’ve finished reading this post.

As we go through the source code of the classic Tic Tac Toe game — written in Reason, using React — I’ll explain the core features of the language. You’ll see the benefits of the strong type system, immutability, pattern matching, functional composition using pipe, and so on. Unlike JavaScript, these features are intrinsic to Reason itself.

Warming up

Before getting your hands dirty, you need to install Reason on your machine following this guide.

After that, you need to setup your app. To do this, you can either clone my repository containing the code of our app or you can setup your own project using ReasonScripts and code along.

To view your app in the browser, you need to compile your Reason files to JavaScript ones first. The BuckleScript compiler will take care of that.

In other words, when you run npm start (in the ReasonScripts project), your Reason code gets compiled to JavaScript. The result of the compilation is then rendered to the browser. You can see for yourself how readable the compiled code is by checking the lib folder inside your app.

Our first component

As we’ve already mentioned, our Tic Tac Toe app is written using ReasonReact library. This makes Reason approachable for JavaScript developers, and a lot of newcomers are coming from this community.

Our app has a classic component structure, like any other React app. We’ll go through the components top-down when talking about UI, and bottom-up when describing their logic.

Let’s get started by taking a look at the top level App component.

let component = ReasonReact.statelessComponent("App");
let make = _children => {
  ...component,
  render: _self =>
    <div>
       <div className="title">
         (ReasonReact.string("Tic Tac Toe"))
       </div>
       <Game />
    </div>,
};

The component gets created when you call ReasonReact.statelessComponent and pass the name of the component to it. You don’t need any class keywords like in React, since Reason doesn’t have any whatsoever.

The component is neither a class nor function — it’s a so-called record. record is one of Reason’s data structures, which is similar to the JavaScript object. Unlike the latter, however, record is immutable.

Our new record component contains various default properties such as the initial state, lifecycle methods, and render. To adjust the component to our needs, we need to override some of these properties. We can do that inside the make function that returns our component.

Since the record is immutable, we can’t override its properties by mutation. Instead, we need to return a new record. To do this, we need to spread our component and redefine the properties we want to change. This is very similar to the JavaScript object spread operator.

Since the App is a pretty simple component, we want to override only the default render method so we can render our elements to the screen. The render method takes a single self argument that gives us access to the state and reducers, as we’ll see later.

Since ReasonReact supports JSX, our render function can return JSX elements. The uncapitalized element will be recognized as a DOM element — div. The capitalized element will be recognized as a component — Game.

Due to Reason’s strong type system, you can’t simply pass a string to an element in order to display it, as you can in classic React.

Instead, you need to pass such string into a ReasonReact.string helper function that’ll convert it into reactElement which can be rendered.

Since this is a little bit verbose, and we’ll use this helper quite often, let’s store it in a toString variable. In Reason, you can use only the let keyword to do that.

let toString = ReasonReact.string;

Before moving any further, let’s talk a bit about the make function’s arguments. Since we are not passing any props to the App component, it takes only the default children argument.

However, we are not using it. We can make this explicit by writing an underscore before it. If we haven’t done this, the compiler would give us a warning that the argument is not being used. We are doing the same with the self argument in the render method.

Understandable error and warning messages are another cool feature that’ll improve your developer experience, compared to JavaScript.

Setting up variant types

Before diving into the application itself, we’ll define our types first.

Reason is a statically typed language. This means it evaluates the types of our values during the compilation time. In other words, you don’t need to run your app to check if your types are correct. This also means that your editor can provide you with useful editing support.

However, having a type system doesn’t mean you need to explicitly define types for all the values. If you decide not to, Reason will figure out (infer) the types for you.

We’ll take advantage of the type system to define the types that we’ll use throughout our app. This will force us to think about the structure of our app before coding it and we’ll get a code documentation as a bonus.

If you’ve had any experience with TypeScript or Flow, Reason types will look familiar. However, unlike these two libraries, you don’t need any previous configuration at all (I’m looking at you Typescript). Types are available out of the box.

In Reason, we can distinguish between types and variant types (in short variants). Types are for example bool, string, and int. On the other hand, variants are more complex. Think of them as of enumerable sets of values—or more precisely, constructors. Variants can be processed via pattern matching, as we’ll see later.

type player =
  | Cross
  | Circle;

type field =
  | Empty
  | Marked(player);

Here we define player and field variants. When defining a variant, you need to use a type keyword.

Since we are building a Tic Tac Toe game, we’ll need two players. So, the player type will have two possible constructors — Cross and Circle.

If we think about the playing board, we know that each field type can have two possible constructors — either Empty or Marked by one of the players.

If you take a look at the Marked constructor, you can see that we are using it as a data structure. We use a variant to hold another piece of data. In our case, we pass it the player variant. This behavior is pretty powerful since it enables us to combine different variants and types together to create more complex types.

So, we’ve got the field variant. However, we need to define the whole playing board which consists of rows of fields.

type row = list(field);
type board = list(row);

Each row is a list of fields and the playing board is composed of a list of rows.

The list is one of Reason’s data structures—similar to the JavaScript array. The difference is, it’s immutable. Reason also has an array as a mutable fixed-length list. We’ll come back to these structures later.

type gameState = 
  | Playing(player)
  | Winner(player)
  | Draw;

Another variant we need to define is a gameState. The game can have three possible states. One of the players can be Playing, be a Winner, or we can have a Draw.

Now, we have all the types we need to compose the state of our game.

type state = {
  board,
  gameState,
};

Our component’s state is a record composed of the board and the gameState.

Before moving any further, I’d like to talk about modules. In Reason, files are modules. For example, we stored all our variants inside SharedTypes.re file. This code gets automatically wrapped inside the module like this:

module SharedTypes {
  /* variant types code */
}

If we wanted to access this module in a different file, we don’t need any import keyword. We can easily access our modules anywhere in our app using the dot notation — for example SharedTypes.gameState.

Since we are using our variants quite often, we can make it more concise by writing open SharedTypes at the top of the file in which we want to access our module. This allows us to drop the dot notation since we can use our module in the scope of our file.

Establishing state

Since we know how the state of our app will look, we can start building the game itself.

We’ve seen that our App component renders the Game component. This is the place where all the fun starts. I’ll walk you through the code step-by-step.

The App was a stateless component, similar to the functional component in React. On the other hand, the Game is a stateful one which means it can contain state and reducers. Reducers in Reason are based on the same principles as those you know from Redux. You call an action, and the reducer will catch it and update the state accordingly.

To see what’s going on in the Game component, let’s inspect the make function (the code is shortened).

let component = ReasonReact.reducerComponent("Game");

let make = _children => {
  ...component,
  initialState: () => initialState,
  reducer: (action: action, state: state) => ...,
  render: ({state, send}) => ...,
};

In the App component, we’ve overridden only the render method. Here, we are overriding reducer and initialState properties as well. We’ll talk about reducers later.

initialState is a function that (surprisingly) returns the initial state which we stored in a variable.

let initialState = {
  board: [
    [Empty, Empty, Empty],
    [Empty, Empty, Empty],
    [Empty, Empty, Empty],
  ],
  gameState: Playing(Cross),
};

If you scroll up a little bit and check our state type, you’ll see that the initialState has the same structure. It’s composed of the board that consists of rows of fields. At the beginning of the game all fields are Empty.

However, their status may change as the game goes on. Another part of the state is the gameState which is initially set to theCross player who plays first.

Rendering board

Let’s take a look at the render method of our Game component.

render: ({state, send}) =>
    <div className="game">
      <Board
        state
        onRestart=(_evt => send(Restart))
        onMark=(id => send(ClickSquare(id)))
      />
    </div>,

We already knew that it receives the self argument. Here, we use destructuring to access the state and the send function. This works just like in JavaScript.

The render method returns the Board component and passes it the state and two state handlers as props. The first one takes care of the app restart and the second one fires when the field gets marked by a player.

You might’ve noticed that we aren’t writing state=state when passing the state prop. In Reason, if we are not changing the prop’s name, we can pass prop using this simplified syntax.

Now, we can take a look at the Board component. I’ve omitted most of the render method for the time being.

let component = ReasonReact.statelessComponent("Board");

let make = (~state: state, ~onMark, ~onRestart, _children) => {
  ...component,
  render: _ =>
    <div className="game-board">
      /* ... */
    </div>,
};

The Board is a stateless component. As you might’ve noticed, the make function now takes several arguments. These are the props we’ve passed from the Game parent component.

The ~ symbol means that the argument is labeled. When calling a function with such an argument, we need to explicitly write the name of the argument when calling this function (component). And that’s what we did when we passed the props to it in the Game component.

You might’ve also noticed that we are doing another thing with one of the arguments — ~state:state. In the previous section, we defined our state type. Here, we are telling the compiler that the structure of this argument should be same as of the state type. You might know this pattern from Flow.

Let’s come back to the render method of the Board component.

Since we are dealing with lists there, we’ll talk about them a little bit more now, before inspecting the rest of the render method.

Excursion I: list and array

In Reason, we have two data structures resembling JavaScript arrays — list and array. The list is immutable and resizable, whereas the array is mutable and has a fixed length. We are using a list due to its flexibility and efficiency which really shines when we use it recursively.

To map a list, you can use List.map method that receives two arguments—a function and a list. The function takes an element from the list and maps it. This works pretty much like the JavaScript Array.map. Here’s a simple example:

let numbers = [1, 5, 8, 9, 15];
let increasedNumbers = List.map((num) => num + 2, numbers);
Js.log(increasedNumbers);  /* [3,[7,[10,[11,[17,0]]]]] */

What? You’re saying that the printed result looks weird? This is because the lists in Reason are linked.

Printing lists in your code can be confusing. Fortunately, you can convert it into an array using the Array.of_list method.

Js.log(Array.of_list(increasedNumbers));  /* [3,7,10,11,17] */

Let’s come back to our app and remind ourselves how our state looks.

let initialState = {
  board: [
    [Empty, Empty, Empty],
    [Empty, Empty, Empty],
    [Empty, Empty, Empty],
  ],
  gameState: Playing(Cross),
};

Inside the Board’s render method we first map over board which is composed of a list of rows. So, by mapping over it, we’ll gain access to the rows. Then, we render the BoardRow component.

let component = ReasonReact.statelessComponent("Board");

let make = (~state: state, ~onMark, ~onRestart, _children) => {
   ...component,
   render: _ =>
      <div className="game-board">
         ( 
            ReasonReact.array(
               Array.of_list(
                  List.mapi(
                    (index: int, row: row) =>
                     <BoardRow
                        key=(string_of_int(index))
                        gameState=state.gameState
                        row
                        onMark
                        index
                     />,
                   state.board,
                 ),
             ),
           )
        )
     /* ... */

We are using the List.mapi method, which provides us with an index argument that we need to uniquely define our ids.

When mapping the list to the JSX elements, we need to do two additional things.

First, we need to convert it to an array using Array.of_list. Secondly, we need to convert the result to the reactElement using ReasonReact.array, since we (as already mentioned) can’t simply pass the string to the JSX element like in React.

To get to the field values, we need to map over each row as well. We are doing this inside the BoardRow component. Here, each element from the row is then mapped to the Square component.

let component = ReasonReact.statelessComponent("BoardRow");

let make = (~gameState: gameState, ~row: row, ~onMark, ~index: int, _children) => {
   ...component,
   render: (_) =>
      <div className="board-row">
         (ReasonReact.array(
            Array.of_list(
               List.mapi(
                  (ind: int, value: field) => {
                    let id = string_of_int(index) ++ string_of_int(ind);
                    <Square
                       key=id
                       value
                       onMark=(() => onMark(id))
                       gameState
                    />;
                 },
               row,
             ),
          ),
        ))
    </div>,
};

Using these two mappings, our board gets rendered. You’ll agree with me that the readability of this code isn’t so good because of all the function wrappings.

To improve it, we can use the pipe operator which takes our list data and pipes it through our functions. Here’s the second mapping example — this time using pipe.

let component = ReasonReact.statelessComponent("BoardRow");

let make = (~gameState: gameState, ~row: row, ~onMark, ~index: int, _children) => {
   ...component,
   render: (_) =>
      <div className="board-row">
         (
            row
            |> List.mapi((ind: int, value: field) => {
               let id = string_of_int(index) ++ string_of_int(ind
               <Square 
                 key=id
                 value
                 onMark=(() => onMark(id))
                 gameState
               />;
             })
            |> Array.of_list
            |> ReasonReact.array
         )
      </div>,
};

This makes our code much more readable, don’t you think? First, we take the row and pass it to the mapping method. Then, we convert our result to an array. Finally, we convert it to the reactElement.

By mapping our board, we are rendering a bunch of Square components to the screen and by doing so, we are creating the whole playing board.

We’re passing a couple of props to the Square. Since we want our id to be unique, we create it by combining indices from both mappings. We are also passing down the value which contains the field type that can be either Empty or Marked.

Finally, we pass a gameState and the onMark handler which will get invoked when a particular Square is clicked.

Entering fields

let component = ReasonReact.statelessComponent("Square");

let make = (~value: field, ~gameState: gameState, ~onMark, _children) => {
  ...component,
  render: _self =>
    <button
      className=(getClass(gameState, value))
      disabled=(gameState |> isFinished |> Js.Boolean.to_js_boolean)
      onClick=(_evt => onMark())>
      (value |> toValue |> toString)
    </button>,
};

The Square component renders a button and passes it some props. We are using a couple of helper functions here, but I won’t talk about all of them in detail. You can find them all in the repo.

The button’s class is calculated using the getClass helper function which turns the square green when one of the players wins. When this happens, all the Squares will be disabled as well.

To render the button’s value, we use two helpers.

let toValue = (field: field) =>
  switch (field) {
  | Marked(Cross) => "X"
  | Marked(Circle) => "O"
  | Empty => ""
};

toValue will convert the field type to the string using pattern matching. We’ll talk about pattern matching later. For now, you need to know that we are matching the field data to our three patterns. So, the result would be X, O, or an empty string. Then, we use toString to convert it to the reactElement.

Phew. We’ve just rendered the game board. Let’s quickly recap how we did it.

Our top-level App component renders the Game component which holds the game state and passes it down along with the handlers to the Board component.

The Board then takes the board state prop and maps the rows to the BoardRow component which maps the rows to the Square components. Each Square has an onClick handler that will fill it with a square or a circle.

Make it do something already!

Let’s take a look at how our logic controlling the game works.

Since we have a board, we can allow a player to click on any square. When this happens, the onClick handler is fired and the onMark handler is called.

/* Square component */
<button
  className=(getClass(gameState, value))
  disabled=(gameState |> isFinished |> Js.Boolean.to_js_boolean)
  onClick=(_evt => onMark())>
  (value |> toValue |> toString)
</button>

The onMark handler got passed from the BoardRow component, but it was originally defined in the Game component that takes care of the state.

/* Game component */
render: ({state, send}) =>
    <div className="game">
      <Board
        state
        onRestart=(_evt => send(Restart))
        onMark=(id => send(ClickSquare(id)))
      />
    </div>,

We can see that the onMark prop is a ClickSquare reducer, which means we are using it to update the state (as in Redux). The onRestart handler works similarly.

Notice that we are passing square’s unique id to the onMark handler inside the BoardRow component.

/* BoardRow component */
(
  row
  |> List.mapi((ind: int, value: field) => {
    let id = string_of_int(index) ++ string_of_int(ind
    <Square 
      key=id
      value
      onMark=(() => onMark(id))
      gameState
    />;
   })
  |> Array.of_list
  |> ReasonReact.array
)

Before taking a look at our reducers in detail, we need to define actions to which our reducers will respond.

type action =
  | ClickSquare(string)
  | Restart;

As with the global variant types, this forces us to think about our logic before we start implementing it. We define two action variants. ClickSquare takes one argument that will have a type of astring.

Now, let’s take a look at our reducers.

let updateBoard = (board: board, gameState: gameState, id) =>
  board
  |> List.mapi((ind: int, row: row) =>
    row
      |> List.mapi((index: int, value: field) =>
        string_of_int(ind) ++ string_of_int(index) === id ?
          switch (gameState, value) {
          | (_, Marked(_)) => value
          | (Playing(player), Empty) => Marked(player)
          | (_, Empty) => Empty
          } :
          value
      )
  );

reducer: (action: action, state: state) =>
    switch (action) {
    | Restart => ReasonReact.Update(initialState)
    | ClickSquare((id: string)) =>
       let updatedBoard = updateBoard(state.board, state.gameState, id);
       ReasonReact.Update({
         board: updatedBoard,
         gameState:
            checkGameState3x3(updatedBoard, state.board, state.gameState),
       });
    },

The ClickSquare reducer takes an id of the particular Square. As we’ve seen, we are passing in the BoardRow component. Then, our reducer calculates a new state.

For the board state update, we’ll call the updateBoard function. It uses the same mapping logic we used in the Board and BoardRow component. Inside of it, we map over the state.board to get the rows and then map over the rows to get the field values.

Since the id of each square is a composition of ids from both mappings, we’ll use it to find the field which the player clicked. When we find it, we’ll use the pattern matching to determine what to do with it. Otherwise, we’ll leave the square’s value unmodified.

Excursion II: pattern matching

We use the pattern matching to process our data. We define patterns which we’ll match against our data. When exercising the pattern matching in Reason, we use a switch statement.

switch (state.gameState, value) {
  | (_, Marked(_)) => value
  | (Playing(player), Empty) => Marked(player)
  | (_, Empty) => Empty
}

In our case, we are using a tuple to represent our data. Tuples are data structures that separate data with commas. Our tuple contains the gameState and the value (containing the field type).

Then we define multiple patterns that we’ll match against our data. The first match determines the result of the entire pattern matching.

By writing an underscore inside the pattern, we are telling the compiler that we don’t care what the particular value is. In other words, we want to have a match every time.

For example, the first pattern is matched when the value is Marked by any player. So, we don’t care about the gameState and we don’t care about the player type either.

When this pattern is matched, the result is the original value. This pattern prevents players from overriding already marked Squares.

The second pattern addresses the situation when any player is playing, and the field is Empty. Here, we use the player type in the pattern and then again in the result. We are basically saying that we don’t care about which player is playing (Circle or Cross) but we still want to mark the square according to the player that is actually playing.

The last pattern acts as the default one. If the first or the second pattern isn’t matched, the third will always match. Here, we don’t care about the gameState.

However, since we’re checking for the Playing game state in the previous pattern, we are now checking for the Draw or Winner gameState type. If this is the case, we’ll leave the field Empty. This default scenario prevents players from continuing to play when the game is over.

A cool thing about pattern matching in Reason is that the compiler will warn you if you haven’t covered all the possible pattern matches. This will save you a lot of trouble, because you’ll always know if you’ve covered all the possible scenarios. So, if the compiler is not giving you any warnings, your pattern matching will never fail.

When the pattern matching is finished, the particular field gets updated. When all the mappings are done, we get a new board state and store it as the updatedBoard. We can then update the component’s state by calling ReasonReact.Update.

ReasonReact.Update({
  board: updatedBoard,
  gameState:
    checkGameState3x3(updatedBoard, state.board, state.gameState),

We update the board state using the result of the pattern matching. When updating the gameState, we call the checkGameState3x3 helper which calculates the state of the game for us.

Do we have a winner?

Let’s take a look what the checkGameState3x3 does.

First, we need to define all the possible combinations of winning fields (for the 3x3 board) and store them as winningCombs. We also have to define the winningRows type.

type winningRows = list(list(int));

let winningCombs = [
  [0, 1, 2],
  [3, 4, 5],
  [6, 7, 8],
  [0, 3, 6],  
  [1, 4, 7],
  [2, 5, 8],
  [0, 4, 8],
  [2, 4, 6],
];

We passed this list to the checkGameState function as the first argument.

let checkGameState3x3 = checkGameState(winningCombs);

By doing this, we are taking advantage of the currying principle. When we pass the winningCombs to the checkGameState function, we get back a new function waiting for the rest of the arguments to be passed. We store this new function as the checkGameState3x3.

This behavior is really helpful, since we are able to configure the checkGameState function depending on the width and height of the board.

Let’s see what’s going on inside the checkGameState function.

let checkGameState =
  (
    winningRows: winningRows,
    updatedBoard: board,
    oldBoard: board,
    gameState: gameState,
  ) =>
 oldBoard == updatedBoard ?
   gameState :
   {
     let flattenBoard = List.flatten(updatedBoard);
     let rec check = (rest: winningRows) => {
       let head = List.hd(rest);
       let tail = List.tl(rest);
       switch (
         getWinner(flattenBoard, head),
         gameEnded(flattenBoard),
         tail,
       ) {
       | (Cross, _, _) => Winner(Cross)
       | (Circle, _, _) => Winner(Circle)
       | (_, true, []) => Draw
       | (_, false, []) => whosPlaying(gameState)
       | _ => check(tail)
       };
    };
    check(winningRows);
};

First, we check if the board state is different from the previous one. If that’s not the case, we’ll return the unchanged gameState. Otherwise, we’ll calculate the new game state.

Calculating new states

We start determining our new game state by converting the board part of the state, which consists of a list of rows, to a simple list using List.flatten. The flattened result will have this kind of structure:

[Empty, Empty, Empty, Empty, Empty, Empty, Empty, Empty, Empty]

Back in the function, we define a check function that receives a single rest argument that has type of winningRows . The rec keyword before its definition means that it can be invoked recursively. However, for the recursive function calls, we need recursive data as well. Fortunately, the list is a recursive data structure.

We’ve already learned that lists in Reason are linked. This feature enables us to iterate through lists using recursion easily.

At the bottom of the checkGameState, we call the check function for the first time and pass it the winningCombs list. Inside the function, we extract the first element from the list and store it as the head. The rest of the list gets stored as the tail.

After that, we use the pattern matching again. We already know how it works, so I won’t go into detail. But it’s worth checking how we define our data and patterns.

type winner =
  | Cross
  | Circle
  | NoOne;

switch (
  getWinner(flattenBoard, head),
  gameEnded(flattenBoard),
  tail,
) { ...

Inside the switch statement, we use a tuple again to represent our data. Our tuple contains three elements—winner type as a result of the getWinner function, boolean as a result of the gameEnded function, and remaining list elements (tail).

Before going any further, let’s talk a bit about these two helper functions.

We’ll take a look inside the getWinner function first.

let getWinner = (flattenBoard, coords) =>
  switch (
    List.nth(flattenBoard, List.nth(coords, 0)),
    List.nth(flattenBoard, List.nth(coords, 1)),
    List.nth(flattenBoard, List.nth(coords, 2)),
  ) {
  | (Marked(Cross), Marked(Cross), Marked(Cross)) => Cross
  | (Marked(Circle), Marked(Circle), Marked(Circle)) => Circle
  | (_, _, _) => NoOne
  };

When we call the check recursive function for the first time, the head will be the first element of the winningRows, that is [0, 1, 2] which is a list. We pass head to the getWinner function as the coords argument along with the flattenBoard.

Again, we use the pattern matching with the tuple. Inside the tuple, we use the List.nth method to access the equivalent positions of the coords coordinates in the flattened board list. The List.nth function takes a list and a number and returns the list’s element to that position.

So, our tuple consists of the three winning coordinates of our board that we’ve accessed using List.nth.

Now, we can match our tuple data against the patterns. The first two patterns check if all three fields are marked by the same player. If they are, we’ll return the winner — Cross or Circle. Otherwise, we’ll return NoOne.

Let’s see what’s going on inside the gameEnded function. It checks if all the fields are Marked and returns a boolean.

let gameEnded = board =>
  List.for_all(
    field => field == Marked(Circle) || field == Marked(Cross),
    board,
  );

Since we know what values can be returned from our helper functions, let’s come back to our check function.

switch (
  getWinner(flattenBoard, head),
  gameEnded(flattenBoard),
  tail,
  ) {
  | (Cross, _, _) => Winner(Cross)
  | (Circle, _, _) => Winner(Circle)
  | (_, true, []) => Draw
  | (_, false, []) => whosPlaying(gameState)
  | _ => check(tail)
  };

Our pattern matching can now determine if the game ended in a win or draw. If these cases are not matched, we’ll move to the following case. If it’s matched, the game will continue and the whosPlaying function will be called, and the other player will take a turn.

let whosPlaying = (gameState: gameState) =>
  switch (gameState) {
  | Playing(Cross) => Playing(Circle)
  | _ => Playing(Cross)
  };

Otherwise, we’ll call the check function recursively with a new combination of winning fields.

That’s it. Now you know how our code controlling the game logic works.

That’s all folks!

I hope this post helped you to understand the core features of this promising and still-developing language. However, to fully appreciate the power of this new syntax on top of OCaml, you need to start building your own stuff. Now you’re ready to do that.

Good luck!

If you liked this article, give it a few claps. I would greatly appreciate it and more people will be able to see this post as well.

This post was originally published on my blog.

If you have any questions, criticism, observations, or tips for improvement, feel free to write a comment below or reach me via Twitter.