DEV Community: Victor N.

From object-oriented JS to functional ReScript

Victor N. — Mon, 06 Dec 2021 14:55:09 +0000

This article might be easily titled:

From object-oriented C++ to functional Haskell
From object-oriented C# to functional F#
From object-oriented Python to functional OCaml
etc

The main idea is to show how OOP (Object Oriented Programming) concepts can be projected to FP (Functional Programming) while accomplishing the same tasks. It’s always good to base on specifics for the sake of an example. So, I’ve chosen the JavaScript vs. ReScript combo for the illustration because these are the languages I use the most currently.

I’m expecting you’re a developer familiar with JS who uses objects, their methods, and properties regularly. Not sure, you are creating your own classes to get things done, but definitely use objects from third-party libraries, feel what myObj.foo.func() means, seen that “Boom! undefined is not a function” for many times, and maybe even never thought if you might do things another way.

Destructuring Object-Oriented Programming

OOP is a programming paradigm. It is a synthetic concept that offers a way to structure your program. You know, OOP is ubiquitous: most popular programming languages allow or enforce to structure programs and libraries this way.

However, objects are not the only way of programming and are definitely not a silver bullet solution to all problems. Objects were proven to have downsides: composability issues, implicit state dependencies, monolithness, and others. One possible alternative is the functional programming paradigm.

And what does that “functional” mean in practice? I’m going to break down OOP into parts, see what problems they are intended to solve and try to find a functional programming way to do the similar. The parts I’m referring to are:

encapsulation
abstraction
inheritance
polymorphism

Part 1: Encapsulation

Encapsulation, arguably, the most recognized part of OOP. It is that dot (.) allowing you to drill down the objects to obtain a value you want or a method you are going to call.

Formally speaking, encapsulation is an ability to:

group related data and functions within a single thing (known as object);
using a reference to the object, access to the data (known as fields);
using a reference to the object, call its functions to operate over the data (known as methods).

Many languages extend the concept with things like “properties” (fields that are methods actually, aka getters/setters), “events” (fields that are arrays of callback function pointers actually), and other features. Still, it does not change the big picture.

To illustrate encapsulation, let’s make some burgers with JavaScript.

class Burger {
  constructor(title) {
    // Add a field `layers` to burger objects
    // Let it be an array of layer objects
    // Arrays are by themselves objects too having methods `push`, `splice`, etc;
    // so, we have a nested hierarchy of objects here
    this.layers = [];
    this.layers.push(new BreadRoll());
    this.layers.push(new BeefPatty());
    this.layers.push(new BreadRoll());

    // Another field to hold a menu title
    this.title = title;
  }

  // Provide a method to further build a burger
  addLayer(layer) {
    // access the array method and its `length` property through `this` reference
    // to insert a new layer right before the last bread roll
    this.layers.splice(this.layers.length - 1, 0, layer);
  }
}

// Construct a couple of different burgers using the class we’ve just defined
let cheeseburger = new Burger("Cheeseburger");
cheeseburger.addLayer(new Cheese());

let kingburger = new Burger("Special King Burger");
kingburger.addLayer(new SecretSauce());
kingburger.addLayer(new Cheese());
kingburger.addLayer(new Onion());
kingburger.addLayer(new Tomato());

We’ve built (an oversimplified) system to describe burgers as objects. Now, we can pass Burgers around an app to compute prices, show menu, take orders, manage a cooking queue, and so on.

OK, and if we make an app using the functional programming paradigm, how will the code look? Most FP languages, including ReScript, lack the concept of classes along with their props and methods at all. Functional languages strictly separate data from behavior and algorithms. Data and functions are the bread and butter of functional programming, with a clear point stating that bread ≠ butter. Given that, let’s start with a definition of the data we operate upon:

// === Burger.res ===

type t = {
  title: string,
  layers: array<Layer.t>,
}

Here we define a new type that groups all the data related to burgers. The type is a record with two fields to model our burgers. It’s that simple. No methods, no indirection, no funky syntax: just what a JS programmer would call a “plain old JavaScript object.”

The t name is a ReScript convention for a type describing the primary data type of the current module. It’s handy because you can then fluently refer to such types from other modules like this: Burger.t, Layer.t, Order.t, etc.

We’ve got data; let’s move on to the behavior, that is, to the functions. First, we’re going to add a constructor for our type. A user of Burger.t might easily create a new instance directly by specifying all the fields one by one:

let myBurger = {
  title: "My personal burger",
  layers: [],
}

…but following the same logic as in the JavaScript example, let’s pre-populate layers with a very basic ingredient stack:

// === Burger.res ===

type t = {
  title: string,
  layers: array<Layer.t>,
}

let make = title => {
  title: title,
  layers: [
    Layer.BreadRoll,
    Layer.BeefPatty,
    Layer.BreadRoll,
  ]
}

Again, nothing fancy here. Constructors are just regular functions conventionally named make or makeBlahBlahBlah. Our constructor takes a string as a parameter and returns a new Burger.t.

The final bit is our addLayer function:

// === Burger.res ===

type t = {
  title: string,
  layers: array<Layer.t>,
}

let make = (title) => {
  title: title,
  layers: [
    Layer.BreadRoll,
    Layer.BeefPatty,
    Layer.BreadRoll,
  ]
}

let addLayer = (burger, layer) =>
  switch burger.layers->ArrayX.last {
  | Some(last) =>
    // put the layer before the last one (which is a bread roll)
    let first =
      burger.layers
      ->Array.slice(~offset=0, ~len=burger.layers->Array.length - 1)

    // list new layers
    {
       ...burger,
       layers: Array.concatMany([first, [layer], [last]]),
    }
  | None =>
    // hmmm... someone messed up with layers, let it be a burger
    // of one ingredient
    { ...burger, layers: [layer] }
  }

Now a developer can use our system:

let kingburger = Burger.make("Special King Burger")
  ->Burger.addLayer(SecretSauce)
  ->Burger.addLayer(Cheese)
  ->Burger.addLayer(Onion)
  ->Burger.addLayer(Tomato)

These two previous snippets are pretty simple but carry so many essential details of FP and ReScript in particular. Let’s look at them one by one.

Pipes

The -> operator in ReScript is known as a fast pipe. It’s a syntax sugar over regular function call that puts the value on the left-hand side as the first argument of the function on the right-hand side. The following are equivalent:

myBurger->Burger.addLayer(Cheese)
Burger.addLayer(myBurger, Cheese)

Thanks to the fast pipe, working with data almost feels like working with objects in OOP using its dot-notation. But in contrast to OOP, accessing “object” (data), “methods” (compatible functions) is not a unique language mechanic; it’s an alternative syntax of the good old plain function call. The “object” (the one with type t) is conventionally passed as the first argument explicitly. Beautiful, eh?

No methods, no monkey-patching

In the kingburger construction pipeline above, you might be caught on the repetition of Burger., Burger., Burger.. These qualifiers are a direct consequence of the fact that -> is just a function call; it’s not something that belongs to the “object.” We have to tell ReScript the module name where the functions are defined, thus the module prefix on every step.

It might look annoying, but in practice, it’s beneficial. First, when you read code, you can easily follow the most complex processing pipelines without guessing what type a method returns and where to find a class with such a method: the code is much more self-documenting. Second, such (ugly) things as object monkey-patching or polyfills are just irrelevant in ReScript: if you miss a “method” on an “object” you don’t control, go ahead and write the desired new function in a module you do control and use it.

Note, in the example above I used ArrayX.last to get the last element of an array. The Array module of the standard ReScript library does not include such a function, but I find it handy in this project. So I’m free to create a module (say, ArrayX) and add whatever array utilities I find useful (e.g., ArrayX.last). There are no agonies of choosing whether I should monkey-patch the built-in Array object, inherit a new Array class, or keep utilities in a module and have code with mixed method/function calls.

In the same way, even if I were given the Burger module as a library, I could extend it:

// === BurgerPreset.res ===

let addVegiLayers = burger =>
  burger
  ->Burger.addLayer(Onion)
  ->Burger.addLayer(Tomato)
  ->Burger.addLayer(Cucumber)
  ->Burger.addLayer(Salat)

and use the new “method” afterthen:

let freshburger = Burger.make("Double Fresh Burger")
  ->Burger.addLayer(SecretSauce)
  ->BurgerPreset.addVegiLayers
  ->Burger.addLayer(BeefPatty)
  ->Burger.addLayer(Cheese)

In case you’re still too annoyed, ReScript offers two possible shortcuts:

// Opening a module brings all its functions
// to the scope of the current one
open Burger

// Module aliases useful for more compact code
// still leaving the trails to the origin
module BP = BurgerPreset

let freshburger = make("Double Fresh Burger")
  ->addLayer(SecretSauce)
  ->BP.addVegiLayers
  ->addLayer(BeefPatty)
  ->addLayer(Cheese)

Immutable data

Although nothing in the OOP paradigm forces you to change the values of objects’ fields, this is the default way to do the job when using classes. A method accesses fields of this instance and changes their values. Or it calls another method on the nested child object that changes its values, etc. In other words, OOP traditionally mutates data associated with objects on method calls.

In contrast, the default way in FP languages is to hold on to data that never changes, the immutable data. If you want to change the value of one field, you don’t. Instead, you clone the data you want to change, keeping values for everything the same, except for the fields you want to change. Retake a look at our topping function:

let addLayer = (burger, layer) =>
  switch burger.layers->ArrayX.last {
  | Some(last) =>
    let first =
      burger.layers
      ->Array.slice(~offset=0, ~len=burger.layers->Array.length - 1)

    // 👇 Clone!
    {
       ...burger,
       layers: Array.concatMany([first, [layer], [last]]),
    }
  | None =>
    // 👇 Clone!
    { ...burger, layers: [layer] }
  }

The ... operator in ReScript clones a record copying all values over, except for the fields specified explicitly. So, the addLayer function takes a burger, makes a new one which looks exactly like the original but with the additional layer, then throws the original one to a trash bin. I’d say it’s the direct opposite of OOP encapsulation, and this is the authentic way of FP.

let kingburger =
  Burger.make("Special King Burger") // make burger #1
  ->Burger.addLayer(SecretSauce) // make burger #2, throw away #1
  ->Burger.addLayer(Cheese) // make burger #3, throw away #2
  ->Burger.addLayer(Onion) // make burger #4, throw away #3

Yes, I know, it’s strange to throw away a burger and make a new one from scratch just to add a slice of cheese. Gordon Ramsay probably didn’t get it, so he failed to become a programmer (that’s good, actually). However, immutability has a massive effect on programs' simplicity and reliability for us, developers. Working with immutable data structures, you don’t even touch the problem of a shared state which is the source of so many bugs. Before changing a field, you don’t think which other system parts you can affect and how they will behave after that. You don’t think about inconsistent and incomplete data updates in a multithreading environment. You don’t think about orphan nested objects. You just don’t have to think broader than the function you’re writing or reviewing. Immutable data reduces so much stress.

Everything has a cost, and the cost of immutability is performance. But the performance isn’t hit to an extent you might imagine. With guarantees of recursive immutability, creating a clone of a complex and deeply nested object is effectively done by creating one shallow copy at the outermost nesting level. All nested objects are reused in the copy because they cannot change anyway. So, cloning is cheap in most cases.

And when absolutely required, ReScript offers escape hatches. Namely, the mutable keyword can be applied to a record field declaration. Also, the standard library provides some in-place modification functions for potentially heavy operations. Such functions are explicitly named with caution (for example, stableSortInPlaceBy) and return unit (that is, “nothing”) to forbid further pipeline-style processing that could introduce implicit mutable dependencies. When you’re in the danger zone of conventional chaotic imperative programming, ReScript shows this apparently at the level of the language syntax and standard library design.

No null references

Not obviously related to object-oriented programming or encapsulation in particular, there’s a curse in programming familiar to every developer. The billion-dollar mistake, the null reference. Yes, null pointers were introduced way before OOP, but I’m sure mainstream OOP languages like C++, Java, C#, then JavaScript ultimately escalated the problem to a historical extent. That’s because OOP is built around the concept of objects and that objects should be passed around somehow every time. They are passed by reference (aka pointer) and the actual object behind this reference can be—well—the real object, or it can be a bomb which will crash the program once touched 🍔💥

ReScript makes “undefined is not a function” impossible. Let’s take a look at our function one more time:

let addLayer = (burger, layer) =>
  switch burger.layers->ArrayX.last {
  | Some(last) =>
    let first =
      burger.layers
      ->Array.slice(~offset=0, ~len=burger.layers->Array.length - 1)

    {
       ...burger,
       layers: Array.concatMany([first, [layer], [last]]),
    }
  | None =>
    { ...burger, layers: [layer] }
  }

First, because ReScript has no null references, you can be 100% sure that the arguments (burger and layer) are indeed valid data values, neither can be null/undefined. So the program will never crash operating on burger.layers. Also, the layers array can never accidentally get a null layer that will be a time bomb ready to explode later. Beef, tomato, null, cheese, anyone?

Next, ReScript makes the possibility of an error obvious using one of the idiomatic functional programming mechanics. For example, in our case, ArrayX.last returns an option that can be some value or none if the array is empty. It sounds similar to what JavaScript does anyway, but there’s a vital difference. You are forced to check both outcomes; otherwise, ReScript compiler barks on you with an error.

Ironic enough, this enforcement made it apparent that the same function implemented earlier in JavaScript is incorrect: it won’t add anything if a burger object has no layers. It should not happen in our simplistic model but inevitably will occur in a real system during its evolution.

Again, there are escape hatches for the cases when you know what you do. ReScript has exceptions and unsafe routines when they are necessary. Such functions are conventionally named with precautionary suffixes like lalaExn, lalaUnsafe to warn you about the slippery floor.

Part 2: Abstraction

Abstraction is an OOP feature allowing you to hide implementation details of an object. You’re given an abstraction along with a well-defined interface, and you use it through this interface without thinking how it works under the hood. Let’s see again at our JavaScript class:

class Burger {
  constructor(title) {
    this.layers = [];
    this.layers.push(new BreadRoll());
    this.layers.push(new BeefPatty());
    this.layers.push(new BreadRoll());
    this.title = title;
  }

  addLayer(layer) {
    this.layers.splice(this.layers.length - 1, 0, layer);
  }
}

let cheeseburger = new Burger("Cheeseburger");
cheeseburger.addLayer(new Cheese());

It’s transparent that any object of type Burger has a field named layers, and that field is an array. It’s not obvious though, if I’m, as an object user, allowed to tweak or even access this field directly. After all, nothing can stop me from messing up layers:

cheeseburger.layers.shift();

Now we have a burger without bread on the bottom, which is unacceptable for our app. To solve the problem, OOP languages allow hiding some fields and methods of an object, making them private for the outside world. C++, C#, Java have class member keyword specifiers; Python, JavaScript recommend following a convention of starting private property names from an underscore _. Modern JS also allows using hash # prefix to mark a field private, so we’d better define our class this way:

class Burger {
  #layers;

  constructor(title) {
    this.#layers = [];
    this.#layers.push(new BreadRoll());
    this.#layers.push(new BeefPatty());
    this.#layers.push(new BreadRoll());
    this.title = title;
  }

  addLayer(layer) {
    this.#layers.splice(this.#layers.length - 1, 0, layer);
  }
}

let cheeseburger = new Burger("Cheeseburger");
cheeseburger.addLayer(new Cheese());
cheeseburger.#layers.shift(); // error!

Now, no one outside the Burger methods can shuffle the layers. It’s better protected from entering an invalid state now.

Can we hide implementation details in functional programming as well? Easy. Not talking about all FP languages, ReScript has a couple of features that perfectly solve the problem. They are:

interface files / module signatures
opaque types

Earlier in the article, we implemented a Burger module in the Burger.res source file. Now we can add a Burger.resi file next to Burger.res to define the API of this module, effectively limiting how a consumer can use the module from the outside world:

// === Burger.resi ===

type t

let make: string => t
let addLayer: (t, Layer.t) => t

Note that we declared the t type in this interface file but didn’t provide any details of its underlying structure. That is an opaque type. Having this restriction, a user can’t create arbitrary data values, possibly violating business rules. The only way to make a new burger now is the make function: you give it a string (the title), you get your burger. Likewise, we declare the signature of addLayer function.

If we’d add a new function, constant, type definition, or whatever to the Burger.res implementation file now, they won’t be available anywhere outside of the Burger module. You must also add them to the interface file to express the public “export” intent.

In the example, we’ve created a module and then declared its interface. In practice, most of the time, I do the reverse: first, create an interface, and only after that write down the implementation. Focusing on the interface rather than implementation details at the first step forces you to imagine and design the best and cleanest API for your mini-library (consider modules are mini-libraries). And only after the well-shaped framework is ready, you complete it with minimally required implementation. Such workflow automatically makes you follow KISS and YAGNI principles.

Now we’ve hidden all the details behind a module signature. I’d say we’ve hidden too much. It’s no longer possible to get a burger name or layers put so far. Let’s fix it and evolve our signature:

// === Burger.resi ===

type t

let make: string => t

// We don’t allow a burger to be renamed after construction,
// but of course, we provide a way to get the given name
let title: t => string

// Get all layers. As long as we follow immutability requirements,
// do whatever you want with the result, it won’t affect the
// underlying burger data
let layers: t => array<Layer.t>

let addLayer: (t, Layer.t) => t

A simple and clear API, isn’t it? It’s time to fill the gaps in the implementation, and that’s trivial:

// === Burger.res ===

/* ... */

let title = burger => burger.title
let layers = burger => burger.layers

I found this pattern of making all record types opaque and publishing just a minimal set of data getters/updaters super-typical for domain objects modeling. With only techniques shown up to this point, you can go very far, and probably your app does not require anything further.

Part 3: Inheritance

OOP offers a mechanism of class extension when a new class declares it is based on some other class. In this case, the derived class inherits all the properties and methods of the base class, then adds new stuff over this base. So, whenever we have several classes derived from the same base, we can be sure they all provide the goodness declared in the base class.

Inheritance expresses the “is a” relation:

Button is a UI Component
Cat is an Animal
Car is a Vehicle

In our restaurant app, besides burgers, we could also serve cocktails. They both, burgers and cocktails, should be present in a menu where’s it is required to show their title, photo, and price. That title, photo, and price are properties they have in common because any such object “is a” product. However, the construction procedure differs; hence we have different object classes. Here’s a possible class hierarchy:

In JavaScript, the hierarchy could be expressed like this:

class Product {
  ##hhDiscount;

  constructor(imageUrl, price, hhDiscount, title) {
    this.imageUrl = imageUrl;
    this.price = price;
    this.#hhDiscount = hhDiscount;
    this.title = title
  }

  discountForHappyHour() {
    this.price *= 1 - this.#hhDiscount;
  }
}

class Burger extends Product {
  constructor(imageUrl, price, hhDiscount, title) {
    super(imageUrl, price, hhDiscount, title);
    // ... add the basic layers ...
  }

  addLayer(layer) {
    // ...
  }
}

class Cocktail extends Product {
  constructor(imageUrl, price, hhDiscount, title) {
    super(imageUrl, price, hhDiscount, title);
  }

  mix(drink, volume) {
    // ...
  }
}

Now, given a list of products, whether burgers or cocktails, a system can render a menu using the common fields and the method to compute a happy-hour price.

The traditional question: how can I express inheritance in a functional programming paradigm? You don’t! Inheritance, like most practices in programming, is an ephemeral concept. You don’t inherit classes for the sake of inheritance; you’re trying to solve problems. And the problem inheritance tries to solve is providing a common ground across different entities. Let’s focus on that.

OOP has a proven principle that any inheritance can be replaced with composition. This is useful because, in general, FP languages have no common inheritance mechanisms, but the composition is something built into their DNA. So, to the practice, how can we express Product, Burger, and Cocktail in ReScript to render a menu of available items and keep the difference in construction? Bonus obstacle to overtake JS OOP inheritance: we already have the Burger module from above, we are happy with it, we don’t want to change anything there.

First, let’s model our menu render service:

// === Menu.resi ===
let render: array<Product.t> => Image.t

OK, we need a product, here it is:

// === Product.resi ===
type t
let make:
  (
    ~title: string,
    ~imageUrl: string,
    ~price: Money.t,
    ~discount: float,
  ) => t

let title: t => string
let imageUrl: t => string
let price: t => Money.t
let happyHourPrice: t => Money.t

Good. But isn’t the product is too abstract? Yep, we’ve lost any traces of what the item is and how it is constructed. Let’s fix it:

// === Product.resi ===
type t

type kind =
  | Burger(Burger.t) // 100% reuse
  | Cocktail(Cocktail.t)

let make:
  (
    ~title: string,
    ~imageUrl: string,
    ~price: Money.t,
    ~discount: float,
    kind: kind,
  ) => t

let title: t => string
let imageUrl: t => string
let price: t => Money.t
let happyHourPrice: t => Money.t
let kind: t => kind

Here I use the thing any FP language provides: an algebraic data type (ADT), known as variant in ReScript. It’s a straightforward yet powerful concept. A value of a variant is strictly one of the enumerated cases along with the payload value(s) specified in parens. In this case, the product kind can be either a Burger with Burger.t payload we’ve implemented earlier or a Cocktail with Cocktail.t payload.

Now, whenever I deal with a value of Product.kind type, I’m forced to explain all the variants to the compiler, otherwise it will bark on me:

let isAllowedBefore18 = prodKind =>
  switch prodKind {
  | Burger(_) => true
  | Cocktail(c) => !(c->Cocktail.containsAlcohol)
  }

To recap, what was the fuss all about? To abstract burgers and cocktails enough so that the Menu module could render a nice menu image for our restaurant without thinking much about what particular item is actually. Can we do it now? Definitely!

let cheeseburger = Burger.make()->Burger.addLayer(Cheese)
// ... other instnances ...

// Most likely these would come from a DB,
// but many great things start with hardcode :)
let summerMenu = [
  Product.make(
    ~title="Cheeseburger",
    ~imageUrl="https://example.com/f562e1f4.jpg",
    ~price=2.95->Money.eur,
    ~discount=0.5,
    Burger(cheeseburger)
  ),
  Product.make(
    ~title="Holy King Burger",
    ~imageUrl="https://example.com/ab1a63a0.jpg",
    ~price=4.95->Money.eur,
    ~discount=0.5,
    Burger(holyburger)
  ),
  Product.make(
    ~title="Nonlynchburg Lemonade",
    ~imageUrl="https://example.com/b585a3c4.jpg",
    ~price=1.95->Money.eur,
    ~discount=0.25,
    Cocktail(lemonade)
  ),
  Product.make(
    ~title="B52",
    ~imageUrl="https://example.com/8a5066aa.jpg",
    ~price=3.95->Money.eur,
    ~discount=0,
    Cocktail(b52)
  ),
]

Menu.render(summerMenu)->Team.sendToReview

If I were reading this text 10-15 years ago, I would complain: “— Bullshit! It’s hardcode! The generalized entity has to know all the concrete specifications, inflexible, cannot work!” The reality is that you can’t create an abstraction over an abstraction within an abstraction to model everything in the world. The actual business requirements evolve and show our mental models of classifying things become wrong at some point most of the time.

The good news is the world is simple, actually! If you know you’re making software to manage burgers and cocktails only (OK, a product owner would add maybe appetizers and salads later), it’s perfectly OK to be explicit about it. If you know there will be hundreds of product kinds, go ahead and inverse the structure: let the specific types provide a ProductDescription instead of keeping specific types inside a Product. Be flexible, yet simple!

And again, for the most complex scenarios, ReScript offers effective mechanisms like module functors to do metaprogramming. I don’t want to touch them in this article. They can make miracles more impressive than OOP tricks. And if you’d apply them just for a case, your code will become a hocus-pocus: fun for your mates, less fun to solve the problems. Everything has pros and cons.

Part 4: Polymorphism

The last pillar of OOP is subtyping polymorphism also known as virtual methods or inherited methods overloading. The purpose is the following. You can be given a reference to an object that you think is an instance of some class (let’s call it Base) and call its method (e.g. doJob). But under the cover—and you neither know it nor want to know—this object can have a type of another class inherited from the Base (let’s call it Derived). In this case, instead of the code defined in Base.doJob, the program will execute the code of Derived.doJob.

Before C-style classes came to JavaScript in ES6, I would say web devs rarely used OOP polymorphism because the JS-native prototype chain inheritance is too brain-bending for a casual developer. However, it was always a casual tool in other languages to delegate and split various problems. Now it is in JS as well. Imagine generating a minimalistic HTML menu for a given product list. The JavaScript code might be:

class Product {
  /* ... */

  // Returns an HTML snippet to render a minimalistic
  // menu item in the following style:
  //
  // ***
  // Classic Omelet
  // (Eggs, Cheese, Onion, Parsley)
  // ***

  menuItemHtml() {
    return [
      "<dt>",
      this.title,
      "</dt>",
      "<dd>",
      "(",
      this.ingredientsString(),
      ")",
      "</dd>",
    ].join("\n");
  }

  ingredientsString() {
    return "Chef recipe";
  }
}

class Burger extends Product {
  /* ... */

  ingredientsString() {
    return (
      this
      .layers
      // exclude bread on the top and bottom as implied
      .slice(1, -1)
      .map(l => l.title)
      .join(", ")
    );
  }
}

class Cocktail extends Product {
  /* ... */

  ingredientsString() {
    return (
      this
      .drinks
      .map(d => d.title + " " + d.volume + "ml")
      .join(" / ")
    );
  }
}

function menuHtml(products) {
  return [
    "<dl>",
    products.map(p => p.menuItemHtml()),
    "</dl>"
  ].join("\n");
}

Here we have the ingredientsString method, which is polymorphic. It should give the customer an idea of what he orders. The method can be used on its own, but in particular, it is called by the base class Product.menuItemHtml to generate the whole menu item markup used elsewhere while menu rendering. The trick with polymorphism is handy because the final result for burgers and cocktails is similar but different in detail. And method overloading can express this requirement in OOP.

How can we express such polymorphism in ReScript? You know the answer: “we don’t!” Again, polymorphism is a synthetic concept employed to solve particular problems, not to use polymorphism on its own, right? All we need is to solve the given problem using the tools available. Variants to the rescue again! I even think it’s too similar to dealing with inheritance to the point of boring:

// === Product.res ===

/* ... */

// Yes, boring dispatching based on the product kind
let ingredientsString = product =>
  switch product->kind {
  | Burger(b) => b->Burger.ingredientsString
  | Cocktail(c) => c->Cocktail.ingredientsString
  }

let menuItemHtml = product =>
  [
    "<dt>",
    product->title,
    "</dt>",
    "<dd>",
    "(",
    product->ingredientsString,
    ")",
    "</dd>",
  ]
  ->Js.Array2.joinWith("\n");

And our burger:

// === Burger.res ===

/* ... */

let ingredientsString = burger =>
  burger
  ->layers
  ->Array.slice(~offset=1, ~len=burger.layers->Array.length - 2)
  ->Array.map(Layer.title)
  ->Js.Array2.joinWith(", ")

And cocktails:

// === Cocktail.res ===

/* ... */

let ingredientsString = cocktail =>
  cocktail
  ->drinks
  ->Array.map(
    ((drink, volume)) =>
      Drink.title ++ " " ++ volume->Volume.value(#ml) ++ "ml"
  )
  ->Js.Array2.joinWith(" / ")

Boring? Well, yes. Unscalable? Not quite. Of course, when you have a dozen virtual methods, it could become tedious to add switch-based dispatching again and again. However, I cannot remember a single case when this particular point became boilerplate. First, it’s rare to have a really wide inheritance graph with all classes having their very specific method implementations: in most cases, they are all the same, and only 1 of 10 has something uncommon to say. Second, suppose you absolutely want inheritance polymorphism without dispatch boilerplate. In that case, ReScript offers module functors and first-class modules to achieve it, and I’m still ignoring them in the article because they are ninja-weapon for other issues, I bet it. Third…

Which came earlier: the chicken or the egg? In our case, both should also know about HTML. So the question is going to expand! Which came earlier: the chicken, the egg, or the HTML?! What the hell should an egg think about its presentation on a menu? Should an egg be an expert in HTML, or maybe in PDF or SVG? Hell, no! For so many times, I saw objects that were too smart about the context they live in as I’m giving a high five to the famous quote.

Because the problem with object-oriented languages is they’ve got all this implicit environment that they carry around with them. You wanted a banana but what you got was a gorilla holding the banana and the entire jungle.
—Joe Armstrong, creator of Erlang programming language

The subtyping polymorphism is a beautiful idea that often does not sustain real-world requirements. In the example above, I’d group stuff related to the HTML-menu generation to a separate module leaving the essence untouched.

// === HtmlMenu.res ===

// Hmm… not so dull. All rendering in a single place.
// This module is self-sufficient for solving the rendering problem.
// The original modules are free to remain dumb.

let ingredientsString = product =>
  // A potentially long switch that nevertheless allows you to imagine
  // and compare the outcome of different kinds of products
  switch product->kind {
  | Burger(b) =>
    b
    ->layers
    ->Array.slice(~offset=1, ~len=b.layers->Array.length - 2)
    ->Array.map(Layer.title)
    ->Js.Array2.joinWith(", ")
  | Cocktail(c) =>
    c
    ->drinks
    ->Array.map(
      ((drink, volume)) =>
        Drink.title ++ " " ++ volume->Volume.value(#ml) ++ "ml"
    )
    ->Js.Array2.joinWith(" / ")
  }

let make = products =>
  [
    "<dt>",
    product->Product.title,
    "</dt>",
    "<dd>",
    "(",
    product->ingredientsString,
    ")",
    "</dd>",
  ]
  ->Js.Array2.joinWith("\n");

Now, everything related to the HTML menu is nicely grouped in a dedicated module. Easy to read, easy to reason about, easy to change.

What’s wrong with OOP

Nothing. It is overpriced, though. OOP is given to us as a universal solution to all problems in mainstream development. Sure, you can go arbitrarily far just sticking to object-oriented patterns. The question is efficiency and development experience. Besides OOP, other worlds do exist. I’m not saying they are perfect, but we deserve to know the options. Luckily, alternative concepts leak into the mainstream world from time to time and become famous. Take React, for example; I’d say it is an object-oriented antipode; it differs a lot from UI frameworks that were popular before. I’m glad it got traction.

The same is about ReScript. It’s a practical language for real-world development, albeit with a (relaxed) functional paradigm. ReScript also has lightweight JavaScript interop, so it’s easy to mix ReScript parts into an existing JS codebase and vice versa. Take your scale: if your wants for code reliability, simplicity, and robustness overweight the risk of employing new technology, give a chance to the functional programming with ReScript. BTW, I’m not affiliated with the ReScript team anyhow; I’m just a humble, proud user 😌

Cross-posting. This post was originally published at https://fullsteak.dev/posts/from-oop-javascript-to-functional-rescript

ReScript JSON Typed Strongly

Victor N. — Tue, 02 Nov 2021 19:37:56 +0000

As a follow-up to the “Full stack ReScript” post, I’d like to zoom in on an architectural layer that was intentionally omitted in that article to avoid focus blurring. Namely, the layer responsible for making strongly-typed and business-valid domain objects out of bits and bytes coming over the wire.

More generally, how can we deserialize raw data provided as JSONs (or XML, or Protobuf, or whatever) into domain objects that make sense for the business logic and serialize them back?

Go cooking! Imagine we’re making a cookbook application and have domain objects describing recipe ingredients. The app should be smart, allowing users to adjust the number of portions they want to cook.

// === RecipeDomain.resi ===

module Quantity: {
  type units = [
    | #pc // pieces
    | #tsp // tea spoon
    | #tbsp // table spoon
    | #cup // half a pint
    | #ml
    | #l
    | #g
    | #kg
    | #oz
    | #lb
    | #clove
  ]

  type t

  let make: (float, units) => t

  /* Multiplies value by the given factor */
  let scale: (t, float) => t

  let rawValue: t => (float, units)

  /* Rounds value to nearest 1, ½, ⅓, or ¼ and converts
   units to more appropriate if possible */
  let humanValue: (t, [#us | #metric]) => (float, units)
}

module Ingredient: {
  type t
  let make: (string, Quantity.t) => t
  let product: t => string
  let quantity: t => Quantity.t
}

module IngredientList: {
  type t

  let make: (array<Ingredient.t>, ~numberOfPortions: int) => t
  let all: (t, ~numberOfPortions: int) => array<Ingredient.t>
  let originalNumberOfPortions: t => int
}

While building our front-end app prototype, we work in this cozy land of business domain objects. At some moment we need to save the user’s recipe somewhere and be able to load it later. It might be our back-end or browser local storage. Can we pass IngredientList there as is? The general answer is “no” because wire, file, and browser storage require a continuous sequence of bytes. In contrast, our domain object runtime presentation is unknown and is unlikely to be sequential in RAM.

Well, technically you can use IngredientList almost as is, as long as you’re developing in ReScript. It compiles to JavaScript, and JS objects ≈ JSON objects that trivially serialize into strings. But such way would be too fragile and unsafe 🤞

If the internal presentation of any domain object model changes, you break backward compatibility
If data comes from an untrusted source (a user), you pass invalid and inconsistent data to the house
The JSON schema can be already defined by another party: external service API or another team member
A requirement to support other formats besides JSON can appear

OK, domain objects and their JSON representation are different things, and we should learn how to transform one to another and back. For the example, we’re going to work with the following JSON shape:

{
  "number-of-portions": 1,
  [
    {
      "product": "Jumbo Egg",
      "quantity": "2 pc"
    },
    {
      "product": "Salt",
      "quantity": "1 tspn"
    },
    {
      "product": "Milk",
      "quantity": "2 tbspn"
    }
  ]
}

How do we convert between this and our IngredientList? There’re obviously several ways to do it. I’ll describe one that might seem complicated at first sight. But it has proven to scale well if a project has many types of objects and messages.

Three layers

Yep, layers again.

The first one we had described already: it’s the domain layer defining our IngredientList, Ingredient, and Quantity objects. To keep architecture well-shaped, this layer must not care about serialization/deserialization, know something about app message format, or even know anything about such thing as JSON. It should just do the business; constructing and destructing domain objects is others’ responsibility.

DTO

Next comes DTO layer. DTO stands for “Data Transfer Object.” This layer contains type definitions that more or less resemble the shape of JSON data. DTO layer is also responsible for converting DTOs to domain objects and back. In our case, it might be:

// === RecipeDto.res ===

// This module works only with DTO types defined in it and domain
// object types. This domain `open` makes code less cluttered.
open RecipeDomain

//======================================================================
// DTOs
//======================================================================

type ingredient = {
  product: string,
  quantity: string,
}

type ingredientList = {
  numberOfPortions: int,
  items: array<ingredient>,
}

//======================================================================
// Converters
//======================================================================

let unitsFromDomain = (u: Quantity.units) =>
  switch u {
  | #pc => "pc"
  | #tsp => "tsp"
  | #tbsp => "tsp"
  | #cup => "cup"
  | #ml => "ml"
  | #l => "ltr" // there might be difference
  | #g => "gr" // there might be difference
  | #kg => "kg"
  | #oz => "oz"
  | #lb => "lb"
  | #clove => "clove"
  }

let unitsToDomain = s =>
  switch s {
  | "pc" => Ok(#pc)
  | "tsp" => Ok(#tsp)
  | "tbsp" => Ok(#tbsp)
  | "cup" => Ok(#cup)
  | "ml" => Ok(#ml)
  | "ltr" => Ok(#l)
  | "gr" => Ok(#g)
  | "kg" => Ok(#kg)
  | "oz" => Ok(#oz)
  | "lb" => Ok(#lb)
  | "clove" => Ok(#clove)
  // it can fail
  | _ => Error(#UnkonwnUnit(s))
  }

let ingredientFromDomain = (ingredient: Ingredient.t): ingredient => {
  let (amount, units) = ingredient->Ingredient.quantity->Quantity.rawValue

  {
    product: ingredient->Ingredient.product,
    quantity: amount->Float.toString ++ " " ++ units->unitsFromDomain,
  }
}

let ingredientToDomain = (dto: ingredient): result<Ingredient.t, 'err> => {
  // Handle that non-machine-friendly "2 tspn" format
  let quantityR = switch dto.quantity->Js.String2.split(" ") {
  | [amountStr, unitsStr] =>
    switch (amountStr->Float.fromString, unitsStr->unitsToDomain) {
    | (Some(amount), Ok(units)) => Quantity.make(amount, units)->Ok
    | (_, Error(_) as err) => err
    | _ => Error(#BadQuantityFormat(dto.quantity))
    }
  | _ => Error(#BadQuantityFormat(dto.quantity))
  }

  quantityR->Result.map(quantity => Ingredient.make(dto.product, quantity))
}

let ingredientListFromDomain = (ingredients: IngredientList.t): ingredientList => {
  let n = ingredients->IngredientList.originalNumberOfPortions
  {
    numberOfPortions: n,
    items: ingredients->IngredientList.all(~numberOfPortions=n)->Array.map(ingredientFromDomain),
  }
}

let ingredientListToDomain = (dto: ingredientList): result<IngredientList.t, 'err> => {
  dto.items
  ->Array.map(ingredientToDomain)
  ->ResultX.sequence
  ->Result.map(items => IngredientList.make(items, ~numberOfPortions=dto.numberOfPortions))
}

You might ask, what’s the point of creating another set of types that is similar to the set already defined in the domain layer?

Domain objects are opaque. We’re free to tweak their internal presentation without fear of breaking communication; DTOs are transparent and much closer resemble the data shape rather than domain objects. And the difference between a DTO and a domain object is sometimes significant.
Domain objects and DTOs can evolve independently. For example, DTOs may change in response to an API update, and business logic will not be affected.
Domain objects include strict runtime checks to verify business rules and often make it impossible to have an invalid state; DTOs, on the other side, hold data as is providing only minimal validation like field presence or types.

In summary, the separation gives you more flexibility in the long run.

Whew, we are almost done supporting our JSON data schema. But… where is JSON itself here?

Codecs

Here comes codec layer. Its responsibility is converting between a basic primitive type such as string or Js.Json.t and data transfer objects. Why another layer in addition to DTO? It’s all about flexibility again. First, JSON field names might differ (e.g., use kebab-case-names) or imply some defaults; second, you are not limited to JSON only or a particular JSON parser. Having a dedicated layer allows creating different variations for different cases: full-fledged JSON parser/validator for user-facing JSONs, XML parser/validator for interaction with an external system, blind JSON “any-cast” for internal performance-critical message exchange.

To build a solid JSON codec layer I use Jzon library (disclosure: I’m the author of Jzon). Here are codecs which do the job for our ingredient list:

// === RecipeJson.res ===

// This `open` lets refer to DTO fields without prefixes
open RecipeDto

let ingredient = Jzon.object2(
  // A function to convert DTO to a tuple that is friendly to Jzon
  dto => (dto.product, dto.quantity),
  // A function to convert Jzon-friendly tuple back to DTO
  ((product, quantity)) => Ok({product: product, quantity: quantity}),
  // Enumeration of fields comprising the tuple
  Jzon.field("product", Jzon.string),
  Jzon.field("quantity", Jzon.string),
)

// The similar codec, but for another DTO. See Jzon docs for more examples
let ingredientList = Jzon.object2(
  dto => (dto.numberOfPortions, dto.items),
  ((numberOfPortions, items)) => Ok({numberOfPortions: numberOfPortions, items: items}),
  // here we handle a kebab-case-field-name used in JSON
  Jzon.field("number-of-portions", Jzon.int),
  Jzon.field("items", Jzon.array(ingredient)),
)

Aren’t codecs just boilerplate? Indeed, they closely follow the shapes of data types defined in the DTO layer. But some code is anyway required to lift an arbitrary-shaped Js.Json.t to well-defined DTOs. Someone has to write it down. I’m thinking about a tool to auto-generate Jzon codecs out of types defined in a DTO module. Perhaps it’s possible, but I’d leave it at the level of an idea until some actual demand.

As I told already, you might use other tools to create the codecs layer. Take bs-json if it feels better. Or even force Js.Json.t to DTO conversion with Obj.magic if you know what you do.

Putting all together

Finally, all ropes are stretched across the layers. What’s next? We can use it!

// === Serialize ===
let myJson =
  ingredients->RecipeDto.ingredientListFromDomain->Jzon.encodeWith(RecipeJson.ingredientList)

// === Deserialize ===
let ingredientsR =
  myJson
  ->Jzon.decodeWith(RecipeJson.ingredientList)
  ->ResultX.mapError(err => #JsonDecodingError(err))
  ->Result.flatMap(dto => dto->RecipeDto.ingredientListToDomain)

switch ingredientsR {
| Ok(ingredients) =>
  /* show recipe to user */
| Error(#JsonDecodingError(err)) =>
  /* handle low-level error somehow */
  Js.log(err->Jzon.DecodingError.toString)
| Error(#BadQuantityFormat(str)) =>
  /* handle other errors, e.g. show an error in UI */
| Error(#UnkonwnUnit(str)) =>
  /* handle other errors, e.g. show an error in UI */
| Error(_) =>
  /* and so on */
}

Alternatives (or not)

Isn’t this three-layer system too complicated to get a JSON object and just extract some field values? Maybe. However, in a system with many data types required to be serialized/deserialized, such layer separation adds its maintainability points, despite seemingly much boilerplate.

Anyway, you always have alternatives to consider:

ReScript Apollo Client generates type-safe bindings to GraphQL schemas. Nice option if you only develop the front-end part in ReScript and the server provides GraphQL API.
JSON Schema might be used to describe data shape along with a validator such as Ajv to verify the validity of a JSON. This can save you from creating codec layers.

And in some quick’n’dirty or straightforward cases, you are free to just use Object.magic to any-cast between Js.Json.t and {..}, then using this object fields directly hoping/knowing the fields are indeed there and have valid types.

So, it all depends on your project. Pick a strategy and go ahead. You can always “upgrade” if it does not fit your needs later.

This article was originally published at: https://fullsteak.dev/posts/rescript-json-typed-strongly

Full-stack ReScript. Architecture Overview

Victor N. — Fri, 22 Oct 2021 15:03:20 +0000

So, ReScript. I guess you have heard about this beautiful and pragmatic language in the context of reliable and enjoyable web development. If you dive into learning resources around ReScript, you’ll see most of them focus on React/UI/front-end development, leaving the server-side with no attention. But can ReScript also be used to create a full-featured back-end? In this article, I’d try to prove it can and does it with success.

I have two projects running in production, which are primarily done in ReScript (with some routine JS glue) from the front to the back:

Future Corporations — a multiplayer game for web and mobile platforms
Figuro — an on-demand laser cut service where a user uploads his drawing, chooses material, and voilà gets his widget delivered the next day

They both are small-scale, but I’m sure I found some architecture and patterns that would allow me to scale them quickly and easily if it is required. ReScript is one of the few options to do an entire project using the only platform in the functional programming paradigm. A project can be quickly done solo or by a small team, avoiding cognitive context switches, code duplication, etc.

Let me unwind both project internals to show how they work on the high level leaving specific implementation details out of the scope.

Disclaimer: There’re infinite ways to shape your project. I’m describing just one possible way. I did not invent this architecture, but I gathered ideas from DDD (Domain Driven Development) and satellite paradigms, then projected them to ReScript. The suggested architecture might not fit your needs, but it works well for the projects I’m talking about.

To be more specific, the article is not about ReScript. It’s about architecture. The same principles can be easily used with any FP language like F# or PureScript or even in a non-FP platform (JavaScript, TypeScript) if you follow functional programming principles.

One message journey

Even though projects use different transports, storage services, and deployment mechanisms, they share the same architecture. The architecture is made up of layers that are strictly isolated and play different roles on the whole.

Here’s how a typical user action and its corresponding reaction look like:

😲 Quite many arrows and boxes for a single “Pew-pew,” right? Don’t be afraid; this is simplified; there’re more actually. However, every layer here is for a reason, and let’s take a look at them one by one from left to right. Depending on your project, you can omit some layers.

Let’s walk through the most complex scenario.

Front-end

Depicted as a single “React SPA” layer here, it contains more layers inside in practice. But the focus of this article is the server-side, so it is simplified. What’s important is that this layer often initiates requests on behalf of a user and renders responses to present results.

Such requests are usually sent inside React.useEffect or triggered by UI event handlers such as onClick. The requests might be delivered via various transports. For example, in the Figuro web project, they are simple asynchronous HTTP requests. Whereas in the Future Corporations game, they are sent over websocket connection because a persistent connection better serves a real-time game with two-way communication.

JSON vs DTO

A request usually contains some useful payload. This payload is sent over the wire, so it should be a basic structure serializable to a string or byte buffer. You know, JSON is a popular format to exchange messages, and I use it as well. However, it might be BSON, XML, protobuf, or a home-grown format.

In a strongly-typed language such as ReScript (or F#, or PureScript), it is pretty impractical to deal with raw JSON (the Js.Json.t type), so the first thing to do on a boundary is to convert it to a so-called DTO: data transfer object. DTOs are simple nested strongly-typed records that are trivial to convert to JSON and back. You’ll get no DTOs in JavaScript because JSONs are DTOs already there, albeit without any checking 🤞

In ReScript, you’d have another layer (not shown on the diagram for simplicity) to convert JSON to DTO and back. To illustrate the difference, here’s JSON:

{"buy-in":900,"tax":100}

and here’s DTO type:

type fee = {
  buyIn: float,
  tax: float,
}

The difference might seen minor (it is), but:

(a) your can work with DTO fields semantically whereas it’s hardly possible with black-boxed Js.Json.t (data->Js.Json.decodeObject->Option.getExn->Js.Dict.get("tax")->Option.getExn->Js.Json.decodeNumber->Option.getExn anyone?),
(b) you can perform trivial invariant validations at the stage of conversion to check whether all fields are present or timestamps are specified in a proper ISO format.

Despite all fuzz, DTOs are intermediate technical objects that are not interesting to business logic. The business logic wants to work with Money.t (and not float) that places much more restrictions on the possible values, has several ways to present the data, etc. The conversion between a DTO and model is the responsibility of further layers. I mention it here to say that checking business rules is not a part of the JSON-to-DTO layer.

Gateway layer

Gateway is a process that listens on a public hostname and ports well-known to the front end. Its role is to route incoming requests further to a proper Server App and then passing responses back, possibly modifying message metadata. A gateway can be a ready-made solution such as NGINX reverse proxy, Kubernetes Ingress, or Traefik. Or it can be a small custom daemon if existing solutions do not fit. Your project will usually have zero or one gateway.

In the case of the Figuro laser-cut web app, I have no gateway at all because it is a NextJS monolith at the moment, and all requests are sent directly to the Server App. But the Future Corporations game has a custom thin gateway that keeps websocket connections with clients on one side and NATS message queue on the other side. The gateway is some proxy that converts the websocket protocol suitable for clients’ browsers and mobile apps to NATS messages used to talk between server apps. It also does the reverse: looks for some NATS messages interesting to clients and, once found, forwards them to relevant recipients over websocket.

Server app layer

A server app, also called “service app” or “daemon,” is a thing that defines process boundaries. That is, a server app is a deployment unit. You run this thing as a Docker container, or with pm2, or straight as systemd service, whatever deployment strategy you choose.

You’ll have one server app if you build a monolith or several (dozens, hundreds) if you build mini-/microservices. For example, the Figuro web app has a single app: the NextJS app itself. And the Future Corporations game has seven miniservices at the moment. Each server app is responsible for its own activity: checking in players for a new online game (searching for opponents), customizing a player profile, holding and advancing running game state, triggering timeouts if a player has gone sleep, tracking statistics for further analytics, and so on.

The activities themselves are served mainly by other layers: handlers, domain services, and domain models (described below). The primary purpose of the server app itself is to run all these layers and call them when necessary.

You can see the “App Module” at the chain start. This is the only code that actually belongs to the server app layer. Its mission is:

Read config (from environment variables, for example)
Connect to network services, start listening on given ports
Subscribe to MQ topics of interest or URL paths in case of HTTP
Engage timers if the app acts as a cron-job rather than a network request handler
Take requests, deserialize their payload, and forward them to Handler
Serialize handling results and errors to send them back over HTTP or MQ
Write logs
Reply to health checks

The app layer is hardest to test because you’d have to issue actual HTTP requests or MQ messages and check responses the same way. Luckily, the App Module is easy to make very thin and almost boilerplate. I never cover this layer with tests.

Summarizing the above, the Server App layer is technically just a container for other layers so that an OS can run the app. All interesting happens further.

Handler layer

The handler layer knows what to do with requests. The hosting server app provides a handler with such requests in the form of inbound messages such as “player acted,” “player has gone offline,” “room is full,” “timeout expired,” etc. The job of a handler is to take such message, convert its DTO payload to domain objects, perform actions, interact with a database or other external services, and finally return a list of outbound messages such as “game updated,” “game finished” so that the caller can make responses. We know the caller is the server app, but the handler itself knows nothing about it.

The handler layer is the last one that is allowed to perform IO and make side effects. For example, interact with the database, file system, or e-mail sending SaaS. They do it via adapters that are configured and provided by the hosting app module. To be more precise, it is their primary duty. They act as clerks:

Decode incoming messages
Read external storage
Forward this further to the service layer, which actually makes business decisions
Get decisions back and record the results in the database
Encode domain objects back to DTO and return results to a caller

Here’s an example of check-in app handler interface:

module InboundMessage = CheckinMessages.InboundMessage
module OutboundMessage = CheckinMessages.OutboundMessage

type t

// Possible results
type handleResult =
  | Message(OutboundMessage.t)
  | ServerError(string)

// Room and Profile store are adaptors to interact with data in PostgreSQL database
let make: (RoomStore.t, ProfileStore.t) => t

// The essense of a handler
let handle: (t, InboundMessage.t) => Promise.t<array<handleResult>>

And implementation outline:

module InboundMessage = CheckinMessages.InboundMessage
module OutboundMessage = CheckinMessages.OutboundMessage
module Service = CheckinService
module Command = Service.Command
module Event = Service.Event
module Player = AxEngine.Player
module Room = LobbyDomain.Room
module RoomTable = LobbyDomain.RoomTable
module RoomPlayer = LobbyDomain.RoomPlayer

type t = {
  roomStore: RoomStore.t,
  profileStore: ProfileStore.t,
}

type handleResult =
  | Message(OutboundMessage.t)
  | ServerError(string)

let make = (roomStore, profileStore) => {roomStore: roomStore, profileStore: profileStore}

type commandOrQuery =
  | Command(Command.t)
//| Query(query); // no queries in this miniservice, only commands

// An inbound message is either a command to do something, or a query to read
// some data. This function interprets an inbound message segregating commands
// and queries. The latter are applied directly to stores skipping further
// processing layers.
let toCommandsAndQueries =
  (
    handler,
    inMessage: InboundMessage.t
  ): Promise.t<result<array<commandOrQuery>, 'err>> =>
  switch inMessage {
  | PlayerPresenceUpdated({playerId, online: false}) =>
    /* ... */

  | PlayerPresenceUpdated({online: true}) =>
    /* ... */

  | PlayerGameStartSubscriptionUpdated({playerId, subscribed}) =>
    Command.UpdateWaitMode(PlayerId(playerId), subscribed ? OnlineAndOffline : OnlineOnly)
    ->Command
    ->Array.just
    ->Ok
    ->Promise.resolve

  | RoomJoin(playerId, plainRoomAddress) =>
    /* ... */

  | RoomLeave(playerId) =>
    /* ... */
  }

// No queries in this miniservice. But if there were a few, this function would
// query DB via store adapters.
//let handleQuery = (handler, query) => raise(Exn.NotImplementedYet)

// This function reformats domain-level events to publicly consumable
// outbound messages if required
let toOutboundMessages = (handler, events): Promise.t<array<OutboundMessage.t>> => {
  let {profileStore} = handler
  events->Array.map((event: Event.t) =>
    switch event {
    | RoomCreated(_) =>
      // It is OK to not announce some events
      []->Promise.resolve

    | PlayerJoinedRoom(playerId, room) =>
      OutboundMessage.PlayerJoinedRoom({
        playerId: playerId->PlayerId.toInt,
        roomAddress: room->Room.address->Room.Address.toString,
        buyin: room->Room.buyin,
        tax: room->Room.tax,
      })
      ->Array.just
      ->Promise.resolve

    | PlayerLeftRoom(playerId, room) =>
      OutboundMessage.PlayerLeftRoom({
        playerId: playerId->PlayerId.toInt,
        roomAddress: room->Room.address->Room.Address.toString,
        refund: room->Room.buyin,
      })
      ->Array.just
      ->Promise.resolve

    | RoomFilledUp(roomTable) =>
      /* ... */

    | WaitModeUpdated(_, _) =>
      /* ... */
    }
  )
  ->Promise.all
  ->Promise.map(Array.concatMany)
}

// React to events by sending update queries to our database
// through LalalaStore adapters. They effectivelly convert
// function calls to SQL expressions and execute them on DB
let applyEventsToStore = (handler, events) => {
  let {roomStore, profileStore} = handler
  events->Promise.runInSequence(event =>
    switch (event: Event.t) {
    | RoomCreated(room) => roomStore->RoomStore.create(room)
    | PlayerJoinedRoom(playerId, room) =>
      roomStore->RoomStore.addPlayerToRoom(playerId, room->Room.id)
    | PlayerLeftRoom(playerId, room) =>
      roomStore->RoomStore.removePlayerFromRoom(playerId, room->Room.id)
    | RoomFilledUp(roomTable) =>
      roomStore->RoomStore.markAsPlaying(roomTable->RoomTable.room->Room.id)
    | WaitModeUpdated(playerId, mode) =>
      profileStore->ProfileStore.updateWaitMode(playerId, mode)
    }
  )->Promise.erase
}

let handleCommand = (handler, command) =>
  switch (command, Service.execute(command)) {
  | (_, Ok(events)) =>
    // The happy path: we execute a command, get events (their descriptions),
    // save data to DB and convert them to outbound messages
    handler
    ->applyEventsToStore(events)
    ->Promise.then(() =>
      handler
      ->toOutboundMessages(events)
      ->Promise.map(Array.map(_, x => Message(x)))
    )

  | (JoinRoom(roomPlayer, joinTarget), Error(err)) =>
    // Custom error handling is possible when we express a domain error
    // as a valid scenario with its own message
    let roomAddress = switch joinTarget {
    | New(roomAddress) => roomAddress
    | Existing(roomTable) => roomTable->RoomTable.room->Room.address
    }
    let reason = switch err {
    | #RoomFull => #ALREADY_FULL
    | #BadNumberOfPlayers => #BAD_ADDRESS
    | #RoomDoesNotExist => #NOT_EXIST
    }
    Message(
      RoomJoinError({
        playerId: roomPlayer->RoomPlayer.playerId->PlayerId.toInt,
        roomAddress: roomAddress->Room.Address.toString,
        reason: reason,
      }),
    )
    ->Array.just
    ->Promise.resolve

  | (_, Error(err)) =>
    // Generic error. The caller should log it, send to Sentry,
    // call admin whatever
    ServerError(
      Js.Json.stringifyAny(err)
      ->Option.getWithDefault("<not serializable error>")
    )
    ->Array.just
    ->Promise.resolve
  }

let handle = (handler, inMessage) =>
  handler->toCommandsAndQueries(inMessage)->Promise.then(coqs =>
    switch coqs {
    | Ok(coqs) =>
      coqs->Promise.runInSequence(coq =>
        switch coq {
        | Command(command) => handler->handleCommand(command)
        //| Query(query) => handler->handleQuery(query)
        }
      )->Promise.map(Array.concatMany)
    | Error(#BadJoinRoomAddress(playerId, roomAddress)) =>
      Message(
        RoomJoinError({
          playerId: playerId->PlayerId.toInt,
          roomAddress: roomAddress,
          reason: #BAD_ADDRESS,
        }),
      )
      ->Array.just
      ->Promise.resolve
    }
  )

Handlers are testable, not very convenient, but absolutely doable. The basic idea is to create a dedicated database for unit testing, which is erased and seed with demo data on each test case setup. Then, the test suite plays the role of the server app layer, asks to handle various messages, and checks handle results. Because handlers know nothing about hosting apps, the technique is straightforward. Such tests are slow, but they serve an important role in checking whether all layers are correctly glued and that IO works as expected with actual storage. In my case, handler tests comprise ~20% of all tests.

In summary, the handler layer is a reusable module that forwards all pure-functional work further to the service layer and, on its own, does the dirty stuff. It converts domain objects to DTO and back, reads storage to prepare input for the service layer, writes storage to save the service layer output.

Service layer

The service layer, also known as the “domain service layer,” is the first layer in the chain that is purely functional 🥰 It takes commands along with domain models, applies business logic, and produces events describing what happened. Here’s an example of such a service:

open SimpleTypes

// Services use domain models extensively
module Player = AxEngine.Player
module Room = LobbyDomain.Room
module RoomTable = LobbyDomain.RoomTable
module RoomPlayer = LobbyDomain.RoomPlayer

module Command = {
  type joinRoomTarget =
    | Existing(RoomTable.t)
    | New(Room.Address.t)

  // Commands are variants designating desired action.
  // Their parameters contain minimal context to perform this action.
  type t =
    | JoinRoom(RoomPlayer.t, joinRoomTarget)
    | LeaveAllRooms(RoomPlayer.t)
    | UpdateWaitMode(playerId, RoomPlayer.waitMode)
    | GoOffline(RoomPlayer.t)

  // Command might be rejected if it violates business contract
  type error = [#RoomFull | #BadNumberOfPlayers | #RoomDoesNotExist]
}

module Event = {
  // If command applied successfully, zero or more events reported
  // as happened. A caller is responsible to record/report these events.
  type t =
    | RoomCreated(Room.t)
    | PlayerJoinedRoom(playerId, Room.t)
    | PlayerLeftRoom(playerId, Room.t)
    | WaitModeUpdated(playerId, RoomPlayer.waitMode)
    | RoomFilledUp(RoomTable.t)
}

// The essense of a service
type execute = Command.t => result<array<Event.t>, Command.error>

//=====================================================================
// Implementation
//=====================================================================

let execute: execute = command =>
  switch command {
  | JoinRoom(roomPlayer, New(FriendsRoom(_) as address)) =>
    /* ... call domain models’ functions ... */

  | JoinRoom(roomPlayer, New(GlobalRoomForTwo as address)) =>
    /* ... call domain models’ functions ... */

  | JoinRoom(roomPlayer, Existing(roomTable)) =>
    /* ... call domain models’ functions ... */

  | JoinRoom(_, New(GlobalRoom(_))) =>
    /* ... call domain models’ functions ... */

  | UpdateWaitMode(playerId, waitMode) =>
    /* ... call domain models’ functions ... */

  | GoOffline(roomPlayer) =>
    /* ... call domain models’ functions ... */

  | LeaveAllRooms(roomPlayer) =>
    /* ... call domain models’ functions ... */
  }

The services are joyful to test. They have no side effects, neither they have impure dependencies. You make a command, give it to execute, and check the result. You might quickly craft dozens of tests for all the various flows and edge cases and be sure the business logic is rock solid.

You might wonder why this layer exists and what the purpose of the long variant switches is. After all, the handler layer might directly call domain models’ functions. The reason is composability. Different commands might produce the same events or intersecting sets of events. Similarly, various inbound messages can trigger the same commands. If not put in a dedicated service layer, the handler layer is going to blow up. However, if you have done the split this way, the service layer offloads the handler layer, and the latter is only required to produce commands and handle events.

Another reason lies in the canonical DDD methodology. What a system can do and what events it can produce is discussed with domain experts (developers talk to business people). The activity is known as “Event Storming.” And even if you don’t arrange such activity, understanding the possible ins and outs is likely to happen before you write an app. So, in practice, you typically create this layer and cover it with tests before the handler layer even appears.

In summary, the purpose of the service layer is to define how business works in terms of commands and events. The primary function is execute, which gets a command, domain models to operate upon, calls necessary domain functions over these models to actually apply business logic, and finally produces output in the form of events.

Domain layer

Finally, the domain layer is a place where the most exciting things happen. A domain is what makes your project do something valuable and unique. It delivers business value. More specifically, it defines objects (aka models) and data types along with functions operating on them that together describe the world your app works with.

If you make a game, the domain contains everything related to the rules and objects of the game. If you make an online store, the domain would include concepts of a cart, order, product, coupons, and functions related to checkout, product comparison, and so on.
If you make an online graphics editor, the domain would include all GFX math, paint tools, filter algorithms, etc, etc.

Here's just one module interface from the Future Corporations game to give you a rough idea of how domain objects and functions can look like. It is responsible for a particular game state management; it defines the rules of the game (highly inspired by Monopoly):

/*
 *
 * The central point of game logic engine
 *
 */
type t

module Cluster = Board.Cluster
module Timeout = Types.Timeout

// Creates a new game room
let make: (
  ~initialCash: Money.t=?,
  ~initialSalary: Money.t=?,
  ~bonusAmount: Money.t=?,
  ~actionTimeout: int=?,
  ~bidTimeout: int=?,
  ~turnMissesBeforeKnockout: int=?,
  ~skipWelcomeLogEntry: bool=?,
  int /* number of players */,
) => t

let getNumberOfPlayers: t => int

/*
  Returns a list like [0, 1, 2, 3] where number of elements is defined
  by the number of players in the game.
*/
let listPlayers: t => list<Player.t>

let countPlayersAt: (t, Location.t) => int

let getPlayerState: (t, Player.t) => Player.State.t

let getWhoTurns: t => Player.t

let getActivePlayerNextTo: (t, Player.t) => Player.t

let getSalary: t => Money.t

let getAuction: t => option<Auction.t>
let hasAuction: t => bool

let getCellOwner: (t, Location.t) => option<Player.t>

let getMonopolyOwner: (t, Cluster.t) => option<Player.t>

let getMortgageLimit: (t, ~player: Player.t) => Money.t

// Returns property upgrade level (0 to 5); returns 0 if not a property
let getPropertyLevel: (t, Location.t) => int

let maySellCell: (t, Location.t, ~player: Player.t) => bool
let mayUpgradeProperty: (t, Location.t, ~player: Player.t) => bool
let mayDegradeProperty: (t, Location.t, ~player: Player.t) => bool

let isFinished: t => bool

// Winner goes at index #0, second place at #1, and so on
let getFinalRanks: t => option<list<Player.t>>

let getTimeoutId: t => Timeout.id
let getTimeoutDuration: t => option<int>
let getTimeoutSettling: t => int
let getTimeoutPlayers: t => Player.Set.t

let getTurnMissesBeforeKnockout: t => option<int>

/* ====================================================================
 *
 * Game log manipulation
 *
 * ================================================================== */

/*
  Forcibly adds a new record to the log. Use to push non-game records and
  to consolidate the log when records are obtained via an alternative
  channel, such as network message
*/
let log: (t, Log.Record.t) => t

/*
  Steals log from the second game argument into the first inserting it
  before the current records. Useful to hydrate a game update that came
  with partial log only
*/
let prependLogFrom: (t, t) => t

let getLog: t => Log.t
let clearLog: t => t

/* ====================================================================
 *
 * Actions
 *
 * ================================================================== */

let applyDiceRoll: (t, (int, int), ~player: Player.t) => t
let applyChance: (t, Chance.t, ~player: Player.t) => t

let passAuction: (t, ~player: Player.t) => t
let startAuction: (t, ~player: Player.t) => t
let giveUpAuction: (t, ~player: Player.t) => t

/*
  Makes a bid on the current auction. The bid is expected to be absolute,
  that is offered price, *not* price delta
*/
let bidAuction: (t, Money.t, ~player: Player.t) => t

let upgradeProperty: (t, Location.t, ~player: Player.t) => t
let degradeProperty: (t, Location.t, ~player: Player.t) => t
let sellOwnCell: (t, Location.t, ~player: Player.t) => t

let acceptChance: (t, ~player: Player.t) => t
let rejectChance: (t, ~player: Player.t) => t

let resign: (t, ~player: Player.t) => t

let handleTimeout:
  (
    t,
    Timeout.id,
    ~roll: unit => (int, int),
    ~takeChance: unit => Chance.t
  ) => t

// Alternative interface (used to play with bot)
let act: (
  t,
  Player.Action.t,
  ~player: Player.t,
  ~roll: unit => (int, int),
  ~takeChance: unit => Chance.t,
) => t

One crucial requirement to everything in the domain layer is functional purity. In other words, domain layer functions cannot have side effects, perform IO, get the current time, generate random numbers, or do anything which can lead to behavior differences depending on the environment, current time, or process state. Neither they may take impure function arguments or return impure functions. This requirement may sound unreasonably strict, but it is pretty easy to satisfy once you see a pattern:

When a domain function wants a value or object that cannot be obtained purely (say, the current time), add a parameter to this function that brings this value to the function scope (e.g., ~now: Js.Date.t). Let the caller do the dirty work.
When a domain function wants to perform a side effect, return a simple record/object that describes the desired effect. Let the caller apply it accordingly.

In the example provided, take a look at the functions applyDiceRoll and applyChance, for example. Instead of implicit random number generation when a player is going to roll a dice or pick a chance card, the engine “waits” for the caller to tell the outcome explicitly.

Why so? The answer is simple. As long as you keep your domain pure, you can test it effectively. Pure functions never require mocks, stubs, or any hacks. You literally test what you test, no less, no more. And as the domain layer contains most of the logic intrinsic to your application, keeping it pure makes it easy to have a comprehensive test suite covering all the business scenarios. In my particular case, more than 50% of the test code goes here. This gives you high confidence in your product. Multiply this by the sound and robust type system of ReScript, and you get an unbreakable core!

A very attentive reader could spot purity violation in functions handleTimeout and act. Although they have no side effects, they have impure functions as parameters roll and takeChance. Yes, my fault. They were written before all the ideas of layer restrictions were crystallized in my head. As a consequence, this couple often causes pain while testing and composing. If I implement these functions today, instead of taking impure random-generation functions as arguments, I’d provide them with some kind of pure object called “Entropy” that already contains a sequence of a few specific pre-generated values with a knowingly enough length to perform any chain of a single turn game actions.

In summary, the domain layer is your application heart. It is a collection of types, objects, functions that effectively do the job. The domain layer has no artificial requirements for its interface. You are free to shape and organize it in whatever way that makes more sense. The only vital requirement is functional purity, allowing heavy unit testing.

Shared domain

You might note that I put the domain layer out of the “back-end” box on the original diagram. That’s because some portions of domain code can be shared across the back-end and front-end. And that’s where full-stack strategy really shines 🌟

For example, the server and the mobile app use the same game domain logic in the Future Corporations game. On the server, it is used for multiplayer games (that is, the server updates the games), and in the app, absolutely the same code is used to run offline games against AI or friends in hot-seat mode.

In the Figuro laser cut service, the same code is used by the client to compute manufacturing price instantly (without hitting a server) as a user uploads a new drawing or chooses another material and on the server at checkout to verify prices and avoid potential fraud.

Cool eh? 😎 This would be impossible if front and back were developed in different languages.

I think it’s clear that not all the domain code is reusable on both sides. So, most of the domain code is indeed belongs to the server. I just wanted to emphasize the possibility of uniform client/server-side usage in the cases when it makes sense.

Back-end overview

Let’s repeat in short what layers the back-end has and how they communicate.

Gateway. The only thing available publicly. Forwards messages forth and back between clients and server apps. For web apps, you’d likely use a ready-made solution like NGINX or Traefik. For real-time apps based on websockets, this would probably be a thin OS service connected to some message broker.
Server app. A deployment and replication unit. Hosts all further layers inside itself. The primary responsibility is to listen for messages, convert wire data to DTO and back, perform logging, read configs, keep connections to external services. Hardly testable.
Handler. Communicates to external services and databases, converts DTO to domain objects and back, interprets inbound messages to commands and events to outbound messages. Quite testable using external service stubs and dedicated unit-test databases.
Service. Applies commands to domain objects and generates command consequence events. Functionally pure. Directly testable with no hacks.
Domain. Business domain objects and functions. No restrictions on API. Functionally pure. Directly testable with no hacks.

One sandwich with onion, please

What else besides software architecture have layers? Yep, onions and sandwiches. That’s why they became metaphors for software engineering. And if I happened to explain the concepts clearly, you almost already know what “Onion architecture” and “Impure-pure-impure sandwich” are. These terms are just another view on the things already explained. Let’s repack the concepts so that you can keep the talk with your mates in a bar.

— We use onion architecture 🤘

— Me too!

The point of all buzz around the onion architecture is having well-defined layers with a unified coupling direction. We have this. Domain knows nothing about the service layer; the service layer knows nothing about handlers; the handlers don't know anything about the app layer. Onion done!

Topics to discuss in a bar: do external services belong to the onion skin, and how deep they might be coupled with outer layers?

— We make impure-pure-impure sandwiches 🤤

— Me too!

The metaphor about the sandwich is all about shifting side effects to an operation boundary so that the middle layer (the stuffing) might be easily testable. We have this. The service app layer is highly impure and hard to test, the handlers are impure too (yet testable), and the service layer, along with the domain layer, is pure, juicy, and easily testable.

Topics to discuss in a bar: is it OK to say that processing with FFmpeg or ImageMagick may belong to the stuffing layer? Does the answer change if I won’t call them as a subprocess but use NodeJS bindings and make the transform in-process?

Final words

The architecture described in this article is just one way to do things. You might follow it, or follow it partially, or ignore it and build your project in a completely other fashion. I aimed to describe a possible way to structure code sustainable enough to survive medium-scale. If you’re making a small-scale intranet utility, it is OK to mash all the logic in a single layer. If you’re big and looking for super-hi-load recipes, you don’t read these words. And if you are a solo developer or a small dev team member planning to rule the world, I’d be happy if I helped a little.

A minute of insolence: if you like the article, I’d appreciate it if you rate Future Corporations on Google Play. It’s my side project, but I put much effort into it. And because I’m stupid in marketing, one ad campaign brought me a pack of 1-star ratings. I would be happy to recover, but only if you really like the game.

Cross-post

This post was originally published at https://fullsteak.dev/posts/fullstack-rescript-architecture-overview

Mobile game with ReasonML/ReScript and React: my experience

Victor N. — Wed, 16 Dec 2020 13:00:15 +0000

Hello everyone! When the Covid pandemic started, I've got some extra time and decided to use it to create a game for mobile and web platforms. I wanted to resurrect one cool multiplayer remake of a board game that shut down ten years ago. Since a digital tabletop game sounds like something which might be done without fancy 3D graphics, I decided to outwalk traditional tools like Unity and make everything like a web application. The first reason is that I have no experience with Unity, and the second reason is Reason 😄 I mean ReasonML, an emerging strongly typed language tightly integrated with React, which compiles to JavaScript.

ReasonML has a powerful type system that makes the development really joyful and surprisingly reliable, and bug-free. I've got some experience with ReasonML for classic web development, so it shouldn't take more than 2-3 months of evening/weekend programming to complete the game. Oh, I was mistaken. Nevertheless, the game is released and playable.

And now I want to share the experience of making a mobile game using Expo + React Native + ReasonML/ReScript + NodeJS stack. I'm writing this article for JavaScript web developers thinking about making a mobile app or a 2D game similar to an app. There are a few roads to choose from, and this article describes my path to hopefully make things a bit clearer.

HTML and SVG for graphics

Although I have no 3D graphics, the game itself is far from being similar to a web page with text and pictures. The game screen looks like this:

As you may see, there are plenty of elements that would be hard to implement just with HTML + CSS. SVG to the rescue! What's cool is that SVG might be easily embedded into the big HTML picture. So, I'm using HTML for the top-level layout, whereas in tight places, I employ SVG to draw some ellipses, arrows, shines, etc.

For example, the game board, player stats pane, and action buttons are laid out with HTML flex containers, whereas the elliptic TVs with player avatars and cash counters are rendered with SVG primitives. The use of HTML on the top-level benefits from simple compatibility with various screen sizes and their aspect ratios. And you'll find there's almost an infinite number of screen parameter permutations on Android.

Does the HTML + SVG combo scale well for any graphic effects? Unfortunately, no. Even in my case, I stumbled upon the absence of a feature to manage raster image colors with a relatively simple scene. By design, a player may change the color of his/her car used as an avatar:

The cars themselves are quite complex art pieces, so they are rasterized before using them in the game. I need to rotate the hue of the color in places denoted by a mask stored in another image. This cannot be done with SVG. The only option I found is going deeper and use OpenGL to solve this particular problem. That is, take the input images, do the required color processing with a low-level fragment shader, and return the result back to the "web world." To be honest, I haven't done partial recoloring yet — the whole car is recolored at the moment — but it does not make a difference in understanding the big picture. Falling back to OpenGL when necessary works but not without some issues. The main problem here is performance: although rendering a frame is blazing fast (10 ms in my case), snapshotting and transferring the frame back to the world of image tags and PNGs introduces a penalty of ~150 ms. It makes it impossible to use OpenGL in this way in real-time. You have to either keep some parts of the screen (or the whole screen) in the OpenGL world forever or use it only to prepare/process some resources once. Now I use the latter and recolor the cars right before the game when players' appearance is known.

To put summary, the HTML + SVG combo is excellent for graphics if you don't require some unique effects. For anything non-standard, OpenGL could help, but you'd either stick to OpenGL altogether, dropping HTML and SVG, or use it only when a game "level" loads.

React as GUI framework

OK, HTML and SVG can make the scene, but how should we translate the current game state to the proper UI tree and UI actions back to game state handlers? One could use vanilla JS, but in the case of a complex app such as the game, it will quickly become quite complicated. At the very best, it would lead to creating a new framework from scratch. It might be interesting but wasn't my purpose.

The natural choice for me was employing React. As you likely know, React is a declarative UI framework that fits perfectly with the functional programming paradigm. The ReasonML/ReScript language is primarily functional and even includes support for React-style markup (like JSX) right into the language.

In general, using React Native along with React Native SVG is very productive to get the first results quickly. The whole game is easily split into dozens of well-encapsulated components. In turn, the components might be quickly inspected visually and in various states one by one, without waiting for a proper game situation. Thanks Storybook for that.

Of course, nothing can be perfect, and React is not an exception. One of the problems is performance. I'm not saying React is slow, but you can easily make a "mistake," which will cause the whole component tree to re-render. The re-render will happen even if all that has been changed is the color of one hair-width line in the bottom-right corner of a small icon, which is, in fact, hidden by another element right now. These excessive re-renders make the app jerky. You'll have to carefully catch all such moments with React developer tools to analyze why the undesired computational spike has appeared and polish this snatch by properly memoizing some heavy UI parts. Once you've spotted all such moments, the game becomes performant and joyful to play.

React Native for mobile

The original React framework is designed to drive in-browser single-page applications. But the applications for Android and iOS are not web pages. They are freestanding beasts that should be developed natively with Kotlin and Swift. How should a web app appear as a full-fledged mobile app? Here comes React Native.

React Native is a specific subset of the general React which has <View>'s instead of <div>'s, <Text> instead of <span>, no <ul> or <ol>, own CSS-in-JS framework, etc. While it might seem to limit the expressiveness, I didn't suffer from it in practice. At least in the game project where most UI elements are custom and created from scratch in any case. These all are minor problems compared to the HUUUGE benefit: you develop once and build for all the platforms at once: Web (for desktops and mobile without installation), Android, iOS.

This is what the docs promise. In practice, React Native is buggy, glitchy, scattered, and non-obvious in many places. I'm not blaming anyone. The framework is massive and unprecedented, but it almost made me scream and smash the laptop.

Here is a fraction of the problems you might face:

No box shadows on Android: do it yourself
At most one text-shadow may be specified
Text nested Text does not work on Android if it changes font face
SVG nested in SVG does not work correctly on Android
SVG images stored as built-in asset files do not work on Android
SVG effects are not available: no shadows, no blur, nothing
Custom fonts do not work in SVG on Android
SVG interactions do not work
Preloading of fonts does not work on web
Preloading of SVG does not work on web
Linear gradients are not available via styles; however, they are available as a 3-rd party component, but it flickers on the first render
Radial gradients are not available
CSS animations are not available
Hardware-accelerated animations are not available on the web
SVG stroke opacity animation is broken on Android
In contrast to the browser, the mobile app can suddenly crash on something as innocent as an arc path with zero radius; hard to find the reason
Sub-pixel rounding is buggy on Android, causing ±1 pixel gaps and overflows
Absolute positioning inside a reverse-order flexbox is broken on Android
Z-index does not work on Android
etc, etc, etc

I haven't touched iOS yet but expect a pile of problems too, extrapolating what I've got with Android. Making the already functional web-version work on Android took me ~30% of the time spent implementing the rest of the game.

Animations is a pain

React Native offers its own animation subsystem known as Animated. So, what's wrong with it? Well, nothing once you get it, but the process of describing the animation is time-consuming and somewhat non-intuitive, especially in cases with long tracks of tricky intermediate keyframes, sequences, and perfect-timing. It's like trying to program an image directly out of your head, bypassing any trial in a graphic editor: doable but complicated. I'm missing the ability to 100% offload some animations to an artist as I can do with illustrations. That's the reason I had to skip implementing most of the animations before the release. Many of them are still on the TODO-list.

What makes animations even more problematic is the architecture of React Native, which runs them by default on the same thread as the JavaScript code. So, if you do something in JS at the same time when an animation is running, you lose frames, and the app looks snatchy.

There's a way to offload animation to another "fast" thread. Still, it should be carefully planned, and the only values allowed to animate in this case are non-layout properties such as translation, rotation, scale, and color.

In summary, animations in React Native are somewhat a bottleneck that can be worked around, but it takes so much development energy.

ReasonML/ReScript as language

If I'd been a more mainstream web-developer, I use TypeScript to program the React Native app. But some time ago, I was infected by the ideas of functional programming and saw no road back. One of the project requirements was having a shared codebase for the front (the app) and the back (multiplayer server). Filtering the possible language options (Elm, F#, Dart, PureScript, Haskell) through this matrix, not so many variants were left, and I've chosen RasonML/ReScript.

Long story short, the exotic language is the most joyful and robust tier in all the technology stack. The strong yet flexible type system, very simple JS interop, FP-first, and built-in React markup syntax is a breath of fresh air compared to the vanilla JS or TypeScript.

If the project ended up to compile successfully, I'm very confident in the quality of the result. There are no null-pointer exceptions (no exceptions at all if you wish), no forgotten if/else and switch/case paths, no data inconsistency, and fearless refactoring. Any programming should look like this.

ReasonML/ReScript compiles to JavaScript, so I could write a shared game engine for both: the client app and multiplayer server. The client then is built further with React Native, and the server is running with NodeJS. The project is 95% ReasonML/ReScript. The rest is trivial JavaScript glue.

One particular outcome of choosing a functional language for the back-end was learning DDD (Domain Driven Development) development and its satellites: the onion architecture, CQRS, and friends. These techniques have initially been formulated using Java but the core ideas a so much better aligned with functional programming. I'm pleased with well-structured and easily extensible services that are simple and intensively tested with almost no mocks, stubs, fakes, and other hacks considered to be "normal" for some reason.

So, does ReasonML/ReScript is a perfect language? No, unfortunately. And the reason is the slash between the two words. To be more precise, the reasons are political and not technical. ReasonML and its successor (?) ReScript evolve since 2016. ReasonML is a language built on top of OCaml: the niche OCaml's power with the syntax familiar to JS developers. Then, there was a thing called BuckleScript (BS), which compiles OCaml (or ReasonML) to JavaScript. The community targeting the JS platform was fragmented a little: the old school part used OCaml syntax, and the newcomers used ReasonML. This was annoying, but since both languages are just different presentations of the same abstract syntax tree, the library ecosystem was (and is) 100% compatible. Arguably the community center of the mass has slowly moved toward ReasonML, and it got the traction. But recently, the core team made a sudden step and released ReScript: the third syntax in a row that no longer 100% compatible with OCaml AST. At the same time, ReasonML and OCaml BS were deprecated. This happened in a single day, and many people (including me) were left with projects written in deprecated languages. The community was fragmented again:

BS OCaml is killed
ReasonML is forked now and maintained by others, slowly-slowly shifting toward OCaml
ReScript is the new official, but have a minimal user base

Yes, there are tools to almost automatically convert ReasonML to ReScript (which look very similar at the bottom line). But I haven't done it because I not sure what else harsh steps the core team might perform, and I have many things to polish before such risky updates. I'm waiting for some clarification and opacity. AFAIK, some Facebook funds are floating around ReScript (formerly around ReasonML), and it can be abandoned if Facebook will stop investing. It might be a good idea to hold on and see the direction of evolution and try to guess Facebook's rationale.

Expo as app platform

Is React Native enough to get a working app targeted to multiple platforms? Technically it is. But apart from UI, an app is likely to require some other features from the device: the camera, file system, location, or something like this. Here comes Expo. It's a platform built on top of React Native, which provides access to APIs mentioned in a cross-platform fashion.

My game uses the minimum of such APIs (splash screen, local storage, OpenGL interface). Still, even with such small requirements for me, a programmer who develops for mobile for the first time, Expo is very valuable and simplifies the standard tasks.

API access is cool, but the most critical thing Expo offers is the OTA (Over the Air) updates. Do you realize that mobile apps are much more familiar to the good old desktop apps in the sense of deployment? You publish an update and don't know when a user will update your app and whether they are going to update it at all. Things get worse if your app is a client to some online service: evolving the service, you always have to keep in mind that some clients can use the one-year-old stale version of your app. In the case of Google Play Store, even if the users are eager to get new features, any new version has to pass moderation, which takes some random amount of time between two hours and several days. Albeit not a secret, it might come surprising for a web-developer that the deployment takes days, not seconds.

OTA updates help a lot here. When you publish an update, an incremental changeset is generated and stored on Expo's CDN (or your CDN if you want). Then, when a user launches your app, it downloads the required updates in the background, and the next time the app is restarted, the user sees its latest version. All this without waiting for Google Play moderators or the mass app update night.

Another invaluable thing Expo offers is its mobile app to quickly preview what you get on the device without the full build/reinstall/restart cycles. Make a change, wait a few seconds, and you see almost the same result you'll get if you build a stand-alone APK.

Last but not least, Expo provides its build server facilities to bundle the app for Android or iOS without having the respective toolchains installed. This provides a quick start and simplifies CI configuration. You can build locally if you want, but in my case, at least in theory, the feature will allow building for iOS without having to buy a MacBook (I use Arch, BTW): iPhone stolen from my wife would be enough for tests.

In summary, Expo adds a lot to the React Native base. It is a for-profit project which introduces another little layer of WTF's and bugs, and at the same time, Expo offers an obvious way to eject if you want to jump off, and the benefits it gives are greatly outweighing the costs.

Version hell

One problem you should be mentally prepared for is package version hell. Do you remember that the ReScript platform (e.g. version 8.4.0) and ReasonML (e.g. version 3.6.0) are different things? To work with React a binding library is required (e.g. reason-react version 0.9.1 and reason-react-native version 0.62.3). Expo (e.g. version 39.0.0) has its own expectations on the version of react-native (e.g. version 0.63.0), which in turn requires a specific version of react (say, 16.3.1), which can differ from what reason-react wants. I'm not saying reason-expo, react-native-svg, and @reason-react-native/svg are all separate packages with their own versioning rules and dependency styles 🤯

Solving this puzzle is not always a trivial task. In one update, I've come to a situation when Yarn refused to install what I asked in the package.json until I deleted yarn.lock and started over. Not the most pleasant task to work on but so is reality.

Final words

Is it possible to make a full-stack game using only the web development tools of the JavaScript world? Yes, definitely! Does it worth it? It depends. If you have zero knowledge in web development and game development, go with traditional tools like Unity.

If you get some web development background, you can succeed with familiar tools. Here's a quick summary of my way:

Scope	Tool	Am I happy	Alternatives to consider
Scene Tree	HTML/SVG/React	Happy	OpenGL, Pixi, Three.js
GUI	React Native	Frustrated	Bare HTML5, Flutter
Functional Language	ReasonML/ReScript	Suspicious happiness	TypeScript, PureScript, Dart
Platform	Expo	Happy if forget about React Native	Cordova, Dart

And have I mentioned my game? I welcome you to the Future if you have a spare hour to kill 😇 I have literally dozens of things to complete yet, but I hope you'll find the game quite playable even in the current state.