Skip to content
@sandlada/result

Bridge Result: sync → Promise<Result>

Sync Result to Promise-of-Result lift operators.

Functions

Section titled “Functions”

bind()

Section titled “bind()”

Chains a result-producing async function over a sync IResultOfT. The callback returns Promise<IResultOfT<B, F>>, and the result is wrapped into a Promise<IResultOfT<B, F>>.

Bridges from the sync result world to the async world — unlike bindAsync which works on Promise<IResultOfT>. Where bindAsync accepts callbacks that may return sync or async results, bind requires an async callback.

Throw policy: a synchronous throw from f propagates via the outer promise rejection. A rejected Promise from f propagates as a rejection. Matches the canonical AsyncResult throw policy.

Type contract: the success path produces Promise<IResultOfT<B, F>>. The input’s error type E is not widened into the success branch - at runtime E only flows through on the failure short-circuit, where f is never invoked.

The callback is invoked inside the promise chain, so the returned promise is unwrapped by the await chain exactly once: await bind(...) yields the IResultOfT, not a promise of a promise.

export function bind<A, B, F>(
    f: (a: A) => Promise<IResultOfT<B, F>>,
): <E>(r: IResultOfT<A, E>) => Promise<IResultOfT<B, F>>;
export function bind<A, B, E, F>(
    f: (a: A) => Promise<IResultOfT<B, F>>,
    r: IResultOfT<A, E>,
): Promise<IResultOfT<B, F>>;

Defined in: bridge-result/bind.ts

Example

Section titled “Example”
import { bind } from '@sandlada/result/bridge-result';
import { match } from '@sandlada/result/operators';
import { ok, err } from '@sandlada/result/factories';


const input = ok(21);
const chained = await bind(async (x: number) => ok(x * 2), input);
const label = match((n) => `ok:${n}`, (e) => `err:${String(e)}`, chained);
// label === 'ok:42'


const blocked = err('upstream');
const skipped = await bind(async (x: number) => ok(x * 2), blocked);
// skipped stays Err('upstream'); bind does not invoke the callback

bindThrough()

Section titled “bindThrough()”

Side-effect on the success track — calls an async function on success that can propagate errors. If fn returns a failure, that failure propagates. If fn returns a success, the original success value passes through unchanged.

The key difference from bind is that bindThrough preserves the original success value on success, while bind replaces it.

Bridges from the sync result world to the async world — unlike bindAsync which works on Promise<IResultOfT>.

export function bindThrough<A, B, F>(
    fn: (a: A) => Promise<IResultOfT<B, F>>,
): <E>(r: IResultOfT<A, E>) => Promise<IResultOfT<A, E | F>>;
export function bindThrough<A, B, E, F>(
    fn: (a: A) => Promise<IResultOfT<B, F>>,
    r: IResultOfT<A, E>,
): Promise<IResultOfT<A, E | F>>;

Defined in: bridge-result/bindThrough.ts

Example

Section titled “Example”
import { bindThrough } from '@sandlada/result/bridge-result';
import { match } from '@sandlada/result/operators';
import { ok, err } from '@sandlada/result/factories';


const input = ok('data');
const validated = await bindThrough(
    async (v: string) => (v.length > 0 ? ok(v) : err('empty')),
    input,
);
const label = match((s) => `kept:${s}`, (e) => `failed:${String(e)}`, validated);
// label === 'kept:data'


const empty = ok('');
const rejected = await bindThrough(
    async (v: string) => (v.length > 0 ? ok(v) : err('empty')),
    empty,
);
// rejected is Err('empty'); bindThrough propagates the inner failure

map()

Section titled “map()”

Transforms the success value of a sync IResultOfT using an async callback. The callback returns a Promise, and the result is wrapped into a Promise<IResultOfT>.

This bridges from the sync result world to the async world — unlike mapAsync which works on Promise<IResultOfT>.

export function map<A, B>(
    f: (a: A) => Promise<B>,
): <E>(r: IResultOfT<A, E>) => Promise<IResultOfT<B, E>>;
export function map<A, B, E>(
    f: (a: A) => Promise<B>,
    r: IResultOfT<A, E>,
): Promise<IResultOfT<B, E>>;

Defined in: bridge-result/map.ts

Example

Section titled “Example”
import { map } from '@sandlada/result/bridge-result';
import { match } from '@sandlada/result/operators';
import { ok, err } from '@sandlada/result/factories';


const input = ok(5);
const lifted = await map(async (x: number) => x * 2, input);
const label = match((n) => `ok:${n}`, (e) => `err:${String(e)}`, lifted);
// label === 'ok:10'


const failure = err('skip');
const passthrough = await map(async (x: number) => x * 2, failure);
// passthrough stays Err('skip'); map short-circuits on failure

match()

Section titled “match()”

Async match for sync IResultOfT. Lifts a sync Result into the async world and pattern-matches with async-allowed handlers.

export function match<T, E, U>(
    handlers: { ok: (value: T) => U | Promise<U>; err: (error: E) => U | Promise<U> },
): (r: IResultOfT<T, E>) => Promise<U>;
export function match<T, E, U>(
    handlers: { ok: (value: T) => U | Promise<U>; err: (error: E) => U | Promise<U> },
    r: IResultOfT<T, E>,
): Promise<U>;

Defined in: bridge-result/match.ts

Example

Section titled “Example”
import { match as bridgeMatch, map } from '@sandlada/result/bridge-result';
import { ok, err } from '@sandlada/result/factories';


const input = ok(21);
const scaled = await map(async (x: number) => x * 2, input);
const label = await bridgeMatch(
    { ok: async (x: number) => `value:${x}`, err: async (e: string) => `failed:${e}` },
    scaled,
);
// label === 'value:42'


const failed = err('boom');
const message = await bridgeMatch(
    { ok: async (x: number) => `value:${x}`, err: async (e: string) => `failed:${e}` },
    failed,
);
// message === 'failed:boom'

orElse()

Section titled “orElse()”

Async orElse for sync IResultOfT. Lifts a sync Result into the async world and recovers from failure via an async callback.

Companion to bind — bind chains forward on Ok; orElse recovers on Err.

export function orElse<T, E, F>(
    f: (e: E) => Promise<IResultOfT<T, F>>,
): (r: IResultOfT<T, E>) => Promise<IResultOfT<T, E | F>>;
export function orElse<T, E, F>(
    f: (e: E) => Promise<IResultOfT<T, F>>,
    r: IResultOfT<T, E>,
): Promise<IResultOfT<T, E | F>>;

Defined in: bridge-result/orElse.ts

Example

Section titled “Example”
import { orElse } from '@sandlada/result/bridge-result';
import { match } from '@sandlada/result/operators';
import { ok, err } from '@sandlada/result/factories';


const failed = err('boom');
const recovered = await orElse(async (e: string) => ok(`recovered:${e}`), failed);
const label = match((s) => s, (e) => `still:${String(e)}`, recovered);
// label === 'recovered:boom'


const success = ok(42);
const untouched = await orElse(async (_e: string) => ok(0), success);
// untouched stays Ok(42); orElse short-circuits on success
const same = match((n) => n, (_e) => 0, untouched);
// same === 42

tap()

Section titled “tap()”

Side-effect on success for a sync IResultOfT using an async callback. Returns the original Result. If the callback throws or returns a rejected Promise, the error is caught and returned as an Err result.

export function tap<A, E>(
    fn: (a: A) => Promise<void | unknown>,
): (r: IResultOfT<A, E>) => Promise<IResultOfT<A, E>>;
export function tap<A, E>(
    fn: (a: A) => Promise<void | unknown>,
    r: IResultOfT<A, E>,
): Promise<IResultOfT<A, E>>;

Defined in: bridge-result/tap.ts

Example

Section titled “Example”
import { tap } from '@sandlada/result/bridge-result';
import { match } from '@sandlada/result/operators';
import { ok, err } from '@sandlada/result/factories';


const input = ok(42);
const touched = await tap(async (x: number) => { void x; }, input);
const label = match((n) => `still:${n}`, (e) => `err:${String(e)}`, touched);
// label === 'still:42'; tap returns the original Ok unchanged


const failure = err('skip');
const passthrough = await tap(async (x: number) => { void x; }, failure);
// passthrough stays Err('skip'); tap short-circuits on failure

tapErr()

Section titled “tapErr()”

Side-effect on failure for a sync IResultOfT using an async callback. Returns the original Result. If the callback throws or returns a rejected Promise, the error is caught and returned as an Err result.

export function tapErr<A, E>(
    fn: (e: E) => Promise<void | unknown>,
): (r: IResultOfT<A, E>) => Promise<IResultOfT<A, E>>;
export function tapErr<A, E>(
    fn: (e: E) => Promise<void | unknown>,
    r: IResultOfT<A, E>,
): Promise<IResultOfT<A, E>>;

Defined in: bridge-result/tapErr.ts

Example

Section titled “Example”
import { tapErr } from '@sandlada/result/bridge-result';
import { match } from '@sandlada/result/operators';
import { ok, err } from '@sandlada/result/factories';


const failed = err('oops');
const touched = await tapErr(async (e: string) => { void e; }, failed);
const label = match((n) => `ok:${n}`, (e) => `still:${String(e)}`, touched);
// label === 'still:oops'; tapErr returns the original Err unchanged


const success = ok(1);
const passthrough = await tapErr(async (e: string) => { void e; }, success);
// passthrough stays Ok(1); tapErr short-circuits on success