---
title: "API | ReScript"
metaTitle: "API"
description: "The ReScript API documentation"
canonical: "/docs/manual/api"
---

# Introduction

## Stdlib

[Stdlib](/docs/manual/api/stdlib) is ReScript's new builtin standard library.
It will cover just about you need for day-to-day programming in ReScript and covers most of the built in JavaScript API.

## Additional Libraries

ReScript ships with these two additional modules in its standard library:

- [Belt](/docs/manual/api/belt): immutable collections and extra helpers not available in JavaScript / [Stdlib](/docs/manual/api/stdlib).
- [Dom](/docs/manual/api/stdlibdom): Dom related types and modules. Contains our standardized types used by various userland DOM bindings.

---
title: "Array & List"
description: "Arrays and List data structures"
canonical: "/docs/manual/array-and-list"
section: "Language Features"
order: 12
---

# Array and List

## Array

Arrays are the main ordered data structure in ReScript. They can be randomly accessed, dynamically resized, and updated.

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

```res example
let myArray = ["hello", "world", "how are you"]
```

```js
var myArray = ["hello", "world", "how are you"];
```

</CodeTab>

ReScript arrays' items must have the same type, i.e. homogeneous.

### Usage

#### Access

Accessing items in an array will return an `option` and can be done like so:

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

```res example
let myArray = ["hello", "world", "how are you"]

let firstItem = myArray[0] // Some("hello")

let tenthItem = myArray->Array.get(10) // None
```

```js
var myArray = ["hello", "world", "how are you"];

var firstItem = myArray[0];

var tenthItem = myArray[10];
```

</CodeTab>

#### Update

Items in an array can be updated by assigning a value to an index or using a function:

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

```res example
let myArray = ["hello", "world", "how are you"]

myArray[0] = "hey" // now ["hey", "world", "how are you"]

myArray->Array.push("?") //  ["hey", "world", "how are you", "?"]

myArray->Array.set(0, "bye") //  ["bye", "world", "how are you", "?"]
```

```js
var myArray = ["hello", "world", "how are you"];

myArray[0] = "hey";

myArray.push("?");

myArray[0] = "bye";
```

</CodeTab>

### Array spreads

You can spread arrays of the same type into new arrays:

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

```res example
let y = [1, 2]
let x = [4, 5, ...y]
let x2 = [4, 5, ...y, 7, ...y]
let x3 = [...y]
```

```javascript
var y = [1, 2];

var x = [4, 5, ...y];

var x2 = [4, 5, ...y, 7, ...y];

var x3 = [...y];
```

</CodeTab>

## List

ReScript provides a singly linked list too. Lists are:

- immutable
- fast at prepending items
- fast at getting the head
- slow at everything else

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

```res example
let myList = list{1, 2, 3}
```

```js
var myList = {
  hd: 1,
  tl: {
    hd: 2,
    tl: {
      hd: 3,
      tl: 0,
    },
  },
};
```

</CodeTab>

Like arrays, lists' items need to be of the same type.

### Usage

You'd use list for its resizability, its fast prepend (adding at the head), and its fast split, all of which are immutable and relatively efficient.

Do **not** use list if you need to randomly access an item or insert at non-head position. Your code would end up obtuse and/or slow.

For accessing deeper, see [destructuring](./pattern-matching-destructuring.mdx).

#### Immutable Prepend

Use the spread syntax:

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

```res prelude
let myList = list{1, 2, 3}
let anotherList = list{0, ...myList}
```

```js
var myList = {
  hd: 1,
  tl: {
    hd: 2,
    tl: {
      hd: 3,
      tl: 0,
    },
  },
};

var anotherList = {
  hd: 0,
  tl: myList,
};
```

</CodeTab>

`myList` didn't mutate. `anotherList` is now `list{0, 1, 2, 3}`. This is efficient (constant time, not linear). `anotherList`'s last 3 elements are shared with `myList`!

**Note that `list{a, ...b, ...c}` was a syntax error** before compiler v10.1. In general, the pattern should be used with care as its performance and allocation overhead are linear (`O(n)`).

#### Access

`switch` (described in the [pattern matching section](./pattern-matching-destructuring.mdx)) is usually used to access list items:

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

```res example
let message =
  switch myList {
  | list{} => "This list is empty"
  | list{first, second, ...rest} => "The list two items and a potenial remainder of items"
  | list{a, ...rest} => "The head of the list is the string " ++ Int.toString(a)
  }
```

```js
let message =
  myList !== 0
    ? {
        hd: 2,
        tl: {
          hd: 3,
          tl: /* [] */ 0,
        },
      } !== 0
      ? "The list two items and a potenial remainder of items"
      : "The head of the list is the string " + (1).toString()
    : "This list is empty";
```

</CodeTab>

---
title: "Async / Await"
description: "Async / await for asynchronous operations"
canonical: "/docs/manual/async-await"
section: "Language Features"
order: 22
---

{/* This prelude is used in many different followup examples, so we use it to shorten the noise of the example code. */}

<div className="hidden">

```res prelude
@val external fetchUserMail: string => promise<string> = "GlobalAPI.fetchUserMail"
@val external sendAnalytics: string => promise<unit> = "GlobalAPI.sendAnalytics"
```

</div>

{/* See https://github.com/cristianoc/rescript-compiler-experiments/pull/1#issuecomment-1131182023 for all async/await use-case examples */}

# Async / Await

ReScript comes with `async` / `await` support to make asynchronous, `Promise` based code easier to read and write. This feature is very similar to its JS equivalent, so if you are already familiar with JS' `async` / `await`, you will feel right at home.

## How it looks

Let's start with a quick example to show-case the syntax:

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

```res
// Some fictive functionality that offers asynchronous network actions
@val external fetchUserMail: string => promise<string> = "GlobalAPI.fetchUserMail"
@val external sendAnalytics: string => promise<unit> = "GlobalAPI.sendAnalytics"

// We use the `async` keyword to allow the use of `await` in the function body
let logUserDetails = async (userId: string) => {
  // We use `await` to fetch the user email from our fictive user endpoint
  let email = await fetchUserMail(userId)

  await sendAnalytics(`User details have been logged for ${userId}`)

  Console.log(`Email address for user ${userId}: ${email}`)
}
```

```js
async function logUserDetails(userId) {
  var email = await GlobalAPI.fetchUserMail(userId);
  await GlobalAPI.sendAnalytics(
    "User details have been logged for " + userId + "",
  );
  console.log("Email address for user " + userId + ": " + email + "");
}
```

</CodeTab>

As we can see above, an `async` function is defined via the `async` keyword right before the function's parameter list. In the function body, we are now able to use the `await` keyword to explicitly wait for a `Promise` value and assign its content to a let binding `email`.

You will probably notice that this looks very similar to `async` / `await` in JS, but there are still a few details that are specific to ReScript. The next few sections will go through all the details that are specific to the ReScript type system.

## Basics

- You may only use `await` in `async` function bodies
- `await` may only be called on a `promise` value
- `await` calls are expressions, therefore they can be used in pattern matching (`switch`)
- A function returning a `promise<'a>` is equivalent to an `async` function returning a value `'a` (important for writing signature files and bindings)
- `promise` values and types returned from an `async` function don't auto-collapse into a flat promise. See the details below.

## Types and `async` functions

### `async` function type signatures

Function type signatures (i.e defined in signature files) don't require any special keywords for `async` usage. Whenever you want to type an `async` function, use a `promise` return type.

```resi
// Demo.resi

let fetchUserMail: string => promise<string>
```

The same logic applies to type definitions in `.res` files:

```res example
// function type
type someAsyncFn = int => promise<int>

// Function type annotation
let fetchData: string => promise<string> = async (userId) => {
  await fetchUserMail(userId)
}
```

**BUT:** When typing `async` functions in your implementation files, you need to omit the `promise<'a>` type:

```res
// This function is compiled into a `string => promise<string>` type.
// The promise<...> part is implicitly added by the compiler.
let fetchData = async (userId: string): string => {
  await fetchUserMail("test")
}
```

For completeness reasons, let's expand the full signature and inline type definitions in one code snippet:

```res
// Note how the inline return type uses `string`, while the type definition uses `promise<string>`
let fetchData: string => promise<string> = async (userId: string): string {
  await fetchUserMail(userId)
}
```

**Note:** In a practical scenario you'd either use a type signature, or inline types, not both at the same time. In case you are interested in the design decisions, check out [this discussion](https://github.com/rescript-lang/rescript-compiler/pull/5913#issuecomment-1359003870).

### Promises don't auto-collapse in async functions

In JS, nested promises (i.e. `promise<promise<'a>>`) will automatically collapse into a flat promise (`promise<'a>`). This is not the case in ReScript. Use the `await` function to manually unwrap any nested promises within an `async` function instead.

```res
let fetchData = async (userId: string): string => {
  // We can't just return the result of `fetchUserMail`, otherwise we'd get a
  // type error due to our function return type of type `string`
  await fetchUserMail(userId)
}
```

## Error handling

You may use `try / catch` or `switch` to handle exceptions during async execution.

```res
// For simulation purposes
let authenticate = async () => {
  JsError.RangeError.throwWithMessage("Authentication failed.")
}

let checkAuth = async () => {
  try {
    await authenticate()
  } catch {
  | JsExn(e) =>
    switch JsExn.message(e) {
    | Some(msg) => Console.log("JS error thrown: " ++ msg)
    | None => Console.log("Some other exception has been thrown")
    }
  }
}
```

Note how we are essentially catching JS errors the same way as described in our [Exception](./exception.mdx#catch-rescript-exceptions-from-js) section.

You may unify error and value handling in a single switch as well:

```res
let authenticate = async () => {
  JsError.RangeError.throwWithMessage("Authentication failed.")
}

let checkAuth = async () => {
  switch await authenticate() {
  | _ => Console.log("ok")
  | exception JsExn(e) =>
    switch JsExn.message(e) {
    | Some(msg) => Console.log("JS error thrown: " ++ msg)
    | None => Console.log("Some other exception has been thrown")
    }
  }
}
```

**Important:** When using `await` with a `switch`, always make sure to put the actual await call in the `switch` expression, otherwise your `await` error will not be caught.

## Piping `await` calls

You may want to pipe the result of an `await` call right into another function.
This can be done by wrapping your `await` calls in a new `{}` closure.

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

```res example
@val external fetchUserMail: string => promise<string> = "GlobalAPI.fetchUserMail"

let fetchData = async () => {
  let mail = {await fetchUserMail("1234")}->String.toUpperCase
  Console.log(`All upper-cased mail: ${mail}`)
}
```

```js
async function fetchData(param) {
  var mail = (await GlobalAPI.fetchUserMail("1234")).toUpperCase();
  console.log("All upper-cased mail: " + mail + "");
}
```

</CodeTab>

Note how the original closure was removed in the final JS output. No extra allocations!

## Pattern matching on `await` calls

`await` calls are just another kind of expression, so you can use `switch` pattern matching for more complex logic.

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

```res example
@val external fetchUserMail: string => promise<string> = "GlobalAPI.fetchUserMail"

let fetchData = async () => {
  switch (await fetchUserMail("user1"), await fetchUserMail("user2")) {
  | (user1Mail, user2Mail) => {
      Console.log("user 1 mail: " ++ user1Mail)
      Console.log("user 2 mail: " ++ user2Mail)
    }

  | exception JsExn(err) => Console.log2("Some error occurred", err)
  }
}
```

```js
async function fetchData(param) {
  var val;
  var val$1;
  try {
    val = await GlobalAPI.fetchUserMail("user1");
    val$1 = await GlobalAPI.fetchUserMail("user2");
  } catch (raw_err) {
    var err = Caml_js_exceptions.internalToOCamlException(raw_err);
    if (err.RE_EXN_ID === "JsError") {
      console.log("Some error occurred", err._1);
      return;
    }
    throw err;
  }
  console.log("user 1 mail: " + val);
  console.log("user 2 mail: " + val$1);
}
```

</CodeTab>

## `await` multiple promises

We can utilize the `Promise` module to handle multiple promises. E.g. let's use `Promise.all` to wait for multiple promises before continuing the program:

```res
let pauseReturn = (value, timeout) => {
  Promise.make((resolve, _reject) => {
    setTimeout(() => {
      resolve(value)
    }, timeout)->ignore
  })
}

let logMultipleValues = async () => {
  let promise1 = pauseReturn("value1", 2000)
  let promise2 = pauseReturn("value2", 1200)
  let promise3 = pauseReturn("value3", 500)

  let all = await Promise.all([promise1, promise2, promise3])

  switch all {
  | [v1, v2, v3] => Console.log(`All values: ${v1}, ${v2}, ${v3}`)
  | _ => Console.log("this should never happen")
  }
}
```

## JS Interop with `async` functions

`async` / `await` practically works with any function that returns a `promise<'a>` value. Map your `promise` returning function via an `external`, and use it in an `async` function as usual.

Here's a full example of using the MDN `fetch` API, using `async` / `await` to simulate a login:

```res
// A generic Response type for typing our fetch requests
module Response = {
  type t<'data>
  @send external json: t<'data> => promise<'data> = "json"
}

// A binding to our globally available `fetch` function. `fetch` is a
// standardized function to retrieve data from the network that is available in
// all modern browsers.
@val @scope("globalThis")
external fetch: (
  string,
  'params,
) => promise<Response.t<{"token": Nullable.t<string>, "error": Nullable.t<string>}>> =
  "fetch"

// We now use our asynchronous `fetch` function to simulate a login.
// Note how we use `await` with regular functions returning a `promise`.
let login = async (email: string, password: string) => {
  let body = {
    "email": email,
    "password": password,
  }

  let params = {
    "method": "POST",
    "headers": {
      "Content-Type": "application/json",
    },
    "body": Json.stringifyAny(body),
  }

  try {
    let response = await fetch("https://reqres.in/api/login", params)
    let data = await response->Response.json

    switch Nullable.toOption(data["error"]) {
    | Some(msg) => Error(msg)
    | None =>
      switch Nullable.toOption(data["token"]) {
      | Some(token) => Ok(token)
      | None => Error("Didn't return a token")
      }
    }
  } catch {
  | _ => Error("Unexpected network error occurred")
  }
}
```

---
title: "Attribute (Decorator)"
description: "Annotations in ReScript"
canonical: "/docs/manual/attribute"
section: "Language Features"
order: 26
---

# Attribute (Decorator)

Like many other languages, ReScript allows annotating a piece of code to express extra functionality. Here's an example:

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

```res
@inline
let mode = "dev"

let mode2 = mode
```

```js
var mode2 = "dev";
```

</CodeTab>

The `@inline` annotation tells `mode`'s value to be inlined into its usage sites (see output). We call such annotation "attribute" (or "decorator" in JavaScript).

An attribute starts with `@` and goes before the item it annotates. In the above example, it's hooked onto the let binding.

## Usage

> **Note:** In previous versions (< 8.3) all our interop related attributes started with a `bs.` prefix (`bs.module`, `bs.val`). Our formatter will automatically drop them in newer ReScript versions.

You can put an attribute almost anywhere. You can even add extra data to them by using them visually like a function call. Here are a few famous attributes (explained in other sections):

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

```res
@@warning("-27")


@unboxed
type a = Name(string)

@val external message: string = "message"

type student = {
  age: int,
  @as("aria-label") ariaLabel: string,
}

@deprecated
let customDouble = foo => foo * 2

@deprecated("Use SomeOther.customTriple instead")
let customTriple = foo => foo * 3
```

```js

```

</CodeTab>

1. `@@warning("-27")` is a standalone attribute that annotates the entire file. Those attributes start with `@@`. Here, it carries the data `"-27"`. You can find a full list of all available warnings [here](./warning-numbers.mdx).
2. `@unboxed` annotates the type definition.
3. `@val` annotates the `external` statement.
4. `@as("aria-label")` annotates the `ariaLabel` record field.
5. `@deprecated` annotates the `customDouble` expression. This shows a warning while compiling telling consumers to not rely on this method long-term.
6. `@deprecated("Use SomeOther.customTriple instead")` annotates the `customTriple` expression with a string to describe the reason for deprecation.

For a list of all decorators and their usage, please refer to the [Syntax Lookup](../../syntax-lookup/) page.

## Extension Point

There's a second category of attributes, called "extension points" (a remnant term of our early systems):

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

```res
%raw("var a = 1")
```

```js
var a = 1;
```

</CodeTab>

Extension points are attributes that don't _annotate_ an item; they _are_ the item. Usually they serve as placeholders for the compiler to implicitly substitute them with another item.

Extension points start with `%`. A standalone extension point (akin to a standalone regular attribute) starts with `%%`.

For a list of all extension points and their usage, please refer to the [Syntax Lookup](../../syntax-lookup/) page.

---
title: "Bind to Global JS Values"
description: "JS interop with global JS values in ReScript"
canonical: "/docs/manual/bind-to-global-js-values"
section: "JavaScript Interop"
order: 8
---

# Bind to Global JS Values

**First**, make sure the value you'd like to model doesn't already exist in our [provided API](/docs/manual/api/stdlib).

Some JS values, like `setTimeout`, live in the global scope. You can bind to them like so:

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

```res example
@val external setTimeout: (unit => unit, int) => float = "setTimeout"
@val external clearTimeout: float => unit = "clearTimeout"
```

```js
// Empty output
```

</CodeTab>

(We already provide `setTimeout`, `clearTimeout` and others in the [Core API](/docs/manual/api/stdlib) module).

This binds to the JavaScript [`setTimeout`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrworkerGlobalScope/setTimeout) methods and the corresponding `clearTimeout`. The `external`'s type annotation specifies that `setTimeout`:

- Takes a function that accepts `unit` and returns `unit` (which on the JS side turns into a function that accepts nothing and returns nothing aka `undefined`),
- and an integer that specifies the duration before calling said function,
- returns a number that is the timeout's ID. This number might be big, so we're modeling it as a float rather than the 32-bit int.

### Tips & Tricks

**The above isn't ideal**. See how `setTimeout` returns a `float` and `clearTimeout` accepts one. There's no guarantee that you're passing the float created by `setTimeout` into `clearTimeout`! For all we know, someone might pass it `Math.random()` into the latter.

We're in a language with a great type system now! Let's leverage a popular feature to solve this problem: abstract types.

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

```res example
type timerId
@val external setTimeout: (unit => unit, int) => timerId = "setTimeout"
@val external clearTimeout: timerId => unit = "clearTimeout"

let id = setTimeout(() => Console.log("hello"), 100)
clearTimeout(id)
```

```js
var id = setTimeout(function (param) {
  console.log("hello");
}, 100);

clearTimeout(id);
```

</CodeTab>

Clearly, `timerId` is a type that can only be created by `setTimeout`! Now we've guaranteed that `clearTimeout` _will_ be passed a valid ID. Whether it's a number under the hood is now a mere implementation detail.

Since `external`s are inlined, we end up with JS output as readable as hand-written JS.

## Global Modules

If you want to bind to a value inside a global module, e.g. `Math.random`, attach a `scope` to your `val` external:

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

```res example
@scope("Math") @val external random: unit => float = "random"
let someNumber = random()
```

```js
var someNumber = Math.random();
```

</CodeTab>

you can bind to an arbitrarily deep object by passing a tuple to `scope`:

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

```res example
@val @scope(("window", "location", "ancestorOrigins"))
external length: int = "length"
```

```js
// Empty output
```

</CodeTab>

This binds to `window.location.ancestorOrigins.length`.

## Special Global Values

Global values like `__filename` and `__DEV__` don't always exist; you can't even model them as an `option`, since the mere act of referring to them in ReScript (then compiled into JS) would trigger the usual `Uncaught ReferenceError: __filename is not defined` error in e.g. the browser environment.

For these troublesome global values, ReScript provides a special approach: `%external(a_single_identifier)`.

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

```res example
switch %external(__DEV__) {
| Some(_) => Console.log("dev mode")
| None => Console.log("production mode")
}
```

```js
var match = typeof __DEV__ === "undefined" ? undefined : __DEV__;

if (match !== undefined) {
  console.log("dev mode");
} else {
  console.log("production mode");
}
```

</CodeTab>

That first line's `typeof` check won't trigger a JS ReferenceError.

Another example:

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

```res example
switch %external(__filename) {
| Some(f) => Console.log(f)
| None => Console.log("non-node environment")
};
```

```js
var match = typeof __filename === "undefined" ? undefined : __filename;

if (match !== undefined) {
  console.log(match);
} else {
  console.log("non-node environment");
}
```

</CodeTab>

{/* TODO: revamp this page. Not good. Tell to use globalThis["foo"], and look in our stdlib */}

---
title: "Bind to JS Function"
description: "JS interop with functions in ReScript"
canonical: "/docs/manual/bind-to-js-function"
section: "JavaScript Interop"
order: 6
---

# Function

Binding a JS function is like binding any other value:

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

```res example
// Import nodejs' path.dirname
@module("path") external dirname: string => string = "dirname"
let root = dirname("/User/github") // returns "User"
```

```js
var Path = require("path");
var root = Path.dirname("/User/github");
```

</CodeTab>

We also expose a few special features, described below.

## Labeled Arguments

ReScript has [function](./function.mdx) signature. These work on an `external` too! You'd use them to _fix_ a JS function's unclear usage. Assuming we're modeling this:

```js
// MyGame.js

function draw(x, y, border) {
  // suppose `border` is optional and defaults to false
}
draw(10, 20);
draw(20, 20, true);
```

It'd be nice if on ReScript's side, we can bind & call `draw` while labeling things a bit:

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

```res example
@module("MyGame")
external draw: (~x: int, ~y: int, ~border: bool=?) => unit = "draw"

draw(~x=10, ~y=20, ~border=true)
draw(~x=10, ~y=20)
```

```js
var MyGame = require("MyGame");

MyGame.draw(10, 20, true);
MyGame.draw(10, 20, undefined);
```

</CodeTab>

We've compiled to the same function, but now the usage is much clearer on the ReScript side thanks to labels!

Note that you can freely reorder the labels on the ReScript side; they'll always correctly appear in their declaration order in the JavaScript output:

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

```res example
@module("MyGame")
external draw: (~x: int, ~y: int, ~border: bool=?) => unit = "draw"

draw(~x=10, ~y=20)
draw(~y=20, ~x=10)
```

```js
var MyGame = require("MyGame");

MyGame.draw(10, 20, undefined);
MyGame.draw(10, 20, undefined);
```

</CodeTab>

## Object Method

Functions attached to JS objects (other than JS modules) require a special way of binding to them, using `send`:

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

```res example
type document // abstract type for a document object
@send external getElementById: (document, string) => Dom.element = "getElementById"
@val external doc: document = "document"

let el = getElementById(doc, "myId")
```

```js
var el = document.getElementById("myId");
```

</CodeTab>

In a `send`, the object is always the first argument. Actual arguments of the method follow (this is a bit what modern OOP objects are really).

### Chaining

Ever used `foo().bar().baz()` chaining ("fluent api") in JS OOP? We can model that in ReScript too, through the [pipe operator](./pipe.mdx).

### Nested function call

`@send` can also accept a `@scope(("itemOne","itemTwo"))` to access a function on a nested property.

<CodeTab labels={["ReScript", "JS Output"]}>
```res example
type stripe

@module("stripe") @new
external make: string => stripe = "default"

type createSession = {}

type sessionResult

@send
@scope(("checkout", "sessions"))
external createCheckoutSession: (stripe, createSession) =>
Promise.t<sessionResult> = "create"

let stripe = make("sk\_...")
let session = stripe->createCheckoutSession({})

````
```js
import Stripe from "stripe";

var stripe = new Stripe("sk_...");
var session = stripe.checkout.sessions.create({});
````

</CodeTab>

## Variadic Function Arguments

You might have JS functions that take an arbitrary amount of arguments. ReScript supports modeling those, under the condition that the arbitrary arguments part is homogenous (aka of the same type). If so, add `variadic` to your `external`.

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

```res example
@module("path") @variadic
external join: array<string> => string = "join"

let v = join(["a", "b"])
```

```js
var Path = require("path");
var v = Path.join("a", "b");
```

</CodeTab>

`module` will be explained in [Import from/Export to JS](./import-from-export-to-js.mdx).

## Modeling Polymorphic Function

Apart from the above special-case, JS functions in general are often arbitrarily overloaded in terms of argument types and number. How would you bind to those?

### Trick 1: Multiple `external`s

If you can exhaustively enumerate the many forms an overloaded JS function can take, simply bind to each differently:

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

```res example
@module("MyGame") external drawCat: unit => unit = "draw"
@module("MyGame") external drawDog: (~giveName: string) => unit = "draw"
@module("MyGame") external draw: (string, ~useRandomAnimal: bool) => unit = "draw"
```

```js
// Empty output
```

</CodeTab>

Note how all three externals bind to the same JS function, `draw`.

### Trick 2: Polymorphic Variant + `unwrap`

If you have the irresistible urge of saying "if only this JS function argument was a variant instead of informally being either `string` or `int`", then good news: we do provide such `external` features through annotating a parameter as a polymorphic variant! Assuming you have the following JS function you'd like to bind to:

```js
function padLeft(value, padding) {
  if (typeof padding === "number") {
    return Array(padding + 1).join(" ") + value;
  }
  if (typeof padding === "string") {
    return padding + value;
  }
  throw new Error(`Expected string or number, got '${padding}'.`);
}
```

Here, `padding` is really conceptually a variant. Let's model it as such.

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

```res example
@val
external padLeft: (
  string,
  @unwrap [
    | #Str(string)
    | #Int(int)
  ])
  => string = "padLeft"
padLeft("Hello World", #Int(4))
padLeft("Hello World", #Str("Message from ReScript: "))
```

```js
padLeft("Hello World", 4);
padLeft("Hello World", "Message from ReScript: ");
```

</CodeTab>

Obviously, the JS side couldn't have an argument that's a polymorphic variant! But here, we're just piggy backing on poly variants' type checking and syntax. The secret is the `@unwrap` annotation on the type. It strips the variant constructors and compile to just the payload's value. See the output.

## Constrain Arguments Better

Consider the Node `fs.readFileSync`'s second argument. It can take a string, but really only a defined set: `"ascii"`, `"utf8"`, etc. You can still bind it as a string, but we can use poly variants + `string` to ensure that our usage's more correct:

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

```res example
@module("fs")
external readFileSync: (
  ~name: string,
  @string [
    | #utf8
    | @as("ascii") #useAscii
  ],
) => string = "readFileSync"

readFileSync(~name="xx.txt", #useAscii)
```

```js
var Fs = require("fs");
Fs.readFileSync("xx.txt", "ascii");
```

</CodeTab>

- Attaching `@string` to the whole poly variant type makes its constructor compile to a string of the same name.
- Attaching a `@as("bla")` to a constructor lets you customize the final string.

And now, passing something like `"myOwnUnicode"` or other variant constructor names to `readFileSync` would correctly error.

Aside from string, you can also compile an argument to an int, using `int` instead of `string` in a similar way:

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

```res example
@val
external testIntType: (
  @int [
    | #onClosed
    | @as(20) #onOpen
    | #inBinary
  ])
  => int = "testIntType"
testIntType(#inBinary)
```

```js
testIntType(21);
```

</CodeTab>

`onClosed` compiles to `0`, `onOpen` to `20` and `inBinary` to **`21`**.

## Unknown for type safety

It is best practice to inspect data received from untrusted external functions to ensure it contains what you expect. This helps avoid run-time crashes and unexpected behavior. If you're certain about what an external function returns, simply assert the return value as `string` or `array<int>` or whatever you want it to be. Otherwise use `unknown`. The ReScript type system will prevent you from using an `unknown` until you first inspect it and "convert" it using JSON parsing utilities or similar tools.

Consider the example below of two external functions that access the value of a property on a JavaScript object. `getPropertyUnsafe` returns an `'a`, which means "anything you want it to be." ReScript allows you to use this value as a `string` or `array` or any other type. Quite convenient! But if the property is missing or contains something unexpected, your code might break. You can make the binding more safe by changing `'a` to `string` or `option<'a>`, but this doesn't completely eliminate the problem.

The `getPropertySafe` function returns an `unknown`, which could be `null` or a `string` or anything else. But ReScript prevents you from using this value inappropriately until it has been safely parsed.

```res example
@get_index external getPropertyUnsafe: ({..}, string) => 'a = ""
@get_index external getPropertySafe: ({..}, string) => unknown = ""

let person = {"name": "Bob", "age": 12}

let greeting1 = "Hello, " ++ getPropertyUnsafe(person, "name") // works (this time!)
// let greeting2 = "Hello, " ++ getPropertySafe(person, "name") // syntax error
```

## Special-case: Event Listeners

One last trick with polymorphic variants:

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

```res example
type readline

@send
external on: (
    readline,
    @string [
      | #close(unit => unit)
      | #line(string => unit)
    ]
  )
  => readline = "on"

let register = rl =>
  rl
  ->on(#close(event => ()))
  ->on(#line(line => Console.log(line)));
```

```js
function register(rl) {
  return rl
    .on("close", function ($$event) {})
    .on("line", function (line) {
      console.log(line);
    });
}
```

</CodeTab>

{/* TODO: GADT phantom type */}

## Fixed Arguments

Sometimes it's convenient to bind to a function using an `external`, while passing predetermined argument values to the JS function:

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

```res example
@val
external processOnExit: (
  @as("exit") _,
  int => unit
) => unit = "process.on"

processOnExit(exitCode =>
  Console.log("error code: " ++ Int.toString(exitCode))
);
```

```js
process.on("exit", function (exitCode) {
  console.log("error code: " + exitCode.toString());
});
```

</CodeTab>

The `@as("exit")` and the placeholder `_` argument together indicates that you want the first argument to compile to the string `"exit"`. You can also use any JSON literal with `as`: ``@as(json`true`)``, ``@as(json`{"name": "John"}`)``, etc.

## Ignore arguments

You can also explicitly "hide" `external` function parameters in the JS output, which may be useful if you want to add type constraints to other parameters without impacting the JS side:

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

```res
@val external doSomething: (@ignore 'a, 'a) => unit = "doSomething"

doSomething("this only shows up in ReScript code", "test")
```

```js
doSomething("test");
```

</CodeTab>

**Note:** It's a pretty niche feature, mostly used to map to polymorphic JS APIs.

## Modeling `this`-based Callbacks

Many JS libraries have callbacks which rely on this (the source), for example:

```js
x.onload = function (v) {
  console.log(this.response + v);
};
```

Here, `this` would point to `x` (actually, it depends on how `onload` is called, but we digress). It's not correct to declare `x.onload` of type `(. unit) -> unit`. Instead, we introduced a special attribute, `this`, which allows us to type `x` as so:

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

```res example
type x
@val external x: x = "x"
@set external setOnload: (x, @this ((x, int) => unit)) => unit = "onload"
@get external resp: x => int = "response"
setOnload(x, @this (o, v) => Console.log(resp(o) + v))
```

```js
x.onload = function (v) {
  var o = this;
  console.log((o.response + v) | 0);
};
```

</CodeTab>

`@this` reserves the first parameter for the `this` value, and for arity of 0, there is no need for a redundant `unit` type.

## Function Nullable Return Value Wrapping

For JS functions that return a value that can also be `undefined` or `null`, we provide `@return(...)`. To automatically convert that value to an `option` type (recall that ReScript `option` type's `None` value only compiles to `undefined` and not `null`).

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

```res example
type element
type dom

@send @return(nullable)
external getElementById: (dom, string) => option<element> = "getElementById"

let test = dom => {
  let elem = dom->(getElementById("haha"))
  switch (elem) {
  | None => 1
  | Some(_ui) => 2
  }
}
```

```js
function test(dom) {
  var elem = dom.getElementById("haha");
  if (elem == null) {
    return 1;
  } else {
    console.log(elem);
    return 2;
  }
}
```

</CodeTab>

`return(nullable)` attribute will automatically convert `null` and `undefined` to `option` type.

Currently 4 directives are supported: `null_to_opt`, `undefined_to_opt`, `nullable` and `identity`.

{/* When the return type is unit: the compiler will append its return value with an OCaml unit literal to make sure it does return unit. Its main purpose is to make the user consume FFI in idiomatic OCaml code, the cost is very very small and the compiler will do smart optimizations to remove it when the returned value is not used (mostly likely). */}

`identity` will make sure that compiler will do nothing about the returned value. It is rarely used, but introduced here for debugging purpose.

## Tagged template functions

**Since 11.1**

**Experimental** You can easily bind to [JS tagged template functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates).
Tag functions in JS expect as input an array of strings and variadic parameters for the arguments of the interpolation.
To bind to those functions in ReScript, the binding signature must have two arrays as arguments,
the first one being an array of strings and the second can be an array of anything.
You add the `@taggedTemplate` annotation and you're good to go!

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

```res example
// see https://bun.sh/docs/runtime/shell
type result = {exitCode: int}
@module("bun") @taggedTemplate
external sh: (array<string>, array<string>) => promise<result> = "$"

let filename = "index.res"
let result = await sh`ls ${filename}`
```

```js
import * as $$Bun from "bun";
var filename = "index.res";
var result = await $$Bun.$`ls ${filename}`;
```

</CodeTab>

Notice that it gets compiled to tagged template literals in JS, which allows
to use JS tools that only work on the literals and not by calling directly the tag function.

There are plenty of useful JS tools you can bind to, like [`gql`](https://github.com/apollographql/graphql-tag),
[`sql`](https://github.com/porsager/postgres), [`css`](https://github.com/mayank99/ecsstatic) and a lot others!

---
title: "Bind to JS Object"
description: "Interop with JS objects in ReScript"
canonical: "/docs/manual/bind-to-js-object"
section: "JavaScript Interop"
order: 5
---

# Bind to JS Object

JavaScript objects are a combination of several use-cases:

- As a "record" or "struct" in other languages (like ReScript and C).
- As a hash map.
- As a class.
- As a module to import/export.

ReScript cleanly separates the binding methods for JS object based on these 4 use-cases. This page documents the first three. Binding to JS module objects is described in the [Import from/Export to JS](./import-from-export-to-js.mdx) section.

{/* TODO: mention scope here too? */}

## Bind to Record-like JS Objects

### Bind Using ReScript Record

If your JavaScript object has fixed fields, then it's conceptually like a ReScript record. Since a ReScript record compiles to a clean JavaScript object, you can definitely type a JS object as a ReScript record!

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

```res example
type person = {
  name: string,
  friends: array<string>,
  age: int,
}

@module("MySchool") external john: person = "john"

let johnName = john.name
```

```js
var MySchool = require("MySchool");

var johnName = MySchool.john.name;
```

</CodeTab>

External is documented [here](./external.mdx). `@module` is documented [here](./import-from-export-to-js.mdx).

If you want or need to use different field names on the ReScript and the JavaScript side, you can use the `@as` decorator:

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

```res example
type action = {
  @as("type") type_: string
}

let action = {type_: "ADD_USER"}
```

```js
var action = {
  type: "ADD_USER",
};
```

</CodeTab>

This is useful to map to JavaScript attribute names that cannot be expressed in ReScript (such as keywords).

It is also possible to map a ReScript record to a JavaScript array by passing indices to the `@as` decorator:

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

```res
type t = {
  @as("0") foo: int,
  @as("1") bar: string,
}

let value = {foo: 7, bar: "baz"}
```

```js
var value = [7, "baz"];
```

</CodeTab>

### Bind Using ReScript Object

Alternatively, you can use [ReScript object](./object.mdx) to model a JS object too:

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

```res example
type person = {
  "name": string,
  "friends": array<string>,
  "age": int,
}

@module("MySchool") external john: person = "john"

let johnName = john["name"]
```

```js
var MySchool = require("MySchool");

var johnName = MySchool.john.name;
```

</CodeTab>

### Bind Using Special Getter and Setter Attributes

Alternatively, you can use `get` and `set` to bind to individual fields of a JS object:

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

```res example
type textarea
@set external setName: (textarea, string) => unit = "name"
@get external getName: textarea => string = "name"
```

```js

```

</CodeTab>

You can also use `get_index` and `set_index` to access a dynamic property or an index:

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

```res example
type t
@new external create: int => t = "Int32Array"
@get_index external get: (t, int) => int = ""
@set_index external set: (t, int, int) => unit = ""

let i32arr = create(3)
i32arr->set(0, 42)
Console.log(i32arr->get(0))
```

```js
var i32arr = new Int32Array(3);
i32arr[0] = 42;
console.log(i32arr[0]);
```

</CodeTab>

## Bind to Hash Map-like JS Object

If your JavaScript object:

- might or might not add/remove keys
- contains only values that are of the same type

Then it's not really an object, it's a hash map. Use [Dict](/docs/manual/api/stdlib/dict), which contains operations like `get`, `set`, etc. and cleanly compiles to a JavaScript object still.

## Bind to a JS Object That's a Class

Use `new` to emulate e.g. `new Date()`:

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

```res example
type t
@new external createDate: unit => t = "Date"

let date = createDate()
```

```js
var date = new Date();
```

</CodeTab>

You can chain `new` and `module` if the JS module you're importing is itself a class:

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

```res example
type t
@new @module external book: unit => t = "Book"
let myBook = book()
```

```js
var Book = require("Book");
var myBook = new Book();
```

</CodeTab>

---
title: "Configuration Schema"
metaTitle: "Build System Configuration Schema"
description: "Schema exploration widget for the ReScript configuration file"
canonical: "/docs/manual/build-configuration-schema"
section: "Build System"
order: 3
---

<Suspense>
  <Docson tag="master" />
</Suspense>

---
title: "Configuration"
metaTitle: "Build System Configuration"
description: "Details about the configuration of the ReScript build system (rescript.json)"
canonical: "/docs/manual/build-configuration"
section: "Build System"
order: 2
---

# Configuration

`rescript.json` is the single, mandatory build meta file needed for `rescript`.

**The complete configuration schema is [here](./build-configuration-schema.mdx)**. We'll _non-exhaustively_ highlight the important parts in prose below.

## name, namespace

`name` is the name of the library, used as its "namespace". You can activate namespacing through `"namespace": true` in your `rescript.json`. Namespacing is almost **mandatory**; we haven't turned it on by default yet to preserve backward-compatibility.

**Explanation**: by default, your files, once used as a third-party dependency, are available globally to the consumer. E.g. if you have a `Util.res` and the consumer also has a file of the same name, they will clash. Turning on `namespace` avoids this by wrapping all your own project's files into an extra module layer; instead of a global `Util` module, the consumer will see you as `MyProject.Util`. **The namespacing affects your consumers, not yourself**.

Aka, in ReScript, "namespace" is just a fancy term for an auto-generated module that wraps all your project's files (efficiently and correctly, of course!) for third-party consumption.

We don't do folder-level namespacing for your own project; all your own file names must be unique. This is a constraint that enables several features such as fast search and easier project reorganization.

**Note**: the `rescript.json` `name` should be the same as the `package.json` `name`, to avoid confusing corner-cases. However, this means that you can't use a camelCased names such as `MyProject`, since `package.json` and npm forbid you to do so (some file systems are case-insensitive). To have the namespace/module as `MyProject`, write `"name": "my-project"`. ReScript will turn that into the camelCased name correctly.

**Note on custom namespacing**: if for some reason, you need a namespace that is different from what your `name` will produce, you can directly send a string to the `namespace` option. For example, if your package is a binding named `bs-some-thing`, you can use `"namespace": "some-thing"` to get `SomeThing` namespace instead of `BsSomeThing`.

## sources

Your source files need to be specified explicitly (we don't want to accidentally drill down into some unrelated directories). Examples:

```json
{
  "sources": ["src", "examples"]
}
```

```json
{
  "sources": {
    "dir": "src",
    "subdirs": ["page"]
  }
}
```

```json
{
  "sources": [
    "examples",
    {
      "dir": "src",
      "subdirs": true // recursively builds every subdirectory
    }
  ]
}
```

You can mark your directories as dev-only (for e.g. tests). These won't be built and exposed to third-parties, or even to other "dev" directories in the same project:

```json
{
  "sources": {
    "dir": "test",
    "type": "dev"
  }
}
```

You can also explicitly allow which modules can be seen from outside. This feature is especially useful for library authors who want to have a single entry point for their users.  
Here, the file `src/MyMainModule.res` is exposed to outside consumers, while all other files are private.

```json
{
  "sources": {
    "dir": "src",
    "public": ["MyMainModule"]
  }
}
```

## dependencies, dev-dependencies

List of ReScript dependencies. Just like `package.json`'s dependencies, they'll be searched in `node_modules`.

Note that only sources marked with `"type":"dev"` will be able to resolve modules from `dev-dependencies`.

> The legacy keys `bs-dependencies` and `bs-dev-dependencies` are still accepted but deprecated.

## js-post-build

Hook that's invoked every time a file is recompiled. Good for JS build system interop, but please use it **sparingly**. Calling your custom command for every recompiled file slows down your build and worsens the building experience for even third-party users of your lib.

Example:

```json
{
  "js-post-build": {
    "cmd": "/path/to/node ../../postProcessTheFile.js"
  }
}
```

Note that the path resolution for the command (`node` in this case) is done so:

- `/myCommand` is resolved into `/myCommand`
- `package/myCommand` is resolved into `node_modules/package/myCommand`
- `./myCommand` is resolved into `myProjectRoot/myCommand`
- `myCommand` is just called as `myCommand`, aka a globally available executable. But note that ReScript doesn't read into your shell's environment, so if you put e.g. `node`, it won't find it unless you specify an absolute path. Alternatively, add `#!/usr/local/bin/node` to the top of your script to directly call it without prepending `node`.

The command itself is called from inside `lib/bs`.

## jsx

Controls how the compiler emits JSX and which runtime (if any) it delegates to. A minimal configuration looks like this:

```json
{
  "jsx": {
    "version": 4
  }
}
```

- `version`: JSX transform version. `4` enables the React 17+ transform and is the current and only supported option in v12.
- `module`: Override the target module that receives JSX calls. Useful for [generic JSX transforms](./jsx.mdx#generic-jsx-transform-jsx-beyond-react-experimental); omit it when using the built-in React runtime.
- `preserve`: When `true`, the compiler re-emits JSX syntax in the generated JavaScript so bundlers or other tooling can take over the transform later. The regenerated JSX might differ slightly from the original source but stays semantically equivalent. See [Preserve mode](./jsx.mdx#preserve-mode) for details.

All fields are optional; unspecified fields fall back to the defaults mentioned above. Combine them as needed for your project's JSX runtime.

## package-specs

Output to either CommonJS (the default) or JavaScript module. Example:

```json
{
  "package-specs": {
    "module": "commonjs",
    "in-source": true
  }
}
```

- `"module": "commonjs"` generates output as CommonJS format.
- `"module": "esmodule"` generates output as JavaScript module format. Will be default value in next major.
- `"in-source": true` generates output alongside source files. If you omit it, it'll generate the artifacts into `lib/js`. The output directory is not configurable otherwise.

This configuration only applies to you, when you develop the project. When the project is used as a third-party library, the consumer's own `rescript.json` `package-specs` overrides the configuration here, logically.

## suffix

The suffix can be freely chosen. However, we still suggest you stick to the convention and use
one of the following:

- `".js`
- `".mjs"`
- `".cjs"`
- `".res.js"`
- `".res.mjs"`
- `".res.cjs"`

### Design Decisions

Generating JS files with the `.res.js` suffix means that, on the JS side, you can do `const myReScriptFile = require('./TheFile.res.js')`. The benefits:

- It's immediately clear that we're dealing with a generated JS file here.
- It avoids clashes with a potential `TheFile.js` file in the same folder.
- It avoids the need of using a build system loader for ReScript files. This + in-source build means integrating a ReScript project into your pure JS codebase **basically doesn't touch anything in your build pipeline at all**.

## warnings

Selectively turn on/off certain warnings and/or turn them into hard errors. Example:

```json
{
  "warnings": {
    "number": "-44-102",
    "error": "+5"
  }
}
```

Turn off warning `44` and `102` (polymorphic comparison). Turn warning `5` (partial application whose result has function type and is ignored) into a hard error.

The warning numbers are shown in the build output when they're triggered. See [Warning Numbers](./warning-numbers.mdx) for the complete list.

## compiler-flags

Extra flags to pass to the compiler. For advanced usages.

- `-open ABC` opens the module `ABC` for each file in the project. `ABC` can either be a dependency, namespaced project or local module of the current project.

> The legacy key `bsc-flags` is still accepted but deprecated.

## gentypeconfig

To enable genType, set `"gentypeconfig"` at top level in the project's `rescript.json`.

```json
{
  "gentypeconfig": {
    "module": "esmodule",
    "moduleResolution": "node",
    "generatedFileExtension": ".gen.tsx",
    "debug": {
      "all": false,
      "basic": false
    }
  }
}
```

`generatedFileExtension`: File extension used for genType generated files (defaults to `".gen.tsx"`)

`module`: Module format used for the generated `*.gen.tsx` files (supports `"esmodule"` and `"commonjs"`)

`moduleResolution`: Module resolution strategy used in genType outputs. This may be required for compatibility with TypeScript projects. Specify the value as the same in `tsconfig.json`.

- `"node"`(default): Drop extensions in import paths.
- `"node16"`: Use TS output's extension. This provides compatibility with projects using `"moduleResolution": "node16"` and ES Modules.
- `"bundler"`: Use TS input's extension. This provides compatibility with projects using `"moduleResolution": "bundler"` and ES Modules. This also requires TS v5.0+ and `compilerOptions.allowImportingTsExtensions` to `true`

`debug`: Enable debug logs.

## Environment Variables

We heavily disrecommend the usage of environment variables, but for certain cases, they're justified.

### Error Output Coloring: `FORCE_COLOR`

This is mostly for other programmatic usage of `rescript` where outputting colors is not desired.

When `FORCE_COLOR` is set to `1`: `rescript` produces color.
When `FORCE_COLOR` is set to `0`: `rescript` doesn't produce color.
When `FORCE_COLOR` is not set: `rescript` might or might not produce color, depending on a smart detection of where it's outputted.

> Note that the underlying compiler will always be passed `-color always`. See more details in [this issue](https://github.com/rescript-lang/rescript-compiler/issues/2984#issuecomment-410669163).

---
title: "Setting up a monorepo"
metaTitle: "Setting up a monorepo"
description: "Setting up a monorepo"
canonical: "/docs/manual/build-monorepo-setup"
section: "Build System"
order: 5
---

# Setting up a monorepo with ReScript

**Since 12.0**

> A monorepo is a single repository containing multiple separate projects, with clear relationships between them.

ReScript 12.0 introduces improved support for native monorepos through the new ["Rewatch"](../../blog/reforging-build-system.mdx) build system. This guide walks you through the setup process.

**Note:** This feature requires the new build system and is **not compatible** with `rescript-legacy`.

## Project Structure

A ReScript monorepo requires a `rescript.json` file at the repository root, plus a `rescript.json` file in each sub-project directory.
Basically, the monorepo contains a root package that manages all local dependencies. Building the root package will build all its dependencies.

**Important:** You also need a node_modules monorepo setup with symlinks. In practice, if you want a ReScript monorepo, you will also need an npm/yarn/pnpm/bun monorepo.

A typical structure looks like this:

```
my-monorepo/
├── rescript.json
├── package.json
├── node_modules/
│   ├── package-1/ # symlinked
│   ├── package-2/ # symlinked
├── packages/
│   ├── package-1/
│   │   ├── rescript.json
│   │   ├── package.json
│   │   ├── src/
│   ├── package-2/
│   │   ├── rescript.json
│   │   ├── package.json
│   │   ├── src/
│   ├── ...
```

## Root `rescript.json` Configuration

The root `rescript.json` manages the monorepo by listing its packages.

```json
{
  "name": "my-monorepo",
  "dependencies": ["package-1", "package-2"],
  "package-specs": {
    "module": "esmodule",
    "in-source": true
  },
  "suffix": ".res.mjs",
  "compiler-flags": []
}
```

The `"dependencies"` array lists the names of your packages, which must match the `"name"` fields in their respective sub-rescript.json files.
When you build a package in ReScript, it will use the `"package-specs"` and `"suffix"` settings from the root package.
Therefore, it is recommended to place these settings in the root `rescript.json` file and avoid specifying them in local package `rescript.json` files.

**Settings from different config files:** When Rewatch builds a package within a monorepo setup, it uses these settings from the root rescript.json:

- `"jsx"` (jsx_args, jsx_module_args, jsx_mode_args, jsx_preserve_args)
- `"experimental"` (experimental_features_args)
- `"package-specs"` (used for implementation_args)
- `"suffix"` (used for package output)

These settings come from the package's own rescript.json:

- `"sources"` (determines which files to compile)
- `"dependencies"` (package dependencies)
- `"warnings"` (warning_args)
- `"compiler-flags"` (bsc_flags)

When the root package is built, Rewatch will look for the dependencies inside the `my-monorepo/node_modules` folder.
It is expected that `package-1` and `package-2` are available there via a symlink system provided by your node_modules package manager.

Note that your root rescript.json is allowed to have a `"sources"` setting.
These files will be compiled as expected.

## Package `rescript.json` Configuration

Each nested rescript.json sets up a specific package.

`packages/package-1/rescript.json`:

```json
{
  "name": "package-1",
  "sources": ["src"],
  "dependencies": [],
  "compiler-flags": ["-open Foobar"]
}
```

`packages/package-2/rescript.json`:

```json
{
  "name": "package-2",
  "sources": ["src"],
  "dependencies": ["package-1"],
  "warnings": {
    "number": "-27"
  }
}
```

In `package-1`, we show how to use special compiler flags.
In `package-2`, we show how to disable warning 27 (unused variable).
In both cases, the settings only apply to the package where they are specified.
Defining these in the root rescript.json will not affect the packages.
There is no inheritance system.

Also note the dependencies array in `package-2`, which allows that package to depend on `package-1` within the monorepo.

## Building the monorepo

From the root directory, you can run all ReScript commands:

```bash
# Build all packages
rescript build

# Clean all packages
rescript clean

# Format all packages
rescript format
```

### Building individual packages

You can also run ReScript commands on individual packages instead of the entire monorepo. This is useful when you only want to work on one package.

```bash
# Build from the package directory
cd packages/package-3
rescript build
rescript clean
rescript format

# Or run from the root directory
rescript build packages/package-3
rescript clean packages/package-3
rescript format packages/package-3
```

When building a single package, ReScript will use the settings from the root rescript.json as explained in the [Root rescript.json Configuration](#root-rescriptjson-configuration) section above.

### Building without a root rescript.json

If your node_modules monorepo is set up with symlinks, you can build packages even without a root rescript.json:

```
my-monorepo/
├──node_modules/
│   ├── package-1/ # symlinked
│   ├── package-2/ # symlinked
├── package.json
├── packages/
│   ├── package-1/
│   │   ├── rescript.json
│   │   ├── package.json
│   │   ├── src/
│   ├── package-2/
│   │   ├── rescript.json
│   │   ├── package.json
│   │   ├── src/
│   ├── ...
```

Building `package-2` (which depends on `package-1`) will search up the folder structure to find `package-1`.

Example:

```bash
rescript build ./packages/package-2
```

Internally, Rewatch will look for:

- 🔴 `my-monorepo/packages/package-2/node_modules/package-1`
- 🔴 `my-monorepo/packages/node_modules/package-1`
- ✅ `my-monorepo/node_modules/package-1`

This only happens as a last resort if `package-1` is not listed as a (dev-)dependency in a parent `rescript.json`.

## Troubleshooting

If you're having issues with your monorepo setup, you can use the `-v` flag during build to see what Rewatch detected as the project context:

```bash
rescript build -v
```

This will show you detailed information about how Rewatch is interpreting your project structure and which configuration files it's using.

## Recommendation

**The ReScript team strongly recommends using a root `rescript.json` file when setting up monorepos.** While it's technically possible to build packages without one (as shown in the section above), having a root configuration file provides several benefits:

- **Consistent settings** across all packages (jsx, experimental features, package-specs, suffix)
- **Simplified dependency management** through the root dependencies array
- **Better developer experience** with unified build commands from the root
- **Easier maintenance** and configuration updates across the entire monorepo

The root `rescript.json` approach is the intended and supported way to work with ReScript monorepos.

---
title: "Overview"
metaTitle: "Build System Overview"
description: "Documentation about the ReScript build system and its toolchain"
canonical: "/docs/manual/build-overview"
section: "Build System"
order: 1
---

# Build System Overview

ReScript comes with a build system, [`rescript`](https://www.npmjs.com/package/rescript), that's fast, lean and used as the authoritative build system of the community.

Every ReScript project needs a build description file, `rescript.json`.

## Options

See `rescript help`:

```
❯ rescript help
Usage: rescript <options> <subcommand>

`rescript` is equivalent to `rescript build`

Options:
  -v, -version  display version number
  -h, -help     display help

Subcommands:
  build
  clean
  format
  convert
  dump
  help

Run `rescript <subcommand> -h` for subcommand help. Examples:
  rescript build -h
  rescript format -h
```

## Build Project

Each build will create build artifacts from your project's source files.

**To build a project (including its dependencies)**, run:

```sh
rescript
```

Which is an alias for `rescript build`.

To keep a build watcher, run:

```sh
rescript -w
```

Any new file change will be picked up and the build will re-run.

**Note**: third-party libraries in `node_modules` aren't watched, as doing so may exceed the node.js watcher count limit.

For monorepo setup in ReScript 12+, see [Setting up a monorepo](./build-monorepo-setup.mdx).

## Clean Project

If you ever get into a stale build for edge-case reasons, use:

```sh
rescript clean
```

## Compile with stricter errors in CI

**Since 11.1**

You may want to compile your project with stricter rules for production, than when developing. With the `-warn-error` build flag, this can easily be done, for instance in a continuous integration script. E.g.:

```sh
rescript -warn-error +110
```

Here, warning number 110, which is triggered when a [`%todo`](../../syntax-lookup/extension_todo.mdx) has been found, gets promoted to an error. The full list of warning numbers can be found [here](./warning-numbers.mdx).

---
title: "Performance"
metaTitle: "Build Performance"
description: "ReScript build performance and measuring tools"
canonical: "/docs/manual/build-performance"
section: "Build System"
order: 7
---

# Build Performance

ReScript considers performance at install time, build time and run time as a serious feature; it's one of those things you don't notice until you realize it's missing.

## Profile Your Build

Sometime your build can be slow due to some confused infra setups. We provide an interactive visualization of your build's performance via `bstracing`:

```sh
./node_modules/.bin/bstracing
```

Run the above command at your ReScript project's root; it'll spit out a JSON file you can drag and drop into `chrome://tracing`.

<Image
  withShadow={true}
  src="/img/bstracing.avif"
  className="w-auto mx-auto md:mx-auto"
  caption="Screenshot of bstracing result"
/>

## Under the Hood

ReScript itself uses a build system under the hood, called [Ninja](https://ninja-build.org). Ninja is like Make, but cross-platform, minimal, focuses on perf and destined to be more of a low-level building block than a full-blown build system. In this regard, Ninja's a great implementation detail for `rescript`.

ReScript reads into `rescript.json` and generates the Ninja build file in `lib/bs`. The file contains the low-level compiler commands, namespacing rules, intermediate artifacts generation & others. It then runs `ninja` for the actual build.

## The JS Wrapper

`rescript` itself is a Node.js wrapper which takes care of some miscellaneous tasks, plus the watcher. The lower-level, watcher-less, fast native `rescript` is called `rescript.exe`. It's located at `node_modules/rescript/{your-platform}/rescript.exe`.

If you don't need the watcher, you can run said `rescript.exe`. This side-steps Node.js' long startup time, which can be in the order of `100ms`. Our editor plugin finds and uses this native `rescript.exe` for better performance.

## Numbers

Raw `rescript.exe` build on a small project should be around `70ms`. This doubles when you use the JS `rescript` wrapper which comes with a watcher, which is practically faster since you don't manually run the build at every change (though you should opt for the raw `rescript.exe` for programmatic usage, e.g. inserting rescript into your existing JS build pipeline).

No-op build (when no file's changed) should be around `15ms`. Incremental rebuild (described soon) of a single file in a project is around `70ms` too.

Cleaning the artifacts should be instantaneous.

### Extreme Test

We've stress-tested `rescript.exe` on a big project of 10,000 files (2 directories, 5000 files each, first 5000 no dependencies, last 5000 10 dependencies on files from the former directory) using https://github.com/rescript-lang/build-benchmark, on a Retina Macbook Pro Early 2015 (3.1 GHz Intel Core i7).

{/* TODO: better repro */}

- No-op build of 10k files: `800ms` (the minimum amount of time required to check the mtimes of 10k files).
- Clean build: \<3 minutes.
- Incremental build: depends on the number of the dependents of the file. No dependent means `1s`.

### Stability

`rescript` is a file-based build system. We don't do in-memory build, even if that speeds up the build a lot. In-memory builds risk memory leaks, out-of-memory errors, corrupt halfway build and others. Our watcher mode stays open for days or months with no leak.

The watcher is also just a thin file watcher that calls `rescript.exe`. We don't like babysitting daemon processes.

## Incrementality & Correctness

ReScript doesn't take whole seconds to run every time. The bulk of the build performance comes from incremental build, aka re-building a previously built project when a few files changed.

In short, thanks to our compiler and the build system's architecture, we're able to **only build what's needed**. If `MyFile.res` isn't changed, it isn't recompiled. Renaming or moving files is handled automatically, with no stale builds.

## Speed Up Incremental Build

ReScript uses the concept of interface files (`.resi`) (or, equivalently, [module signatures](./module.mdx#signatures)). Exposing only what you need naturally speeds up incremental builds. E.g. if you change a `.res` file whose corresponding `.resi` file doesn't expose the changed part, then you've reduced the amount of dependent files you have to rebuild.

## Programmatic Usage

Unfortunately, JS build systems are usually the bottleneck for building a JS project nowadays. Having parts of the build blazingly fast doesn't matter much if the rest of the build takes seconds or literally minutes. Here are a few suggestions:

- Convert more files into ReScript =). Fewer files going through fewer parts of the JS pipeline helps a ton.
- Careful with bringing in more dependencies: libraries, syntax transforms (e.g. the unofficially supported PPX), build step loaders, etc. The bulk of these dragging down the editing & building experience might out-weight the API benefits they provide.

## Hot Reloading

Hot reloading refers to maintaining a dev server and listening to file changes in a way that allows the server to pipe some delta changes right into the currently running browser page. This provides a relatively fast iteration workflow while working in specific frameworks.

However, hot reloading is fragile by nature, and counts on the occasional inconsistencies (bad state, bad eval, etc.) and the heavy devserver setup/config being less of a hassle than the benefits it provides. We err on the side of caution and stability in general, and decided not to provide a built-in hot reloading _yet_. **Note**: you can still use the hot reloading facility provided by your JS build pipeline.

---
title: "If-Else & Loops"
description: "If, else, ternary, for, and while"
canonical: "/docs/manual/control-flow"
section: "Language Features"
order: 14
---

# If-Else & Loops

ReScript supports `if`, `else`, ternary expression (`a ? b : c`), `for` and `while`.

The `switch` pattern supports a default case. Read more about [pattern-matching & destructuring](./pattern-matching-destructuring.mdx).

## If-Else & Ternary

ReScript's `if` is an expression; it evaluates to its body's content:

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

```res
let message = if isMorning {
  "Good morning!"
} else {
  "Hello!"
}
```

```js
var message = isMorning ? "Good morning!" : "Hello!";
```

</CodeTab>

**Note:** an `if-else` expression without the final `else` branch implicitly gives `()` (aka the `unit` type). So this:

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

```res
if showMenu {
  displayMenu()
}
```

```js
if (showMenu) {
  displayMenu();
}
```

</CodeTab>

is basically the same as:

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

```res
if showMenu {
  displayMenu()
} else {
  ()
}
```

```js
if (showMenu) {
  displayMenu();
}
```

</CodeTab>

Here's another way to look at it. This is clearly wrong:

```res
let result = if showMenu {
  1 + 2
}
```

It'll give a type error, saying basically that the implicit `else` branch has the type `unit` while the `if` branch has type `int`. Intuitively, this makes sense: what would `result`'s value be, if `showMenu` was `false`?

We also have ternary sugar, but **we encourage you to prefer if-else when possible**.

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

```res
let message = isMorning ? "Good morning!" : "Hello!"
```

```js
var message = isMorning ? "Good morning!" : "Hello!";
```

</CodeTab>

`if-else` and ternary are often replaced by [pattern matching](./pattern-matching-destructuring.mdx), which handles a wide range of conditional logic more expressively.

## For Loops

For loops iterate from a starting value up to (and including) the ending value.

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

```res
for i in startValueInclusive to endValueInclusive {
  Console.log(i)
}
```

```js
for (var i = startValueInclusive; i <= endValueInclusive; ++i) {
  console.log(i);
}
```

</CodeTab>

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

```res example
// prints: 1 2 3, one per line
for x in 1 to 3 {
  Console.log(x)
}
```

```js
for (var x = 1; x <= 3; ++x) {
  console.log(x);
}
```

</CodeTab>

You can make the `for` loop count in the opposite direction by using `downto`.

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

```res
for i in startValueInclusive downto endValueInclusive {
  Console.log(i)
}
```

```js
for (var i = startValueInclusive; i >= endValueInclusive; --i) {
  console.log(i);
}
```

</CodeTab>

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

```res example
// prints: 3 2 1, one per line
for x in 3 downto 1 {
  Console.log(x)
}
```

```js
for (var x = 3; x >= 1; --x) {
  console.log(x);
}
```

</CodeTab>

## While Loops

While loops execute its body code block while its condition is true.

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

```res
while testCondition {
  // body here
}
```

```js
while (testCondition) {
  // body here
}
```

</CodeTab>

### Tips & Tricks

There's no loop-breaking `break` keyword (nor early `return` from functions, for that matter) in ReScript. However, we can break out of a while loop easily through using a [mutable binding](./mutation.mdx).

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

```res example
let break = ref(false)

while !break.contents {
  if Math.random() > 0.3 {
    break := true
  } else {
    Console.log("Still running")
  }
}
```

```js
var $$break = {
  contents: false,
};

while (!$$break.contents) {
  if (Math.random() > 0.3) {
    $$break.contents = true;
  } else {
    console.log("Still running");
  }
}
```

</CodeTab>

---
title: "Converting from JS"
description: "How to convert to ReScript with an existing JS codebase"
canonical: "/docs/manual/converting-from-js"
section: "Guides"
order: 1
---

# Converting from JS

ReScript offers a unique project conversion methodology which:

- Ensures minimal disruption to your teammates (very important!).
- Remove the typical friction of verifying conversion's correctness and performance guarantees.
- Doesn't require pre-made binding libraries. You can write bindings directly for any JavaScript API.

## Step 1: Install ReScript

Run `npm install rescript` on your project, then imitate our [New Project](./installation.mdx#new-project) workflow by adding a `rescript.json` at the root. Then start `npx rescript -w`.

## Step 2: Copy Paste the Entire JS File

Let's work on converting a file called `src/main.js`.

```js
const school = require("school");

const defaultId = 10;

function queryResult(usePayload, payload) {
  if (usePayload) {
    return payload.student;
  } else {
    return school.getStudentById(defaultId);
  }
}
```

First, copy the entire file content over to a new file called `src/Main.res` by using our [`%%raw` JS embedding trick](./embed-raw-javascript.mdx):

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

```res example
%%raw(`
const school = require('school');

const defaultId = 10;

function queryResult(usePayload, payload) {
  if (usePayload) {
    return payload.student;
  } else {
    return school.getStudentById(defaultId);
  }
}
`)
```

```js
// Generated by ReScript, PLEASE EDIT WITH CARE
"use strict";

const school = require("school");

const defaultId = 10;

function queryResult(usePayload, payload) {
  if (usePayload) {
    return payload.student;
  } else {
    return school.getStudentById(defaultId);
  }
}

/*  Not a pure module */
```

</CodeTab>

Add this file to `rescript.json`:

```json
  "sources": {
    "dir" : "src",
    "subdirs" : true
  },
```

Open an editor tab for `src/Main.res.js`. Do a command-line `diff -u src/main.js src/Main.res.js`. Aside from whitespaces, you should see only minimal, trivial differences. You're already a third of the way done!

**Always make sure** that at each step, you keep the ReScript output `.res.js` file open to compare against the existing JavaScript file. Our compilation output is very close to your hand-written JavaScript; you can simply eye the difference to catch conversion bugs!

## Step 3: Extract Parts into Idiomatic ReScript

Let's turn the `defaultId` variable into a ReScript let-binding:

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

```res example
let defaultId = 10

%%raw(`
const school = require('school');

function queryResult(usePayload, payload) {
  if (usePayload) {
    return payload.student;
  } else {
    return school.getStudentById(defaultId);
  }
}
`)
```

```js
// Generated by ReScript, PLEASE EDIT WITH CARE
'use strict';

const school = require('school');

function queryResult(usePayload, payload) {
  if usePayload {
    return payload.student
  } else {
    return school.getStudentById(defaultId)
  }
}

var defaultId = 10;

exports.defaultId = defaultId;
/*  Not a pure module */
```

</CodeTab>

Check the output. Diff it. Code still works. Moving on! Extract the function:

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

```res
%%raw(`
const school = require('school');
`)

let defaultId = 10

let queryResult = (usePayload, payload) => {
  if usePayload {
    payload.student
  } else {
    school.getStudentById(defaultId)
  }
}
```

```js

```

</CodeTab>

Format the code: `./node_modules/.bin/rescript format src/Main.res`.

We have a type error: "The record field student can't be found". That's fine! **Always ensure your code is syntactically valid first**. Fixing type errors comes later.

## Step 4: Add externals, Fix Types

The previous type error is caused by `payload`'s record declaration (which supposedly contains the field `student`) not being found. Since we're trying to convert as quickly as possible, let's use our [object](./object.mdx) feature to avoid needing type declaration ceremonies:

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

```res
%%raw(`
const school = require('school');
`)

let defaultId = 10

let queryResult = (usePayload, payload) => {
  if usePayload {
    payload["student"]
  } else {
    school["getStudentById"](defaultId)
  }
}
```

```js

```

</CodeTab>

Now this triggers the next type error, that `school` isn't found. Let's use [`external`](./external.mdx) to bind to that module:

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

```res example
@module external school: 'whatever = "school"

let defaultId = 10

let queryResult = (usePayload, payload) => {
  if usePayload {
    payload["student"]
  } else {
    school["getStudentById"](defaultId)
  }
}
```

```js
// Generated by ReScript, PLEASE EDIT WITH CARE
"use strict";

var School = require("school");

function queryResult(usePayload, payload) {
  if (usePayload) {
    return payload.student;
  } else {
    return School.getStudentById(10);
  }
}

var defaultId = 10;

exports.defaultId = defaultId;
exports.queryResult = queryResult;
/* school Not a pure module */
```

</CodeTab>

We hurrily typed `school` as a polymorphic `'whatever` and let its type be inferred by its usage below. The inference is technically correct, but within the context of bringing it a value from JavaScript, slightly dangerous. This is just the interop trick we've shown in the [`external`](./external.mdx) page.

Anyway, the file passes the type checker again. Check the `.res.js` output, diff with the original `.js`; we've now converted a file over to ReScript!

Now, you can delete the original, hand-written `main.js` file, and grep the files importing `main.js` and change them to importing `Main.res.js`.

## (Optional) Step 5: Cleanup

If you prefer more advanced, rigidly typed `payload` and `school`, feel free to do so:

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

```res example
type school
type student
type payload = {
  student: student
}

@module external school: school = "school"
@send external getStudentById: (school, int) => student = "getStudentById"

let defaultId = 10

let queryResult = (usePayload, payload) => {
  if usePayload {
    payload.student
  } else {
    school->getStudentById(defaultId)
  }
}
```

```js
// Generated by ReScript, PLEASE EDIT WITH CARE
"use strict";

var School = require("school");

function queryResult(usePayload, payload) {
  if (usePayload) {
    return payload.student;
  } else {
    return School.getStudentById(10);
  }
}

var defaultId = 10;

exports.defaultId = defaultId;
exports.queryResult = queryResult;
/* school Not a pure module */
```

</CodeTab>

We've:

- introduced an opaque types for `school` and `student` to prevent misuse of their values
- typed the payload as a record with only the `student` field
- typed `getStudentById` as the sole method of `student`

Check that the `.res.js` output didn't change. How rigidly to type your JavaScript code is up to you; we recommend not typing them too elaborately; it's sometime an endless chase, and produces diminishing returns, especially considering that the elaborate-ness might turn off your potential teammates.

## Tips & Tricks

In the same vein of idea, **resist the urge to write your own wrapper functions for the JS code you're converting**. Use [`external`s](./external.mdx), which are guaranteed to be erased in the output. And avoid trying to take the occasion to convert JS data structures into ReScript-specific data structures like variant or list. **This isn't the time for that**.

The moment you produce extra conversion code in the output, your skeptical teammate's mental model might switch from "I recognize this output" to "this conversion might be introducing more problems than it solves. Why are we testing ReScript again?". Then you've lost.

## Conclusion

- Paste the JS code into a new ReScript file as embedded raw JS code.
- Compile and keep the output file open. Check and diff against original JS file. Free regression tests.
- Always make sure your file is syntactically valid. Don't worry about fixing types before that.
- (Ab)use [object](./object.mdx) accesses to quickly convert things over.
- Optionally clean up the types for robustness.
- Don't go overboard and turn off your boss and fellow teammates.
- Proudly display that you've conserved the semantics and performance characteristics during the conversion by showing your teammates the eerily familiar output.
- Get promoted for introducing a new technology the safer, mature way.

---
title: "Dictionary"
description: "Dictionary data structure in ReScript"
canonical: "/docs/manual/dict"
section: "Language Features"
order: 8
---

# Dictionary

ReScript has first class support for dictionaries. Dictionaries are mutable objects with string keys, where all values must have the same type. Dicts compile to regular JavaScript objects at runtime.

## Create

You can create a new dictionary in a few different ways, depending on your use case.

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

```res prelude
// Using the first class dict syntax
let d = dict{"A": 5, "B": 6}

// Programatically via the standard library
let d2 = Dict.fromArray([("A", 5), ("B", 6)])
```

```js
let d = {
  A: 5,
  B: 6,
};

let d2 = Object.fromEntries([
  ["A", 5],
  ["B", 6],
]);
```

</CodeTab>

A few things to note here:

- Using the first class `dict{}` syntax compiles cleanly to a JavaScript object directly
- Using `Dict.fromArray` is useful when you need to create a dictionary programatically

## Access

You can access values from a Dictionary either via the the standard library `Dict` module functions, or using pattern matching.

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

```res prelude
let d = dict{"A": 5, "B": 6, "C": 7}

// Using `Dict.get`
let a = d->Dict.get("A")

// Switching on the full dict
let b = switch d {
| dict{"B": b} => Some(b)
| _ => None
}

// Destructuring
let dict{"C": ?c} = d
```

```js
let d = {
  A: 5,
  B: 6,
  C: 7,
};

let a = d["A"];

let b = d.B;

let b$1 = b !== undefined ? b : undefined;

let c = d.C;
```

</CodeTab>

> In the Destructuring example, we're using the `?` optional pattern match syntax to pull out the `C` key value as an optional, regardless of if the dict has it or not.

## Pattern matching

Dictionaries have first class support for pattern matching. Read more in the [dedicated guide on pattern matching and destructring in ReScript](./pattern-matching-destructuring.mdx#match-on-dictionaries).

## Updating and setting values

You can set and update new values on your dictionary using the `Dict.set` function. All updates are mutable.

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

```res prelude
let d = dict{"A": 5, "B": 6}

d->Dict.set("C", 7)
```

```js
let d = {
  A: 5,
  B: 6,
};

d["C"] = 7;
```

</CodeTab>

## Advanced example: Pattern matching on JSON

JSON objects are represented as dictionaries (`dict<JSON.t>`). You can leverage that fact to decode JSON in a nice way, using only language features:

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

```res prelude
type user = {
  name: string,
  email: string,
}

/** Decode JSON to a `user`. */
let decodeUser = (json: JSON.t) => {
  switch json {
  | Object(dict{"name": JSON.String(name), "email": JSON.String(email)}) =>
    Some({name, email})
  | _ => None
  }
}

```

```js
function decodeUser(json) {
  if (typeof json !== "object" || json === null || Array.isArray(json)) {
    return;
  }
  let name = json.name;
  if (typeof name !== "string") {
    return;
  }
  let email = json.email;
  if (typeof email === "string") {
    return {
      name: name,
      email: email,
    };
  }
}
```

</CodeTab>

---
title: "Dead Code Analysis in ReScript"
metaTitle: "Dead Code Analysis in ReScript"
description: "Documentation about ReScript editor plugins and code analysis"
canonical: "/docs/manual/editor-code-analysis"
section: "Guides"
order: 2
---

# Dead Code Analysis in ReScript

This guide provides a detailed walkthrough on how to leverage ReScript’s powerful dead code analysis tools to maintain a clean, efficient, and distraction-free codebase.

Dead code refers to code that's present in your codebase but is never executed. It can lead to:

- Increased compilation times
- Confusion during development
- Misleading assumptions about functionality

ReScript’s language design allows for accurate and efficient dead code analysis using the **ReScript Code Analyzer**, available via the official VSCode extension.

### Prerequisites

- ReScript VSCode extension (v1.8.2 or higher)

### Activation

1. Open the Command Palette: `Cmd/Ctrl + P`
2. Run: `> ReScript: Start Code Analyzer`

### Deactivation

- Run: `> ReScript: Stop Code Analyzer`
- Or click “Stop Code Analyzer” in the status bar

### Result

- The “Problems” pane populates with dead code warnings and suggestions.

### Reactive Updates (New)

Reactive dead code updates are a newer enhancement of Editor Code Analysis and require ReScript VSCode extension v1.73.9 or higher (pre-release).

## Real-World Use Cases

### 1. **Unused Record Fields**

```rescript
type useReturn = {
  items: array<item>,
  toggleItemChecked: string => unit, // ← Never used
  setCheckedOnItem: (string, bool) => unit,
  checkAll: unit => unit,
  uncheckAll: unit => unit,
}
```

Remove unused fields to simplify code.

### 2. **Unused Variant Cases**

```rescript
type textType =
  | Text(string)
  | TextWithIcon({icon: React.element, text: string})
  | Render(React.element) // ← Never constructed
```

Removing unused variants allows simplifying rendering logic.

### 3. **Unused Parts of State**

```rescript
type validationState = Idle | Invalid | Valid

type state = {
  oldPassword: string,
  newPassword: string,
  newPasswordRepeated: string,
  validationState: validationState, // ← Never read
}
```

Old validation logic might remain after refactors—clean it up.

### 4. **Unnecessary Interface Exposure**

```rescript
// DrilldownTarget.resi
MetricParam.parse // ← Never used
MetricParam.serialize // ← Never used
```

Keep interfaces minimal by removing unused exports.

### 5. **Unused Functions**

```rescript
let routerUrlToPath = ... // ← Never used
let routeUrlStartsWith = ... // ← Never used
```

Removing these often uncovers further unused logic.

### 6. **Unused Components**

Components never referenced in production should be removed, unless explicitly preserved.

## Keeping Some Dead Code

### Use `@dead` and `@live`

#### `@dead`

Suppresses warnings but notifies if code becomes alive again.

```rescript
type user = {
  name: string,
  @dead age: int,
}
```

#### `@live`

Permanently marks code as alive (no future warnings).

```rescript
@live
let getUserName = user => user.name
```

## Configuration

Add to your `rescript.json`:

```json
"reanalyze": {
  "analysis": ["dce"],
  "suppress": ["src/bindings", "src/stories", "src/routes"],
  "unsuppress": [],
  "transitive": false
}
```

### Options:

- **analysis**: Enables dead code analysis (`"dce"`)
- **suppress**: Silences reporting for paths (still analyzes)
- **unsuppress**: Re-enables reports within suppressed paths
- **transitive**: Controls reporting of indirectly dead code

**Recommendation:** Set `transitive: false` for incremental cleanup.

## Summary

ReScript’s dead code analyzer helps you:

- Incrementally clean up your codebase
- Avoid confusion and complexity
- Improve long-term maintainability

Use it regularly for the best results.

---
title: "Editor"
metaTitle: "Editor"
description: "Documentation about ReScript editor plugins and code analysis"
canonical: "/docs/manual/editor-plugins"
section: "Overview"
order: 3
---

# Editor

This section is about the editor plugin for ReScript. It adds syntax highlighting, autocomplete, type hints, formatting, code navigation, code analysis for `.res` and `.resi` files.

## Plugins

- [VSCode](https://marketplace.visualstudio.com/items?itemName=chenglou92.rescript-vscode)
- [Sublime Text](https://github.com/rescript-lang/rescript-sublime)
- [Vim/Neovim](https://github.com/rescript-lang/vim-rescript)

### Community Supported

We don't officially support these; use them at your own risk!

- [Neovim Tree-sitter](https://github.com/nkrkv/nvim-treesitter-rescript)
- [IDEA](https://github.com/reasonml-editor/reasonml-idea-plugin)
- [Emacs](https://github.com/jjlee/rescript-mode)

## Code analysis

The code analysis provides extra checks for your ReScript project, such as detecting dead code and unhandled exceptions. It's powered by [reanalyze](https://github.com/rescript-association/reanalyze), which is built into the extension — no separate install required.

### How to Use

- Open the command palette and run:  
  `ReScript: Start Code Analyzer`
- Warnings like dead code will show inline in the editor.
- Suppression actions are available where applicable.
- To stop analysis, click **Stop Code Analyzer** in the status bar.

### Configuration

Add a `reanalyze` section to your `rescript.json` to control what the analyzer checks or ignores. You'll get autocomplete for config options in the editor.  
More details: [reanalyze configuration docs](https://github.com/rescript-association/reanalyze#configuration-via-bsconfigjson)

### Exception analysis

The exception analysis is designed to keep track statically of the exceptions that might be thrown at runtime. It works by issuing warnings and recognizing annotations. Warnings are issued whenever an exception is thrown and not immediately caught. Annotations are used to push warnings from he local point where the exception is thrown, to the outside context: callers of the current function.
Nested functions need to be annotated separately.

Instructions on how to run the exception analysis using the `-exception` and `-exception-cmt` command-line arguments, or how to add `"analysis": ["exception"]` in `rescript.json` are contained in the [reanalyze configuration docs](https://github.com/rescript-association/reanalyze#configuration-via-bsconfigjson).

Here's an example, where the analysis reports a warning any time an exception is thrown, and not caught:

```rescript
let throws = () => throw(Not_found)
```

reports:

```sh

  Exception Analysis
  File "A.res", line 1, characters 4-10
  throws might throw Not_found (A.res:1:19) and is not annotated with @throws(Not_found)
```

No warning is reported when a `@throws` annotation is added:

```rescript
@throws(Not_found)
let throws = () => throw(Not_found)
```

When a function throws multiple exceptions, a tuple annotation is used:

```rescript
exception A
exception B

@throws([A, B])
let twoExceptions = (x, y) => {
  if (x) {
    throw(A)
  }
  if (y) {
    throw(B)
  }
}
```

It is possible to silence the analysis by adding a `@doesNotThrow` annotation:

```rescript
@throws(Invalid_argument)
let stringMake1 = String.make(12, ' ')

// Silence only the make function
let stringMake2 = (@doesNotThrow String.make)(12, ' ')

// Silence the entire call (including arguments to make)
let stringMake3 = @doesNotThrow String.make(12, ' ')

```

#### Limitations

- The libraries currently modeled are limited to the standard library, Belt and Js modules. Models are currently vendored in the analysis, and are easy to add (see [`analysis/reanalyze/src/ExnLib.ml`](https://github.com/rescript-lang/rescript/blob/master/analysis/reanalyze/src/ExnLib.ml))
- Generic exceptions are not understood by the analysis. For example `exn` is not recognized below (only concrete exceptions are):

```rescript
try (foo()) { | exn => throw(exn) }
```

- Uses of e.g. `List.head` are interpreted as belonging to the standard library. If you re-define `List` in the local scope, the analysis it will think it's dealing with `List` from the standard library.
- There is no special support for module functions.

### Guide

Look - [Editor Code Analysis](./editor-code-analysis.mdx) for a more detailed guide about how to use the code analysis tool.

### Caveats

- For older extension versions, cross-package dead code analysis in monorepos may be limited.

## Editor features

Below are features and configurations of the editor tooling that might be good to know about.

### Pipe completions

Pipes (`->`) are a huge and important part of the ReScript language, for many reasons. Because of that, extra care has gone into the editor experience for using pipes.

#### Default pipe completion rules for non-builtin types

By default, using `->` will give completions from the module where the type of the expression you're piping on is defined. So, if you're piping on something of the type `SomeModule.t` (like `someValue->`) then you'll get completions for all functions defined in `SomeModule` that take the type `t` as the first unlabelled argument.

#### Pipe completions for builtin types

For builtin types, completion will automatically happen based on the _standard library module_ for that type. So, `array` types will get completions from the `Array` module, `string` gets completions from `String`, and so on.

There is a way to enhance this behavior via configuration, described further down in this document.

### Dot completion enhancements

In ReScript, using a dot (`.`) normally means "access record field". The editor extends dot (`.`) to trigger completions in more scenarios beyond record field access.

This behavior has the following important implications:

- Improves discoverability (E.g. using a `.` will reveal important pipe completions)

Below is a list of all the scenarios where using dots trigger completion in addition to the normal record field completion.

#### Objects

When writing a `.` on something that's a [structural object](./object.mdx), you'll get completions for those object properties. Example:

```res
let obj = {
  "first": true,
  "second": false
}

let x = obj.

// Will give the following completions for object property access:
// - ["first"]
// - ["second"]
```

#### Pipe completions for anything

When writing `.` on _anything_, the editor will try to do pipe completion for the value on the left of the `.`. Example:

```res
let arr = [1, 2, 3]

let x = arr.

// Will give the following pipe completions:
// - ->Array.length
// - ->Array.filter
// - ->Array.map
```

### `@editor.completeFrom` for drawing completions from additional modules

You can configure any type you have control over to draw pipe completions from additional modules, in addition to the main module where the type is defined, via the `@editor.completeFrom` decorator. This is useful in many different scenarios:

- When you, for various reasons, need to have your type definition separate from its "main module". Could be because of cyclic dependencies, a need for the type to be in a recursive type definition chain, and so on.
- You have separate modules with useful functions for your type but that you don't want to (or can't) include in the main module of that type.

Let's look at an example:

```res
// Types.res
// In this example types need to live separately in their own file, for various reasons
type htmlInput

// Utils.res
module HtmlInput = {
  /** Gets the HTML input value. */
  @get
  external value: Types.htmlInput => option<string> = "value"
}
```

In the example above, if we try and pipe on something of the type `Types.htmlInput`, we'll get no completions because there are no functions in `Types` that take `htmlInput` as its first unlabelled argument. But, better DX would be for the editor to draw completions from our util functions for `htmlInput` in the `Utils.HtmlInput` module.

With `@editor.completeFrom`, we can fix this. Let's look at an updated example:

```res
// Types.res
@editor.completeFrom(Utils.HtmlInput)
type htmlInput

// Utils.res
module HtmlInput = {
  /** Gets the HTML input value. */
  @get
  external value: Types.htmlInput => option<string> = "value"
}
```

Now when piping on a value of the type `Types.htmlInput`, the editor tooling will know to include relevant functions from the module `Utils.HtmlInput`, and you'll get the completions you expect, even if the functions aren't located in the same module.

> You can point out multiple modules to draw completions from for a type either by repeating `@editor.completeFrom` with a single module path each time, or by passing an array with all the module paths you want to include, like `@editor.completeFrom([Utils.HtmlInput, HtmlInputUtils])`.

### Configuring the editor via `editor` in `rescript.json`

There's certain configuration you can do for the editor on a per project basis in `rescript.json`. Below lists all of the configuration available.

#### `autocomplete` for pipe completion

The `autocomplete` property of `editor` in `rescript.json` let's you map types to modules _on the project level_ that you want the editor to leverage when doing autocomplete for pipes.

This is useful in scenarios like:

- You have your own util module(s) for builtin types. Maybe you have an `ArrayExtra` with helpers for arrays that you want to get completions from whenever dealing with arrays.
- You have your own util module(s) for types you don't control yourself (and therefore can't use `@editor.completeFrom`), like from external packages you install.

To configure, you pass `autocomplete` an object where the keys are the _path to the type_ you want to target, and then an array of the path to each module you want to include for consideration for pipe completions.

Let's take two examples.

##### Enhancing completion for builtin types

First, let's look at including our own `ArrayExtra` in all completions for `array`:

```json
{
  "editor": {
    "autocomplete": {
      "array": ["ArrayExtra"]
    }
  }
}
```

Now, when using pipes on arrays, you'll get completions both from the standard library array functions, and also from your own `ArrayExtra` module.

```res
let x = [1, 2, 3]->

// Example of what completing at the pipe might look like
- Array.length
- Array.map
- Array.filter
- ArrayExtra.someArrayFn
- ArrayExtra.myOtherArrayFn
```

**Note**: generic types like `promise.t` and `result.t` do not need any additional types in the `rescript.json`:

```json
"editor": {
  "autocomplete": {
    "promise": ["PromiseExt"],
    "result": ["ResultExt"]
  }
}
```

##### Enhancing completion for non-builtin types

Now, let's look at an example of when you have a non-builtin type that you don't have control over.

In this example, imagine this:

- We're writing an app using `fastify`
- We're using an external package that provides the necessary bindings in a `Fastify` module
- We've got our own extra file `FastifyExtra` that has various custom util functions that operate on the main type `Fastify.t`

We now want the editor to always suggest completions from the `FastifyExtra` module, in addition to the regular completions from the main `Fastify` module.

Let's configure this using the `editor.autocomplete` config in `rescript.json`:

```json
{
  "editor": {
    "autocomplete": {
      "Fastify.t": ["FastifyExt"]
    }
  }
}
```

Now, when using pipes on anything of type `Fastify.t`, we'll also get completions from our custom `FastifyExtra`.

##### Enhancing completion for non-builtin types with namespaces

When a project uses a namespace, this affects the internal representation of type names used in the `autocomplete` configuration.

Consider the [geolocation](https://rescript-lang.github.io/experimental-rescript-webapi/apidocs/geolocation-api/#geolocation) type from the [Experimental WebAPI bindings](https://rescript-lang.github.io/experimental-rescript-webapi/).  
This project specifies in its `rescript.json`:

```json
{
  "name": "@rescript/webapi",
  "namespace": "WebAPI"
}
```

This makes the `geolocation` type internally represented as `GeolocationAPI-WebAPI.geolocation`, where:

- `GeolocationAPI` is the module name
- `WebAPI` is the namespace
- `geolocation` is the type name

**Important**: You must use this internal representation when configuring autocomplete for namespaced types:

```json
{
  "editor": {
    "autocomplete": {
      "GeolocationAPI-WebAPI.geolocation": ["GeolocationExt"]
    }
  }
}
```

---
title: "Embed Raw JavaScript"
description: "Utility syntax to for raw JS usage in ReScript"
canonical: "/docs/manual/embed-raw-javascript"
section: "JavaScript Interop"
order: 2
---

# Embed Raw JavaScript

## Paste Raw JS Code

First thing first. If you're ever stuck learning ReScript, remember that you can always just paste raw JavaScript code into our source file:

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

```res example
%%raw(`
// look ma, regular JavaScript!
var message = "hello";
function greet(m) {
  console.log(m)
}
`)
```

```js
// look ma, regular JavaScript!
var message = "hello";
function greet(m) {
  console.log(m);
}
```

</CodeTab>

The `%%raw` special ReScript call takes your code string and pastes it as-is into the output. **You've now technically written your first ReScript file!**

(The backtick syntax is a multiline string. No escaping is needed inside the string.)

While `%%raw` lets you embed top-level raw JS code, `%raw` lets you embed expression-level JS code:

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

```res example
let add = %raw(`
  function(a, b) {
    console.log("hello from raw JavaScript!");
    return a + b
  }
`)

Console.log(add(1, 2))
```

```js
var add = function (a, b) {
  console.log("hello from raw JavaScript!");
  return a + b;
};

console.log(add(1, 2));
```

</CodeTab>

The above code:

- declared a ReScript variable `add`,
- with the raw JavaScript value of a function declaration,
- then called that function in ReScript.

Existing JavaScript code can live inside ReScript files during migration.

## Debugger

You can also drop a `%debugger` expression in a body:

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

```res example
let f = (x, y) => {
  %debugger
  x + y
}
```

```js
function f(x, y) {
  debugger;
  return (x + y) | 0;
}
```

</CodeTab>

Output:

```js
function f(x, y) {
  debugger; // JavaScript developer tools will set an breakpoint and stop here
  x + y;
}
```

## Tips & Tricks

Embedding raw JS snippets isn't the best way to experience ReScript, though it's also highly useful if you're just starting out. As a matter of fact, the first few ReScript projects were converted through:

- pasting raw JS snippets inside a file
- examining the JS output (identical to the old hand-written JS)
- gradually extract a few values and functions and making sure the output still looks OK

At the end, we get a fully safe, converted ReScript file whose JS output is clean enough that we can confidently assert that no new bug has been introduced during the conversion process.

See the [Converting from JS](./converting-from-js.mdx) guide for a detailed walkthrough.

---
title: "Equality and Comparison"
description: "Handling equality and comparison checks"
canonical: "/docs/manual/equality-comparison"
section: "Language Features"
order: 28
---

# Equality and Comparison

ReScript has shallow equality `===`, deep equality `==`, and comparison operators `>`, `>=`, `<`, and `<=`.

## Shallow equality

The shallow equality operator `===` compares two values and either compiles to `===` or a `bool` if the equality is known to the compiler.
It behaves the same as the strict equality operator `===` in JavaScript.

Using `===` will never add a runtime cost.

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

```res
let t1 = 1 === 1 // true
let t2 = "foo" === "foo" // true
let t3 = { "foo": "bar" } === { "foo": "bar"} // false

let doStringsMatch = (s1: string, s2: string) => s1 === s2
```

```js
var t1 = true;
var t2 = "foo" === "foo";
var t3 = { foo: "bar" } === { foo: "bar" };

function doStringsMatch(s1, s2) {
  return s1 === s2;
}
```

</CodeTab>

## Deep equality

ReScript has the deep equality operator `==` to check deep equality of two items, which is very different from the loose equality operator like `==` in JavaScript.

When using `==` in ReScript it will never compile to `==` in JavaScript,
it will either compile to `===`, a runtime call to an internal function that deeply compares the equality, or a `bool` if the equality is known to the compiler.

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

```res
let t1 = 1 == 1 // true
let t2 = "foo" == "foo" // true
let t3 = { "foo": "bar" } == { "foo": "bar"} // true

let doStringsMatch = (s1: string, s2: string) => s1 == s2
```

```js
import * as Caml_obj from "./stdlib/caml_obj.js";

var t1 = true;
var t2 = true;
var t3 = Caml_obj.equal({ foo: "bar" }, { foo: "bar" });

function doStringsMatch(s1, s2) {
  return s1 === s2;
}
```

</CodeTab>

`==` will compile to `===` (or a `bool` if the compiler can determine equality) when:

- Comparing `string`, `char`, `int`, `float`, `bool`, or `unit`
- Comparing variants or polymorphic variants that do not have constructor values

`==` will compile to a runtime check for deep equality when:

- Comparing `array`, `tuple`, `list`, `object`, `record`, or regular expression `Re.t`
- Comparing variants or polymorphic variants that have constructor values

> When using `==` pay close attention to the JavaScript output if you're not sure what `==` will compile to.

## Comparison

ReScript has operators for comparing values that compile to the the same operator in JS, a runtime check using an internal function, or a `bool` if the equality is known to the compiler,

| operator | comparison            |
| -------- | --------------------- |
| `>`      | greater than          |
| `>=`     | greater than or equal |
| `<`      | less than             |
| `<=`     | less than or equal    |

Comparison can be done on any type.

An operator will compile to the same operator (or a `bool` if the compiler can determine equality) when:

- Comparing `int`, `float`, `string`, `char`, `bool`

An operator will compile to a runtime check for deep equality when:

- Comparing `array`, `tuple`, `list`, `object`, `record`, or regular expression (`Re.t`)
- Comparing variants or polymorphic variants

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

```res
let compareInt = (a: int, b: int) => a > b
let t1 = 1 > 10
let compareArray = (a: array<int>, b: array<int>) => a > b
let compareOptions = (a: option<float>, b: option<float>) => a < b
```

```js
import * as Caml_obj from "./stdlib/caml_obj.js";

function compareInt(a, b) {
  return a > b;
}

var t1 = false;

var compareArray = Caml_obj.greaterthan;

var compareOptions = Caml_obj.lessthan;
```

</CodeTab>

## Performance of runtime equality checks

The runtime equality check ReScript uses is quite fast and should be adequate for almost all use cases.
For small objects it can be 2x times faster than alternative deep compare functions such as Lodash's [`_.isEqual`](https://lodash.com/docs/4.17.15#isEqual).

For larger objects instead of using `==` you could manually use a faster alternative such as [fast-deep-compare](https://www.npmjs.com/package/fast-deep-equal), or write a custom comparator function.

[This repo](https://github.com/jderochervlk/rescript-perf) has benchmarks comparing results of different libraries compared to ReScript's built-in equality function.

---
title: "Exception"
description: "Exceptions and exception handling in ReScript"
canonical: "/docs/manual/exception"
section: "Language Features"
order: 19
---

# Exception

Exceptions are just a special kind of variant, thrown in **exceptional** cases (don't abuse them!). Consider using the [`option`](./null-undefined-option.mdx) or [`result`](/docs/manual/api/stdlib/result) type for recoverable errors.

You can create your own exceptions like you'd make a variant (exceptions need to be capitalized too).

<CodeTab labels={["ReScript", "JS Output"]}>
  
```res example
exception InputClosed(string)
// later on
throw(InputClosed("The stream has closed!"))
```

```js
import * as Primitive_exceptions from "./stdlib/Primitive_exceptions.js";

let InputClosed = /* @__PURE__ */ Primitive_exceptions.create(
  "Playground.InputClosed",
);

throw {
  RE_EXN_ID: InputClosed,
  _1: "The stream has closed!",
  Error: new Error(),
};
```

</CodeTab>

## Built-in Exceptions

ReScript has some built-in exceptions:

### `Not_found`

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

```res prelude
let getItem = (item: int) =>
  if (item === 3) {
    // return the found item here
    1
  } else {
    throw(Not_found)
  }

let result =
  try {
    getItem(2)
  } catch {
  | Not_found => 0 // Default value if getItem throws
  }
```

```js
import * as Primitive_exceptions from "./stdlib/Primitive_exceptions.js";

function getItem(item) {
  if (item === 3) {
    return 1;
  }
  throw {
    RE_EXN_ID: "Not_found",
    Error: new Error(),
  };
}

let result;

try {
  result = getItem(2);
} catch (raw_exn) {
  let exn = Primitive_exceptions.internalToException(raw_exn);
  if (exn.RE_EXN_ID === "Not_found") {
    result = 0;
  } else {
    throw exn;
  }
}
```

</CodeTab>

Note that the above is just for demonstration purposes; in reality, you'd return an `option<int>` directly from `getItem` and avoid the `try` altogether.

You can directly match on exceptions _while_ getting another return value from a function:

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

```res prelude
switch list{1, 2, 3}->List.getOrThrow(4) {
| item => Console.log(item)
| exception Not_found => Console.log("No such item found!")
}
```

```js
import * as Stdlib_List from "./stdlib/Stdlib_List.js";
import * as Primitive_exceptions from "./stdlib/Primitive_exceptions.js";

let exit = 0;

let item;

try {
  item = Stdlib_List.getExn(
    {
      hd: 1,
      tl: {
        hd: 2,
        tl: {
          hd: 3,
          tl: /* [] */ 0,
        },
      },
    },
    4,
  );
  exit = 1;
} catch (raw_exn) {
  let exn = Primitive_exceptions.internalToException(raw_exn);
  if (exn.RE_EXN_ID === "Not_found") {
    console.log("No such item found!");
  } else {
    throw exn;
  }
}

if (exit === 1) {
  console.log(item);
}
```

</CodeTab>

### `Invalid_argument`

Used to check if argument is valid. This exception takes a string.

<CodeTab labels={["ReScript", "JS Output"]}>
```res example
let divide = (a, b) =>
  if b == 0 {
    throw(Invalid_argument("Denominator is zero"))
  } else {
    a / b
  }

// catch error
try divide(2, 0)->Console.log catch {
| Invalid_argument(msg) => Console.log(msg) // Denominator is zero
}

````

```js
import * as Primitive_int from "./stdlib/Primitive_int.js";
import * as Primitive_exceptions from "./stdlib/Primitive_exceptions.js";

function divide(a, b) {
  if (b === 0) {
    throw {
      RE_EXN_ID: "Invalid_argument",
      _1: "Denominator is zero",
      Error: new Error()
    };
  }
  return Primitive_int.div(a, b);
}

try {
  console.log(divide(2, 0));
} catch (raw_msg) {
  let msg = Primitive_exceptions.internalToException(raw_msg);
  if (msg.RE_EXN_ID === "Invalid_argument") {
    console.log(msg._1);
  } else {
    throw msg;
  }
}
````

</CodeTab>

### `Assert_failure`

Thrown when you use `assert(condition)` and `condition` is false. The arguments
are the location of the `assert` in the source code (file name, line number, column number).

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

```res example
let decodeUser = (json: JSON.t) =>
  switch json {
  | Object(userDict) =>
    switch (userDict->Dict.get("name"), userDict->Dict.get("age")) {
    | (Some(String(name)), Some(Number(age))) => (name, age->Float.toInt)
    | _ => assert(false)
    }
  | _ => assert(false)
  }


try decodeUser(%raw("{}"))->Console.log catch {
| Assert_failure(loc) => Console.log(loc) // ("filename", line, col)
}
```

```js
import * as Primitive_exceptions from "./stdlib/Primitive_exceptions.js";

function decodeUser(json) {
  if (typeof json === "object" && json !== null && !Array.isArray(json)) {
    let match = json["name"];
    let match$1 = json["age"];
    if (typeof match === "string" && typeof match$1 === "number") {
      return [match, match$1 | 0];
    }
    throw {
      RE_EXN_ID: "Assert_failure",
      _1: ["playground.res", 6, 11],
      Error: new Error(),
    };
  }
  throw {
    RE_EXN_ID: "Assert_failure",
    _1: ["playground.res", 8, 9],
    Error: new Error(),
  };
}

try {
  console.log(decodeUser({}));
} catch (raw_loc) {
  let loc = Primitive_exceptions.internalToException(raw_loc);
  if (loc.RE_EXN_ID === "Assert_failure") {
    console.log(loc._1);
  } else {
    throw loc;
  }
}
```

</CodeTab>

### `Failure`

Exception thrown to signal that the given arguments do not make sense. This
exception takes a string as an argument.

<CodeTab labels={["ReScript", "JS Output"]}>
```res example
let isValidEmail = email => {
  let hasAtSign = String.includes(email, "@")
  let hasDot = String.includes(email, ".")
  if !(hasAtSign && hasDot) {
    throw(Failure("Invalid email address"))
  } else {
    true
  }
}

let isValid = try isValidEmail("rescript.org") catch {
| Failure(msg) => {
Console.error(msg)
false
}
}

````

```js
import * as Primitive_exceptions from "./stdlib/Primitive_exceptions.js";

function isValidEmail(email) {
  let hasAtSign = email.includes("@");
  let hasDot = email.includes(".");
  if (hasAtSign && hasDot) {
    return true;
  }
  throw {
    RE_EXN_ID: "Failure",
    _1: "Invalid email address",
    Error: new Error()
  };
}

let isValid;

try {
  isValid = isValidEmail("rescript.org");
} catch (raw_msg) {
  let msg = Primitive_exceptions.internalToException(raw_msg);
  if (msg.RE_EXN_ID === "Failure") {
    console.error(msg._1);
    isValid = false;
  } else {
    throw msg;
  }
}
````

</CodeTab>

### `Division_by_zero`

Exception thrown by integer division and remainder operations when their second argument is zero.

<CodeTab labels={["ReScript", "JS Output"]}>
```res example
// ReScript throws `Division_by_zero` if the denominator is zero
let result = try Some(10 / 0) catch {
| Division_by_zero => None
}

Console.log(result) // None

````

```js
import * as Primitive_int from "./stdlib/Primitive_int.js";
import * as Primitive_exceptions from "./stdlib/Primitive_exceptions.js";

let result;

try {
  result = Primitive_int.div(10, 0);
} catch (raw_exn) {
  let exn = Primitive_exceptions.internalToException(raw_exn);
  if (exn.RE_EXN_ID === "Division_by_zero") {
    result = undefined;
  } else {
    throw exn;
  }
}

console.log(result);
````

</CodeTab>

## Catching JS Exceptions

To distinguish between JavaScript exceptions and ReScript exceptions, ReScript namespaces JS exceptions under the `JsExn(payload)` variant. To catch an exception thrown from the JS side:

Throw an exception from JS:

```js
// Example.js

exports.someJsFunctionThatThrows = () => {
  throw new Error("A Glitch in the Matrix!");
};
```

Then catch it from ReScript:

```res
// import the method in Example.js
@module("./Example")
external someJsFunctionThatThrows: () => unit = "someJsFunctionThatThrows"

try {
  // call the external method
  someJSFunctionThatThrows()
} catch {
| JsExn(exn) =>
  switch JsExn.message(exn) {
  | Some(m) => Console.log("Caught a JS exception! Message: " ++ m)
  | None => ()
  }
}
```

The payload `exn` here is of type `unknown` since in JS you can throw anything. To operate on `exn`, do like the code above by using the standard library's [`JsExn`](/docs/manual/api/stdlib/jsexn) module's helpers
or use [`Type.Classify.classify`](/docs/manual/api/stdlib/type/classify#value-classify) to get more information about the runtime type of `exn`.

## Throw a JS Exception

### Throw a JS Error

`throw(MyException)` throws a ReScript exception. To throw a JavaScript error (whatever your purpose is), use `JsError.throwWithMessage`:

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

```res example
let myTest = () => {
  JsError.throwWithMessage("Hello!")
}
```

```js
import * as Stdlib_JsError from "./stdlib/Stdlib_JsError.js";

function myTest() {
  return Stdlib_JsError.throwWithMessage("Hello!");
}
```

</CodeTab>

Then you can catch it from the JS side:

```js
// after importing `myTest`...
try {
  myTest();
} catch (e) {
  console.log(e.message); // "Hello!"
}
```

### Throw a value that is not an JS Error

If you want to throw any value that is not a valid JS Error, use `JsExn.throw`:

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

```res example
let myTest = () => {
  JsExn.throw("some non-error value!")
}
```

```js
function myTest() {
  throw "some non-error value!";
}
```

</CodeTab>

Then you can catch it from the JS side:

```js
// after importing `myTest`...
try {
  myTest();
} catch (message) {
  console.log(message); // "Hello!"
}
```

## Catch ReScript Exceptions from JS

To let JavaScript code work with exception-throwing ReScript code, you don't need to throw a JS exception. ReScript exceptions can be used directly from JavaScript.

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

```res example
exception BadArgument({myMessage: string})

let myTest = () => {
  throw(BadArgument({myMessage: "Oops!"}))
}
```

```js
import * as Primitive_exceptions from "./stdlib/Primitive_exceptions.js";

let BadArgument = /* @__PURE__ */ Primitive_exceptions.create(
  "Playground.BadArgument",
);

function myTest() {
  throw {
    RE_EXN_ID: BadArgument, // `RE_EXN_ID` is an internal API and you should NEVER try and access it from JavaScript
    myMessage: "Oops!",
    Error: new Error(),
  };
}
```

</CodeTab>

Then, in your JS:

```js
// after importing `myTest`...
try {
  myTest();
} catch (e) {
  console.log(e.myMessage); // "Oops!"
  console.log(e.Error.stack); // the stack trace
}
```

The above `BadArgument` exception takes an inline record type. We special-case compile the exception as `{RE_EXN_ID, myMessage, Error}` for good ergonomics. If the exception instead took ordinary positional arguments, l like the standard library's `Invalid_argument("Oops!")`, which takes a single argument, the argument is compiled to JS as the field `_1` instead. A second positional argument would compile to `_2`, etc.

## Tips & Tricks

When you have ordinary variants, you often don't **need** exceptions. For example, instead of throwing when `item` can't be found in a collection, try to return an `option<item>` (`None` in this case) instead.

### Catch Both ReScript and JS Exceptions in the Same `catch` Clause

```res
try {
  someOtherJSFunctionThatThrows()
} catch {
| Not_found => ... // catch a ReScript exception
| Invalid_argument(_) => ... // catch a second ReScript exception
| JsExn(exn) => ... // catch the JS exception
}
```

This technically works, but hopefully you don't ever have to work with such code...

---
title: "Extensible Variant"
description: "Extensible Variants in ReScript"
canonical: "/docs/manual/extensible-variant"
section: "Advanced Features"
order: 1
---

# Extensible Variant

Variant types are usually constrained to a fixed set of constructors. There may be very rare cases where you still want to be able to add constructors to a variant type even after its initial type declaration. For this, we offer extensible variant types.

## Definition and Usage

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

```res example
type t = ..

type t += Other

type t +=
  | Point(float, float)
  | Line(float, float, float, float)
```

```js
var Caml_exceptions = require("./stdlib/caml_exceptions.js");

var Other = Caml_exceptions.create("Playground.Other");

var Point = Caml_exceptions.create("Playground.Point");

var Line = Caml_exceptions.create("Playground.Line");
```

</CodeTab>

The `..` in the type declaration above defines an extensible variant `type t`. The `+=` operator is then used to add constructors to the given type.

**Note:** Don't forget the leading `type` keyword when using the `+=` operator!

## Pattern Matching Caveats

Extensible variants are open-ended, so the compiler will not be able to exhaustively pattern match all available cases. You will always need to provide a default `_` case for every `switch` expression.

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

```res
let print = v =>
  switch v {
  | Point(x, y) => Console.log2("Point", (x, y))
  | Line(ax, ay, bx, by) => Console.log2("Line", (ax, ay, bx, by))
  | Other
  | _ => Console.log("Other")
  }
```

```js
function print(v) {
  if (v.RE_EXN_ID === Point) {
    console.log("Point", [v._1, v._2]);
  } else if (v.RE_EXN_ID === Line) {
    console.log("Line", [v._1, v._2, v._3, v._4]);
  } else {
    console.log("Other");
  }
}
```

</CodeTab>

## Tips & Tricks

**Fun fact:** Like [exception](./exception.mdx), extensible variant It's one of the very few use-case where extensible variants make sense.

We usually recommend sticking with common [variants](./variant.mdx) as much as possible to reap the benefits of exhaustive pattern matching.

---
title: "External (Bind to Any JS Library)"
description: "The external keyword"
canonical: "/docs/manual/external"
section: "JavaScript Interop"
order: 3
---

# External (Bind to Any JS Library)

`external` is the primary ReScript feature for bringing in and using JavaScript values.

`external` is like a let binding, but:

- The right side of `=` isn't a value; it's the name of the JS value you're referring to.
- The type for the binding is mandatory, since we need to know what the type of that JS value is.
- Can only exist at the top level of a file or module.

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

```res example
@val external setTimeout: (unit => unit, int) => float = "setTimeout"
```

```js
// Empty output
```

</CodeTab>

There are several kinds of `external`s, differentiated and/or augmented through the [attribute](./attribute.mdx) they carry. This page deals with the general, shared mechanism behind most `external`s. The different `external`s are documented in their respective pages later. A few notable ones:

- `@val`, `@scope`: [bind to global JS values](./bind-to-global-js-values.mdx).
- `@module`: [bind to JS imported/exported values](./import-from-export-to-js.mdx).
- `@send`: [bind to JS methods](./bind-to-js-function.mdx).

You can also use our [Syntax Lookup](../../syntax-lookup/) tool to find them.

Related: See our [interop cheatsheet](./interop-cheatsheet.mdx) for an overview.

## Usage

Once declared, you can use an `external` as a normal value, just like a let binding.

## Tips & Tricks

`external` + ReScript objects are a wonderful combination for quick prototyping. Check the JS output tab:

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

```res example
// The type of document is just some random type 'a
// that we won't bother to specify
@val external document: 'a = "document"

// call a method
document["addEventListener"]("mouseup", _event => {
  Console.log("clicked!")
})

// get a property
let loc = document["location"]

// set a property
document["location"]["href"] = "rescript-lang.org"
```

```js
document.addEventListener("mouseup", function (_event) {
  console.log("clicked!");
});

var loc = document.location;

document.location.href = "rescript-lang.org";
```

</CodeTab>

We've specified `document`'s type as `'a`, a placeholder type that's polymorphic. Any value can be passed there, so you're not getting much type safety (except the inferences at various call sites). This is useful for quickly getting started with a JavaScript library in ReScript since you can write bindings directly for any API you need.

For more rigidly typed bindings, see the other interop pages in this section.

## Performance & Output Readability

`external`s declarations are inlined into their callers during compilation, **and completely disappear from the JS output**. This means any time you use one, you can be sure that you're not incurring extra JavaScript \<-> ReScript conversion cost.

Additionally, no extra ReScript-specific runtime is better for output readability.

> **Note:** do also use `external`s and the `@blabla` attributes in the interface files. Otherwise the inlining won't happen.

## Design Decisions

ReScript takes interoperating with existing code very seriously. Our type system has very strong guarantees. However, such strong feature also means that, without a great interop system, it'd be very hard to gradually convert a codebase over to ReScript. Fortunately, our interop are comprehensive and cooperate very well with most existing JavaScript code.

The combination of a sound type system + great interop means that we get the benefits of a traditional gradual type system regarding incremental codebase coverage & conversion, without the downside of such gradual type system: complex features to support existing patterns, slow analysis, diminishing return in terms of type coverage, etc.

---
title: "Function"
description: "Function syntax in ReScript"
canonical: "/docs/manual/function"
section: "Language Features"
order: 13
---

# Function

_Cheat sheet for the full function syntax at the end_.

ReScript functions are declared with an arrow and return an expression. They compile to clean JavaScript functions.

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

```res prelude
let greet = (name) => "Hello " ++ name
```

```js
function greet(name) {
  return "Hello " + name;
}
```

</CodeTab>

This declares a function and assigns to it the name `greet`, which you can call like so:

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

```res example
greet("world!") // "Hello world!"
```

```js
greet("world!");
```

</CodeTab>

Multi-arguments functions have arguments separated by comma:

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

```res example
let add = (x, y, z) => x + y + z
add(1, 2, 3) // 6
```

```js
function add(x, y, z) {
  return (((x + y) | 0) + z) | 0;
}
```

</CodeTab>

For longer functions, you'd surround the body with a block:

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

```res example
let greetMore = (name) => {
  let part1 = "Hello"
  part1 ++ " " ++ name
}
```

```js
function greetMore(name) {
  return "Hello " + name;
}
```

</CodeTab>

If your function has no argument, just write `let greetMore = () => {...}`.

## Labeled Arguments

Multi-arguments functions, especially those whose arguments are of the same type, can be confusing to call.

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

```res
let addCoordinates = (x, y) => {
  // use x and y here
}
// ...
addCoordinates(5, 6) // which is x, which is y?
```

```js
function addCoordinates(x, y) {
  // use x and y here
}

addCoordinates(5, 6);
```

</CodeTab>

You can attach labels to an argument by prefixing the name with the `~` symbol:

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

```res
let addCoordinates = (~x, ~y) => {
  // use x and y here
}
// ...
addCoordinates(~x=5, ~y=6)
```

```js
function addCoordinates(x, y) {
  // use x and y here
}

addCoordinates(5, 6);
```

</CodeTab>

You can provide the arguments in **any order**:

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

```res
addCoordinates(~y=6, ~x=5)
```

```js
addCoordinates(5, 6);
```

</CodeTab>

The `~x` part in the declaration means the function accepts an argument labeled `x` and can refer to it in the function body by the same name. You can also refer to the arguments inside the function body by a different name for conciseness:

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

```res
let drawCircle = (~radius as r, ~color as c) => {
  setColor(c)
  startAt(r, r)
  // ...
}

drawCircle(~radius=10, ~color="red")
```

```js
function drawCircle(r, c) {
  setColor(c);
  return startAt(r, r);
}

drawCircle(10, "red");
```

</CodeTab>

As a matter of fact, `(~radius)` is just a shorthand for `(~radius as radius)`.

Here's the syntax for typing the arguments:

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

```res
let drawCircle = (~radius as r: int, ~color as c: string) => {
  // code here
}
```

```js
function drawCircle(r, c) {
  // code here
}
```

</CodeTab>

## Optional Labeled Arguments

Labeled function arguments can be made optional during declaration. You can then omit them when calling the function.

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

```res
// radius can be omitted
let drawCircle = (~color, ~radius=?) => {
  setColor(color)
  switch radius {
  | None => startAt(1, 1)
  | Some(r_) => startAt(r_, r_)
  }
}
```

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

function drawCircle(color, radius) {
  setColor(color);
  if (radius === undefined) {
    return startAt(1, 1);
  }
  var r_ = Caml_option.valFromOption(radius);
  return startAt(r_, r_);
}
```

</CodeTab>

When given in this syntax, `radius` is **wrapped** in the standard library's `option` type, defaulting to `None`. If provided, it'll be wrapped with a `Some`. So `radius`'s type value is `None | Some(int)` here.

Unlike [nullable](./null-undefined-option.mdx), optional fields don't

### Signatures and Type Annotations

Functions with optional labeled arguments can be confusing when it comes to signature and type annotations. Indeed, the type of an optional labeled argument looks different depending on whether you're calling the function, or working inside the function body. Outside the function, a raw value is either passed in (`int`, for example), or left off entirely. Inside the function, the parameter is always there, but its value is an option (`option<int>`). This means that the type signature is different, depending on whether you're writing out the function type, or the parameter type annotation. The first being a raw value, and the second being an option.

If we get back to our previous example and both add a signature and type annotations to its argument, we get this:

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

```res
let drawCircle: (~color: color, ~radius: int=?) => unit =
  (~color: color, ~radius: option<int>=?) => {
    setColor(color)
    switch radius {
    | None => startAt(1, 1)
    | Some(r_) => startAt(r_, r_)
    }
  }
```

```js
function drawCircle(color, radius) {
  setColor(color);
  if (radius !== undefined) {
    return startAt(radius, radius);
  } else {
    return startAt(1, 1);
  }
}
```

</CodeTab>

The first line is the function's signature, we would define it like that in an interface file (see [Signatures](./module.mdx#signatures)). The function's signature describes the types that the **outside world** interacts with, hence the type `int` for `radius` because it indeed expects an `int` when called.

In the second line, we annotate the arguments to help us remember the types of the arguments when we use them **inside** the function's body, here indeed `radius` will be an `option<int>` inside the function.

So if you happen to struggle when writing the signature of a function with optional labeled arguments, try to remember this!

### Explicitly Passed Optional

Sometimes, you might want to forward a value to a function without knowing whether the value is `None` or `Some(a)`. Naively, you'd do:

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

```res
let result =
  switch payloadRadius {
  | None => drawCircle(~color)
  | Some(r) => drawCircle(~color, ~radius=r)
  }
```

```js
var r = payloadRadius;

var result =
  r !== undefined
    ? drawCircle(color, Caml_option.valFromOption(r))
    : drawCircle(color);
```

</CodeTab>

This quickly gets tedious. We provide a shortcut:

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

```res
let result = drawCircle(~color, ~radius=?payloadRadius)
```

```js
var result = drawCircle(1, undefined);
```

</CodeTab>

This means "I understand `radius` is optional, and that when I pass it a value it needs to be an `int`, but I don't know whether the value I'm passing is `None` or `Some(val)`, so I'll pass you the whole `option` wrapper".

### Optional with Default Value

Optional labeled arguments can also be provided a default value. In this case, they aren't wrapped in an `option` type.

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

```res
let drawCircle = (~radius=1, ~color) => {
  setColor(color)
  startAt(radius, radius)
}
```

```js
function drawCircle(radiusOpt, color) {
  var radius = radiusOpt !== undefined ? radiusOpt : 1;
  setColor(color);
  return startAt(radius, radius);
}
```

</CodeTab>

## Recursive Functions

ReScript chooses the sane default of preventing a function to be called recursively within itself. To make a function recursive, add the `rec` keyword after the `let`:

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

```res example
let rec neverTerminate = () => neverTerminate()
```

```js
function neverTerminate(_param) {
  while (true) {
    _param = undefined;
    continue;
  }
}
```

</CodeTab>

A simple recursive function may look like this:

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

```res example
// Recursively check every item on the list until one equals the `item`
// argument. If a match is found, return `true`, otherwise return `false`
let rec listHas = (list, item) =>
  switch list {
  | list{} => false
  | list{a, ...rest} => a === item || listHas(rest, item)
  }
```

```js
function listHas(_list, item) {
  while (true) {
    var list = _list;
    if (!list) {
      return false;
    }
    if (list.hd === item) {
      return true;
    }
    _list = list.tl;
    continue;
  }
}
```

</CodeTab>

Recursively calling a function is bad for performance and the call stack. However, ReScript intelligently compiles [tail recursion](https://stackoverflow.com/questions/33923/what-is-tail-recursion) into a fast JavaScript loop. Try checking the JS output of the above code!

### Mutually Recursive Functions

Mutually recursive functions start like a single recursive function using the
`rec` keyword, and then are chained together with `and`:

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

```res example
let rec callSecond = () => callFirst()
and callFirst = () => callSecond()
```

```js
function callSecond(_param) {
  while (true) {
    _param = undefined;
    continue;
  }
}

function callFirst(_param) {
  while (true) {
    _param = undefined;
    continue;
  }
}
```

</CodeTab>

## Partial Application

**Since 11.0**

To partially apply a function, use the explicit `...` syntax.

<CodeTab labels={["ReScript", "JS Output"]}>
```res
let add = (a, b) => a + b
let addFive = add(5, ...)
```

```js
function add(a, b) {
  return (a + b) | 0;
}

function addFive(extra) {
  return (5 + extra) | 0;
}
```

</CodeTab>

## Async/Await

Just as in JS, an async function can be declared by adding `async` before the definition, and `await` can be used in the body of such functions.
The output looks like idiomatic JS:

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

```res example
let getUserName = async (userId) => userId

let greetUser = async (userId) => {
  let name = await getUserName(userId)
  "Hello " ++ name ++ "!"
}
```

```js
async function greetUser(userId) {
  var name = await getUserName(userId);
  return "Hello " + name + "!";
}
```

</CodeTab>

The return type of `getUser` is inferred to be `promise<string>`.
Similarly, `await getUserName(userId)` returns a `string` when the function returns `promise<string>`.
Using `await` outside of an `async` function (including in a non-async callback to an async function) is an error.

### Ergonomic error handling

Error handling is done by simply using `try`/`catch`, or a switch with an `exception` case, just as in functions that are not async.
Both JS exceptions and exceptions defined in ReScript can be caught. The compiler takes care of packaging JS exceptions into the builtin `JsError` exception:

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

```res example
exception SomeReScriptException

let somethingThatMightThrow = async () => throw(SomeReScriptException)

let someAsyncFn = async () => {
  switch await somethingThatMightThrow() {
  | data => Some(data)
  | exception JsExn(_) => None
  | exception SomeReScriptException => None
  }
}
```

```js
var SomeReScriptException = /* @__PURE__ */ Caml_exceptions.create(
  "Example.SomeReScriptException",
);

async function someAsyncFn(param) {
  var data;
  try {
    data = await somethingThatMightThrow(undefined);
  } catch (raw_exn) {
    var exn = Caml_js_exceptions.internalToOCamlException(raw_exn);
    if (exn.RE_EXN_ID === "JsError") {
      return;
    }
    if (exn.RE_EXN_ID === SomeReScriptException) {
      return;
    }
    throw exn;
  }
  return data;
}
```

</CodeTab>

## The ignore() Function

Occasionally you may want to ignore the return value of a function. ReScript provides an `ignore()` function that discards the value of its argument and returns `()`:

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

```res
mySideEffect()->Promise.catch(handleError)->ignore

setTimeout(myFunc, 1000)->ignore
```

```js
$$Promise.$$catch(mySideEffect(), function (prim) {
  return handleError(prim);
});

setTimeout(function (prim) {
  myFunc();
}, 1000);
```

</CodeTab>

## Tips & Tricks

Cheat sheet for the function syntaxes:

### Declaration

```res
// anonymous function
(x, y) => 1
// bind to a name
let add = (x, y) => 1

// labeled
let add = (~first as x, ~second as y) => x + y
// with punning sugar
let add = (~first, ~second) => first + second

// labeled with default value
let add = (~first as x=1, ~second as y=2) => x + y
// with punning
let add = (~first=1, ~second=2) => first + second

// optional
let add = (~first as x=?, ~second as y=?) => switch x {...}
// with punning
let add = (~first=?, ~second=?) => switch first {...}
```

#### With Type Annotation

```res
// anonymous function
(x: int, y: int): int => 1
// bind to a name
let add = (x: int, y: int): int => 1

// labeled
let add = (~first as x: int, ~second as y: int) : int => x + y
// with punning sugar
let add = (~first: int, ~second: int) : int => first + second

// labeled with default value
let add = (~first as x: int=1, ~second as y: int=2) : int => x + y
// with punning sugar
let add = (~first: int=1, ~second: int=2) : int => first + second

// optional
let add = (~first as x: option<int>=?, ~second as y: option<int>=?) : int => switch x {...}
// with punning sugar
// note that the caller would pass an `int`, not `option<int>`
// Inside the function, `first` and `second` are `option<int>`.
let add = (~first: option<int>=?, ~second: option<int>=?) : int => switch first {...}
```

### Application

```res
add(x, y)

// labeled
add(~first=1, ~second=2)
// with punning sugar
add(~first, ~second)

// application with default value. Same as normal application
add(~first=1, ~second=2)

// explicit optional application
add(~first=?Some(1), ~second=?Some(2))
// with punning
add(~first?, ~second?)
```

#### With Type Annotation

```res
// labeled
add(~first=1: int, ~second=2: int)
// with punning sugar
add(~first: int, ~second: int)

// application with default value. Same as normal application
add(~first=1: int, ~second=2: int)

// explicit optional application
add(~first=?Some(1): option<int>, ~second=?Some(2): option<int>)
// no punning sugar when you want to type annotate
```

### Standalone Type Signature

```res
// first arg type, second arg type, return type
type add = (int, int) => int

// labeled
type add = (~first: int, ~second: int) => int

// labeled
type add = (~first: int=?, ~second: int=?, unit) => int
```

#### In Interface Files

To annotate a function from the implementation file (`.res`) in your interface file (`.resi`):

```res sig
let add: (int, int) => int
```

The type annotation syntax is the same as described in [With Type Annotation](#with-type-annotation) above.

**Don't** confuse `let add: myType` with `type add = myType`. When used in `.resi` interface files, the former exports the binding `add` while annotating it as type `myType`. The latter exports the type `add`, whose value is the type `myType`.

---
title: "Generalized Algebraic Data Types"
description: "Generalized Algebraic Data Types in ReScript"
canonical: "/docs/manual/generalized-algebraic-data-types"
section: "Advanced Features"
order: 4
---

# Generalized Algebraic Data Types

Generalized Algebraic Data Types (GADTs) are an advanced feature of ReScript's type system. "Generalized" can be somewhat of a misnomer -- what they actually allow you to do is add some extra type-specificity to your variants. Using a GADT, you can give the individual cases of a variant _different_ types.

For a quick overview of the use cases, reach for GADTs when:

1. You need to distinguish between different members of a variant at the type level.
2. You want to "hide" type information in a type-safe way, without resorting to casts.
3. You need a function to return a different type depending on its input.

GADTs usually are overkill, but when you need them, you need them! Understanding them from first principles is difficult, so it is best to explain through some motivating examples.

## Distinguishing Constructors (Subtyping)

Suppose a simple variant type that represents the current timezone of a date value. This handles both daylight savings and standard time:

```res example
type timezone =
 | EST // standard time
 | EDT // daylight time
 | CST // standard time
 | CDT // daylight time
// etc...
```

Using this variant type, we will end up having functions like this:

{/* TODO: fix this example, it has an error because it doesn't have access to the previous snippet */}

```res
let convertToDaylight = tz => {
  switch tz {
  | EST => EDT
  | CST => CDT
  | EDT | CDT /* or, _ */ => failwith("Invalid timezone provided!")
  }
}
```

This function is only valid for a subset of our variant type's constructors but we can't handle this in a type-safe way using regular variants. We have to enforce that at runtime -- and moreover the compiler can't help us ensure we are failing only in the invalid cases. We are back to dynamically checking validity like we would in a language without static typing. If you work with a large variant type long enough, you will frequently find yourself writing repetitive catchall `switch` statements like the above, and for little actual benefit. The compiler should be able to help us here.

Let's see if we can find a way for the compiler to help us with normal variants. We could define another variant type to distinguish the two kinds of timezone.

{/* TODO: fix this example, it has an error because it doesn't have access to the previous snippet */}

```res
type daylightOrStandard =
  | Daylight(timezone)
  | Standard(timezone)
```

This has a lot of problems. For one, it's cumbersome and redundant. We would now have to pattern-match twice whenever we deal with a timezone that's wrapped up here. The compiler will force us to check whether we are dealing with daylight or standard time, but notice that there's nothing stopping us from providing invalid timezones to these constructors:

{/* TODO: fix this example, it has an error because it doesn't have access to the previous snippet */}

```res
let invalidTz1 = Daylight(EST)
let invalidTz2 = Standard(EDT)
```

Consequently, we still have to write our redundant catchall cases. We could define daylight savings time and standard time as two _separate_ types, and unify those in our `daylightOrStandard` variant.
That could be a passable solution, but what we would really like to do is implement some kind of subtyping relationship.
We have two _kinds_ of timezone. This is where GADTs are handy:

```res example
type standard
type daylight

type rec timezone<_> =
  | EST: timezone<standard>
  | EDT: timezone<daylight>
  | CST: timezone<standard>
  | CDT: timezone<daylight>
```

We define our type with a type parameter. We manually annotate each constructor, providing it with the correct type parameter indicating whether it is standard or daylight. Each constructor is a `timezone`,
but we've added another level of specificity using a type parameter. Constructors are now understood to be `standard` or `daylight` at the _type_ level. Now we can fix our function like this:

{/* TODO: fix this example, it has an error because it doesn't have access to the previous snippet */}

```res
let convertToDaylight = tz => {
  switch tz {
  | EST => EDT
  | CST => CDT
  }
}
```

The compiler can infer correctly that this function should only take `timezone<standard>` and only output
`timezone<daylight>`. We don't need to add any redundant catchall cases and the compiler will even error if
we try to return a standard timezone from this function. Actually, this seems like it could be a problem,
we still want to be able to match on all cases of the variant sometimes, and a naive attempt at this will not pass the type checker. A naive example will fail:

{/* TODO: fix this example, it has an error because it doesn't have access to the previous snippet */}

```res
let convertToDaylight = tz =>
  switch tz {
  | EST => EDT
  | CST => CDT
  | CDT => CDT
  | EDT => EDT
  }
```

This will complain that `daylight` and `standard` are incompatible. To fix this, we need to explicitly annotate to tell the compiler to accept both:

{/* TODO: fix this example, it has an error because it doesn't have access to the previous snippet */}

```res
let convertToDaylight : type a. timezone<a> => timezone<daylight> =  // ...
```

The syntax `type a.` here defines a _locally abstract type_ which basically tells the compiler that the type parameter a is some specific type, but we don't care what it is. The cost of the extra specificity and safety that
GADTs give us is that the compiler less able to help us with type inference.

## Varying return type

Sometimes, a function should have a different return type based on what you give it, and GADTs are how we can do this in a type-safe way. We can implement a generic `add` function that works on both `int` or `float`:

{/* this example purposefully has an error so it is not marked as an example */}

```res
type rec number<_> = Int(int): number<int> | Float(float): number<float>

let add = (type a, x: number<a>, y: number<a>): a =>
  switch (x, y) {
  | (Int(x), Int(y)) => x + y
  | (Float(x), Float(y)) => x + y
  }

let foo = add(Int(1), Int(2))

let bar = add(Int(1), Float(2.0)) // the compiler will complain here
```

How does this work? The key thing is the function signature for add. The `number` GADT is acting as a _type witness_. We have told the compiler that the type parameter for `number` will be the same as the type we return -- both are set to `a`. So if we provide a `number<int>`, `a` equals `int`, and the function will therefore return an `int`.

We can also use this to avoid returning `option` unnecessarily. We create an array searching function which either raises an exception, returns an `option`, or provides a `default` value depending on the behavior we ask for.[^2]

[^2]: This example is adapted from [here](https://dev.realworldocaml.org/gadts.html).

```res example
module IfNotFound = {
  type rec t<_, _> =
    | Raise: t<'a, 'a>
    | ReturnNone: t<'a, option<'a>>
    | DefaultTo('a): t<'a, 'a>
}

let flexible_find = (
  type a b,
  ~f: a => bool,
  arr: array<a>,
  ifNotFound: IfNotFound.t<a, b>,
): b => {
  open IfNotFound
  switch Array.find(arr, f) {
  | None =>
    switch ifNotFound {
    | Raise => failwith("No matching item found")
    | ReturnNone => None
    | DefaultTo(x) => x
    }
  | Some(x) =>
    switch ifNotFound {
    | ReturnNone => Some(x)
    | Raise => x
    | DefaultTo(_) => x
    }
  }
}
```

## Hide and recover Type information Dynamically

In an advanced case that combines the above techniques, we can use GADTs to selectively hide and recover type information. This helps us create more generic types.
The below example defines a `num` type similar to our above addition example, but this lets us use `int` and `float` arrays
interchangeably, hiding the implementation type rather than exposing it. This is similar to a regular variant. However, it is a tuple including embedding a `numTy` and another value.
`numTy` serves as a type-witness, making it
possible to recover type information that was hidden dynamically. Matching on `numTy` will "reveal" the type of the other value in the pair. We can use this to write a generic sum function over arrays of numbers:

```res example
type rec numTy<'a> =
  | Int: numTy<int>
  | Float: numTy<float>
and num = Num(numTy<'a>, 'a): num
and num_array = Narray(numTy<'a>, array<'a>): num_array

let addInt = (x, y) => x + y
let addFloat = (x: float, y: float) => x + y

let sum = (Narray(witness, array)) => {
  switch witness {
  | Int => Num(Int, array->Array.reduce(0, addInt))
  | Float => Num(Float, array->Array.reduce(0., addFloat))
  }
}
```

## A Practical Example -- writing bindings:

Javascript libraries that are highly polymorphic or use inheritance can benefit hugely from GADTs, but they can be useful for bindings even in other cases. The following examples are writing bindings to a simplified
of Node's `Stream` API.

This API has a method for binding event handlers, `on`. This takes an event and a callback. The callback accepts different parameters
depending on which event we are binding to. A naive implementation might look similar to this, defining a
separate method for each stream event to wrap the unsafe version of `on`.

{/* TODO: fix this example, it has an error */}

```res
module Stream = {
    type t

    @new @module("node:http") external make: unit => t = "stream"

    @send external on : (stream, string, 'a) => unit
    let onEnd = (stream, callback: unit=> unit) => stream->on("end", callback)
    let onData = (stream, callback: ('a => 'b)) => stream->on("", callback)
    // etc. ...
}
```

Not only is this quite tedious to write and quite ugly, but we gain very little in return. The function wrappers even add performance overhead, so we are losing on all fronts. If we define subtypes of
Stream like `Readable` or `Writable`, which have all sorts of special interactions with the callback that jeopardize our type-safety, we are going to be in even deeper trouble.

Instead, we can use the same GADT technique that let us vary return type to vary the input type.
Not only are we able to now just use a single method, but the compiler will guarantee we are always using the correct callback type for the given event. We simply define an event GADT which specifies
the type signature of the callback and pass this instead of a plain string.

Additionally, we use some type parameters to represent the different types of Streams.

This example is complex, but it enforces tons of useful rules. The wrong event can never be used
with the wrong callback, but it also will never be used with the wrong kind of stream. The compiler will for example complain if we try to use a `Pipe` event with anything other than a `writable` stream.

The real magic happens in the signature of `on`. Read it carefully, and then look at the examples and try to
follow how the type variables are getting filled in, write it out on paper what each type variable is equal
to if you need and it will soon become clear.

{/* TODO: fix this example, it has an error */}

```res

module Stream = {
  type t<'a>

  type writable
  type readable

  type buffer = {buffer: ArrayBuffer.t}

  @unboxed
  type chunk =
    | Str(string)
    // Node uses actually its own buffer type, but for the tutorial we are using the stdlib's buffer type.
    | Buf(buffer)

  type rec event<_, _> =
    // "as" here is setting the runtime representation of our constructor
    | @as("pipe") Pipe: event<writable, t<readable> => unit>
    | @as("end") End: event<'inputStream, option<chunk> => unit>
    | @as("data") Data: event<readable, chunk => unit>

  @new @module("node:http") external make: unit => t<'a> = "Stream"

  @send
  external on: (t<'inputStream>, event<'inputStream, 'callback>, 'callback) => unit = "on"

}

let writer = Stream.Writable.make()
let reader = Stream.Readable.make()
// Types will be correctly inferred for each callback, based on the event parameter provided
writer->Stream.on(Pipe, r => {
  Console.log("Piping has started")

  r->Stream.on(Data, chunk =>
    switch chunk {
    | Stream.Str(s) => Console.log(s)
    | Stream.Buf(buffer) => Console.log(buffer)
    }
  )
})

writer->Stream.on(End, _ => Console.log("End reached"))

```

This example is only over a tiny, imaginary subset of Node's Stream API, but it shows a real-life example
where GADTs are all but indispensable.

## Conclusion

While GADTs can make your types extra-expressive and provide more safety, with great power comes great
responsibility. Code that uses GADTs can sometimes be too clever for its own good. The type errors you
encounter will be more difficult to understand, and the compiler sometimes requires extra help to properly
type your code.

However, there are definite situations where GADTs are the _right_ decision
and will _simplify_ your code and help you avoid bugs, even rendering some bugs impossible. The `Stream` example above is a good example where the "simpler" alternative of using regular variants or even strings
would lead to a much more complex and error prone interface.

Ordinary variants are not necessarily _simple_ therefore, and neither are GADTs necessarily _complex_.
The choice is rather which tool is the right one for the job. When your logic is complex, the highly expressive nature of GADTs can make it simpler to capture that logic.
When your logic is simple, it's best to reach for a simpler tool and avoid the cognitive overhead.
The only way to get good at identifying which tool to use in a given situation is to practice and experiment with both.

---
title: "Generate Converters & Helpers"
description: "All about the @deriving decorator, and how to generate code from types"
canonical: "/docs/manual/generate-converters-accessors"
section: "JavaScript Interop"
order: 12
---

# Generate Converters & Helpers

**Note**: if you're looking for:

- `@deriving(jsConverter)` for records
- `@deriving({jsConverter: newType})` for records
- `@deriving(abstract)` for records
- `@deriving(jsConverter)` for plain and polymorphic variants

These particular ones are no longer needed. Select a doc version lower than `9.0` in the sidebar to see their old docs.

{/* TODO: genType */}

When using ReScript, you will sometimes come into situations where you want to

- Automatically generate functions that convert between ReScript's internal and JS runtime values (e.g. variants).
- Convert a record type into an abstract type with generated creation, accessor and method functions.
- Generate some other helper functions, such as functions from record attribute names.

You can use the `@deriving` decorator for different code generation scenarios. All different options and configurations will be discussed on this page.

**Note:** Please be aware that extensive use of code generation might make it harder to understand your programs (since the code being generated is not visible in the source code, and you just need to know what kind of functions / values a decorator generates).

## Generate Functions & Plain Values for Variants

Use `@deriving(accessors)` on a variant type to create accessor functions for its constructors.

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

```res
@deriving(accessors)
type action =
  | Click
  | Submit(string)
  | Cancel;
```

```js
function submit(param_0) {
  return /* Submit */ [param_0];
}

var click = /* Click */ 0;

var cancel = /* Cancel */ 1;

exports.click = click;
exports.submit = submit;
exports.cancel = cancel;
```

</CodeTab>

Variants constructors with payloads generate functions, payload-less constructors generate plain integers (the internal representation of variants).

**Note**:

- The generated accessors are lower-cased.
- You can now use these helpers on the JavaScript side! But don't rely on their actual values please.

### Usage

```res
let s = submit("hello"); /* gives Submit("hello") */
```

This is useful:

- When you're passing the accessor function as a higher-order function (which plain variant constructors aren't).
- When you'd like the JS side to use these values & functions opaquely and pass you back a variant constructor (since JS has no such thing).

Please note that in case you just want to _pipe a payload into a constructor_, you don't need to generate functions for that. Use the `->` syntax instead, e.g. `"test"->Submit`.

## Generate Field Accessors for Records

Use `@deriving(accessors)` on a record type to create accessors for its record field names.

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

```res
@deriving(accessors)
type pet = {name: string}

let pets = [{name: "bob"}, {name: "bob2"}]

pets
 ->Array.map(name)
 ->Array.joinWith("&")
 ->Console.log
```

```js
function name(param) {
  return param.name;
}

var pets = [
  {
    name: "bob",
  },
  {
    name: "bob2",
  },
];

console.log(pets.map(name).join("&"));
```

</CodeTab>

---
title: "Import & Export"
description: "Importing / exporting in ReScript modules"
canonical: "/docs/manual/import-export"
section: "Language Features"
order: 25
---

# Import & Export

## Import a Module/File

Unlike JavaScript, ReScript doesn't have or need import statements:

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

```res
// Inside School.res
let studentMessage = Student.message
```

```js
var Student = require("./Student.res.js");
var studentMessage = Student.message;
```

</CodeTab>

The above code refers to the `message` binding in the file `Student.res`. Every ReScript file is also a module, so accessing another file's content is the same as accessing another module's content!

A ReScript project's file names need to be unique.

## Export Stuff

By default, every file's type declaration, binding and module is exported, aka publicly usable by another file. **This also means those values, once compiled into JS, are immediately usable by your JS code**.

To only export a few selected things, use a `.resi` [interface file](./module.mdx#signatures).

## Work with JavaScript Import & Export

To see how to import JS modules and export stuff for JS consumption, see the JavaScript Interop section's [Import from/Export to JS](./import-from-export-to-js.mdx).

---
title: "Import from / Export to JS"
description: "Importing / exporting JS module content in ReScript"
canonical: "/docs/manual/import-from-export-to-js"
section: "JavaScript Interop"
order: 7
---

# Import from/Export to JS

You've seen how ReScript's idiomatic [Import & Export](./import-export.mdx) works. This section describes how we work with importing stuff from JavaScript and exporting stuff for JavaScript consumption.

If you're looking for react-specific interop guidance, check out the [React JS Interop guide](../react/import-export-reactjs.mdx).

**Tip**: keep your compiled JS output open in a tab to verify the generated import/export code.

In short: **make sure your bindings below output what you'd have manually written in JS**.

## Output Format

We support 2 JavaScript import/export formats:

- JavaScript module: `import * from 'MyReScriptFile'` and `export let ...`.
- CommonJS: `require('myFile')` and `module.exports = ...`.

The format is [configurable in via `rescript.json`](./build-configuration.mdx#package-specs).

## Import From JavaScript

### Import a JavaScript Module's Named Export

Use the `module` [external](./external.mdx):

<CodeTab labels={["ReScript", "JS Output (Module)", "JS Output (CommonJS)"]}>

```res example
// Import nodejs' path.dirname
@module("path") external dirname: string => string = "dirname"
let root = dirname("/User/github") // returns "User"
```

```js
import * as Path from "path";
var root = Path.dirname("/User/github");
```

```js
var Path = require("path");
var root = Path.dirname("/User/github");
```

</CodeTab>

Here's what the `external` does:

- `@module("path")`: pass the name of the JS module; in this case, `"path"`. The string can be anything: `"./src/myJsFile"`, `"@myNpmNamespace/myLib"`, etc.
- `external`: the general keyword for declaring a value that exists on the JS side.
- `dirname`: the binding name you'll use on the ReScript side.
- `string => string`: the type signature of `dirname`. Mandatory for `external`s.
- `= "dirname"`: the name of the variable inside the `path` JS module. There's repetition in writing the first and second `dirname`, because sometime the binding name you want to use on the ReScript side is different than the variable name the JS module exported.

### Import a JavaScript Module As a Single Value

By omitting the string argument to `module`, you bind to the whole JS module:

<CodeTab labels={["ReScript", "JS Output (Module)", "JS Output (CommonJS)"]}>

```res example
@module external leftPad: (string, int) => string = "./leftPad"
let paddedResult = leftPad("hi", 5)
```

```js
import * as LeftPad from "./leftPad";
var paddedResult = LeftPad("hi", 5);
```

```js
var LeftPad = require("./leftPad");
var paddedResult = LeftPad("hi", 5);
```

</CodeTab>

Depending on whether you're compiling ReScript to JavaScript module or CommonJS, **this feature will generate subtly different code**. Please check both output tabs to see the difference. The JavaScript module output here would be wrong!

### Import an `default` Export

Use the value `default` on the right hand side:

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

```res example
@module("./student") external studentName: string = "default"
Console.log(studentName)
```

```js
import Student from "./student";
var studentName = Student;
```

</CodeTab>

### Use Import Attributes

**Since 11.1**

[Import attributes](https://github.com/tc39/proposal-import-attributes) can be used in ReScript, as long as ReScript is configured to output JavaScript module. You do that by passing configuration to the `@module` attribute:

<CodeTab labels={["ReScript", "JS Output (Module)"]}>
```rescript
@module({from: "./myJson.json", with: {type_: "json", \"some-exotic-identifier": "someValue"}})
external myJson: JSON.t = "default"

Console.log(myJson)

````

```javascript
import MyJsonJson from "./myJson.json" with {"type": "json", "some-exotic-identifier": "someValue"};

var myJson = MyJsonJson;

console.log(myJson);
````

</CodeTab>

This above imports the local `./myJson.json` file, adding import attributes.

This is how it works:

1. Instead of passing a string or tuple to `@module`, pass a record.
2. This record should have a `from` key. The value of that is where you want the module to be imported from (just like the regular string to `@module` is).
3. It should also have a `with` key, with another record where you put all the import attributes you want emitted.

Notice `\"some-exotic-identifier"` - you'll need to escape any key that's not a valid ReScript record key.
Also notice `type_`. Since `type` is a reserved keyword in ReScript, you can use `type_` instead. It will be output as `type` in the JavaScript code.

## Dynamic Import

Leveraging JavaScript's [dynamic `import`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import) to reduce bundle size and lazy load code as needed is easy in ReScript. It's also a little bit more convenient than in regular JavaScript because you don't need to keep track of file paths manually with ReScript's module system.

### Dynamically Importing Parts of a Module

Use the `import` function to dynamically import a specific part of a module. Put whatever `let` binding you want to import in there, and you'll get a `promise` back resolving to that specific binding.

Let's look at an example. Imagine the following file `MathUtils.res`:

```rescript
let add = (a, b) => a + b
let sub = (a, b) => a - b
```

Now let's dynamically import the add function in another module, e.g. `App.res`:

<CodeTab labels={["ReScript", "JS Output (Module)"]}>
```rescript
// App.res
let main = async () => {
  let add = await import(MathUtils.add)
  let onePlusOne = add(1, 1)

Console.log(onePlusOne)
}

````
```javascript
async function main() {
  var add = await import("./MathUtils.mjs").then(function(m) {
    return m.add;
  });

  var onePlusOne = add(1, 1);
  console.log(onePlusOne);
}
````

</CodeTab>

### Dynamically Importing an Entire Module

The syntax for importing a whole module looks a little different, since we are operating on the module syntax level; instead of using `import`, you may simply `await` the module itself:

<CodeTab labels={["ReScript", "JS Output (Module)"]}>
```rescript
// App.res
let main = async () => {
  module Utils = await MathUtils

let twoPlusTwo = Utils.add(2, 2)
Console.log(twoPlusTwo)
}

````
```javascript
async function main() {
  var Utils = await import("./MathUtils.mjs");

  var twoPlusTwo = Utils.add(2, 2);
  console.log(twoPlusTwo);
}
````

</CodeTab>

## Export To JavaScript

### Export a Named Value

As mentioned in ReScript's idiomatic [Import & Export](./import-export.mdx), every let binding and module is exported by default to other ReScript modules (unless you use a `.resi` [interface file](./module.mdx#signatures)). If you open up the compiled JS file, you'll see that these values can also directly be used by a _JavaScript_ file too.

### Export a `default` Value

If your JS project uses JavaScript module, you're likely exporting & importing some default values:

```js
// student.js
export default name = "Al";
```

```js
// teacher.js
import studentName from "student.js";
```

A JavaScript default export is really just syntax sugar for a named export implicitly called `default` (now you know!). So to export a default value from ReScript, you can just do:

<CodeTab labels={["ReScript", "JS Output (Module)", "JS Output (CommonJS)"]}>

```res example
// ReScriptStudent.res
let default = "Bob"
```

```js
var $$default = "Bob";

exports.$$default = $$default;
exports.default = $$default;
// informal transpiler-compatible marker of a default export compiled from JavaScript module
exports.__esModule = true;
```

```js
var $$default = "Bob";

export { $$default, $$default as default };
```

</CodeTab>

You can then import this default export as usual on the JS side:

```js
// teacher2.js
import studentName from "ReScriptStudent.js";
```

If your JavaScript's default import is transpiled by Babel/Webpack/Jest into CommonJS `require`s, we've taken care of that too! See the CommonJS output tab for `__esModule`.

---
title: "Inlining Constants"
description: "Inlining constants"
canonical: "/docs/manual/inlining-constants"
section: "JavaScript Interop"
order: 10
---

# Inlining Constants

Sometimes, in the JavaScript output, you might want a certain value to be forcefully inlined. For example:

```js
if (process.env.mode === "development") {
  console.log("Dev-only code here!");
}
```

The reason is that your JavaScript bundler (e.g. Webpack) might turn that into:

```js
if ("production" === "development") {
  console.log("Dev-only code here!");
}
```

Then your subsequent Uglifyjs optimization would remove that entire `if` block. This is how projects like ReactJS provide a development mode code with plenty of dev warnings, while ensuring that the uglified (minified) production code is free of those expensive blocks.

So, in ReScript, producing that example `if (process.env.mode === 'development')` output is important. This first try doesn't work:

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

```res example
@val external process: 'a = "process"

let mode = "development"

if (process["env"]["mode"] === mode) {
  Console.log("Dev-only code here!")
}
```

```js
var mode = "development";

if (process.env.mode === mode) {
  console.log("Dev-only code here!");
}
```

</CodeTab>

The JS output shows `if (process.env.mode === mode)`, which isn't what we wanted. To inline `mode`'s value, use `@inline`:

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

```res example
@val external process: 'a = "process"

@inline
let mode = "development"

if (process["env"]["mode"] === mode) {
  Console.log("Dev-only code here!")
}
```

```js
if (process.env.mode === "development") {
  console.log("Dev-only code here!");
}
```

</CodeTab>

Now your resulting JS code can pass through Webpack and Uglifyjs like the rest of your JavaScript code, and that whole `console.log` can be removed.

The inlining currently only works for **string, float and boolean**.

## Tips & Tricks

This is **not** an optimization. This is an edge-case feature for folks who absolutely need particular values inlined for a JavaScript post-processing step, like conditional compilation. Beside the difference in code that the conditional compilation might end up outputting, there's no performance difference between inlining and not inlining simple values in the eyes of a JavaScript engine.

---
title: "Installation"
description: "ReScript installation and setup instructions"
canonical: "/docs/manual/installation"
section: "Overview"
order: 2
---

# Installation

## Prerequisites

<div className="install-list">
- [Node.js](https://nodejs.org/) version >= 22
- One of the following package managers: 
  - [npm](https://docs.npmjs.com/cli/) (comes with Node.js) 
  - [yarn](https://yarnpkg.com/) 
    - yarn versions >1 need to set `nodeLinker: node-modules` in `.yarnrc.yml` 
  - [pnpm](https://pnpm.io/) 
  - [bun](https://bun.sh/) 
  - [deno](http://deno.com/) 
    - Configure `"nodeModulesDir": "auto"` in `deno.json`
</div>

## New Project

The fastest and easiest way to spin up a new ReScript project is with the [create-rescript-app](https://github.com/rescript-lang/create-rescript-app) project generator. This will get you started with a fresh Next.js or Vite app with React and Tailwind CSS.

You can start it with any of the aforementioned package managers or `npx`.

<CodeTab labels={["npm", "npx", "yarn", "pnpm", "bun"]}>

```sh example
npm create rescript-app@latest
```

```sh
npx create-rescript-app
```

```sh
yarn create rescript-app
```

```sh
pnpm create rescript-app
```

```sh
bun create rescript-app
```

</CodeTab>

- Follow the steps of the setup.
- Trigger a ReScript build:

  ```sh
  npm run res:build
  ```
- If you selected the "basic" template, simply run it with:

  ```sh
  node src/Demo.res.mjs
  ```

That compiles your ReScript into JavaScript, then uses Node.js to run said JavaScript.

**When taking your first steps with ReScript, we recommend you use our unique workflow of keeping a tab open for the generated JS file** (`.res.js`/`.res.mjs`), so that you can learn how ReScript transforms into JavaScript. Not many languages output clean JavaScript code you can inspect and learn from! With our [VS Code extension](https://marketplace.visualstudio.com/items?itemName=chenglou92.rescript-vscode), use the command "ReScript: Open the compiled JS file for this implementation file" to open the generated JS file for the currently active ReScript source file.

During development, instead of running `npm run res:build` each time to compile, use `npm run res:dev` to start a watcher that recompiles automatically after file changes.

## Integrate Into an Existing JS Project

If you already have a JavaScript project into which you'd like to add ReScript you can do that in the following ways:

### Quick Setup

In the root directory of your project, execute:

<CodeTab labels={["npm", "npx", "yarn", "pnpm", "bun"]}>

```sh
npm create rescript-app@latest
```

```sh
npx create-rescript-app
```

```sh
yarn create rescript-app
```

```sh
pnpm create rescript-app
```

```sh
bun create rescript-app
```

</CodeTab>

`create-rescript-app` will tell you that a `package.json` file has been detected and ask you if it should install ReScript into your project. Just follow the steps accordingly.

### Manual Setup

- Install ReScript locally:

  <CodeTab labels={["npm", "yarn", "pnpm", "bun", "deno"]}>

  ```sh
  npm install rescript
  ```

  ```sh
  yarn add rescript
  ```

  ```sh
  pnpm install rescript
  ```

  ```sh
  bun install rescript
  ```

  ```sh
  // you will need deno configured to have a node_modules folder
  deno install npm:rescript --allow-scripts
  ```

  </CodeTab>

- Create a ReScript build configuration file (called `rescript.json`) at the root:
  ```json
  {
    "name": "your-project-name",
    "sources": [
      {
        "dir": "src", // update this to wherever you're putting ReScript files
        "subdirs": true
      }
    ],
    "package-specs": [
      {
        "module": "esmodule",
        "in-source": true
      }
    ],
    "suffix": ".res.js"
  }
  ```
  See [Build Configuration](./build-configuration.mdx) for more details on `rescript.json`.
- Add convenience `npm` scripts to `package.json`:
  ```json
  "scripts": {
    "build:res": "rescript",
    "dev:res": "rescript watch"
  }
  ```

Since ReScript compiles to clean readable JS files, the rest of your existing toolchain (e.g. Vite, Rspack, Rollup) should just work!

Helpful guides:

- [Converting from JS](./converting-from-js.mdx).
- [Shared Data Types](./shared-data-types.mdx).
- [Import from/Export to JS](./import-from-export-to-js.mdx).

### Integrate with a ReactJS Project

To start a [rescript-react](../react/introduction.mdx) app, or to integrate ReScript into an existing ReactJS app, follow the instructions [here](../react/installation.mdx).

---
title: "Interop Cheatsheet"
description: "Cheatsheet for various interop scenarios in ReScript"
canonical: "/docs/manual/interop-cheatsheet"
section: "JavaScript Interop"
order: 1
---

# Interop Cheatsheet

This is a glossary with examples. All the features are described by later pages.

## List of Decorators

> **Note:** In ReScript < 8.3, all our attributes started with the `bs.` prefix. This is no longer needed and our formatter automatically removes them in newer ReScript versions.

{/* Synced from https://github.com/rescript-lang/syntax/blob/123760c5a264da5288eeee5213ddd25eb86d62fe/src/res_printer.ml#L19-L51 */}

### Attributes

- `@as`: [here](./attribute.mdx#usage), [here](./bind-to-js-function.mdx#fixed-arguments), [here](./bind-to-js-function.mdx#constrain-arguments-better) and [here](./generate-converters-accessors.mdx#usage-3)
- [`@deriving`](./generate-converters-accessors.mdx#generate-functions--plain-values-for-variants)
- [`@get`](./bind-to-js-object.mdx#bind-using-special-bs-getters--setters)
- [`@get_index`](./bind-to-js-object.mdx#bind-using-special-bs-getters--setters)
- [`@inline`](./inlining-constants.mdx)
- [`@int`](./bind-to-js-function.mdx#constrain-arguments-better)
- [`@module`](./import-from-export-to-js.mdx#import-a-javascript-modules-content)
- [`@new`](./bind-to-js-object.mdx#bind-to-a-js-object-thats-a-class)
- [`@optional`](./generate-converters-accessors.mdx#optional-labels)
- [`@return`](./bind-to-js-function.mdx#function-nullable-return-value-wrapping)
- `@send`: [here](./bind-to-js-function.mdx#object-method) and [here](./pipe.mdx#js-method-chaining)
- [`@scope`](./bind-to-global-js-values.mdx#global-modules)
- [`@set`](./bind-to-js-object.mdx#bind-using-special-bs-getters--setters)
- [`@set_index`](./bind-to-js-object.mdx#bind-using-special-bs-getters--setters)
- [`@variadic`](./bind-to-js-function.mdx#variadic-function-arguments)
- [`@string`](./bind-to-js-function.mdx#constrain-arguments-better)
- [`@this`](./bind-to-js-function.mdx#modeling-this-based-callbacks)
- [`@uncurry`](./bind-to-js-function.mdx#extra-solution)
- [`@unwrap`](./bind-to-js-function.mdx#trick-2-polymorphic-variant--bsunwrap)
- [`@val`](./bind-to-global-js-values.mdx#global-modules)
- [`@taggedTemplate`](./bind-to-js-function.mdx#tagged_template-functions)
- [`@deprecated`](./attribute.mdx#usage)
- [`genType`](https://github.com/reason-association/genType)
- [`@JSX`](./jsx.mdx)
- `@react.component`: [here](../react/introduction.mdx) and [here](https://github.com/reasonml/reason-react)
- [`@warning`](./attribute.mdx#usage)
- [`@unboxed`](./variant.mdx#untagged-variants)

### Extension Points

- [`%debugger`](./embed-raw-javascript.mdx#debugger)
- [`%external`](./bind-to-global-js-values.mdx#special-global-values)
- [`%raw`](./embed-raw-javascript.mdx#paste-raw-js-code)
- [`%todo`](../../syntax-lookup/extension_todo.mdx)

## Raw JS

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

```res example
let add = %raw("(a, b) => a + b")
%%raw("const a = 1")
```

```js
var add = (a, b) => a + b;
const a = 1;
```

</CodeTab>

## Global Value

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

```res example
@val external setTimeout: (unit => unit, int) => float = "setTimeout"
```

```js
// Empty output
```

</CodeTab>

## Global Module's Value

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

```res example
@val @scope("Math")
external random: unit => float = "random"

let someNumber = random()

@val @scope(("window", "location", "ancestorOrigins"))
external length: int = "length"
```

```js
var someNumber = Math.random();
```

</CodeTab>

## Nullable

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

```res example
let a = Some(5) // compiles to 5
let b = None // compiles to undefined
```

```js
var a = 5;
var b;
```

</CodeTab>

Handling a value that can be `undefined` and `null`, by ditching the `option` type and using `Nullable.t`:

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

```res example
let jsNull = Nullable.null
let jsUndefined = Nullable.undefined
let result1: Nullable.t<string> = Nullable.make("hello")
let result2: Nullable.t<int> = Nullable.fromOption(Some(10))
let result3: option<int> = Nullable.toOption(Nullable.make(10))
```

```js
import * as Caml_option from "./stdlib/caml_option.js";
import * as Core__Nullable from "./stdlib/core__Nullable.js";

var result2 = Core__Nullable.fromOption(10);

var jsNull = null;

var jsUndefined;

var result1 = "hello";

var result3 = Caml_option.nullable_to_opt(10);
```

</CodeTab>

## JS Object

- [Bind to a JS object as a ReScript record](./bind-to-js-object.mdx#bind-to-record-like-js-objects).
- [Bind to a JS object that acts like a hash map](./bind-to-js-object.mdx#bind-to-hash-map-like-js-object).
- [Bind to a JS object that's a class](./bind-to-js-object.mdx#bind-to-a-js-object-thats-a-class).

## Function

### Object Method & Chaining

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

```res example
@send external map: (array<'a>, 'a => 'b) => array<'b> = "map"
@send external filter: (array<'a>, 'a => 'b) => array<'b> = "filter"
[1, 2, 3]
  ->map(a => a + 1)
  ->filter(a => mod(a, 2) == 0)
  ->Console.log
```

```js
console.log(
  [1, 2, 3]
    .map(function (a) {
      return (a + 1) | 0;
    })
    .filter(function (a) {
      return a % 2 === 0;
    }),
);
```

</CodeTab>

### Variadic Arguments

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

```res example
@module("path") @variadic
external join: array<string> => string = "join"
```

```js
// Empty output
```

</CodeTab>

### Tagged template functions

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

```res example
// see https://bun.sh/docs/runtime/shell
type result = {exitCode: int}
@module("bun") @taggedTemplate
external sh: (array<string>, array<string>) => promise<result> = "$"

let filename = "index.res"
let result = await sh`ls ${filename}`
```

```js
import * as $$Bun from "bun";
var filename = "index.res";
var result = await $$Bun.$`ls ${filename}`;
```

</CodeTab>

### Polymorphic Function

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

```res example
@module("Drawing") external drawCat: unit => unit = "draw"
@module("Drawing") external drawDog: (~giveName: string) => unit = "draw"
```

```js
// Empty output
```

</CodeTab>

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

```res example
@val
external padLeft: (
  string,
  @unwrap [
    | #Str(string)
    | #Int(int)
  ])
  => string = "padLeft"

padLeft("Hello World", #Int(4))
padLeft("Hello World", #Str("Message from ReScript: "))
```

```js
padLeft("Hello World", 4);
padLeft("Hello World", "Message from ReScript: ");
```

</CodeTab>

## JS Module Interop

[See here](./import-from-export-to-js.mdx)

## Dangerous Type Cast

Final escape hatch converter. Do not abuse.

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

```res example
external convertToFloat: int => float = "%identity"
let age = 10
let gpa = 2.1 + convertToFloat(age)
```

```js
var age = 10;
var gpa = 2.1 + 10;
```

</CodeTab>

---
title: "Interop with JS Build Systems"
description: "Documentation on how to interact with existing JS build systems"
canonical: "/docs/manual/interop-with-js-build-systems"
section: "Build System"
order: 6
---

# Interop with JS Build Systems

If you come from JS, chances are that you already have a build system in your existing project. Here's an overview of the role `rescript` would play in your build pipeline, if you want to introduce some ReScript code.

> **Please** try not to wrap `rescript` into your own incremental build framework. ReScript's compilation is very hard to get right, and you'll inevitably run into stale or badly performing builds (therefore erasing much of our value proposition) if you create your own meta layer on top.

## Popular JS Build Systems

The JS ecosystem uses a few build systems: [vite](https://vite.dev/), [browserify](http://browserify.org/), [rollup](https://github.com/rollup/rollup), [webpack](https://webpack.js.org/), etc. The first one is probably the most popular of the four (as of 2025). These build systems do both the compilation and the linking (aka, bundling many files into one or few files).

`rescript` only takes care of the compilation step; it maps one `.res`/`.resi` file into one JS output file. As such, in theory, no build system integration is needed from our side. From e.g. the webpack watcher's perspective, the JS files ReScript generates are almost equivalent to your hand-written JS files. We also recommend **that you initially check in those ReScript-generated JS files**, as this workflow means:

- You can introduce ReScript silently into your codebase without disturbing existing infra.
- You have a **visual** diff of the performance & correctness of your JS file when you update the `.res` files and the JS artifacts change.
- You can let teammates hot-patch the JS files in emergency situations, without needing to first start learning ReScript.
- You can remove ReScript completely from your codebase and things will still work (in case your company decides to stop using us for whatever reason).

For what it's worth, you can also turn `rescript` into an automated step in your build pipeline, e.g. into a Webpack loader; but such approach is error-prone and therefore discouraged.

### Tips & Tricks

You can make ReScript JS files look even more idiomatic through the in-source + bs suffix config in `rescript.json`:

```json
{
  "package-specs": {
    "module": "commonjs", // or whatever module system your project uses
    "in-source": true
  },
  "suffix": ".res.js"
}
```

This will:

- Generate the JS files alongside your ReScript source files.
- Use the file extension `.res.js`, so that you can require these files on the JS side through `require('./MyFile.res.js')`, without needing a loader.

## Use Loaders on ReScript Side

"What if my build system uses a CSS/png/whatever loader and I'd like to use it in ReScript?"

Loaders are indeed troublesome; in the meantime, please use e.g. `%raw("require('./myStyles.css')")` at the top of your file. This just uses [`raw`](./embed-raw-javascript.mdx) to compile the snippet into an actual JS require.

## Getting Project's Dependencies

`rescript` generates one `MyFile.d` file per `MyFile` source file; you'll find them in `lib/bs`. These are human readable, machine-friendly list of the dependencies of said `MyFile`. You can read into them for your purpose (though mind the IO overhead). Use these files instead of creating your own dependency graph; we did the hard work of tracking the dependencies as best as possible (including inner modules, `open`s, module names overlap, etc).

## Run Script Per File Built

See [js-post-build](./build-configuration.mdx#js-post-build). Though please use it sparingly; if you hook up a node.js script after each file built, you'll incur the node startup time per file!

---
title: "Introduction"
description: "Introduction to the ReScript programming language"
canonical: "/docs/manual/introduction"
section: "Overview"
order: 1
---

# ReScript

ReScript is a robustly typed language that compiles to efficient and human-readable JavaScript. It comes with a lightning fast compiler toolchain that scales to any codebase size.

## JavaScript Interop

ReScript compiles to clean, readable, and performant JavaScript, directly runnable in browsers and Node. Your existing package managers, bundlers, frameworks, and test runners all work with ReScript.

Your existing knowledge of web development transfers to ReScript projects.

ReScript code can be [imported into JavaScript code](./import-from-export-to-js.mdx#export-to-javascript), can [generate types for TypeScript](./typescript-integration.mdx), and ReScript can [import code written in JavaScript or TypeScript](./import-from-export-to-js.mdx#import-from-javascript).

## Type System

- Is deliberately curated to be a simple subset most folks will have an easier time to use.
- Sound type system. If a type isn't marked as nullable, the value will never be `undefined`. **ReScript code has no null/undefined errors**.
- No configuration needed. The type system behaves the same way in every project.
- Runs extremely fast precisely thanks to its simplicity and curation. It's one of the fastest compiler & build system toolchains for JavaScript development.
- **Doesn't need type annotations**. Annotate as much or as little as you'd like. The types are inferred by the language (and, again, are guaranteed correct).

## Compiler

### Compiles to Optimized JavaScript

ReScript's type system and compiler generate JavaScript that is performant by default, taking advantage of Just-In-Time optimizations (hidden classes, inline caching, avoiding deopts, etc).

### Tiny JS Output

A `Hello world` ReScript program generates **20 bytes** of JS code. Additionally, the standard library pieces you require in are only included when needed.

### Fast Iteration Loop

ReScript's build time is **one or two orders of magnitude** faster than alternatives. In its watcher mode, the build system usually finishes before you switch screen from the editor to the terminal tab (two digits of milliseconds). A fast iteration cycle reduces the need of keeping one's mental state around longer; this in turn allows one to stay in the flow longer and more often.

### Readable Output

ReScript's JS output is very readable. This is especially important while learning, where users might want to understand how the code's compiled, and to audit for bugs.

This characteristic, combined with a fully-featured JS interop system, allows ReScript code to be inserted into an existing JavaScript codebase almost unnoticed.

### Preservation of Code Structure

ReScript maps one source file to one JavaScript output file. This eases the integration of existing tools such as bundlers and test runners. You can even start writing a single file without much change to your build setup. Each file's code structure is approximately preserved, too.

### High Quality Dead Code Elimination

The JavaScript ecosystem is very reliant on dependencies. Shipping the final product inevitably drags in a huge amount of code, lots of which the project doesn't actually use. These regions of dead code impact loading, parsing and interpretation speed. ReScript provides powerful dead code elimination at all levels:

- Function- and module-level code elimination is facilitated by the well-engineered type system and purity analysis.
- At the global level, ReScript generates code that is naturally friendly to dead code elimination done by bundling tools such as [Rollup](https://github.com/rollup/rollup) and [Closure Compiler](https://developers.google.com/closure/compiler/), after its own sophisticated elimination pass.
- The same applies for ReScript's own tiny runtime (which is written in ReScript itself).

---
title: "JSON"
description: "Interacting with JSON in ReScript"
canonical: "/docs/manual/json"
section: "JavaScript Interop"
order: 9
---

# JSON

## Parse

Bind to JavaScript's `JSON.parse` and type the return value as the type you're expecting:

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

```res example
// declare the shape of the json you're binding to
type data = {names: array<string>}

// bind to JS' JSON.parse
@scope("JSON") @val
external parseIntoMyData: string => data = "parse"

let result = parseIntoMyData(`{"names": ["Luke", "Christine"]}`)
let name1 = result.names[0]
```

```js
var result = JSON.parse('{"names": ["Luke", "Christine"]}');
var name1 = result.names[0];
```

</CodeTab>

Where `data` can be any type you assume the JSON is. As you can see, this compiles to a straightforward `JSON.parse` call. As with regular JS, this is convenient, but has no guarantee that e.g. the data is correctly shaped, or even syntactically valid. Slightly dangerous.

## Stringify

Use [`JSON.stringify`](/docs/manual/api/stdlib/json#value-stringify) if your data is of type `JSON.t` or [`JSON.stringifyAny`](/docs/manual/api/stdlib/json#value-stringifyAny) if it is not.

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

```res example
Console.log(JSON.stringifyAny(["Amy", "Joe"]))
```

```js
console.log(JSON.stringify(["Amy", "Joe"]));
```

</CodeTab>

## Import a JSON file

Use the `@module` attribute to import JSON files directly.

<CodeTab labels={["ReScript", "JS Output (Module)", "JS Output (CommonJS)"]}>

```res example
@module external studentNames: JSON.t = "./students.json"
Console.log(studentNames)
```

```js
import * as StudentsJson from "./students.json";

var studentNames = StudentsJson;

console.log(studentNames);
```

```js
var StudentsJson = require("./students.json");

var studentNames = StudentsJson;

console.log(studentNames);
```

</CodeTab>

## Advanced

The generated types are [variants](./variant.mdx), and decoding them requires you to drill down as much

---
title: "JSX"
description: "JSX syntax in ReScript and React"
canonical: "/docs/manual/jsx"
section: "Language Features"
order: 18
---

# JSX

Would you like some HTML syntax in your ReScript? If not, quickly skip over this section and pretend you didn't see anything!

ReScript supports the JSX syntax, with some slight differences compared to the one in [ReactJS](https://facebook.github.io/react/docs/introducing-jsx.html). ReScript JSX isn't tied to ReactJS; they translate to normal function calls:

**Note** for [ReScriptReact](../react/introduction.mdx) readers: this isn't what ReScriptReact turns JSX into, in the end. See Usage section for more info.

## Capitalized

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

```res
<MyComponent name={"ReScript"} />
```

```js
import * as JsxRuntime from "react/jsx-runtime";

JsxRuntime.jsx(MyComponent, {
  name: "ReScript",
});
```

</CodeTab>

becomes

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

```res
React.jsx(MyComponent.make, {name: {"ReScript"}})
```

```js
import * as JsxRuntime from "react/jsx-runtime";

JsxRuntime.jsx(MyComponent, {
  name: "ReScript",
});
```

</CodeTab>

## Uncapitalized

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

```res
<div onClick={handler}> child1 child2 </div>
```

```js
import * as JsxRuntime from "react/jsx-runtime";

JsxRuntime.jsxs("div", {
  children: [child1, child2],
  onClick: handler,
});
```

</CodeTab>

becomes

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

```res
ReactDOM.jsxs("div", {onClick: {handler}, children: React.array([child1, child2])})
```

```js
import * as JsxRuntime from "react/jsx-runtime";

JsxRuntime.jsxs("div", {
  children: [child1, child2],
  onClick: handler,
});
```

</CodeTab>

## Fragment

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

```res
<> child1 child2 </>
```

```js
import * as JsxRuntime from "react/jsx-runtime";

JsxRuntime.jsxs(JsxRuntime.Fragment, {
  children: [child1, child2],
});
```

</CodeTab>

becomes

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

```res
React.jsxs(React.jsxFragment, {children: React.array([child1, child2])})
```

```js
import * as JsxRuntime from "react/jsx-runtime";

JsxRuntime.jsxs(JsxRuntime.Fragment, {
  children: [child1, child2],
});
```

</CodeTab>

### Children

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

```res
<MyComponent> child1 child2 </MyComponent>
```

```js
import * as JsxRuntime from "react/jsx-runtime";

JsxRuntime.jsxs(MyComponent, {
  children: [child1, child2],
});
```

</CodeTab>

This is the syntax for passing a list of two items, `child1` and `child2`, to the children position. It transforms to a list containing `child1` and `child2`:

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

```res
React.jsxs(MyComponent.make, {children: React.array([child1, child2])})
```

```js
import * as JsxRuntime from "react/jsx-runtime";

JsxRuntime.jsxs(MyComponent, {
  children: [child1, child2],
});
```

</CodeTab>

**Note** again that this isn't the transform for ReScriptReact; ReScriptReact turns the final list into an array. But the idea still applies.

So naturally, `<MyComponent> myChild </MyComponent>` is transformed to `React.jsx(MyComponent.make, {children: myChild})`. I.e. whatever you do, the arguments passed to the children position will be wrapped in a list.

## Usage

See [ReScriptReact Elements & JSX](../react/elements-and-jsx.mdx) for an example application of JSX, which transforms the above calls into a ReScriptReact-specific call.

Here's a JSX tag that shows most of the features.

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

```res
<MyComponent
  booleanAttribute={true}
  stringAttribute="string"
  intAttribute=1
  forcedOptional=?{Some("hello")}
  onClick={handleClick}>
  <div> {React.string("hello")} </div>
</MyComponent>
```

```js
import * as JsxRuntime from "react/jsx-runtime";

JsxRuntime.jsx(Playground$MyComponent, {
  children: JsxRuntime.jsx("div", {
    children: "hello",
  }),
  booleanAttribute: true,
  stringAttribute: "string",
  intAttribute: 1,
  forcedOptional: "hello",
  onClick: handleClick,
});
```

</CodeTab>

## Departures From JS JSX

- Attributes and children don't mandate `{}`, but we show them anyway for ease of learning. Once you format your file, some of them go away and some turn into parentheses.
- Props spread is supported, but there are some restrictions (see below).
- Punning!
- Props and tag names have to follow ReScript's restrictions on identifiers at the exception of hyphens for lowercase tags ([see below](#hyphens-in-tag-names)).

### Spread Props

**Since 10.1**

JSX props spread is supported with type safety.

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

```res
<Comp {...props} a="a" />
```

```js
import * as JsxRuntime from "react/jsx-runtime";

JsxRuntime.jsx(Comp.make, {
  a: "a",
  b: "b",
});
```

</CodeTab>

Multiple spreads are not allowed:

<CodeTab labels={["ReScript"]}>

```res
<NotAllowed {...props1} {...props2} />
```

</CodeTab>

The spread must be at the first position, followed by other props:

<CodeTab labels={["ReScript"]}>

```res
<NotAllowed a="a" {...props} />
```

</CodeTab>

### Punning

"Punning" refers to the syntax shorthand for when a label and a value are the same. For example, in JavaScript, instead of doing `return {name: name}`, you can do `return {name}`.

JSX supports punning. `<input checked />` is just a shorthand for `<input checked=checked />`. The formatter will help you format to the punned syntax whenever possible. This is convenient in the cases where there are lots of props to pass down:

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

```res
<MyComponent isLoading text onClick />
```

```js
import * as JsxRuntime from "react/jsx-runtime";

JsxRuntime.jsx(MyComponent, {
  text: text,
  isLoading: true,
  onClick: onClick,
});
```

</CodeTab>

Consequently, a JSX component can cram in a few more props before reaching for extra libraries solutions that avoids props passing.

**Note** that this is a departure from ReactJS JSX, which does **not** have punning. ReactJS' `<input checked />` desugars to `<input checked=true />`, in order to conform to DOM's idioms and for backward compatibility.

### Hyphens in tag names

**Since 11.1**

JSX now supports lowercase tags with hyphens in their name. This allows to bind
to web components.

Note though that props names can't have hyphens, you should use `@as` to bind to
such props in your custom `JsxDOM.domProps` type ([see generic JSX transform](#generic-jsx-transform-jsx-beyond-react-experimental)).

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

```res
<model-viewer src touchActions="pan-y"></model-viewer>
```

```js
import * as JsxRuntime from "react/jsx-runtime";

JsxRuntime.jsx("model-viewer", {
  "touch-actions": "pan-y",
  src: src,
});
```

</CodeTab>

## Generic JSX transform: JSX beyond React (experimental)

**Since 11.1**

While ReScript comes with first class support for JSX in React, it's also possible to have ReScript delegate JSX to other frameworks. You do that by configuring a _generic JSX transform_.

This is what you need to do to use a generic JSX transform:

1. Make sure you have a ReScript module that [implements the functions and types necessary for the JSX transform](#implementing-a-generic-jsx-transform-module).
2. Configure `rescript.json` to delegated JSX to that module.

That's it really. We'll expand on each point below.

### Configuration

You configure a generic JSX transform by putting any module name in the `module` config of JSX in `rescript.json`. This can be _any valid module name_. Example part from `rescript.json`:

```json
"jsx": {
  "module": "Preact"
 },
```

This will now put the `Preact` module in control of the generated JSX calls. The `Preact` module can be defined by anyone - locally in your project, or by a package. As long a it's available in the global scope. The JSX transform will delegate any JSX related code to `Preact`.

#### What about `@react.component` for components?

`@react.component` will still be available, and so is a generic `@jsx.component` notation. Both work the same way.

### Usage Example

Here's a quick usage example (the actual definition of `Preact.res` comes below):

First, configure `rescript.json`:

```json
"jsx": {
  "module": "Preact"
 },
```

Now you can build Preact components:

```rescript
// Name.res
@jsx.component // or @react.component if you want
let make = (~name) => Preact.string(`Hello ${name}!`)
```

And you can use them just like normal with JSX:

```rescript
let name = <Name name="Test" />
```

#### File level configuration

You can configure what JSX transform is used at the file level via `@@jsxConfig`, just like before. Like:

```rescript
@@jsxConfig({module_: "Preact"})
```

This can be convenient if you're mixing different JSX frameworks in the same project.

### Implementing a generic JSX transform module

Below is a full list of everything you need in a generic JSX transform module, including code comments to clarify. It's an example implementation of a `Preact` transform, so when doing this for other frameworks you'd of course adapt what you import from, and so on.

> You can easily copy-paste-and-adapt this to your needs if you're creating bindings to a JSX framework. Most often, all you'll need to change is what the `@module("") external` points to, so the runtime calls point to the correct JS module.

<CodeTab labels={["ReScript"]}>

```rescript
// Preact.res
/* Below is a number of aliases to the common `Jsx` module */
type element = Jsx.element

type component<'props> = Jsx.component<'props>

type componentLike<'props, 'return> = Jsx.componentLike<'props, 'return>

@module("preact/jsx-runtime")
external jsx: (component<'props>, 'props) => element = "jsx"

@module("preact/jsx-runtime")
external jsxKeyed: (component<'props>, 'props, ~key: string=?, @ignore unit) => element = "jsx"

@module("preact/jsx-runtime")
external jsxs: (component<'props>, 'props) => element = "jsxs"

@module("preact/jsx-runtime")
external jsxsKeyed: (component<'props>, 'props, ~key: string=?, @ignore unit) => element = "jsxs"

/* These identity functions and static values below are optional, but lets
you move things easily to the `element` type. The only required thing to
define though is `array`, which the JSX transform will output. */
external array: array<element> => element = "%identity"
@val external null: element = "null"

external float: float => element = "%identity"
external int: int => element = "%identity"
external string: string => element = "%identity"
external promise: promise<element> => element = "%identity"

/* These are needed for Fragment (<> </>) support */
type fragmentProps = {children?: element}

@module("preact/jsx-runtime") external jsxFragment: component<fragmentProps> = "Fragment"

/* The Elements module is the equivalent to the ReactDOM module in Preact. This holds things relevant to _lowercase_ JSX elements. */
module Elements = {
  /* Here you can control what props lowercase JSX elements should have.
  A base that the React JSX transform uses is provided via JsxDOM.domProps,
  but you can make this anything. The editor tooling will support
  autocompletion etc for your specific type. */
  type props = JsxDOM.domProps

  @module("preact/jsx-runtime")
  external jsx: (string, props) => Jsx.element = "jsx"

  @module("preact/jsx-runtime")
  external div: (string, props) => Jsx.element = "jsx"

  @module("preact/jsx-runtime")
  external jsxKeyed: (string, props, ~key: string=?, @ignore unit) => Jsx.element = "jsx"

  @module("preact/jsx-runtime")
  external jsxs: (string, props) => Jsx.element = "jsxs"

  @module("preact/jsx-runtime")
  external jsxsKeyed: (string, props, ~key: string=?, @ignore unit) => Jsx.element = "jsxs"

  external someElement: element => option<element> = "%identity"
}
```

</CodeTab>

As you can see, most of the things you'll want to implement will be copy paste from the above. But do note that **everything needs to be there unless explicitly noted** or the transform will fail at compile time.

To enable this, you need to configure the `jsx` `module` in your `rescript.json`:

```json
{
  "jsx": {
    "version": 4,
    "module": "Preact"
  }
}
```

_value "Preact" is the name of the module that implements the generic JSX transform._

## Preserve mode

**Since 12.0**

JSX Preserve Mode keeps JSX syntax in the compiled JavaScript output instead of transforming it to `JsxRuntime.jsx` calls. This lets bundlers (ESBuild, SWC, Next.js) or React Server Components handle JSX transformation.

### Configuration

```json
{
  "jsx": {
    "version": 4,
    "preserve": true
  }
}
```

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

```res
let c1 = <div className="foo"> {React.string("Hello")} </div>
let c2 = <MyComponent text="hey" isLoading=true onClick />
```

```js
let c1 = <div className={"foo"}>{"Hello"}</div>;

let c2 = <MyComponent.make text={"hey"} isLoading={true} onClick={onClick} />;
```

</CodeTab>

Note that the JSX output is functional but not always the most aesthetically pleasing.

---
title: "Lazy Value"
description: "Data type for deferred computation in ReScript"
canonical: "/docs/manual/lazy-values"
section: "Language Features"
order: 20
---

# Lazy Value

If you have some expensive computations you'd like to **defer and cache** subsequently, you can turn them into _lazy_ values:

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

```res prelude
@module("node:fs")
external readdirSync: string => array<string> = "readdirSync"

// Read the directory, only once
let expensiveFilesRead = Lazy.make(() => {
  Console.log("Reading dir")
  readdirSync("./pages")
})
```

```js
import * as Lazy from "./stdlib/Lazy.js";
import * as Nodefs from "node:fs";

let expensiveFilesRead = Lazy.make(() => {
  console.log("Reading dir");
  return Nodefs.readdirSync("./pages");
});
```

</CodeTab>

**Note**: a lazy value is **not** a [shared data type](./shared-data-types.mdx). Don't rely on its runtime representation in your JavaScript code.

## Execute The Lazy Computation

To actually run the lazy value's computation, use `Lazy.get` from the standard library `Lazy` module:

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

```res example
// First call. The computation happens
Console.log(Lazy.get(expensiveFilesRead)) // logs "Reading dir" and the directory content

// Second call. Will just return the already calculated result
Console.log(Lazy.get(expensiveFilesRead)) // logs the directory content
```

```js
console.log(Lazy.get(expensiveFilesRead));

console.log(Lazy.get(expensiveFilesRead));
```

</CodeTab>

The first time `Lazy.get` is called, the expensive computation happens and the result is **cached**. The second time, the cached value is directly used.

**You can't re-trigger the computation after the first `get` call**. Make sure you only use a lazy value with computations whose results don't change (e.g. an expensive server request whose response is always the same).

## Exception Handling

For completeness' sake, our files read example might throw an exception because of `readdirSync`. Here's how you'd handle it:

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

```res example
let result = try {
  Lazy.get(expensiveFilesRead)
} catch {
| Not_found => [] // empty array of files
}
```

```js
let result;

try {
  result = Lazy.get(expensiveFilesRead);
} catch (raw_exn) {
  let exn = Primitive_exceptions.internalToException(raw_exn);
  if (exn.RE_EXN_ID === "Not_found") {
    result = [];
  } else {
    throw exn;
  }
}
```

</CodeTab>

Though you should probably handle the exception inside the lazy computation itself.

---
title: "Let Binding"
description: "Let binding syntax for binding to values in ReScript"
canonical: "/docs/manual/let-binding"
section: "Language Features"
order: 2
---

# Let Binding

A "let binding", in other languages, might be called a "variable declaration". `let` _binds_ values to names. They can be seen and referenced by code that comes _after_ them.

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

```res example
let greeting = "hello!"
let score = 10
let newScore = 10 + score
```

```js
var greeting = "hello!";
var score = 10;
var newScore = 20;
```

</CodeTab>

## Block Scope

Bindings can be scoped through `{}`.

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

```res example
let message = {
  let part1 = "hello"
  let part2 = "world"
  part1 ++ " " ++ part2
}
// `part1` and `part2` not accessible here!
```

```js
var message = "hello world";
```

</CodeTab>

The value of the last line of a scope is implicitly returned.

### Design Decisions

ReScript's `if`, `while` and functions all use the same block scoping mechanism. The code below works **not** because of some special "if scope"; but simply because it's the same scope syntax and feature you just saw:

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

```res
if displayGreeting {
  let message = "Enjoying the docs so far?"
  Console.log(message)
}
// `message` not accessible here!
```

```js
if (displayGreeting) {
  console.log("Enjoying the docs so far?");
}
```

</CodeTab>

## Bindings Are Immutable

Let bindings are "immutable", aka "cannot change". This helps our type system deduce and optimize much more than other languages (and in turn, help you more).

## Binding Shadowing

The above restriction might sound unpractical at first. How would you change a value then? Usually, 2 ways:

The first is to realize that many times, what you want isn't to mutate a variable's value. For example, this JavaScript pattern:

```js
var result = 0;
result = calculate(result);
result = calculateSomeMore(result);
```

...is really just to comment on intermediate steps. You didn't need to mutate `result` at all! You could have just written this JS:

```js
var result1 = 0;
var result2 = calculate(result1);
var result3 = calculateSomeMore(result2);
```

In ReScript, this obviously works too:

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

```res
let result1 = 0
let result2 = calculate(result1)
let result3 = calculateSomeMore(result2)
```

```js
var result1 = 0;
var result2 = calculate(0);
var result3 = calculateSomeMore(result2);
```

</CodeTab>

Additionally, reusing the same let binding name overshadows the previous bindings with the same name. So you can write this too:

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

```res
let result = 0
let result = calculate(result)
let result = calculateSomeMore(result)
```

```js
var result = calculate(0);
var result$1 = calculateSomeMore(result);
```

</CodeTab>

(Though for the sake of clarity, we don't recommend this).

As a matter of fact, even this is valid code:

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

```res example
let result = "hello"
Console.log(result) // prints "hello"
let result = 1
Console.log(result) // prints 1
```

```js
var result = 1;
console.log("hello");
console.log(1);
```

</CodeTab>

The binding you refer to is whatever's the closest upward. No mutation here!
If you need _real_ mutation, e.g. passing a value around, have it modified by many pieces of code, we provide a slightly heavier [mutation feature](./mutation.mdx).

## Private let bindings

Private let bindings are introduced in the release [7.2](../../blog/archived/bucklescript-release-7-2.mdx).

In the module system, everything is public by default,
the only way to hide some values is by providing a separate signature to
list public fields and their types:

```res
module A: {
  let b: int
} = {
  let a = 3
  let b = 4
}
```

`%%private` gives you an option to mark private fields directly

```res
module A = {
  %%private(let a = 3)
  let b = 4
}
```

`%%private` also applies to file level modules, so in some cases,
users do not need to provide a separate interface file just to hide some particular values.

Note interface files are still recommended as a general best practice since they give you better
separate compilation units and also they're better for documentation.

Still, `%%private` is useful in the following scenarios:

- **Code generators.** Some code generators want to hide some values but it is sometimes very hard or time consuming for code generators to synthesize the types for public fields.

- **Quick prototyping.** During prototyping, we still want to hide some values, but the interface file is not stable yet. `%%private` provides you such convenience.

---
title: "Libraries & Publishing"
description: "Install & publish ReScript packages"
canonical: "/docs/manual/libraries"
section: "JavaScript Interop"
order: 14
---

# Libraries & Publishing

ReScript libraries are just like JavaScript libraries: published & hosted on [NPM](http://npmjs.com). You can reuse your `npm`, `yarn` and `package.json`-related tools to manage them!

## Tips & Tricks

### Publish

We recommend you to check in your compiled JavaScript output, for its [various benefits](./interop-with-js-build-systems.mdx#popular-js-build-systems). If not, then at least consider publishing the JavaScript output by un-ignoring them in your [npmignore](https://docs.npmjs.com/cli/v7/using-npm/developers#keeping-files-out-of-your-package). This way, your published ReScript package comes with plain JavaScript files that JS users can consume. If your project's good, JS users might not even realize that they've installed a library written in ReScript!

### Find Libraries

Search `rescript`-related packages on NPM, or use our [Package Index](/packages).

If you can't find what you're looking for, remember that **you don't need a wrapper** to use a JS library:

- Most JS data types, such as array and objects, [map over cleanly to ReScript and vice-versa](./shared-data-types.mdx).
- You also have access to the familiar [Core API](/docs/manual/api/stdlib).
- You can use a JavaScript library without needing to install dedicated binding libraries. Check the [`external`](./external.mdx) page.

---
title: "LLMs"
description: "Documentation for LLMs"
canonical: "/docs/manual/llms"
section: "Overview"
order: 4
---

# Documentation for LLMs

We adhere to the [llms.txt convention](https://llmstxt.org/) to make documentation accessible to large language models and their applications.

Currently, we have the following files...

- [/llms/manual/llms.txt](/llms/manual/llms.txt) — a list of the available files for ReScript language.
- [/llms/manual/llm-full.txt](/llms/manual/llm-full.txt) — complete documentation for ReScript language.
- [/llms/manual/llm-small.txt](/llms/manual/llm-small.txt) — compressed version of the former, without examples.

...and package-level documentation:

- [/docs/react/llms](../react/llms.mdx) — the LLms documentation for ReScript React.

## Notes

- The content is automatically generated from the same source as the official documentation for the specific version

---
title: "Migrate to v11"
description: "Instructions on upgrading to ReScript 11"
canonical: "/docs/manual/migrate-to-v11"
---

# Migrate to ReScript 11

## Foreword

The ReScript community is proud to introduce ReScript V11 which comes with a ton of new features but also removes a lot of bulk.
A migration to it can be very straightforward, but it can also take some time, depending on your code style or what dependencies you use.

Please have a look at the full [set of breaking changes](#list-of-all-breaking-changes) below to be able to decide whether this is a task you want to undertake. There is also the possibilty to [opt-out of uncurried mode](#minimal-migration) for now, which is probably the most fundamental change of this release. That and other new and notable features are discussed in the following blogposts:

- [Blog: Improving Interop with unboxed types](../../blog/improving-interop.mdx)
- [Blog: Enhanced Ergonomics for Record Types](../../blog/enhanced-ergonomics-for-record-types.mdx)
- [Blog: First-Class Dynamic `import()` Support](../../blog/first-class-dynamic-import-support.mdx)
- [Blog: Uncurried Mode by Default](../../blog/uncurried-mode.mdx)

## Recommended Migration

### Uncurried Mode

For uncurried mode to take effect in ReScript 11 there is nothing to configure, it is activated by default.

### Adapt suffix

ReScript 11 now allows having arbitrary suffixes in the generated JavaScript files. However, it is still recommended to stick to using `.res.js`, `.res.mjs` or `.res.cjs`. For more information, read the Build System Configuration about [suffixes](./build-configuration.mdx#suffix).

### rescript.json

The old configuration filename `bsconfig.json` is deprecated. Rename `bsconfig.json` to `rescript.json` to get rid of the deprecation warning.

### ReScript Core standard library

[ReScript Core](https://github.com/rescript-association/rescript-core) is ReScript's new standard library. It replaces the complete `Js` module as well as some of the more frequently used modules from `Belt` and is recommended to use with uncurried mode.

It will be integrated into the compiler in a future version. In ReScript 11, it still needs to be installed manually:

```console
$ npm install @rescript/core
```

Then add `@rescript/core` to your `rescript.json`'s dependencies:

```diff
 {
   "bs-dependencies": [
+    "@rescript/core"
   ]
 }
```

Open it so it's available in the global scope.

```diff
 {
   "bsc-flags": [
+    "-open RescriptCore",
   ]
 }
```

One major change to be aware of is that array access now returns an `option`.

```res
let firstItem = myArray[0] // Some("hello")
```

If you would like to not use an `option`, you can use [`Array.getUnsafe`](/docs/manual/api/stdlib/array#value-getUnsafe).

For a detailed explanation on migration to ReScript Core, please refer to its [migration guide](https://github.com/rescript-association/rescript-core#migration). A semi-automated script is available as well.

See ReScript Core API docs [here](/docs/manual/api/stdlib).

### Removed bindings

Many Node bindings have been removed from the compiler. Please use [rescript-nodejs](https://github.com/TheSpyder/rescript-nodejs) instead or write your own local bindings.

## Minimal Migration

This guide describes the things to do at least to migrate to ReScript 11.

### Disable uncurried mode

If you use currying extensively and don't want to bother with adapting your code, or have dependencies that just don't work with uncurried mode yet, just set it to false in your `rescript.json`.

```json
{
  "uncurried": false
}
```

For more information, read the Build System Configuration about [uncurried](./build-configuration.mdx#uncurried).

## List of all breaking changes

Below is an excerpt from the compiler changelog about all the breaking changes of ReScript 11.

### Language and Compiler

- Add smart printer for pipe chains. https://github.com/rescript-lang/rescript-compiler/pull/6411 (the formatter will reformat existing code in certain cases)
- Parse `assert` as a regular function. `assert` is no longer a unary expression. Example: before `assert 1 == 2` is parsed as `(assert 1) == 2`, now it is parsed as `assert(1 == 2)`. https://github.com/rescript-lang/rescript-compiler/pull/6180
- Remove support for the legacy Reason syntax. Existing Reason code can be converted to ReScript syntax using ReScript 9 as follows:
  - `npx rescript@9 convert <reason files>`
- Curried after uncurried is not fused anymore: `(. x) => y => 3` is not equivalent to `(. x, y) => 3` anymore. It's instead equivalent to `(. x) => { y => 3 }`.
  Also, `(. int) => string => bool` is not equivalen to `(. int, string) => bool` anymore.
  These are only breaking changes for unformatted code.
- Exponentiation operator `**` is now right-associative. `2. ** 3. ** 2.` now compile to `Math.pow(2, Math.pow(3, 2))` and not anymore `Math.pow(Math.pow(2, 3), 2)`. Parentheses can be used to change precedence.
- Stop mangling object field names. If you had objects with field names containing "\_\_" or leading "\_", they won't be mangled in the compiled JavaScript and represented as it is without changes. https://github.com/rescript-lang/rescript-compiler/pull/6354
- `$$default` is no longer exported from the generated JavaScript when using default exports. https://github.com/rescript-lang/rescript-compiler/pull/6328
- `-bs-super-errors` flag has been deprecated along with Super_errors. https://github.com/rescript-lang/rescript-compiler/pull/6243
- Remove unsafe `` j`$(a)$(b)` `` interpolation deprecated in compiler version 10 https://github.com/rescript-lang/rescript-compiler/pull/6068
- `@deriving(jsConverter)` not supported anymore for variant types https://github.com/rescript-lang/rescript-compiler/pull/6088
- New representation for variants, where the tag is a string instead of a number. https://github.com/rescript-lang/rescript-compiler/pull/6088

### Compiler Libraries

- Fixed name collision between the newly defined Js.Json.t and the variant constructor in the existing Js.Json.kind type. To address this, the usage of the existing Js.Json.kind type can be updated to Js.Json.Kind.t. https://github.com/rescript-lang/rescript-compiler/pull/6317
- Remove rudimentary node bindings and undocumented `%node` extension. https://github.com/rescript-lang/rescript-compiler/pull/6285
- `@rescript/react` >= 0.12.0-alpha.2 is now required because of the React.fragment's children type fix. https://github.com/rescript-lang/rescript-compiler/pull/6238
- Remove deprecated module `Printexc`

### Build System and Tools

- Update watcher rules to recompile only on config and `*.res`/`*.resi`/`*.ml`/`.mli` file changes. Solves the issue of unnecessary recompiles on `.css`, `.ts`, and other unrelated file changes. https://github.com/rescript-lang/rescript-compiler/pull/6420
- Made pinned dependencies transitive: if _a_ is a pinned dependency of _b_ and _b_ is a pinned dependency of _c_, then _a_ is implicitly a pinned dependency of _c_. This change is only breaking if your build process assumes non-transitivity.
- Remove obsolete built-in project templates and the "rescript init" functionality. This is replaced by [create-rescript-app](https://github.com/rescript-lang/create-rescript-app) which is maintained separately.
- Do not attempt to build ReScript from source on npm postinstall for platforms without prebuilt binaries anymore.
- GenType: removed support for `@genType.as` for records and variants which has become unnecessary. Use the language's `@as` instead to channge the runtime representation without requiring any runtime conversion during FFI. https://github.com/rescript-lang/rescript-compiler/pull/6099 https://github.com/rescript-lang/rescript-compiler/pull/6101

---
title: "Migrate to v12"
description: "Instructions on upgrading to ReScript 12"
canonical: "/docs/manual/migrate-to-v12"
section: "Overview"
order: 4
---

# Migrate to ReScript 12

If you encounter any missing information or issues during migration, please [open an issue](https://github.com/rescript-lang/rescript-lang.org/issues/new?template=documentation_issue.md) or, even better, [send a pull request](https://github.com/rescript-lang/rescript-lang.org/) to help improve this guide.

## Recommended Migration

### Prerequisites

- ReScript V11 project.
- Uncurried mode must be enabled (i.e. you have not opted-out from it).
- Your project must not contain any OCaml source code anymore, as support for `.ml` files is removed in this version. However there are ways to convert OCaml syntax with an older ReScript compiler version ([see below](#converting-generated-ml-files)).
- Minimum supported Node.js version is 20.11.0.

### Standard Library Changes

In V12, the new standard library ships with the compiler, so you can uninstall and remove the `@rescript/core` dependency from your `rescript.json`

```console
$ npm remove @rescript/core
```

```diff
 {
   "bs-dependencies": [
-    "@rescript/core"
   ]
 }
```

Also remove auto opening of `RescriptCore`.

```diff
 {
   "bsc-flags": [
-    "-open RescriptCore",
   ]
 }
```

if you had `@rescript/std` installed, remove it as well:

```shell
npm uninstall @rescript/std
```

this is replaced by `@rescript/runtime`, which is a installed as a dependency of `rescript` now.

## Replacements

Some typical name changes include:

- `Error.t` -> `JsError.t`
- `raise(MyException("error"))` -> `throw(MyException("error"))`
- `Js.Exn.Error` exception -> `JsExn`
- `Error.make` -> `JsExn.make`
- `Error.raise` -> `JsExn.raise`
- `Error.message` -> `JsExn.message`
- `Bool.fromStringExn("true")` -> `Bool.fromStringOrThrow("true")`
- `Int.Bitwise.lsl` -> `Int.shiftLeft`

Tip: You can use the migration tool to automatically replace these with the new functions.

```shell
npx rescript-tools migrate-all <root>

# preview the changes via
rescript-tools migrate <file> [--stdout]
```

### Bitwise operations

v11:

```res
let w = lnot(a)     // bitwise NOT
let x = lxor(a, b)  // bitwise XOR
let y = land(a, b)  // bitwise AND
let z = lor(a, b)   // bitwise OR
```

v12:

```res
let w = ~~~a     // bitwise NOT
let x = a ^^^ b  // bitwise XOR
let y = a &&& b  // bitwise AND
let z = a ||| b  // bitwise OR
```

### Shift operations

v11:

```res
let x = lsl(a, b)  // logical left shift
let y = lsr(a, b)  // logical right shift
let z = asr(a, b)  // unsigned right shift
```

v12:

```res
let x = a << b  // logical left shift
let y = a >> b  // logical right shift
let z = a >>> b  // unsigned right shift
```

### JSX children spread

v11:

```res
<div> ...children </div>
```

v12:

```res
<div> children </div>
```

### Attributes

v11:

```res
@bs.as("foo")
@bs.send
@bs.new
@raises
@genType.as
```

v12:

```res
@as("foo")
@send
@new
@throws
@as
```

- `@meth` and `@bs.send.pipe` are removed.

### Assert

v11:

```res
assert 1 == 2
```

v12:

```res
assert(1 == 2)  // Now a regular function call
```

## Configuration

Rename `bsconfig.json` to `rescript.json` and update these configuration options:

- `bs-dependencies` → `dependencies`
- `bs-dev-dependencies` → `dev-dependencies`
- `bsc-flags` → `compiler-flags`

### jsx

- Set `version` to `4` (lower versions are not supported)
- Remove `mode` option (automatically set to `automatic`)

## Build System Changes

The build system has been completely rewritten in v12.0.0.

In v11, we had:

```shell
# build
rescript build

# watch build
rescript build -w

# format
rescript format -all
```

in v12, this becomes:

```shell
# build
rescript

# watch build
rescript watch

# format
rescript format
```

## Converting generated `.ml` files

**Note**: This setup is an escape hatch. It keeps legacy generators like `atdgen` working but it also forces you to maintain two compiler versions. Whenever possible migrate such things to modern ReScript tooling such as [Sury](https://github.com/DZakh/sury/).

Some projects still rely on tools such as `atdgen` that emit `.ml` files. ReScript 12 cannot compile those files directly, so you must keep using ReScript 11 **only** to convert the generated `.ml` files back to `.res` files before you run the v12 build.

1. Keep ReScript 12 as the sole compiler dependency in your main project (i.e. `devDependencies.rescript` stays at `^12.0.0`).

2. Install ReScript 11 in a dedicated subfolder (so its binaries never replace the v12 ones in `node_modules/.bin`). A simple option is to store it under a subfolder, e.g. `tools` (if you're using workspaces, keep this folder out of the root workspace list so hoisting can't swap the v12 shims):

`cd` into `tools` and run `npm create rescript-app` and select the basic template and a v11 version of ReScript. You can name it `rescript-11` for instance.

3. `cd` back into the root of your project and add a helper script that references the compiler from that folder (adapt the path accordingly):

   ```json
   {
     "scripts": {
       "convert-ml": "tools/rescript-11/node_modules/.bin/rescript convert src/*.ml"
     }
   }
   ```

4. Execute the helper script to convert your `.ml` files to `.res` files:

```console
npm run convert-ml
```

## List of all breaking changes

Below is a consolidated excerpt of all the breaking changes from the compiler changelog.

### Language & syntax

- Tag functions named `j` or `js` are no longer reserved, so add your own implementation whenever a tagged template expects them. https://github.com/rescript-lang/rescript-compiler/pull/6817
- `lazy` syntax was removed; use the `Lazy` module instead. https://github.com/rescript-lang/rescript-compiler/pull/6342
- All legacy `@bs.*` attributes (e.g. `@bs.as`, `@bs.send`) and `@bs.open` were removed; use their prefix-free successors (`@as`, `@send`, `@open`, …). https://github.com/rescript-lang/rescript-compiler/pull/6643 https://github.com/rescript-lang/rescript-compiler/pull/6629
- `@bs.send.pipe` was removed; rewrite bindings to use `@send`. https://github.com/rescript-lang/rescript-compiler/pull/6858 https://github.com/rescript-lang/rescript-compiler/pull/6891
- OCaml `.ml` files are no longer supported anywhere: `.ml` parsing/formatting went away and the `rescript convert` CLI was removed, so convert legacy files to `.res` before upgrading. https://github.com/rescript-lang/rescript-compiler/pull/6848 https://github.com/rescript-lang/rescript-compiler/pull/6852 https://github.com/rescript-lang/rescript-compiler/pull/6860
- Some global names and old keywords are no longer automatically prefixed during JS emission; update any code that was relying on the mangled names. https://github.com/rescript-lang/rescript-compiler/pull/6831
- JSX v3 and the `-bs-jsx-mode` option were removed and JSX children spreads are no longer valid; JSX v4 semantics are now the only supported mode. https://github.com/rescript-lang/rescript-compiler/pull/7072 https://github.com/rescript-lang/rescript/pull/7327 https://github.com/rescript-lang/rescript/pull/7869

### Standard library & runtime

- OCaml compatibility layers in the stdlib and primitives were removed/deprecated. https://github.com/rescript-lang/rescript-compiler/pull/6984
- Deprecated modules `Js.Vector` and `Js.List` were deleted. https://github.com/rescript-lang/rescript-compiler/pull/6900
- The legacy `js_cast.res` helpers were removed; migrate to explicit externals. https://github.com/rescript-lang/rescript-compiler/pull/7075
- `JsError` and related modules were renamed/cleaned up under `JsExn`. https://github.com/rescript-lang/rescript/pull/7408
- `BigInt.fromFloat` now returns `option` and exposes `BigInt.fromFloatOrThrow`, and the `Exn`-suffixed helpers across `Bool`, `BigInt`, `JSON`, `Option`, `Null`, `Nullable`, `Result`, and `List` now end with `OrThrow`. https://github.com/rescript-lang/rescript/pull/7419 https://github.com/rescript-lang/rescript/pull/7518 https://github.com/rescript-lang/rescript/pull/7554
- `Result.getOrThrow` throws a JS `Error` (instead of `Not_found`), and `Result.equal` / `Result.compare` now provide a comparison function for `Error` values. https://github.com/rescript-lang/rescript/pull/7630 https://github.com/rescript-lang/rescript/pull/7933
- `Iterator.forEach` now emits `Iterator.prototype.forEach`. https://github.com/rescript-lang/rescript/pull/7506
- `Date.make` uses `~day` instead of `~date`. https://github.com/rescript-lang/rescript/pull/7324
- Plain `int` multiplication is implemented as a regular int32 operation instead of `Math.imul`. https://github.com/rescript-lang/rescript/pull/7358
- The `List` API was cleaned up—several functions were renamed or removed (see the PR for the exact surface). https://github.com/rescript-lang/rescript/pull/7290
- `String.getSymbol` / `String.setSymbol` were removed; only `String.getSymbolUnsafe` remains on strings. https://github.com/rescript-lang/rescript/pull/7571 https://github.com/rescript-lang/rescript/pull/7626
- `String.charCodeAt` now returns `option<int>` and exposes `String.charCodeAtUnsafe` for unchecked access. https://github.com/rescript-lang/rescript/pull/7877
- `Intl.*.supportedLocalesOf` bindings now return `array<string>` and the non-portable `Intl.PluralRules.selectBigInt` / `selectRangeBigInt` were removed. https://github.com/rescript-lang/rescript/pull/7995

### Build system & CLI

- The new Rust-based `rewatch` build system now powers the `rescript` command. The old Ninja-based builder system moved behind `rescript legacy`, and `--compiler-args` became the `compiler-args` subcommand. https://github.com/rescript-lang/rescript/pull/7551 https://github.com/rescript-lang/rescript/pull/7593 https://github.com/rescript-lang/rescript/pull/7928
- `rescript format` was reimplemented in Rust, its options now use the `--check` / `--stdin` long-form spelling, and the `--all` flag was removed because every tracked file (non-dev by default) is formatted automatically. https://github.com/rescript-lang/rescript/pull/7603 https://github.com/rescript-lang/rescript/pull/7752
- The `rescript dump` command was removed; call `bsc` directly if you need to inspect `.cmi` files. https://github.com/rescript-lang/rescript/pull/7710

### Configuration & platform

- The minimum supported Node.js version is now 20.11.0. https://github.com/rescript-lang/rescript/pull/7354
- The `experimental-features` key in `rescript.json` now uses kebab-case to match the other config fields. https://github.com/rescript-lang/rescript/pull/7891
- The legacy `-bs-super-errors` flag was removed. https://github.com/rescript-lang/rescript-compiler/pull/6814

---
title: "Module Functions"
description: "Module Functions in ReScript"
canonical: "/docs/manual/module-functions"
section: "Advanced Features"
order: 3
---

# Module Functions

Module functions can be used to create modules based on types, values, or functions from other modules.
This is a powerful tool that can be used to create abstractions and reusable code that might not be possible with functions, or might have a runtime cost if done with functions.

This is an advanced part of ReScript and you can generally get by with normal values and functions.

## Quick example

Next.js has a `useParams` hook that returns an unknown type,
and it's up to the developer in TypeScript to add a type annotation for the parameters returned by the hook.

```TS
const params = useParams<{ tag: string; item: string }>()
```

In ReScript we can create a module function that will return a typed response for the `useParams` hook.

<CodeTab labels={["ReScript", "JS Output"]}>
```res example
module Next = {
  // define our module function
  module MakeParams = (Params: { type t }) => {
    @module("next/navigation")
    external useParams: unit => Params.t = "useParams"
    /* You can use values from the function parameter, such as Params.t */
  }
}

module Component: {
@react.component
let make: unit => Jsx.element
} = {
// Create a module that matches the module type expected by Next.MakeParams
module P = {
type t = {
tag: string,
item: string,
}
}

// Create a new module using the Params module we created and the Next.MakeParams module function
module Params = Next.MakeParams(P)

@react.component
let make = () => {

// Use the functions, values, or types created by the module function
let params = Params.useParams()

  <div>
    <p>
      {React.string("Tag: " ++ params.tag /* params is fully typed! */)}
    </p>
    <p> {React.string("Item: " ++ params.item)} </p>
  </div>
  }
}

````
```js
// Generated by ReScript, PLEASE EDIT WITH CARE

import * as $$Navigation from "next/navigation";
import * as JsxRuntime from "react/jsx-runtime";

function MakeParams(Params) {
  return {};
}

var Next = {
  MakeParams: MakeParams
};

function Playground$Component(props) {
  var params = $$Navigation.useParams();
  return JsxRuntime.jsxs("div", {
              children: [
                JsxRuntime.jsx("p", {
                      children: "Tag: " + params.tag
                    }),
                JsxRuntime.jsx("p", {
                      children: "Item: " + params.item
                    })
              ]
            });
}

var Component = {
  make: Playground$Component
};

export {
  Next ,
  Component ,
}
/* next/navigation Not a pure module */

````

</ CodeTab>

## Sharing a type with an external binding

This becomes incredibly useful when you need to have types that are unique to a project but shared across multiple components.
Let's say you want to create a library with a `getEnv` function to load in environment variables found in `import.meta.env`.

```res
@val external env: 'a = "import.meta.env"

let getEnv = () => {
  env
}
```

It's not possible to define types for this that will work for every project, so we just set it as 'a and the consumer of our library can define the return type.

```res
type t = {"LOG_LEVEL": string}

let values: t = getEnv()
```

This isn't great and it doesn't take advantage of ReScript's type system and ability to use types without type definitions, and it can't be easily shared across our application.

We can instead create a module function that can return a module that has contains a `getEnv` function that has a typed response.

```res
module MakeEnv = (
  E: {
    type t
  },
) => {
  @val external env: E.t = "import.meta.env"

  let getEnv = () => {
    env
  }
}
```

And now consumers of our library can define the types and create a custom version of the hook for their application.
Notice that in the JavaScript output that the `import.meta.env` is used directly and doesn't require any function calls or runtime overhead.

<CodeTab labels={["ReScript", "JS Output"]}>
```res
module Env = MakeEnv({
	type t = {"LOG_LEVEL": string}
})

let values = Env.getEnv()

````
```js
var Env = {
  getEnv: getEnv
};

var values = import.meta.env;
````

</ CodeTab>

## Shared functions

You might want to share functions across modules, like a way to log a value or render it in React.
Here's an example of module function that takes in a type and a transform to string function.

```res
module MakeDataModule = (
  T: {
    type t
    let toString: t => string
  },
) => {
  type t = T.t
  let log = a => Console.log("The value is " ++ T.toString(a))

  module Render = {
    @react.component
    let make = (~value) => value->T.toString->React.string
  }
}
```

You can now take a module with a type of `t` and a `toString` function and create a new module that has the `log` function and the `Render` component.

<CodeTab labels={["ReScript", "JS Output"]}>
```res
module Person = {
  type t = { firstName: string, lastName: string } 
  let toString = person => person.firstName ++ person.lastName
}

module PersonData = MakeDataModule(Person)

````

```js
// Notice that none of the JS output references the MakeDataModule function

function toString(person) {
  return person.firstName + person.lastName;
}

var Person = {
  toString: toString
};

function log(a) {
  console.log("The value is " + toString(a));
}

function Person$MakeDataModule$Render(props) {
  return toString(props.value);
}

var Render = {
  make: Person$MakeDataModule$Render
};

var PersonData = {
  log: log,
  Render: Render
};
````

</CodeTab>

Now the `PersonData` module has the functions from the `MakeDataModule`.

<CodeTab labels={["ReScript", "JS Output"]}>
```res
@react.component
let make = (~person) => {
  let handleClick = _ => PersonData.log(person)
  <div>
    {React.string("Hello ")}
    <PersonData.Render value=person />
    <button onClick=handleClick>
      {React.string("Log value to console")}
    </button>
  </div>
}
```
```js
function Person$1(props) {
  var person = props.person;
  var handleClick = function (param) {
    log(person);
  };
  return JsxRuntime.jsxs("div", {
              children: [
                "Hello ",
                JsxRuntime.jsx(Person$MakeDataModule$Render, {
                      value: person
                    }),
                JsxRuntime.jsx("button", {
                      children: "Log value to console",
                      onClick: handleClick
                    })
              ]
            });
}
```
</CodeTab>

## Dependency injection

Module functions can be used for dependency injection.
Here's an example of injecting in some config values into a set of functions to access a database.

<CodeTab labels={["ReScript", "JS Output"]}>
```res
module type DbConfig = {
  let host: string
  let database: string
  let username: string
  let password: string
}

module MakeDbConnection = (Config: DbConfig) => {
type client = {
write: string => unit,
read: string => string,
}
@module("database.js")
external makeClient: (string, string, string, string) => client = "makeClient"

let client = makeClient(Config.host, Config.database, Config.username, Config.password)
}

module Db = MakeDbConnection({
let host = "localhost"
let database = "mydb"
let username = "root"
let password = "password"
})

let updateDb = Db.client.write("new value")

````
```js
// Generated by ReScript, PLEASE EDIT WITH CARE

import * as DatabaseJs from "database.js";

function MakeDbConnection(Config) {
  var client = DatabaseJs.makeClient(Config.host, Config.database, Config.username, Config.password);
  return {
          client: client
        };
}

var client = DatabaseJs.makeClient("localhost", "mydb", "root", "password");

var Db = {
  client: client
};

var updateDb = client.write("new value");

export {
  MakeDbConnection ,
  Db ,
  updateDb ,
}
/* client Not a pure module */
````

</CodeTab>

---
title: "Module"
description: "ReScript modules, module signatures and interface files"
canonical: "/docs/manual/module"
section: "Language Features"
order: 24
---

# Module

## Basics

**Modules are like mini files**! They can contain type definitions, `let`
bindings, nested modules, etc.

### Creation

To create a module, use the `module` keyword. The module name must start with a
**capital letter**. Whatever you could place in a `.res` file, you may place
inside a module definition's `{}` block.

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

```res example
module School = {
  type profession = Teacher | Director

  let person1 = Teacher
  let getProfession = (person) =>
    switch person {
    | Teacher => "A teacher"
    | Director => "A director"
    }
}
```

```js
function getProfession(person) {
  if (person) {
    return "A director";
  } else {
    return "A teacher";
  }
}

var School = {
  person1: /* Teacher */ 0,
  getProfession: getProfession,
};
```

</CodeTab>

A module's contents (including types!) can be accessed much like a record's,
using the `.` notation. This demonstrates modules' utility for namespacing.

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

```res
let anotherPerson: School.profession = School.Teacher
Console.log(School.getProfession(anotherPerson)) /* "A teacher" */
```

```js
var anotherPerson = /* Teacher */ 0;
console.log("A teacher");
```

</CodeTab>

Nested modules work too.

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

```res example
module MyModule = {
  module NestedModule = {
    let message = "hello"
  }
}

let message = MyModule.NestedModule.message
```

```js
var NestedModule = {
  message: message,
};

var MyModule = {
  NestedModule: NestedModule,
};

var message = MyModule.NestedModule.message;
```

</CodeTab>

### `open`ing a module

Constantly referring to a value/type in a module can be tedious. Instead, we can "open" a module and refer to its contents without always prepending them with the
module's name. Instead of writing:

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

```res
let p = School.getProfession(School.person1)
```

```js
var p = School.getProfession(School.person1);
```

</CodeTab>

We can write:

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

```res
open School
let p = getProfession(person1)
```

```js
var p = School.getProfession(School.person1);
```

</CodeTab>

The content of `School` module are made visible (**not** copied into the file, but simply made visible!) in scope. `profession`, `getProfession` and `person1` will thus correctly be found.

**Use `open` this sparingly, it's convenient, but makes it hard to know where some values come from**. You should usually use `open` in a local scope:

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

```res
let p = {
  open School
  getProfession(person1)
}
/* School's content isn't visible here anymore */
```

```js
var p = School.getProfession(School.person1);
```

</CodeTab>

### Use `open!` to ignore shadow warnings

There are situations where `open` will cause a warning due to existing identifiers (bindings, types) being redefined. Use `open!` to explicitly tell the compiler that this is desired behavior.

```res
let map = (arr, value) => {
  value
}

// opening Array would shadow our previously defined `map`
// `open!` will explicitly turn off the automatic warning
open! Array
let arr = map([1,2,3], (a) => { a + 1})
```

**Note:** Same as with `open`, don't overuse `open!` statements if not necessary. Use (sub)modules to prevent shadowing issues.

### Destructuring modules

**Since 9.0.2**

As an alternative to `open`ing a module, you can also destructure a module's functions and values into separate let bindings (similarly on how we'd destructure an object in JavaScript).

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

```res
module User = {
  let user1 = "Anna"
  let user2 = "Franz"
}

// Destructure by name
let {user1, user2} = module(User)

// Destructure with different alias
let {user1: anna, user2: franz} = module(User)
```

```js
var user1 = "Anna";

var user2 = "Franz";

var User = {
  user1: user1,
  user2: user2,
};
```

</CodeTab>

**Note:** You can't extract types with module destructuring — use a type alias instead (`type user = User.myUserType`).

### Extending modules

Using `include` in a module statically "spreads" a module's content into a new one, thus often fulfill the role of "inheritance" or "mixin".

**Note**: this is equivalent to a compiler-level copy paste. **We heavily discourage `include`**. Use it as last resort!

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

```res example
module BaseComponent = {
  let defaultGreeting = "Hello"
  let getAudience = (~excited) => excited ? "world!" : "world"
}

module ActualComponent = {
  /* the content is copied over */
  include BaseComponent
  /* overrides BaseComponent.defaultGreeting */
  let defaultGreeting = "Hey"
  let render = () => defaultGreeting ++ " " ++ getAudience(~excited=true)
}
```

```js
function getAudience(excited) {
  if (excited) {
    return "world!";
  } else {
    return "world";
  }
}

var BaseComponent = {
  defaultGreeting: "Hello",
  getAudience: getAudience,
};

var defaultGreeting = "Hey";

function render(param) {
  return "Hey world!";
}

var ActualComponent = {
  getAudience: getAudience,
  defaultGreeting: defaultGreeting,
  render: render,
};
```

</CodeTab>

**Note**: `open` and `include` are very different! The former brings a module's content into your current scope, so that you don't have to refer to a value by prefixing it with the module's name every time. The latter **copies over** the definition of a module statically, then also do an `open`.

### Every `.res` file is a module

Every ReScript file is itself compiled to a module of the same name as the file name, capitalized. The file `React.res` implicitly forms a module `React`, which can be seen by other source files.

**Note**: ReScript file names should, by convention, be capitalized so that their casing matches their module name. Uncapitalized file names are not invalid, but will be implicitly transformed into a capitalized module name. I.e. `file.res` will be compiled into the module `File`. To simplify and minimize the disconnect here, the convention is therefore to capitalize file names.

## Signatures

A module's type is called a "signature", and can be written explicitly. If a
module is like a `.res` (implementation) file, then a module's signature is like
a `.resi` (interface) file.

### Creation

To create a signature, use the `module type` keyword. The signature name must start with a
**capital letter**. Whatever you could place in a `.resi` file, you may place
inside a signature definition's `{}` block.

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

```res example
/* Using the types defined above */
module type EstablishmentType = {
  type profession
  let getProfession: profession => string
}
```

```js
// Empty output
```

</CodeTab>

A signature defines the list of requirements that a module must satisfy in order
for that module to match the signature. Those requirements are of the form:

- `let x: int` requires a `let` binding named `x`, of type `int`.
- `type t = someType` requires a type field `t` to be equal to `someType`.
- `type t` requires a type field `t`, but without imposing any requirements on the actual, concrete type of `t`. We'd use `t` in other entries in the signature to describe relationships, e.g. `let makePair: t => (t, t)` but we cannot, for example, assume that `t` is an `int`. This gives us great, enforced abstraction abilities.

To illustrate the various kinds of type entries, consider the above signature
`EstablishmentType` which requires that a module:

- Declare a type named `profession`.
- Must include a function that takes in a value of the type `profession` and returns a string.

**Note**:

Modules of the type `EstablishmentType` can contain more fields than the
signature declares, just like the module `School` defined above (if we
choose to assign it the type `EstablishmentType`. Otherwise, `School` exposes
every field). This effectively makes the `person1` field an enforced
implementation detail! Outsiders can't access it, since it's not present in the
signature; the signature **constrained** what others can access.

The type `EstablishmentType.profession` is **abstract**: it doesn't have a
concrete type; it's saying "I don't care what the actual type is, but it's used
as input to `getProfession`". This is useful to fit many modules under the same
interface:

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

```res
module Company: EstablishmentType = {
  type profession = CEO | Designer | Engineer | ...

  let getProfession = (person) => ...
  let person1 = ...
  let person2 = ...
}
```

```js
function getProfession(person) {
  ...
}

var person1 = ...

var person2 = ...

var Company = {
  getProfession: getProfession,
  person1: person1,
  person2: person2
};
```

</CodeTab>

It's also useful to hide the underlying type as an implementation detail others
can't rely on. If you ask what the type of `Company.profession` is, instead of
exposing the variant, it'll only tell you "it's `Company.profession`".

This also means that the compiler can't make assumptions about the type.
In certain cases, when working with abstract types and `option` for example, the compiler doesn't know whether
the abstract type can be the JavaScript value `undefined` or not. This can lead to less optimal code being generated.
For this reason, you can use the `@notUndefined` decorator to tell the compiler that the abstract type can never be `undefined`
(use with caution and see the `@notUndefined` decorator documentation for more details and caveats).

### Extending module signatures

Like modules themselves, module signatures can also be extended by other module signatures using `include`. Again, **heavily discouraged**:

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

```res example
module type BaseComponent = {
  let defaultGreeting: string
  let getAudience: (~excited: bool) => string
}

module type ActualComponent = {
  /* the BaseComponent signature is copied over */
  include BaseComponent
  let render: unit => string
}
```

```js
// Empty output
```

</CodeTab>

**Note**: `BaseComponent` is a module **type**, not an actual module itself!

If you do not have a defined module type, you can extract it from an actual module
using `include (module type of ActualModuleName)`. For example, we can extend the
`List` module from the standard library, which does not define a module
type.

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

```res example
module type MyList = {
  include (module type of List)
  let myListFun: list<'a> => list<'a>
}
```

```js
// Empty output
```

</CodeTab>

### Every `.resi` file is a signature

Similar to how a `React.res` file implicitly defines a module `React`, a file
`React.resi` implicitly defines a signature for `React`. If `React.resi` isn't
provided, the signature of `React.res` defaults to exposing all the fields of the
module. Because they don't contain implementation files, `.resi` files are used
in the ecosystem to also document the public API of their corresponding modules.

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

```res example
/* file React.res (implementation. Compiles to module React) */
type state = int
let render = (str) => str
```

```js
function render(str) {
  return str;
}
```

</CodeTab>

```res sig
/* file React.resi (interface. Compiles to the signature of React.res) */
type state = int
let render: string => string
```

## Module Functions (functors)

Modules can be passed to functions! It would be the equivalent of passing a file
as a first-class item. However, modules are at a different "layer" of the
language than other common concepts, so we can't pass them to _regular_
functions. Instead, we pass them to special functions called "functors".

The syntax for defining and using functors is very much like the syntax
for defining and using regular functions. The primary differences are:

- Functors use the `module` keyword instead of `let`.
- Functors take modules as arguments and return a module.
- Functors _require_ annotating arguments.
- Functors must start with a capital letter (just like modules/signatures).

Here's an example `MakeSet` functor, that takes in a module of the type
`Comparable` and returns a new set that can contain such comparable items.

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

```res prelude
module type Comparable = {
  type t
  let equal: (t, t) => bool
}

module MakeSet = (Item: Comparable) => {
  // let's use a list as our naive backing data structure
  type backingType = list<Item.t>
  let empty = list{}
  let add = (currentSet: backingType, newItem: Item.t): backingType =>
    // if item exists
    if currentSet->List.some(x => Item.equal(x, newItem)) {
      currentSet // return the same (immutable) set (a list really)
    } else {
      list{
        newItem,
        ...currentSet // prepend to the set and return it
      }
    }
}
```

```js
var List = require("./stdlib/list.js");

function MakeSet(Item) {
  var add = function (currentSet, newItem) {
    if (
      List.exists(function (x) {
        return Item.equal(x, newItem);
      }, currentSet)
    ) {
      return currentSet;
    } else {
      return {
        hd: newItem,
        tl: currentSet,
      };
    }
  };
  return {
    empty: /* [] */ 0,
    add: add,
  };
}
```

</CodeTab>

Functors can be applied using function application syntax. In this case, we're
creating a set, whose items are pairs of integers.

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

```res example
module IntPair = {
  type t = (int, int)
  let equal = ((x1: int, y1: int), (x2, y2)) => x1 == x2 && y1 == y2
  let create = (x, y) => (x, y)
}

/* IntPair abides by the Comparable signature required by MakeSet */
module SetOfIntPairs = MakeSet(IntPair)
```

```js
function equal(param, param$1) {
  if (param[0] === param$1[0]) {
    return param[1] === param$1[1];
  } else {
    return false;
  }
}

function create(x, y) {
  return [x, y];
}

var IntPair = {
  equal: equal,
  create: create,
};

var SetOfIntPairs = {
  empty: /* [] */ 0,
  add: add,
};
```

</CodeTab>

### Module functions types

Like with module types, functor types also act to constrain and hide what we may
assume about functors. The syntax for functor types are consistent with those
for function types, but with types capitalized to represent the signatures of
modules the functor accepts as arguments and return values. In the
previous example, we're exposing the backing type of a set; by giving `MakeSet`
a functor signature, we can hide the underlying data structure!

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

```res
module type Comparable = ...

module type MakeSetType = (Item: Comparable) => {
  type backingType
  let empty: backingType
  let add: (backingType, Item.t) => backingType
}

module MakeSet: MakeSetType = (Item: Comparable) => {
  ...
}
```

```js
// Empty output
```

</CodeTab>

## Exotic Module Filenames

**Since 8.3**

It is possible to use non-conventional characters in your filenames (which is sometimes needed for specific JS frameworks). Here are some examples:

- `src/Button.ios.res`
- `pages/[id].res`

Please note that modules with an exotic filename will not be accessible from other ReScript modules and will only produce JavaScript files.

## Tips & Tricks

Modules and functors are at a different "layer" of language than the rest (functions, let bindings, data structures, etc.). For example, you can't easily pass them into a tuple or record. Use them judiciously, if ever! Lots of times, just a record or a function is enough.

---
title: "Mutation"
description: "Imperative and mutative programming capabilities in ReScript"
canonical: "/docs/manual/mutation"
section: "Language Features"
order: 17
---

# Mutation

ReScript has great traditional imperative & mutative programming capabilities. You should use these features sparingly, but sometimes they allow your code to be more performant and written in a more familiar pattern.

## Mutate Let-binding

Let-bindings are immutable, but you can wrap it with a `ref`, exposed as a record with a single mutable field in the standard library:

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

```res prelude
let myValue = ref(5)
```

```js
var myValue = {
  contents: 5,
};
```

</CodeTab>

## Usage

You can get the actual value of a `ref` box through accessing its `contents` field:

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

```res example
let five = myValue.contents // 5
```

```js
var five = myValue.contents;
```

</CodeTab>

Assign a new value to `myValue` like so:

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

```res example
myValue.contents = 6
```

```js
myValue.contents = 6;
```

</CodeTab>

We provide a syntax sugar for this:

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

```res example
myValue := 6
```

```js
myValue.contents = 6;
```

</CodeTab>

Note that the previous binding `five` stays `5`, since it got the underlying item on the `ref` box, not the `ref` itself.

**Note**: you might see in the JS output tabs above that `ref` allocates an object. Worry not; local, non-exported `ref`s allocations are optimized away.

## Tip & Tricks

Before reaching for `ref`, know that you can achieve lightweight, local "mutations" through [overriding let bindings](./let-binding.mdx#binding-shadowing).

---
title: "Null, Undefined and Option"
description: "JS interop with nullable and optional values in ReScript"
canonical: "/docs/manual/null-undefined-option"
section: "Language Features"
order: 11
---

# 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"]}>

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

```js
// Empty output
```

</CodeTab>

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](./variant.mdx).

## Example

Here's a normal value:

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

```res example
let licenseNumber = 5
```

```js
var licenseNumber = 5;
```

</CodeTab>

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"]}>

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

```js
var licenseNumber = personHasACar ? 5 : undefined;
```

</CodeTab>

Later on, when another piece of code receives such value, it'd be forced to handle both cases through [pattern matching](./pattern-matching-destructuring.mdx):

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

```res
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))
}
```

```js
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");
}
```

</CodeTab>

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"]}>

```res example
let x = Some(5)
```

```js
var x = 5;
```

</CodeTab>

simply compiles down to `5`, and

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

```res example
let x = None
```

```js
var x;
```

</CodeTab>

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

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`](/docs/manual/api/stdlib/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"]}>

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

```js
// Empty output
```

</CodeTab>

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"]}>

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

let result = validate(personId)
```

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

</CodeTab>

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.

---
title: "Object"
description: "Interoping with JS objects in ReScript"
canonical: "/docs/manual/object"
section: "Language Features"
order: 7
---

# Object

ReScript objects are like [records](./record.mdx), but:

- No type declaration needed.
- Structural and more polymorphic, [unlike records](./record.mdx#record-types-are-found-by-field-name).
- Doesn't support updates unless the object comes from the JS side.
- Doesn't support [pattern matching](./pattern-matching-destructuring.mdx).

{/* TODO: support update man */}

Although ReScript records compile to clean JavaScript objects, ReScript objects are a better candidate for emulating/binding to JS objects, as you'll see.

## Type Declaration

**Optional**, unlike for records. The type of an object is inferred from the value, so you never really need to write down its type definition. Nevertheless, here's its type declaration syntax:

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

```res prelude
type person = {
  "age": int,
  "name": string
};
```

```js
// Empty output
```

</CodeTab>

Visually similar to record type's syntax, with the field names quoted.

{/* TODO: document {.} and {..} */}

## Creation

To create a new object:

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

```res example
let me = {
  "age": 5,
  "name": "Big ReScript"
}
```

```js
var me = {
  age: 5,
  name: "Big ReScript",
};
```

</CodeTab>

**Note**: as said above, unlike for record, this `me` value does **not** try to find a conforming type declaration with the field `"age"` and `"name"`; rather, the type of `me` is inferred as `{"age": int, "name": string}`. This is convenient, but also means this code passes type checking without errors:

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

```res
type person = {
  "age": int
};

let me = {
  "age": "hello!" // age is a string. No error.
}
```

```js
var me = {
  age: "hello!",
};
```

</CodeTab>

Since the type checker doesn't try to match `me` with the type `person`. If you ever want to force an object value to be of a predeclared object type, just annotate the value:

```res
let me: person = {
  "age": "hello!"
}
```

Now the type system will error properly.

## Access

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

```res
let age = me["age"]
```

```js
var age = me["age"];
```

</CodeTab>

## Update

Disallowed unless the object is a binding that comes from the JavaScript side. In that case, use `=`

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

```res example
type student = {
  @set "age": int,
  @set "name": string,
}
@module("MyJSFile") external student1: student = "student1"

student1["name"] = "Mary"
```

```js
var MyJSFile = require("MyJSFile");
MyJSFile.student1.name = "Mary";
```

</CodeTab>

## Combine Types

You can spread one object type definition into another using `...`:

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

```res example
type point2d = {
  "x": float,
  "y": float,
}
type point3d = {
  ...point2d,
  "z": float,
}

let myPoint: point3d = {
  "x": 1.0,
  "y": 2.0,
  "z": 3.0,
}
```

```js
var myPoint = {
  x: 1.0,
  y: 2.0,
  z: 3.0,
};
```

</CodeTab>

This only works with object types, not object values!

## Tips & Tricks

Since objects don't require type declarations, and since ReScript infers all the types for you, you get to very quickly and easily (and dangerously) bind to any JavaScript API. Check the JS output tab:

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

```res example
// The type of document is just some random type 'a
// that we won't bother to specify
@val external document: 'a = "document"

// call a method
document["addEventListener"]("mouseup", _event => {
  Console.log("clicked!")
})

// get a property
let loc = document["location"]

// set a property
document["location"]["href"] = "rescript-lang.org"
```

```js
document.addEventListener("mouseup", function (_event) {
  console.log("clicked!");
});
var loc = document.location;
document.location.href = "rescript-lang.org";
```

</CodeTab>

The `external` feature and the usage of this trick are also documented in the [external](./external.mdx#tips--tricks) section later. It's an excellent way to start writing some ReScript code without worrying about whether bindings to a particular library exists.

---
title: "Overview"
metaTitle: "Language Features Overview"
description: "A quick overview of ReScript's syntax and language features"
canonical: "/docs/manual/overview"
section: "Language Features"
order: 1
---

# Language Overview

A concise reference of ReScript's syntax and core language features.

## Semicolons

ReScript does not require semicolons. Line breaks are sufficient to separate statements.

## Comments

| Syntax                           | Purpose                |
| -------------------------------- | ---------------------- |
| `// Line comment`                | Single-line comment    |
| `/* Block comment */`            | Multi-line comment     |
| `/** Doc comment */`             | Documentation comment  |
| `/*** Standalone doc comment */` | Standalone doc comment |

## Variables

| Syntax                                | Description             |
| ------------------------------------- | ----------------------- |
| `let x = 5`                           | Immutable binding       |
| `let x = ref(5); x := x.contents + 1` | Mutable value via `ref` |

## Strings

| Syntax                    | Description          |
| ------------------------- | -------------------- |
| `"Hello world!"`          | String literal       |
| `"hello " ++ "world"`     | String concatenation |
| `` `hello ${message}` ``  | String interpolation |
| `` sql`select ${col};` `` | Tagged template      |

Strings must use double quotes (`"`).

## Booleans

| Syntax               | Description                    |
| -------------------- | ------------------------------ |
| `true`, `false`      | Boolean literals               |
| `!`                  | Logical NOT                    |
| `\|\|`, `&&`         | Logical OR, AND                |
| `<=`, `>=`, `<`, `>` | Comparison operators           |
| `===`, `!==`         | Referential (shallow) equality |
| `==`, `!=`           | Structural (deep) equality     |

There is no equality with implicit type casting.

## Numbers

| Syntax       | Description                        |
| ------------ | ---------------------------------- |
| `3`          | Integer literal                    |
| `3.1415`     | Float literal                      |
| `3 + 4`      | Addition (works for int and float) |
| `2 / 3 * 4`  | Division and multiplication        |
| `2.0 ** 3.0` | Exponentiation                     |
| `5 % 3`      | Modulo                             |

Arithmetic operators (`+`, `-`, `*`, `/`, `%`, `**`) work for both `int` and `float`.

## Records

Records are typed, immutable-by-default data structures with named fields.

| Syntax                                  | Description          |
| --------------------------------------- | -------------------- |
| `type point = {x: int, mutable y: int}` | Type declaration     |
| `{x: 30, y: 20}`                        | Record creation      |
| `point.x`                               | Field access         |
| `point.y = 30`                          | Mutable field update |
| `{...point, x: 30}`                     | Immutable update     |

## Arrays

| Syntax            | Description            |
| ----------------- | ---------------------- |
| `[1, 2, 3]`       | Array literal          |
| `myArray[1] = 10` | Mutable element update |

Arrays are homogeneous. For mixed types, use tuples or [Untagged Variants](./variant.mdx#untagged-variants).

## Tuples

| Syntax              | Description         |
| ------------------- | ------------------- |
| `(1, "Bob", true)`  | Tuple literal       |
| `let (a, b, c) = t` | Tuple destructuring |

Tuples are fixed-length, heterogeneous, and immutable.

## Null & Option

ReScript has no `null` or `undefined`. The `option` type represents the possible absence of a value:

| Syntax       | Description     |
| ------------ | --------------- |
| `None`       | No value        |
| `Some("hi")` | A present value |

## Functions

| Syntax                        | Description          |
| ----------------------------- | -------------------- |
| `arg => retVal`               | Anonymous function   |
| `let named = (arg) => retVal` | Named function       |
| `add(4, add(5, 6))`           | Function application |

## Async / Await

| Syntax                             | Description                    |
| ---------------------------------- | ------------------------------ |
| `async (arg) => {...}`             | Async anonymous function       |
| `let named = async (arg) => {...}` | Async named function           |
| `await somePromise`                | Await a promise                |
| `async (arg): string => {...}`     | Typed async (return type only) |

## Blocks

The last expression in a `{}` block is implicitly returned, including in function bodies.

<table>
  <thead>
    <tr>
      <th>Example</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>
      ```
      let myFun = (x, y) => {
        let doubleX = x + x
        let doubleY = y + y
        doubleX + doubleY
      }
      ```
      </td>
      <td>Function body with implicit return</td>
    </tr>
    <tr>
      <td>
      ```
      let result = {
        let x = 23
        let y = 34
        x + y
      }
      ```
      </td>
      <td>Block expression bound to a variable</td>
    </tr>
  </tbody>
</table>

## If-Else

| Syntax              | Description                                                              |
| ------------------- | ------------------------------------------------------------------------ |
| `if a {b} else {c}` | Conditional expression                                                   |
| `a ? b : c`         | Ternary expression                                                       |
| `switch`            | Pattern matching — [see full docs](./pattern-matching-destructuring.mdx) |

Conditionals are expressions: `let result = if a {"hello"} else {"bye"}`

## Destructuring

| Syntax                      | Description               |
| --------------------------- | ------------------------- |
| `let {a, b} = data`         | Record destructuring      |
| `let [a, b] = data`         | Array destructuring \*    |
| `let {a: aa, b: bb} = data` | Destructuring with rename |

\* The compiler warns if `data` might not be of length 2.

## Loops

| Syntax                       | Description     |
| ---------------------------- | --------------- |
| `for i in 0 to 10 {...}`     | Ascending loop  |
| `for i in 10 downto 0 {...}` | Descending loop |
| `while true {...}`           | While loop      |

## JSX

| Syntax                                    | Description            |
| ----------------------------------------- | ---------------------- |
| `<Comp message="hi" onClick={handler} />` | Props                  |
| `<Comp message />`                        | Argument punning       |
| `<input checked=true />`                  | Explicit boolean props |
| `<Comp>...children</Comp>`                | Children spread        |

## Exceptions

| Syntax                                        | Description           |
| --------------------------------------------- | --------------------- |
| `throw(SomeException(...))`                   | Raise an exception    |
| `try a catch { \| SomeException(err) => ...}` | Catch an exception \* |

\* There is no `finally` clause.

## Compilation Output Reference

A reference showing how common ReScript features compile to JavaScript.

| Feature                   | ReScript                             | JavaScript Output                          |
| ------------------------- | ------------------------------------ | ------------------------------------------ |
| String                    | `"Hello"`                            | `"Hello"`                                  |
| String Interpolation      | `` `Hello ${message}` ``             | `"Hello " + message`                       |
| Character (discouraged)   | `'x'`                                | `120` (char code)                          |
| Integer                   | `23`, `-23`                          | `23`, `-23`                                |
| Float                     | `23.0`, `-23.0`                      | `23.0`, `-23.0`                            |
| Addition                  | `23 + 1`                             | `23 + 1`                                   |
| Float Addition            | `23.0 + 1.0`                         | `23.0 + 1.0`                               |
| Division/Multiply         | `2 / 23 * 1`                         | `2 / 23 * 1`                               |
| Float Division/Multiply   | `2.0 / 23.0 * 1.0`                   | `2.0 / 23.0 * 1.0`                         |
| Float Exponentiation      | `2.0 ** 3.0`                         | `2.0 ** 3.0`                               |
| String Concatenation      | `"Hello " ++ "World"`                | `"Hello " + "World"`                       |
| Comparison                | `>`, `<`, `>=`, `<=`                 | `>`, `<`, `>=`, `<=`                       |
| Boolean operation         | `!`, `&&`, `\|\|`                    | `!`, `&&`, `\|\|`                          |
| Shallow and deep Equality | `===`, `==`                          | `===`, `==`                                |
| List (discouraged)        | `list{1, 2, 3}`                      | `{hd: 1, tl: {hd: 2, tl: {hd: 3, tl: 0}}}` |
| List Prepend              | `list{a1, a2, ...oldList}`           | `{hd: a1, tl: {hd: a2, tl: theRest}}`      |
| Array                     | `[1, 2, 3]`                          | `[1, 2, 3]`                                |
| Record                    | `type t = {b: int}; let a = {b: 10}` | `var a = {b: 10}`                          |
| Multiline Comment         | `/* Comment here */`                 | Not in output                              |
| Single line Comment       | `// Comment here`                    | Not in output                              |

_Note that this is a cleaned-up reference table; some examples' JavaScript output may differ slightly in practice._

---
title: "Pattern Matching / Destructuring"
description: "Pattern matching and destructuring complex data structures in ReScript"
canonical: "/docs/manual/pattern-matching-destructuring"
section: "Language Features"
order: 16
---

# Pattern Matching / Destructuring

One of ReScript's **best** feature is our pattern matching. Pattern matching combines 3 brilliant features into one:

- Destructuring.
- `switch` based on shape of data.
- Exhaustiveness check.

We'll dive into each aspect below.

## Destructuring

Even JavaScript has destructuring, which is "opening up" a data structure to extract the parts we want and assign variable names to them:

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

```res example
let coordinates = (10, 20, 30)
let (x, _, _) = coordinates
Console.log(x) // 10
```

```js
var coordinates = [10, 20, 30];
var x = 10;
console.log(10);
```

</CodeTab>

Destructuring works with most built-in data structures:

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

```res
// Record
type student = {name: string, age: int}
let student1 = {name: "John", age: 10}
let {name} = student1 // "John" assigned to `name`

// Variant
type result =
  | Success(string)
let myResult = Success("You did it!")
let Success(message) = myResult // "You did it!" assigned to `message`
```

```js
var student1 = {
  name: "John",
  age: 10,
};
var name = "John";

var myResult = /* Success */ {
  _0: "You did it!",
};
var message = "You did it!";

var myArray = [1, 2, 3];
if (myArray.length !== 2) {
  throw {
    RE_EXN_ID: "Match_failure",
    _1: ["playground.res", 14, 4],
    Error: new Error(),
  };
}
var item1 = myArray[0];
var item2 = myArray[1];

var myList = {
  hd: 1,
  tl: {
    hd: 2,
    tl: {
      hd: 3,
      tl: /* [] */ 0,
    },
  },
};
// ...
```

</CodeTab>

You can also use destructuring anywhere you'd usually put a binding:

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

```res example
type result =
  | Success(string)
let displayMessage = (Success(m)) => {
  // we've directly extracted the success message
  // string by destructuring the parameter
  Console.log(m)
}
displayMessage(Success("You did it!"))
```

```js
function displayMessage(m) {
  console.log(m._0);
}

displayMessage(
  /* Success */ {
    _0: "You did it!",
  },
);
```

</CodeTab>

For a record, you can rename the field while destructuring:

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

```res
let {name: n} = student1 // "John" assigned to `n`
```

```js
var n = "John";
```

</CodeTab>

You _can_ in theory destructure array and list at the top level too:

```res
let myArray = [1, 2, 3]
let [item1, item2, _] = myArray
// 1 assigned to `item1`, 2 assigned to `item2`, 3rd item ignored

let myList = list{1, 2, 3}
let list{head, ...tail} = myList
// 1 assigned to `head`, `list{2, 3}` assigned to tail
```

But the array example is **highly disrecommended** (use tuple instead) and the list example will error on you. They're only there for completeness' sake. As you'll see below, the proper way of using destructuring array and list is using `switch`.

## `switch` Based on Shape of Data

While the destructuring aspect of pattern matching is nice, it doesn't really change the way you think about structuring your code. One paradigm-changing way of thinking about your code is to execute some code based on the shape of the data.

Consider a variant:

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

```res prelude
type payload =
  | BadResult(int)
  | GoodResult(string)
  | NoResult
```

```js
// Empty output
```

</CodeTab>

We'd like to handle each of the 3 cases differently. For example, print a success message if the value is `GoodResult(...)`, do something else when the value is `NoResult`, etc.

In other languages, you'd end up with a series of if-elses that are hard to read and error-prone. In ReScript, you can instead use the supercharged `switch` pattern matching facility to destructure the value while calling the right code based on what you destructured:

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

```res example
let data = GoodResult("Product shipped!")
switch data {
| GoodResult(theMessage) =>
  Console.log("Success! " ++ theMessage)
| BadResult(errorCode) =>
  Console.log("Something's wrong. The error code is: " ++ Int.toString(errorCode))
| NoResult =>
  Console.log("Bah.")
}
```

```js
var data = {
  TAG: "GoodResult",
  _0: "Product shipped!",
};

if (typeof data !== "object") {
  console.log("Bah.");
} else if (data.TAG === "BadResult") {
  console.log(
    "Something's wrong. The error code is: " + "Product shipped!".toString(),
  );
} else {
  console.log("Success! Product shipped!");
}
```

</CodeTab>

In this case, `message` will have the value `"Success! Product shipped!"`.

Suddenly, your if-elses that messily checks some structure of the value got turned into a clean, compiler-verified, linear list of code to execute based on exactly the shape of the value.

### Complex Examples

Here's a real-world scenario that'd be a headache to code in other languages. Given this data structure:

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

```res prelude
type status = Vacations(int) | Sabbatical(int) | Sick | Present
type reportCard = {passing: bool, gpa: float}
type student = {name: string, status: status, reportCard: reportCard}
type person =
  | Teacher({name: string, age: int})
  | Student(student)
```

```js
// Empty output
```

</CodeTab>

Imagine this requirement:

- Informally greet a person who's a teacher and if his name is Mary or Joe.
- Greet other teachers formally.
- If the person's a student, congratulate him/her score if they passed the semester.
- If the student has a gpa of 0 and is on vacations or sabbatical, display a different message.
- A catch-all message for a student.

ReScript can do this easily!

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

```res prelude
let person1 = Teacher({name: "Jane", age: 35})

let message = switch person1 {
| Teacher({name: "Mary" | "Joe"}) =>
  `Hey, still going to the party on Saturday?`
| Teacher({name}) =>
  // this is matched only if `name` isn't "Mary" or "Joe"
  `Hello ${name}.`
| Student({name, reportCard: {passing: true, gpa}}) =>
  `Congrats ${name}, nice GPA of ${Float.toString(gpa)} you got there!`
| Student({
    reportCard: {gpa: 0.0},
    status: Vacations(daysLeft) | Sabbatical(daysLeft)
  }) =>
  `Come back in ${Int.toString(daysLeft)} days!`
| Student({status: Sick}) =>
  `How are you feeling?`
| Student({name}) =>
  `Good luck next semester ${name}!`
}
```

```js
var person1 = {
  TAG: "Teacher",
  name: "Jane",
  age: 35,
};

var message;

if (person1.TAG === "Teacher") {
  message = "Hello Jane.";
} else {
  var match = "Jane";
  var match$1 = match.status;
  var name = match.name;
  var match$2 = match.reportCard;
  if (match$2.passing) {
    message =
      "Congrats " +
      name +
      ", nice GPA of " +
      match$2.gpa.toString() +
      " you got there!";
  } else {
    var exit = 0;
    if (typeof match$1 !== "object") {
      message =
        match$1 === "Sick"
          ? "How are you feeling?"
          : "Good luck next semester " + name + "!";
    } else {
      exit = 1;
    }
    if (exit === 1) {
      message =
        match.reportCard.gpa !== 0.0
          ? "Good luck next semester " + name + "!"
          : "Come back in " + match$1._0.toString() + " days!";
    }
  }
}
```

</CodeTab>

**Note** how we've:

- drilled deep down into the value concisely
- using a **nested pattern check** `"Mary" | "Joe"` and `Vacations | Sabbatical`
- while extracting the `daysLeft` number from the latter case
- and assigned the greeting to the binding `message`.

Here's another example of pattern matching, this time on an inline tuple.

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

```res
type animal = Dog | Cat | Bird
let categoryId = switch (isBig, myAnimal) {
| (true, Dog) => 1
| (true, Cat) => 2
| (true, Bird) => 3
| (false, Dog | Cat) => 4
| (false, Bird) => 5
}
```

```js
var categoryId = isBig ? (myAnimal + 1) | 0 : myAnimal >= 2 ? 5 : 4;
```

</CodeTab>

**Note** how pattern matching on a tuple is equivalent to a 2D table:

| isBig \ myAnimal | Dog | Cat | Bird |
| ---------------- | --- | --- | ---- |
| true             | 1   | 2   | 3    |
| false            | 4   | 4   | 5    |

### Fall-Through Patterns

The nested pattern check, demonstrated in the earlier `person` example, also works at the top level of a `switch`:

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

```res prelude
let myStatus = Vacations(10)

switch myStatus {
| Vacations(days)
| Sabbatical(days) => Console.log(`Come back in ${Int.toString(days)} days!`)
| Sick
| Present => Console.log("Hey! How are you?")
}
```

```js
var myStatus = {
  TAG: /* Vacations */ 0,
  _0: 10,
};

if (typeof myStatus === "number") {
  console.log("Hey! How are you?");
} else {
  console.log("Come back in " + (10).toString() + " days!");
}
```

</CodeTab>

Having multiple cases fall into the same handling can clean up certain types of logic.

### Ignore Part of a Value

If you have a value like `Teacher(payload)` where you just want to pattern match on the `Teacher` part and ignore the `payload` completely, you can use the `_` wildcard like this:

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

```res example
switch person1 {
| Teacher(_) => Console.log("Hi teacher")
| Student(_) => Console.log("Hey student")
}
```

```js
if (person1.TAG === "Teacher") {
  console.log("Hi teacher");
} else {
  console.log("Hey student");
}
```

</CodeTab>

`_` also works at the top level of the `switch`, serving as a catch-all condition:

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

```res example
switch myStatus {
| Vacations(_) => Console.log("Have fun!")
| _ => Console.log("Ok.")
}
```

```js
if (typeof myStatus !== "object" || myStatus.TAG !== "Vacations") {
  console.log("Ok.");
} else {
  console.log("Have fun!");
}
```

</CodeTab>

**Do not** abuse a top-level catch-all condition. Instead, prefer writing out all the cases:

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

```res example
switch myStatus {
| Vacations(_) => Console.log("Have fun!")
| Sabbatical(_) | Sick | Present => Console.log("Ok.")
}
```

```js
if (typeof myStatus !== "object" || myStatus.TAG !== "Vacations") {
  console.log("Ok.");
} else {
  console.log("Have fun!");
}
```

</CodeTab>

Slightly more verbose, but a one-time writing effort. This helps when you add a new variant case e.g. `Quarantined` to the `status` type and need to update the places that pattern match on it. A top-level wildcard here would have accidentally and silently continued working, potentially causing bugs.

### If Clause

Sometime, you want to check more than the shape of a value. You want to also run some arbitrary check on it. You might be tempted to write this:

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

```res example
switch person1 {
| Teacher(_) => () // do nothing
| Student({reportCard: {gpa}}) =>
  if gpa < 0.5 {
    Console.log("What's happening")
  } else {
    Console.log("Heyo")
  }
}
```

```js
if (person1.TAG !== "Teacher") {
  if ("Jane".reportCard.gpa < 0.5) {
    console.log("What's happening");
  } else {
    console.log("Heyo");
  }
}
```

</CodeTab>

`switch` patterns support a shortcut for the arbitrary `if` check, to keep your pattern linear-looking:

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

```res example
switch person1 {
| Teacher(_) => () // do nothing
| Student({reportCard: {gpa}}) if gpa < 0.5 =>
  Console.log("What's happening")
| Student(_) =>
  // fall-through, catch-all case
  Console.log("Heyo")
}
```

```js
if (person1.TAG) {
  if (person1.reportCard.gpa < 0.5) {
    console.log("What's happening");
  } else {
    console.log("Heyo");
  }
}
```

</CodeTab>

### Match on subtype variants

You can refine a variant A to variant B using the [variant type spread syntax](./variant.mdx#variant-type-spreads) in pattern matching. This is possible if variant B [is a subtype of](./variant.mdx#coercion) variant A.

Let's look at an example:

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

```res
type pets = Cat | Dog
type fish = Cod | Salmon
type animals = | ...pets | ...fish

let greetPet = (pet: pets) => {
  switch pet {
  | Cat => Console.log("Hello kitty!")
  | Dog => Console.log("Woof woof doggie!")
  }
}

let greetFish = (fish: fish) => {
  switch fish {
  | Cod => Console.log("Blub blub..")
  | Salmon => Console.log("Blub blub blub blub..")
  }
}

let greetAnimal = (animal: animals) => {
  switch animal {
  | ...pets as pet => greetPet(pet)
  | ...fish as fish => greetFish(fish)
  }
}
```

```js
function greetPet(pet) {
  if (pet === "Cat") {
    console.log("Hello kitty!");
    return;
  }
  console.log("Woof woof doggie!");
}

function greetFish(fish) {
  if (fish === "Cod") {
    console.log("Blub blub..");
    return;
  }
  console.log("Blub blub blub blub..");
}

function greetAnimal(animal) {
  switch (animal) {
    case "Cat":
    case "Dog":
      return greetPet(animal);
    case "Cod":
    case "Salmon":
      return greetFish(animal);
  }
}
```

</CodeTab>

Let's break down what we did:

- Defined two different variants for pets and for fish
- Wrote a dedicated function per animal type to greet that particular type of animal
- Combined `pets` and `fish` into a main variant for `animals`
- Wrote a function that can greet any animal by _spreading_ each sub variant on its own branch, aliasing that spread to a variable, and passing that variable to the dedicated greet function for that specific type

Notice how we're able to match on parts of the main variant, as long as the variants are compatible.

The example above aliases the variant type spread to a variable so we can use it in our branch. But, you can just as easily match without aliasing if you don't care about the value:

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

```res
let isPet = (animal: animals) => {
  switch animal {
  | ...pets => Console.log("A pet!")
  | _ => Console.log("Not a pet...")
  }
}

```

```js
function isPet(animal) {
  switch (animal) {
    case "Cat":
    case "Dog":
      console.log("A pet!");
      return;
    case "Cod":
    case "Salmon":
      console.log("Not a pet...");
      return;
  }
}
```

</CodeTab>

Similarily, if you want to get advanced, you can even pull out a single variant constructor. This works with and without aliases. Example:

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

```res
type dog = Dog
type pets = Cat | ...dog
type fish = Cod | Salmon
type animals = | ...pets | ...fish

let isPet = (animal: animals) => {
  switch animal {
  | ...dog => Console.log("A dog!")
  | _ => Console.log("Not a dog...")
  }
}

```

```js
function isPet(animal) {
  if (animal === "Dog") {
    console.log("A dog!");
    return;
  }
  console.log("Not a dog...");
}
```

</CodeTab>

And, thanks to the rules of subtyping, the `Dog` constructor wouldn't _really_ need to be spread inside of the `pets` variant for this to work:

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

```res
type pets = Cat | Dog
type fish = Cod | Salmon
type animals = | ...pets | ...fish

// Notice `dog` isn't spread into the `pets` variant,
// but this still work due to subtyping.
type dog = Dog

let isPet = (animal: animals) => {
  switch animal {
  | ...dog => Console.log("A dog!")
  | _ => Console.log("Not a dog...")
  }
}

```

```js
function isPet(animal) {
  if (animal === "Dog") {
    console.log("A dog!");
    return;
  }
  console.log("Not a dog...");
}
```

</CodeTab>

### Match on Exceptions

If the function throws an exception (covered later), you can also match on _that_, in addition to the function's normally returned values.

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

```res
switch List.find(i => i === theItem, myItems) {
| item => Console.log(item)
| exception Not_found => Console.log("No such item found!")
}
```

```js
var exit = 0;

var item;

try {
  item = List.find(function (i) {
    return i === theItem;
  }, myItems);
  exit = 1;
} catch (raw_exn) {
  var exn = Caml_js_exceptions.internalToOCamlException(raw_exn);
  if (exn.RE_EXN_ID === "Not_found") {
    console.log("No such item found!");
  } else {
    throw exn;
  }
}

if (exit === 1) {
  console.log(item);
}
```

</CodeTab>

### Match on Array

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

```res example
let students = ["Jane", "Harvey", "Patrick"]
switch students {
| [] => Console.log("There are no students")
| [student1] =>
  Console.log("There's a single student here: " ++ student1)
| manyStudents =>
  // display the array of names
  Console.log2("The students are: ", manyStudents)
}
```

```js
var students = ["Jane", "Harvey", "Patrick"];

var len = students.length;

if (len !== 1) {
  if (len !== 0) {
    console.log("The students are: ", students);
  } else {
    console.log("There are no students");
  }
} else {
  var student1 = students[0];
  console.log("There's a single student here: " + student1);
}
```

</CodeTab>

### Match on List

Pattern matching on list is similar to array, but with the extra feature of extracting the tail of a list (all elements except the first one):

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

```res example
let rec printStudents = (students) => {
  switch students {
  | list{} => () // done
  | list{student} => Console.log("Last student: " ++ student)
  | list{student1, ...otherStudents} =>
    Console.log(student1)
    printStudents(otherStudents)
  }
}
printStudents(list{"Jane", "Harvey", "Patrick"})
```

```js
function printStudents(_students) {
  while (true) {
    var students = _students;
    if (!students) {
      return;
    }
    var otherStudents = students.tl;
    var student = students.hd;
    if (otherStudents) {
      console.log(student);
      _students = otherStudents;
      continue;
    }
    console.log("Last student: " + student);
    return;
  }
}

printStudents({
  hd: "Jane",
  tl: {
    hd: "Harvey",
    tl: {
      hd: "Patrick",
      tl: /* [] */ 0,
    },
  },
});
```

</CodeTab>

### Match on Dictionaries

You can pattern match on dictionaries just like you can on other ReScript data structures.

When pattern matching on a dictionary it's assumed by default that you're expecting the keys you match on to exist in the dictionary. Example:

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

```res prelude
let d = dict{"A": 5, "B": 6}

// We're expecting the `B` key to exist below, and `b` will be `int` in the match branch
let b = switch d {
| dict{"B": b} => Some(b)
| _ => None
}
```

```js
let d = {
  A: 5,
  B: 6,
};

let b = d.B;

let b$1 = b !== undefined ? b : undefined;
```

</CodeTab>

However, there are situations where you want to pull out the value of a key as an option. You can do that using the `?` optional syntax in the pattern match:

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

```res prelude
let d = dict{"A": 5, "B": 6}

// We're pulling out `B` regardless of if it has a value or not, and therefore get `b` as `option<int>`
let b = switch d {
| dict{"B": ?b} => b
}
```

```js
let d = {
  A: 5,
  B: 6,
};

let b = d.B;
```

</CodeTab>

Notice how in the first case, when not using `?`, we had to supply a catch-all case `_`. That's because the pattern match _expects_ `B` to exist in the first case, for the pattern to match. If `B` doesn't exist, the match falls through to the next branch, and therefore we need to catch it to be exhaustive in our matching.

However, in the second case, we don't need a catch-all case. That's because the first branch will _always_ match the dictionary - either `B` exists or it doesn't, but it doesn't matter because we're pulling it out as an optional value.

### Small Pitfall

**Note**: you can only pass literals (i.e. concrete values) as a pattern, not let-binding names or other things. The following doesn't work as expected:

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

```res example
let coordinates = (10, 20, 30)
let centerY = 20
switch coordinates {
| (x, _centerY, _) => Console.log(x)
}
```

```js
var coordinates = [10, 20, 30];
var centerY = 20;

console.log(10);
```

</CodeTab>

A first time ReScript user might accidentally write that code, assuming that it's matching on `coordinates` when the second value is of the same value as `centerY`. In reality, this is interpreted as matching on coordinates and assigning the second value of the tuple to the name `centerY`, which isn't what's intended.

## Exhaustiveness Check

As if the above features aren't enough, ReScript also provides arguably the most important pattern matching feature: **compile-time check of missing patterns**.

Let's revisit one of the above examples:

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

```res
let message = switch person1 {
| Teacher({name: "Mary" | "Joe"}) =>
  `Hey, still going to the party on Saturday?`
| Student({name, reportCard: {passing: true, gpa}}) =>
  `Congrats ${name}, nice GPA of ${Float.toString(gpa)} you got there!`
| Student({
    reportCard: {gpa: 0.0},
    status: Vacations(daysLeft) | Sabbatical(daysLeft)
  }) =>
  `Come back in ${Int.toString(daysLeft)} days!`
| Student({status: Sick}) =>
  `How are you feeling?`
| Student({name}) =>
  `Good luck next semester ${name}!`
}
```

```js
if (person1.TAG) {
  var match$1 = person1.status;
  var name = person1.name;
  var match$2 = person1.reportCard;
  if (match$2.passing) {
    "Congrats " +
      name +
      ", nice GPA of " +
      match$2.gpa.toString() +
      " you got there!";
  } else if (typeof match$1 === "number") {
    if (match$1 !== 0) {
      "Good luck next semester " + name + "!";
    } else {
      ("How are you feeling?");
    }
  } else if (person1.reportCard.gpa !== 0.0) {
    "Good luck next semester " + name + "!";
  } else {
    "Come back in " + match$1._0.toString() + " days!";
  }
} else {
  switch (person1.name) {
    case "Joe":
    case "Mary":
      break;
    default:
      throw {
        RE_EXN_ID: "Match_failure",
        _1: ["playground.res", 13, 0],
        Error: new Error(),
      };
  }
}
```

</CodeTab>

Did you see what we removed? This time, we've omitted the handling of the case where `person1` is `Teacher({name})` when `name` isn't Mary or Joe.

Failing to handle every scenario of a value likely constitutes the majority of program bugs out there. This happens very often when you refactor a piece of code someone else wrote. Fortunately for ReScript, the compiler will tell you so:

```
Warning 8: this pattern-matching is not exhaustive.
Here is an example of a value that is not matched:
Some({name: ""})
```

**BAM**! You've just erased an entire category of important bugs before you even ran the code. In fact, this is how most of nullable values is handled:

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

```res example
let myNullableValue = Some(5)

switch myNullableValue {
| Some(_v) => Console.log("value is present")
| None => Console.log("value is absent")
}
```

```js
var myNullableValue = 5;

if (myNullableValue !== undefined) {
  console.log("value is present");
} else {
  console.log("value is absent");
}
```

</CodeTab>

If you don't handle the `None` case, the compiler warns. No more `undefined` bugs in your code!

## Conclusion & Tips & Tricks

Hopefully you can see how pattern matching is a game changer for writing correct code, through the concise destructuring syntax, the proper conditions handling of `switch`, and the static exhaustiveness check.

Below is some advice:

Avoid using the wildcard `_` unnecessarily. Using the wildcard `_` will bypass the compiler's exhaustiveness check. Consequently, the compiler will not be able to notify you of probable errors when you add a new case to a variant. Try only using `_` against infinite possibilities, e.g. string, int, etc.

Use the `if` clause sparingly.

**Flatten your pattern-match whenever you can**. This is a real bug remover. Here's a series of examples, from worst to best:

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

```res example
let optionBoolToBool = opt => {
  if opt == None {
    false
  } else if opt === Some(true) {
    true
  } else {
    false
  }
}
```

```js
function optionBoolToBool(opt) {
  if (opt === undefined) {
    return false;
  } else {
    return opt === true;
  }
}
```

</CodeTab>

Now that's just silly =). Let's turn it into pattern-matching:

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

```res example
let optionBoolToBool = opt => {
  switch opt {
  | None => false
  | Some(a) => a ? true : false
  }
}
```

```js
function optionBoolToBool(opt) {
  if (opt !== undefined && opt) {
    return true;
  } else {
    return false;
  }
}
```

</CodeTab>

Slightly better, but still nested. Pattern-matching allows you to do this:

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

```res example
let optionBoolToBool = opt => {
  switch opt {
  | None => false
  | Some(true) => true
  | Some(false) => false
  }
}
```

```js
function optionBoolToBool(opt) {
  if (opt !== undefined && opt) {
    return true;
  } else {
    return false;
  }
}
```

</CodeTab>

Much more linear-looking! Now, you might be tempted to do this:

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

```res example
let optionBoolToBool = opt => {
  switch opt {
  | Some(true) => true
  | _ => false
  }
}
```

```js
function optionBoolToBool(opt) {
  if (opt !== undefined && opt) {
    return true;
  } else {
    return false;
  }
}
```

</CodeTab>

Which is much more concise, but kills the exhaustiveness check mentioned above; refrain from using that. This is the best:

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

```res example
let optionBoolToBool = opt => {
  switch opt {
  | Some(trueOrFalse) => trueOrFalse
  | None => false
  }
}
```

```js
function optionBoolToBool(opt) {
  if (opt !== undefined) {
    return opt;
  } else {
    return false;
  }
}
```

</CodeTab>

Pretty darn hard to make a mistake in this code at this point! Whenever you'd like to use an if-else with many branches, prefer pattern matching instead. It's more concise and [performant](./variant.mdx#design-decisions) too.

---
title: "Pipe"
description: "The Pipe operator (->)"
canonical: "/docs/manual/pipe"
section: "Language Features"
order: 15
---

# Pipe

ReScript provides a tiny but surprisingly useful operator `->`, called the "pipe", that allows you to "flip" your code inside-out. `a(b)` becomes `b->a`. It's a simple piece of syntax that doesn't have any runtime cost.

Why would you use it? Imagine you have the following:

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

```res
validateAge(getAge(parseData(person)))
```

```js
validateAge(getAge(parseData(person)));
```

</CodeTab>

This is slightly hard to read, since you need to read the code from the innermost part, to the outer parts. Use pipe to streamline it:

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

```res
person
  ->parseData
  ->getAge
  ->validateAge
```

```js
validateAge(getAge(parseData(person)));
```

</CodeTab>

Basically, `parseData(person)` is transformed into `person->parseData`, and `getAge(person->parseData)` is transformed into `person->parseData->getAge`, etc.

**This works when the function takes more than one argument too**.

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

```res
a(one, two, three)
```

```js
a(one, two, three);
```

</CodeTab>

is the same as

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

```res
one->a(two, three)
```

```js
a(one, two, three);
```

</CodeTab>

This also works with labeled arguments.

Pipes are used to emulate object-oriented programming. For example, `myStudent.getName` in other languages like Java would be `myStudent->getName` in ReScript (equivalent to `getName(myStudent)`). This allows us to have the readability of OOP without the downside of dragging in a huge class system just to call a function on a piece of data.

## Tips & Tricks

Do **not** abuse pipes; they're a means to an end. Inexperienced engineers sometimes shape a library's API to take advantage of the pipe. This is backwards.

## JS Method Chaining

[bind to JS function](./bind-to-js-function.mdx) docs

JavaScript's APIs are often attached to objects, and are often chainable, like so:

```js
const result = [1, 2, 3].map((a) => a + 1).filter((a) => a % 2 === 0);

asyncRequest().setWaitDuration(4000).send();
```

Assuming we don't need the chaining behavior above, we'd bind to each case of this using [`@send`](../../syntax-lookup/decorator_send.mdx) from the aforementioned binding API page:

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

```res prelude
type request
@val external asyncRequest: unit => request = "asyncRequest"
@send external setWaitDuration: (request, int) => request = "setWaitDuration"
@send external send: request => unit = "send"
```

```js
// Empty output
```

</CodeTab>

You'd use them like this:

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

```res example
let result = Array.filter(
  Array.map([1, 2, 3], a => a + 1),
  a => mod(a, 2) == 0
)

send(setWaitDuration(asyncRequest(), 4000))
```

```js
var result = [1, 2, 3]
  .map(function (a) {
    return (a + 1) | 0;
  })
  .filter(function (a) {
    return a % 2 === 0;
  });

asyncRequest().setWaitDuration(4000).send();
```

</CodeTab>

This looks much worse than the JS counterpart! Clean it up visually with pipe:

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

```res example
let result = [1, 2, 3]
  ->Array.map(a => a + 1)
  ->Array.filter(a => mod(a, 2) == 0)

asyncRequest()->setWaitDuration(4000)->send
```

```js
var result = [1, 2, 3]
  .map(function (a) {
    return (a + 1) | 0;
  })
  .filter(function (a) {
    return a % 2 === 0;
  });

asyncRequest().setWaitDuration(4000).send();
```

</CodeTab>

## Pipe Into Variants

You can pipe into a variant's constructor as if it was a function:

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

```res
let result = name->preprocess->Some
```

```js
var result = preprocess(name);
```

</CodeTab>

We turn this into:

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

```res
let result = Some(preprocess(name))
```

```js
var result = preprocess(name);
```

</CodeTab>

**Note** that using a variant constructor as a function wouldn't work anywhere else beside here.

## Pipe Placeholders

A placeholder is written as an underscore and it tells ReScript that you want to fill in an argument of a function later. These two have equivalent meaning:

```res
let addTo7 = (x) => add3(3, x, 4)
let addTo7 = add3(3, _, 4)
```

Sometimes you don't want to pipe the value you have into the first position. In these cases you can mark a placeholder value to show which argument you would like to pipe into.

Let's say you have a function `namePerson`, which takes a `person` then a `name` argument. If you are transforming a person then pipe will work as-is:

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

```res
makePerson(~age=47)
  ->namePerson("Jane")
```

```js
namePerson(makePerson(47), "Jane");
```

</CodeTab>

If you have a name that you want to apply to a person object, you can use a placeholder:

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

```res
getName(input)
  ->namePerson(personDetails, _)
```

```js
var __x = getName(input);
namePerson(personDetails, __x);
```

</CodeTab>

This allows you to pipe into any positional argument. It also works for named arguments:

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

```res
getName(input)
  ->namePerson(~person=personDetails, ~name=_)
```

```js
var __x = getName(input);
namePerson(personDetails, __x);
```

</CodeTab>

---
title: "Polymorphic Variant"
description: "The Polymorphic Variant data structure in ReScript"
canonical: "/docs/manual/polymorphic-variant"
section: "Language Features"
order: 10
---

# Polymorphic Variant

Polymorphic variants (or poly variant) are a cousin of [variant](./variant.mdx). With these differences:

- They start with a `#` and the constructor name doesn't need to be capitalized.
- They don't require an explicit type definition. The type is inferred from usage.
- Values of different poly variant types can share the constructors they have in common (aka, poly variants are "structurally" typed, as opposed to ["nominally" typed](./variant.mdx#variant-types-are-found-by-field-name)).

They're a convenient and useful alternative to regular variants, but should **not** be abused. See the drawbacks at the end of this page.

## Creation

We provide 3 syntaxes for a poly variant's constructor:

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

```res
let myColor = #red
let myLabel = #"aria-hidden"
let myNumber = #7
```

```js
var myColor = "red";
var myLabel = "aria-hidden";
var myNumber = 7;
```

</CodeTab>

**Take a look at the output**. Poly variants are _great_ for JavaScript interop. For example, you can use it to model JavaScript string and number enums like TypeScript, but without confusing their accidental usage with regular strings and numbers.

`myColor` uses the common syntax. The second and third syntaxes are to support expressing strings and numbers more conveniently. We allow the second one because otherwise it'd be invalid syntax since symbols like `-` and others are usually reserved.

## Type Declaration

Although **optional**, you can still pre-declare a poly variant type:

```res
// Note the surrounding square brackets, and # for constructors
type color = [#red | #green | #blue]
```

These types can also be inlined, unlike for regular variant:

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

```res
let render = (myColor: [#red | #green | #blue]) => {
  switch myColor {
  | #blue => Console.log("Hello blue!")
  | #red
  | #green => Console.log("Hello other colors")
  }
}
```

```js
function render(myColor) {
  if (myColor === "green" || myColor === "red") {
    console.log("Hello other colors");
  } else {
    console.log("Hello blue!");
  }
}
```

</CodeTab>

**Note**: because a poly variant value's type definition is **inferred** and not searched in the scope, the following snippet won't error:

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

```res
type color = [#red | #green | #blue]

let render = myColor => {
  switch myColor {
  | #blue => Console.log("Hello blue!")
  | #green => Console.log("Hello green!")
  // works!
  | #yellow => Console.log("Hello yellow!")
  }
}
```

```js
function render(myColor) {
  if (myColor === "yellow") {
    console.log("Hello yellow!");
  } else if (myColor === "green") {
    console.log("Hello green!");
  } else {
    console.log("Hello blue!");
  }
}
```

</CodeTab>

That `myColor` parameter's type is inferred to be `#red`, `#green` or `#yellow`, and is unrelated to the `color` type. If you intended `myColor` to be of type `color`, annotate it as `myColor: color` in any of the places.

## Constructor Arguments

This is similar to a regular variant's [constructor arguments](./variant.mdx#constructor-arguments):

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

```res
type account = [
  | #Anonymous
  | #Instagram(string)
  | #Facebook(string, int)
]

let me: account = #Instagram("Jenny")
let him: account = #Facebook("Josh", 26)
```

```js
var me = {
  NAME: "Instagram",
  VAL: "Jenny",
};

var him = {
  NAME: "Facebook",
  VAL: ["Josh", 26],
};
```

</CodeTab>

### Combine Types and Pattern Match

You can use poly variant types within other poly variant types to create a sum of all constructors:

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

```res
type red = [#Ruby | #Redwood | #Rust]
type blue = [#Sapphire | #Neon | #Navy]

// Contains all constructors of red and blue.
// Also adds #Papayawhip
type color = [red | blue | #Papayawhip]

let myColor: color = #Ruby
```

```js
var myColor = "Ruby";
```

</CodeTab>

There's also some special [pattern matching](./pattern-matching-destructuring.mdx) syntax to match on constructors defined in a specific poly variant type:

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

```res
// Continuing the previous example above...

switch myColor {
| #...blue => Console.log("This blue-ish")
| #...red => Console.log("This red-ish")
| other => Console.log2("Other color than red and blue: ", other)
}
```

```js
var other = myColor;

if (other === "Neon" || other === "Navy" || other === "Sapphire") {
  console.log("This is blue-ish");
} else if (other === "Rust" || other === "Ruby" || other === "Redwood") {
  console.log("This is red-ish");
} else {
  console.log("Other color than red and blue: ", other);
}
```

</CodeTab>

This is a shorter version of:

```res
switch myColor {
| #Sapphire | #Neon | #Navy => Console.log("This is blue-ish")
| #Ruby | #Redwood | #Rust => Console.log("This is red-ish")
| other => Console.log2("Other color than red and blue: ", other)
}
```

## Structural Sharing

Since poly variants value don't have a source of truth for their type, you can write such code:

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

```res
type preferredColors = [#white | #blue]

let myColor: preferredColors = #blue

let displayColor = v => {
  switch v {
  | #red => "Hello red"
  | #green => "Hello green"
  | #white => "Hey white!"
  | #blue => "Hey blue!"
  }
}

Console.log(displayColor(myColor))
```

```js
var myColor = "blue";

function displayColor(v) {
  if (v === "white") {
    return "Hey white!";
  } else if (v === "red") {
    return "Hello red";
  } else if (v === "green") {
    return "Hello green";
  } else {
    return "Hey blue!";
  }
}

console.log(displayColor("blue"));
```

</CodeTab>

With a regular variant, the line `displayColor(myColor)` would fail, since it'd complain that the type of `myColor` doesn't match the type of `v`. No problem with poly variant.

## JavaScript Output

Poly variants are great for JavaScript interop! You can share their values to JS code, or model incoming JS values as poly variants.

- `#red` and `#"I am red 😃"` compile to JavaScipt `"red"` and `"I am red 😃"`.
- `#1` compiles to JavaScript `1`.
- Poly variant constructor with 1 argument, like `Instagram("Jenny")` compile to a straightforward `{NAME: "Instagram", VAL: "Jenny"}`. 2 or more arguments like `#Facebook("Josh", 26)` compile to a similar object, but with `VAL` being an array of the arguments.

### Bind to Functions

For example, let's assume we want to bind to `Intl.NumberFormat` and want to make sure that our users only pass valid locales, we could define an external binding like this:

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

```res
type t

@scope("Intl") @val
external makeNumberFormat: ([#"de-DE" | #"en-GB" | #"en-US"]) => t = "NumberFormat"

let intl = makeNumberFormat(#"de-DE")
```

```js
var intl = Intl.NumberFormat("de-DE");
```

</CodeTab>

The JS output is identical to handwritten JS, but we also get to enjoy type errors if we accidentally write `makeNumberFormat(#"de-DR")`.

More advanced usage examples for poly variant interop can be found in [Bind to JS Function](./bind-to-js-function.mdx#constrain-arguments-better).

### Bind to String Enums

Let's assume we have a TypeScript module that expresses following enum export:

```js
// direction.js
enum Direction {
  Up = "UP",
  Down = "DOWN",
  Left = "LEFT",
  Right = "RIGHT",
}

export const myDirection = Direction.Up
```

For this particular example, we can also inline poly variant type definitions to design the type for the imported `myDirection` value:

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

```res
type direction = [ #UP | #DOWN | #LEFT | #RIGHT ]
@module("./direction.js") external myDirection: direction = "myDirection"
```

```js
var DirectionJs = require("./direction.js");

var myDirection = DirectionJs.myDirection;
```

</CodeTab>

Again: since we were using poly variants, the JS Output is practically zero-cost and doesn't add any extra code!

## Extra Constraints on Types

The previous poly variant type annotations we've looked at are the regular "closed" kind. However, there's a way to express "I want at least these constructors" (lower bound) and "I want at most these constructors" (upper bound):

```res
// Only #Red allowed. Closed.
let basic: [#Red] = #Red

// May contain #Red, or any other value. Open
// here, foreground will actually be inferred as [> #Red | #Green]
let foreground: [> #Red] = #Green

// The value must be, at most, one of #Red or #Blue
// Only #Red and #Blue are valid values
let background: [< #Red | #Blue] = #Red
```

**Note:** We added this info for educational purposes. In most cases you will not want to use any of this stuff, since it makes your APIs pretty unreadable / hard to use.

### Closed `[`

This is the simplest poly variant definition, and also the most practical one. Like a common variant type, this one defines an exact set of constructors.

```res
type rgb = [ #Red | #Green | #Blue ]

let color: rgb = #Green
```

In the example above, `color` will only allow one of the three constructors that are defined in the `rgb` type. This is usually the way how poly variants should be defined.

In case you want to define a type that is extensible, you'll need to use the lower / upper bound syntax.

### Lower Bound `[>`

A lower bound defines the minimum set of constructors a poly variant type is aware of. It is also considered an "open poly variant type", because it doesn't restrict any additional values.

Here is an example on how to make a minimum set of `basicBlueTones` extensible for a new `color` type:

```res
type basicBlueTone<'a> = [> #Blue | #DeepBlue | #LightBlue ] as 'a
type color = basicBlueTone<[#Blue | #DeepBlue | #LightBlue | #Purple]>

let color: color = #Purple

// This will fail due to missing minimum constructors:
type notWorking = basicBlueTone<[#Purple]>
```

Here, the compiler will enforce the user to define `#Blue | #DeepBlue | #LightBlue` as the minimum set of constructors when trying to extend `basicBlueTone<'a>`.

**Note:** Since we want to define an extensible poly variant, we need to provide a type placeholder `<'a>`, and also add `as 'a` after the poly variant declaration, which essentially means: "Given type `'a` is constraint to the minimum set of constructors (`#Blue | #DeepBlue | #LightBlue`) defined in `basicBlueTone`".

### Upper Bound `[<`

The upper bound works in the opposite way than a lower bound: the extending type may only use constructors that are stated in the upper bound constraint.

Here another example, but with red colors:

```res
type validRed<'a> = [< #Fire | #Crimson | #Ash] as 'a
type myReds = validRed<[#Ash]>

// This will fail due to unlisted constructor not defined by the lower bound
type notWorking = validRed<[#Purple]>
```

## Coercion

You can convert a poly variant to a `string` or `int` at no cost:

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

```res
type company = [#Apple | #Facebook]
let theCompany: company = #Apple

let message = "Hello " ++ (theCompany :> string)
```

```js
var theCompany = "Apple";
var message = "Hello " + theCompany;
```

</CodeTab>

**Note**: for the coercion to work, the poly variant type needs to be closed; you'd need to annotate it, since otherwise, `theCompany` would be inferred as `[> #Apple]`.

## Tips & Tricks

### Variant vs Polymorphic Variant

One might think that polymorphic variants are superior to regular [variants](./variant.mdx). As always, there are trade-offs:

- Due to their "structural" nature, poly variant's type errors might be more confusing. If you accidentally write `#blur` instead of `#blue`, ReScript will still error but can't indicate the correct source as easily. Regular variants' source of truth is the type definition, so the error can't go wrong.
- It's also harder to refactor poly variants. Consider this:

  ```res
  let myFruit = #Apple
  let mySecondFruit = #Apple
  let myCompany = #Apple
  ```

  Refactoring the first one to `#Orange` doesn't mean we should refactor the third one. Therefore, the editor plugin can't touch the second one either. Regular variant doesn't have such problem, as these 2 values presumably come from different variant type definitions.

- You might lose some nice pattern match checks from the compiler:

  ```res
  let myColor = #red

  switch myColor {
  | #red => Console.log("Hello red!")
  | #blue => Console.log("Hello blue!")
  }
  ```

  Because there's no poly variant definition, it's hard to know whether the `#blue` case can be safely removed.

In most scenarios, we'd recommend to use regular variants over polymorphic variants, especially when you are writing plain ReScript code. In case you want to write zero-cost interop bindings or generate clean JS output, poly variants are oftentimes a better option.

---
title: "Primitive Types"
description: "Primitive Data Types in ReScript"
canonical: "/docs/manual/primitive-types"
section: "Language Features"
order: 4
---

# Primitive Types

ReScript comes with the familiar primitive types like `string`, `int`, `float`, etc.

{/* TODO: doc unit */}

## String

ReScript `string`s are delimited using **double** quotes (single quotes are reserved for the character type below).

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

```res example
let greeting = "Hello world!"
let multilineGreeting = "Hello
 world!"
```

```js
var greeting = "Hello world!";
var multilineGreeting = "Hello\n world!";
```

</CodeTab>

To concatenate strings, use `++`:

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

```res example
let greetings = "Hello " ++ "world!"
```

```js
var greetings = "Hello world!";
```

</CodeTab>

### String Interpolation

There's a special syntax for string that allows

- multiline string just like before
- no special character escaping
- Interpolation

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

```res example
let name = "Joe"

let greeting = `Hello
World
👋
${name}
`
```

```js
var name = "Joe";

var greeting = "Hello\nWorld\n👋\n" + name + "\n";
```

</CodeTab>

This is just like JavaScript's backtick string interpolation, except without needing to escape special characters.

### Usage

See the familiar `String` API in the [API docs](/docs/manual/api/stdlib/string). Since a ReScript string maps to a JavaScript string, you can mix & match the string operations in all standard libraries.

### Tips & Tricks

**You have a good type system now!** In an untyped language, you'd often overload the meaning of string by using it as:

- a unique id: `var BLUE_COLOR = "blue"`
- an identifier into a data structure: `var BLUE = "blue" var RED = "red" var colors = [BLUE, RED]`
- the name of an object field: `person["age"] = 24`
- an enum: `if (audio.canPlayType() === 'probably') {...}` [(ಠ_ಠ)](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/canPlayType#Return_value)
- other crazy patterns you'll soon find horrible, after getting used to ReScript's alternatives.

The more you overload the poor string type, the less the type system (or a teammate) can help you! ReScript provides concise, fast and maintainable types & data structures alternatives to the use-cases above (e.g. [variants](./variant.mdx)).

## Char

ReScript has a type for a string with a single letter:

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

```res example
let firstLetterOfAlphabet = 'a'
```

```js
var firstLetterOfAlphabet = /* "a" */ 97;
```

</CodeTab>

**Note**: Char doesn't support Unicode or UTF-8 and is therefore not recommended.

To convert a String to a Char, use `String.get("a", 0)`. To convert a Char to a String, use `String.make(1, 'a')`.

## Regular Expression

ReScript regular expressions compile cleanly to their JavaScript counterpart:

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

```res example
let r = /b/g
```

```js
let r = /b/g;
```

</CodeTab>

A regular expression like the above has the type `RegExp.t`. The [RegExp](/docs/manual/api/stdlib/regexp) module contains the regular expression helpers you have seen in JS.

## Boolean

A ReScript boolean has the type `bool` and can be either `true` or `false`. Common operations:

- `&&`: logical and.
- `||`: logical or.
- `!`: logical not.
- `<=`, `>=`, `<`, `>`
- `==`: structural equal, compares data structures deeply. `(1, 2) == (1, 2)` is `true`. Convenient, but use with caution.
- `===`: referential equal, compares shallowly. `(1, 2) === (1, 2)` is `false`. `let myTuple = (1, 2); myTuple === myTuple` is `true`.
- `!=`: structural unequal.
- `!==`: referential unequal.

ReScript's `true/false` compiles into a JavaScript `true/false`.

## Integers

32-bits, truncated when necessary. We provide the usual operations on them: `+`, `-`, `*`, `/`, etc. See [Int](/docs/manual/api/stdlib/int) for helper functions.

Integer operators include `+`, `-`, `*`, `/`, `**`, and `%`.

`%` keeps the familiar `mod` naming, but its semantics are remainder (same behavior as JavaScript `%`).

Bitwise operators for `int`: `~~~`, `&&&`, `|||`, `^^^`, `<<`, `>>`, `>>>`.

**Be careful when you bind to JavaScript numbers!** Since ReScript integers have a much smaller range than JavaScript numbers, data might get lost when dealing with large numbers. In those cases it’s much safer to bind the numbers as **float**. Be extra mindful of this when binding to JavaScript Dates and their epoch time.

To improve readability, you may place underscores in the middle of numeric literals such as `1_000_000`. Note that underscores can be placed anywhere within a number, not just every three digits.

## Floats

Arithmetic operators (`+`, `-`, `*`, `/`, `%`, `**`) work for both `int` and `float`. Like `0.5 + 0.6`. See [Float](/docs/manual/api/stdlib/float) for helper functions.

As with integers, you may use underscores within literals to improve readability.

### Int-to-Float Coercion

`int` values can be coerced to `float` with the `:>` (type coercion) operator.

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

```res example
let result = (1 :> float) + 2.
```

```js
var result = 1 + 2;
```

</CodeTab>

## Big Integers (experimental)

**Since 11.1**

For values which are too large to be represented by Int or Float, there is the `bigint` primitive type.
We provide the usual operations on them: `+`, `-`, `*`, `/`, `**`, `%`, etc. See [BigInt](/docs/manual/api/stdlib/bigint) for helper functions.

A `bigint` number is denoted by a trailing `n` like so: `42n`.

As `bigint` is a different data type than `int`, it's necessary to open the corresponding module to overload the operators.

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

```res example
open! BigInt

let a = 9007199254740991n + 9007199254740991n
let b = 2n ** 2n
```

```js
var a = 9007199254740991n + 9007199254740991n;

var p = 2n ** 2n;
```

</CodeTab>

It also supports all the bitwise operations, except unsigned shift right (`>>>`), which is not supported by JS itself for `bigint`s.

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

```res example
open! BigInt

let a = 5n &&& 3n
let b = 5n ||| 2n
let c = 5n ^^^ 1n
let d = ~~~5n
let e = 5n << 1n
let f = 5n >> 1n
```

```js
var a = 5n & 3n;

var b = 5n | 2n;

var c = 5n ^ 1n;

var d = ~5n;

var e = 5n << 1n;

var f = 5n >> 1n;
```

</CodeTab>

It can also be pattern-matched.

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

```res example
let bigintValue = 1n

switch bigintValue {
| 1n => Console.log("Small bigint")
| 100n => Console.log("Larger bigint")
| _ => Console.log("Other bigint")
}
```

```js
if (1n !== 1n) {
  if (1n !== 100n) {
    console.log("Other bigint");
  } else {
    console.log("Larger bigint");
  }
} else {
  console.log("Small bigint");
}

var bigintValue = 1n;
```

</CodeTab>

## Unit

The `unit` type indicates the absence of a specific value. It has only a single value, `()`, which acts as a placeholder when no other value exists or is needed. It compiles to JavaScript's `undefined` and resembles the `void` type in languages such as C++. What's the point of such a type?

Consider the `Math.random` function. Its type signature is `unit => float`, which means it receives a `unit` as input and calculates a random `float` as output. You use the function like this - `let x = Math.random()`. Notice `()` as the first and only function argument.

Imagine a simplified `Console.log` function that prints a message. Its type signature is `string => unit` and you'd use it like this `Console.log("Hello!")`. It takes a string as input, prints it, and then returns nothing useful. When `unit` is the output of a function it means the function performs some kind of side-effect.

## Unknown

The `unknown` type represents values with contents that are a mystery or are not 100% guaranteed to be what you think they are. It provides type-safety when interacting with data received from an untrusted source. For example, suppose an external function is supposed to return a `string`. It might. But if the documentation is not accurate or the code has bugs, the function could return `null`, an `array`, or something else you weren't expecting.

The ReScript type system helps you avoid run-time crashes and unpredicatable behavior by preventing you from using `unknown` in places that expect a `string` or `int` or some other type. The ReScript core libraries also provide utility functions to help you inspect `unknown` values and access their contents. In some cases you may need a JSON parsing library to convert `unknown` values to types you can safely use.

Consider using `unknown` when receiving data from [external JavaScript functions](./bind-to-js-function.mdx)

---
title: "Project Structure"
description: "Notes on project structure and other rough ReScript guidelines"
canonical: "/docs/manual/project-structure"
section: "Guides"
order: 3
---

# Project Structure

These are the existing, non-codified community practices that are currently propagated through informal agreement. We might remove some of them at one point, and enforce some others. Right now, they're just recommendations for ease of newcomers.

## File Casing

Capitalized file names (aka first letter upper-cased).

**Justification**: Module names can only be capitalized. Newcomers often ask how a file maps to a module, and why `draw.res` maps to the module `Draw`, and sometimes try to refer to a module through uncapitalized identifiers. Using `Draw.res` makes this mapping more straightforward. It also helps certain file names that'd be awkward in uncapitalized form: `uRI.res`.

## Ignore `.merlin` File

This is generated by the build system and you should not have to manually edit it. Don't check it into the repo.

**Justification**: `.merlin` is for editor tooling. The file contains absolute paths, which are also not cross-platform (e.g. Windows paths are different).

## Folders

Try not to have too many nested folders. Keep your project flat, and have fewer files (reminder: you can use nested modules).

**Justification**: The file system is a _tree_, but your code's dependencies are a _graph_. Because of that, any file & folder organization is usually imperfect. While it's still valuable to group related files together in a folder, the time wasted debating & getting decision paralysis over these far outweight their benefits. We'll always recommend you to Get Work Done instead of debating about these issues.

## Third-party Dependencies

Keep them to a minimum.

**Justification**: A compiled, statically typed language cannot model its dependencies easily by muddling along like in a dynamic language, especially when we're still piggy-backing on NPM/Yarn (to reduce learning overhead in the medium-term). Keeping dependencies simple & lean helps reduce possibility of conflicts (e.g. two diamond dependencies, or clashing interfaces).

## Documentation

Have them. Spend more effort making them great (examples, pitfalls) and professional rather than _just_ fancy-looking. Do use examples, and avoid using names such as `foo` and `bar`. There's always more concrete names (it's an example, no need to be abstract/generalized just yet. The API docs will do this plentily). For blog posts, don't repeat the docs themselves, describe the _transition_ from old to new, and why (e.g. "it was a component, now it's a function, because ...").

**Justification**: It's hard for newcomers to distinguish between a simple/decent library and one that's fancy-looking. For the sake of the community, don't try too hard to one-up each other's libraries. Do spread the words, but use your judgement too.

## PPX & Other Meta-tools

Keep them to a minimum. PPX, unless used in renown cases (printer, accessors and serializer/deserializer generation), can cause big learning churn for newcomers; on top of the syntax, semantics, types, build tool & FFI that they already have to learn, learning per-library custom transformations of the code is an extra step. More invasive macros makes the code itself less semantically meaningful too, since the essence would be hiding somewhere else.

## Paradigm

Don't abuse overly fancy features. Do leave some breathing room for future APIs but don't over-architect things.

**Justification**: Simple code helps newcomers understand and potentially contribute to your code. Contributing is the best way for them to learn. The extra help you receive might also surpass the gain of using a slightly more clever language trick. But do try new language tricks in some of more casual projects! You might discover new ways of architecting code.

## Publishing

If it's a wrapper for a JS library, don't publish the JS artifacts. If it's a legit library, publish the artifacts in lib/js if you think JS consumers might use it. This is especially the case when you gradually convert a JS lib to ReScript while not breaking existing JS consumers.

Do put the keywords `"rescript"` in your package.json `keywords` field. This allows us to find the library much more easily for future purposes.

**Justification**: Be nice to JS consumers of your library. They're your future ReScripters.

---
title: "Promises"
description: "JS Promise handling in ReScript"
canonical: "/docs/manual/promise"
section: "Language Features"
order: 21
---

# Promise

> **Note:** Starting from ReScript 10.1 and above, we recommend using [async / await](./async-await.mdx) when interacting with Promises.

## `promise` type

**Since 10.1**

In ReScript, every JS promise is represented with the globally available `promise<'a>` type.

Here's a usage example in a function signature:

```resi
// User.resi file

type user = {name: string}

let fetchUser: string => promise<user>
```

To work with promise values (instead of using `async` / `await`) you may want to use the built-in `Promise` module.

## Promise

A builtin module to create, chain and manipulate promises.

### Creating a promise

```res
let p1 = Promise.make((resolve, reject) => {
  resolve("hello world")
})

let p2 = Promise.resolve("some value")

// You can only reject `exn` values for streamlined catch handling
exception MyOwnError(string)
let p3 = Promise.reject(MyOwnError("some rejection"))
```

### Access the contents and transform a promise

```res
let logAsyncMessage = () => {
  open Promise
  Promise.resolve("hello world")
  ->then(msg => {
    // then callbacks require the result to be resolved explicitly
    resolve("Message: " ++ msg)
  })
  ->then(msg => {
    Console.log(msg)

    // Even if there is no result, we need to use resolve() to return a promise
    resolve()
  })
  ->ignore // Requires ignoring due to unhandled return value
}
```

For comparison, the `async` / `await` version of the same code would look like this:

```res
let logAsyncMessage = async () => {
  let msg = await Promise.resolve("hello world")
  Console.log(`Message: ${msg}`)
}
```

Needless to say, the async / await version offers better ergonomics and less opportunities to run into type issues.

### Handling Rejected Promises

You can handle a rejected promise using the [`Promise.catch()`](/docs/manual/api/stdlib/promise#value-catch) method, which allows you to catch and manage errors effectively.

### Run multiple promises in parallel

In case you want to launch multiple promises in parallel, use `Promise.all`:

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

```res
@val
external fetchMessage: string => promise<string> = "global.fetchMessage"

let logAsyncMessage = async () => {
  let messages = await Promise.all([fetchMessage("message1"), fetchMessage("message2")])

  Console.log(messages->Array.joinWith(", "))
}
```

```js
async function logAsyncMessage(param) {
  var messages = await Promise.all([
    global.fetchMessage("message1"),
    global.fetchMessage("message2"),
  ]);
  console.log(messages.join(", "));
}

export { logAsyncMessage };
```

</CodeTab>

---
title: "Record"
description: "Record types in ReScript"
canonical: "/docs/manual/record"
section: "Language Features"
order: 6
---

# Record

Records are like JavaScript objects but:

- are immutable by default
- have fixed fields (not extensible)

## Type Declaration

A record needs a mandatory type declaration:

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

```res prelude
type person = {
  age: int,
  name: string,
}
```

```js
// Empty output
```

</CodeTab>

You can also nest definitions of records.

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

```res example
type person = {
  age: int,
  name: string,
  notificationSettings: {
    sendEmails: bool,
    allowPasswordLogin: bool,
  },
}

let person = {
  age: 90,
  name: "Test Person",
  notificationSettings: {
    sendEmails: true,
    allowPasswordLogin: false,
  },
}

```

```js
let person = {
  age: 90,
  name: "Test Person",
  notificationSettings: {
    sendEmails: true,
    allowPasswordLogin: false,
  },
};
```

</CodeTab>

Nesting record definitions is a nice way to group records that are part of the same structure, and won't be referenced from the outside.

If you end up needing to refer to a nested record type explicitly, you should make it an explicit definition instead of a nested one. This is mainly for 2 reasons:

- The records that are automatically generated for the nested record definitions are named in a way that would require you to use escaped identifiers to reference them. The nested record at `notificationSettings` above would be named `\"person.notificationSettings"` for instance
- For the sake of clarity (and caring about your co-workers), having an explicit and named definition to look at and refer to is much easier than scanning a potentially large record definition for the nested record you're looking for

So if we in the example above ended up needing to refer to `person.notificationSettings` nested record from the outside, we should instead make it explicit, just like how we normally define records:

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

```res example
type personNotificationSettings = {
  sendEmails: bool,
  allowPasswordLogin: bool,
}

type person = {
  age: int,
  name: string,
  notificationSettings: personNotificationSettings
}

let person = {
  age: 90,
  name: "Test Person",
  notificationSettings: {
    sendEmails: true,
    allowPasswordLogin: false,
  },
}

```

```js
let person = {
  age: 90,
  name: "Test Person",
  notificationSettings: {
    sendEmails: true,
    allowPasswordLogin: false,
  },
};
```

</CodeTab>

## Creation

To create a `person` record (declared above):

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

```res prelude
let me = {
  age: 5,
  name: "Big ReScript"
}
```

```js
var me = {
  age: 5,
  name: "Big ReScript",
};
```

</CodeTab>

When you create a new record value, ReScript tries to find a record type declaration that conforms to the shape of the value. So the `me` value here is inferred as of type `person`.

The type is found by looking above the `me` value. **Note**: if the type instead resides in another file or module, you need to explicitly indicate which file or module it is:

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

```res example
// School.res
type person = {age: int, name: string}
```

```js
// Empty output
```

</CodeTab>

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

```res
// Example.res

let me: School.person = {age: 20, name: "Big ReScript"}
/* or */
let me2 = {School.age: 20, name: "Big ReScript"}
```

```js
var me = {
  age: 20,
  name: "Big ReScript",
};
var me2 = {
  age: 20,
  name: "Big ReScript",
};
```

</CodeTab>

In both `me` and `me2` the record definition from `School` is found. The first one, `me` with the regular type annotation, is preferred.

## Access

Use the familiar dot notation:

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

```res example
let name = me.name
```

```js
var name = "Big ReScript";
```

</CodeTab>

## Immutable Update

New records can be created from old records with the `...` spread operator. The original record isn't mutated.

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

```res example
let meNextYear = {...me, age: me.age + 1}
```

```js
var meNextYear = {
  age: 21,
  name: "Big ReScript",
};
```

</CodeTab>

**Note**: spread cannot add new fields to the record value, as a record's shape is fixed by its type.

## Mutable Update

Record fields can optionally be mutable. This allows you to efficiently update those fields in-place with the `=` operator.

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

```res example
type person = {
  name: string,
  mutable age: int
}

let baby = {name: "Baby ReScript", age: 5}
baby.age = baby.age + 1 // `baby.age` is now 6. Happy birthday!
```

```js
var baby = {
  name: "Baby ReScript",
  age: 5,
};

baby.age = (baby.age + 1) | 0;
```

</CodeTab>

Fields not marked with `mutable` in the type declaration cannot be mutated.

## JavaScript Output

ReScript records compile to straightforward JavaScript objects; see the various JS output tabs above.

## Optional Record Fields

ReScript [`v10`](../../blog/release-10-0-0.mdx#experimental-optional-record-fields) introduced optional record fields. This means that you can define fields that can be omitted when creating the record. It looks like this:

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

```res example
type person = {
  age: int,
  name?: string
}
```

```js
// Empty output
```

</CodeTab>

Notice how `name` has a suffixed `?`. That means that the field itself is _optional_.

### Creation

You can omit any optional fields when creating a record. Not setting an optional field will default the field's value to `None`:

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

```res example
type person = {
  age: int,
  name?: string
}

let me = {
  age: 5,
  name: "Big ReScript"
}

let friend = {
  age: 7
}
```

```js
var me = {
  age: 5,
  name: "Big ReScript",
};

var friend = {
  age: 7,
};
```

</CodeTab>

This has consequences for pattern matching, which we'll expand a bit on soon.

## Immutable Update

Updating an optional field via an immutable update above lets you set that field value without needing to care whether it's optional or not.

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

```res example
type person = {
  age: int,
  name?: string
}

let me = {
  age: 123,
  name: "Hello"
}

let withoutName = {
  ...me,
  name: "New Name"
}
```

```js
import * as Caml_obj from "./stdlib/caml_obj.js";

var me = {
  age: 123,
  name: "Hello",
};

var newrecord = Caml_obj.obj_dup(me);

newrecord.name = "New Name";

var withoutName = newrecord;
```

</CodeTab>

However, if you want to set the field to an optional value, you prefix that value with `?`:

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

```res example
type person = {
  age: int,
  name?: string
}

let me = {
  age: 123,
  name: "Hello"
}

let maybeName = Some("My Name")

let withoutName = {
  ...me,
  name: ?maybeName
}
```

```js
import * as Caml_obj from "./stdlib/caml_obj.js";

var me = {
  age: 123,
  name: "Hello",
};

var maybeName = "My Name";

var newrecord = Caml_obj.obj_dup(me);

newrecord.name = maybeName;

var withoutName = newrecord;
```

</CodeTab>

You can unset an optional field's value via that same mechanism by setting it to `?None`.

### Pattern Matching on Optional Fields

[Pattern matching](./pattern-matching-destructuring.mdx), one of ReScript's most important features, has two caveats when you deal with optional fields.

When matching on the value directly, it's an `option`. Example:

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

```res
type person = {
  age: int,
  name?: string,
}

let me = {
  age: 123,
  name: "Hello",
}

let isRescript = switch me.name {
| Some("ReScript") => true
| Some(_) | None => false
}
```

```js
var isRescript;

isRescript = "Hello" === "ReScript" ? true : false;

var me = {
  age: 123,
  name: "Hello",
};
```

</CodeTab>

But, when matching on the field as part of the general record structure, it's treated as the underlying, non-optional value:

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

```res
type person = {
  age: int,
  name?: string,
}

let me = {
  age: 123,
  name: "Hello",
}

let isRescript = switch me {
| {name: "ReScript"} => true
| _ => false
}

```

```js
var isRescript;

isRescript = "Hello" === "ReScript" ? true : false;

var me = {
  age: 123,
  name: "Hello",
};
```

</CodeTab>

Sometimes you _do_ want to know whether the field was set or not. You can tell the pattern matching engine about that by prefixing your option match with `?`, like this:

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

```res
type person = {
  age: int,
  name?: string,
}

let me = {
  age: 123,
  name: "Hello",
}

let nameWasSet = switch me {
| {name: ?None} => false
| {name: ?Some(_)} => true
}
```

```js
var nameWasSet = true;

var me = {
  age: 123,
  name: "Hello",
};
```

</CodeTab>

## Record Type Spread

In ReScript v11, you can now spread one or more record types into a new record type. It looks like this:

```rescript
type a = {
  id: string,
  name: string,
}

type b = {
  age: int
}

type c = {
  ...a,
  ...b,
  active: bool
}
```

`type c` will now be:

```rescript
type c = {
  id: string,
  name: string,
  age: int,
  active: bool,
}
```

Record type spreads act as a 'copy-paste' mechanism for fields from one or more records into a new record. This operation inlines the fields from the spread records directly into the new record definition, while preserving their original properties, such as whether they are optional or mandatory. It's important to note that duplicate field names are not allowed across the records being spread, even if the fields have the same type.

## Record Type Coercion

Record type coercion gives us more flexibility when passing around records in our application code. In other words, we can now coerce a record `a` to be treated as a record `b` at the type level, as long as the original record `a` contains the same set of fields in `b`. Here's an example:

```rescript
type a = {
  name: string,
  age: int,
}

type b = {
  name: string,
  age: int,
}

let nameFromB = (b: b) => b.name

let a: a = {
  name: "Name",
  age: 35,
}

let name = nameFromB(a :> b)
```

Notice how we _coerced_ the value `a` to type `b` using the coercion operator `:>`. This works because they have the same record fields. This is purely at the type level, and does not involve any runtime operations.

Additionally, we can also coerce records from `a` to `b` whenever `a` is a super-set of `b` (i.e. `a` containing all the fields of `b`, and more). The same example as above, slightly altered:

```rescript
type a = {
  id: string,
  name: string,
  age: int,
  active: bool,
}

type b = {
  name: string,
  age: int,
}

let nameFromB = (b: b) => b.name

let a: a = {
  id: "1",
  name: "Name",
  age: 35,
  active: true,
}

let name = nameFromB(a :> b)
```

Notice how `a` now has more fields than `b`, but we can still coerce `a` to `b` because `b` has a subset of the fields of `a`.

In combination with [optional record fields](./record.mdx#optional-record-fields), one may coerce a mandatory field of an `option` type to an optional field:

```rescript
type a = {
  name: string,

  // mandatory, but explicitly typed as option<int>
  age: option<int>,
}

type b = {
  name: string,
  // optional field
  age?: int,
}

let nameFromB = (b: b) => b.name

let a: a = {
  name: "Name",
  age: Some(35),
}

let name = nameFromB(a :> b)
```

## Tips & Tricks

### Record Types Are Found By Field Name

With records, you **cannot** say "I'd like this function to take any record type, as long as they have the field `age`". The following **won't work as intended**:

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

```res
type person = {age: int, name: string}
type monster = {age: int, hasTentacles: bool}

let getAge = (entity) => entity.age
```

```js
function getAge(entity) {
  return entity.age;
}
```

</CodeTab>

Instead, `getAge` will infer that the parameter `entity` must be of type `monster`, the closest record type with the field `age`. The following code's last line fails:

```res
let kraken = {age: 9999, hasTentacles: true}
let me = {age: 5, name: "Baby ReScript"}

getAge(kraken)
getAge(me) // type error!
```

The type system will complain that `me` is a `person`, and that `getAge` only works on `monster`. If you need such capability, use ReScript objects, described [here](./object.mdx).

### Optional Fields in Records Can Be Useful for Bindings

Many JavaScript APIs tend to have large configuration objects that can be a bit annoying to model as records, since you previously always needed to specify all record fields when creating a record.

Optional record fields, introduced in [`v10`](../../blog/release-10-0-0.mdx#experimental-optional-record-fields), is intended to help with this. Optional fields will let you avoid having to specify all fields, and let you just specify the one's you care about. A significant improvement in ergonomics for bindings and other APIs with for example large configuration objects.

## Design Decisions

Why use records instead of objects?

1. The truth is that most of the times in your app, your data's shape is actually fixed, and if it's not, it can potentially be better represented as a combination of variant (introduced next) + record instead.

2. Since a record type is resolved through finding that single explicit type declaration (we call this "nominal typing"), the type error messages end up better than the counterpart ("structural typing", like for tuples). This makes refactoring easier; changing a record type's fields naturally allows the compiler to know that it's still the same record, just misused in some places. Otherwise, under structural typing, it might get hard to tell whether the definition site or the usage site is wrong.

---
title: "Reserved Keywords"
description: "All reserved keywords in ReScript"
canonical: "/docs/manual/reserved-keywords"
section: "Language Features"
order: 27
---

# Reserved Keywords

> **Note**: Some of these words are reserved purely for backward compatibility.
>
> If you _need_ to use one of these names as binding and/or field name, see [Use Illegal Identifier Names](./use-illegal-identifier-names.mdx).

- `and`
- `as`
- `assert`

{/* - `begin` */}

{/* - `class` */}

- `constraint`

{/* - `do` */}
{/* - `done` */}

- `else`
  {/* - `end` */}
  {/* - `esfun` */}
- `exception`
- `external`

* `false`
* `for`
  {/* - `fun` */}
  {/* - `function` */}
  {/* - `functor` */}

- `if`
- `in`
- `include`
  {/* - `inherit` */}
  {/* - `initializer` */}

* `lazy`
* `let`

- `module`
- `mutable`

{/* - `new` */}
{/* - `nonrec` */}

{/* - `object` */}

- `of`
- `open`
  {/* - `or` */}

{/* - `pri` */}
{/* - `pub` */}

- `rec`

{/* - `sig` */}
{/* - `struct` */}

- `switch`

{/* - `then` */}

- `true`
- `try`
- `type`

{/* - `val` */}
{/* - `virtual` */}

- `when`
- `while`
- `with`

---
title: "Scoped Polymorphic Types"
description: "Scoped Polymorphic Types in ReScript"
canonical: "/docs/manual/scoped-polymorphic-types"
section: "Advanced Features"
order: 2
---

# Scoped Polymorphic Types

Scoped Polymorphic Types in ReScript are functions with the capability to handle arguments of any type within a specific scope. This feature is particularly valuable when working with JavaScript APIs, as it allows your functions to accommodate diverse data types while preserving ReScript's strong type checking.

## Definition and Usage

Scoped polymorphic types in ReScript offer a flexible and type-safe way to handle diverse data types within specific scopes. This documentation provides an example to illustrate their usage in a JavaScript context.

### Example: Logging API

Consider a logging example within a JavaScript context that processes various data types:

```js
const logger = {
  log: (data) => {
    if (typeof data === "string") {
      /* handle string */
    } else if (typeof data === "number") {
      /* handle number */
    } else {
      /* handle other types */
    }
  },
};
```

In ReScript, we can bind to this function as a record with a scoped polymorphic function type:

```res prelude
type logger = { log: 'a. 'a => unit }

@module("jsAPI") external getLogger: unit => logger = "getLogger"
```

The `logger` type represents a record with a single field `log`, which is a scoped polymorphic function type `'a. 'a => unit`. The `'a` indicates a type variable that can be any type within the scope of the `log` function.

Now, we can utilize the function obtained from `getLogger`:

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

```res example
let myLogger = getLogger()

myLogger.log("Hello, ReScript!")
myLogger.log(42)
```

```js
var myLogger = JsAPI.getLogger();

myLogger.log("Hello, ReScript!");
myLogger.log(42);
```

</CodeTab>

In this example, we create an instance of the logger by calling `getLogger()`, and then we can use the `log` function on the `myLogger` object to handle different data types.

## Limitations of Normal Polymorphic Types

Let's consider the same logging example in ReScript, but this time using normal polymorphic types:

```res
type logger<'a> = { log: 'a => unit}

@module("jsAPI") external getLogger: unit => logger<'a> = "getLogger"
```

In this case, the `logger` type is a simple polymorphic function type `'a => unit`. However, when we attempt to use this type in the same way as before, we encounter an issue:

```res
let myLogger = getLogger()

myLogger.log("Hello, ReScript!")
myLogger.log(42) // Type error!
```

The problem arises because the type inference in ReScript assigns a concrete type to the `logger` function based on the first usage. In this example, after the first call to `myLogger`, the compiler infers the type `logger<string>` for `myLogger`. Consequently, when we attempt to pass an argument of type `number` in the next line, a type error occurs because it conflicts with the inferred type `logger<string>`.

In contrast, scoped polymorphic types, such as `'a. 'a => unit`, overcome this limitation by allowing type variables within the scope of the function. They ensure that the type of the argument is preserved consistently within that scope, regardless of the specific value used in the first invocation.

## Limitations of Scoped Polymorphic Types

Scoped polymorphic types work only when they are directly applied to let-bindings or record fields (as demonstrated in the logger example above). They can neither be applied to function bodies, nor to separate type definitions:

```res
exception Abort

let testExn: 'a. unit => 'a = () => throw(Abort) // Works!

let testExn2 = (): 'a. 'a = throw(Abort) // Syntax error!
type fn = 'a. 'a => unit // Syntax error!
```

---
title: "Shared Data Types"
description: "Data types that share runtime presentation between JS and ReScript"
canonical: "/docs/manual/shared-data-types"
section: "JavaScript Interop"
order: 2
---

# Shared Data Types

ReScript's built-in values of type `string`, `float`, `array` and a few others have a rather interesting property: they compile to the exact same value in JavaScript!

This means that if you're passing e.g. a ReScript string to the JavaScript side, the JavaScript side can directly use it as a native string. It also means that you can import a JavaScript string and use it as a native ReScript string.

ReScript values compile to their JavaScript equivalents directly, so **no data converters are needed for most types**.

**Shared, bidirectionally usable types**:

- String. ReScript strings are JavaScript strings, vice-versa. (Caveat: only our backtick string `` `hello 👋 ${personName}` `` supports unicode and interpolation).
- Float. ReScript floats are JavaScript numbers, vice-versa.
- Array. Use the [Array API](/docs/manual/api/stdlib/array) for array operations.
- Tuple. Compiles to an array at runtime. You can treat a fixed-sized, heterogenous JavaScript array as a ReScript tuple too.
- Boolean.
- Record. Record compiles to a JavaScript object. Therefore you can also treat JavaScript objects as records. If they're too dynamic, consider modeling them on the ReScript side as a hashmap/dictionary [`Dict`](/docs/manual/api/stdlib/dict) or a ReScript object.
- Object. ReScript objects are JavaScript objects, vice-versa.
- Function. They compile to clean JavaScript functions.
- Module. ReScript files are considered top-level modules, and are compiled to JavaScript files 1 to 1. Nested modules are compiled to JavaScript objects.
- Polymorphic variants.
- Unit. The `unit` type, which has a single value `()`, compiles to `undefined` too. Likewise, you can treat an incoming `undefined` as `()` if that's the only value it'll ever be.

**Types that are slightly different, but that you can still use from JavaScript**:

- Int. **Ints are 32-bits**! Be careful, you can potentially treat them as JavaScript numbers and vice-versa, but if the number's large, then you better treat JavaScript numbers as floats. For example, we bind to `Date` using `float`s.
- Option. The `option` type's `None` value compiles into `undefined`. The `Some` value, e.g. `Some(5)`, compiles to `5`. Likewise, you can treat an incoming `undefined` as `None`. **`null` isn't handled here**. If your JavaScript value can be `null`, use [Nullable](/docs/manual/api/stdlib/nullable) helpers.
- Exception.
- Variant. Check the compiled JavaScript output of variant to see its shape. We don't recommend exporting a ReScript variant for pure JavaScript usage, since they're harder to read as plain JavaScript code, but you can do it.
- List, which is just a regular variant.

**Non-shared types (aka internal types)**:

- Character.
- Int64.
- Lazy values.
- Everything else.

Many of these are stable, which means that you can still serialize/deserialize them as-is without manual conversions. But we discourage actively peeking into their structure otherwise.

These types require manual conversions if you want to export them for JavaScript consumption. For a seamless JavaScript/TypeScript integration experience, check out the [TypeScript Integration](./typescript-integration.mdx) page instead of doing conversions by hand.

---
title: "Tagged templates"
description: "Using tagged templates in ReScript"
canonical: "/docs/manual/tagged-templates"
section: "Language Features"
order: 23
---

# Tagged templates

**Since 11.1**

Tagged templates provide a special form of string interpolation, enabling the creation of template literals
where placeholders aren't restricted to strings. Moreover, the resulting output isn't confined solely to
strings either. You can take a look at the [JS documentation
about tagged templates](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates)
to learn more about them.

## Define a tag function

Tag functions in ReScript have the following signature:

```res
let myTagFunction : (array<string>, array<'param>) => 'output
```

As you can see, you can have any type you want both for the placeholder array and for the output.

Given how string interpolation works, you'll always have the following invariant:

```res
Array.length(strings) == Array.length(placeholder) + 1
```

Let's say you want to interpolate strings with all kind of builtin types and make it work inside React components,
you can define the following tag function:

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

```res prelude
type params =
  | I(int)
  | F(float)
  | S(string)
  | Bool(bool)

let s = (strings, parameters) => {
  let text = Array.reduceWithIndex(parameters, Array.getUnsafe(strings, 0), (
    acc,
    param,
    i,
  ) => {
    let s = Array.getUnsafe(strings, i + 1)
    let p = switch param {
    | I(i) => Int.toString(i)
    | F(f) => Float.toString(f)
    | S(s) => s
    | Bool(true) => "true"
    | Bool(false) => "false"
    }
    acc ++ p ++ s
  })
  React.string(text)
}
```

```js
import * as Core__Array from "./stdlib/core__Array.js";

function s(strings, parameters) {
  return Core__Array.reduceWithIndex(
    parameters,
    strings[0],
    function (acc, param, i) {
      var s = strings[(i + 1) | 0];
      var p;
      switch (param.TAG) {
        case "I":
        case "F":
          p = param._0.toString();
          break;
        case "S":
          p = param._0;
          break;
        case "Bool":
          p = param._0 ? "true" : "false";
          break;
      }
      return acc + p + s;
    },
  );
}
```

</CodeTab>

## Write tagged template literals

Now that you have defined your tag function, you can use it this way:

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

```res example
module Greetings = {
  @react.component
  let make = (~name, ~age) => {
    <div> {s`hello ${S(name)} you're ${I(age)} year old!`} </div>
  }
}
```

```js
function Greetings(props) {
  return React.createElement(
    "div",
    undefined,
    s(
      ["hello ", " you're ", " year old!"],
      [
        {
          TAG: "S",
          _0: props.name,
        },
        {
          TAG: "I",
          _0: props.age,
        },
      ],
    ),
  );
}
```

</CodeTab>

Pretty neat, isn't it? As you can see, it looks like any regular template literal but it accepts placeholders that are not strings
and it outputs something that is not a string either, a `React.element` in this case.

---
title: "Try"
description: "Try ReScript via Command Line"
canonical: "/docs/manual/try"
---

## Try Online

Our [Playground](/try) lets you try ReScript online, and comes with the [ReScript React bindings](../react/introduction.mdx) and the new [ReScript Core](https://github.com/rescript-association/rescript-core) standard library preinstalled.

---
title: "Tuple"
description: "Tuple types and values in ReScript"
canonical: "/docs/manual/tuple"
section: "Language Features"
order: 5
---

# Tuple

Tuples are a ReScript-specific data structure that don't exist in JavaScript. They are:

- immutable
- ordered
- fix-sized at creation time
- heterogeneous (can contain different types of values)

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

```res example
let ageAndName = (24, "Lil' ReScript")
let my3dCoordinates = (20.0, 30.5, 100.0)
```

```js
var ageAndName = [24, "Lil' ReScript"];
var my3dCoordinates = [20.0, 30.5, 100.0];
```

</CodeTab>

Tuples' types can be used in type annotations as well. Tuple types visually resemble tuples values.

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

```res prelude
let ageAndName: (int, string) = (24, "Lil' ReScript")
// a tuple type alias
type coord3d = (float, float, float)
let my3dCoordinates: coord3d = (20.0, 30.5, 100.0)
```

```js
var ageAndName = [24, "Lil' ReScript"];
var my3dCoordinates = [20.0, 30.5, 100.0];
```

</CodeTab>

**Note**: there's no tuple of size 1. You'd just use the value itself.

## Usage

To get a specific member of a tuple, destructure it:

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

```res example
let (_, y, _) = my3dCoordinates // now you've retrieved y
```

```js
var y = 30.5;
```

</CodeTab>

The `_` means you're ignoring the indicated members of the tuple.

Tuples aren't meant to be updated mutatively. You'd create new ones by destructuring the old ones:

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

```res example
let coordinates1 = (10, 20, 30)
let (c1x, _, _) = coordinates1
let coordinates2 = (c1x + 50, 20, 30)
```

```js
var coordinates1 = [10, 20, 30];
var c1x = 10;
var coordinates2 = [60, 20, 30];
```

</CodeTab>

## Tips & Tricks

You'd use tuples in handy situations that pass around multiple values without too much ceremony. For example, to return many values:

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

```res
let getCenterCoordinates = () => {
  let x = doSomeOperationsHere()
  let y = doSomeMoreOperationsHere()
  (x, y)
}
```

```js
function getCenterCoordinates(param) {
  var x = doSomeOperationsHere(undefined);
  var y = doSomeMoreOperationsHere(undefined);
  return [x, y];
}
```

</CodeTab>

Try to keep the usage of tuple **local**. For data structures that are long-living and passed around often, prefer a **record**, which has named fields.

---
title: "Type"
description: "Types and type definitions in ReScript"
canonical: "/docs/manual/type"
section: "Language Features"
order: 3
---

# Type

Types are the highlight of ReScript! They are:

- **Strong**. A type can't change into another type. In JavaScript, your variable's type might change when the code runs (aka at runtime). E.g. a `number` variable might change into a `string` sometimes. This is an anti-feature; it makes the code much harder to understand when reading or debugging.
- **Static**. ReScript types are erased after compilation and don't exist at runtime. Never worry about your types dragging down performance. You don't need type info during runtime; we report all the information (especially all the type errors) during compile time. Catch the bugs earlier!
- **Sound**. This is our biggest differentiator versus many other typed languages that compile to JavaScript. Our type system is guaranteed to **never** be wrong. Most type systems make a guess at the type of a value and show you a type in your editor that's sometime incorrect. We don't do that. We believe that a type system that is sometime incorrect can end up being dangerous due to expectation mismatches.
- **Fast**. Many developers underestimate how much of their project's build time goes into type checking. Our type checker is one of the fastest around.
- **Inferred**. You don't have to write down the types! ReScript can deduce them from their values. Yes, it might seem magical that we can deduce all of your program's types, without incorrectness, without your manual annotation, and do so quickly. Welcome to ReScript =).

The following sections explore more of our type system.

## Inference

This let-binding doesn't contain any written type:

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

```res example
let score = 10
let add = (a, b) => a + b
```

```js
var score = 10;
function add(a, b) {
  return (a + b) | 0;
}
```

</CodeTab>

ReScript knows that `score` is an `int`, judging by the value `10`. This is called **inference**. Likewise, it also knows that the `add` function takes 2 `int`s and returns an `int`, judging from the `+` operator, which works on ints.

## Type Annotation

But you can also optionally write down the type, aka annotate your value:

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

```res example
let score: int = 10
```

```js
var score = 10;
```

</CodeTab>

If the type annotation for `score` doesn't correspond to our inferred type for it, we'll show you an error during compilation time. We **won't** silently assume your type annotation is correct, unlike many other languages.

You can also wrap any expression in parentheses and annotate it:

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

```res
let myInt = 5
let myInt: int = 5
let myInt = (5: int) + (4: int)
let add = (x: int, y: int) : int => x + y
let drawCircle = (~radius as r: int): circleType => /* code here */
```

```js
var myInt = 9;
function add(x, y) {
  return (x + y) | 0;
}
function drawCircle(r) {
  /* code here */
}
```

</CodeTab>

Note: in the last line, `(~radius as r: int)` is a labeled argument. More on this in the [function](./function.mdx) page.

## Type Alias

You can refer to a type by a different name. They'll be equivalent:

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

```res example
type scoreType = int
let x: scoreType = 10
```

```js
var x = 10;
```

</CodeTab>

## Type Parameter (Aka Generic)

Types can accept parameters, akin to generics in other languages. The parameters' names **need** to start with `'`.

The use-case of a parameterized type is to kill duplications. Before:

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

```res example
// this is a tuple of 3 items, explained next
type intCoordinates = (int, int, int)
type floatCoordinates = (float, float, float)

let a: intCoordinates = (10, 20, 20)
let b: floatCoordinates = (10.5, 20.5, 20.5)
```

```js
var a = [10, 20, 20];
var b = [10.5, 20.5, 20.5];
```

</CodeTab>

After:

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

```res example
type coordinates<'a> = ('a, 'a, 'a)

let a: coordinates<int> = (10, 20, 20)
let b: coordinates<float> = (10.5, 20.5, 20.5)
```

```js
var a = [10, 20, 20];
var b = [10.5, 20.5, 20.5];
```

</CodeTab>

Note that the above codes are just contrived examples for illustration purposes. Since the types are inferred, you could have just written:

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

```res example
let buddy = (10, 20, 20)
```

```js
var buddy = [10, 20, 20];
```

</CodeTab>

The type system infers that it's a `(int, int, int)`. Nothing else needed to be written down.

Type arguments appear in many places. Our `array<'a>` type is such a type that requires a type parameter.

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

```res example
// inferred as `array<string>`
let greetings = ["hello", "world", "how are you"]
```

```js
// inferred as `array<string>`
var greetings = ["hello", "world", "how are you"];
```

</CodeTab>

If types didn't accept parameters, the standard library would need to define the types `arrayOfString`, `arrayOfInt`, `arrayOfTuplesOfInt`, etc. That'd be tedious.

Types can receive many arguments, and be composable.

{/* TODO: too early for this example */}

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

```res example
type result<'a, 'b> =
  | Ok('a)
  | Error('b)

type myPayload = {data: string}

type myPayloadResults<'errorType> = array<result<myPayload, 'errorType>>

let payloadResults: myPayloadResults<string> = [
  Ok({data: "hi"}),
  Ok({data: "bye"}),
  Error("Something wrong happened!")
]
```

```js
var payloadResults = [
  {
    TAG: /* Ok */ 0,
    _0: { data: "hi" },
  },
  {
    TAG: /* Ok */ 0,
    _0: { data: "bye" },
  },
  {
    TAG: /* Error */ 1,
    _0: "Something wrong happened!",
  },
];
```

</CodeTab>

## Recursive Types

Just like a function, a type can reference itself within itself using `rec`:

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

```res example
type rec person = {
  name: string,
  friends: array<person>
}
```

```js
// Empty output
```

</CodeTab>

## Mutually Recursive Types

Types can also be _mutually_ recursive through `and`:

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

```res example
type rec student = {taughtBy: teacher}
and teacher = {students: array<student>}
```

```js
// Empty output
```

</CodeTab>

## Type Escape Hatch

ReScript's type system is robust and does not allow dangerous, unsafe stuff like implicit type casting, randomly guessing a value's type, etc. However, out of pragmatism, we expose a single escape hatch for you to "lie" to the type system:

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

```res
external myShadyConversion: myType1 => myType2 = "%identity"
```

```js
// Empty output
```

</CodeTab>

This declaration converts a `myType1` of your choice to `myType2` of your choice. You can use it like so:

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

```res example
external convertToFloat : int => float = "%identity"
let age = 10
let gpa = 2.1 + convertToFloat(age)
```

```js
var age = 10;
var gpa = 2.1 + 10;
```

</CodeTab>

Obviously, do **not** abuse this feature. Use it tastefully when you're working with existing, overly dynamic JS code, for example.

More on externals [here](./external.mdx).

**Note**: this particular `external` is the only one that isn't preceded by a `@` [attribute](./attribute.mdx).

---
title: "TypeScript"
description: "GenType - Interoperability between ReScript and TypeScript"
canonical: "/docs/manual/typescript-integration"
section: "JavaScript Interop"
order: 15
---

# ReScript & TypeScript

The ReScript compiler includes a code generation tool that lets you export ReScript values and types to use in TypeScript, and import TypeScript values and types into ReScript. It is called "genType".

The implementation of genType performs a type-directed transformation of ReScript programs after compilation. The transformed programs operate on data types idiomatic to TypeScript.

For example, a ReScript variant (which is represented as custom objects with tags at runtime):

```res
@genType
type t = | A(int) | B(string)
```

is exported to a TypeScript type:

```ts
type t = { TAG: "A"; _0: number } | { TAG: "B"; _0: string };
```

## A Quick Example

Let's assume we are working on a TypeScript codebase and we want to integrate a single ReScript function.

We want to be able to import the function like any other one in our existing TypeScript code, but we also want to preserve all the ReScript types in the TypeScript type system.

**That's exactly what genType was made for!**

First we'll set up a function:

```res
// src/Color.res

@genType
type color =
  | Red
  | Blue

@genType
let printColorMessage = (~color, ~message) => {
  let prefix = switch color {
  | Red => "\x1b[91m"
  | Blue => "\x1b[94m"
  }
  let reset = "\x1b[0m"

  Console.log(prefix ++ message ++ reset)
}

```

On a successful compile, `genType` will convert `src/Color.res` to a TypeScript file called `src/Color.gen.tsx` which will look something like this:

```ts
// src/Color.gen.tsx

/* TypeScript file generated from Color.res by genType. */

/* eslint-disable */
/* tslint:disable */

import * as ColorJS from "./Color.res.js";

export type color = "Red" | "Blue";

export const printColorMessage: (color: color) => void =
  ColorJS.printColorMessage as any;
```

genType automatically maps the `color` variant to TS via a string union type `"Red" | "Blue"`.

Within our TypeScript application, we can now import and use the function in the following manner:

```ts
// src/app.ts

import { printColorMessage } from "./Color.gen.tsx";

printColorMessage("Red", "Hello, genType!");
```

## Exporting an entire module

_Since ReScript `11.0.0`_ modules can be annotated with `@genType` as well. In that case, all types and values of the module will be converted to TS types. Example:

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

```res example
@genType
module Size = {
  type t =
    | Small
    | Medium
    | Large

  let getNum = (size: t) =>
    switch size {
    | Small => 1.
    | Medium => 5.
    | Large => 10.
    }
}
```

```ts
import * as MyCompBS__Es6Import from "./MyComp.res";
const MyCompBS: any = MyCompBS__Es6Import;

export type Size_t = "Small" | "Medium" | "Large";

export const Size_getNum: (size: Size_t) => number = MyCompBS.Size.getNum;

export const Size: { getNum: (size: Size_t) => number } = MyCompBS.Size;
```

</CodeTab>

## Setup

Add a `gentypeconfig` section to your `rescript.json` (See [Configuration](./build-configuration.mdx#gentypeconfig) for details).

Every `genType` powered project requires a configuration item `"gentypeconfig"` at top level in the project's `rescript.json`.

The minimal configuration of genType is following:

```json
{
  "gentypeconfig": {
    "module": "esmodule",
    "moduleResolution": "node",
    "generatedFileExtension": ".gen.tsx"
  }
}
```

And don't forget to make sure `allowJs` is set to `true` in the project's `tsconfig.json`:

```json
{
  "compilerOptions": {
    "allowJs": true
  }
}
```

### TypeScript Module Resolutions

Make sure to set the same `moduleResolution` value in both `rescript.json` and `tsconfig.json`, so that the output of genType is done with the preferred module resolution.

For example if the TypeScript project uses JavaScript modules with `Node16` / `NodeNext` module resolution:

```json
// tsconfig.json
{
  "compilerOptions": {
    "moduleResolution": "node16"
  }
}
```

Then `moduleResolution` in `gentypeconfig` should be same value:

```json
// rescript.json
{
  "gentypeconfig": {
    "moduleResolution": "node16"
  }
}
```

In case of the TypeScript project using `Bundler` module resolution, `allowImportingTsExtensions` should also be `true`:

```json
// tsconfig.json
{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true
  }
}
```

```json
// rescript.json
{
  "gentypeconfig": {
    "moduleResolution": "bundler"
  }
}
```

## Testing the Whole Setup

Open any relevant `*.res` file and add `@genType` annotations to any bindings / values / functions to be used from JavaScript. If an annotated value uses a type, the type must be annotated too. See e.g. [Hooks.res](https://github.com/rescript-lang/rescript-compiler/blob/master/jscomp/gentype_tests/typescript-react-example/src/Hooks.res).

Save the file and rebuild the project via `npm run build:res` or similar. You should now see a `*.gen.tsx` file with the same name (e.g. `MyComponent.res` -> `MyComponent.gen.tsx`).

Any values exported from `MyComponent.res` can then be imported from TypeScript. For example:

```js
import MyComponent from "./components/MyComponent.gen.tsx";
```

## Experimental features

These features are for experimentation only. They could be changed/removed any time, and not be considered breaking changes.

- Export object and record types as interfaces. To activate, add `"exportInterfaces": true` to the configuration. The types are also renamed from `name` to `Iname`.

## Shims

A shim is a TS file that provides user-provided definitions for library types.

Required only if one needs to export certain basic ReScript data types to JS when one cannot modify the sources to add annotations (e.g. exporting ReScript lists), and if the types are not first-classed in genType.

- Example: `Array<string>` with format: `"RescriptModule=JavaScriptModule"`

Configure your shim files within `"gentypeconfig"` in your [`rescript.json`]:

```json
{
  "gentypeconfig": {
    "shims": {
      "Js": "Js",
      "ReactEvent": "ReactEvent",
      "RescriptPervasives": "RescriptPervasives",
      "ReasonReact": "ReactShim"
    }
  }
}
```

and add relevant `.shim.ts` files in a directory which is visible by ReScript e.g.

```
├── rescript.json
├── src
│   ├── shims
│   │   ├── Js.shim.ts
│   │   ├── ReactEvent.shim.ts
│   │   └── RescriptPervasives.shim.ts
```

Here are some examples:

```ts
// Excerpt from https://github.com/rescript-lang/rescript-compiler/blob/master/jscomp/gentype_tests/typescript-react-example/src/shims/Js.shim.ts
export type Json_t = unknown;
export type t = unknown;
```

```ts
// Excerpt from https://github.com/rescript-lang/rescript-compiler/tree/master/jscomp/gentype_tests/typescript-react-example/src/shims
export type inputFocusEvent = React.FocusEvent<HTMLInputElement>;
```

More complete example shims can be found [here](https://github.com/rescript-lang/rescript-compiler/blob/master/jscomp/gentype_tests/typescript-react-example/src/shims/).

## Deprecated features

Features related to generating runtimes were deprecated since v11 and should no longer be used.

- **`@genType("alias")`** and **`@genType.as("alias")`**
- **`@genType.opaque`**
- **`@genType.import`**
- TypeScript Shims

genType does not generate anything runtime-related, and in the near future it generates definition files (`*.d.ts`) directly (See the [roadmap](https://github.com/rescript-lang/rescript-compiler/issues/6196)).

If any runtime code is required for interoperability with JavaScript / TypeScript projects, it can be written by hand, or request a relevant features (e.g. `@deriving`) to the compiler.

## Limitations

- **in-source = true**. Currently only supports ReScript projects with [in-source generation](./build-configuration.mdx#package-specs) and file suffixes that end on `.js`, like `.res.js` or `.bs.js`.

- **Limited namespace support**. Currently there's limited [namespace](./build-configuration.mdx#name-namespace) support, and only `namespace:true` is possible, not e.g. `namespace:"custom"`.

---
title: "Use Illegal Identifier Names"
description: "Handling (JS) naming collisions in ReScript"
canonical: "/docs/manual/use-illegal-identifier-names"
section: "JavaScript Interop"
order: 11
---

# Use Illegal Identifier Names

Sometime, for e.g. a let binding or a record field, you might want to use:

- A capitalized name.
- A name that contains illegal characters (e.g. emojis, hyphen, space).
- A name that's one of ReScript's reserved keywords.

We provide an escape hatch syntax for these cases:

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

```res example
let \"my-🍎" = 10

type element = {
  \"aria-label": string
}

let myElement = {
  \"aria-label": "close"
}

let label = myElement.\"aria-label"

let calculate = (~\"Props") => {
  \"Props" + 1
}
```

```js
var my$$unknown$unknown$unknown$unknown = 10;

var myElement = {
  "aria-label": "close",
};

var label = myElement["aria-label"];

function calculate(Props) {
  return (Props + 1) | 0;
}
```

</CodeTab>

See the output. **Use them only when necessary**, for interop with JavaScript. This is a last-resort feature. If you abuse this, many of the compiler guarantees will go away.

---
title: "Variant"
description: "Variant data structures in ReScript"
canonical: "/docs/manual/variant"
section: "Language Features"
order: 9
---

# Variant

So far, most of ReScript's data structures might look familiar to you. This section introduces an extremely important, and perhaps unfamiliar, data structure: variant.

Most data structures in most languages are about "this **and** that". A variant allows us to express "this **or** that".

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

```res example
type myResponse =
  | Yes
  | No
  | PrettyMuch

let areYouCrushingIt = Yes
```

```js
var areYouCrushingIt = "Yes";
```

</CodeTab>

`myResponse` is a variant type with the cases `Yes`, `No` and `PrettyMuch`, which are called "variant constructors" (or "variant tag"). The `|` bar separates each constructor.

**Note**: a variant's constructors need to be capitalized.

## Variant Needs an Explicit Definition

If the variant you're using is in a different file, bring it into scope [record](./record.mdx) type

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

```res example
// Zoo.res
type animal = Dog | Cat | Bird
```

```js
// Empty output
```

</CodeTab>

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

```res
// Example.res
let pet: Zoo.animal = Dog // preferred
// or
let pet2 = Zoo.Dog
```

```js
var pet = "Dog";
var pet2 = "Dog";
```

</CodeTab>

## Constructor Arguments

A variant's constructors can hold extra data separated by comma.

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

```res prelude
type account =
  | None
  | Instagram(string)
  | Facebook(string, int)
```

```js
// Empty output
```

</CodeTab>

Here, `Instagram` holds a `string`, and `Facebook` holds a `string` and an `int`. Usage:

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

```res example
let myAccount = Facebook("Josh", 26)
let friendAccount = Instagram("Jenny")
```

```js
var myAccount = {
  TAG: "Facebook",
  _0: "Josh",
  _1: 26,
};
var friendAccount = {
  TAG: "Instagram",
  _0: "Jenny",
};
```

</CodeTab>

### Labeled Variant Payloads (Inline Record)

If a variant payload has multiple fields, you can use a record-like syntax to label them for better readability:

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

```res example
type user =
  | Number(int)
  | Id({name: string, password: string})

let me = Id({name: "Joe", password: "123"})
```

```js
var me = {
  TAG: "Id",
  name: "Joe",
  password: "123",
};
```

</CodeTab>

This is technically called an "inline record", and only allowed within a variant constructor. You cannot inline a record type declaration anywhere else in ReScript.

Of course, you can just put a regular record type in a variant too:

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

```res example
type u = {name: string, password: string}
type user =
  | Number(int)
  | Id(u)

let me = Id({name: "Joe", password: "123"})
```

```js
var me = {
  TAG: "Id",
  _0: {
    name: "Joe",
    password: "123",
  },
};
```

</CodeTab>

The output is slightly uglier and less performant than the former.

## Variant Type Spreads

Just like [with records](./record.mdx#record-type-spread), it's possible to use type spreads to create new variants from other variants:

```rescript
type a = One | Two | Three
type b = | ...a | Four | Five
```

Type `b` is now:

```rescript
type b = One | Two | Three | Four | Five
```

Type spreads act as a 'copy-paste', meaning all constructors are copied as-is from `a` to `b`. Here are the rules for spreads to work:

- You can't overwrite constructors, so the same constructor name can exist in only one place as you spread. This is true even if the constructors are identical.
- All variants and constructors must share the same runtime configuration - `@unboxed`, `@tag`, `@as` and so on.
- You can't spread types in recursive definitions.

Note that you need a leading `|` if you want to use a spread in the first position of a variant definition.

### Pattern Matching On Variant

See the [Pattern Matching/Destructuring](./pattern-matching-destructuring.mdx) section later.

## JavaScript Output

A variant value compiles to 3 possible JavaScript outputs depending on its type declaration:

- If the variant value is a constructor with no payload, it compiles to a string of the constructor name. Example: `Yes` compiles to `"Yes"`.
- If it's a constructor with a payload, it compiles to an object with the field `TAG` and the field `_0` for the first payload, `_1` for the second payload, etc. The value of `TAG` is the constructor name as string by default, but note that the name of the `TAG` field as well as the string value used for each constructor name [can be customized](#tagged-variants).
- Labeled variant payloads (the inline record trick earlier) compile to an object with the label names instead of `_0`, `_1`, etc. The object will have the `TAG` field as per the previous rule.

Check the output in these examples:

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

```res example
type greeting = Hello | Goodbye
let g1 = Hello
let g2 = Goodbye

type outcome = Good | Error(string)
let o1 = Good
let o2 = Error("oops!")

type family = Child | Mom(int, string) | Dad (int)
let f1 = Child
let f2 = Mom(30, "Jane")
let f3 = Dad(32)

type person = Teacher | Student({gpa: float})
let p1 = Teacher
let p2 = Student({gpa: 99.5})

type s = {score: float}
type adventurer = Warrior(s) | Wizard(string)
let a1 = Warrior({score: 10.5})
let a2 = Wizard("Joe")
```

```js
var g1 = "Hello";

var g2 = "Goodbye";

var o1 = "Good";

var o2 = {
  TAG: "Error",
  _0: "oops!",
};

var f1 = "Child";

var f2 = {
  TAG: "Mom",
  _0: 30,
  _1: "Jane",
};

var f3 = {
  TAG: "Dad",
  _0: 32,
};

var p1 = "Teacher";

var p2 = {
  TAG: "Student",
  gpa: 99.5,
};

var a1 = {
  TAG: "Warrior",
  _0: {
    score: 10.5,
  },
};

var a2 = {
  TAG: "Wizard",
  _0: "Joe",
};
```

</CodeTab>

## Tagged variants

- The `@tag` attribute lets you customize the discriminator (default: `TAG`).
- `@as` attributes control what each variant case is discriminated on (default: the variant case name as string).

### Example: Binding to TypeScript enums

```typescript
// direction.ts
/** Direction of the action. */
enum Direction {
  /** The direction is up. */
  Up = "UP",

  /** The direction is down. */
  Down = "DOWN",

  /** The direction is left. */
  Left = "LEFT",

  /** The direction is right. */
  Right = "RIGHT",
}

export const myDirection = Direction.Up;
```

You can bind to the above enums like so:

```rescript
/** Direction of the action. */
type direction =
  | /** The direction is up. */
  @as("UP")
  Up

  | /** The direction is down. */
  @as("DOWN")
  Down

  | /** The direction is left. */
  @as("LEFT")
  Left

  | /** The direction is right. */
  @as("RIGHT")
  Right

@module("./direction.js") external myDirection: direction = "myDirection"
```

Now, this maps 100% to the TypeScript code, including letting us bring over the documentation strings so we get a nice editor experience.

### String literals

The same logic is easily applied to string literals from TypeScript, only here the benefit is even larger, because string literals have the same limitations in TypeScript that polymorphic variants have in ReScript:

```typescript
// direction.ts
type direction = "UP" | "DOWN" | "LEFT" | "RIGHT";
```

There's no way to attach documentation strings to string literals in TypeScript, and you only get the actual value to interact with.

### Valid `@as` payloads

Here's a list of everything you can put in the `@as` tag of a variant constructor:

- A string literal: `@as("success")`
- An int: `@as(5)`
- A float: `@as(1.5)`
- True/false: `@as(true)` and `@as(false)`
- Null: `@as(null)`
- Undefined: `@as(undefined)`

## Untagged variants

With _untagged variants_ it is possible to mix types together that normally can't be mixed in the ReScript type system, as long as there's a way to discriminate them at runtime. For example, with untagged variants you can represent a heterogenous array:

```rescript
@unboxed type listItemValue = String(string) | Boolean(bool) | Number(float)

let myArray = [String("Hello"), Boolean(true), Boolean(false), Number(13.37)]
```

Here, each value will be _unboxed_ at runtime. That means that the variant payload will be all that's left, the variant case name wrapping the payload itself will be stripped out and the payload will be all that remains.

It, therefore, compiles to this JS:

```javascript
var myArray = ["hello", true, false, 13.37];
```

In the above example, reaching back into the values is as simple as pattern matching on them.

### Advanced: Unboxing rules

#### No overlap in constructors

A variant can be unboxed if no constructors have overlap in their runtime representation.

For example, you can't have `String1(string) | String2(string)` in the same unboxed variant, because there's no way for ReScript to know at runtime which of `String1` or `String2` that `string` belongs to, as it could belong to both.
The same goes for two records - even if they have fully different shapes, they're still JavaScript `object` at runtime.

Don't worry - the compiler will guide you and ensure there's no overlap.

#### What you can unbox

Here's a list of all possible things you can unbox:

- `string`: `String(string)`
- `float`: `Float(float)`. Note you can only have one of `float` or `int` because JavaScript only has `number` (not actually `int` and `float` like in ReScript) so we can't disambiguate between `float` and `int` at runtime.
- `int`: `Int(int)`. See note above on `float`.
- `bigint`: `BigInt(int)`. **Since 11.1** This is a distinct type from JavaScript's `number` type so you can use it beside either `float` or `int`.
- `bool`: `Boolean(bool)`
- `array<'value>`: `List(array<string>)`
- `('a, 'b, 'c)`: `Tuple((string, int, bool))`. Any size of tuples works, but you can have only one case of array or tuple in a variant.
- `promise<'value>`: `Promise(promise<string>)`
- `Dict.t`: `Object(Dict.t<string>)`
- `Date.t`: `Date(Date.t)`. A JavaScript date.
- `Blob.t`: `Blob(Blob.t)`. A JavaScript blob.
- `File.t`: `File(File.t)`. A JavaScript file.
- `RegExp.t`: `RegExp(RegExp.t)`. A JavaScript regexp instance.

Again notice that the constructor names can be anything, what matters is what's in the payload.

> **Under the hood**: Untagged variants uses a combination of JavaScript `typeof` and `instanceof` checks to discern between unboxed constructors at runtime. This means that we could add more things to the list above detailing what can be unboxed, if there are useful enough use cases.

### Pattern matching on unboxed variants

Pattern matching works the same on unboxed variants as it does on regular variants. In fact, in the perspective of ReScript's type system there's no difference between untagged and tagged variants. You can do virtually the same things with both. That's the beauty of untagged variants - they're just variants to you as a developer.

Here's an example of pattern matching on an unboxed nullable value that illustrates the above:

```rescript
module Null = {
  @unboxed type t<'a> = Present('a) | @as(null) Null
}

type userAge = {ageNum: Null.t<int>}

type rec user = {
  name: string,
  age: Null.t<userAge>,
  bestFriend: Null.t<user>,
}

let getBestFriendsAge = user =>
  switch user.bestFriend {
  | Present({age: Present({ageNum: Present(ageNum)})}) => Some(ageNum)
  | _ => None
  }
```

No difference to how you'd do with a regular variant. But, the runtime representation is different to a regular variant.

> Notice how `@as` allows us to say that an untagged variant case should map to a specific underlying _primitive_. `Present` has a type variable, so it can hold any type. And since it's an unboxed type, only the payloads `'a` or `null` will be kept at runtime. That's where the magic comes from.

### Decoding and encoding JSON idiomatically

With untagged variants, we have everything we need to define a native JSON type:

```rescript
@unboxed
type rec json =
  | @as(null) Null
  | Boolean(bool)
  | String(string)
  | Number(float)
  | Object(Dict.t<json>)
  | Array(array<json>)

let myValidJsonValue = Array([String("Hi"), Number(123.)])
```

Here's an example of how you could write your own JSON decoders easily using the above, leveraging pattern matching:

```rescript
@unboxed
type rec json =
  | @as(null) Null
  | Boolean(bool)
  | String(string)
  | Number(float)
  | Object(Dict.t<json>)
  | Array(array<json>)

type rec user = {
  name: string,
  age: int,
  bestFriend: option<user>,
}

let rec decodeUser = json =>
  switch json {
  | Object(userDict) =>
    switch (
      userDict->Dict.get("name"),
      userDict->Dict.get("age"),
      userDict->Dict.get("bestFriend"),
    ) {
    | (Some(String(name)), Some(Number(age)), Some(maybeBestFriend)) =>
      Some({
        name,
        age: age->Float.toInt,
        bestFriend: maybeBestFriend->decodeUser,
      })
    | _ => None
    }
  | _ => None
  }

let decodeUsers = json =>
  switch json {
  | Array(array) => array->Array.map(decodeUser)->Array.keepSome
  | _ => []
  }
```

Encoding that same structure back into JSON is also easy:

```rescript
let rec userToJson = user => Object(
  Dict.fromArray([
    ("name", String(user.name)),
    ("age", Number(user.age->Int.toFloat)),
    (
      "bestFriend",
      switch user.bestFriend {
      | None => Null
      | Some(friend) => userToJson(friend)
      },
    ),
  ]),
)

let usersToJson = users => Array(users->Array.map(userToJson))
```

This can be extrapolated to many more cases.

### Advanced: Catch-all Constructors

With untagged variants comes a rather interesting capability - catch-all cases are now possible to encode directly into a variant.

Let's look at how it works. Imagine you're using a third party API that returns a list of available animals. You could of course model it as a regular `string`, but given that variants can be used as "typed strings", using a variant would give you much more benefit:

<CodeTab labels={["ReScript", "JS Output"]}>
```rescript
type animal = Dog | Cat | Bird

type apiResponse = {
animal: animal
}

let greetAnimal = (animal: animal) =>
switch animal {
| Dog => "Wof"
| Cat => "Meow"
| Bird => "Kashiiin"
}

````
```javascript
````

</CodeTab>

This is all fine and good as long as the API returns `"Dog"`, `"Cat"` or `"Bird"` for `animal`.
However, what if the API changes before you have a chance to deploy new code, and can now return `"Turtle"` as well? Your code would break down because the variant `animal` doesn't cover `"Turtle"`.

So, we'll need to go back to `string`, loosing all of the goodies of using a variant, and then do manual conversion into the `animal` variant from `string`, right?
Well, this used to be the case before, but not anymore! We can leverage untagged variants to bake in handling of unknown values into the variant itself.

Let's update our type definition first:

```rescript
@unboxed
type animal = Dog | Cat | Bird | UnknownAnimal(string)
```

Notice we've added `@unboxed` and the constructor `UnknownAnimal(string)`. Remember how untagged variants work? You remove the constructors and just leave the payloads. This means that the variant above at runtime translates to this (made up) JavaScript type:

```
type animal = "Dog" | "Cat" | "Bird" | string
```

So, any string not mapping directly to one of the payloadless constructors will now map to the general `string` case.

As soon as we've added this, the compiler complains that we now need to handle this additional case in our pattern match as well. Let's fix that:

<CodeTab labels={["ReScript", "JS Output"]}>
```rescript
@unboxed
type animal = Dog | Cat | Bird | UnknownAnimal(string)

type apiResponse = {
animal: animal
}

let greetAnimal = (animal: animal) =>
switch animal {
| Dog => "Wof"
| Cat => "Meow"
| Bird => "Kashiiin"
| UnknownAnimal(otherAnimal) =>
`I don't know how to greet animal ${otherAnimal}`
}

````
```javascript
function greetAnimal(animal) {
  if (!(animal === "Cat" || animal === "Dog" || animal === "Bird")) {
    return "I don't know how to greet animal " + animal;
  }
  switch (animal) {
    case "Dog" :
        return "Wof";
    case "Cat" :
        return "Meow";
    case "Bird" :
        return "Kashiiin";

  }
}
````

</CodeTab>

There! Now the external API can change as much as it wants, we'll be forced to write all code that interfaces with `animal` in a safe way that handles all possible cases. All of this baked into the variant definition itself, so no need for labor intensive manual conversion.

This is useful in any scenario when you use something enum-style that's external and might change. Additionally, it's also useful when something external has a large number of possible values that are known, but where you only care about a subset of them. With a catch-all case you don't need to bind to all of them just because they can happen, you can safely just bind to the ones you care about and let the catch-all case handle the rest.

## Coercion

In certain situations, variants can be coerced to other variants, or to and from primitives. Coercion is always zero cost.

### Coercing Variants to Other Variants

You can coerce a variant to another variant if they're identical in runtime representation, and additionally if the variant you're coercing can be represented as the variant you're coercing to.

Here's an example using [variant type spreads](#variant-type-spreads):

```rescript
type a = One | Two | Three
type b = | ...a | Four | Five

let one: a = One
let four: b = Four

// This works because type `b` can always represent type `a` since all of type `a`'s constructors are spread into type `b`
let oneAsTypeB = (one :> b)
```

### Coercing Variants to Primitives

Variants that are guaranteed to always be represented by a single primitive at runtime can be coerced to that primitive.

It works with strings, the default runtime representation of payloadless constructors:

```rescript
// Constructors without payloads are represented as `string` by default
type a = One | Two | Three

let one: a = One

// All constructors are strings at runtime, so you can safely coerce it to a string
let oneAsString = (one :> string)
```

If you were to configure all of your construtors to be represented as `int` or `float`, you could coerce to those too:

```rescript
type asInt = | @as(1) One | @as(2) Two | @as(3) Three

let oneInt: asInt = One
let toInt = (oneInt :> int)
```

### Advanced: Coercing `string` to Variant

In certain situtations it's possible to coerce a `string` to a variant. This is an advanced technique that you're unlikely to need much, but when you do it's really useful.

You can coerce a `string` to a variant when:

- Your variant is `@unboxed`
- Your variant has a "catch-all" `string` case

Let's look at an example:

```rescript
@unboxed
type myEnum = One | Two | Other(string)

// Other("Other thing")
let asMyEnum = ("Other thing" :> myEnum)

// One
let asMyEnum = ("One" :> myEnum)
```

This works because the variant is unboxed **and** has a catch-all case. So, if you throw a string at this variant that's not representable by the payloadless constructors, like `"One"` or `"Two"`, it'll _always_ end up in `Other(string)`, since that case can represent any `string`.

## Tips & Tricks

**Be careful** not to confuse a constructor carrying 2 arguments with a constructor carrying a single tuple argument:

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

```res example
type account =
  | Facebook(string, int) // 2 arguments
type account2 =
  | Instagram((string, int)) // 1 argument - happens to be a 2-tuple
```

```js
// Empty output
```

</CodeTab>

### Variants Must Have Constructors

If you come from an untyped language, you might be tempted to try `type myType = int | string`. This isn't possible in ReScript; you'd have to give each branch a constructor: `type myType = Int(int) | String(string)`. The former looks nice, but causes lots of trouble down the line.

### Interop with JavaScript

_This section assumes knowledge about our JavaScript interop. Skip this if you haven't felt the itch to use variants for wrapping JS functions yet_.

Quite a few JS libraries use functions that can accept many types of arguments. In these cases, it's very tempting to model them as variants. For example, suppose there's a `myLibrary.draw` JS function that takes in either a `number` or a `string`. You might be tempted to bind it like so:

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

```res example
// reserved for internal usage
@module("myLibrary") external draw : 'a => unit = "draw"

type animal =
  | MyFloat(float)
  | MyString(string)

let betterDraw = (animal) =>
  switch animal {
  | MyFloat(f) => draw(f)
  | MyString(s) => draw(s)
  }

betterDraw(MyFloat(1.5))
```

```js
var MyLibrary = require("myLibrary");

function betterDraw(animal) {
  MyLibrary.draw(animal._0);
}

betterDraw({
  TAG: "MyFloat",
  _0: 1.5,
});
```

</CodeTab>

**Try not to do that**, as this generates extra noisy output. Instead, use the `@unboxed` attribute to guide ReScript to generate more efficient code:

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

```res example
// reserved for internal usage
@module("myLibrary") external draw : 'a => unit = "draw"

@unboxed
type animal =
  | MyFloat(float)
  | MyString(string)

let betterDraw = (animal) =>
  switch animal {
  | MyFloat(f) => draw(f)
  | MyString(s) => draw(s)
  }

betterDraw(MyFloat(1.5))
```

```js
var MyLibrary = require("myLibrary");

function betterDraw(animal) {
  MyLibrary.draw(animal);
}

MyLibrary.draw(1.5);
```

</CodeTab>

Alternatively, define two `external`s that both compile to the same JS call:

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

```res example
@module("myLibrary") external drawFloat: float => unit = "draw"
@module("myLibrary") external drawString: string => unit = "draw"
```

```js
// Empty output
```

</CodeTab>

ReScript also provides [a few other ways](./bind-to-js-function.mdx#modeling-polymorphic-function) to do this.

### Variant Types Are Found By Field Name

Please refer to this [record section](./record.mdx#tips--tricks). Variants are the same: a function can't accept an arbitrary constructor shared by two different variants. Again, such feature exists; it's called a polymorphic variant. We'll talk about this in the future =).

## Design Decisions

Variants, in their many forms (polymorphic variant, open variant, GADT, etc.), are likely _the_ feature of a type system such as ReScript's. The aforementioned `option` variant, for example, obliterates the need for nullable types, a major source of bugs in other languages. Philosophically speaking, a problem is composed of many possible branches/conditions. Mishandling these conditions is the majority of what we call bugs. **A type system doesn't magically eliminate bugs; it points out the unhandled conditions and asks you to cover them**\*. The ability to model "this or that" correctly is crucial.

For example, some folks wonder how the type system can safely eliminate badly formatted JSON data from propagating into their program. They don't, not by themselves! But if the parser returns the `option` type `None | Some(actualData)`, then you'd have to handle the `None` case explicitly in later call sites. That's all there is.

Performance-wise, a variant can potentially tremendously speed up your program's logic. Here's a piece of JavaScript:

```js
let data = 'dog'
function logData(data) {
  if (data === 'dog') {
    ...
  } else if (data === 'cat') {
    ...
  } else if (data === 'bird') {
    ...
  }
}
logData(data)
```

There's a linear amount of branch checking here (`O(n)`). Compare this to using a ReScript variant:

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

```res example
type animal = Dog | Cat | Bird
let data = Dog
let logData = data => {
  switch data {
  | Dog => Console.log("Wof")
  | Cat => Console.log("Meow")
  | Bird => Console.log("Kashiiin")
  }
}
logData(data)

```

```js
function logData(data) {
  switch (data) {
    case "Dog":
      console.log("Wof");
      return;
    case "Cat":
      console.log("Meow");
      return;
    case "Bird":
      console.log("Kashiiin");
      return;
  }
}

logData("Dog");
```

</CodeTab>

The compiler sees the variant, then

1. conceptually turns them into `type animal = "Dog" | "Cat" | "Bird"`
2. compiles `switch` to a constant-time jump table (`O(1)`).

---
title: "Warning Numbers"
description: "Available compiler warning numbers in ReScript"
canonical: "/docs/manual/warning-numbers"
section: "Build System"
order: 8
---

# Warning Numbers

You can configure which warnings the ReScript compiler generates
[in the build configuration](./build-configuration.mdx#warnings) or
using the [`@warning()`](../../syntax-lookup/decorator_expression_warning.mdx) or the [`@@warning()`](../../syntax-lookup/decorator_module_warning.mdx) decorator.

<WarningTable />