Exception

Exceptions are just a special kind of variant, thrown in exceptional cases (don't abuse them!). Consider using the option or result type for recoverable errors.

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

exception InputClosed(string)
// later on
raise(InputClosed("The stream has closed!"))

Built-in Exceptions

ReScript has some built-in exceptions:

Not_found

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

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

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:

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

Invalid_argument

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

let divide = (a, b) =>
  if b == 0 {
    raise(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
}

Assert_failure

Raise 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).

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)
}

Failure

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

let isValidEmail = email => {
  let hasAtSign = String.includes(email, "@")
  let hasDot = String.includes(email, ".")
  if !(hasAtSign && hasDot) {
    raise(Failure("Invalid email address"))
  } else {
    true
  }
}

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

Division_by_zero

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

// ReScript raise `Division_by_zero` if the denominator is zero
let result = try Some(10 / 0) catch {
| Division_by_zero => None
}

Console.log(result) // None

Catching JS Exceptions

To distinguish between JavaScript exceptions and ReScript exceptions, ReScript namespaces JS exceptions under the Exn.Error(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 {
| Exn.Error(obj) =>
  switch Exn.message(obj) {
  | Some(m) => Console.log("Caught a JS exception! Message: " ++ m)
  | None => ()
  }
}

The obj here is of type Exn.t, intentionally opaque to disallow illegal operations. To operate on obj, do like the code above by using the standard library's Exn module's helpers.

Raise a JS Exception

raise(MyException) raises a ReScript exception. To raise a JavaScript exception (whatever your purpose is), use Exn.raiseError:

let myTest = () => {
  Exn.raiseError("Hello!")
}

Then you can catch it from the JS side:

JS
// after importing `myTest`...
try {
  myTest();
} catch (e) {
  console.log(e.message); // "Hello!"
}

Catch ReScript Exceptions from JS

The previous section is less useful than you think; to let your JS code work with your exception-throwing ReScript code, the latter doesn't actually need to throw a JS exception. ReScript exceptions can be used by JS code!

exception BadArgument({myMessage: string})

let myTest = () => {
  raise(BadArgument({myMessage: "Oops!"}))
}

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
}

Note: RE_EXN_ID is an internal field for bookkeeping purposes. Don't use it on the JS side. Use the other fields.

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
| Exn.Error(obj) => ... // catch the JS exception
}

This technically works, but hopefully you don't ever have to work with such code...