Neverthrow project

Result/Ok/Err generic monad library with chaining and combine overloads; exercises generic monad composition and tuple-spread overload resolution.

tsz unavailable 1202 lines 36 KB tsz error; tsc ok

Timing

tsz
failed
tsgo
n/a

README

NeverThrow 🙅

GitHub Workflow Status

Description

Encode failure into your program.

Demo

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

Table Of Contents

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<U, A>(
    callback: (error: E) => Result<U, A>
  ): Result<U | 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

Result.andTee (method)

Takes a Result<T, E> and lets the original Result<T, E> pass through regardless the result of the passed-in function. This is a handy way to handle side effects whose failure or success should not affect your main logics such as logging.

Signature:

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

Example:

import { parseUserInput } from 'imaginary-parser'
import { logUser } from 'imaginary-logger'
import { insertUser } from 'imaginary-database'

// ^ assume parseUserInput, logUser and insertUser have the following signatures:
// parseUserInput(input: RequestData): Result<User, ParseError>
// logUser(user: User): Result<void, LogError> 
// insertUser(user: User): ResultAsync<void, InsertError>
// Note logUser returns void upon success but insertUser takes User type.

const resAsync = parseUserInput(userInput)
               .andTee(logUser)
               .asyncAndThen(insertUser)

// Note no LogError shows up in the Result type
resAsync.then((res: Result<void, ParseError | InsertError>) => {
  if(res.isErr()){
    console.log("Oops, at least one step failed", res.error)
  }
  else{
    console.log("User input has been parsed and inserted successfully.")
  }
})

⬆️ Back to top

Result.orTee (method)

Like andTee for the error track. Takes a Result<T, E> and lets the Err value pass through regardless the result of the passed-in function. This is a handy way to handle side effects whose failure or success should not affect your main logics such as logging.

Signature:

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

Example:

import { parseUserInput } from 'imaginary-parser'
import { logParseError } from 'imaginary-logger'
import { insertUser } from 'imaginary-database'

// ^ assume parseUserInput, logParseError and insertUser have the following signatures:
// parseUserInput(input: RequestData): Result<User, ParseError>
// logParseError(parseError: ParseError): Result<void, LogError> 
// insertUser(user: User): ResultAsync<void, InsertError>
// Note logParseError returns void upon success but insertUser takes User type.

const resAsync = parseUserInput(userInput)
               .orTee(logParseError)
               .asyncAndThen(insertUser)

// Note no LogError shows up in the Result type
resAsync.then((res: Result<void, ParseError | InsertError>) => {
  if(res.isErr()){
    console.log("Oops, at least one step failed", res.error)
  }
  else{
    console.log("User input has been parsed and inserted successfully.")
  }
})

⬆️ Back to top

Result.andThrough (method)

Similar to andTee except for:

  • when there is an error from the passed-in function, that

...