TypeScript Sleep: How to Wait or Delay in TypeScript

TypeScript has no built-in sleep. Write a function that returns a Promise<void> which setTimeout resolves after the delay, then await it inside an async function:

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) pauses only main. The program is not frozen: timers, other async functions and I/O keep running while it waits.

How the sleep Function Works

setTimeout(resolve, ms) schedules resolve to be called after ms milliseconds, and calling resolve settles the promise. await on that promise suspends the async function until then.

The <void> type argument matters. A standalone new Promise(...) does not infer its type from the resolve calls, so without it sleep would return Promise<unknown>. And void is what allows resolve to be called with no value: in a Promise<number>, resolve() with no argument is a compile error. When the function has a declared return type, the type argument can go there instead:

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 guarantees a minimum, not an exact time: the callback runs when the delay has passed and the event loop is free. Expect a few milliseconds of slack.

Sleeping Inside a Loop

await sleep() inside a for or for...of loop pauses between iterations, which is how you pace work (rate limits, polling, animations in a 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);

This does not work inside forEach: it ignores the promise each async callback returns, so all iterations start at once and nothing waits. Use a for or for...of loop, as explained on the async/await page.

Retry with a Delay

A common real use: try an operation, and if it fails, wait and try again, doubling the wait each time (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();

The return await fn() inside try matters: without await, a rejected promise would be returned before the catch could see it.

A Cancellable sleep

A plain sleep cannot be interrupted. To stop waiting early (a user pressed Cancel, a shutdown started), pass an AbortSignal and clear the timer when it fires:

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

The program exits right after the abort because the long timer was cleared. Without clearTimeout, Node would keep running until the 5 seconds were up.

Node's Built-in Promise Timers

Node ships a promise version of setTimeout in the node:timers/promises module, so in Node code you can import it instead of writing the helper. It also accepts a value to resolve with and an 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
}

The types come from @types/node (npm i -D @types/node). This module does not exist in browsers, where the one-line helper is the portable choice.

There Is No Blocking sleep

Languages with threads have a sleep that blocks the current thread. JavaScript runs your code on a single thread with an event loop, so a blocking sleep would freeze everything else: no timers fire, no network responses are handled, and in a browser the page stops responding. A busy loop that spins until the clock passes a time does exactly that, and is never the right tool.

The async sleep is how waiting works in JavaScript and TypeScript: the function is suspended, the thread is free, and the function resumes when the timer fires. Atomics.wait can truly block, but only on a SharedArrayBuffer, and browsers forbid it on the main thread; it exists for coordinating worker threads, not for delays.