BuckleScript Gradual Typing: Incremental Change

IN THE previous post, I showed a basic example of overlaying an OCaml type over a dynamically-typed JavaScript function, using BuckleScript's FFI feature. In this post, I will show a slightly more complex example: binding to the Web API's Intl.DateTimeFormat constructor. As usual, you can follow along by typing and pasting code into the BuckleScript playground.

In JavaScript, we would use the constructor like:

const format =
  new Intl.DateTimeFormat("en-CA", { hour12: false });

We do need to note, though, that both of the arguments to Intl.DateTimeFormat are optional, and will be given default values if they are not passed in. So really in our BuckleScript binding we want to somehow make them optional as well.

Fortunately, OCaml and BuckleScript allow for optional function parameters, as long as we make the final parameter non-optional:

type dateTimeFormat

external dateTimeFormat_make :
  ?locales:'locales -> ?options:'options -> unit -> dateTimeFormat =
  "Intl.DateTimeFormat" [@@bs.new]

let format =
  dateTimeFormat_make
    ~locales:"en-CA" ~options:[%obj { hour12 = false }] ()


We introduce several new concepts here:

type dateTimeFormat is an abstract type that, for now, is defined only by the fact that we create values of the type with:

external dateTimeFormat_make ... is a binding to a constructor (thanks to the [@@bs.new] attribute) which takes optional locales and options arguments, a required unit argument, and returns an instance of dateTimeFormat. The optional parameters are marked by the '?' symbol.

let format = ... is a usage of the dateTimeFormat_make FFI binding to force BuckleScript to actually generate a call to the Intl.DateTimeFormat constructor. By default BuckleScript only generates JavaScript output lazily.

In the spirit of gradual typing, I've also been lazy about working out the actual types of the parameters to the dateTimeFormat_make binding. Partly it's because the free type variables 'locales and 'options allow me to pass in any type of argument into those slots. In the previous snippet, I passed in the correct types (a string and a JavaScript object with a valid keyword) intentionally, but there is no type-level guarantee that I have to do so. I could have passed in values of invalid types, and BuckleScript would merrily generate JavaScript which would only fail at runtime.

So how can I force some more measure of type safety into the bindings here? Well, for the locales parameter, the Web API reference for Intl.DateTimeFormat says its type has to be either a string or an array of strings. In BuckleScript, we can model this 'either-or' scenario using the [@bs.unwrap] attribute:

external dateTimeFormat_make :
  ?locales:([ `one of string | `many of string array ] [@bs.unwrap]) ->
  ?options:'options ->
  unit ->
  dateTimeFormat =
  "Intl.DateTimeFormat" [@@bs.new]

let formatOne = dateTimeFormat_make ~locales:(`one "en-CA") ()

let formatMany = dateTimeFormat_make ~locales:(`many [|"en-US"; "en-CA"|]) ()

Now, we can pass locales only as a single string or as an array of strings. Anything else is a type error. The compiler does need some help though, to statically tell the difference; hence we have to use polymorphic variants to differentiate one case from the other.

Note that I left out the options argument in these cases to make them simpler. If you paste this into the playground, you'll see BuckleScript generates undefined arguments in their place.

This post is getting rather long now, so I'll explore how to make the options argument more type-safe in the next one. It's going to be quite fun, because there's quite a lot we can do in BuckleScript to enforce the business rules of the API at the type level!