跳转到内容
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 的状态。状态共有三种：

  • 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 对象。