| title |
|---|
Common 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.
Immutable on both sides, as expected. BuckleScript String API. JS String API.
OCaml string is an immutable byte sequence. If the user types some unicode:
Js.log "你好"Js.log("你好")It'll compile to the following JS:
console.log("\xe4\xbd\xa0\xe5\xa5\xbd");Which gives you cryptic console output. To rectify this, BuckleScript exposes a special js annotation to the default quoted string syntax built into the language. Use it like this:
Js.log {js|你好，
世界|js}Js.log({js|你好，
世界|js})This'll correctly output:
console.log("你好，\n世界");For convenience, we also expose another special tag quoted string annotation, j, which supports the equivalent of JS' string interpolation, but for variables only (not arbitrary expressions):
let world = {j|世界|j}
let helloWorld = {j|你好，$world|j}let world = {j|世界|j};
let helloWorld = {j|你好，$world|j};You can surround the variable in parentheses too: {j|你好，$(world)|j}.
BuckleScript floats are JS numbers, vice-versa. The OCaml standard library doesn't come with a Float module. JS Float API is here.
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.
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.
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!
Since BuckleScript 3, OCaml/Reason bool now compile to JS boolean.
Since BuckleScript v7, OCaml/Reason records map directly to JS objects. If records contain any Non-Shared data types (like variants), then these values must be transformed separately and cannot be directly used in JS.
Variants (including option and list), BuckleScript objects 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.
However, for BuckleScript related data types, we provide generation of converters and accessors. Once you convert e.g. variants to a string, you can naturally use them on the JS side.
For list, use Array.of_list and Array.to_list in the Array module. option will be highlighted shortly later on and also has its dedicated section as well.
For a seamless JS / TypeScript / Flow integration experience, you might want to use genType instead of doing convertion by hand.
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.
| OCaml/BS/Reason Type | JavaScript Type |
|---|---|
| int | number |
| nativeint | number |
| int32 | number |
| float | number |
| string | string |
| array | array |
| tuple | array. (3, 4) -> [3, 4] |
| bool | boolean |
| Js.Nullable.t | null/undefined |
| option | None -> undefined |
| option | Some( Some .. Some (None)) -> internal representation |
| option | Some other -> other |
| record | object. {x: 1; y: 2} -> {x: 1, y: 2} |
special bs.deriving abstract record |
object |
Again, the representations are subject to change.
| OCaml/BS/Reason Type | JavaScript Value |
|---|---|
| int64 | array. [high, low]. high is signed, low unsigned |
| char | 'a' -> 97 |
| bytes | number array (we might encode it as buffer in NodeJS) |
| list | [] -> 0, [x, y] -> [x, [y, 0]], [1, 2, 3] -> [ 1, [ 2, [ 3, 0 ] ] ] |
| Variant | * |
| Polymorphic variant | ** |
| exception | - |
| extension | - |
| object | - |
* Variants with a single non-nullary constructor:
type tree = Leaf | Node of int * tree * tree
(* Leaf -> 0 *)
(* Node a b c -> [a, b, c] *)type tree = Leaf | Node(int, tree, tree);
/* Leaf -> 0 */
/* Node a b c -> [a, b, c] */Variants with more than one non-nullary constructor:
type u = A of string | B of int
(* A a -> [a].tag = 0 -- tag 0 assignment is optional *)
(* B b -> [b].tag = 1 *)type u = A(string) | B(int);
/* A(a) -> [a].tag = 0 -- tag 0 assignment is optional */
/* B(b) -> [b].tag = 1 */** Polymorphic Variant:
`a (* 97 *)
`a (1, 2) (* [ 97, [1, 2] ] *)`a /* 97 */
`a(1, 2) /* [ 97, [1, 2] ] */BuckleScript compiles unit to 0 in some cases but don't worry about it because it's considered internal and subject to change.