PendingOption

Interface: PendingOption<T>

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

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:902

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:926

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:950

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:975

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:999

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:1029

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

iter()

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

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

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

Returns

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

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

map()

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

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

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:1109

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<U> | Awaited<F>>;

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

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<U> | Awaited<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:1156

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:1173

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:1195

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:1218

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:1244

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@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`	`Option`<`T`>
`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, E>(this): PendingResult<Option<U>, E>;

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

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:1288

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

Interface: PendingOption<T>

Extends​

Type Parameters​

Methods​

and()​

Type Parameters​

Parameters​

Returns​

Notes​

Example​

andThen()​

Type Parameters​

Parameters​

Returns​

Notes​

Example​

catch()​

Type Parameters​

Parameters​

Returns​

Inherited from​

combine()​

Type Parameters​

Parameters​

Returns​

Example​

filter()​

Parameters​

Returns​

Notes​

Example​

flatten()​

Type Parameters​

Parameters​

Returns​

Notes​

Example​

inspect()​

Parameters​

Returns​

Notes​

Example​

iter()​

Returns​

Notes​

Example​

map()​

Type Parameters​

Parameters​

Returns​

Notes​

Example​

mapAll()​

Type Parameters​

Parameters​

Returns​

Notes​

Example​

match()​

Type Parameters​

Parameters​

Returns​

Throws​

Notes​

Example​

okOr()​

Type Parameters​

Parameters​

Returns​

Example​

okOrElse()​

Type Parameters​

Parameters​

Returns​

Example​

or()​

Parameters​

Returns​

Notes​

Example​

Extends

Type Parameters

Methods

and()

Type Parameters

Parameters

Returns

Notes

Example

andThen()

Type Parameters

Parameters

Returns

Notes

Example

catch()

Type Parameters

Parameters

Returns

Inherited from

combine()

Type Parameters

Parameters

Returns

Example

filter()

Parameters

Returns

Notes

Example

flatten()

Type Parameters

Parameters

Returns

Notes

Example

inspect()

Parameters

Returns

Notes

Example

iter()

Returns

Notes

Example

map()

Type Parameters

Parameters

Returns

Notes

Example

mapAll()

Type Parameters

Parameters

Returns

Notes

Example

match()

Type Parameters

Parameters

Returns

Throws

Notes

Example

okOr()

Type Parameters

Parameters

Returns

Example

okOrElse()

Type Parameters

Parameters

Returns

Example

or()

Parameters

Returns

Notes

Example

orElse()