Promise في TypeScript: 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
});

آليات الـ promise (الحالات، وطابور المهام الدقيقة، والتسلسل) هي 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 جديدًا نوعه مأخوذ مما تعيده دالتها. إذا أعادت الدالة 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"));

معامل دالة 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 أو يُرفض بأول مُدخل يستقر، ونوعه union المُدخلات؛ ويُحل Promise.any بأول نجاح، ولا يُرفض بـ AggregateError إلا إذا فشلت كل المُدخلات.

Promise.allSettled ونوع نتيجته

ينتظر Promise.allSettled كل المُدخلات ولا يُرفض أبدًا. كل نتيجة من النوع PromiseSettledResult<T>، وهو union تضيّقه بالحقل 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 حتى تُحدد المصفوفة الناتجة كنتائج ناجحة.

تغليف واجهة Callback في Promise

الواجهات الأقدم تُبلغ عن النتائج عبر دالة 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)، وكثير من الوحدات المدمجة لها أصلًا نسخ تعمل بالـ promises (node:fs/promises، node:timers/promises).

أخطاء شائعة

• إعادة T حيث يقول التوقيع Promise<T>، أو العكس. الدالة غير المتزامنة المصرّح بأنها تعيد Promise<User> يجب أن تعيد promise؛ أما دالة async فتعيد واحدًا تلقائيًا.
• نسيان التعامل مع promise. استدعاء مثل save(user); دون await أو then أو catch يُترجم دون مشكلة، ويصبح الرفض رفضًا غير معالج (ينهي عملية Node افتراضيًا). قاعدة typescript-eslint no-floating-promises تكتشف هذه الحالات.
• الثقة بنوع .catch((e) => ...). المتغير e فيها نوعه any. حدد نوعه كـ unknown.
• استخدام new Promise حول شيء يعيد promise أصلًا. أعد الـ promise الموجود أو استخدم await معه مباشرة.