Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Streams and readline

Node.js stream.compose() function

Reference for stream.compose() in Node.js: combine streams, async generators and functions into a single duplex stream that can be reused or piped.

stream.compose(...streams) glues several streams, async generator functions or web streams together and returns one Duplex. Data written to the composed stream flows through every step in order, and what the last step produces can be read from it. The result behaves like a single Transform, so you can store it, reuse it or pipe other streams into it.

It does the same plumbing as stream.pipeline(), but instead of running immediately between a source and a destination, it gives you a reusable middle piece. Errors in any step destroy the whole composed stream.

NODE
import { compose } from 'node:stream';

const cleanAndShout = compose(
  async function* (source) { for await (const s of source) yield String(s).trim(); },
  async function* (source) { for await (const s of source) yield s.toUpperCase(); },
);

Try it

Node.js A reusable text pipeline

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 Mixing a Transform and a generator

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.compose(...streams): stream.Duplex
Name Description
...streams Two or more of: a Node.js stream, a web ReadableStream/WritableStream/TransformStream, or a function. A function receives an async iterable of the previous step's output and returns an async iterable (typically an async generator), or a promise for the final step.

Returns: a Duplex. Writes go into the first step, reads come from the last. If the first step is a Readable (not writable) the result is readable only, and if the last step is a Writable the result is writable only.

Errors: an error in any stream, or a thrown exception in a function, destroys every step and is emitted on the composed stream. Passing fewer than one stream throws ERR_MISSING_ARGS.

Usage notes

  • A function step is an iterator transform. Whatever you yield becomes the next step's input, so you can map, filter or split without writing a Transform class.
  • Object mode follows the steps. A generator can yield strings or objects, and the composed stream becomes readable in object mode if the last step produces non-byte values. Buffers and strings from generators are converted as needed.
  • Compose is lazy. Nothing is read until someone consumes the result, for instance by piping, iterating with for await or calling toArray().
  • Use pipeline for one-shot jobs. When you have a fixed source and destination, pipeline() gives you a promise to await. Use compose() when you need a stream object to hand to other code.
  • Cleanup is automatic. Destroying the composed stream destroys all of its parts, which is the main advantage over chaining .pipe() calls by hand.
  • Stability. stream.compose() is marked experimental in some Node.js releases. Check the stability index before relying on edge cases such as web stream steps.
  • Added in Node.js 16.9.