Sleep en TypeScript: cómo esperar o hacer un delay

TypeScript no tiene un sleep integrado. Escribe una función que devuelva una Promise<void> que setTimeout resuelve después del retardo, y luego espérala con await dentro de una función 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) solo pausa main. El programa no se congela: los temporizadores, otras funciones async y la E/S siguen funcionando mientras espera.

Cómo funciona la función sleep

setTimeout(resolve, ms) programa la llamada a resolve al cabo de ms milisegundos, y llamar a resolve cumple la promesa. await sobre esa promesa suspende la función async hasta entonces.

El argumento de tipo <void> importa. Un new Promise(...) suelto no infiere su tipo a partir de las llamadas a resolve, así que sin él sleep devolvería Promise<unknown>. Y void es lo que permite llamar a resolve sin valor: en una Promise<number>, resolve() sin argumento es un error de compilación. Cuando la función tiene un tipo de retorno declarado, el argumento de tipo puede ir ahí:

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 garantiza un mínimo, no un tiempo exacto: el callback se ejecuta cuando ha pasado el retardo y el event loop está libre. Cuenta con unos pocos milisegundos de margen.

Sleep dentro de un bucle

await sleep() dentro de un bucle for o for...of hace una pausa entre iteraciones, y así es como se regula el ritmo del trabajo (límites de peticiones, sondeos, animaciones en una 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);

Esto no funciona dentro de forEach: ignora la promesa que devuelve cada callback async, así que todas las iteraciones empiezan a la vez y nada espera. Usa un bucle for o for...of, como se explica en la página de async/await.

Reintentar con un retardo

Un uso real habitual: intentar una operación y, si falla, esperar y volver a intentarlo, duplicando la espera cada vez (backoff exponencial).

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

El return await fn() dentro de try importa: sin await, se devolvería una promesa rechazada antes de que el catch pudiera verla.

Un sleep cancelable

Un sleep normal no se puede interrumpir. Para dejar de esperar antes (el usuario pulsó Cancelar, empezó un apagado), pasa un AbortSignal y limpia el temporizador cuando se dispare:

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

El programa termina justo después de la cancelación porque se limpió el temporizador largo. Sin clearTimeout, Node seguiría en marcha hasta que pasaran los 5 segundos.

Los temporizadores con promesas de Node

Node incluye una versión con promesas de setTimeout en el módulo node:timers/promises, así que en código de Node puedes importarla en lugar de escribir la función auxiliar. También acepta un valor con el que resolverse y 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
}

Los tipos vienen de @types/node (npm i -D @types/node). Este módulo no existe en los navegadores, donde la función auxiliar de una línea es la opción portable.

No existe un sleep bloqueante

Los lenguajes con hilos tienen un sleep que bloquea el hilo actual. JavaScript ejecuta tu código en un único hilo con un event loop, así que un sleep bloqueante congelaría todo lo demás: no se dispararía ningún temporizador, no se atendería ninguna respuesta de red y, en un navegador, la página dejaría de responder. Un bucle activo que gira hasta que el reloj pasa de cierta hora hace exactamente eso, y nunca es la herramienta correcta.

El sleep asíncrono es cómo funciona la espera en JavaScript y TypeScript: la función se suspende, el hilo queda libre y la función se reanuda cuando se dispara el temporizador. Atomics.wait sí puede bloquear de verdad, pero solo sobre un SharedArrayBuffer, y los navegadores lo prohíben en el hilo principal; existe para coordinar hilos worker, no para hacer retardos.