Sleep en TypeScript : attendre ou faire une pause

TypeScript n'a pas de sleep intégré. Écrivez une fonction qui renvoie une Promise<void> que setTimeout résout après le délai, puis attendez-la avec await dans une fonction 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) ne met en pause que main. Le programme n'est pas figé : les timers, les autres fonctions async et les entrées/sorties continuent pendant l'attente.

Comment fonctionne la fonction sleep

setTimeout(resolve, ms) programme l'appel de resolve après ms millisecondes, et appeler resolve règle la promesse. await sur cette promesse suspend la fonction async jusque-là.

L'argument de type <void> a son importance. Un new Promise(...) isolé ne déduit pas son type des appels à resolve, donc sans lui sleep renverrait Promise<unknown>. Et c'est void qui permet d'appeler resolve sans valeur : dans une Promise<number>, resolve() sans argument est une erreur de compilation. Quand la fonction a un type de retour déclaré, l'argument de type peut aller là à la place :

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 garantit une durée minimale, pas une durée exacte : le callback s'exécute quand le délai est écoulé et que la boucle d'événements est libre. Comptez quelques millisecondes de marge.

Faire une pause dans une boucle

await sleep() dans une boucle for ou for...of fait une pause entre les itérations, ce qui permet de cadencer un travail (limites de débit, polling, animations dans un 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);

Cela ne fonctionne pas dans forEach : il ignore la promesse que renvoie chaque callback async, donc toutes les itérations démarrent en même temps et rien n'attend. Utilisez une boucle for ou for...of, comme l'explique la page async/await.

Réessayer après un délai

Un usage réel courant : tenter une opération et, si elle échoue, attendre puis réessayer, en doublant l'attente à chaque fois (backoff exponentiel).

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

Le return await fn() dans le try a son importance : sans await, une promesse rejetée serait renvoyée avant que le catch puisse la voir.

Un sleep annulable

Un sleep simple ne peut pas être interrompu. Pour arrêter d'attendre plus tôt (l'utilisateur a cliqué sur Annuler, un arrêt a commencé), passez un AbortSignal et effacez le timer quand il se déclenche :

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

Le programme se termine juste après l'annulation, car le long timer a été effacé. Sans clearTimeout, Node continuerait à tourner jusqu'à la fin des 5 secondes.

Les timers à promesses intégrés de Node

Node fournit une version à promesses de setTimeout dans le module node:timers/promises, donc dans du code Node vous pouvez l'importer au lieu d'écrire la fonction. Elle accepte aussi une valeur avec laquelle se résoudre et un 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
}

Les types viennent de @types/node (npm i -D @types/node). Ce module n'existe pas dans les navigateurs, où la fonction d'une ligne est le choix portable.

Il n'y a pas de sleep bloquant

Les langages avec des threads ont un sleep qui bloque le thread courant. JavaScript exécute votre code sur un seul thread avec une boucle d'événements, donc un sleep bloquant figerait tout le reste : aucun timer ne se déclenche, aucune réponse réseau n'est traitée, et dans un navigateur la page ne répond plus. Une boucle active qui tourne jusqu'à ce que l'horloge dépasse une heure donnée fait exactement cela, et ce n'est jamais le bon outil.

Le sleep async est la façon d'attendre en JavaScript et en TypeScript : la fonction est suspendue, le thread est libre, et la fonction reprend quand le timer se déclenche. Atomics.wait peut vraiment bloquer, mais seulement sur un SharedArrayBuffer, et les navigateurs l'interdisent sur le thread principal ; il sert à coordonner des threads workers, pas à créer des délais.