Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Streams and readline

The Node.js stream/promises module

Reference for node:stream/promises: promise versions of pipeline() and finished(), usage with async functions, abort signals and error handling.

node:stream/promises exports promise-returning versions of the two stream utilities that otherwise take callbacks: pipeline() and finished(). With them you can write streaming code as ordinary async functions, use try/catch for errors and await the moment a transfer is complete.

The promise forms behave exactly like the callback forms, with one convenience: pipeline() also accepts async generator functions and iterables as steps, and it resolves only when the destination has fully finished. The module has been stable for a long time, and stream.promises on the main node:stream module is the same object.

NODE
import { pipeline, finished } from 'node:stream/promises';

await pipeline(source, transformA, destination);
await finished(someStream);

Try it

Node.js pipeline() with a generator in the middle

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 Errors and cancellation with await

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
import { pipeline, finished } from 'node:stream/promises';

pipeline(...streams[, options]): Promise<void>
pipeline(streams[, options]): Promise<void>
finished(stream[, options]): Promise<void>
Name Description
streams Two or more steps: a source (a stream, iterable or async generator), zero or more transforms (streams or async functions), and a destination (a writable or an async function).
options.signal An AbortSignal that destroys every stream in the pipeline when aborted.
options.end For pipeline(): when false, the last destination is not ended automatically.
finished options error, readable, writable and signal, as for stream.finished().

Returns: a promise. pipeline() resolves with undefined, or with the return value of the last step when that step is an async function. finished() always resolves with undefined.

Errors: the promise rejects with the first error from any step, with AbortError when the signal fires, or with ERR_STREAM_PREMATURE_CLOSE if a stream is closed early. All streams in a pipeline are destroyed when it fails.

Usage notes

  • Prefer it over .pipe(). readable.pipe(writable) does not forward errors or clean up on failure, which leaks file descriptors. pipeline() does both.
  • The last step may be a function. An async function as the final step receives the async iterable of the previous output and its return value becomes the resolved value of the promise.
  • No second write after rejection. When the pipeline fails, the destination is destroyed, so partially written files may exist. Remove them in the catch block if needed.
  • Mix with fs. pipeline(createReadStream(a), createGzip(), createWriteStream(b)) is the canonical file-compression recipe.
  • Same object, two names. import { pipeline } from 'node:stream/promises' and stream.promises.pipeline are identical.
  • Await it. A forgotten await turns a failing pipeline into an unhandled rejection, which terminates the process by default.