DEV Community: RawToast

Abstraction & Type-Safety using Singleton Variants

RawToast — Sat, 15 Feb 2020 05:23:43 +0000

Variants are sold as one of Reason's more powerful features, often demonstrated to show polymorphic pattern matching; however, they have another interesting use case by boxing datatypes as singleton variants to create something similar to a Value Class or newtype.

From previous with Scala I am used to creating Value Classes, which can be compared to Haskell's newtype. These constructs allow the developer to express greater levels of type information and abstraction in their code, with little or no runtime performance penalty. It's possible to achieve the same effect in ReasonML with singleton variants.

What is a Value Class?

A value class is a simple wrapper around a primitive type that gives you more control over the input and output of functions. This has a number of benefits, such as restricting construction to validated values or simply aiding with passing around many parameters into a function.

These are very easy to construct in Scala by extending AnyVal

case class Name(value: String) extends AnyVal

Whilst it looks like there is an additional overhead here; after all, the String has been boxed inside a class which you would expect would need to be instantiated each time – in the JVM the wrapping class is removed after compilation. So there should not be a performance cost when wrapping types in this manner. There is just one minor issue, if you wish to access the underlying String then you have to manually access it:

val name = Name("Cat")

println("The name is: " + name.value)

You can achieve something similar in ReasonML by boxing the type within a single-argument variant, which I'll demonstrate later.

Why would you want to do this?

Essentially to make your code more descriptive and to prevent mistakes. This is probably best illustrated with examples. So let us imagine you have a function type signature for a simple function to create a person:

let makePerson: (string, string, string, int) => unit;

As simple as the definition is, it may leave you wondering about a number of things: how do you distinguish between the meaning of these fields? Which holds the first name and which the surname? Just what exactly is that integer? Why are there three string parameters?

Sure, you could probably work those questions out by looking at the output type, and yes, I deliberately left it as unit to make life hard. Still, this function could be storing its output in a database or mutable dictionary somewhere and unit could be an acceptable output type.

So in order to answer that question, you may wish to use named parameters instead. And that's a reasonable solution:

let makePerson: (
  ~firstName: string,
  ~surname: string, 
  ~hometown: string, 
  ~age: int
) => unit

Now at least you can identify what goes where and it would be acceptable to finish here. Still, this has some minor issues that can be addressed. For example, you could accidentally pass in a name into the hometown field.

Another alternative would be to use type aliases for the fields, which would make the method more descriptive without the overhead of typing the labels each time:

type firstName = string;
type surname = string;
type hometown = string;
type age = int;

let makePerson: (
  firstName,
  surname, 
  hometown, 
  age) => unit

Whilst very readable, this code is no safer than the original implementation. Aliases don't provide any protection and you can pass any string as any of the function's parameters.

In both solutions, the string type is still being used for three different things; however, in Scala is possible to abstract the string away by using Value Classes. Let's quickly demonstrate that:

case class FirstName(value: String) extends AnyVal
case class Surname(value: String) extends AnyVal
case class Hometown(value: String) extends AnyVal
case class Age(value: String) extends AnyVal

abstract def makePerson(
  firstName: FirstName,
  surname: Surname, 
  hometown: Hometown,
  age: Age): Person

// Or if you simply wanted to use a constructor
case class Person(
  firstName: FirstName,
  surname: Surname, 
  hometown: Hometown,
  age: Age)

In the above example, unlike simple type aliases, you cannot pass a FirstName into say the Hometown field. Each of those types is independent of the primitive type it wraps.

So how do we do this in Reason?

So how do we do this in Reason? Well, we can box the primitive types within single-argument variants.

type firstName = FirstName(string);
type surname = Surname(string);
type hometown = Hometown(string);
type age = Age(int);

let makePerson: (
  firstName,
  surname, 
  hometown, 
  age) => unit = (a, b, c, d) => ();

Now it isn't possible to accidentally pass in a hometown as a surname, any such mistake would cause the program to not compile. Whilst this is only a simple example, this becomes more useful the bigger your solution gets. Anywhere else in the codebase it would no longer be possible to mistake a surname for a string or an age for an int.

A common situation for this in a larger application is for id fields. You may end up with int being used for a user id, post id, account id, payment id, group id, and so on. If these types are abstracted within singleton variants, then we can differentiate between the types.

Now, at some point, you will need to unbox the values from these singleton variants. You could use a switch, but that's a little long-winded. Instead, try using fun instead:

let name = FirstName("Dave");

let nameString = name |> fun | FirstName(str) => str;

Isn't there a performance cost?

Unlike Scala, the above example can come with a penalty. In older versions of Reason, it will construct the variant as a single argument array. Accessing the value in the code above is like accessing an array using myArray[0]. For example, if you use one of the online Reason editors the above name construction may compile to:

var name = /* FirstName */["Dave"];

However, since Bucklescript release 7.1.0 we are able to use unboxed to get around this! What is this? Let's look at the OCaml manual:

unboxed can be used on a type definition if the type is a single-field record or a concrete type with a single constructor that has a single argument. It tells the compiler to optimize the representation of the type by removing the block that represents the record or the constructor (i.e. a value of this type is physically equal to its argument).

This now means a singleton variant is not compiled as an array but is instead unboxed to the underlying type. Essentially, like with Scala, the OCaml compiler will erase the singleton variant in a later stage of compilation as it's not required at runtime. To use this mark the type as [@unboxed] like so:

[@unboxed]
type hometown = Hometown(string);
let tokyo = Hometown("tokyo");

This will then be unboxed from the array during compilation:

var tokyo = "tokyo";

So no more performance penalties! According to the release notes, this can also be used to unbox singleton records. Note, that whilst the release notes are for development version, this feature was released with bs-platform@7.1.0.

Whether you prefer to use singleton variants or records for this is a personal choice. I've included a small demonstration of using singleton records for this at Itazura.io.

Dependency Injection in ReasonML using Modules

RawToast — Fri, 31 Jan 2020 08:23:38 +0000

When I wrote my first project in ReasonML I just imported modules from anywhere as that just seemed to be the way things were done. This was fine when writing a simple React frontend, but when I later wrote the more complex backend for Bouken it didn't scale and quickly became messy and hard to test.

I was used to using dependency injection – often known as DI – as a pattern from writing Java and Scala, which is a pattern that enables inversion of control. Or more simply put, constructing an object or module from other modules/objects and using the functions provided.

Now in ReasonML functors – functions from modules to modules – can be used to implement dependency injection. Functors can be used for more advanced techniques, such as creating modules that parameterise other modules; however, this is a good introduction to the module system. When I first used this technique the language server failed to understand what I was doing! Thankfully, that issue been fixed!

Why would you want to use dependency injection? Well, for example, you could have a service that uses another module to make a call to an API:

module MyService = {
  let userAndComments = id => { 
     let user = UserApi.userById(id);
     switch(user) {
       | Some(user) => { 
       let comments = CommentsApi.fetchUserComments(id);    
       Some({ user.name, comments });
       }
       | None => None
     }
   };
};

The code should work fine, but are a few issues with this:

It can lead to a spiderweb of dependencies.
It can be hard to unit test, in this example you cannot test the userAndComments method without making an HTTP call. In order to test this module, you would require either a mocked server or an integration test.

We can use dependency injection to control what the service receives in order to facilitate easier unit testing. So how would we go about that?

First, let define a type that we can inject. This is a simple type definition for logging output.

module type Logger = {
  let log: string => unit;
};

Then we can create a new module that uses the Logger we have defined. In OCaml and Reason a module that is built from other modules is known as a Functor.

module GreetingService = (LOG: Logger) => {
  let sayHello = name => LOG.log("Hello " ++ name); 
};

Now we can implement a logger and pass it into a GreetingService: creating a module from another module.

module ConsoleLogger = {
  let log = loggable => Js.Console.log(log);
};

module ConsoleGreeter = GreetingService(ConsoleLogger);

ConsoleGreeter.sayHello("World");

Note that we are free to choose how the Logger works – it only has to match the type signature. For example, you could implement an ErrorLogger instead:

module ErrorLogger = {
  let log = loggable => Js.Console.error(log);
};

Effectively we have taken away control from GreetingService to Logger. Now GreetingService describes what it wants to do, but doesn't actually implement how to do it. This is often referred to as inversion of control.

When writing systems in a modern object-oriented style using programming languages such as Java or Kotlin, this technique is heavily used. Often you will read that you should:

"prefer composition over inheritance"

...and DI is used to alongside composition to create cleaner more testable code.

This pattern can be used in ReasonML (and OCaml), by using functors for dependency injection. Lets, go back to the original example to demonstrate this

Updating the Original Service

Remember this? It's the MyService module from the first example.

module MyService = {
  let userAndComments = id => { 
     let user = UserApi.userById(id);
     switch(user) {
       | Some(user) => { 
       let comments = CommentsApi.fetchUserComments(id);    
       Some({ user.name, comments });
       }
       | None => None
     }
   };
};

We can turn MyService into a functor and construct an instance by passing module types for UserApi and CommentsApi.

module MyService = (Users: UserApi, Comments: CommentsApi) => {
  let userAndComments = id => { 
    let user = Users.userById(id);
    switch(user) {
      | Some(user) => { 
      let comments = Comments.fetchUserComments(id);    
      Some({ user.name, comments });
      }
     | None => None
    }
  };
};

Now, this module is easier to unit test. You can pass in stubbed versions of the modules in order to test the flow of the userAndComments function.

module StubUserApi = {
  let userById = id => switch(id) {
    | 1 => Some({ name: "Test User"})
    | _ => None
  };
};

module StubCommentsApi = {
  let fetchUserComments = id => 
    { title: "Test Comment", message: "Hello" };
};

Now it's easy to test the service using these simple stubbed modules:

module UnderTest = MyService(StubUserApi, StubCommentsApi);

let result = UnderTest.userAndComments(1); // Some({ ...
let anotherResult = Undertest.userAndComment(2); // None

I started using this technique partway through building Bouken. As previously stated, I initially imported modules from anywhere as that seemed to be the way things were done and worked for my frontend logic. Shortly afterwards, the game loop became unwieldy and needed breaking up.

Over time the more complex modules were broken down into smaller modules for easier testing and code management. This eventually turns into a dependency tree of module types. For example, the main game builder is defined as follows:

module CreateGame: (
  Types.GameLoop, 
  Types.World, 
  Types.WorldBuilder
) => (Types.Game) = (
    GL: Types.GameLoop, 
    W: Types.World, 
    WB: Types.WorldBuilder
  ) => { };

// Which is built from a
module CreateGameLoop = (
  Pos: Types.Positions, 
  EL: EnemyLoop
) => { };

module CreateEnemyLoop = (
  Pos: Types.Positions, 
  Places: Types.Places, 
  World: World
) => { };

Note that I chose to prefix the module names with CreateX, as they create a module that matches a module type name. I don't know what the preference is for calling these modules in Reason/OCaml, but it was a long-running debate in Java and C#...

So as demonstrated, you can use Reason's advanced module system for dependency injection. Whilst DI is often mentioned in object-oriented development – you do not need to use objects! Instead, use modules for organising your code and leave objects alone until you absolutely require open types or inheritance. In fact, DI is used in functional programming, often by using the Reader Monad or some construct derived from the Reader Monad such as RIO.

Based on a post initially published at itazura.io

Immutable Updates of Objects in Reason

RawToast — Tue, 28 Jan 2020 06:02:10 +0000

I've recently been playing around with objects in ReasonML and reading about using them in OCaml to get a better understanding, as there is a lack of good documentation on their use in Reason. So I thought I'd try and writing something about one of the interesting and lesser-known features of objects in ReasonML.

I am sure none of this will come as a surprise to a seasoned OCaml developer, but like many developers, I have no experience with Ocaml and keep finding out new features that can also used in our projects.

In ReasonML the spread operator is a great piece of syntactic sugar that makes immutable updates quick to implement, similar to the copy method of case classes in Scala. I was happy to find out that this was also possible with objects, allowing the creation of immutable, but updatable, objects. In OCaml, these are known as functional objects.

Most ReasonML developers have come across the syntax below to update immutable records:

type cat = {name: string, age: int};

let kitten = { name: "Charles", age: 1 };

let oldCat = { ...kitten, age: 4 };

A similar technique exists for objects; however, it's not so well known amongst Reason developers, as I believe it is not included in the documentation. So at first, you might attempt something like the example below, which works but quickly becomes verbose as your records grow in size:

class immutableDog(name, age) = {
  as _;
  pub getAge: int = age;
  pub getName: string = name;
  pub setName: string => immutableDog = newName => new immutableDog(newName, age);
  pub setAge: int => immutableDog = newAge => new immutableDog(name, newAge);
};

Instead, you can override values to make a new instance with only the specified updates, similar to records. The syntax is not so obvious:

class immutableCat(name, age) = {
  as _;
  val name = name;
  val age = age;
  pub getAge: int = age;
  pub getName: string = name;
  pub setName = newName => {<name: newName>}; // Creates a new instance.
  pub setAge = newAge => {<age: newAge>};
};

I believe this syntax is known as the override construct {< ... >}, which returns a copy of the current object and allows you to override the value of instance variables or methods.

Let's see what it looks like in action:

let myImmutableCat: immutableCat = new immutableCat("Cool Cat", 5);
let myNewCat: immutableCat = myImmutableCat#setName("Dave"); // does not change myImmutableCat

It is also possible to update values in the same way:

class immutable = (number) => {
  as _;
  val counter = number * number;
  pub makeNegative = {<counter: -counter>};
  pub getCounter = counter;
};

let myImmutable = new immutable(4);
let negative = myImmutable#makeNegative;
myImmutable#getCounter // 4
negative#getCounter // -16

Thanks for reading, I hope you found this post useful and legible!

Based on a post in a series on using objects in Reason at itazura.io