Promise di TypeScript: Promise<T>, Promise.all, allSettled

Di TypeScript, sebuah promise bertipe Promise<T>, dengan T adalah tipe nilai yang dihasilkannya saat resolve. Fungsi yang mengembalikan promise mendeklarasikannya di tipe kembaliannya, dan nilai yang kamu dapat dari then atau await bertipe 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
});

Mekanisme promise (state, antrean microtask, chaining) adalah JavaScript biasa, dibahas di promise JavaScript. Halaman ini membahas tipenya.

Memberi Tipe pada new Promise dan resolve

Kalau new Promise adalah nilai kembalian fungsi yang tipe kembaliannya dideklarasikan, T berasal dari situ. Kalau berdiri sendiri, TypeScript tidak menyimpulkan T dari pemanggilan resolve, dan kamu mendapat Promise<unknown>. Berikan argumen tipenya secara eksplisit:

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

Ada dua detail. resolve diberi tipe dari T, jadi resolve("42") di Promise<number> adalah error kompilasi. Lalu resolve() tanpa argumen hanya diperbolehkan kalau T memuat void: di Promise<number> hasilnya error TS2794 (Expected 1 arguments, but got 0. Did you forget to include 'void' in your type argument to 'Promise'?).

Sisi reject tidak bertipe. Tidak ada Promise<T, E>: sebuah promise bisa reject dengan nilai apa pun.

then, catch dan finally

Setiap then mengembalikan promise baru yang tipenya ditentukan oleh apa yang dikembalikan callback-nya. Kalau callback mengembalikan promise, TypeScript membukanya, jadi kamu tidak akan pernah mendapat 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"));

Parameter callback catch diberi tipe any di standard library, bukan unknown. Tidak ada yang mencegahmu menulis e.message pada nilai yang mungkin berupa string. Anotasi sebagai unknown, seperti di atas, lalu persempit tipenya sebelum dipakai. try/catch di sekitar await lebih baik: dengan strict, variabel catch-nya sudah bertipe unknown (lihat penanganan error).

Promise.all Mengembalikan Tuple

Kalau diberi array literal berisi promise dengan tipe berbeda, Promise.all mengembalikan promise berisi tuple, dengan setiap posisi mempertahankan tipenya sendiri:

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

Nilai yang bukan promise boleh dicampur dan diteruskan apa adanya. Promise.all langsung reject begitu satu input reject, dan hasil lainnya hilang. Promise.race resolve atau reject mengikuti yang pertama selesai dan bertipe union dari semua input; Promise.any resolve dengan keberhasilan pertama dan reject dengan AggregateError hanya kalau semua input gagal.

Promise.allSettled dan Tipe Hasilnya

Promise.allSettled menunggu setiap input dan tidak pernah reject. Setiap hasil adalah PromiseSettledResult<T>, sebuah union yang kamu persempit dengan field 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 hanya ada setelah pengecekan status, karena varian rejected tidak punya value. reason bertipe any, dengan alasan yang sama seperti di catch. filter memakai type predicate supaya array hasil saringannya bertipe hasil fulfilled.

Membungkus API Callback dalam Promise

API lama melaporkan hasilnya lewat callback, sering dengan gaya Node (err, result) => void. Bungkus sekali dalam fungsi yang mengembalikan promise bertipe, dan sisa kodenya bisa memakai 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();

Di Node, util.promisify melakukan hal ini untuk fungsi yang mengikuti konvensi (err, result), dan banyak module bawaan sudah punya versi promise (node:fs/promises, node:timers/promises).

Kesalahan Umum

• Mengembalikan T padahal signature-nya Promise<T>, atau sebaliknya. Fungsi non-async yang dideklarasikan Promise<User> harus mengembalikan promise; fungsi async mengembalikannya secara otomatis.
• Lupa menangani promise. Pemanggilan seperti save(user); tanpa await, then atau catch tetap lolos kompilasi, dan rejection-nya menjadi unhandled rejection (yang secara default menghentikan proses Node). Aturan typescript-eslint no-floating-promises menangkap kasus seperti ini.
• Memercayai tipe .catch((e) => ...). e-nya bertipe any. Anotasi sebagai unknown.
• Memakai new Promise di sekitar sesuatu yang sudah mengembalikan promise. Cukup return atau await promise yang sudah ada.