Skip to content
Tutorials Center
My learning

Topics

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.

NODE
import { pipeline } from "node:stream/promises";
await pipeline(source, transform, destination);

Try it

Node.js Pipeline with generators

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 Failure destroys every stream

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
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.stdout and process.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 yield output. 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.