Timeout-driven cancellation
Cancel a fetch or other supported asynchronous operation when a deadline expires.
Node.js · Class
AbortController
AbortController signals cancellation to selected Promise-based APIs. Pass its signal to an operation and call abort() to trigger cancellation notification.
- Since
- v15.4.0
How it works
AbortController coordinates cancellation for supported Promise-based APIs. Create one, give its signal to an operation, and call abort() to emit the abort event; an optional reason becomes available through the signal.
Syntax
new AbortController();
abortController.abort([reason])Parameters
| Name | Type | Description |
|---|---|---|
reason | any | Optional value recorded as the signal's reason and retrievable from AbortSignal.reason. |
Returns
abort(reason) returns undefined; the controller exposes its associated AbortSignal through the signal property.
Key points
- It provides a standard cancellation signal for supported Promise-based Node.js APIs.
- Its design follows the Web API AbortController model, making the same cancellation pattern familiar across environments.
- Calling abort() notifies consumers by causing the controller's signal to emit an abort event.
- Consumers observe the signal rather than polling the controller, allowing cancellation-aware operations to react.
- Abort event callbacks receive one event object whose type property is set to 'abort'.
Common mistakes
- Aborting is one-way: the associated signal emits its abort event only once, so a controller cannot be reused for a later operation.
- If a reason matters to callers, provide it to abort(reason) and read it from the signal's reason property.
Example: Cancel a fetch request
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(new Error('Timed out')), 100);
try {
await fetch('https://nodejs.org', { signal: controller.signal });
console.log('Request completed');
} catch (error) {
if (controller.signal.aborted) console.log('Request cancelled');
else throw error;
} finally {
clearTimeout(timeout);
}Creates a controller, passes its signal to fetch, and aborts the request after 100 milliseconds.
When to use it
External cancellation
Let a user, request handler, or shutdown routine stop an in-flight operation.
Reason-aware cancellation
Propagate a cancellation reason to code observing the operation.
Interview questions
QWhat is AbortController used for?
AbortController is a utility class for signaling cancellation to selected Promise-based APIs. Pass its signal to the API, then call abort() when cancellation is needed.
Follow-up: What does abort() do to the signal? It causes the controller's signal to emit the abort event and marks the signal as aborted.
QWhat does abort(reason) do?
Calling abort(reason) triggers the controller's signal and optionally records the supplied value as the signal's reason. The reason can be any value.
Follow-up: Can the same controller be reset? No; its associated signal can trigger the abort event only once, so create a new controller for another operation.
QWhat is the role of AbortSignal?
The signal is the object observers and supported APIs use to learn that cancellation was requested. It emits an 'abort' event when its controller's abort() method is called.
Follow-up: How should an event listener be registered when it only needs to run once? Use an event listener option with once: true, as shown in the documentation example.
Related
AbortSignalAbortSignal.abort()AbortSignal.timeout()