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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AbortController
✓ import { AbortController } from 'node-abort-controller';
✗ const AbortController = require('node-abort-controller');
Since v3, `AbortController` must be a named import for both ESM and CJS. Default exports were removed.
AbortSignal
✓ import { AbortController, AbortSignal } from 'node-abort-controller';
✗ import AbortSignal from 'node-abort-controller';
While `AbortSignal` is exposed, it's typically accessed via `controller.signal`. Explicitly importing `AbortSignal` is less common but possible.
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.
import fetch from 'node-fetch';
import { AbortController } from 'node-abort-controller';
const main = async () => {
const controller = new AbortController();
const signal = controller.signal;
// Abort fetch after 500ms. Effectively a timeout
const timeoutId = setTimeout(() => {
console.log('Request timed out, aborting...');
controller.abort();
}, 500);
try {
console.log('Fetching from Google...');
const response = await fetch('https://www.google.com', { signal });
clearTimeout(timeoutId);
if (response.ok) {
console.log(`Successfully fetched Google (Status: ${response.status})`);
// const text = await response.text();
// console.log(text.substring(0, 100) + '...');
} else {
console.error(`Failed to fetch Google (Status: ${response.status})`);
}
} catch (error) {
if (error.name === 'AbortError') {
console.warn('Fetch request was aborted.');
} else {
console.error('Fetch error:', error.message);
}
}
};
main();
Debug
Known issues
breakingVersion 3.x removed default exports. `AbortController` and `AbortSignal` must now be imported as named exports for both ES Modules and CommonJS.fixChange `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');` affects: >=3.0.0
gotchaThis 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.fixFor 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.
affects: >=14.7.0 (Node.js)
gotchaThis 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.fixIf targeting browsers, use `abort-controller` or `cross-fetch`. If targeting modern browsers only, no polyfill is needed.
affects: *
gotchaWhen 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.fixAlways wrap operations that accept an `AbortSignal` in a `try...catch` block and check `if (error.name === 'AbortError')` to handle cancellations gracefully.
affects: *
Errors
Common errors & fixes
TypeError: AbortController is not a constructor
Attempting to use `require('node-abort-controller')` as a direct constructor call (default import style) after upgrading to v3+, or importing it incorrectly.
fixEnsure you are using named imports: `const { AbortController } = require('node-abort-controller');` for CommonJS or `import { AbortController } from 'node-abort-controller';` for ESM. 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' } }
Installing `node-abort-controller` in a Node.js environment version 14.7.0 or higher. This package explicitly targets older Node.js versions.
fixIf 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.
FetchError: The user aborted a request.
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.
fixWrap 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.
Audit
Dependencies
node-fetchoptionalCommonly used with this polyfill for cancellable HTTP requests in Node.js.