{"id":15145,"library":"node-abort-controller","title":"Node AbortController Polyfill","description":"node-abort-controller provides a minimal polyfill for the AbortController and AbortSignal Web APIs, specifically designed for Node.js environments running versions 14.6.x and below. It leverages Node.js's EventEmitter for its implementation. This package is explicitly *not* needed for Node.js versions 14.7.0 and above, as `AbortController` and `AbortSignal` are built-in globals in modern Node.js environments, becoming stable in v15.4.0. The library's current stable version is 3.1.1, and its release cadence is tied to the evolving Node.js core, with updates typically occurring when there are breaking changes or new Node.js versions make the polyfill redundant. Its key differentiator is its lightweight, Node.js-specific approach, aiming to avoid shipping unnecessary polyfills to environments that don't require them, making it ideal for library authors targeting mixed Node.js and modern browser environments where `node-fetch` is also used.","status":"maintenance","version":"3.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/southpolesteve/node-abort-controller","tags":["javascript","AbortController","AbortSignal","fetch","polyfill"],"install":[{"cmd":"npm install node-abort-controller","lang":"bash","label":"npm"},{"cmd":"yarn add node-abort-controller","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-abort-controller","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Commonly used with this polyfill for cancellable HTTP requests in Node.js.","package":"node-fetch","optional":true}],"imports":[{"note":"Since v3, `AbortController` must be a named import for both ESM and CJS. Default exports were removed.","wrong":"const AbortController = require('node-abort-controller');","symbol":"AbortController","correct":"import { AbortController } from 'node-abort-controller';"},{"note":"While `AbortSignal` is exposed, it's typically accessed via `controller.signal`. Explicitly importing `AbortSignal` is less common but possible.","wrong":"import AbortSignal from 'node-abort-controller';","symbol":"AbortSignal","correct":"import { AbortController, AbortSignal } from 'node-abort-controller';"}],"quickstart":{"code":"import fetch from 'node-fetch';\nimport { AbortController } from 'node-abort-controller';\n\nconst main = async () => {\n  const controller = new AbortController();\n  const signal = controller.signal;\n\n  // Abort fetch after 500ms. Effectively a timeout\n  const timeoutId = setTimeout(() => {\n    console.log('Request timed out, aborting...');\n    controller.abort();\n  }, 500);\n\n  try {\n    console.log('Fetching from Google...');\n    const response = await fetch('https://www.google.com', { signal });\n    clearTimeout(timeoutId);\n    if (response.ok) {\n      console.log(`Successfully fetched Google (Status: ${response.status})`);\n      // const text = await response.text();\n      // console.log(text.substring(0, 100) + '...');\n    } else {\n      console.error(`Failed to fetch Google (Status: ${response.status})`);\n    }\n  } catch (error) {\n    if (error.name === 'AbortError') {\n      console.warn('Fetch request was aborted.');\n    } else {\n      console.error('Fetch error:', error.message);\n    }\n  }\n};\n\nmain();","lang":"javascript","description":"This example demonstrates how to use AbortController with `node-fetch` to implement a timeout for an HTTP request, showing how to create a controller, pass its signal, and handle the abort event."},"warnings":[{"fix":"Change `import AbortController from 'node-abort-controller';` to `import { AbortController } from 'node-abort-controller';` or `const AbortController = require('node-abort-controller');` to `const { AbortController } = require('node-abort-controller');`","message":"Version 3.x removed default exports. `AbortController` and `AbortSignal` must now be imported as named exports for both ES Modules and CommonJS.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"For Node.js versions 14.7.0 and above, remove this package and use the native `AbortController` from the global scope. For Node.js >=14.7.0 and <15.4.0, it might require the `--experimental-abortcontroller` flag.","message":"This package is a polyfill for Node.js versions *below* 14.7.0. For Node.js 14.7.0 and above, `AbortController` and `AbortSignal` are built-in globals. In Node.js >=15.4.0, they are stable. Using this package in newer Node.js versions is unnecessary and may lead to unexpected behavior or larger bundle sizes.","severity":"gotcha","affected_versions":">=14.7.0 (Node.js)"},{"fix":"If targeting browsers, use `abort-controller` or `cross-fetch`. If targeting modern browsers only, no polyfill is needed.","message":"This package is specifically designed for Node.js environments and should NOT be used for browser-side polyfilling. For browser applications, especially those supporting legacy browsers, use packages like `abort-controller` or `whatwg-fetch` which provide more comprehensive polyfills.","severity":"gotcha","affected_versions":"*"},{"fix":"Always wrap operations that accept an `AbortSignal` in a `try...catch` block and check `if (error.name === 'AbortError')` to handle cancellations gracefully.","message":"When an `AbortSignal` is triggered, the associated asynchronous operation (e.g., a `fetch` request) will throw an `AbortError`. It is crucial to catch this specific error to prevent application crashes and differentiate between a graceful cancellation and other network or operational failures.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure you are using named imports: `const { AbortController } = require('node-abort-controller');` for CommonJS or `import { AbortController } from 'node-abort-controller';` for ESM.","cause":"Attempting to use `require('node-abort-controller')` as a direct constructor call (default import style) after upgrading to v3+, or importing it incorrectly.","error":"TypeError: AbortController is not a constructor"},{"fix":"If your Node.js version is 14.7.0 or newer, you do not need this package. Remove it and use the native `AbortController` global provided by Node.js.","cause":"Installing `node-abort-controller` in a Node.js environment version 14.7.0 or higher. This package explicitly targets older Node.js versions.","error":"npm WARN EBADENGINE Unsupported engine { package: 'node-abort-controller@3.1.0', required: { node: '<14.7.0' }, current: { node: 'vX.Y.Z', npm: 'A.B.C' } }"},{"fix":"Wrap the `fetch` call in a `try...catch` block. In the `catch` block, specifically check for `error.name === 'AbortError'` to differentiate a user-initiated or programmatic abort from other types of errors.","cause":"An `AbortController`'s signal was passed to a `fetch` request, and `controller.abort()` was called, leading to a programmatic cancellation. This is often an expected behavior but can be surprising if not explicitly handled.","error":"FetchError: The user aborted a request."}],"ecosystem":"npm"}