PendingResult

@ts-rust/std

---

@ts-rust/std / Result / PendingResult

Interface: PendingResult<T, E>

Defined in: packages/std/src/result/interface.ts:905

Interface defining an asynchronous Result that wraps a Promise resolving to a Result.

Extends Result functionality for pending states, with methods mirroring their synchronous counterparts but returning PendingResult or Promise for async operations. Rejections typically resolve to Err unless otherwise specified.

Extends

• PromiseLike<Result<T, E>>.Recoverable<Result<T, E>>

Type Parameters

Type Parameter
T
E

Methods

and()

and<U>(x): PendingResult<Awaited<U>, Awaited<E>>;

Defined in: packages/std/src/result/interface.ts:925

Returns a PendingResult that resolves to Err if this result resolves to Err, otherwise returns a PendingResult with x.

This is the asynchronous version of and.

Type Parameters

Type Parameter
U

Parameters

Parameter	Type
x	| Result<U, E> | PendingResult<U, E> | Promise<Result<U, E>>

Returns

PendingResult<Awaited<U>, Awaited<E>>

Example

const x = ok<number, string>(1).toPending();
const y = ok<number, string>(2);
const z = err<number, string>("failure").toPending();

expect(await x.and(y)).toStrictEqual(ok(2));
expect(await x.and(z)).toStrictEqual(err("failure"));
expect(await z.and(x)).toStrictEqual(err("failure"));

---

andThen()

andThen<U>(f): PendingResult<Awaited<U>, Awaited<E>>;

Defined in: packages/std/src/result/interface.ts:946

Returns a PendingResult that resolves to Err if this result resolves to Err, otherwise applies f to the resolved Ok value and returns its result.

This is the asynchronous version of andThen.

Type Parameters

Type Parameter
U

Parameters

Parameter	Type
f	(x) => | Result<U, E> | PendingResult<U, E> | Promise<Result<U, E>>

Returns

PendingResult<Awaited<U>, Awaited<E>>

Example

const x = ok<number, string>(2).toPending();
const y = err<number, string>("failure").toPending();

expect(await x.andThen((n) => ok(n * 2))).toStrictEqual(ok(4));
expect(await x.andThen((_) => err("oops"))).toStrictEqual(err("oops"));
expect(await y.andThen((_) => err("oops"))).toStrictEqual(err("failure"));

---

catch()

catch<R>(onrejected?): Promise<
  | Result<T, E>
  | R>;

Defined in: packages/std/src/types.ts:145

Type Parameters

Type Parameter	Default type
R	never

Parameters

Parameter	Type
onrejected?	(reason) => R | PromiseLike<R>

Returns

Promise< | Result<T, E> | R>

Inherited from

Recoverable.catch

---

check()

check(): Promise<readonly [boolean,
  | Awaited<T>
  | CheckedError<Awaited<E>>]>;

Defined in: packages/std/src/result/interface.ts:970

Inspects this PendingResult’s state, returning a promise of a tuple with a success flag and either the value or error.

This is the asynchronous version of check.

Returns

Promise<readonly [boolean, | Awaited<T> | CheckedError<Awaited<E>>]>

Notes

• Resolves to [true, Awaited<T>] if this is an Ok, or to [false, CheckedError<Awaited<E>>] if this is an Err.
• Never rejects, providing a safe way to await the result’s state.

Example

const x = ok<number, string>(42).toPending();
const y = err<number, string>("failure").toPending();

expect(await x.check()).toEqual([true, 42]);
expect(await y.check()).toEqual([
  false,
  expect.objectContaining({ expected: "failure" }),
]);

---

combine()

combine<U>(...opts): PendingResult<[Awaited<T>, ...OkAwaitedValues<U, unknown>[]], E>;

Defined in: packages/std/src/result/interface.ts:992

Combines this PendingResult with other Result or PendingResult instances into a single PendingResult containing a tuple of resolved values.

The combine method takes an arbitrary number of Result or PendingResult instances. It resolves all inputs and returns a PendingResult that, when resolved, contains a Result with a tuple of their Ok values if all resolve to Ok. If any input resolves to Err, the result resolves to that Err. The resulting tuple includes the resolved value of this PendingResult as the first element, followed by the resolved values from the provided instances.

Type Parameters

Type Parameter
U extends ( | Result<unknown, E> | PendingResult<unknown, E>)[]

Parameters

Parameter	Type
...opts	U

Returns

PendingResult<[Awaited<T>, ...OkAwaitedValues<U, unknown>[]], E>

Example

const a = pendingOk<number, Error>(1);
const b = ok<Promise<string>, Error>(Promise.resolve("hi"));
const c = err<symbol, Error>(new Error("An error occurred"));
const d = pendingErr<Promise<Date>, Error>(new Error("not a date"));
const e = a.combine(b, c, d); // PendingResult<[number, string, symbol, Date], Error>

---

err()

err(): PendingOption<Awaited<E>>;

Defined in: packages/std/src/result/interface.ts:1016

Converts this PendingResult to a PendingOption\<E\> containing the awaited error, if present.

Returns a PendingOption that resolves to Some with the error value if this resolves to an Err with ExpectedError, or to None if this resolves to an Ok or Err with UnexpectedError.

This is the asynchronous version of err.

Returns

PendingOption<Awaited<E>>

Example

const x = ok<number, string>(1).toPending();
const y = err<number, string>("failure").toPending();

expect(await x.err()).toStrictEqual(none());
expect(await y.err()).toStrictEqual(some("failure"));

---

flatten()

flatten<U, F>(this): PendingResult<Awaited<U>, Awaited<F>>;

Defined in: packages/std/src/result/interface.ts:1038

Flattens a nested PendingResult into a single pending result, resolving any inner Result or PendingResult to its final state.

This is the asynchronous version of flatten.

Type Parameters

Type Parameter
U
F

Parameters

Parameter	Type
this	| PendingResult<Result<U, F>, F> | PendingResult<PendingResult<U, F>, F> | PendingResult<PromiseLike<Result<U, F>>, F>

Returns

PendingResult<Awaited<U>, Awaited<F>>

Notes

• Handles cases like PendingResult<Result<T, E>, E> or PendingResult<PendingResult<T, E>, E>, resolving to PendingResult<Awaited<T>, Awaited<E>>.

Example

const x = ok(ok(6)).toPending();
const y = ok(err<number, string>("oops")).toPending();

expect(await x.flatten()).toStrictEqual(ok(6));
expect(await y.flatten()).toStrictEqual(err("oops"));

---

inspect()

inspect(f): PendingResult<T, E>;

Defined in: packages/std/src/result/interface.ts:1069

Calls f with the value if this pending result resolves to an Ok, then returns a new pending result with the original state.

This is the asynchronous version of inspect.

Parameters

Parameter	Type
f	(x) => unknown

Returns

PendingResult<T, E>

Notes

• Returns a new PendingResult instance, not the original reference.
• If f throws or returns a Promise that rejects, the error is ignored, and the returned promise still resolves to the original state.

Example

const x = ok<number, string>(2).toPending();
const y = err<number, string>("failure").toPending();
let sideEffect = 0;

expect(await x.inspect((n) => (sideEffect = n))).toStrictEqual(ok(2));
expect(
  await x.inspect((_) => {
    throw new Error();
  }),
).toStrictEqual(ok(2));
expect(sideEffect).toBe(2);
expect(await y.inspect((n) => (sideEffect = n))).toStrictEqual(err("failure"));
expect(sideEffect).toBe(2); // Unchanged

---

inspectErr()

inspectErr(f): PendingResult<T, E>;

Defined in: packages/std/src/result/interface.ts:1096

Calls f with the error if this pending result resolves to an Err, then returns a new pending result with the original state.

This is the asynchronous version of inspectErr.

Parameters

Parameter	Type
f	(x) => unknown

Returns

PendingResult<T, E>

Notes

• Returns a new PendingResult instance, not the original reference.
• If f throws or returns a Promise that rejects, the error is ignored, and the returned promise still resolves to the original state.

Example

const x = ok<number, string>(2).toPending();
const y = err<number, string>("failure").toPending();
let sideEffect: CheckedError<string> | null = null;

expect(await x.inspectErr((n) => (sideEffect = n))).toStrictEqual(ok(2));
expect(
  await x.inspectErr((_) => {
    throw new Error();
  }),
).toStrictEqual(ok(2));
expect(sideEffect).toBeNull();
expect(await y.inspectErr((n) => (sideEffect = n))).toStrictEqual(
  err("failure"),
);
expect(
  await y.inspectErr((_) => {
    throw new Error();
  }),
).toStrictEqual(err("failure"));
expect(isCheckedError(sideEffect)).toBe(true);

---

iter()

iter(): AsyncIterableIterator<Awaited<T>, Awaited<T>, void>;

Defined in: packages/std/src/result/interface.ts:1129

Returns an async iterator over this pending result’s value, yielding it if it resolves to Ok or nothing if it resolves to Err.

Returns

AsyncIterableIterator<Awaited<T>, Awaited<T>, void>

Notes

• Yields exactly one item for a resolved Ok, or zero items for a resolved Err.
• Compatible with for await...of loops and async spread operators (with caution).
• Ignores the error value in Err cases, focusing only on the success case.

Example

const x = ok<number, string>(42).toPending();
const y = err<number, string>("failure").toPending();

const iterX = x.iter();
expect(await iterX.next()).toEqual({ value: 42, done: false });
expect(await iterX.next()).toEqual({ done: true });

const iterY = y.iter();
expect(await iterY.next()).toEqual({ done: true });

async function collect(iter) {
  const result = [];
  for await (const val of iter) result.push(val);
  return result;
}
expect(await collect(x.iter())).toEqual([42]);
expect(await collect(y.iter())).toEqual([]);

---

map()

map<U>(f): PendingResult<Awaited<U>, Awaited<E>>;

Defined in: packages/std/src/result/interface.ts:1151

Maps the resolved value with f, returning a PendingResult with the result if Ok, or the original Err if Err.

This is the asynchronous version of map.

Type Parameters

Type Parameter
U

Parameters

Parameter	Type
f	(x) => U

Returns

PendingResult<Awaited<U>, Awaited<E>>

Notes

• If f throws or returns a rejected promise, returns a PendingResult with an Err containing an UnexpectedError.

Example

const x = ok<number, string>(2).toPending();
const y = err<number, string>("failure").toPending();

expect(await x.map((n) => n * 2)).toStrictEqual(ok(4));
expect(
  (
    await x.map(() => {
      throw new Error("boom");
    })
  ).unwrapErr().unexpected,
).toBeDefined();
expect(await y.map((n) => n * 2)).toStrictEqual(err("failure"));

---

mapAll()

mapAll<U, F>(f): PendingResult<Awaited<U>, Awaited<F>>;

Defined in: packages/std/src/result/interface.ts:1183

Maps this pending result by applying a callback to its full state, executing the callback for both Ok and Err, returning a new PendingResult.

Unlike andThen, which only invokes the callback for Ok, this method always calls f, passing the entire Result as its argument.

This is the asynchronous version of mapAll.

Type Parameters

Type Parameter
U
F

Parameters

Parameter	Type
f	(x) => | Result<U, F> | PendingResult<U, F> | Promise<Result<U, F>>

Returns

PendingResult<Awaited<U>, Awaited<F>>

Notes

• If f throws or returns a Promise that rejects, the newly created PendingResult will resolve to an Err with an UnexpectedError.

Example

const okRes = ok<number, string>(42).toPending();
const errRes = err<number, string>("failure").toPending();

const okMapped = okRes.mapAll((res) =>
  Promise.resolve(ok(res.unwrapOr(0) + 1)),
);
expect(await okMapped).toStrictEqual(ok(43));

const errMapped = errRes.mapAll((res) =>
  Promise.resolve(ok(res.unwrapOr(0) + 1)),
);
expect(await errMapped).toStrictEqual(ok(1));

const throwMapped = okRes.mapAll(() => {
  throw new Error("boom");
});
expect((await throwMapped).unwrapErr().unexpected).toBeDefined();

---

mapErr()

mapErr<F>(f): PendingResult<Awaited<T>, Awaited<F>>;

Defined in: packages/std/src/result/interface.ts:1211

Transforms this pending result by applying f to the error if it resolves to an Err with an expected error, or preserves the Ok unchanged.

This is the asynchronous version of mapErr.

Type Parameters

Type Parameter
F

Parameters

Parameter	Type
f	(x) => F

Returns

PendingResult<Awaited<T>, Awaited<F>>

Notes

• If f throws or returns a rejected promise, returns a PendingResult with an Err containing an UnexpectedError.
• If this resolves to an Err with an UnexpectedError, f is not called, and the original error is preserved.

Example

const x = ok<number, string>(2).toPending();
const y = err<number, string>("failure").toPending();

expect(await x.mapErr((e) => e.length)).toStrictEqual(ok(2));
expect(await y.mapErr((e) => e.length)).toStrictEqual(err(7));
expect(
  (
    await y.mapErr(() => {
      throw new Error("boom");
    })
  ).unwrapErr().unexpected,
).toBeDefined();

---

match()

match<U, F>(f, g): Promise<Awaited<U> | Awaited<F>>;

Defined in: packages/std/src/result/interface.ts:1238

Matches this PendingResult, returning a promise of f applied to the value if it resolves to an Ok, or g applied to the error if it resolves to an Err.

This is the asynchronous version of match.

Type Parameters

Type Parameter	Default type
U	‐
F	U

Parameters

Parameter	Type
f	(x) => U
g	(e) => F

Returns

Promise<Awaited<U> | Awaited<F>>

Throws

• Rejects ResultError if f or g throws an exception or rejects, original error will be set as ResultError.reason.

Notes

• If f or g throws or returns a rejected Promise, the returned promise rejects with the original error. In this case the caller is responsible for handling the rejection.

Example

const x = ok<number, string>(2).toPending();
const y = err<number, string>("failure").toPending();

expect(
  await x.match(
    (n) => n * 2,
    () => 0,
  ),
).toBe(4);
expect(
  await y.match(
    (n) => n * 2,
    (e) => e.expected?.length,
  ),
).toBe(7);

---

or()

or<F>(x): PendingResult<Awaited<T>, Awaited<F>>;

Defined in: packages/std/src/result/interface.ts:1266

Returns this pending result if it resolves to an Ok, otherwise returns x.

This is the asynchronous version of or.

Type Parameters

Type Parameter
F

Parameters

Parameter	Type
x	| Result<T, F> | PendingResult<T, F> | Promise<Result<T, F>>

Returns

PendingResult<Awaited<T>, Awaited<F>>

Notes

• If this result resolves to an Err and x is a Promise that rejects, the resulting PendingResult resolves to an Err with an UnexpectedError.

Example

const x = ok<number, string>(2).toPending();
const y = err<number, string>("failure").toPending();

expect(await x.or(ok(3))).toStrictEqual(ok(2));
expect(await x.or(err("another one"))).toStrictEqual(ok(2));
expect(await y.or(ok(3))).toStrictEqual(ok(3));
expect(await y.or(err("another one"))).toStrictEqual(err("failure"));
expect(
  (await y.or(Promise.reject(new Error("boom")))).unwrapErr().unexpected,
).toBeDefined();

---

orElse()

orElse<F>(f): PendingResult<Awaited<T>, Awaited<F>>;

Defined in: packages/std/src/result/interface.ts:1292

Returns this PendingResult if it resolves to Ok, otherwise returns a PendingResult with the result of f.

This is the asynchronous version of orElse.

Type Parameters

Type Parameter
F

Parameters

Parameter	Type
f	() => | Result<T, F> | PendingResult<T, F> | Promise<Result<T, F>>

Returns

PendingResult<Awaited<T>, Awaited<F>>

Notes

• If f throws or returns a rejected promise, the resulting PendingResult resolves to an Err with an UnexpectedError.

Example

const x = ok<number, string>(2).toPending();
const y = err<number, string>("failure").toPending();

expect(await x.orElse(() => ok(3))).toStrictEqual(ok(2));
expect(await y.orElse(() => Promise.resolve(ok(3)))).toStrictEqual(ok(3));
expect(
  (
    await y.orElse(() => {
      throw new Error("boom");
    })
  ).unwrapErr().unexpected,
).toBeDefined();
expect(await y.orElse(() => err("another one"))).toStrictEqual(
  err("another one"),
);

---

tap()

tap(f): PendingResult<T, E>;

Defined in: packages/std/src/result/interface.ts:1318

Executes f with the resolved result, then returns a new PendingResult unchanged.

This is the asynchronous version of tap.

Parameters

Parameter	Type
f	(x) => unknown

Returns

PendingResult<T, E>

Notes

• If f throws or rejects, the error is ignored
• If f returns a promise, the promise is not awaited before returning

Example

const x = pendingResult(ok<number, string>(42));
const y = pendingResult(err<number, string>("failure"));
let log = "";

expect(await x.tap((res) => (log = res.toString()))).toStrictEqual(ok(42));
expect(log).toBe("Ok { 42 }");
expect(await y.tap((res) => (log = res.toString()))).toStrictEqual(
  err("failure"),
);
expect(log).toBe("Err { 'failure' }");

---

then()

then<TResult1, TResult2>(onfulfilled?, onrejected?): PromiseLike<TResult1 | TResult2>;

Defined in: node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/lib/lib.es5.d.ts:1537

Attaches callbacks for the resolution and/or rejection of the Promise.

Type Parameters

Type Parameter	Default type
TResult1	Result<T, E>
TResult2	never

Parameters

Parameter	Type	Description
onfulfilled?	null | (value) => TResult1 | PromiseLike<TResult1>	The callback to execute when the Promise is resolved.
onrejected?	null | (reason) => TResult2 | PromiseLike<TResult2>	The callback to execute when the Promise is rejected.

Returns

PromiseLike<TResult1 | TResult2>

A Promise for the completion of which ever callback is executed.

Inherited from

PromiseLike.then;

---

transpose()

transpose<U, F>(this): PendingOption<Result<U, F>>;

Defined in: packages/std/src/result/interface.ts:1337

Transposes a PendingResult of an Option into a PendingOption containing a Result.

This is the asynchronous version of transpose.

Type Parameters

Type Parameter
U
F

Parameters

Parameter	Type
this	PendingResult<Option<U>, F>

Returns

PendingOption<Result<U, F>>

Example

const x = pendingOption(some(ok(2)));
const y = pendingOption(some(err("error")));
const z = pendingOption(none<Result<number, string>>());

expect(await x.transpose()).toStrictEqual(ok(some(2)));
expect(await y.transpose()).toStrictEqual(err("error"));
expect(await z.transpose()).toStrictEqual(ok(none()));

---

try()

try(): Promise<readonly [boolean,
  | undefined
  | CheckedError<Awaited<E>>, undefined | Awaited<T>]>;

Defined in: packages/std/src/result/interface.ts:1365

Extracts this PendingResult’s state, returning a promise of a tuple with a success flag, error, and value.

Inspired by the Try Operator proposal.

This is the asynchronous version of try.

Returns

Promise<readonly [boolean, | undefined | CheckedError<Awaited<E>>, undefined | Awaited<T>]>

Notes

• Resolves to [true, undefined, Awaited<T>] if this is an Ok, or [false, CheckedError<Awaited<E>>, undefined] if this is an Err.
• Never rejects, offering a safe way to await the result’s state with explicit success indication.

Example

const x = ok<number, string>(42).toPending();
const y = err<number, string>("failure").toPending();

expect(await x.try()).toEqual([true, undefined, 42]);
expect(await y.try()).toEqual([
  false,
  expect.objectContaining({ expected: "failure" }),
  undefined,
]);