PendingOption

@ts-rust/std

---

@ts-rust/std / Option / PendingOption

Interface: PendingOption<T>

Defined in: packages/std/src/option/interface.ts:882

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

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

Extends

• PromiseLike<Option<T>>.Recoverable<Option<T>>

Type Parameters

Type Parameter
T

Methods

and()

and<U>(x): PendingOption<Awaited<U>>;

Defined in: packages/std/src/option/interface.ts:906

Returns a PendingOption with None if this option resolves to None, otherwise returns a PendingOption with x.

This is the asynchronous version of and.

Type Parameters

Type Parameter
U

Parameters

Parameter	Type
x	| Option<U> | PendingOption<U> | Promise<Option<U>>

Returns

PendingOption<Awaited<U>>

Notes

• Default: If x is a Promise and rejects, None is returned.

Example

const x = pendingOption(some(2));
const y = pendingOption(none<number>());

expect(await x.and(some(3))).toStrictEqual(some(3));
expect(await x.and(Promise.resolve(some(3)))).toStrictEqual(some(3));
expect(await x.and(none())).toStrictEqual(none());
expect(await x.and(Promise.resolve(none()))).toStrictEqual(none());
expect(await y.and(some(3))).toStrictEqual(none());
expect(await y.and(Promise.resolve(none()))).toStrictEqual(none());

---

andThen()

andThen<U>(f): PendingOption<Awaited<U>>;

Defined in: packages/std/src/option/interface.ts:930

Returns a PendingOption with None if this Option resolves to None, otherwise applies f to the resolved value and returns the result.

This is the asynchronous version of andThen.

Type Parameters

Type Parameter
U

Parameters

Parameter	Type
f	(x) => | Option<U> | PendingOption<U> | Promise<Option<U>>

Returns

PendingOption<Awaited<U>>

Notes

• Default: If f rejects or throws, None is returned.

Example

const x = pendingOption(some(2));
const y = pendingOption(none<number>());

expect(await x.andThen((n) => some(n * 2))).toStrictEqual(some(4));
expect(await x.andThen((n) => Promise.resolve(some(n * 2)))).toStrictEqual(
  some(4),
);
expect(await x.andThen((_) => none())).toStrictEqual(none());
expect(await y.andThen((n) => some(n * 2))).toStrictEqual(none());

---

catch()

catch<R>(onrejected?): Promise<
  | Option<T>
  | 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< | Option<T> | R>

Inherited from

Recoverable.catch

---

combine()

combine<U>(...opts): PendingOption<[Awaited<T>, ...SomeAwaitedValues<U>[]]>;

Defined in: packages/std/src/option/interface.ts:954

Combines this PendingOption with other Option or PendingOption instances into a single PendingOption containing a tuple of resolved values.

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

Type Parameters

Type Parameter
U extends ( | Option<unknown> | PendingOption<unknown>)[]

Parameters

Parameter	Type
...opts	U

Returns

PendingOption<[Awaited<T>, ...SomeAwaitedValues<U>[]]>

Example

const a = pendingSome(1);
const b = some(Promise.resolve("hi"));
const c = none<Error>();
const d = pendingNone<Promise<Date>>();
const e = a.combine(b, c, d); // PendingOption<[number, string, Error, Date]>

---

filter()

filter(f): PendingOption<T>;

Defined in: packages/std/src/option/interface.ts:979

Returns a PendingOption with None if this option resolves to None, otherwise calls f with the resolved value and returns a PendingOption with the original value if f resolves to true, or None otherwise.

This is the asynchronous version of filter.

Parameters

Parameter	Type
f	(x) => boolean | Promise<boolean>

Returns

PendingOption<T>

Notes

• Default: If f rejects or throws, None is returned.

Example

const x = pendingOption(some(2));
const y = pendingOption(none<number>());

expect(await x.filter((n) => n > 0)).toStrictEqual(some(2));
expect(await x.filter((n) => Promise.resolve(n < 0))).toStrictEqual(none());
expect(await y.filter((_) => true)).toStrictEqual(none());

---

flatten()

flatten<U>(this): PendingOption<Awaited<U>>;

Defined in: packages/std/src/option/interface.ts:1003

Flattens a PendingOption of a PendingOption or Option, resolving nested pending states.

This is the asynchronous version of flatten.

Type Parameters

Type Parameter
U

Parameters

Parameter	Type
this	| PendingOption<Option<U>> | PendingOption<PendingOption<U>> | PendingOption<PromiseLike<Option<U>>>

Returns

PendingOption<Awaited<U>>

Notes

• Default: If inner Option is wrapped in a Promise and rejects, flattened PendingOption with None is returned.

Example

const option1: PendingOption<Option<number>> = getPendingOption();
option1.flatten(); // PendingOption<number>

const option2: PendingOption<PendingOption<number>> = getPendingOption();
option2.flatten(); // PendingOption<number>

const option3: PendingOption<PendingOption<PendingOption<number>>> =
  getPendingOption();
option3.flatten(); // PendingOption<Option<number>>

---

inspect()

inspect(f): PendingOption<T>;

Defined in: packages/std/src/option/interface.ts:1033

Calls f with the resolved value if this option is Some, then returns this PendingOption unchanged. Useful for side effects.

This is the asynchronous version of inspect.

Parameters

Parameter	Type
f	(x) => unknown

Returns

PendingOption<T>

Notes

• Returns a new PendingOption instance with the same value as the original, rather than the exact same reference. The returned option is a distinct object, preserving the original value.

Example

const x = pendingOption(some(2));
const y = pendingOption(none<number>());
let sideEffect = 0;

expect(await x.inspect((n) => (sideEffect = n))).toStrictEqual(some(2));
expect(sideEffect).toBe(2);
expect(await y.inspect((n) => (sideEffect = n))).toStrictEqual(none());
expect(sideEffect).toBe(2); // Unchanged

---

map()

map<U>(f): PendingOption<Awaited<U>>;

Defined in: packages/std/src/option/interface.ts:1054

Maps the resolved value with f, returning a PendingOption with the result if Some, or None if None.

This is the async version of map.

Type Parameters

Type Parameter
U

Parameters

Parameter	Type
f	(x) => U

Returns

PendingOption<Awaited<U>>

Notes

• If f throws or rejects, returns None.

Example

const x = pendingOption(some(2));
const y = pendingOption(none<number>());

expect(await x.map((n) => n * 2)).toStrictEqual(some(4));
expect(await x.map((n) => Promise.resolve(n * 2))).toStrictEqual(some(4));
expect(await y.map((n) => n * 2)).toStrictEqual(none());

---

mapAll()

mapAll<U>(f): PendingOption<Awaited<U>>;

Defined in: packages/std/src/option/interface.ts:1081

Maps this option by applying a callback to its full state, executing the callback for both Some and None, returning a new PendingOption.

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

This is the asynchronous version of mapAll.

Type Parameters

Type Parameter
U

Parameters

Parameter	Type
f	(x) => | Option<U> | PendingOption<U> | Promise<Option<U>>

Returns

PendingOption<Awaited<U>>

Notes

• Default: If f throws or returns a Promise that rejects, the newly created PendingOption will resolve to a None.

Example

const someOpt = pendingOption(some(42));
const noneOpt = pendingOption(none<number>());

const someMapped = someOpt.mapAll((opt) =>
  Promise.resolve(some(opt.unwrapOr(0))),
);
expect(await someMapped).toStrictEqual(some(42));

const noneMapped = noneOpt.mapAll((opt) =>
  Promise.resolve(some(opt.unwrapOr(0) + 1)),
);
expect(await noneMapped).toStrictEqual(some(1));

---

match()

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

Defined in: packages/std/src/option/interface.ts:1110

Matches the resolved option, returning f applied to the value if Some, or g if None. Returns a Promise with the result.

This is the asynchronous version of match.

Type Parameters

Type Parameter	Default type
U	‐
F	U

Parameters

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

Returns

Promise<Awaited<InferType<U, F>>>

Throws

• Rejects with OptionError if f or g throws an exception or rejects, original error will be set as OptionError.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 = pendingOption(some(2));
const y = pendingOption(none<number>());

expect(
  await x.match(
    (n) => n * 2,
    () => 0,
  ),
).toBe(4);
expect(
  await y.match(
    (n) => n * 2,
    () => 0,
  ),
).toBe(0);
await expect(
  y.match(
    (n) => n * 2,
    () => {
      throw new Error();
    },
  ),
).rejects.toThrow(OptionError);

---

okOr()

okOr<E>(y): PendingResult<T, E>;

Defined in: packages/std/src/option/interface.ts:1131

Converts to a PendingResult, using y as the error value if this PendingOption resolves to None.

This is the asynchronous version of okOr, check it for more details.

Type Parameters

Type Parameter
E

Parameters

Parameter	Type
y	Awaited<E>

Returns

PendingResult<T, E>

Example

const x = pendingOption(some(2));
const y = pendingOption(none<number>());

expect(await x.okOr("error")).toStrictEqual(ok(2));
expect(await y.okOr("error")).toStrictEqual(err("error"));

---

okOrElse()

okOrElse<E>(mkErr): PendingResult<T, E>;

Defined in: packages/std/src/option/interface.ts:1148

Converts to a PendingResult, using the result of mkErr as the error value if this resolves to None.

This is the asynchronous version of okOrElse.

Type Parameters

Type Parameter
E

Parameters

Parameter	Type
mkErr	() => E | Promise<E>

Returns

PendingResult<T, E>

Example

const x = pendingOption(some(2));
const y = pendingOption(none<number>());

expect(await x.okOrElse(() => "error")).toStrictEqual(ok(2));
expect(await y.okOrElse(() => Promise.resolve("error"))).toStrictEqual(
  err("error"),
);

---

or()

or(x): PendingOption<Awaited<T>>;

Defined in: packages/std/src/option/interface.ts:1170

Returns this PendingOption if it resolves to Some, otherwise returns a PendingOption with x.

This is the asynchronous version of or.

Parameters

Parameter	Type
x	| PendingOption<T> | Option<T> | Promise<Option<T>>

Returns

PendingOption<Awaited<T>>

Notes

• Default: If x is a Promise that rejects, None is returned.

Example

const x = pendingOption(some(2));
const y = pendingOption(none<number>());

expect(await x.or(some(3))).toStrictEqual(some(2));
expect(await x.or(Promise.resolve(none()))).toStrictEqual(some(2));
expect(await y.or(some(3))).toStrictEqual(some(3));
expect(await y.or(Promise.resolve(none()))).toStrictEqual(none());

---

orElse()

orElse(f): PendingOption<Awaited<T>>;

Defined in: packages/std/src/option/interface.ts:1193

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

This is the asynchronous version of orElse.

Parameters

Parameter	Type
f	() => | PendingOption<T> | Option<T> | Promise<Option<T>>

Returns

PendingOption<Awaited<T>>

Notes

• Default: If f throws or rejects, None is returned.

Example

const x = pendingOption(some(2));
const y = pendingOption(none<number>());

expect(await x.orElse(() => some(3))).toStrictEqual(some(2));
expect(await y.orElse(() => Promise.resolve(some(3)))).toStrictEqual(some(3));
expect(await y.orElse(() => some(1))).toStrictEqual(some(1));

---

tap()

tap(f): PendingOption<T>;

Defined in: packages/std/src/option/interface.ts:1219

Executes f with the resolved option, then returns a new PendingOption unchanged.

This is the asynchronous version of tap.

Parameters

Parameter	Type
f	(x) => unknown

Returns

PendingOption<T>

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 = pendingOption(some(42));
const y = pendingOption(none<number>());
let log = "";

expect(await x.tap((opt) => (log = opt.toString()))).toStrictEqual(some(42));
expect(log).toBe("Some { 42 }");
expect(await y.tap((opt) => (log = opt.toString()))).toStrictEqual(none());
expect(log).toBe("None");

---

then()

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

Defined in: node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1542

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

Type Parameters

Type Parameter	Default type
TResult1	Option<T>
TResult2	never

Parameters

Parameter	Type	Description
onfulfilled?	((value) => TResult1 | PromiseLike<TResult1>) | null	The callback to execute when the Promise is resolved.
onrejected?	((reason) => TResult2 | PromiseLike<TResult2>) | null	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, E>(this): PendingResult<Option<U>, E>;

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

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

This is the asynchronous version of transpose.

Type Parameters

Type Parameter
U
E

Parameters

Parameter	Type
this	PendingOption<Result<U, E>>

Returns

PendingResult<Option<U>, E>

Example

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

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

---

xor()

xor(y): PendingOption<Awaited<T>>;

Defined in: packages/std/src/option/interface.ts:1263

Returns a PendingOption with Some if exactly one of this option or y resolves to Some, otherwise returns a PendingOption with None.

This is the asynchronous version of xor.

Parameters

Parameter	Type
y	| PendingOption<T> | Option<T> | Promise<Option<T>>

Returns

PendingOption<Awaited<T>>

Notes

• Default: If y is a Promise that rejects, None is returned.

Example

const x = pendingOption(some(2));
const y = pendingOption(none<number>());

expect(await x.xor(some(3))).toStrictEqual(none());
expect(await x.xor(Promise.resolve(none()))).toStrictEqual(some(2));
expect(await y.xor(some(3))).toStrictEqual(some(3));
expect(await y.xor(Promise.resolve(none()))).toStrictEqual(none());