Promise trong TypeScript: Promise<T>, all và allSettled

Trong TypeScript, một promise có kiểu Promise<T>, trong đó T là kiểu của giá trị mà nó resolve. Hàm trả về promise khai báo điều đó trong kiểu trả về, và giá trị bạn nhận từ then hoặc await có kiểu 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
});

Cơ chế của promise (các trạng thái, hàng đợi microtask, nối chuỗi) là JavaScript thuần, được trình bày ở promise trong JavaScript. Trang này tập trung vào kiểu.

Khai báo kiểu cho new Promise và resolve

Khi new Promise là giá trị trả về của một hàm có khai báo kiểu trả về, T được lấy từ đó. Nếu đứng riêng, TypeScript không suy ra T từ các lời gọi resolve, và bạn nhận Promise<unknown>. Hãy truyền đối số kiểu một cách tường minh:

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();

Có hai chi tiết. resolve có kiểu dựa trên T, nên resolve("42") trong một Promise<number> là lỗi biên dịch. Và resolve() không có đối số chỉ được phép khi T có chứa void: trong một Promise<number> nó là lỗi TS2794 (Expected 1 arguments, but got 0. Did you forget to include 'void' in your type argument to 'Promise'?).

Phía reject thì không có kiểu. Không có Promise<T, E>: một promise có thể reject với bất kỳ giá trị nào.

then, catch và finally

Mỗi then trả về một promise mới có kiểu theo giá trị mà callback của nó trả về. Nếu callback trả về một promise, TypeScript sẽ mở nó ra, nên bạn không bao giờ nhận 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"));

Tham số của callback catch có kiểu any trong thư viện chuẩn, không phải unknown. Không có gì ngăn bạn viết e.message trên một giá trị có thể là chuỗi. Hãy chú thích nó là unknown như ở trên, và thu hẹp kiểu trước khi dùng. try/catch bao quanh await thì tốt hơn: khi bật strict, biến catch của nó đã là unknown (xem xử lý lỗi).

Promise.all trả về một tuple

Với một mảng literal gồm các promise khác kiểu, Promise.all trả về promise của một tuple, mỗi vị trí giữ kiểu riêng của nó:

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();

Có thể trộn các giá trị không phải promise vào, và chúng đi qua mà không thay đổi. Promise.all reject ngay khi một đầu vào bị reject, và các kết quả khác bị mất. Promise.race resolve hoặc reject theo promise hoàn tất đầu tiên và có kiểu là union của các đầu vào; Promise.any resolve với lần thành công đầu tiên và chỉ reject với một AggregateError khi mọi đầu vào đều thất bại.

Promise.allSettled và kiểu kết quả của nó

Promise.allSettled chờ mọi đầu vào và không bao giờ reject. Mỗi kết quả là một PromiseSettledResult<T>, một union mà bạn thu hẹp bằng trường 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();

r.value chỉ tồn tại sau khi kiểm tra status, vì biến thể bị reject không có value. reason có kiểu any, cùng lý do như trong catch. Lệnh filter dùng một type predicate để mảng sau khi lọc có kiểu là các kết quả fulfilled.

Bọc API dùng callback thành promise

Các API cũ trả kết quả qua callback, thường theo kiểu Node (err, result) => void. Hãy bọc chúng một lần trong một hàm trả về promise có kiểu, rồi phần code còn lại có thể dùng 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();

Trong Node, util.promisify làm việc này cho các hàm tuân theo quy ước (err, result), và nhiều module có sẵn đã có phiên bản promise (node:fs/promises, node:timers/promises).

Những lỗi thường gặp

• Trả về T trong khi chữ ký ghi Promise<T>, hoặc ngược lại. Một hàm không phải async khai báo Promise<User> phải trả về promise; hàm async tự động trả về promise.
• Quên xử lý promise. Một lời gọi như save(user); không có await, then hay catch vẫn biên dịch bình thường, và một lần reject sẽ trở thành unhandled rejection (theo mặc định sẽ làm tiến trình Node dừng lại). Quy tắc no-floating-promises của typescript-eslint bắt được các trường hợp này.
• Tin vào kiểu của .catch((e) => ...). e của nó có kiểu any. Hãy chú thích nó là unknown.
• Dùng new Promise bao quanh thứ đã trả về promise. Chỉ cần trả về hoặc await promise có sẵn.