wait-utils

A modern, zero-dependency wait and timing utility toolkit for JavaScript and TypeScript.

Supports AbortSignal, timeouts, retries, and polling — all with first-class TypeScript types.

Features

• 🕒 Accurate delays with timeout, wait and waitUntil
• 🔁 Flexible polling and retry logic with waitFor
• 🧪 100% test coverage — reliable and verified
• 🧩 Fully typed — TypeScript support with minimal generics
• 🧘 Zero dependencies — lean and tree-shakable for any runtime

Installation

NPM:

npm install wait-utils

Yarn:

yarn add wait-utils

JSR:

jsr add @rojas/wait-utils

API

timeout(delay?: number, signal?: AbortSignal): Promise<void>

Rejects with a TimeoutError after the specified delay, unless cancelled by an AbortSignal.

Parameters

Returns

A Promise<void> that:

• Resolves if the signal is aborted before the delay
• Rejects with a TimeoutError if the full delay completes
• Rethrows an unexpected error if one occurs

Example

import { timeout } from "wait-utils";

const controller = new AbortController();

try {
  await timeout(200, controller.signal);
  console.log("Aborted before timeout.");
} catch (error) {
  if (error.name === "TimeoutError") {
    console.error("Timed out!");
  } else {
    console.error("Unexpected error:", error);
  }
}

wait(delay, signal?)

Waits for a given number of milliseconds, unless cancelled by an AbortSignal.

Parameters

Returns

A Promise<void> that:

• Resolves after the delay
• Rejects with the AbortSignal.reason if cancelled before the delay

Example

import { wait } from "wait-utils";

await wait(1000); // waits 1 second

const controller = new AbortController();
wait(5000, controller.signal).catch((err) => {
  if (err.name === "AbortError") {
    console.log("Aborted!");
  }
});
controller.abort(); // cancels the wait

waitFor(callback | delay, options?)

Repeats a wait until a condition resolves or aborts

Parameters

Supported options are:

Returns

A Promise<void> that:

• Resolves once the delay is ≤ 0
• Rejects with the AbortSignal.reason if cancelled before the delay
• Rejects with a RetryError if onRetry returns false
• Rejects with a TimeoutError if the timeout is triggered before resolving

Examples

Fixed delay:

// Retry every 500ms, until the timeout
await waitFor(500, {
  timeout: 2000,
  onRetry(ms) {
    console.log(`Retrying in ${ms}ms...`);
  },
});

Dynamic delay:

import { waitFor } from "wait-utils";

// 80% wait for 100ms, 20% stop waiting
await waitFor(() => (Math.random() < 0.2 ? 0 : 100));

waitUntil(timestamp, signal?)

Waits until the given performance.now() timestamp is reached, unless canceled by an AbortSignal.

Parameters

Returns

A Promise<void> that:

• Resolves after the given timestamp is reached
• Rejects with the AbortSignal.reason if cancelled before the delay

Example

import { waitUntil } from "wait-utils";

const target = performance.now() + 2000;
await waitUntil(target); // waits until ~2s have passed

Errors

• AbortError
• TimeoutError
• RetryError

License

MIT © Michael Rojas

Sponsor

If you find this useful, consider sponsoring on GitHub.