NeverThrow 🙅

Description

Encode failure into your program.

This package contains a Result type that represents either success (Ok) or failure (Err).

For asynchronous tasks, neverthrow offers a ResultAsync class which wraps a Promise<Result<T, E>> and gives you the same level of expressivity and control as a regular Result<T, E>.

ResultAsync is thenable meaning it behaves exactly like a native Promise<Result> ... except you have access to the same methods that Result provides without having to await or .then the promise! Check out the wiki for examples and best practices.

Need to see real-life examples of how to leverage this package for error handling? See this repo: https://github.com/parlez-vous/server

Installation
Recommended: Use eslint-plugin-neverthrow
Top-Level API
API Documentation
A note on the Package Name

Installation

> npm install neverthrow

Recommended: Use `eslint-plugin-neverthrow`

As part of neverthrows bounty program, user mdbetancourt created eslint-plugin-neverthrow to ensure that errors are not gone unhandled.

Install by running:

> npm install eslint-plugin-neverthrow

With eslint-plugin-neverthrow, you are forced to consume the result in one of the following three ways:

Calling .match
Calling .unwrapOr
Calling ._unsafeUnwrap

This ensures that you're explicitly handling the error of your Result.

This plugin is essentially a porting of Rust's must-use attribute.

Top-Level API

neverthrow exposes the following:

ok convenience function to create an Ok variant of Result
err convenience function to create an Err variant of Result
Ok class and type
Err class and type
Result Type as well as namespace / object from which to call Result.fromThrowable, Result.combine.
ResultAsync class
okAsync convenience function to create a ResultAsync containing an Ok type Result
errAsync convenience function to create a ResultAsync containing an Err type Result

import {
  ok,
  Ok,
  err,
  Err,
  Result,
  okAsync,
  errAsync,
  ResultAsync,
  fromAsyncThrowable,
  fromThrowable,
  fromPromise,
  fromSafePromise,
  safeTry,
} from 'neverthrow'

Check out the wiki for help on how to make the most of neverthrow.

If you find this package useful, please consider sponsoring me or simply buying me a coffee!

API Documentation

Synchronous API (`Result`)

`ok`

Constructs an Ok variant of Result

Signature:

ok<T, E>(value: T): Ok<T, E> { ... }

Example:

import { ok } from 'neverthrow'

const myResult = ok({ myData: 'test' }) // instance of `Ok`

myResult.isOk() // true
myResult.isErr() // false

⬆️ Back to top

`err`

Constructs an Err variant of Result

Signature:

err<T, E>(error: E): Err<T, E> { ... }

Example:

import { err } from 'neverthrow'

const myResult = err('Oh noooo') // instance of `Err`

myResult.isOk() // false
myResult.isErr() // true

⬆️ Back to top

`Result.isOk` (method)

Returns true if the result is an Ok variant

Signature:

isOk(): boolean { ... }

⬆️ Back to top

`Result.isErr` (method)

Returns true if the result is an Err variant

Signature:

isErr(): boolean { ... }

⬆️ Back to top

`Result.map` (method)

Maps a Result<T, E> to Result<U, E> by applying a function to a contained Ok value, leaving an Err value untouched.

This function can be used to compose the results of two functions.

Signature:

class Result<T, E> {
  map<U>(callback: (value: T) => U): Result<U, E> { ... }
}

Example:

import { getLines } from 'imaginary-parser'
// ^ assume getLines has the following signature:
// getLines(str: string): Result<Array<string>, Error>

// since the formatting is deemed correct by `getLines`
// then it means that `linesResult` is an Ok
// containing an Array of strings for each line of code
const linesResult = getLines('1\n2\n3\n4\n')

// this Result now has a Array<number> inside it
const newResult = linesResult.map(
  (arr: Array<string>) => arr.map(parseInt)
)

newResult.isOk() // true

⬆️ Back to top

`Result.mapErr` (method)

Maps a Result<T, E> to Result<T, F> by applying a function to a contained Err value, leaving an Ok value untouched.

This function can be used to pass through a successful result while handling an error.

Signature:

class Result<T, E> {
  mapErr<F>(callback: (error: E) => F): Result<T, F> { ... }
}

Example:

import { parseHeaders } from 'imaginary-http-parser'
// imagine that parseHeaders has the following signature:
// parseHeaders(raw: string): Result<SomeKeyValueMap, ParseError>

const rawHeaders = 'nonsensical gibberish and badly formatted stuff'

const parseResult = parseHeaders(rawHeaders)

parseResult.mapErr(parseError => {
  res.status(400).json({
    error: parseError
  })
})

parseResult.isErr() // true

⬆️ Back to top

`Result.unwrapOr` (method)

Unwrap the Ok value, or return the default if there is an Err

Signature:

class Result<T, E> {
  unwrapOr<T>(value: T): T { ... }
}

Example:

const myResult = err('Oh noooo')

const multiply = (value: number): number => value * 2

const unwrapped: number = myResult.map(multiply).unwrapOr(10)

⬆️ Back to top

`Result.andThen` (method)

Same idea as map above. Except you must return a new Result.

The returned value will be a Result. As of v4.1.0-beta, you are able to return distinct error types (see signature below). Prior to v4.1.0-beta, the error type could not be distinct.

This is useful for when you need to do a subsequent computation using the inner T value, but that computation might fail.

Additionally, andThen is really useful as a tool to flatten a Result<Result<A, E2>, E1> into a Result<A, E2> (see example below).

Signature:

class Result<T, E> {
  // Note that the latest version lets you return distinct errors as well.
  // If the error types (E and F) are the same (like `string | string`)
  // then they will be merged into one type (`string`)
  andThen<U, F>(
    callback: (value: T) => Result<U, F>
  ): Result<U, E | F> { ... }
}

Example 1: Chaining Results

import { err, ok } from 'neverthrow'

const sq = (n: number): Result<number, number> => ok(n ** 2)

ok(2)
  .andThen(sq)
  .andThen(sq) // Ok(16)

ok(2)
  .andThen(sq)
  .andThen(err) // Err(4)

ok(2)
  .andThen(err)
  .andThen(sq) // Err(2)

err(3)
  .andThen(sq)
  .andThen(sq) // Err(3)

Example 2: Flattening Nested Results

// It's common to have nested Results
const nested = ok(ok(1234))

// notNested is a Ok(1234)
const notNested = nested.andThen((innerResult) => innerResult)

⬆️ Back to top

`Result.asyncAndThen` (method)

Same idea as andThen above, except you must return a new ResultAsync.

The returned value will be a ResultAsync.

Signature:

class Result<T, E> {
  asyncAndThen<U, F>(
    callback: (value: T) => ResultAsync<U, F>
  ): ResultAsync<U, E | F> { ... }
}

⬆️ Back to top

`Result.orElse` (method)

Takes an Err value and maps it to a Result<T, SomeNewType>. This is useful for error recovery.

Signature:

class Result<T, E> {
  orElse<A>(
    callback: (error: E) => Result<T, A>
  ): Result<T, A> { ... }
}

Example:

enum DatabaseError {
  PoolExhausted = 'PoolExhausted',
  NotFound = 'NotFound',
}

const dbQueryResult: Result<string, DatabaseError> = err(DatabaseError.NotFound)

const updatedQueryResult = dbQueryResult.orElse((dbError) =>
  dbError === DatabaseError.NotFound
    ? ok('User does not exist') // error recovery branch: ok() must be called with a value of type string
    //
    //
    // err() can be called with a value of any new type that you want
    // it could also be called with the same error value
    //     
    //     err(dbError)
    : err(500) 
)

⬆️ Back to top

`Result.match` (method)

Given 2 functions (one for the Ok variant and one for the Err variant) execute the function that matches the Result variant.

Match callbacks do not necessitate to return a Result, however you can return a Result if you want to.

Signature:

class Result<T, E> {
  match<A, B = A>(
    okCallback: (value: T) =>  A,
    errorCallback: (error: E) =>  B
  ): A | B => { ... }
}

match is like chaining map and mapErr, with the distinction that with match both functions must have the same return type. The differences between match and chaining map and mapErr are that:

with match both functions must have the same return type A
match unwraps the Result<T, E> into an A (the match functions' return type)
- This makes no difference if you are performing side effects only

Example:

// map/mapErr api
// note that you DON'T have to append mapErr
// after map which means that you are not required to do
// error handling
computationThatMightFail().map(console.log).mapErr(console.error)

// match api
// works exactly the same as above since both callbacks
// only perform side effects,
// except, now you HAVE to do error handling :)
computationThatMightFail().match(console.log, console.error)

// Returning values
const attempt = computationThatMightFail()
  .map((str) => str.toUpperCase())
  .mapErr((err) => `Error: ${err}`)
// `attempt` is of type `Result<string, string>`

const answer = computationThatMightFail().match(
  (str) => str.toUpperCase(),
  (err) => `Error: ${err}`
)
// `answer` is of type `string`

If you don't use the error parameter in your match callback then match is equivalent to chaining map with unwrapOr:

const answer = computationThatMightFail().match(
  (str) => str.toUpperCase(),
  () => 'ComputationError'
)
// `answer` is of type `string`

const answer = computationThatMightFail()
  .map((str) => str.toUpperCase())
  .unwrapOr('ComputationError')

⬆️ Back to top

`Result.asyncMap` (method)

Similar to map except for two things:

the mapping function must return a Promise
asyncMap returns a ResultAsync

You can then chain the result of asyncMap using the ResultAsync apis (like map, mapErr, andThen, etc.)

Signature:

class Result<T, E> {
  asyncMap<U>(
    callback: (value: T) => Promise<U>
  ): ResultAsync<U, E> { ... }
}

Example:

import { parseHeaders } from 'imaginary-http-parser'
// imagine that parseHeaders has the following signature:
// parseHeaders(raw: string): Result<SomeKeyValueMap, ParseError>

const asyncRes = parseHeaders(rawHeader)
  .map(headerKvMap => headerKvMap.Authorization)
  .asyncMap(findUserInDatabase)

Note that in the above example if parseHeaders returns an Err then .map and .asyncMap will not be invoked, and asyncRes variable will resolve to an Err when turned into a Result using await or .then().

⬆️ Back to top