# API Reference

This API reference will give you specific details on how to use each function. It's intended that you've read through [The Big Picture](/explicit-exceptions/master.md) first, to give you a grasp of how these functions work together.

### wrap(fnToWrap, allowedExceptionTypes = null)

Decorates the provided `fnToWrap`, such that the wrapper will always return a maybe type, whether or not the wrapped function threw an exception or returned a value. It is intended that the users of this wrapped function use `unwrap()` to retrieve the original returned value

**Parameters:**

* `fnToWrap` The function to be wrapped. if `fnToWrap` is async, `wrapAsync()` should be used instead to properly wrap the entire async body.
* `allowedExceptionTypes` Optional list of exceptions this function may propagate. Defaults to allowing all. Any thrown exception not found in this list will be escalated (i.e. an instance of Error will be thrown instead, explaining what happened).

**returns:** A maybe type, intended to be unwrapped with `unwrap()`

The maybe instance returned by a `wrap()` function *must* at some point be unwrapped by the `unwrap()` function. It is considered a bug if the return value is ignored. If you wish to ignore the return value of a wrapped function and escalate any exceptions it provides, you must do so explicitly with the unwrap call, like this `unwrap(someWrappedFn(), [])`, or more simply `unwrap(someWrappedFn())`.

The `allowedExceptionTypes` list is intended to be used by those who wish to provide self-documentation of the types of exceptions a function may throw, without requiring the user to look through the body of the function. For example:

```javascript
const getEntry = wrap(id => {
  if (!data.has(id)) {
    // Throws our custom Exception instance, with the intention that
    // our caller would be able to catch and handle this.
    throw new Exception('NotFound')
  }
  return data.get(id)
}, ['NotFound'])
```

In the above example, you can know that `getEntry()` will only provide the `NotFound` exception, because any other exceptions would have been escalated, as they were not found in the `allowedExceptionTypes` list.

If an unhandled maybe instance gets garbage collected, a warning will be logged informing you of the forgotten `unwrap()` call. Note that you can't depend on these warnings to show up - depending on the javascript implementation and how large your program is, it's possible that the garbage collector doesn't even run during the lifetime of your program. In node, to help debug issues and force these warnings to show up, you can force-schedule the garbage collector to run by starting node with the `--expose-gc` flag, then calling the now-available global `gc()` function.

### wrapAsync(fnToWrap, allowedExceptionTypes = null)

Same as `wrap()`, except it expects `fnToWrap()` to return a promise. The entire promise will be wrapped, and `wrapAsync()` itself will return a promise that resolves into a `Maybe` type.

### unwrap(maybeValue, allowedExceptionTypes = \[])

Unwraps a maybe type. One of three possible scenarios will happen:

* If the maybe type contains an "ok" value, its content will be returned.
* If the maybe type contains an exception whose code is found in `allowedExceptionTypes`, the exception will be rethrown.
* If the maybe type contains an exception whose code is not found in `allowedExceptionTypes`, the exception will be escalated (meaning, a new `Error()` instance will be thrown, explaining that this specific exception was unhandled).

### new Exception(code, message = null, data = null)

Creates a new `Exception` instance, that's meant to be thrown within a wrapped function. Never throw it outside of a wrapped function - this goes against the entire philosophy of explicit-exceptions. In the future, we may provide linter rules to help enforce this.

An `Exception` is a subclass of an `Error`, which means it'll contain an error message and stack trace, just like a normal error.

**Parameters:**

* `code` Gets set as the "code" property on the exception instance. Can be used to programmatically distinguish one exception from another. Other functions provided by explicit-exceptions will use this property for this exact purpose.
* `message` (optional) Both the code and the optional message value will be used together to create the "message" property of the exception. This message property will be used to provide additional debugging information if the exception escalates to a fatal error.
* `data` (optional) Any arbitrary data that you wish to attach to the exception instance (under the "data" property).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://thescottyjam.gitbook.io/explicit-exceptions/api-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.