TypeScript Promise：Promise<T>、Promise.all 与 allSettled

在 TypeScript 中，Promise 的类型是 Promise<T>，其中 T 是它兑现时的值的类型。返回 Promise 的函数在返回类型中声明它，而你通过 then 或 await 得到的值类型就是 T。

type User = { id: number; name: string };

function fetchUser(id: number): Promise<User> {
    return new Promise((resolve) => {
        setTimeout(() => resolve({ id, name: "Ada" }), 50);
    });
}

fetchUser(1).then((user) => {
    // user is User here
    console.log(user.name.toUpperCase()); // ADA
});

Promise 的运行机制（状态、微任务队列、链式调用）属于普通 JavaScript，在 JavaScript Promise 中讲解。本页只讲类型。

为 new Promise 和 resolve 标注类型

当 new Promise 作为一个声明了返回类型的函数的返回值时，T 就来自那个返回类型。单独使用时，TypeScript 不会从 resolve 调用中推断 T，你得到的是 Promise<unknown>。显式传入类型参数：

const untyped = new Promise((resolve) => resolve(42));
// untyped is Promise<unknown>

const typed = new Promise<number>((resolve, reject) => {
    const n = 42;
    if (n < 0) reject(new Error("negative"));
    else resolve(n);
});

// A promise that resolves with no value is Promise<void>.
const done = new Promise<void>((resolve) => setTimeout(resolve, 10));

async function main() {
    const n = await typed;
    console.log(n.toFixed(1)); // 42.0
    await done;
    console.log("done");
    const u = await untyped;
    // @ts-expect-error: 'u' is of type 'unknown'.
    console.log(u.toFixed(1)); // 42.0 at runtime, but the compiler cannot know that
}
main();

有两个细节。resolve 的类型来自 T，所以在 Promise<number> 中写 resolve("42") 会编译出错。而不带参数的 resolve() 只有在 T 包含 void 时才允许：在 Promise<number> 中它会报错 TS2794（Expected 1 arguments, but got 0. Did you forget to include 'void' in your type argument to 'Promise'?）。

reject 这一边没有类型。并不存在 Promise<T, E>：Promise 可以用任何值拒绝。

then、catch 与 finally

每个 then 都返回一个新的 Promise，其类型由回调的返回值决定。如果回调返回的是 Promise，TypeScript 会把它解开，所以你永远不会得到 Promise<Promise<T>>。

const price = Promise.resolve("19.99");

const withTax = price
    .then((s) => Number(s))                     // Promise<number>
    .then((n) => Promise.resolve(n * 1.2))      // still Promise<number>
    .then((n) => n.toFixed(2));                 // Promise<string>

withTax
    .then((s) => console.log(s)) // 23.99
    .catch((e: unknown) => {
        console.log(e instanceof Error ? e.message : String(e));
    })
    .finally(() => console.log("finished"));

在标准库中，catch 回调的参数类型是 any，而不是 unknown。没有什么能阻止你在一个可能是字符串的值上写 e.message。像上面那样把它标注为 unknown，使用前先收窄。在 await 外面套 try/catch 会更好：在 strict 下，它的 catch 变量已经是 unknown（参见错误处理）。

Promise.all 返回元组

传入由不同 Promise 类型组成的数组字面量时，Promise.all 返回一个元组的 Promise，每个位置都保留自己的类型：

const getUser = () => Promise.resolve({ name: "Ada" });
const getCount = () => Promise.resolve(3);
const getTags = () => Promise.resolve(["admin", "dev"]);

async function main() {
    const [user, count, tags] = await Promise.all([getUser(), getCount(), getTags()]);
    // user: { name: string }, count: number, tags: string[]
    console.log(user.name, count + 1, tags.join("/")); // Ada 4 admin/dev

    // Same element type: the result is an array.
    const ids = [1, 2, 3];
    const doubled = await Promise.all(ids.map((id) => Promise.resolve(id * 2)));
    console.log(doubled); // [ 2, 4, 6 ]
}
main();

可以混入非 Promise 的值，它们会原样传递。只要有一个输入被拒绝，Promise.all 就会立即拒绝，其他结果都会丢失。Promise.race 以第一个完成的结果兑现或拒绝，类型是各输入的联合类型；Promise.any 以第一个成功的结果兑现，只有在所有输入都失败时才以 AggregateError 拒绝。

Promise.allSettled 及其结果类型

Promise.allSettled 会等待每一个输入，并且永远不会拒绝。每个结果都是 PromiseSettledResult<T>，这是一个联合类型，可以用 status 字段来收窄：

function load(id: number): Promise<string> {
    return id % 2 === 0
        ? Promise.resolve(`item ${id}`)
        : Promise.reject(new Error(`item ${id} not found`));
}

async function main() {
    const results = await Promise.allSettled([load(1), load(2), load(4)]);

    for (const r of results) {
        if (r.status === "fulfilled") {
            console.log("ok:", r.value); // value: string
        } else {
            // reason: any, so narrow it like a caught error
            console.log("failed:", r.reason instanceof Error ? r.reason.message : r.reason);
        }
    }

    const values = results
        .filter((r): r is PromiseFulfilledResult<string> => r.status === "fulfilled")
        .map((r) => r.value);
    console.log(values); // [ 'item 2', 'item 4' ]
}
main();

只有在检查 status 之后才能访问 r.value，因为拒绝的那个变体没有 value。reason 是 any，原因和 catch 中一样。filter 使用了类型谓词，这样过滤后的数组类型就是已兑现的结果。

把回调式 API 包装成 Promise

较老的 API 通过回调报告结果，通常是 Node 风格的 (err, result) => void。把它们包装一次，变成返回带类型 Promise 的函数，其余代码就可以使用 await 了：

type Callback<T> = (err: Error | null, result?: T) => void;

// An old-style API.
function lookupPort(service: string, cb: Callback<number>): void {
    setTimeout(() => {
        if (service === "http") cb(null, 80);
        else cb(new Error(`unknown service ${service}`));
    }, 10);
}

function lookupPortAsync(service: string): Promise<number> {
    return new Promise((resolve, reject) => {
        lookupPort(service, (err, port) => {
            if (err) reject(err);
            else resolve(port!); // present whenever err is null
        });
    });
}

async function main() {
    console.log(await lookupPortAsync("http")); // 80
    try {
        await lookupPortAsync("gopher");
    } catch (e) {
        if (e instanceof Error) console.log(e.message); // unknown service gopher
    }
}
main();

在 Node 中，util.promisify 可以对遵循 (err, result) 约定的函数完成这件事，而且很多内置模块已经有了 Promise 版本（node:fs/promises、node:timers/promises）。

常见错误

• 签名写的是 Promise<T> 却返回了 T，或者反过来。 一个声明为 Promise<User> 的非 async 函数必须返回 Promise；async 函数会自动返回 Promise。
• 忘记处理 Promise。 像 save(user); 这样没有 await、then 或 catch 的调用可以正常编译，而一旦被拒绝，就会变成未处理的拒绝（默认会让 Node 进程退出）。typescript-eslint 的 no-floating-promises 规则可以捕获这类问题。
• 相信 .catch((e) => ...) 的类型。 它的 e 是 any。把它标注为 unknown。
• 给已经返回 Promise 的东西再套一层 new Promise。 直接返回或 await 现有的 Promise 就行。