ResultAsync<T, E>

Represents an asynchronous Result that wraps a Promise.

ResultAsync implements PromiseLike<Result<T, E>>, which means it can be awaited directly or used with .then() chains. It provides the same API as Result but for asynchronous operations.

Since

2.0.0

---

Example

const asyncResult = okAsync(Promise.resolve("hello"));

// Can be awaited directly
const result = await asyncResult;
if (result.isOk()) {
  console.log(result.value); // "hello"
}

// Or used with .then()
asyncResult.then(result => {
  if (result.isOk()) {
    console.log(result.value);
  }
});

---

Type Parameters

T: T

The type of the success value

E: E

The type of the error value

---

Implements

• PromiseLike<Result<T, E>>

---

Constructors

Constructor

Creates a new ResultAsync instance.

res: Promise<Result<T, E>> — Promise that resolves to a Result
Returns: ResultAsync<T, E>

---

Methods

fromSafePromise()

Creates a ResultAsync from a Promise that is guaranteed to resolve successfully. This method assumes the Promise will never reject, so use with caution.

Type Parameters

T: T

The type of the value in the Promise

E: E = never

The type of the error (defaults to never)

promise: Promise<T> — Promise that will resolve to a value
Returns: ResultAsync<T, E> — A new ResultAsync that will resolve to Ok(value)

Example

const promise = Promise.resolve(42);
const result = ResultAsync.fromSafePromise(promise);

const resolved = await result;
// resolved is Ok(42)

fromPromise()

Creates a ResultAsync from a Promise that may reject. The errorFn parameter is used to transform any rejection into an error value.

Type Parameters

T: T

The type of the value in the Promise

E: E

The type of the error

promise: Promise<T> — Promise that may resolve or reject
errorFn: (e) => E — Function to transform rejections into error values
Returns: ResultAsync<T, E> — A new ResultAsync that will resolve to Ok(value) or Err(error)

Example

const fetchUser = (id: string) =>
  fetch(`/api/users/${id}`).then(r => r.json());

const result = ResultAsync.fromPromise(
  fetchUser("123"),
  (error) => `Failed to fetch user: ${error}`
);

const resolved = await result;
if (resolved.isOk()) {
  console.log(resolved.value); // User data
} else {
  console.log(resolved.error); // Error message
}

fromThrowable()

Wraps an async function with try-catch error handling, creating a new function that returns a ResultAsync instead of throwing exceptions.

Uses unknown types for maximum type safety and modern TypeScript syntax.

Type Parameters

A: A extends unknown[]

The types of the function arguments

R: R

The return type of the async function

E: E = unknown

The type of the error

fn: (...args) => Promise<R> — Async function to wrap with error handling
errorFn?: (err) => E — Optional function to transform thrown errors
Returns: A new function that returns a ResultAsync instead of throwing — > (...args): ResultAsync<R, E>

args: ...A
Returns: ResultAsync<R, E>

Example

const fetchUser = async (id: string) => {
  const response = await fetch(`/api/users/${id}`);
  if (!response.ok) {
    throw new Error(`HTTP ${response.status}`);
  }
  return response.json();
};

const safeFetchUser = ResultAsync.fromThrowable(
  fetchUser,
  (error) => `User fetch failed: ${error}`
);

const result = await safeFetchUser("123");
if (result.isOk()) {
  console.log(result.value); // User data
} else {
  console.log(result.error); // Error message
}

combine()

Combines multiple ResultAsync instances into a single ResultAsync. Returns the first error encountered, or all values if all ResultAsyncs are Ok.

Uses unknown types for maximum type safety and compatibility.

Type Parameters

T: T extends ResultAsync<unknown, unknown>[]

The type of the ResultAsync array

asyncResultList: T — Array of ResultAsync instances to combine
Returns: ResultAsync<unknown[], unknown> — A ResultAsync containing an array of all values, or the first error

Example

const results = [
  okAsync(Promise.resolve(1)),
  okAsync(Promise.resolve(2)),
  okAsync(Promise.resolve(3))
];

const combined = ResultAsync.combine(results);
const resolved = await combined;
// resolved is Ok([1, 2, 3])

const withError = [
  okAsync(Promise.resolve(1)),
  errAsync("second failed"),
  okAsync(Promise.resolve(3))
];

const failed = ResultAsync.combine(withError);
const errorResult = await failed;
// errorResult is Err("second failed")

combineWithAllErrors()

Combines multiple ResultAsync instances into a single ResultAsync. Collects all errors encountered, or returns all values if all ResultAsyncs are Ok.

Unlike combine(), this method doesn't stop at the first error but collects all errors from failed ResultAsyncs into an array.

Type Parameters

T: T extends ResultAsync<unknown, unknown>[]

The type of the ResultAsync array

asyncResultList: T — Array of ResultAsync instances to combine
Returns: ResultAsync<unknown[], unknown[]> — A ResultAsync containing an array of all values, or an array of all errors

Example

const results = [
  okAsync(1),
  errAsync("error1"),
  okAsync(3),
  errAsync("error2")
];

const combined = ResultAsync.combineWithAllErrors(results);
const resolved = await combined;
// resolved is Err(["error1", "error2"])

const allSuccess = [okAsync(1), okAsync(2), okAsync(3)];
const success = ResultAsync.combineWithAllErrors(allSuccess);
const values = await success;
// values is Ok([1, 2, 3])

map()

Transforms the success value using the provided function. If this resolves to an error result, the error is preserved unchanged. The transformation function can be synchronous or asynchronous.

Optimized for efficient Promise handling and type safety.

Type Parameters

A: A

The type of the transformed value

f: (t) => A | Promise<A> — Function to transform the success value (can return Promise<A>)
Returns: ResultAsync<A, E> — A new ResultAsync with the transformed value or the original error

Example

const result = okAsync(Promise.resolve(5));

// Synchronous transformation
const doubled = result.map(x => x * 2);
const resolved = await doubled; // Ok(10)

// Asynchronous transformation
const fetched = result.map(async x => {
  const response = await fetch(`/api/data/${x}`);
  return response.json();
});

const data = await fetched; // Ok(data)

mapErr()

Transforms the error value using the provided function. If this resolves to a success result, the value is preserved unchanged. The transformation function can be synchronous or asynchronous.

Optimized for efficient Promise handling and type safety.

Type Parameters

U: U

The type of the transformed error

f: (e) => U | Promise<U> — Function to transform the error value (can return Promise<U>)
Returns: ResultAsync<T, U> — A new ResultAsync with the original value or the transformed error

Example

const error = errAsync("network error");

// Synchronous transformation
const enhanced = error.mapErr(e => `Error: ${e}`);
const resolved = await enhanced; // Err("Error: network error")

// Asynchronous transformation
const logged = error.mapErr(async e => {
  await logError(e);
  return `Logged: ${e}`;
});

const result = await logged; // Err("Logged: network error")

andThen()

Chains operations by applying the provided function to the success value. If this resolves to an error result, the error is propagated unchanged.

Optimized for efficient Promise chaining and type safety.

Type Parameters

U: U

The type of the success value in the returned ResultAsync

F: F

The type of the error value in the returned ResultAsync

f: (t) => ResultAsync<U, F> — Function that takes the success value and returns a new ResultAsync
Returns: ResultAsync<U, E | F> — A new ResultAsync with combined error types

Example

const result = okAsync(Promise.resolve(5));

const chained = result.andThen(x =>
  x > 0 ? okAsync(Promise.resolve(x * 2)) : errAsync("negative")
);

const resolved = await chained; // Ok(10)

// Chain multiple operations
const pipeline = result
  .andThen(x => okAsync(Promise.resolve(x * 2)))
  .andThen(x => okAsync(Promise.resolve(x.toString())));

const final = await pipeline; // Ok("10")

unwrapOr()

Returns the success value if this resolves to an Ok result, otherwise returns the default value.

Type Parameters

A: A

The type of the default value

v: A — Default value to return if this resolves to an error result
Returns: Promise<T | A> — A Promise that resolves to the success value or the default value

Example

const success = okAsync(Promise.resolve(42));
const value = await success.unwrapOr(0); // 42

const error = errAsync("failed");
const fallback = await error.unwrapOr(0); // 0

match()

Pattern matching function that executes different code paths based on the resolved result state.

Type Parameters

A: A

The return type for the success case

B: B = A

The return type for the error case (defaults to A)

ok: (t) => A — Function to execute if this resolves to a success result
err: (e) => B — Function to execute if this resolves to an error result
Returns: Promise<A | B> — A Promise that resolves to the result of executing the appropriate function

Example

const result = okAsync(Promise.resolve(42));

const message = await result.match(
  value => `Success: ${value}`,
  error => `Error: ${error}`
); // "Success: 42"

const processed = await result.match(
  async value => {
    const doubled = value * 2;
    await saveToDatabase(doubled);
    return doubled;
  },
  error => 0
); // 84

orElse()

Provides an alternative ResultAsync when this resolves to an error. If this resolves to a success result, the original value is returned unchanged.

Type Parameters

U: U

The type of the success value in the returned ResultAsync

F: F

The type of the error value in the returned ResultAsync

f: (e) => ResultAsync<U, F> — Function that returns a ResultAsync to use as fallback
Returns: ResultAsync<T | U, F> — A new ResultAsync with the original value or the fallback result

Example

const result = errAsync("network error");
const fallback = result.orElse(() => okAsync("cached data"));
const resolved = await fallback; // Ok("cached data")

const success = okAsync(42);
const noFallback = success.orElse(() => errAsync("fallback"));
const value = await noFallback; // Ok(42)

then()

Implements the PromiseLike interface, allowing ResultAsync to be used with Promise methods like .then(), .catch(), and await.

Provides seamless integration with native Promise APIs and async/await syntax.

Type Parameters

TResult1: TResult1 = Result<T, E>

The type of the fulfilled result

TResult2: TResult2 = never

The type of the rejected result

onfulfilled?: Optional callback for when the Promise is fulfilled — (value) => TResult1 | PromiseLike<TResult1> | null
onrejected?: Optional callback for when the Promise is rejected — (reason) => TResult2 | PromiseLike<TResult2> | null
Returns: Promise<TResult1 | TResult2> — A Promise that resolves to the result of the callbacks

Example

const result = okAsync(Promise.resolve("hello"));

// Use with .then()
result.then(
  res => res.isOk() ? res.value : "error",
  error => "promise rejected"
);

// Use with .catch()
result.catch(error => console.error(error));

Implementation of

PromiseLike.then