neverthrow
Advanced tools
The neverthrow npm package provides a functional way to handle errors in TypeScript and JavaScript. It introduces the Result and Option types, which help in managing success and failure cases without using exceptions.
Result Type
The Result type is used to represent either a success (ok) or a failure (err). This example demonstrates a division function that returns a Result type, handling division by zero as an error.
const { ok, err, Result } = require('neverthrow');
function divide(a, b) {
if (b === 0) {
return err(new Error('Division by zero'));
}
return ok(a / b);
}
const result = divide(4, 2);
result.match({
ok: value => console.log('Result:', value),
err: error => console.error('Error:', error.message)
});Option Type
The Option type is used to represent an optional value that may or may not be present. This example shows a function that looks up a user by ID and returns an Option type.
const { some, none, Option } = require('neverthrow');
function findUserById(id) {
const users = { 1: 'Alice', 2: 'Bob' };
return users[id] ? some(users[id]) : none();
}
const user = findUserById(1);
user.match({
some: value => console.log('User found:', value),
none: () => console.log('User not found')
});Chaining Operations
Chaining operations with Result types allows for sequential error handling. This example demonstrates parsing a number and then dividing it, with each step returning a Result type.
const { ok, err, Result } = require('neverthrow');
function parseNumber(str) {
const num = Number(str);
return isNaN(num) ? err(new Error('Invalid number')) : ok(num);
}
function divide(a, b) {
if (b === 0) {
return err(new Error('Division by zero'));
}
return ok(a / b);
}
const result = parseNumber('4').andThen(num => divide(num, 2));
result.match({
ok: value => console.log('Result:', value),
err: error => console.error('Error:', error.message)
});Folktale is a standard library for functional programming in JavaScript. It provides similar functionality to neverthrow with its Result and Maybe types, but also includes a broader range of functional programming utilities.
fp-ts is a library for functional programming in TypeScript. It offers a comprehensive set of tools for functional programming, including Result and Option types, similar to neverthrow, but with a more extensive ecosystem and integration with other functional programming concepts.
Purify is a functional programming library for TypeScript that provides Maybe and Either types, which are analogous to neverthrow's Option and Result types. It focuses on immutability and functional programming patterns.
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
> npm install neverthrow
neverthrow exposes the following:
ok convenience function to create an Ok variant of Resulterr convenience function to create an Err variant of ResultOk class for you to construct an Ok variant in an OOP way using newErr class for you to construct an Err variant in an OOP way using newResult type - only available in TypeScriptResultAsync classokAsync convenience function to create a ResultAsync containing an Ok type ResulterrAsync convenience function to create a ResultAsync containing an Err type Resultcombine utility function that allows you to turn Result<T, E>[] into Result<T[], E>, or a ResultAsync<T, E>[] into ResultAsync<T[], E> (just like Promise.all)import {
ok,
Ok,
err,
Err,
Result,
okAsync,
errAsync,
ResultAsync,
combine
} 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!
Result)okConstructs 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
errConstructs an Err variant of Result
Signature:
err<T, E>(err: E): Err<T, E> { ... }
Example:
import { err } from 'neverthrow'
const myResult = err('Oh noooo') // instance of `Err`
myResult.isOk() // false
myResult.isErr() // true
Result.isOk (method)Returns true if the result is an Ok variant
Signature:
isOk(): boolean { ... }
Result.isErr (method)Returns true if the result is an Err variant
Signature:
isErr(): boolean { ... }
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:
type MapFunc = <T, U>(f: T) => U
map<U>(fn: MapFunc): Result<U, E> { ... }
Example:
const { 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
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:
type MapFunc = <E>(e: E) => F
mapErr<U>(fn: MapFunc): Result<T, F> { ... }
Example:
import { parseHeaders } '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
Result.unwrapOr (method)Unwrap the Ok value, or return the default if there is an Err
Signature:
unwrapOr<T>(v: T): T { ... }
Example:
const myResult = err('Oh noooo')
const multiply = (val: number): number => val * 2
const unwrapped: number = myResult.map(multiply).unwrapOr(10)
Result.andThen (method)Same idea as map above. Except you must return a new Result.
The returned value will be a Result.
This is useful for when you need to do a subsequent computation using the inner T value, but that computation might fail.
andThen is really useful as a tool to flatten a Result<Result<A, E2>, E1> into a Result<A, E2> (see example below).
Signature:
type AndThenFunc = <T, U>(t: T) => Result<U, E>
andThen<U>(f: AndThenFunc): Result<U, E> { ... }
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)
Result.asyncAndThen (method)Same idea as andThen above. Except you must return a new ResultAsync.
The returned value will be a ResultAsync.
Signature:
type AndThenAsyncFunc = (t: T) => ResultAsync<U, E>
asyncAndThen<U>(f: AndThenAsyncFunc): ResultAsync<U, E> { ... }
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:
match<A>(
okFn: (t: T) => A,
errFn: (e: E) => A
): A => { ... }
match is like chaining map and mapErr, with the distinction that with match both functions must have the same return type.
Example:
const result = computationThatMightFail()
const successCallback = (someNumber: number) => {
console.log('> number is: ', someNumber)
}
const failureCallback = (someFailureValue: string) => {
console.log('> boooooo')
}
// method chaining api
// note that you DONT have to append mapErr
// after map which means that you are not required to do
// error handling
result.map(successCallback).mapErr(failureCallback)
// match api
// works exactly the same as above,
// except, now you HAVE to do error handling :)
myval.match(successCallback, failureCallback)
Result.asyncMap (method)Similar to map except for two things:
PromiseResultAsyncYou can then chain the result of asyncMap using the ResultAsync apis (like map, mapErr, andThen, etc.)
Signature:
type MappingFunc = (t: T) => Promise<U>
asyncMap<U>(fn: MappingFunc): ResultAsync<U, E> { ... }
Example:
import { parseHeaders } '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().
ResultAsync)okAsyncConstructs an Ok variant of ResultAsync
Signature:
okAsync<T, E>(value: T): ResultAsync<T, E>
Example:
import { okAsync } from 'neverthrow'
const myResultAsync = okAsync({ myData: 'test' }) // instance of `ResultAsync`
const myResult = await myResultAsync // instance of `Ok`
myResult.isOk() // true
myResult.isErr() // false
errAsyncConstructs an Err variant of ResultAsync
Signature:
errAsync<T, E>(err: E): ResultAsync<T, E>
Example:
import { errAsync } from 'neverthrow'
const myResultAsync = errAsync('Oh nooo') // instance of `ResultAsync`
const myResult = await myResultAsync // instance of `Err`
myResult.isOk() // false
myResult.isErr() // true
ResultAsync.fromPromise (static class method)Transforms a Promise<T> into a ResultAsync<T, E>.
The second argument handles the rejection case of the promise. If it is ommited, the code might throw because neverthrow does not know if the promise you are passing to fromPromise has any promise rejection logic associated to it (via a .catch method call or catch (err) {} block).
Signature:
fromPromise<U, E>(p: Promise<U>, f?: (e: unknown) => E): ResultAsync<U, E> { ... }
Example:
import { ResultAsync } from 'neverthrow'
import { insertIntoDb } from 'imaginary-database'
// insertIntoDb(user: User): Promise<User>
const res = ResultAsync.fromPromise(insertIntoDb(myUser), () => new Error('Database error'))
// res has a type of ResultAsync<User, Error>
ResultAsync.map (method)Maps a ResultAsync<T, E> to ResultAsync<U, E> by applying a function to a contained Ok value, leaving an Err value untouched.
The applied function can be synchronous or asynchronous (returning a Promise<U>) with no impact to the return type.
This function can be used to compose the results of two functions.
Signature:
type MapFunc = <T>(f: T | Promise<T>) => U
map<U>(fn: MapFunc): ResultAsync<U, E> { ... }
Example:
const { findUsersIn } from 'imaginary-database'
// ^ assume findUsersIn has the following signature:
// findUsersIn(country: string): ResultAsync<Array<User>, Error>
const usersInCanada = findUsersIn("Canada")
// Let's assume we only need their names
const namesInCanada = usersInCanada.map((users: Array<User>) => users.map(user => user.name))
// namesInCanada is of type ResultAsync<Array<string>, Error>
// We can extract the Result using .then() or await
namesInCanada.then((namesResult: Result<Array<string>, Error>) => {
if(namesResult.isErr()){
console.log("Couldn't get the users from the database", namesResult.error)
}
else{
console.log("Users in Canada are named: " + namesResult.value.join(','))
}
})
ResultAsync.mapErr (method)Maps a ResultAsync<T, E> to ResultAsync<T, F> by applying a function to a contained Err value, leaving an Ok value untouched.
The applied function can be synchronous or asynchronous (returning a Promise<F>) with no impact to the return type.
This function can be used to pass through a successful result while handling an error.
Signature:
type MapFunc = <E>(e: E) => F | Promise<F>
mapErr<U>(fn: MapFunc): ResultAsync<T, F> { ... }
Example:
const { findUsersIn } from 'imaginary-database'
// ^ assume findUsersIn has the following signature:
// findUsersIn(country: string): ResultAsync<Array<User>, Error>
// Let's say we need to low-level errors from findUsersIn to be more readable
const usersInCanada = findUsersIn("Canada").mapErr((e: Error) => {
// The only error we want to pass to the user is "Unknown country"
if(e.message === "Unknown country"){
return e.message
}
// All other errors will be labelled as a system error
return "System error, please contact an administrator."
})
// usersInCanada is of type ResultAsync<Array<User>, string>
usersInCanada.then((usersResult: Result<Array<User>, string>) => {
if(usersResult.isErr()){
res.status(400).json({
error: usersResult.error
})
}
else{
res.status(200).json({
users: usersResult.value
})
}
})
ResultAsync.unwrapOr (method)Unwrap the Ok value, or return the default if there is an Err.
Works just like Result.unwrapOr but returns a Promise<T> instead of T.
Signature:
unwrapOr<T>(v: T): Promise<T> { ... }
Example:
const unwrapped: number = await errAsync(0).unwrapOr(10)
// unwrapped = 10
ResultAsync.andThen (method)Same idea as map above. Except the applied function must return a Result or ResultAsync.
ResultAsync.andThen always returns a ResultAsync no matter the return type of the applied function.
This is useful for when you need to do a subsequent computation using the inner T value, but that computation might fail.
andThen is really useful as a tool to flatten a ResultAsync<ResultAsync<A, E2>, E1> into a ResultAsync<A, E2> (see example below).
Signature:
type AndThenFunc = (t: T) => ResultAsync<U, E> | Result<U, E>
andThen<U>(f: AndThenFunc): ResultAsync<U, E> { ... }
Example
const { validateUser } from 'imaginary-validator'
const { insertUser } from 'imaginary-database'
const { sendNotification } from 'imaginary-service'
// ^ assume validateUser, insertUser and sendNotification have the following signatures:
// validateUser(user: User): Result<User, Error>
// insertUser(user): ResultAsync<User, Error>
// sendNotification(user): ResultAsync<void, Error>
const resAsync = validateUser(user)
.andThen(insertUser)
.andThen(sendNotification)
// resAsync is a ResultAsync<void, Error>
resAsync.then((res: Result<void, Error>) => {
if(res.isErr()){
console.log("Oops, at least one step failed", res.error)
}
else{
console.log("User has been validated, inserted and notified successfully.")
}
})
ResultAsync.match (method)Given 2 functions (one for the Ok variant and one for the Err variant) execute the function that matches the ResultAsync variant.
The difference with Result.match is that it always returns a Promise because of the asynchronous nature of the ResultAsync.
Signature:
match<A>(
okFn: (t: T) => A,
errFn: (e: E) => A
): Promise<A> => { ... }
Example:
const { validateUser } from 'imaginary-validator'
const { insertUser } from 'imaginary-database'
// ^ assume validateUser and insertUser have the following signatures:
// validateUser(user: User): Result<User, Error>
// insertUser(user): ResultAsync<User, Error>
// Handle both cases at the end of the chain using match
const resultMessage = await validateUser(user)
.andThen(insertUser)
.match(
(user: User) => `User ${user.name} has been successfully created`,
(e: Error) => `User could not be created because ${e.message}`
)
// resultMessage is a string
combineIf you're familiar with Promise.all, the combine function works conceptually the same.
The combine function takes a list of results and return a single result. If all the results in the list are Ok, then the return value will be a Ok containing a list of all the individual Ok values.
If just one of the results in the list is an Err then the combine function returns that Err value (it short circuits and returns the first Err that it finds).
Formally speaking:
function combine<T, E>(resultList: Result<T, E>[]): Result<T[], E>
Additionally, this same function also works for ResultAsync. And thanks to typescript function overloading, the types can be distinguished.
function combine<T, E>(asyncResultList: ResultAsync<T, E>[]): ResultAsync<T[], E>
Limitation: combine, as you may have noticed, only works homogenous lists (where all the T and E's are the same for each element in the list). There are plans to eventually make combine work on heterogeneous lists.
If you find this package useful, please consider sponsoring me or simply buying me a coffee!
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.
FAQs
Stop throwing errors, and instead return Results!
The npm package neverthrow receives a total of 620,637 weekly downloads. As such, neverthrow popularity was classified as popular.
We found that neverthrow demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Critics call the Node.js EOL CVE a misuse of the system, sparking debate over CVE standards and the growing noise in vulnerability databases.
Security News
cURL and Go security teams are publicly rejecting CVSS as flawed for assessing vulnerabilities and are calling for more accurate, context-aware approaches.
Security News
Bun 1.2 enhances its JavaScript runtime with 90% Node.js compatibility, built-in S3 and Postgres support, HTML Imports, and faster, cloud-first performance.