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.
import { pipeline, finished } from 'node:stream/promises'; await pipeline(source, transformA, destination); await finished(someStream);
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
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
catchblock 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'andstream.promises.pipelineare identical. - Await it. A forgotten
awaitturns a failing pipeline into an unhandled rejection, which terminates the process by default.