Async Await ב-TypeScript: טיפוסים, שגיאות וקריאות במקביל

פונקציית async ב-TypeScript תמיד מחזירה promise: אם הגוף שלה מחזיר string, הטיפוס שלה הוא Promise<string>. בתוכה, await פורס Promise<T> ל-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();

ההתנהגות בזמן ריצה (מה await משהה, ה-event loop) שייכת ל-JavaScript, ומוסברת ב-async/await ב-JavaScript. החלק של TypeScript הוא הטיפוסים שנכנסים ויוצאים.

טיפוסי החזרה של פונקציות async

טיפוס ההחזרה המוצהר של פונקציית async חייב להיות Promise<...>, גם אם הגוף מחזיר את הערך הרגיל. אם משמיטים אותו, TypeScript מסיקה אותו.

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

כתיבה של async function count(): number היא השגיאה TS1064 (The return type of an async function or method must be the global Promise<T> type. Did you mean to write 'Promise<number>'?). טיפוס העזר Awaited<T> נותן את הטיפוס הפרוס: Awaited<ReturnType<typeof count>> הוא number.

שכחתם await

await חסר משאיר ביד Promise<T> במקום T. TypeScript תופסת את רוב המקרים האלה כי הטיפוסים כבר לא מתאימים:

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

הבאג של if (ok) אמיתי: אובייקט promise תמיד truthy, ולכן הגישה אושרה. TypeScript מדווחת עליו כ-TS2801. גם השמה של ה-promise למשתנה boolean, או קריאה של מאפיין שאין ל-promise, לא היו עוברות קומפילציה. קריאה שמתעלמים מהתוצאה שלה (save(user);) לא נתפסת; הכלל no-floating-promises של typescript-eslint מכסה את זה.

טיפול בשגיאות עם try/catch

promise שנדחה גורם ל-await לזרוק, ולכן try/catch רגיל עובד. תחת strict, המשתנה ב-catch הוא unknown, ומצמצמים אותו לפני שקוראים את .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 בתוך פונקציית async דוחה את ה-promise שלה במקום לזרוק במקום הקריאה. דפוסים נוספים, כולל מחלקות שגיאה מותאמות והחזרת תוצאות במקום זריקה, נמצאים בעמוד טיפול בשגיאות.

await ברמה העליונה

await מחוץ לכל פונקציה עובד רק ב-ES module. קובץ שמקומפל כ-CommonJS (המצב בדוגמאות האלה, ובפרויקטי Node בלי "type": "module") דוחה אותו:

// 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.

עטפו את הקוד בפונקציית main אסינכרונית וקראו לה, כמו שכל דוגמה בעמוד הזה עושה. בפרויקט ES module ("type": "module" ב-package.json עם module שמוגדר ל-node16 או nodenext, או module: "esnext" ל-bundler), await ברמה העליונה מותר.

סדרתי מול מקביל

כל await ממתין ל-promise שלו לפני שהשורה הבאה מתחילה. לקריאות בלתי תלויות, התחילו את כולן קודם והמתינו להן יחד עם 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();

בחצי הסדרתי, b לא יכול להסתיים לפני a כי הוא עוד לא התחיל. בחצי המקבילי, d מסתיים ראשון, והזמן הכולל הוא בערך הקריאה הארוכה ביותר ולא הסכום. Promise.all עדיין מחזיר את התוצאות בסדר הקלט, עם טיפוס של tuple.

המלכודת של forEach

forEach מתעלמת מה-promise ש-callback אסינכרוני מחזיר, ולכן אף אחד לא ממתין לעבודה:

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 עם await מעבד פריטים אחד אחרי השני; Promise.all עם map מריץ אותם במקביל וממתין לכולם. forEach לא עושה אף אחד מהשניים, ו-TypeScript לא מזהירה, כי callback שהטיפוס שלו מחזיר void מקבל גם callback שמחזיר promise.

איטרציה אסינכרונית עם for await

for await...of עוברת בלולאה על async iterable, כמו async generator, וממתינה לכל ערך:

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

טיפוס האיבר מגיע מהערת הטיפוס AsyncGenerator<T> של ה-generator, או מהסקה כשמשמיטים אותה.