StatefulPromise

StatefulPromise is a class implementing PromiseLike that doesn’t throw errors even if rejected in an unhandled state.

Import

import { StatefulPromise } from "@tai-kun/surrealdb/utils";

.constructor()

new StatefulPromise<T>(executor: StatefulPromiseExecutor<T>);

Arguments

executor

Serves the same purpose as the executor in the Promise() constructor for StatefulPromise.

Return Value

When called with new, StatefulPromise returns its instance.

Examples

Resolution

The following example waits until the StatefulPromise resolves and receives its result:

import { StatefulPromise } from "@tai-kun/surrealdb/utils";

const promise = new StatefulPromise(resolve => {
  setTimeout(() => resolve("test"), 0);
});

const result = await promise;

console.log(result); // "test"

Rejection

The following example waits until the StatefulPromise is rejected and expects an error to be thrown upon handling:

const promise = new StatefulPromise((_, reject) => {
  setTimeout(() => reject("test"), 0);
});

while (promise.state === "pending") {
  await new Promise(r => setTimeout(r, 50));
}

try {
  await promise;
} catch (e) {
  console.log(e); // "test"
}

Note that while a regular Promise would trigger an unhandledrejection if rejected in an unhandled state (i.e., reject is called), StatefulPromise does not throw an error until explicitly handled.

.state instance property readonly

Represents the current state of the StatefulPromise. There are three possible states:

• pending: Indicates that the promise is pending. It has neither resolved nor rejected yet.
• fulfilled: Indicates that the promise has been resolved.
• rejected: Indicates that the promise has been rejected.

.then() instance method

.then takes callback functions for both success and failure cases of the StatefulPromise and returns a StatefulPromise object.

then<R1, R2>(
  onFulfilled?: ((value: any) => R1 | PromiseLike<R1>) | undefined | null,
  onRejected?: ((reason: unknown) => R2 | PromiseLike<R2>) | undefined | null,
): StatefulPromise<R1 | R2>;

Arguments

Same as Promise.prototype.then.

Return Value

Returns a StatefulPromise object.

.resolve() static method

.resolve returns a StatefulPromise resolved with the given value.

resolve<T>(value?: T | PromiseLike<T>): StatefulPromise<Awaited<T>>;

Arguments

value

The value to resolve with. Defaults to undefined.

Return Value

Returns a StatefulPromise object resolved with the given value. If the value is a StatefulPromise object, that value is returned.

.reject() static method

.reject returns a StatefulPromise object rejected with the given reason.

reject<T>(reason?: unknown): StatefulPromise<T>;

Arguments

reason

The reason for rejection. Defaults to undefined.

Return Value

Returns a StatefulPromise rejected with the given reason.

.withResolvers() static method

.withResolvers is a function that returns a new StatefulPromise object and an object containing functions to resolve or reject it.

withResolvers<T>(): {
  promise: StatefulPromise<T>;
  resolve: (value: T | PromiseLike<T>) => void;
  reject: (reason: unknown) => void;
};

Arguments

None.

Return Value

A plain object containing the following properties:

promise

The new StatefulPromise object.

resolve

A function to resolve the promise.

reject

A function to reject the promise.

.try() static method

.try is a function that wraps a function in a StatefulPromise.

try<T, A extends readonly unknown[]>(
  func: (...args: A) => T | PromiseLike<T>,
  ...args: A
): StatefulPromise<T>;

Arguments

func

The function to be called. This function can return values other than StatefulPromise. It can also throw errors synchronously within the function.

Return Value

• If func returns a value synchronously, a resolved StatefulPromise is returned.
• If func throws an error synchronously, a rejected StatefulPromise is returned.
• If func resolves or rejects asynchronously, a pending StatefulPromise is returned.

Example

The following example shows that a synchronously thrown error is caught by the StatefulPromise:

import { StatefulPromise } from "@tai-kun/surrealdb/utils";

const promise = StatefulPromise.try(() => {
  throw "test";
});

await promise.then(null, e => {
  console.log(e); // "test"
});

.allRejected() static method

.allRejected is a function that collects only the reasons of rejected StatefulPromises.

allRejected(promises: Iterable<unknown>): StatefulPromise<unknown[]>;
allRejected<T>(
  promises: Iterable<T>,
  extract: (item: T) => unknown,
): StatefulPromise<unknown[]>;

Arguments

promises

An iterable object. It can contain non-StatefulPromise objects, but they will not be treated as errors. Regular Promise objects are similarly ignored.

extract

A function to extract StatefulPromise objects from promises.

Return Value

Returns a StatefulPromise object resolved with an array of the reasons why StatefulPromise objects were rejected.