Sleep in TypeScript: come attendere o creare un ritardo

TypeScript non ha uno sleep integrato. Scrivi una funzione che restituisce una Promise<void> che setTimeout risolve dopo il ritardo, poi fanne l'await dentro una funzione 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) mette in pausa solo main. Il programma non si blocca: i timer, le altre funzioni async e l'I/O continuano a girare mentre aspetta.

Come funziona la funzione sleep

setTimeout(resolve, ms) programma la chiamata a resolve dopo ms millisecondi, e chiamare resolve conclude la promise. Un await su quella promise sospende la funzione async fino a quel momento.

L'argomento di tipo <void> è importante. Un new Promise(...) da solo non inferisce il suo tipo dalle chiamate a resolve, quindi senza di esso sleep restituirebbe Promise<unknown>. Ed è void che permette di chiamare resolve senza valore: in una Promise<number>, resolve() senza argomenti è un errore di compilazione. Quando la funzione ha un tipo di ritorno dichiarato, l'argomento di tipo può andare lì:

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 garantisce un tempo minimo, non esatto: la callback viene eseguita quando il ritardo è trascorso e l'event loop è libero. Mettiti in conto qualche millisecondo di margine.

Sleep dentro un ciclo

await sleep() dentro un ciclo for o for...of fa una pausa tra un'iterazione e l'altra, ed è così che dosi il lavoro (limiti di frequenza, polling, animazioni nel terminale):

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

Non funziona dentro forEach: ignora la promise restituita da ogni callback async, quindi tutte le iterazioni partono insieme e nulla aspetta. Usa un ciclo for o for...of, come spiegato nella pagina su async/await.

Riprovare con un ritardo

Un uso reale comune: prova un'operazione e, se fallisce, aspetta e riprova, raddoppiando l'attesa ogni volta (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();

Il return await fn() dentro il try è importante: senza await, una promise rifiutata verrebbe restituita prima che il catch possa vederla.

Uno sleep annullabile

Uno sleep semplice non si può interrompere. Per smettere di aspettare prima (l'utente ha premuto Annulla, è iniziato uno spegnimento), passa un AbortSignal e cancella il timer quando scatta:

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

Il programma termina subito dopo l'annullamento perché il timer lungo è stato cancellato. Senza clearTimeout, Node continuerebbe a girare finché non fossero trascorsi i 5 secondi.

I timer con promise integrati in Node

Node include una versione con promise di setTimeout nel modulo node:timers/promises, quindi nel codice Node puoi importarla invece di scrivere l'helper. Accetta anche un valore con cui risolversi e 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
}

I tipi arrivano da @types/node (npm i -D @types/node). Questo modulo non esiste nei browser, dove l'helper di una riga è la scelta portabile.

Non esiste uno sleep bloccante

I linguaggi con i thread hanno uno sleep che blocca il thread corrente. JavaScript esegue il tuo codice su un solo thread con un event loop, quindi uno sleep bloccante congelerebbe tutto il resto: nessun timer scatta, nessuna risposta di rete viene gestita, e in un browser la pagina smette di rispondere. Un ciclo attivo che gira finché l'orologio non supera un certo istante fa esattamente questo, e non è mai lo strumento giusto.

Lo sleep asincrono è il modo in cui si aspetta in JavaScript e TypeScript: la funzione viene sospesa, il thread è libero, e la funzione riprende quando scatta il timer. Atomics.wait può bloccare davvero, ma solo su uno SharedArrayBuffer, e i browser lo vietano sul thread principale; esiste per coordinare i worker thread, non per creare ritardi.