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، وحلقة الأحداث) هو 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);) فلا يُكتشف؛ وتغطيه قاعدة typescript-eslint المسماة no-floating-promises.

معالجة الأخطاء بـ 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. الملف المُترجم كـ 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 ("type": "module" في package.json مع ضبط module على node16 أو nodenext، أو module: "esnext" مع أداة تجميع) تكون 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 الذي تعيده دالة async، فلا شيء ينتظر العمل:

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، لأن دالة نوعها يعيد void تقبل دالة تعيد promise.

التكرار غير المتزامن بـ for await

تكرر for await...of على كائن قابل للتكرار غير متزامن، مثل مولّد غير متزامن، وتنتظر كل قيمة:

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> للمولّد، أو من الاستنتاج إذا لم تكتبه.