ResultAsync

ResultAsync<T, E> is a PromiseLike<Result<T, E>>. You can await or .then() it directly to get a synchronous Result<T, E>, or chain methods on it without ever leaving the async context. Nearly Every method that exists on Result has an equivalent on ResultAsync, and each returns another ResultAsync so chains stay fluent.

import { chas } from 'ts-chas';

const result: chas.Result<number, string> = await chas.okAsync(42);
// Ok(42)

Creating a `ResultAsync`

`chas.okAsync(value)`

Wraps a value or Promise<T> in a ResultAsync that resolves to Ok.

T | Promise<T>

required

The success value or promise to wrap.

ResultAsync<T, never>

Resolves to Ok(value).

const res = chas.okAsync(42);
const result = await res; // Ok(42)

`chas.errAsync(error)`

Wraps an error or Promise<E> in a ResultAsync that resolves to Err.

E | Promise<E>

required

The error value or promise to wrap.

ResultAsync<never, E>

Resolves to Err(error).

const res = chas.errAsync('request failed');
const result = await res; // Err('request failed')

`chas.fromPromise(promise, mapErr?)`

Wraps a native Promise in a ResultAsync. Resolves to Ok on fulfillment and Err on rejection.

Promise<T>

required

The promise to wrap.

(error: unknown) => E

Maps the rejection reason to your error type. When omitted, the error is typed as unknown.

ResultAsync<T, E>

A ResultAsync wrapping the promise outcome.

const res = chas.fromPromise(
  fetch('/api/user').then(r => r.json()),
  (e) => `Fetch failed: ${e}`
);

`ResultAsync.fromResult(syncResult)`

Lifts a synchronous Result into ResultAsync.

Result<T, E>

required

The synchronous result to wrap.

ResultAsync<T, E>

A ResultAsync that immediately resolves to the provided result.

const sync = chas.ok(42);
const async = chas.ResultAsync.fromResult(sync);
const result = await async; // Ok(42)

`ResultAsync.fromSafePromise(promise)`

Wraps a promise that is guaranteed not to reject. No mapErr is needed.

Promise<T>

required

A promise that will not reject.

ResultAsync<T, never>

Resolves to Ok(value).

const res = chas.ResultAsync.fromSafePromise(Promise.resolve(42));
const result = await res; // Ok(42)

Instance methods

All methods below return a ResultAsync, so you can chain them without await until you need the final value.

`.map(fn)`

Transforms the Ok value. Err passes through unchanged.

(value: T) => U | Promise<U>

required

Function applied to the Ok value. May be async.

ResultAsync<U, E>

Ok(fn(value)) or the original Err.

const res = chas.okAsync(5).map(v => v * 2);
const result = await res; // Ok(10)

`.mapErr(fn)`

Transforms the Err error. Ok passes through unchanged.

(error: E) => F | Promise<F>

required

Function applied to the Err error. May be async.

ResultAsync<T, F>

The original Ok or Err(fn(error)).

const res = chas.errAsync('not_found').mapErr(e => e.toUpperCase());
const result = await res; // Err('NOT_FOUND')

`.andThen(fn)`

Chains another Result- or ResultAsync-returning function. Calls fn with the Ok value, or short-circuits on Err.

(value: T) => Result<U, F> | ResultAsync<U, F>

required

Function returning a new result. May return sync or async.

ResultAsync<U, E | F>

The chained result, or the original Err.

const res = chas.okAsync(5).andThen(v => chas.okAsync(v * 2));
const result = await res; // Ok(10)

`.orElse(fn)`

Recovers from an Err by calling fn with the error. Ok passes through unchanged.

(error: E) => Result<T2, F> | ResultAsync<T2, F>

required

Recovery function returning a new result.

ResultAsync<T | T2, F>

The original Ok, or the recovery result.

const res = chas.errAsync('timeout').orElse(() => chas.okAsync('default'));
const result = await res; // Ok('default')

`.tap(fn)`

Runs a side effect when Ok. Returns the original result unchanged.

(value: T) => void | Promise<void>

required

Side-effect function. May be async.

ResultAsync<T, E>

The original result, unmodified.

const res = await fetchUser()
  .tap(async u => await auditLog.record(u.id));

`.tapErr(fn)`

Runs a side effect when Err. Returns the original result unchanged.

(error: E) => void | Promise<void>

required

Side-effect function. May be async.

ResultAsync<T, E>

The original result, unmodified.

const res = await fetchUser()
  .tapErr(async e => await errorLog.send(e));

`.match({ ok, err })`

Exhaustively handles both branches and resolves to a plain value.

(value: T) => U | Promise<U>

required

Handler called when the result is Ok.

(error: E) => F | Promise<F>

required

Handler called when the result is Err.

Promise<U | F>

A standard Promise (not a ResultAsync) resolving to the matched handler’s return value.

const message = await chas.okAsync(42).match({
  ok: v => `Got ${v}`,
  err: e => `Failed: ${e}`,
});
// 'Got 42'

`.unwrap()`

Returns a Promise that resolves to the Ok value, or throws the Err error.

Promise<T>

Resolves to the Ok value.

Throws the contained error if the result is Err. Prefer .unwrapOr() or .match() in production code.

const value = await chas.okAsync(5).unwrap(); // 5

`.unwrapOr(defaultValue)`

Returns a Promise that resolves to the Ok value, or defaultValue if Err.

required

Fallback value returned when the result is Err.

Promise<T>

Resolves to the Ok value or the default.

const value = await chas.errAsync('missing').unwrapOr(0); // 0

`.pipe(fn1, fn2, ...)`

Passes the ResultAsync through a sequence of functions, identical in behaviour to Result#pipe.

const add5 = (r: chas.ResultAsync<number, never>) => r.map(v => v + 5);
const double = (r: chas.ResultAsync<number, never>) => r.map(v => v * 2);

const result = await chas.okAsync(1).pipe(add5, double);
// Ok(12)

`.context(ctx)`

Attaches a debug label or metadata object to the error when Err. No-op when Ok.

string | Record<string, unknown>

required

A description string or metadata object for the current step.

ResultAsync<T, E>

The same result with context prepended to error._context (if Err).

const result = await fetchUser(id)
  .context('fetching user')
  .andThen(u => validatePermissions(u))
  .context('checking permissions');

`.catchTag(target, handler)`

Catches a specific tagged error variant by _tag or error factory, and removes it from the error union. Unmatched tags pass through unchanged.

string | ErrorFactory

required

The _tag string to match, or an error factory.

(error: MatchedError) => Result<T2, E2> | ResultAsync<T2, E2>

required

Recovery function.

ResultAsync<T | T2, Exclude<E, { _tag: ... }> | E2>

A result with the matched tag removed from the error union.

await fetchUser(id)
  .catchTag('NotFound', () => chas.ok(GUEST_USER));
// ResultAsync<User | GuestUser, Unauthorized>

`.tapTag(target, handler)`

Runs a side effect for a specific tagged error. The original result is returned unchanged.

string | ErrorFactory

required

The _tag string to match, or an error factory.

(error: MatchedError) => void | Promise<void>

required

Side-effect function called when the tag matches.

ResultAsync<T, E>

The original result, unmodified.

await fetchUser(id)
  .tapTag('Unauthorized', () => redirectToLogin());

Complete example

import { chas } from 'ts-chas';

interface User { id: number; name: string }

function fetchUser(id: number): chas.ResultAsync<User, string> {
  return chas.fromPromise(
    fetch(`/api/users/${id}`).then(r => {
      if (!r.ok) throw new Error(`HTTP ${r.status}`);
      return r.json() as Promise<User>;
    }),
    (e) => `Fetch error: ${e}`
  );
}

const result = await fetchUser(1)
  .map(user => ({ ...user, name: user.name.toUpperCase() }))
  .mapErr(e => ({ code: 'FETCH_FAILED', detail: e }))
  .tap(user => console.log('Fetched:', user.name));

result.match({
  ok: user => console.log('User:', user.name),  // 'ALICE'
  err: e => console.error('Failed:', e.detail),
});

Result

Guard

Task

Other Modules

Creating a `ResultAsync`

`chas.okAsync(value)`

`chas.errAsync(error)`

`chas.fromPromise(promise, mapErr?)`

`ResultAsync.fromResult(syncResult)`

`ResultAsync.fromSafePromise(promise)`

Instance methods

`.map(fn)`

`.mapErr(fn)`

`.andThen(fn)`

`.orElse(fn)`

`.tap(fn)`

`.tapErr(fn)`

`.match({ ok, err })`

`.unwrap()`

`.unwrapOr(defaultValue)`

`.pipe(fn1, fn2, ...)`

`.context(ctx)`

`.catchTag(target, handler)`

`.tapTag(target, handler)`

Complete example

​Creating a ResultAsync

​chas.okAsync(value)

​chas.errAsync(error)

​chas.fromPromise(promise, mapErr?)

​ResultAsync.fromResult(syncResult)

​ResultAsync.fromSafePromise(promise)

​Instance methods

​.map(fn)

​.mapErr(fn)

​.andThen(fn)

​.orElse(fn)

​.tap(fn)

​.tapErr(fn)

​.match({ ok, err })

​.unwrap()

​.unwrapOr(defaultValue)

​.pipe(fn1, fn2, ...)

​.context(ctx)

​.catchTag(target, handler)

​.tapTag(target, handler)

​Complete example

Creating a `ResultAsync`

`chas.okAsync(value)`

`chas.errAsync(error)`

`chas.fromPromise(promise, mapErr?)`

`ResultAsync.fromResult(syncResult)`

`ResultAsync.fromSafePromise(promise)`

Instance methods

`.map(fn)`

`.mapErr(fn)`

`.andThen(fn)`

`.orElse(fn)`

`.tap(fn)`

`.tapErr(fn)`

`.match({ ok, err })`

`.unwrap()`

`.unwrapOr(defaultValue)`

`.pipe(fn1, fn2, ...)`

`.context(ctx)`

`.catchTag(target, handler)`

`.tapTag(target, handler)`

Complete example