Sleep в TypeScript: как сделать паузу или задержку

Встроенного sleep в TypeScript нет. Напишите функцию, которая возвращает Promise<void>, разрешаемый через setTimeout после задержки, и ждите её через await внутри функции 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) приостанавливает только main. Программа не замирает: пока функция ждёт, таймеры, другие async-функции и ввод-вывод продолжают работать.

Как работает функция sleep

setTimeout(resolve, ms) планирует вызов resolve через ms миллисекунд, а вызов resolve завершает промис. await на этом промисе приостанавливает async-функцию до этого момента.

Аргумент типа <void> важен. Отдельно стоящий new Promise(...) не выводит свой тип из вызовов resolve, поэтому без него sleep возвращала бы Promise<unknown>. А void позволяет вызывать resolve без значения: в Promise<number> вызов resolve() без аргумента даёт ошибку компиляции. Если у функции объявлен тип возвращаемого значения, аргумент типа можно указать там:

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 гарантирует минимальное, а не точное время: колбэк выполняется, когда задержка прошла и цикл событий свободен. Рассчитывайте на запас в несколько миллисекунд.

Пауза внутри цикла

await sleep() внутри цикла for или for...of делает паузу между итерациями. Так задают темп работы (ограничения частоты запросов, опрос, анимации в терминале):

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

Внутри forEach это не работает: он игнорирует промис, который возвращает каждый async-колбэк, поэтому все итерации запускаются сразу и ничего не ждёт. Используйте цикл for или for...of, как объясняется на странице async/await.

Повтор с задержкой

Частый реальный случай: попробовать выполнить операцию, а если она не удалась, подождать и попробовать снова, каждый раз удваивая ожидание (экспоненциальная задержка, 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() внутри try здесь важен: без await отклонённый промис был бы возвращён раньше, чем catch успел бы его увидеть.

Отменяемый sleep

Простой sleep нельзя прервать. Чтобы перестать ждать раньше (пользователь нажал «Отмена», началось завершение работы), передайте AbortSignal и очистите таймер, когда сигнал сработает:

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

Программа завершается сразу после отмены, потому что долгий таймер очищен. Без clearTimeout Node продолжал бы работать, пока не истекут 5 секунд.

Встроенные промис-таймеры Node

В Node есть промис-версия setTimeout в модуле node:timers/promises, поэтому в коде для Node её можно импортировать вместо того, чтобы писать свою функцию. Она также принимает значение, с которым разрешится промис, и 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
}

Типы берутся из @types/node (npm i -D @types/node). В браузерах этого модуля нет, и там переносимый вариант: вспомогательная функция в одну строку.

Блокирующего sleep не существует

В языках с потоками есть sleep, который блокирует текущий поток. JavaScript выполняет ваш код в одном потоке с циклом событий, поэтому блокирующий sleep заморозил бы всё остальное: таймеры не срабатывают, сетевые ответы не обрабатываются, а в браузере страница перестаёт отвечать. Цикл активного ожидания, который крутится, пока часы не дойдут до нужного времени, делает ровно это, и он никогда не бывает правильным решением.

Асинхронный sleep и есть способ ждать в JavaScript и TypeScript: функция приостанавливается, поток свободен, и функция продолжает работу, когда срабатывает таймер. Atomics.wait действительно умеет блокировать, но только на SharedArrayBuffer, и браузеры запрещают его в главном потоке; он существует для координации рабочих потоков, а не для задержек.