Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Streams and readline

Node.js TransformStream (web streams)

Reference for the global TransformStream in Node.js: build a transformer with transform and flush, use it with pipeThrough, and handle errors and backpressure.

TransformStream pairs a WritableStream and a ReadableStream: whatever you write into its writable side is run through a transformer function and comes out of its readable side. It is the web streams counterpart of Node.js Transform, and the building block behind CompressionStream and TextDecoderStream.

You rarely use the two sides directly. Instead you call readable.pipeThrough(transformStream), which pipes the source into the writable half and returns the readable half, so steps chain like a.pipeThrough(b).pipeThrough(c).

NODE
const upper = new TransformStream({
  transform(chunk, controller) {
    controller.enqueue(chunk.toUpperCase());
  },
});

Try it

Node.js Upper-casing a stream with pipeThrough

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 Splitting lines with flush

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
new TransformStream(transformer?, writableStrategy?, readableStrategy?)
transformStream.readable   // ReadableStream
transformStream.writable   // WritableStream
Name Description
transformer.start(controller) Runs once when the stream is created.
transformer.transform(chunk, controller) Called per written chunk. Call controller.enqueue() zero or more times. May return a promise.
transformer.flush(controller) Called after the writable side closes, before the readable side closes. Emit leftover data here.
writableStrategy, readableStrategy Queuing strategies ({ highWaterMark, size }) for each side. Defaults: 1 and 0 chunks.
controller enqueue(chunk), error(reason), terminate() and desiredSize.

Returns: an object with the two linked streams. Without a transform function the stream is an identity transform that forwards chunks unchanged.

Errors: an exception or rejection in transform() or flush() errors both sides, so pending reads and writes reject with that error. controller.terminate() closes the readable side and errors the writable side.

Usage notes

  • Chunk boundaries are arbitrary. A network or file source can split a record anywhere. Buffer incomplete data across transform() calls and emit it in flush().
  • Backpressure works across the pair. transform() is not called again until the readable side has room, because the default readable high-water mark is 0.
  • Emit as many chunks as you like. One input can produce none (filtering), one (mapping) or many (splitting).
  • Many built-ins are transform streams. CompressionStream, DecompressionStream, TextEncoderStream and TextDecoderStream each expose the same readable and writable pair.
  • Node.js interop. Use Duplex.fromWeb() or stream.Transform when mixing with older code.
  • Class-based transformers. An object with the three methods works as well as an object literal, which helps when you need state or this.