コンテンツにスキップ
surrealdb.js

StatefulPromise

StatefulPromise はハンドリングされていない状態で拒否されてもエラーを投げない PromiseLike を実装するクラスです。

インポート

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

.constructor()

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

引数

executor

StatefulPromise に対して Promise() コンストラクター の executor と同じ役割を果たします。

返値

new を通じて呼び出された場合、StatefulPromise はそのインスタンスを返します。

例

解決

次の例では、StatefulPromise が解決されるまで待機し、その結果を受け取ります:

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


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


const result = await promise;


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

次の例では、StatefulPromise が拒否されるまで待機し、ハンドリングするとエラーを投げることを期待します:

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"
}

通常の Promise ではハンドリングされていない状態で拒否される (つまり reject が呼び出される) と unhandledrejection が発生しますが、StatefulPromise は明示的にハンドリングするまでエラーを投げないことがわかります。

.state インスタンス プロパティー 読み取り専用

現在の StatefulPromise の状態を表します。状態には次の 3 つがあります:

  • pending: 保留中であることを示します。まだ解決も拒否もされていません。
  • fulfilled: 解決されたことを示します。
  • rejected: 拒否されたことを示します。

.then() インスタンス メソッド

.then は StatefulPromise が成功した場合と失敗した場合のコールバック関数を取り、StatefulPromise オブジェクトを返します。

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

引数

Promise.prototype.then と同じです。

返値

StatefulPromise オブジェクトが返ります。

.resolve() 静的 メソッド

.resolve は与えられた値で解決された StatefulPromise を返します。

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

引数

value

解決する値。デフォルト値は undefined です。

返値

引数の value で解決された StatefulPromise オブジェクトを返します。値が StatefulPromise オブジェクトであれば、その値を返します。

.reject() 静的 メソッド

.reject は与えられた理由で拒否された StatefulPromise オブジェクトを返します。

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

引数

reason

拒否する理由。デフォルト値は undefined です。

返値

引数の reason で拒否された StatefulPromise を返します。

.withResolvers() 静的 メソッド

.withResolvers は新しい StatefulPromise オブジェクトと、それを解決または拒否する関数を含むオブジェクトを返す関数です。

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

引数

なし。

返値

以下のプロパティーを含むプレーンオブジェクトです。

promise

新しい StatefulPromise オブジェクトです。

resolve

promise を解決する関数です。

reject

promise を拒否する関数です。

.try() 静的 メソッド

.try は関数を StatefulPromise でラップする関数です。

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

引数

func

呼び出される関数です。この関数は StatefulPromise 以外の値を返すことができます。また関数内で同期的にエラーを投げることもできます。

返値

  • func が同期的に値を返す場合、解決された状態の StatefulPromise を返します。
  • func が同期的にエラーを投げる場合、拒否された状態の StatefulPromise を返します。
  • func が非同期的に解決または拒否する場合、保留状態の StatefulPromise を返します。

例

次の例は、同期的に投げられたエラーが StatefulPromise によって補足されていることを示します:

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


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


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

.allRejected() 静的 メソッド

.allRejected は拒否された StatefulPromise の理由だけを収集する関数です。

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

引数

promises

反復可能オブジェクトです。StatefulPromise オブジェクト以外を含むこともできますが、それらはエラーとして判定されません。また通常の Promise も同様に無視されます。

extract

promises から StatefulPromise オブジェクトを取り出す関数です。

返値

StatefulPromise オブジェクトが拒否した理由の配列で解決された StatefulPromise オブジェクトを返します。