Belt

The preferred standard library for Reason when targeting JavaScript (browser, node, React Native).

It is recommended to use the modules from Belt rather than from the OCaml standard library or from the Js namespace, e.g. use Belt.List instead of List or Js.List and Belt.Array instead of Array or Js.Array.

Belt is currently mostly covering collection types. It has no string or date functions yet, although Belt.String is in the works. (In the meantime, use Js.String for string functions and Js.Date for date functions.)

Motivation

Belt aims to improve the user experience for Reason developers targeting JavaScript as well as for JavaScript developers learning Reason, since the original OCaml standard library was not written with JS in mind.

To achieve this, Belt provides:

A consistent naming convention familiar to JS developers (camelCase)
A consistent argument order familiar to JS Developers (see Pipe First)
Safety by default: A Belt function will never throw exceptions, unless it is indicated explicitly in the function name (suffix "Exn").
Better performance and smaller code size running on the JS platform
Ready for Tree Shaking

Usage

To use modules from Belt, either refer to them by their fully qualified name (Belt.List, Belt.Array etc.) or open the Belt module by putting


open Belt;

at the top of your source files. After opening Belt this way, Array will refer to Belt.Array, List will refer to Belt.List etc. in the source code below.

If you want to open Belt globally for all files in your project instead, you can put


  "bsc-flags": [ "-open Belt" ],

into your bsconfig.json.

Pipe First

The argument order of Belt functions follows the "Data-First" convention. I.e. the object they act on (e.g. a list or an array) will always be the first argument.

This way, the pipe first operator -> can be used nicely with the Belt APIs, giving a similar feel to method invocations in OOP languages and allowing easy chaining of Belt API calls.

For more information about the data-first argument order and the trade-offs compared to data-last, see this blog post.

Example:


let someNumbers = [|1, 1, 4, 2, 3, 6, 3, 4, 2|];

let greaterThan2UniqueAndSorted =
  someNumbers
  ->Belt.Array.keep(x => x > 2)
  /* convert to and from set to make values unique */
  ->Belt.Set.Int.fromArray
  ->Belt.Set.Int.toArray; /* output is already sorted */

Js.log2("result", greaterThan2UniqueAndSorted);

Curried vs. Uncurried Callbacks

For functions taking a callback parameter, there are usually two versions available:

curried (no suffix)
uncurried (suffixed with U)

E.g.:


let forEach: (t('a), 'a => unit) => unit;

let forEachU: (t('a), (. 'a) => unit) => unit;

The uncurried version will be faster in some cases, but for simplicity we recommend to stick with the curried version unless you know what you are doing and really need the optimization.

The two versions can be invoked as follows:


["a", "b", "c"]->Belt.List.forEach(x => Js.log(x));

["a", "b", "c"]->Belt.List.forEachU((. x) => Js.log(x));

Specialized Collections

For collections types like set or map, Belt provides both a generic module as well as specialized, more efficient implementations for string and int keys.

For example, Belt has the following set modules:

Implementation Details

Array access runtime safety

One common confusion comes from the way Belt handles array access. It differs from than the default standard library's.

RE
let letters = [|"a", "b", "c"|];
let a = letters[0]; /* a == "a" */
let capitalA = Js.String.toUpperCase(a);
let k = letters[10]; /* Raises an exception! The 10th index doesn't exist. */

Because Belt avoids exceptions and returns options instead, this code behaves differently:

RE
open Belt;
let letters = [|"a", "b", "c"|];
let a = letters[0]; /* a == Some("a") */
let captialA = Js.String.toUpperCase(a); /* Type error! This code will not compile. */
let k = letters[10]; /* k == None */

Although we've fixed the problem where k raises an exception, we now have a type error when trying to capitalize a. There are a few things going on here:

Reason transforms array index access to the function Array.get. So letters[0] is the same as Array.get(letters, 0).
The compiler uses whichever Array module is in scope. If you open Belt, then it uses Belt.Array.
Belt.Array.get returns values wrapped in options, so letters[0] == Some("a").

Fortunately, this is easy to fix:

RE
open Belt;
let letters = [|"a, "b, "c"|];
let a = letters[0];

/* Use a switch statement: */
let capitalA =
  switch(a) {
    | Some(a) => Some(Js.String.toUpperCase(a))
    | None => None
  };
  
/* Alternatively, use the Option module: */
let capitalA = a->Option.map(Js.String.toUpperCase);

let k = letters[10]; /* k == None */

With that little bit of tweaking, our code now compiles successfully and is 100% free of runtime errors!

A special encoding for collection safety

When we create a collection library for a custom data type we need a way to provide a comparator function. Take Set for example, suppose its element type is a pair of ints, it needs a custom compare function that takes two tuples and returns their order. The Set could not just be typed as Set.t (int * int) , its customized compare function needs to manifest itself in the signature, otherwise, if the user creates another customized compare function, the two collection could mix which would result in runtime error.

The original OCaml stdlib solved the problem using functor which creates a big closure at runtime and makes dead code elimination much harder. We use a phantom type to solve the problem:


module Comparable1 =
  Belt.Id.MakeComparable(
    {
      type t = (int, int);
      let cmp = ((a0, a1), (b0, b1)) =>
        switch (Pervasives.compare(a0, b0)) {
        | 0 => Pervasives.compare(a1, b1)
        | c => c
        };
    }
  );

let mySet1 = Belt.Set.make(~id=(module Comparable1));

module Comparable2 =
  Belt.Id.MakeComparable(
    {
      type t = (int, int);
      let cmp = ((a0, a1), (b0, b1)) =>
        switch (Pervasives.compare(a0, b0)) {
        | 0 => Pervasives.compare(a1, b1)
        | c => c
        };
    }
  );

let mySet2 = Belt.Set.make(~id=(module Comparable2));

Here, the compiler would infer mySet1 and mySet2 having different type, so e.g. a merge operation that tries to merge these two sets will correctly fail.


let mySet1: t((int, int), Comparable1.identity);
let mySet2: t((int, int), Comparable2.identity);

Comparable1.identity and Comparable2.identity are not the same using our encoding scheme.