Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Streams and readline

Node.js stream.Transform class

Reference for stream.Transform in Node.js: write transform() and flush(), push zero or many outputs per input, use object mode and handle errors in pipelines.

A Transform is a Duplex stream whose output is computed from its input: you write data in, it passes through your function, and the result comes out of the readable side. Compression, encryption, parsing, line splitting and format conversion are all transforms.

You implement transform(chunk, encoding, callback). For every chunk written, you may produce nothing, one output, or many outputs, by calling this.push() any number of times and then callback() once. An optional flush(callback) runs after the last chunk, which is where you emit whatever you buffered, such as a final incomplete line.

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

const upper = new Transform({
  transform(chunk, encoding, callback) {
    callback(null, chunk.toString().toUpperCase());
  },
});

Try it

Node.js Uppercase in a 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 Line splitter 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.

Node.js Dropping chunks and failing

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 stream.Transform([options])
transform(chunk, encoding, callback): void
flush(callback): void
Name Description
transform(chunk, encoding, cb) Required. Process one chunk. Call cb() exactly once. cb(err) fails the stream; cb(null, data) pushes data, same as this.push(data); cb().
flush(cb) Optional. Called after all input has been processed and before 'end'. Push remaining data, then call cb().
readableObjectMode, writableObjectMode, objectMode Object mode per side or for both.
highWaterMark and the other Duplex options Same as for Duplex.

Subclassing: define _transform() and _flush() methods instead of passing functions.

Errors: calling the callback more than once raises ERR_MULTIPLE_CALLBACK. Errors passed to the callback destroy the stream and emit 'error'; later input is discarded.

Usage notes

  • chunk is a Buffer by default, even when you wrote a string. Chunk boundaries are arbitrary, so never assume a chunk holds a whole line, record or character; buffer partial data and use flush().
  • In readableObjectMode the output side is object-counted while the input side stays byte-based, which is the usual setup for parsers (bytes in, objects out).
  • Backpressure is automatic: when the readable buffer is full, transform() is not called for more input until it is drained.
  • Do not call callback() before asynchronous work is complete, or order and error handling break.
  • For simple cases consider an async generator inside pipeline(), or the iterator helpers (readable.map(), filter()), which avoid the class.
  • Built-in transforms: zlib compressors, crypto ciphers and hashes, and stream.PassThrough (a transform that does nothing).