NeverThrow

Type-Safe Errors for JS & TypeScript

Error handlingFunctional programming
supermacro/neverthrowneverthrow

README

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>` and gives you the same level of expressivity and control as a regular `Result`.

`ResultAsync` is `thenable` meaning it **behaves exactly like a native `Promise`** ... except you have access to the same methods that `Result` provides without having to `await` or `.then` the promise! Check out [the wiki](https://github.com/supermacro/neverthrow/wiki/Basic-Usage-Examples#asynchronous-api) 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


  1. ```sh
  2. > npm install neverthrow
  3. ```

Recommended: Use eslint-plugin-neverthrow


As part of neverthrows bounty program, user mdbetancourt created [eslint-plugin-neverthrow](https://github.com/mdbetancourt/eslint-plugin-neverthrow) to ensure that errors are not gone unhandled.

Install by running:

  1. ```sh
  2. > npm install eslint-plugin-neverthrow
  3. ```

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](https://doc.rust-lang.org/std/result/#results-must-be-used) 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](#resultfromthrowable-static-class-method), 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

  1. ```typescript
  2. import {
  3.   ok,
  4.   Ok,
  5.   err,
  6.   Err,
  7.   Result,
  8.   okAsync,
  9.   errAsync,
  10.   ResultAsync,
  11.   fromThrowable,
  12.   fromPromise,
  13.   fromSafePromise,
  14. } from 'neverthrow'
  15. ```


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

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:

  1. ```typescript
  2. ok<T, E>(value: T): Ok<T, E> { ... }
  3. ```

Example:

  1. ```typescript
  2. import { ok } from 'neverthrow'

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

  6. myResult.isOk() // true
  7. myResult.isErr() // false
  8. ```

⬆️  Back to top


err


Constructs an Err variant of Result

Signature:

  1. ```typescript
  2. err<T, E>(error: E): Err<T, E> { ... }
  3. ```

Example:

  1. ```typescript
  2. import { err } from 'neverthrow'

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

  6. myResult.isOk() // false
  7. myResult.isErr() // true
  8. ```

⬆️  Back to top


Result.isOk (method)


Returns true if the result is an Ok variant

Signature:

  1. ```typescript
  2. isOk(): boolean { ... }
  3. ```

⬆️  Back to top


Result.isErr (method)


Returns true if the result is an Err variant

Signature:

  1. ```typescript
  2. isErr(): boolean { ... }
  3. ```

⬆️  Back to top


Result.map (method)


Maps a `Result` to `Result` 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:

  1. ```typescript
  2. class Result<T, E> {
  3.   map<U>(callback: (value: T) => U): Result<U, E> { ... }
  4. }
  5. ```

Example:

  1. ```typescript
  2. import { getLines } from 'imaginary-parser'
  3. // ^ assume getLines has the following signature:
  4. // getLines(str: string): Result, Error>

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

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

  16. newResult.isOk() // true
  17. ```

⬆️  Back to top


Result.mapErr (method)


Maps a `Result` to `Result` 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:

  1. ```typescript
  2. class Result<T, E> {
  3.   mapErr<F>(callback: (error: E) => F): Result<T, F> { ... }
  4. }
  5. ```

Example:

  1. ```typescript
  2. import { parseHeaders } from 'imaginary-http-parser'
  3. // imagine that parseHeaders has the following signature:
  4. // parseHeaders(raw: string): Result

  6. const rawHeaders = 'nonsensical gibberish and badly formatted stuff'

  8. const parseResult = parseHeaders(rawHeaders)

  10. parseResult.mapErr(parseError => {
  11.   res.status(400).json({
  12.     error: parseError
  13.   })
  14. })

  16. parseResult.isErr() // true
  17. ```

⬆️  Back to top


Result.unwrapOr (method)


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

Signature:

  1. ```typescript
  2. class Result<T, E> {
  3.   unwrapOr<T>(value: T): T { ... }
  4. }
  5. ```

Example:

  1. ```typescript
  2. const myResult = err('Oh noooo')

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

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

⬆️  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, E1>` into a `Result` (see example below).

Signature:

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

Example 1: Chaining Results

  1. ```typescript
  2. import { err, ok } from 'neverthrow'

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

  6. ok(2)
  7.   .andThen(sq)
  8.   .andThen(sq) // Ok(16)

  10. ok(2)
  11.   .andThen(sq)
  12.   .andThen(err) // Err(4)

  14. ok(2)
  15.   .andThen(err)
  16.   .andThen(sq) // Err(2)

  18. err(3)
  19.   .andThen(sq)
  20.   .andThen(sq) // Err(3)
  21. ```

Example 2: Flattening Nested Results

  1. ```typescript
  2. // It's common to have nested Results
  3. const nested = ok(ok(1234))

  5. // notNested is a Ok(1234)
  6. const notNested = nested.andThen((innerResult) => innerResult)
  7. ```

⬆️  Back to top


Result.asyncAndThen (method)


Same idea as [andThen above](#resultandthen-method), except you must return a new ResultAsync.

The returned value will be a ResultAsync.

Signature:

  1. ```typescript
  2. class Result<T, E> {
  3.   asyncAndThen<U, F>(
  4.     callback: (value: T) => ResultAsync<U, F>
  5.   ): ResultAsync<U, E | F> { ... }
  6. }
  7. ```

⬆️  Back to top


Result.orElse (method)


Takes an `Err` value and maps it to a `Result`. This is useful for error recovery.

Signature:

  1. ```typescript
  2. class Result<T, E> {
  3.   orElse<A>(
  4.     callback: (error: E) => Result<T, A>
  5.   ): Result<T, A> { ... }
  6. }
  7. ```

Example:

  1. ```typescript
  2. enum DatabaseError {
  3.   PoolExhausted = 'PoolExhausted',
  4.   NotFound = 'NotFound',
  5. }

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

  9. const updatedQueryResult = dbQueryResult.orElse((dbError) =>
  10.   dbError === DatabaseError.NotFound
  11.     ? ok('User does not exist') // error recovery branch: ok() must be called with a value of type string
  12.     //
  13.     //
  14.     // err() can be called with a value of any new type that you want
  15.     // it could also be called with the same error value
  16.     //    
  17.     //     err(dbError)
  18.     : err(500)
  19. )
  20. ```

⬆️  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:

  1. ```typescript
  2. class Result<T, E> {
  3.   match<A>(
  4.     okCallback: (value: T) =>  A,
  5.     errorCallback: (error: E) =>  A
  6.   ): A => { ... }
  7. }
  8. ```

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` into an `A` (the match functions' return type)
  - This makes no difference if you are performing side effects only

Example:

  1. ```typescript
  2. // map/mapErr api
  3. // note that you DON'T have to append mapErr
  4. // after map which means that you are not required to do
  5. // error handling
  6. computationThatMightFail().map(console.log).mapErr(console.error)

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

  14. // Returning values
  15. const attempt = computationThatMightFail()
  16.   .map((str) => str.toUpperCase())
  17.   .mapErr((err) => `Error: ${err}`)
  18. // `attempt` is of type `Result`

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

If you don't use the error parameter in your match callback then match is equivalent to chaining map with unwrapOr:
  1. ```ts
  2. const answer = computationThatMightFail().match(
  3.   (str) => str.toUpperCase(),
  4.   () => 'ComputationError'
  5. )
  6. // `answer` is of type `string`

  8. const answer = computationThatMightFail()
  9.   .map((str) => str.toUpperCase())
  10.   .unwrapOr('ComputationError')
  11. ```

A note on the Package Name


Although the package is called neverthrow, please don't take this literally. I am simply encouraging the developer to think a bit more about the ergonomics and usage of whatever software they are writing.

Throwing and catching is very similar to using goto statements - in other words; it makes reasoning about your programs harder. Secondly, by using throw you make the assumption that the caller of your function is implementing catch. This is a known source of errors. Example: One dev throws and another dev uses the function without prior knowledge that the function will throw. Thus, and edge case has been left unhandled and now you have unhappy users, bosses, cats, etc.

With all that said, there are definitely good use cases for throwing in your program. But much less than you might think.