Node.js Reference ยท Streams and readline
Node.js stream.addAbortSignal() function
Reference for stream.addAbortSignal() in Node.js: attach an AbortSignal to a stream so aborting destroys it with an AbortError, plus timeouts and cleanup.
stream.addAbortSignal(signal, stream) connects an AbortSignal to a Node.js stream. When the signal aborts, the stream is destroyed with an AbortError, and every consumer that is waiting on it (a pipeline, a for await loop, a finished() call) sees that error.
It gives you one uniform way to cancel streaming work: a user clicks "cancel", a request times out, or a parent task is cancelled. The function returns the same stream, so you can wrap a stream at the point where you create it.
import { addAbortSignal } from 'node:stream'; const ac = new AbortController(); const source = addAbortSignal(ac.signal, createSomeReadable()); ac.abort(); // source is destroyed with an AbortError
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
stream.addAbortSignal(signal: AbortSignal, stream: Readable | Writable | Duplex): stream
| Name | Description |
|---|---|
signal |
The AbortSignal to watch. It must really be an AbortSignal, otherwise ERR_INVALID_ARG_TYPE is thrown. |
stream |
A Node.js Readable, Writable, Duplex or Transform. Web streams are not accepted. |
Returns: the same stream, now linked to the signal.
Errors: aborting destroys the stream with an AbortError (err.name === 'AbortError', err.code === 'ABORT_ERR'). If the signal carried a reason, it is available as err.cause. If the signal is already aborted when you call the function, the stream is destroyed immediately.
Usage notes
- It destroys, it does not end. An aborted stream is destroyed, so data still buffered may be lost. This is cancellation, not a graceful close.
- No work is rolled back. Writes that already reached a file or socket stay there. Design the consumer to tolerate partial output.
- Many APIs take
signaldirectly.pipeline(),fs.createReadStream(),events.once()andreadlineaccept asignaloption. Reach foraddAbortSignal()when you build the stream yourself. - Listeners are removed when the stream ends. The abort listener is attached to the signal and cleaned up when the stream closes, so a long-lived signal does not keep finished streams alive.
- Pair it with
AbortSignal.timeout()for per-operation deadlines, and withAbortSignal.any()to combine a user cancel with a deadline. - Catch the error. An aborted stream with no
errorlistener and no pipeline/finished()observer will throw an uncaught exception. - Added in Node.js 15.4.