neverthrow

neverthrow — Condensed API (Core surface, minimal examples)

Top‑Level Exports

• ok, err, Ok, Err, Result, ResultAsync
• okAsync, errAsync
• fromThrowable, fromAsyncThrowable, fromPromise, fromSafePromise, safeTry

Core Concepts

• Result<T, E>: synchronous success/error container
• ResultAsync<T, E>: async version resolving to Result<T, E>
• Combinators never execute callbacks on the non-matching variant (short-circuit)
• Prefer map/andThen over try/catch; mapErr/orElse to standardize and recover errors

Result<T, E>

Constructors

ok<T, E = never>(value: T): Ok<T, E>
err<T = never, E = unknown>(error: E): Err<T, E>

Introspection

isOk(): boolean
isErr(): boolean

Transformations

map<U>(fn: (value: T) => U): Result<U, E>
mapErr<F>(fn: (error: E) => F): Result<T, F>
unwrapOr(defaultValue: T): T
match<A, B = A>(okFn: (v: T) => A, errFn: (e: E) => B): A | B

Control flow / chaining

andThen<U, F>(fn: (value: T) => Result<U, F>): Result<U, E | F>
asyncAndThen<U, F>(fn: (value: T) => ResultAsync<U, F>): ResultAsync<U, E | F>
asyncMap<U>(fn: (value: T) => Promise<U>): ResultAsync<U, E>
orElse<U, A>(fn: (error: E) => Result<U, A>): Result<U | T, A>

Side‑effect helpers

andTee(cb: (value: T) => unknown): Result<T, E>           // pass-through side effects on Ok
orTee(cb: (error: E) => unknown): Result<T, E>            // pass-through side effects on Err
andThrough<F>(cb: (value: T) => Result<unknown, F>): Result<T, E | F>
asyncAndThrough<F>(cb: (value: T) => ResultAsync<unknown, F>): ResultAsync<T, E | F>

Statics on Result

Result.fromThrowable<A, E>(fn: (...args: any[]) => A, mapError?: (u: unknown) => E): (...args: any[]) => Result<A, E>
Result.combine<T, E>(list: Result<T, E>[]): Result<T[], E>
Result.combine<T1, T2, E1, E2>(tuple: [Result<T1, E1>, Result<T2, E2>]): Result<[T1, T2], E1 | E2>
Result.combineWithAllErrors<T, E>(list: Result<T, E>[]): Result<T[], E[]>

ResultAsync<T, E>

Constructors

okAsync<T, E = never>(value: T): ResultAsync<T, E>
errAsync<T = never, E = unknown>(error: E): ResultAsync<T, E>

Introspection (via awaiting or .then): resolves to Result<T, E>

Transformations

map<U>(fn: (value: T) => U | Promise<U>): ResultAsync<U, E>
mapErr<F>(fn: (error: E) => F | Promise<F>): ResultAsync<T, F>
unwrapOr(defaultValue: T): Promise<T>
match<A, B = A>(okFn: (v: T) => A, errFn: (e: E) => B): Promise<A | B>

Control flow / chaining

andThen<U, F>(fn: (value: T) => Result<U, F> | ResultAsync<U, F>): ResultAsync<U, E | F>
orElse<U, A>(fn: (error: E) => Result<U, A> | ResultAsync<U, A>): ResultAsync<U | T, A>

Side‑effect helpers

andTee(cb: (value: T) => unknown): ResultAsync<T, E>
orTee(cb: (error: E) => unknown): ResultAsync<T, E>
andThrough<F>(cb: (value: T) => Result<unknown, F> | ResultAsync<unknown, F>): ResultAsync<T, E | F>

Statics on ResultAsync

ResultAsync.fromThrowable<A, E>(fn: (...args: any[]) => Promise<A>, mapError?: (u: unknown) => E): (...args: any[]) => ResultAsync<A, E>
ResultAsync.fromPromise<A, E>(p: PromiseLike<A>, mapError: (u: unknown) => E): ResultAsync<A, E>
ResultAsync.fromSafePromise<A, E = never>(p: PromiseLike<A>): ResultAsync<A, E>
ResultAsync.combine<T, E>(list: ResultAsync<T, E>[]): ResultAsync<T[], E>
ResultAsync.combineWithAllErrors<T, E>(list: ResultAsync<T, E>[]): ResultAsync<T[], E[]>

Utilities

fromThrowable / fromAsyncThrowable

• Wrap throwy sync/async functions into functions returning Result / ResultAsync
• Always provide mapError to normalize unknown to a typed E when possible

fromPromise / fromSafePromise

• fromPromise: wrap an existing promise, map rejection reason (unknown) to typed E
• fromSafePromise: same but assumes it won’t throw; no error handler; be certain

safeTry

• Write linear code over multiple Result/ResultAsync operations without manual unwrap
• Generator-based; yield* short-circuits on Err; returns Ok on success

const result = safeTry<number, string>(function* () {
	const a = yield* mayFail1();
	const b = yield* mayFail2();
	return ok(a + b);
});