timed-out HTTP/HTTPS Request Timeout

Common errors

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

  cause 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

  cause 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 <...>

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

  cause 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.

Warnings

• breaking Version 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.
• breaking Version 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`.
• breaking Version 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`.
• breaking Version 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`.

Install

• npm install timed-out npm
• yarn add timed-out yarn
• pnpm add timed-out pnpm

Imports

• timedOut
  wrong:

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

  correct:

  import timedOut from 'timed-out';

  Pure ESM since v6.0.0. The package exports a default function.
• timedOut
  wrong:

  import { timedOut } from 'timed-out';

  correct:

  import timedOut from 'timed-out';

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

Quickstart

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.