null-undefined-option.mdx

title	description	canonical
Null, Undefined and Option	JS interop with nullable and optional values in ReScript	/docs/manual/v11.0.0/null-undefined-option

Null, Undefined and Option

ReScript 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 someAttribute of undefined!

However, the concept of a potentially nonexistent value is still useful, and safely exists in our language.

We represent the existence and nonexistence of a value by wrapping it with the option type. Here's its definition from the standard library:

<CodeTab labels={["ReScript", "JS Output"]}>

type option<'a> = None | Some('a)

// Empty output

It means "a value of type option is either None (representing nothing) or that actual value wrapped in a Some".

Note how the option type is just a regular variant.

Example

Here's a normal value:

<CodeTab labels={["ReScript", "JS Output"]}>

let licenseNumber = 5

var licenseNumber = 5;

To represent the concept of "maybe null", you'd turn this into an option type by wrapping it. For the sake of a more illustrative example, we'll put a condition around it:

<CodeTab labels={["ReScript", "JS Output"]}>

let licenseNumber =
  if personHasACar {
    Some(5)
  } else {
    None
  }

var licenseNumber = personHasACar ? 5 : undefined;

Later on, when another piece of code receives such value, it'd be forced to handle both cases through pattern matching:

<CodeTab labels={["ReScript", "JS Output"]}>

switch licenseNumber {
| None =>
  Console.log("The person doesn't have a car")
| Some(number) =>
  Console.log("The person's license number is " ++ Int.toString(number))
}

var number = licenseNumber;

if (number !== undefined) {
  console.log("The person's license number is " + number.toString());
} else {
  console.log("The person doesn't have a car");
}

By turning your ordinary number into an option type, and by forcing you to handle the None case, the language effectively removed the possibility for you to mishandle, or forget to handle, a conceptual null value! A pure ReScript program doesn't have null errors.

Interoperate with JavaScript undefined and null

The option type is common enough that we special-case it when compiling to JavaScript:

<CodeTab labels={["ReScript", "JS Output"]}>

let x = Some(5)

var x = 5;

simply compiles down to 5, and

<CodeTab labels={["ReScript", "JS Output"]}>

let x = None

var x;

compiles to undefined! If you've got e.g. a string in JavaScript that you know might be undefined, type it as option<string> and you're done! Likewise, you can send a Some(5) or None to the JS side and expect it to be interpreted correctly =)

Caveat 1

The option-to-undefined translation isn't perfect, because on our side, option values can be composed:

<CodeTab labels={["ReScript", "JS Output"]}>

let x = Some(Some(Some(5)))

var x = 5;

This still compiles to 5, but this gets troublesome:

<CodeTab labels={["ReScript", "JS Output"]}>

let x = Some(None)

var Caml_option = require("./stdlib/caml_option.js");

var x = Caml_option.some(undefined);

(See output tab).

What's this Caml_option.some thing? Why can't this compile to undefined? Long story short, when dealing with a polymorphic option type (aka option<'a>, for any 'a), many operations become tricky if we don't mark the value with some special annotation. If this doesn't make sense, don't worry; just remember the following rule:

• Never, EVER, pass a nested option value (e.g. Some(Some(Some(5)))) into the JS side.
• Never, EVER, annotate a value coming from JS as option<'a>. Always give the concrete, non-polymorphic type.

Caveat 2

Unfortunately, lots of times, your JavaScript value might be both null or undefined. In that case, you unfortunately can't type such value as e.g. option<int>, since our option type only checks for undefined and not null when dealing with a None.

Solution: More Sophisticated undefined & null Interop

To solve this, we provide access to more elaborate null and undefined helpers through the Nullable module. This somewhat works like an option type, but is different from it.

Examples

To create a JS null, use the value Nullable.null. To create a JS undefined, use Nullable.undefined (you can naturally use None too, but that's not the point here; the Nullable.* helpers wouldn't work with it).

If you're receiving, for example, a JS string that can be null and undefined, type it as:

<CodeTab labels={["ReScript", "JS Output"]}>

@module("MyConstant") external myId: Nullable.t<string> = "myId"

// Empty output

To create such a nullable string from our side (presumably to pass it to the JS side, for interop purpose), do:

<CodeTab labels={["ReScript", "JS Output"]}>

@module("MyIdValidator") external validate: Nullable.t<string> => bool = "validate"
let personId: Nullable.t<string> = Nullable.make("abc123")

let result = validate(personId)

var MyIdValidator = require("MyIdValidator");
var personId = "abc123";
var result = MyIdValidator.validate(personId);

The return part "wraps" a string into a nullable string, to make the type system understand and track the fact that, as you pass this value around, it's not just a string, but a string that can be null or undefined.

Convert to/from option

Nullable.fromOption converts from a option to Nullable.t. Nullable.toOption does the opposite.