Interface PendingOption<T>

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.

interface PendingOption<T> {
 and(x: Option | Promise<Option>): PendingOption<Awaited>;
 andThen(
 f: (x: T) => Option | Promise<Option>,
 ): PendingOption<Awaited>;
 catch<R = never>(
 onrejected?: (reason: unknown) => R | PromiseLike<R>,
 ): Promise<Option<T> | R>;
 filter(f: (x: T) => boolean | Promise<boolean>): PendingOption<T>;
 flatten(
 this:
 | PendingOption<Option>
 | PendingOption<PendingOption>
 | PendingOption<PromiseLike<Option>>,
 ): PendingOption<Awaited>;
 inspect(f: (x: T) => unknown): PendingOption<T>;
 iter(): AsyncIterableIterator<Awaited<T>, Awaited<T>, void>;
 map(f: (x: T) => U): PendingOption<Awaited>;
 mapAll(
 f: (x: Option<T>) => Option | Promise<Option>,
 ): PendingOption<Awaited>;
 match<U, F = U>(
 f: (x: T) => U,
 g: () => F,
 ): Promise<Awaited | Awaited<F>>;
 okOr<E>(y: Awaited<E>): PendingResult<T, E>;
 okOrElse<E>(mkErr: () => E | Promise<E>): PendingResult<T, E>;
 or(x: Option<T> | Promise<Option<T>>): PendingOption<Awaited<T>>;
 orElse(f: () => Option<T> | Promise<Option<T>>): PendingOption<Awaited<T>>;
 tap(f: (x: Option<T>) => unknown): PendingOption<T>;
 then<TResult1 = Option<T>, TResult2 = never>(
 onfulfilled?:
 | null
 | ((value: Option) => TResult1 | PromiseLike<TResult1>),
 onrejected?: null | ((reason: any) => TResult2 | PromiseLike<TResult2>),
 ): PromiseLike<TResult1 | TResult2>;
 transpose<U, E>(
 this: PendingOption<Result<U, E>>,
 ): PendingResult<Option, E>;
 xor(y: Option<T> | Promise<Option<T>>): PendingOption<Awaited<T>>;
}

Type Parameters

Hierarchy (View Summary)

PromiseLike<Option<T>>
Recoverable<Option<T>>
- PendingOption

Index

Methods

and andThen catch filter flatten inspect iter map mapAll match okOr okOrElse or orElse tap then transpose xor

Methods

and

and(x: Option | Promise<Option>): PendingOption<Awaited>

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

This is the asynchronous version of and.

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());

Type Parameters

Parameters

x: Option | Promise<Option>

Returns PendingOption<Awaited>

andThen

andThen(
f: (x: T) => Option | Promise<Option>,
): PendingOption<Awaited>
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.

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());
```
Type Parameters
- U
Parameters
- f: (x: T) => Option | Promise<Option>
Returns PendingOption<Awaited>
- Defined in packages/std/src/option/interface.ts:900

catch

catch<R = never>(
onrejected?: (reason: unknown) => R | PromiseLike<R>,
): Promise<Option<T> | R>
Type Parameters
- R = never
Parameters
- Optionalonrejected: (reason: unknown) => R | PromiseLike<R>
Returns Promise<Option<T> | R>
Inherited from Recoverable.catch
- Defined in packages/std/src/types.ts:133

filter

filter(f: (x: T) => boolean | Promise<boolean>): PendingOption<T>
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.

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(n => true)).toStrictEqual(none());
```
Parameters
- f: (x: T) => boolean | Promise<boolean>
Returns PendingOption<T>
- Defined in packages/std/src/option/interface.ts:925

flatten

flatten(
 this:
 | PendingOption<Option>
 | PendingOption<PendingOption>
 | PendingOption<PromiseLike<Option>>,
): PendingOption<Awaited>
Flattens a PendingOption of a PendingOption or Option, resolving nested pending states.

This is the asynchronous version of flatten.

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>>
```
Type Parameters
- U
Parameters
- this:
 | PendingOption<Option>
 | PendingOption<PendingOption>
 | PendingOption<PromiseLike<Option>>
Returns PendingOption<Awaited>
- Defined in packages/std/src/option/interface.ts:949

inspect

inspect(f: (x: T) => unknown): PendingOption<T>
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.

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
```
Parameters
- f: (x: T) => unknown
Returns PendingOption<T>
- Defined in packages/std/src/option/interface.ts:979

iter

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

Returns an async iterator over this pending option’s value, yielding it if it resolves to Some or nothing if it resolves to None.

Notes

Yields exactly one item for a resolved Some, or zero items for a resolved None.
Compatible with for await...of loops and async spread operators (with caution).

Example

const x = some(42).toPending();
const y = none<number>().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([]);

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

map

map(f: (x: T) => U): PendingOption<Awaited>
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.

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());
```
Type Parameters
- U
Parameters
- f: (x: T) => U
Returns PendingOption<Awaited>
- Defined in packages/std/src/option/interface.ts:1032

mapAll

mapAll(
f: (x: Option<T>) => Option | Promise<Option>,
): PendingOption<Awaited>
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.

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));
```
Type Parameters
- U
Parameters
- f: (x: Option<T>) => Option | Promise<Option>
Returns PendingOption<Awaited>
- Defined in packages/std/src/option/interface.ts:1057

match

match<U, F = U>(f: (x: T) => U, g: () => F): Promise<Awaited | Awaited<F>>
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.

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);
```
Type Parameters
- U
- F = U
Parameters
- f: (x: T) => U
- g: () => F
Returns Promise<Awaited | Awaited<F>>
- Defined in packages/std/src/option/interface.ts:1086

okOr

okOr<E>(y: Awaited<E>): PendingResult<T, E>
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.

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"));
```
Type Parameters
- E
Parameters
- y: Awaited<E>
Returns PendingResult<T, E>
- Defined in packages/std/src/option/interface.ts:1104

okOrElse

okOrElse<E>(mkErr: () => E | Promise<E>): PendingResult<T, E>
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.

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"));
```
Type Parameters
- E
Parameters
- mkErr: () => E | Promise<E>
Returns PendingResult<T, E>
- Defined in packages/std/src/option/interface.ts:1121

or

or(x: Option<T> | Promise<Option<T>>): PendingOption<Awaited<T>>
Returns this PendingOption if it resolves to Some, otherwise returns a PendingOption with x.

This is the asynchronous version of or.

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());
```
Parameters
- x: Option<T> | Promise<Option<T>>
Returns PendingOption<Awaited<T>>
- Defined in packages/std/src/option/interface.ts:1143

orElse

orElse(f: () => Option<T> | Promise<Option<T>>): PendingOption<Awaited<T>>
Returns this PendingOption if it resolves to Some, otherwise returns a PendingOption with the result of f.

This is the asynchronous version of orElse.

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(() => none())).toStrictEqual(none());
```
Parameters
- f: () => Option<T> | Promise<Option<T>>
Returns PendingOption<Awaited<T>>
- Defined in packages/std/src/option/interface.ts:1164

tap

tap(f: (x: Option<T>) => unknown): PendingOption<T>
Executes f with the resolved option, then returns a new PendingOption unchanged.

This is the asynchronous version of tap.

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");
```
Parameters
- f: (x: Option<T>) => unknown
Returns PendingOption<T>
- Defined in packages/std/src/option/interface.ts:1188

then

then<TResult1 = Option<T>, TResult2 = never>(
 onfulfilled?:
 | null
 | ((value: Option) => TResult1 | PromiseLike<TResult1>),
 onrejected?: null | ((reason: any) => TResult2 | PromiseLike<TResult2>),
): PromiseLike<TResult1 | TResult2>
Attaches callbacks for the resolution and/or rejection of the Promise.
Type Parameters
- TResult1 = Option<T>
- TResult2 = never
Parameters
- Optionalonfulfilled: null | ((value: Option) => TResult1 | PromiseLike<TResult1>)
 The callback to execute when the Promise is resolved.
- Optionalonrejected: null | ((reason: any) => 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
- Defined in node_modules/.pnpm/typescript@5.7.3/node_modules/typescript/lib/lib.es5.d.ts:1537

transpose

transpose<U, E>(this: PendingOption<Result<U, E>>): PendingResult<Option, E>

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

This is the asynchronous version of transpose.

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"));

Type Parameters

Parameters

this: PendingOption<Result<U, E>>

Returns PendingResult<Option, E>

xor

xor(y: Option<T> | Promise<Option<T>>): PendingOption<Awaited<T>>
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.

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());
```
Parameters
- y: Option<T> | Promise<Option<T>>
Returns PendingOption<Awaited<T>>
- Defined in packages/std/src/option/interface.ts:1232

Interface PendingOption<T>

Type Parameters

Hierarchy (View Summary)

Index

Methods

Methods

and

Notes

Example

Type Parameters

Parameters

Returns PendingOption<Awaited<U>>

andThen

Notes

Example

Type Parameters

Parameters

Returns PendingOption<Awaited<U>>

catch

Type Parameters

Parameters

Returns Promise<Option<T> | R>

filter

Notes

Example

Parameters

Returns PendingOption<T>

flatten

Notes

Example

Type Parameters

Parameters

Returns PendingOption<Awaited<U>>

inspect

Notes

Example

Parameters

Returns PendingOption<T>

iter

Notes

Example

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

map

Notes

Example

Type Parameters

Parameters

Returns PendingOption<Awaited<U>>

mapAll

Notes

Example

Type Parameters

Parameters

Returns PendingOption<Awaited<U>>

match

Rejects

Notes

Example

Type Parameters

Parameters

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

okOr

Example

Type Parameters

Parameters

Returns PendingResult<T, E>

okOrElse

Example

Type Parameters

Parameters

Returns PendingResult<T, E>

or

Notes

Example

Parameters

Returns PendingOption<Awaited<T>>

orElse

Notes

Example

Parameters