Cooperative cancellation
Pass a signal to a promise-based API so a controller can cancel the operation.
Node.js · Class
AbortSignal
AbortSignal is an EventTarget-based cancellation signal for selected promise APIs. It can be created in an aborted, timed, or composed form and exposes cancellation state and reason.
- Since
- v15.0.0
How it works
AbortSignal is an EventTarget-based cancellation signal used by selected promise APIs. An AbortController triggers it, while static factories can create an already-aborted signal, a timed signal, or a signal composed from several signals.
Syntax
class AbortSignal extends EventTarget
AbortSignal.abort([reason])
AbortSignal.timeout(delay)
AbortSignal.any(signals)Parameters
| Name | Type | Description |
|---|---|---|
reason | any | Optional value attached to a signal created by AbortSignal.abort(). |
delay | number | Milliseconds before the returned signal aborts. |
signals | AbortSignal[] | Signals used to compose a signal that follows the first one to abort. |
Returns
AbortSignal instances from the static factory methods; the class exposes aborted, onabort, and reason properties.
Key points
- A controller's abort operation notifies consumers through its associated signal.
- AbortSignal.abort() is useful when an API should receive immediate cancellation.
- AbortSignal.timeout(delay) expresses cancellation as a millisecond deadline.
- AbortSignal.any(signals) models alternative cancellation sources.
- The aborted property indicates whether cancellation has already occurred.
- The reason property carries the value associated with cancellation.
Common mistakes
- Treat abort as a one-time transition; it cannot be reset for reuse.
- Use a one-shot listener to avoid retaining an unnecessary abort handler.
- With any(), the winning signal determines the composed signal's reason.
Example: Combine cancellation and timeout
const controller = new AbortController();
const signal = AbortSignal.any([
controller.signal,
AbortSignal.timeout(1000),
]);
signal.addEventListener('abort', () => {
console.log('aborted:', signal.reason);
}, { once: true });
setTimeout(() => controller.abort(new Error('cancelled')), 100);Combines caller cancellation with a one-second deadline and reports the reason when the resulting signal aborts.
When to use it
Timeout enforcement
Create a deadline that automatically cancels work after a fixed duration.
Multiple cancellation sources
Combine user cancellation with a timeout or another cancellation source.
Interview questions
QWhat is AbortSignal used for?
AbortSignal represents cancellation state and dispatches an abort event when its associated controller is aborted. APIs that accept a signal can observe that event or inspect aborted and reason.
Follow-up: How can a deadline be added without manually managing a timer? Use AbortSignal.timeout(delay), which returns a signal aborted after the specified number of milliseconds.
QHow do the static factory methods differ?
AbortSignal.abort(reason) creates a signal that is already aborted, optionally carrying reason. AbortSignal.timeout(delay) creates one that aborts after delay milliseconds.
Follow-up: What if cancellation may come from either a caller or a deadline? Compose both with AbortSignal.any([callerSignal, timeoutSignal]).
QWhat does AbortSignal.any() do?
AbortSignal.any(signals) returns a signal that aborts when any supplied signal aborts. Its reason is taken from the signal that caused the composition to abort.
Follow-up: How should consumers handle the composed signal's reason? Inspect signal.reason after abort and account for whichever cancellation source won.
Related
AbortControllerEventTargetAbortSignal.abort()AbortSignal.timeout()AbortSignal.any()