Sleep في TypeScript: كيف تنتظر أو تؤخر التنفيذ

لا يوجد في TypeScript دالة sleep مدمجة. اكتب دالة تعيد Promise<void> يحلّها setTimeout بعد مدة التأخير، ثم انتظرها بـ await داخل دالة async:

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

async function main() {
    console.log("start");
    await sleep(300); // pause this function for 300 ms
    console.log("300 ms later");
}
main();

توقف await sleep(300) الدالة main وحدها. البرنامج لا يتجمد: المؤقتات والدوال غير المتزامنة الأخرى وعمليات الإدخال والإخراج تستمر في العمل أثناء الانتظار.

كيف تعمل دالة sleep

يجدول setTimeout(resolve, ms) استدعاء resolve بعد ms ملّي ثانية، واستدعاء resolve يُنهي الـ promise. وawait على ذلك الـ promise تعلّق الدالة غير المتزامنة حتى تلك اللحظة.

وسيط النوع <void> مهم. التعبير new Promise(...) المستقل لا يستنتج نوعه من استدعاءات resolve، لذلك دونه تعيد sleep النوع Promise<unknown>. وvoid هو ما يسمح باستدعاء resolve دون قيمة: في Promise<number> يكون resolve() دون وسيط خطأ ترجمة. وعندما يكون للدالة نوع إعادة مصرّح به، يمكن وضع وسيط النوع هناك بدلًا من ذلك:

function sleep(ms: number): Promise<void> {
    return new Promise((resolve) => setTimeout(resolve, ms));
}

// A variant that resolves with a value after the delay.
function delay<T>(ms: number, value: T): Promise<T> {
    return new Promise((resolve) => setTimeout(() => resolve(value), ms));
}

async function main() {
    await sleep(100);
    const answer = await delay(100, 42); // answer: number
    console.log(answer + 1); // 43
}
main();

يضمن setTimeout حدًا أدنى لا وقتًا دقيقًا: تعمل الدالة عندما تنقضي المدة وتكون حلقة الأحداث متفرغة. توقّع فارقًا ببضع ملّي ثوان.

الانتظار داخل حلقة

await sleep() داخل حلقة for أو for...of توقف التنفيذ بين التكرارات، وهكذا تضبط وتيرة العمل (حدود المعدل، والاستطلاع الدوري، والحركات في الطرفية):

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

async function countdown(from: number): Promise<void> {
    for (let i = from; i > 0; i--) {
        console.log(i);
        await sleep(200);
    }
    console.log("liftoff");
}

countdown(3);

هذا لا يعمل داخل forEach: فهي تتجاهل الـ promise الذي تعيده كل دالة async، فتبدأ كل التكرارات معًا ولا شيء ينتظر. استخدم حلقة for أو for...of، كما هو مشروح في صفحة async/await.

إعادة المحاولة مع تأخير

استخدام حقيقي شائع: جرّب عملية، وإذا فشلت انتظر وحاول مجددًا، مع مضاعفة مدة الانتظار في كل مرة (التراجع الأسي، exponential backoff).

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

async function retry<T>(fn: () => Promise<T>, attempts: number, baseMs: number): Promise<T> {
    for (let i = 1; ; i++) {
        try {
            return await fn();
        } catch (e) {
            if (i >= attempts) throw e;
            const wait = baseMs * 2 ** (i - 1);
            console.log(`attempt ${i} failed, waiting ${wait} ms`);
            await sleep(wait);
        }
    }
}

let calls = 0;
async function flakyRequest(): Promise<string> {
    calls++;
    if (calls < 3) throw new Error("network error");
    return "response body";
}

async function main() {
    const body = await retry(flakyRequest, 5, 50);
    console.log(body); // response body
}
main();

وجود return await fn() داخل try مهم: دون await سيُعاد الـ promise المرفوض قبل أن تتمكن catch من رؤيته.

sleep قابلة للإلغاء

لا يمكن مقاطعة sleep العادية. لإيقاف الانتظار مبكرًا (ضغط المستخدم على إلغاء، أو بدأ إيقاف التشغيل)، مرّر AbortSignal وامسح المؤقت عندما تُطلق الإشارة:

function sleep(ms: number, signal?: AbortSignal): Promise<void> {
    return new Promise((resolve, reject) => {
        if (signal?.aborted) return reject(new Error("aborted"));
        const timer = setTimeout(resolve, ms);
        signal?.addEventListener("abort", () => {
            clearTimeout(timer);
            reject(new Error("aborted"));
        }, { once: true });
    });
}

async function main() {
    const controller = new AbortController();
    setTimeout(() => controller.abort(), 50); // cancel after 50 ms

    try {
        await sleep(5000, controller.signal);
        console.log("slept the full 5 s");
    } catch (e) {
        if (e instanceof Error) console.log("woke early:", e.message); // woke early: aborted
    }
}
main();

ينتهي البرنامج فور الإلغاء لأن المؤقت الطويل مُسح. دون clearTimeout كانت Node ستستمر في العمل حتى تنقضي الثواني الخمس.

مؤقتات Promise المدمجة في Node

توفر Node نسخة من setTimeout تعمل بالـ promises في الوحدة node:timers/promises، لذلك يمكنك في كود Node استيرادها بدلًا من كتابة الدالة المساعدة. وهي تقبل أيضًا قيمة يُحل بها الـ promise وAbortSignal:

import { setTimeout as sleep } from "node:timers/promises";

async function main() {
    await sleep(1000);                              // wait one second
    const result = await sleep(500, "done");        // resolves with "done"
    const ac = new AbortController();
    await sleep(10_000, undefined, { signal: ac.signal }); // cancellable
}

تأتي الأنواع من @types/node (npm i -D @types/node). هذه الوحدة غير موجودة في المتصفحات، حيث تكون الدالة المساعدة ذات السطر الواحد هي الخيار الذي يعمل في كل مكان.

لا يوجد sleep حاجب

اللغات التي فيها خيوط لها دالة sleep تحجب الخيط الحالي. أما JavaScript فتشغّل كودك على خيط واحد مع حلقة أحداث، لذلك سيجمّد sleep الحاجب كل شيء آخر: لا تنطلق أي مؤقتات، ولا تُعالج أي استجابات شبكة، وتتوقف الصفحة في المتصفح عن الاستجابة. الحلقة المشغولة التي تدور حتى تتجاوز الساعة وقتًا معينًا تفعل ذلك بالضبط، وليست أبدًا الأداة الصحيحة.

الـ sleep غير المتزامنة هي طريقة الانتظار في JavaScript وTypeScript: تُعلّق الدالة، ويبقى الخيط متفرغًا، وتستأنف الدالة عندما يُطلق المؤقت. يستطيع Atomics.wait الحجب فعلًا، لكن على SharedArrayBuffer فقط، وتمنعه المتصفحات على الخيط الرئيسي؛ فهو موجود لتنسيق خيوط الـ workers، لا للتأخير.