Standard Library

Advanced

Common Data Types

Shared Data Types

BuckleScript's primitives such as string, float, array and a few others have a rather interesting property: they compile to the exact same thing in JavaScript! Thanks to this, there's close to no API to learn for these data types.

This means that if you receive e.g. a string from the JS side, you can use it without conversion on the BS side, and vice-versa. In other words, string and others are "guaranteed public representations".

P.S. if you need an overview of the language primitives themselves, see the Reason docs.

BuckleScript uses the same standard library as OCaml; see the docs here (in Reason syntax). Additionally, we provide access to all the familiar JS primitives here. You can mix and match these two.

Float

Int

Ints are 32-bits! Be careful, you can potentially treat them as JS numbers and vice-versa, but if the number's large, then you better treat JS numbers as floats. For example, we bind to Js.Date using floats. Js Int API here.

Array

Idiomatic OCaml arrays are supposed to be fix-sized. This constraint is relaxed on the BuckleScript size. You can change its length using the usual JS Array API. BuckleScript's own Array API is here.

Tuple

OCaml tuples are compiled to JS arrays. Convenient when you're interop-ing with a JS array that contains heterogeneous values, but happens to have a fixed length. Model it as a tuple on the BS side!

Bool

Since BuckleScript 3, OCaml/Reason bool now compile to JS boolean.

Non-shared Data Types

Record, variant (including option and list), object and others can be exported as well, but you should not rely on their internal representation on the JS side. Aka, don't grab a BS list and start manipulating its structure on the JS side.

For list, use Array.of_list and Array.to_list in the Array module. option will be treated later on.

Design Decisions

As to why we don't compile list to JS array or vice-versa, it's because OCaml array and JS array share similar characteristics: mutable, similar read/write performance, etc. List, on the other hand, is immutable and has different access perf characteristics.

The same justification applies for records. OCaml records are fixed, nominally typed, and in general doesn't work well with JS objects. We do provide excellent facilities to bind to JS objects in the object section.