{"id":16240,"library":"timed-out","title":"timed-out HTTP/HTTPS Request Timeout","description":"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.","status":"active","version":"7.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/sindresorhus/timed-out","tags":["javascript","http","https","timeout","get","url","uri","request","simple"],"install":[{"cmd":"npm install timed-out","lang":"bash","label":"npm"},{"cmd":"yarn add timed-out","lang":"bash","label":"yarn"},{"cmd":"pnpm add timed-out","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Pure ESM since v6.0.0. The package exports a default function.","wrong":"const timedOut = require('timed-out');","symbol":"timedOut","correct":"import timedOut from 'timed-out';"},{"note":"The primary export is a default function, not a named export. Destructuring `timedOut` will result in `undefined`.","wrong":"import { timedOut } from 'timed-out';","symbol":"timedOut","correct":"import timedOut from 'timed-out';"}],"quickstart":{"code":"import http from 'node:http';\nimport timedOut from 'timed-out';\n\n// Example 1: Basic timeout for a GET request\nconst request1 = http.get('http://www.google.com', (res) => {\n  console.log('Request 1 response status:', res.statusCode);\n  res.resume(); // Consume response data to prevent memory leaks\n});\ntimedOut(request1, 2000); // Sets a 2-second timeout\n\nrequest1.on('timeout', () => {\n  request1.destroy(new Error('Request 1 timed out after 2 seconds'));\n  console.error('Request 1 timed out!');\n});\n\nrequest1.on('error', (err) => {\n  if (err.code === 'ETIMEDOUT' || err.code === 'ESOCKETTIMEDOUT') {\n    console.error('Request 1 failed due to timeout:', err.message);\n  } else {\n    console.error('Request 1 encountered an error:', err.message);\n  }\n});\n\n// Example 2: Granular connect and socket timeouts for a different request\nconst request2 = http.get('http://www.example.com', (res) => {\n  console.log('Request 2 response status:', res.statusCode);\n  res.resume();\n});\ntimedOut(request2, { connect: 1000, socket: 3000 }); // Connect timeout 1s, socket activity timeout 3s\n\nrequest2.on('timeout', () => {\n  request2.destroy(new Error('Request 2 timed out'));\n  console.error('Request 2 timed out!');\n});\n\nrequest2.on('error', (err) => {\n  if (err.code === 'ETIMEDOUT' || err.code === 'ESOCKETTIMEDOUT') {\n    console.error('Request 2 failed due to timeout:', err.message);\n  } else {\n    console.error('Request 2 encountered an error:', err.message);\n  }\n});\n\n// In a real application, ensure all requests are explicitly handled or destroyed\n// to prevent lingering connections or memory leaks. For testing timeouts, \n// you might need to use a slow or non-existent endpoint.","lang":"javascript","description":"Demonstrates how to apply both simple and granular connect/socket timeouts to Node.js `http.ClientRequest` instances, including proper error and timeout event handling."},"warnings":[{"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.","message":"Version 7.0.0 requires Node.js 20 or later. Earlier Node.js versions are not supported.","severity":"breaking","affected_versions":">=7.0.0"},{"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`.","message":"Version 6.0.0 converted the package to pure ESM (ECMAScript Modules). It is no longer compatible with CommonJS `require()` syntax.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Ensure your Node.js environment is version 12 or newer. For older Node.js, use `timed-out@<6.0.0`.","message":"Version 6.0.0 requires Node.js 12 or later. Previous versions of Node.js are no longer supported.","severity":"breaking","affected_versions":">=6.0.0"},{"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`.","message":"Version 5.0.0 requires Node.js 8 or later. Running on earlier Node.js versions will cause issues.","severity":"breaking","affected_versions":">=5.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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`.","cause":"Attempting to import `timed-out` using `require()` in a CommonJS context after the package converted to pure ESM in v6.0.0.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/timed-out/index.js from ... not supported."},{"fix":"Ensure you are using the correct default import syntax for ES Modules: `import timedOut from 'timed-out';`.","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.","error":"TypeError: timedOut is not a function"},{"fix":"Ensure you are passing an actual `ClientRequest` instance, typically obtained from `http.get()`, `http.request()`, `https.get()`, or `https.request()`.","cause":"The first argument passed to the `timedOut` function is not a valid Node.js `http.ClientRequest` object, which is expected by the package.","error":"TypeError: The \"request\" argument must be an instance of ClientRequest. Received type <...>"},{"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.","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.","error":"Error: Request timed out after X milliseconds (or ETIMEDOUT / ESOCKETTIMEDOUT code)"}],"ecosystem":"npm"}