Skip to content
Tutorials Center
My learning

Topics

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.

NODE
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

Node.js Cancelling a slow reader

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.

Node.js A timeout with AbortSignal.timeout

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

NODE
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 signal directly. pipeline(), fs.createReadStream(), events.once() and readline accept a signal option. Reach for addAbortSignal() 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 with AbortSignal.any() to combine a user cancel with a deadline.
  • Catch the error. An aborted stream with no error listener and no pipeline/finished() observer will throw an uncaught exception.
  • Added in Node.js 15.4.