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

המנגנון של promises (מצבים, תור ה-microtasks, שרשור) הוא JavaScript רגיל, ומוסבר ב-promises ב-JavaScript. הדף הזה עוסק בטיפוסים.

טיפוס ל-new Promise ול-resolve

כש-new Promise הוא ערך ההחזרה של פונקציה עם טיפוס החזרה מוצהר, T מגיע משם. לבדו, TypeScript לא מסיק את T מהקריאות ל-resolve, ומקבלים 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, ולכן resolve("42") ב-Promise<number> היא שגיאת קומפילציה. ו-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 חדש שהטיפוס שלו נקבע לפי מה שה-callback שלו מחזיר. אם ה-callback מחזיר 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"));

הפרמטר של ה-callback של catch מוגדר כ-any בספרייה הסטנדרטית, ולא כ-unknown. שום דבר לא מונע מכם לכתוב e.message על ערך שעשוי להיות מחרוזת. תנו לו את הטיפוס unknown, כמו למעלה, וצמצמו לפני השימוש. try/catch סביב await עדיף: תחת strict, משתנה ה-catch שלו כבר unknown (ראו טיפול בשגיאות).

Promise.all מחזיר tuple

כשמקבל ליטרל מערך של promises מטיפוסים שונים, Promise.all מחזיר promise של tuple, וכל מיקום שומר על הטיפוס שלו:

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

אפשר לערבב גם ערכים שאינם promises, והם עוברים בלי שינוי. 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();

r.value קיים רק אחרי בדיקת status, כי לגרסה הנדחית אין value. reason הוא any, מאותה סיבה כמו ב-catch. ה-filter משתמש ב-type predicate כדי שהמערך המסונן יקבל את הטיפוס של תוצאות מוצלחות.

עטיפת API מבוסס callback ב-promise

ממשקי API ישנים מדווחים על תוצאות דרך callback, לרוב בסגנון 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).

טעויות נפוצות

• החזרת T במקום שבו החתימה אומרת Promise<T>, או להפך. פונקציה שאינה async שהוצהרה כ-Promise<User> חייבת להחזיר promise; פונקציית async מחזירה אחד אוטומטית.
• שכחה לטפל ב-promise. קריאה כמו save(user); בלי await, then או catch עוברת קומפילציה, ודחייה הופכת ל-unhandled rejection (שמסיימת תהליך Node כברירת מחדל). כלל ה-typescript-eslint no-floating-promises תופס את אלה.
• הסתמכות על הטיפוס של .catch((e) => ...). ה-e שלו הוא any. תנו לו את הטיפוס unknown.
• שימוש ב-new Promise סביב משהו שכבר מחזיר promise. פשוט החזירו את ה-promise הקיים או עשו לו await.