timed-out

library7.0.0jsnpmunverified

The `timed-out` package provides a simple and effective mechanism for adding timeout functionality to Node.js `http.ClientRequest` objects, preventing requests from hanging indefinitely. It automatically emits an `Error` object with specific `code` properties (`ETIMEDOUT` or `ESOCKETTIMEDOUT`) when a request exceeds its defined time limit. The current stable version is `7.0.0`. The project maintains a steady release cadence, typically introducing new major versions to align with Node.js LTS releases and introduce breaking changes like pure ESM adoption. Its key differentiator lies in its focused approach: it specifically extends the native `ClientRequest` object, offering granular control over connection and socket activity timeouts, rather than being part of a larger HTTP client library. This makes it a lightweight solution for augmenting existing `http` and `https` module usage without introducing a full-fledged client.

http-networking

npm install timed-out

github ↗package ↗

INSTALL

IMPORT

SIG · TIMED-OUT

timed-out

http-networkingjavascriptv7.0.0

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.

timedOut

✓ import timedOut from 'timed-out';

✗ const timedOut = require('timed-out');

Pure ESM since v6.0.0. The package exports a default function.

timedOut

✓ import timedOut from 'timed-out';

✗ import { timedOut } from 'timed-out';

The primary export is a default function, not a named export. Destructuring `timedOut` will result in `undefined`.

Demonstrates how to apply both simple and granular connect/socket timeouts to Node.js `http.ClientRequest` instances, including proper error and timeout event handling.

import http from 'node:http'; import timedOut from 'timed-out'; // Example 1: Basic timeout for a GET request const request1 = http.get('http://www.google.com', (res) => { console.log('Request 1 response status:', res.statusCode); res.resume(); // Consume response data to prevent memory leaks }); timedOut(request1, 2000); // Sets a 2-second timeout request1.on('timeout', () => { request1.destroy(new Error('Request 1 timed out after 2 seconds')); console.error('Request 1 timed out!'); }); request1.on('error', (err) => { if (err.code === 'ETIMEDOUT' || err.code === 'ESOCKETTIMEDOUT') { console.error('Request 1 failed due to timeout:', err.message); } else { console.error('Request 1 encountered an error:', err.message); } }); // Example 2: Granular connect and socket timeouts for a different request const request2 = http.get('http://www.example.com', (res) => { console.log('Request 2 response status:', res.statusCode); res.resume(); }); timedOut(request2, { connect: 1000, socket: 3000 }); // Connect timeout 1s, socket activity timeout 3s request2.on('timeout', () => { request2.destroy(new Error('Request 2 timed out')); console.error('Request 2 timed out!'); }); request2.on('error', (err) => { if (err.code === 'ETIMEDOUT' || err.code === 'ESOCKETTIMEDOUT') { console.error('Request 2 failed due to timeout:', err.message); } else { console.error('Request 2 encountered an error:', err.message); } }); // In a real application, ensure all requests are explicitly handled or destroyed // to prevent lingering connections or memory leaks. For testing timeouts, // you might need to use a slow or non-existent endpoint.

Debug

Known issues

breakingVersion 7.0.0 requires Node.js 20 or later. Earlier Node.js versions are not supported.

fix

Upgrade your Node.js environment to version 20 or higher. Alternatively, use an older version of `timed-out` if you must remain on an earlier Node.js release.

affects: >=7.0.0

breakingVersion 6.0.0 converted the package to pure ESM (ECMAScript Modules). It is no longer compatible with CommonJS `require()` syntax.

fix

Migrate your project to use ES Modules by setting `"type": "module"` in your `package.json` and using `import` statements. If you require CommonJS, you must use `timed-out@<6.0.0`.

affects: >=6.0.0

breakingVersion 6.0.0 requires Node.js 12 or later. Previous versions of Node.js are no longer supported.

fix

Ensure your Node.js environment is version 12 or newer. For older Node.js, use `timed-out@<6.0.0`.

affects: >=6.0.0

breakingVersion 5.0.0 requires Node.js 8 or later. Running on earlier Node.js versions will cause issues.

fix

Update your Node.js environment to version 8 or higher. If backwards compatibility with Node.js <8 is critical, use `timed-out@<5.0.0`.

affects: >=5.0.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/timed-out/index.js from ... not supported.

Attempting to import `timed-out` using `require()` in a CommonJS context after the package converted to pure ESM in v6.0.0.

fix

Convert your project or file to ES Modules by adding `"type": "module"` to your `package.json` or by using `.mjs` file extensions, and then use `import timedOut from 'timed-out';`. If CommonJS is unavoidable, use `timed-out@<6.0.0`.

TypeError: timedOut is not a function

This error typically occurs when attempting to import a default export as a named export (e.g., `import { timedOut } from 'timed-out';`) or when the import is incorrect after the ESM transition.

fix

Ensure you are using the correct default import syntax for ES Modules: `import timedOut from 'timed-out';`.

TypeError: The "request" argument must be an instance of ClientRequest. Received type <...>

The first argument passed to the `timedOut` function is not a valid Node.js `http.ClientRequest` object, which is expected by the package.

fix

Ensure you are passing an actual `ClientRequest` instance, typically obtained from `http.get()`, `http.request()`, `https.get()`, or `https.request()`.

Error: Request timed out after X milliseconds (or ETIMEDOUT / ESOCKETTIMEDOUT code)

The HTTP/HTTPS request exceeded the specified `time` limit, either during connection (`connect` timeout) or while waiting for activity on the socket (`socket` timeout). This is often an expected runtime condition rather than a code error.

fix

Implement robust error handling for `ETIMEDOUT` or `ESOCKETTIMEDOUT` error codes. Consider increasing the timeout duration if the network or server is genuinely slow, or implement retry logic and user notifications.

Upgrade

Version history

7.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

12 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/sindresorhus/timed-out ↗

packagehttps://www.npmjs.com/package/timed-out ↗