Interop

📄️ Overview

"Interop" (short for "interoperability"), in the context of BuckleScript, means communicating with JavaScript. One of BuckleScript's major goals is to interop as smoothly as possible with JS across the stack.

📄️ Cheatsheet

The next few sections will cover these in detail. Feel free to skip this one if nothing makes sense yet!

📄️ Embed Raw JavaScript

We're introducing this last-resort escape hatch first, in case you're ever stuck trying the other more legitimate APIs and wanna move on. Here's how you can drop a chunk of JavaScript right into your BuckleScript file:

📄️ Common Data Types

Shared Data Types

📄️ Intro to External

Many parts of the interop system uses a concept called external, so we'll specially introduce it here.

📄️ Bind to Global Values

Do you want to use window? Or Math? Or anything that you don't have to first import or require in JavaScript? This section describes how to access those from BuckleScript.

📄️ Null, Undefined & Option

BuckleScript itself doesn't have the notion of null or undefined. This is a great thing, as it wipes out an entire category of bugs. No more undefined is not a function, and cannot access foo of undefined!

📄️ Object

JavaScript objects are used for two major purposes:

📄️ Object 2

There's an alternative of binding to JavaScript objects, if the previous section's bs.deriving abstract doesn't suit your needs:

📄️ Class

new

📄️ Function

Modeling a JS function is like modeling a normal value:

📄️ Property access

Binding to Getter/Setter using bs.get, bs.set.

📄️ Return value wrapping

In general, the FFI code is error prone, and potentially will leak in

📄️ Import & Export

Export

📄️ Regular Expression

See the Reason documentation on Regular Expression

📄️ Exceptions

In the JS world, exception could be any data, while an OCaml exception is a structured data format and supports pattern matching. Catching an OCaml exception on JS side therefore doesn't work as intended.

📄️ JSON

There are several ways to work with JSON right now, that we'll unify and polish very soon.

📄️ Pipe First

BuckleScript has a special |. (or -> for Reason) pipe syntax for dealing with various situations. This operator has many uses.

📄️ Generate Converters & Helpers

Sometimes, you might want to generate e.g. function accessors from a variant declaration, or a Js.t object + converter functions from a record definition. BuckleScript comes with a few annotations that allow you to generate those.

📄️ Better Data Structures Printing (Debug Mode)

You might have seen that using Js.log to print records, variants and others don't print out record field names and variant tags. Record, for example, is compiled into an array (the field names are removed). This is partially for performance, and partially because of [insert excuse here].