JavaScript异步与并发

July 5, 2023

Promise

/**
 * @source lib.es5.d.ts
 * 注：es5 没有实现 Promise，故只有接口（供 polyfill）
 */

declare type PromiseConstructorLike = new <T>(
    executor: (resolve: (value: T | PromiseLike<T>) => void, reject: (reason?: any) => void) => void,
) => PromiseLike<T>;

interface PromiseLike<T> {
    then<TResult1 = T, TResult2 = never>(
        onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | undefined | null,
        onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined | null,
    ): PromiseLike<TResult1 | TResult2>;
}

// Promise 的泛型参数 T 只指明了 fulfilled 状态时的默认类型
interface Promise<T> {
    then<TResult1 = T, TResult2 = never>(
        onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | undefined | null,
        onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined | null,
    ): Promise<TResult1 | TResult2>;
    catch<TResult = never>(
        onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | undefined | null,
    ): Promise<T | TResult>;
}

/**
 * @source lib.es2015.promise.d.ts
 * 注：es2015 实现了 Promise 构造器
 */

interface PromiseConstructor {
    readonly prototype: Promise<any>;
    new <T>(
        executor: (resolve: (value: T | PromiseLike<T>) => void, reject: (reason?: any) => void) => void,
    ): Promise<T>;
    all<T extends readonly unknown[] | []>(values: T): Promise<{ -readonly [P in keyof T]: Awaited<T[P]> }>;
    race<T extends readonly unknown[] | []>(values: T): Promise<Awaited<T[number]>>;
    reject<T = never>(reason?: any): Promise<T>;
    resolve(): Promise<void>;
    resolve<T>(value: T): Promise<Awaited<T>>;
    resolve<T>(value: T | PromiseLike<T>): Promise<Awaited<T>>;
}

declare var Promise: PromiseConstructor;

/**
 * @source lib.es2015.iterable.d.ts
 * 注：规范中 all 和 race 静态方法实际上接受迭代器，类型如下
 */

interface PromiseConstructor {
    // 接受一个含 Promise 实例的迭代器，当迭代器中所有 Promise 实例都变为 fulfilled 状态时
    // 则 resolve 所有 fulfillment 的值组成的数组
    // 否则，若任意一个 Promise 实例变为 rejected 状态，则 reject 那个 Promise 实例的 rejection 值
    all<T>(values: Iterable<T | PromiseLike<T>>): Promise<Awaited<T>[]>;
    // 接受一个含 Promise 实例的迭代器，当迭代器中任意一个 Promise 对象
    // 变为 fulfilled 或 rejected 状态时（即，不是 pending 状态）
    // 就 resolve 该 fulfillment 值，或 reject 该 rejection 值
    race<T>(values: Iterable<T | PromiseLike<T>>): Promise<Awaited<T>>;
}

/**
 * @source lib.es2018.promise.d.ts
 * 注：原型上添加了 finally 方法
 */

interface Promise<T> {
    finally(onfinally?: (() => void) | undefined | null): Promise<T>;
}

/**
 * @source lib.es2020.promise.d.ts
 * 注：添加了 allSettled 静态方法
 */

interface PromiseFulfilledResult<T> {
    status: "fulfilled";
    value: T;
}

interface PromiseRejectedResult {
    status: "rejected";
    reason: any;
}

type PromiseSettledResult<T> = PromiseFulfilledResult<T> | PromiseRejectedResult;

interface PromiseConstructor {
    allSettled<T extends readonly unknown[] | []>(
        values: T,
    ): Promise<{ -readonly [P in keyof T]: PromiseSettledResult<Awaited<T[P]>> }>;
    // 当迭代器中所有 Promise 实例都 settle 时（就是说，不是 pedding 状态）
    // resolve 一个数组，数组的每一项都是一个对象，对应于迭代器中的 Promise 实例
    // 若 Promise 实例为 fulfilled 状态，则为 `{ status: "fulfilled", value: 对应fulfillment值 }`
    // 若 Promise 实例为 rejected 状态，则为 `{ status: "rejected", reason: 对应rejection值 }`
    allSettled<T>(values: Iterable<T | PromiseLike<T>>): Promise<PromiseSettledResult<Awaited<T>>[]>;
}

/**
 * @source lib.es2021.promise.d.ts
 * 注：添加了 any 静态方法
 */

interface AggregateError extends Error {
    errors: any[];
}

interface AggregateErrorConstructor {
    new (errors: Iterable<any>, message?: string): AggregateError;
    (errors: Iterable<any>, message?: string): AggregateError;
    readonly prototype: AggregateError;
}

declare var AggregateError: AggregateErrorConstructor;

interface PromiseConstructor {
    any<T extends readonly unknown[] | []>(values: T): Promise<Awaited<T[number]>>;
    // 当迭代器中任意一个 Promise 实例变为 fulfilled 状态时，resolve 那个 fulfillment 值
    // 否则，reject 一个 AggregateError 错误，该错误的 errors 属性是一个数组
    // 包含所有 rejection 值（按照迭代器中的 Promise 实例的顺序）
    any<T>(values: Iterable<T | PromiseLike<T>>): Promise<Awaited<T>>;
}

`Array.fromAsync()`

在不使用生成器的情况下：
对于普通迭代器，可以简单地看作类似于 Promise.prototype.all()，但依次（而不是并发，且惰性地）等待每一个 Promise。
对于异步迭代器，可以简单地看作类似于 Array.from()

// es2022
// TODO: 目前 typescript5.4dev 暂未提供类型，且 chrome 暂未实现。
interface ArrayConstructor {
    fromAsync<T>(asyncIterable: AsyncIterable<T>): Promise<Array<T>>;
    fromAsync<T>(iterableOrArrayLike: Iterable<T> | ArrayLike<T>): Promise<Array<Awaited<T>>>;

    fromAsync<T, U>(
        asyncIterable: AsyncIterable<T>,
        mapperFn: (value: T) => U,
        thisArg?: any,
    ): Promise<Array<Awaited<U>>>;
    fromAsync<T, U>(
        iterableOrArrayLike: Iterable<T> | ArrayLike<T>,
        mapperFn: (value: Awaited<T>) => U,
        thisArg?: any,
    ): Promise<Array<Awaited<U>>>;
}

`Promise.withResolvers()`

Promise.withResolvers() 添加自 Chrome119。

interface PromiseConstructor {
    withResolvers<T>(): {
        promise: Promise<T>;
        resolve: (value: T | PromiseLike<T>) => void;
        reject: (reason?: any) => void;
    };
}

该方法非常方便，能够减少嵌套

function loadScript(src) {
    const { promise, resolve, reject } = Promise.withResolvers();
    const script = document.createElement("script");
    script.src = src;
    script.onload = resolve;
    script.onerror = reject;
    return promise;
}

←Back to home

This work is licensed under CC BY-NC-SA 4.0