TypeScript sleep: warten und verzögern in TypeScript

TypeScript hat kein eingebautes sleep. Schreibe eine Funktion, die ein Promise<void> zurückgibt, das setTimeout nach der Verzögerung auflöst, und warte dann in einer async-Funktion mit await darauf:

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) pausiert nur main. Das Programm ist nicht eingefroren: Timer, andere async-Funktionen und I/O laufen weiter, während es wartet.

Wie die sleep-Funktion funktioniert

setTimeout(resolve, ms) plant, dass resolve nach ms Millisekunden aufgerufen wird, und der Aufruf von resolve schließt das Promise ab. await auf dieses Promise hält die async-Funktion bis dahin an.

Das Typargument <void> ist wichtig. Ein alleinstehendes new Promise(...) leitet seinen Typ nicht aus den Aufrufen von resolve ab, ohne es würde sleep also Promise<unknown> zurückgeben. Und void erlaubt, resolve ohne Wert aufzurufen: In einem Promise<number> ist resolve() ohne Argument ein Compilerfehler. Hat die Funktion einen deklarierten Rückgabetyp, kann das Typargument stattdessen dort stehen:

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 garantiert eine Mindestzeit, keine genaue: Der Callback läuft, wenn die Verzögerung vorbei und die Event Loop frei ist. Rechne mit ein paar Millisekunden Spielraum.

sleep in einer Schleife

await sleep() in einer Schleife mit for oder for...of pausiert zwischen den Durchläufen, und so taktest du Arbeit (Rate Limits, Polling, Animationen im Terminal):

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

In forEach funktioniert das nicht: Es ignoriert das Promise, das jeder async-Callback zurückgibt, also starten alle Durchläufe auf einmal, und nichts wartet. Nimm eine Schleife mit for oder for...of, wie auf der Seite zu async/await erklärt.

Retry mit Verzögerung

Ein häufiger echter Einsatz: Probiere eine Operation, und wenn sie scheitert, warte und versuche es erneut, wobei sich die Wartezeit jedes Mal verdoppelt (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();

Das return await fn() im try ist wichtig: Ohne await würde ein abgelehntes Promise zurückgegeben, bevor der catch es sehen könnte.

Ein abbrechbares sleep

Ein einfaches sleep lässt sich nicht unterbrechen. Um früher mit dem Warten aufzuhören (jemand hat auf Abbrechen gedrückt, ein Shutdown hat begonnen), übergib ein AbortSignal und lösche den Timer, wenn es auslöst:

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

Das Programm endet direkt nach dem Abbruch, weil der lange Timer gelöscht wurde. Ohne clearTimeout würde Node weiterlaufen, bis die 5 Sekunden um sind.

Die eingebauten Promise-Timer von Node

Node liefert im Modul node:timers/promises eine Promise-Version von setTimeout mit, in Node-Code kannst du sie also importieren, statt die Hilfsfunktion zu schreiben. Sie akzeptiert auch einen Wert, mit dem aufgelöst wird, und ein 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
}

Die Typen kommen aus @types/node (npm i -D @types/node). Dieses Modul gibt es in Browsern nicht, dort ist die einzeilige Hilfsfunktion die portable Wahl.

Es gibt kein blockierendes sleep

Sprachen mit Threads haben ein sleep, das den aktuellen Thread blockiert. JavaScript führt deinen Code auf einem einzigen Thread mit einer Event Loop aus, ein blockierendes sleep würde also alles andere einfrieren: Keine Timer lösen aus, keine Netzwerkantworten werden verarbeitet, und im Browser reagiert die Seite nicht mehr. Eine Busy-Schleife, die dreht, bis die Uhr einen Zeitpunkt überschreitet, tut genau das und ist nie das richtige Werkzeug.

Das asynchrone sleep ist die Art, wie Warten in JavaScript und TypeScript funktioniert: Die Funktion wird angehalten, der Thread ist frei, und die Funktion läuft weiter, wenn der Timer auslöst. Atomics.wait kann wirklich blockieren, aber nur auf einem SharedArrayBuffer, und Browser verbieten es im Hauptthread; es dient der Koordination von Worker-Threads, nicht für Verzögerungen.