class AsyncResult
implements PromiseLike<Result<T, E>>

An asynchronous Result class that represents a Promise of Result<T, E>.

Implements PromiseLike to be awaitable, and provides async versions of all Result methods that return AsyncResult for seamless chaining.

Examples

Example 1

async function fetchUser(id: string): AsyncResult<User, NetworkError> {
  return AsyncResult.wrap(async () => {
    const response = await fetch(`/api/users/${id}`);
    return await response.json();
  });
}

const result = fetchUser("123")
  .map(user => user.name)
  .map(name => name.toUpperCase());

const value = await result.take();
if (isErr(value)) return value;
console.log(value); // "ALICE"

Constructors

AsyncResult(promise: Promise<Result<T, E>>)

Type Parameters

T

The type of the success value

E extends BaseError

The type of the error (must extend BaseError)

Static Methods

all<T, E extends BaseError>(results: readonly (AsyncResult<T, E> | Promise<Result<T, E>>)[]): AsyncResult<T[], E>

Combines multiple AsyncResults into a single AsyncResult containing an array.

If all Results are Ok, returns Ok with an array of all values. If any Result is Err, returns the first Err encountered.

any<T, E extends BaseError>(results: readonly (AsyncResult<T, E> | Promise<Result<T, E>>)[]): AsyncResult<T, E>

Returns the first Ok result from an array of AsyncResults.

If any Result is Ok, returns that Ok result. If all Results are Err, returns the last Err.

err<E extends BaseError, T = never>(error: E): AsyncResult<T, E>

Creates a failed AsyncResult with the given error.

from<T, E extends BaseError>(promise: Promise<Result<T, E>>): AsyncResult<T, E>

Creates an AsyncResult from a Promise of Result.

lift<T, E extends BaseError>(value: Result<T, E> | AsyncResult<T, E> | Promise<Result<T, E>>): AsyncResult<T, E>

Creates an AsyncResult from a Result, AsyncResult, or Promise<Result>.

This is the key method for working with MaybeAsync types - it normalizes both synchronous Results and asynchronous AsyncResults into AsyncResults.

ok<T, E extends BaseError = never>(value: T): AsyncResult<T, E>

Creates a successful AsyncResult with the given value.

try<T>(
fn: () => Promise<T>,
context?: Record<string, unknown>
): AsyncResult<T, UnexpectedError>

Wraps an async function that might throw into an AsyncResult.

Catches any exceptions and wraps them in UnexpectedError.

Methods

andThen<U, F extends BaseError>(fn: (value: T) => Result<U, F> | AsyncResult<U, F> | Promise<Result<U, F>>): AsyncResult<U, E | F>

Chains operations that return Results.

context(
message: string,
extra?: Record<string, unknown>
): AsyncResult<T, E>

Adds context to an Err result for early returns. Async version - can be chained before take().

inspect(fn: (value: T) => void | Promise<void>): AsyncResult<T, E>

Performs a side effect on the Ok value without changing the result.

inspectErr(fn: (error: E) => void | Promise<void>): AsyncResult<T, E>

Performs a side effect on the Err value without changing the result.

map<U>(fn: (value: T) => U): AsyncResult<U, E>

Transforms the Ok value using a mapper function, leaving Err untouched.

mapErr<F extends BaseError>(fn: (error: E) => F): AsyncResult<T, F>

Transforms the Err value using a mapper function, leaving Ok untouched.

match<U>(pattern: { ok: (value: T) => U; err: (error: E) => U; }): Promise<U>

Pattern matching for async Results.

or<U>(other: Result<U, E> | AsyncResult<U, E> | Promise<Result<U, E>>): AsyncResult<T | U, E>

Returns this result if Ok, otherwise returns the fallback.

orElse<U, F extends BaseError>(fn: (error: E) => Result<U, F> | AsyncResult<U, F> | Promise<Result<U, F>>): AsyncResult<T | U, F>

Returns this result if Ok, otherwise computes a fallback from the error.

orThrow(): Promise<T>

Returns the Ok value or throws the Err error.

Async version of Result.orThrow().

take(): Promise<T | Result<never, E>>

Extracts the value from Ok or returns the Err for early returns.

This is the async version of Result.take(). It returns a Promise that resolves to either the unwrapped value T or an Err Result.

then<TResult1 = Result<T, E>, TResult2 = never>(
onfulfilled?:
((value: Result<T, E>) => TResult1 | PromiseLike<TResult1>)
| null,
onrejected?:
((reason: unknown) => TResult2 | PromiseLike<TResult2>)
| null
): Promise<TResult1 | TResult2>

Implements PromiseLike to make AsyncResult awaitable.

unwrapOr<U>(defaultValue: U): Promise<T | U>

Returns the Ok value or a default value if Err.

unwrapOrElse<U>(fn: (error: E) => U): Promise<T | U>

Returns the Ok value or computes a default from the error.

Usage

import { AsyncResult } from "result/mod.ts";