StatefulPromise

StatefulPromise is a class that implements PromiseLike, which doesn’t throw errors 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, it returns that value.

.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 returns 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 with the following properties:

promise

A new StatefulPromise object.

resolve

A function to resolve the promise.

reject

A function to reject the promise.

.try() static method

.try 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 a value other than a StatefulPromise. It can also throw errors synchronously within the function.

Return Value

• If func returns a value synchronously, it returns a fulfilled StatefulPromise.
• If func throws an error synchronously, it returns a rejected StatefulPromise.
• If func resolves or rejects asynchronously, it returns a pending StatefulPromise.

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 for 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 objects other than StatefulPromise objects, but they will not be treated as errors. Similarly, regular Promise objects will also be ignored.

extract

A function that extracts StatefulPromise objects from promises.

Return Value

Returns a StatefulPromise object resolved with an array of reasons for which StatefulPromise objects were rejected.