Async Await TypeScript: Tipe, Error, dan Panggilan Paralel

Fungsi async di TypeScript selalu mengembalikan promise: kalau isinya mengembalikan string, tipenya adalah Promise<string>. Di dalamnya, await membuka Promise<T> menjadi T.

type Order = { id: number; total: number };

function fetchOrder(id: number): Promise<Order> {
    return new Promise((resolve) => setTimeout(() => resolve({ id, total: 42 }), 20));
}

async function orderSummary(id: number): Promise<string> {
    const order = await fetchOrder(id); // order: Order, not Promise<Order>
    return `Order #${order.id}: $${order.total.toFixed(2)}`;
}

async function main() {
    const text = await orderSummary(7);
    console.log(text); // Order #7: $42.00
}
main();

Perilaku saat runtime (apa yang dijeda oleh await, event loop) adalah urusan JavaScript, dibahas di async/await JavaScript. Bagian TypeScript adalah tipe yang masuk dan keluar.

Tipe Kembalian Fungsi Async

Tipe kembalian yang dideklarasikan untuk fungsi async harus Promise<...>, meskipun isinya mengembalikan nilai biasa. TypeScript menyimpulkannya kalau kamu tidak menuliskannya.

async function count(): Promise<number> {
    return 3; // a number, wrapped in a promise automatically
}

async function log(message: string): Promise<void> {
    console.log(message); // returns nothing: Promise<void>
}

const double = async (n: number) => n * 2; // inferred: (n: number) => Promise<number>

class Repo {
    async findName(id: number): Promise<string | undefined> {
        return id === 1 ? "Ada" : undefined;
    }
}

async function main() {
    await log("start");
    console.log(await count(), await double(21)); // 3 42
    console.log(await new Repo().findName(2));   // undefined
}
main();

Menulis async function count(): number menghasilkan error TS1064 (The return type of an async function or method must be the global Promise<T> type. Did you mean to write 'Promise<number>'?). Utility type Awaited<T> memberikan tipe yang sudah dibuka: Awaited<ReturnType<typeof count>> adalah number.

Lupa Menulis await

await yang terlewat membuatmu memegang Promise<T>, bukan T. TypeScript menangkap sebagian besar kasus ini karena tipenya jadi tidak cocok:

async function isAdmin(id: number): Promise<boolean> {
    return id === 1;
}

async function main() {
    const ok = isAdmin(2); // forgot await: ok is Promise<boolean>

    // @ts-expect-error: This condition will always return true since this 'Promise<boolean>' is always defined.
    if (ok) console.log("access granted (wrong!)");

    if (await isAdmin(2)) console.log("never printed");
    else console.log("access denied"); // correct
}
main();

Bug if (ok) ini nyata: objek promise selalu truthy, jadi akses diberikan. TypeScript melaporkannya sebagai TS2801. Memberikan promise ke variabel boolean, atau membaca property yang tidak dimiliki promise, juga akan gagal dikompilasi. Panggilan yang hasilnya kamu abaikan (save(user);) tidak tertangkap; aturan typescript-eslint no-floating-promises menangani kasus itu.

Menangani Error dengan try/catch

Promise yang di-reject membuat await melempar error, jadi try/catch biasa bisa dipakai. Dengan strict, variabel di catch bertipe unknown, dan kamu mempersempitnya sebelum membaca .message:

async function loadConfig(name: string): Promise<{ port: number }> {
    if (name !== "prod") throw new Error(`no config named "${name}"`);
    return { port: 443 };
}

async function main() {
    try {
        const cfg = await loadConfig("dev");
        console.log(cfg.port);
    } catch (e) {
        // e: unknown
        if (e instanceof Error) console.log("failed:", e.message);
        else console.log("failed with", e);
    } finally {
        console.log("cleanup runs either way");
    }
}
main();
// failed: no config named "dev"
// cleanup runs either way

throw di dalam fungsi async me-reject promise-nya, bukan melempar error di tempat pemanggilan. Pola lainnya, termasuk class error kustom dan mengembalikan hasil alih-alih melempar error, ada di halaman penanganan error.

Top-Level await

await di luar fungsi apa pun hanya berjalan di ES module. File yang dikompilasi sebagai CommonJS (kasus contoh-contoh ini, dan proyek Node tanpa "type": "module") menolaknya:

// This does not compile: top-level await in a CommonJS file.
const data = await Promise.resolve([1, 2, 3]);
console.log(data);

index.ts(2,14): error TS1309: The current file is a CommonJS module and cannot use 'await' at the top level.

Bungkus kodenya dalam fungsi async main lalu panggil, seperti yang dilakukan setiap contoh di halaman ini. Di proyek ES module ("type": "module" di package.json dengan module diatur ke node16 atau nodenext, atau module: "esnext" untuk bundler), await di top level diizinkan.

Berurutan vs Paralel

Setiap await menunggu promise-nya sebelum baris berikutnya dimulai. Untuk panggilan yang saling independen, mulai semuanya terlebih dahulu lalu await bersama-sama dengan Promise.all:

const wait = (ms: number, label: string) =>
    new Promise<string>((resolve) => setTimeout(() => {
        console.log(`  finished ${label}`);
        resolve(label);
    }, ms));

async function main() {
    console.log("sequential:");
    const a = await wait(60, "a");
    const b = await wait(20, "b"); // starts only after a is done
    console.log(" ", [a, b]);

    console.log("parallel:");
    const [c, d] = await Promise.all([wait(60, "c"), wait(20, "d")]);
    console.log(" ", [c, d]); // results keep input order
}
main();

Di bagian berurutan, b tidak bisa selesai sebelum a karena belum dimulai. Di bagian paralel, d selesai lebih dulu, dan total waktunya kira-kira sama dengan panggilan terlama, bukan jumlah semuanya. Promise.all tetap mengembalikan hasil sesuai urutan input, dengan tipe tuple.

Jebakan forEach

forEach mengabaikan promise yang dikembalikan callback async, jadi tidak ada yang menunggu pekerjaannya:

const sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));

async function main() {
    const ids = [1, 2, 3];

    ids.forEach(async (id) => {
        await sleep(10);
        console.log("forEach saved", id);
    });
    console.log("after forEach (runs first!)");
    await sleep(50); // only so the output above appears in order

    for (const id of ids) {
        await sleep(10);
        console.log("for...of saved", id);
    }
    console.log("after for...of (really after)");

    await Promise.all(ids.map(async (id) => {
        await sleep(10);
        console.log("map saved", id);
    }));
    console.log("after Promise.all (really after)");
}
main();

for...of dengan await memproses item satu per satu; Promise.all dengan map menjalankannya secara paralel dan menunggu semuanya. forEach tidak melakukan keduanya, dan TypeScript tidak memberi peringatan, karena callback yang bertipe mengembalikan void tetap menerima callback yang mengembalikan promise.

Iterasi Async dengan for await

for await...of melakukan perulangan pada async iterable, seperti async generator, sambil meng-await setiap nilainya:

async function* pages(total: number): AsyncGenerator<string[]> {
    for (let page = 1; page <= total; page++) {
        await new Promise((r) => setTimeout(r, 10));
        yield [`item ${page}a`, `item ${page}b`];
    }
}

async function main() {
    for await (const batch of pages(3)) {
        console.log(batch.join(", ")); // batch: string[]
    }
}
main();

Tipe elemennya berasal dari anotasi AsyncGenerator<T> pada generator, atau dari inferensi kalau kamu tidak menuliskannya.