Sleep w TypeScript: jak czekać lub opóźnić wykonanie

TypeScript nie ma wbudowanego sleep. Napisz funkcję zwracającą Promise<void>, który setTimeout rozwiązuje po upływie opóźnienia, a potem użyj na nim await wewnątrz funkcji 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) wstrzymuje tylko main. Program nie jest zamrożony: timery, inne funkcje async i operacje wejścia/wyjścia działają dalej, gdy on czeka.

Jak działa funkcja sleep

setTimeout(resolve, ms) planuje wywołanie resolve po ms milisekundach, a wywołanie resolve rozstrzyga promise. await na tym promise'ie zawiesza funkcję async do tego momentu.

Argument typu <void> ma znaczenie. Samodzielne new Promise(...) nie wnioskuje swojego typu z wywołań resolve, więc bez niego sleep zwracałoby Promise<unknown>. A void pozwala wywołać resolve bez wartości: w Promise<number> resolve() bez argumentu to błąd kompilacji. Gdy funkcja ma zadeklarowany typ zwracany, argument typu może trafić tam:

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 gwarantuje minimalny, a nie dokładny czas: callback uruchamia się, gdy opóźnienie minie i pętla zdarzeń jest wolna. Licz się z kilkoma milisekundami zapasu.

Sleep wewnątrz pętli

await sleep() wewnątrz pętli for lub for...of robi pauzę między iteracjami i tak właśnie ustala się tempo pracy (limity zapytań, odpytywanie, animacje w terminalu):

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

Nie działa to wewnątrz forEach: ignoruje on promise zwracany przez każdy callback async, więc wszystkie iteracje startują naraz i nic nie czeka. Użyj pętli for lub for...of, jak wyjaśnia strona async/await.

Ponawianie z opóźnieniem

Częste praktyczne zastosowanie: spróbuj wykonać operację, a jeśli się nie uda, poczekaj i spróbuj ponownie, za każdym razem podwajając czas oczekiwania (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() wewnątrz try ma znaczenie: bez await odrzucony promise zostałby zwrócony, zanim catch zdążyłby go zobaczyć.

Sleep, który można anulować

Zwykłego sleep nie da się przerwać. Aby przestać czekać wcześniej (użytkownik nacisnął Anuluj, zaczęło się zamykanie), przekaż AbortSignal i wyczyść timer, gdy sygnał zadziała:

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

Program kończy się zaraz po przerwaniu, bo długi timer został wyczyszczony. Bez clearTimeout Node działałby dalej, aż minęłoby 5 sekund.

Wbudowane timery oparte na promise'ach w Node

Node dostarcza wersję setTimeout opartą na promise'ach w module node:timers/promises, więc w kodzie dla Node możesz ją zaimportować zamiast pisać funkcję pomocniczą. Przyjmuje też wartość, którą ma się rozwiązać, i 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
}

Typy pochodzą z @types/node (npm i -D @types/node). Ten moduł nie istnieje w przeglądarkach, gdzie przenośnym wyborem jest jednolinijkowa funkcja pomocnicza.

Nie ma blokującego sleep

Języki z wątkami mają sleep, który blokuje bieżący wątek. JavaScript wykonuje twój kod na jednym wątku z pętlą zdarzeń, więc blokujący sleep zamroziłby wszystko inne: żadne timery by nie odpaliły, żadne odpowiedzi sieciowe nie byłyby obsłużone, a w przeglądarce strona przestałaby reagować. Pętla, która kręci się, dopóki zegar nie minie określonego czasu, robi dokładnie to i nigdy nie jest właściwym narzędziem.

Asynchroniczny sleep to sposób, w jaki działa czekanie w JavaScripcie i TypeScripcie: funkcja jest zawieszona, wątek jest wolny, a funkcja wznawia działanie, gdy odpali timer. Atomics.wait naprawdę potrafi blokować, ale tylko na SharedArrayBuffer, a przeglądarki zabraniają go w głównym wątku; istnieje do koordynacji wątków workerów, a nie do opóźnień.