Registry / http-networking / await-timeout

await-timeout

library1.1.1jsnpmunverified

await-timeout, currently at version 1.1.1, offers a Promise-based API for handling `setTimeout` and `clearTimeout` in JavaScript, making it particularly useful within `async/await` constructs. It simplifies common asynchronous patterns such as adding timeouts to network requests or other long-running operations. The library provides both static methods like `Timeout.set(ms)` for simple delays and instance methods (`new Timeout().set(ms)`) for more controlled scenarios, including wrapping existing promises with timeouts using `Timeout.wrap(promise, ms, rejectReason)`. A key differentiator is its emphasis on proper resource management, advising the use of `.clear()` within `finally` blocks to prevent unhandled promise rejections or 'unexpected effects' when dealing with `Promise.race`. While a specific release cadence isn't detailed, its stable 1.x version implies a mature and focused utility for precise timeout management in asynchronous codebases.

http-networking web-framework

npm install await-timeout

github ↗package ↗

INSTALL

IMPORT

SIG · AWAIT-TIMEOUT

await-timeout

http-networkingjavascriptv1.1.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Timeout

✓ import Timeout from 'await-timeout';

✗ const Timeout = require('await-timeout');

While CommonJS `require` works, ESM `import` is the idiomatic way for modern Node.js and bundlers.

Timeout.set (static)

✓ await Timeout.set(1000);

✗ await new Timeout().set(1000);

For simple delays without the need for manual clearing, the static `set` method is more concise. Using an instance is only necessary if you intend to manually clear the timer.

Timeout (instance)

✓ const timer = new Timeout();

✗ const timer = Timeout();

The `Timeout` class must be instantiated with `new` to create a new timer object for instance methods like `.set()` and `.clear()`.

Demonstrates using `await-timeout` to add a timeout to a fetch request with `Promise.race` and proper cleanup, alongside a simple static delay.

import Timeout from 'await-timeout'; async function fetchWithTimeoutExample() { const timer = new Timeout(); try { console.log('Attempting to fetch data with a 1-second timeout...'); const dataPromise = fetch('https://jsonplaceholder.typicode.com/todos/1').then(res => res.json()); const result = await Promise.race([ dataPromise, timer.set(1000, new Error('Fetch operation timed out!')) // Rejects after 1 second ]); if (result instanceof Error) { throw result; // Propagate the timeout error } console.log('Data fetched successfully:', result.title); } catch (error) { console.error('Operation failed:', error.message); } finally { timer.clear(); // Essential cleanup to prevent resource leaks and 'unexpected effects' console.log('Timeout timer cleared.'); } } async function simpleDelayExample() { console.log('\nStarting a 500ms delay...'); await Timeout.set(500); // Static method for a simple awaitable delay console.log('Delay finished after 500ms.'); } fetchWithTimeoutExample(); simpleDelayExample();

Debug

Known issues

gotchaWhen using `Timeout` instances, especially with `Promise.race`, it is crucial to always call `.clear()` in a `finally` block. Failing to do so can lead to 'unexpected effects' or unhandled promise rejections, as the internal `setTimeout` might still fire even if the race condition is met by another promise.

fix

Ensure `timer.clear()` is called within a `try...finally` block after `Promise.race` or any operation involving an instance-based timer.

affects: >=1.0.0

gotchaIf `Timeout.set(delay, rejectReason)` is used to create a rejecting promise and that promise is not caught or handled, it will result in an 'Unhandled Promise Rejection' error in Node.js or the browser console.

fix

Always chain a `.catch()` to the promise returned by `timer.set(delay, rejectReason)` or wrap the `await` call in a `try...catch` block if the promise is configured to reject.

affects: >=1.0.0

gotchaThe `Timeout.wrap(promise, delay, rejectReason)` static method is a convenient shortcut, but it internally creates and manages a `Timeout` instance. While it handles clearing the timer automatically, developers should understand its behavior to avoid misuse or misinterpreting its interactions in complex promise chains.

fix

Familiarize yourself with the internal implementation of `wrap` (as shown in the README) to understand how it uses `Promise.race` and `timer.clear()` to ensure proper behavior.

affects: >=1.0.0

Errors

Common errors & fixes

UnhandledPromiseRejectionWarning: Unhandled promise rejection (rejection id: X): Error: Timeout!

A `Timeout.set(ms, 'Timeout!')` promise was rejected, but there was no `.catch()` handler or surrounding `try...catch` block to manage it.

fix

Add a `.catch()` block to the promise returned by `Timeout.set()` or wrap the `await Timeout.set()` call in a `try...catch` statement to handle the rejection.

TypeError: Timeout is not a constructor

Attempting to call `Timeout()` directly without the `new` keyword, or incorrect import of the default export.

fix

Use `const timer = new Timeout();` to create an instance, ensuring `Timeout` is correctly imported as a class: `import Timeout from 'await-timeout';`.

Upgrade

Version history

1.1.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

18 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/vitalets/await-timeout ↗

packagehttps://www.npmjs.com/package/await-timeout ↗