Node.js Reference ยท Streams and readline
Node.js stream.pipeline() function
Reference for stream.pipeline() in Node.js: connect streams, async generators and iterables, get one error and one callback, and clean up every stream.
stream.pipeline(...streams, callback) connects several streams in order, forwards data with backpressure, and destroys all of them if any one fails or is closed early. The callback runs exactly once, with an error or without. That fixes the main weakness of pipe(), where an error in one stream leaves the others open.
A promise version lives in node:stream/promises, and you can put async generator functions, async iterables or plain iterables into the chain.
import { pipeline } from "node:stream/promises"; await pipeline(source, transform, destination);
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
pipeline(source, ...transforms, destination, callback): stream pipeline(streams, callback) await pipeline(source, ...transforms, destination[, options]) // node:stream/promises
| Name | Description |
|---|---|
source |
A readable stream, an iterable, an async iterable, or a function returning one. |
transforms |
Zero or more duplex/transform streams, or async functions that take a source iterable and return an async iterable. |
destination |
A writable stream, or an async function that consumes the source and may return a value. |
callback(err) |
Called once at the end (callback form). If the last stage returns a value, it is the second argument. |
options.signal |
Promise form only: an AbortSignal that aborts the pipeline with AbortError. |
options.end |
Promise form only: set false to keep the final destination open after the source ends. |
Returns: the last stream (callback form), or a promise (promises form), resolved once the destination has finished.
Errors: the first error from any stream is reported. Streams that closed before finishing without an error cause ERR_STREAM_PREMATURE_CLOSE.
Usage notes
- All streams are destroyed on failure, except the final
process.stdoutandprocess.stderr, which are never closed. - Prefer the promises version with
async/await; the callback version is the same function without promises. - A function in the middle receives the previous stage as an async iterable and should
yieldoutput. A function at the end consumes the iterable. - Intermediate stages must be duplex-like; passing a plain readable in the middle is an error.
- Event listeners you add yourself, such as
'error'handlers, stay attached. Catching the error on the stream does not stop pipeline from seeing it. - Use
compose()to build one reusable duplex from several stages without running them. - Compared with
pipe(): pipeline handles errors, forwards cleanup and reports completion.pipe()only moves data.