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

#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

RE
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

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

into your bsconfig.json.

#Pipe First

The argument order of Belt functions follows the "Pipe 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 "Pipe First" argument order and the trade-offs compared to "Pipe Last", see this blog post.

Example:

RE
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.:

RE
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:

RE
["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

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:

RE
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.

RE
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.