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).
const upper = new TransformStream({ transform(chunk, controller) { controller.enqueue(chunk.toUpperCase()); }, });
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
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 inflush(). - 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,TextEncoderStreamandTextDecoderStreameach expose the samereadableandwritablepair. - Node.js interop. Use
Duplex.fromWeb()orstream.Transformwhen 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.