Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Streams and readline

Node.js stream.Readable class

Reference for stream.Readable in Node.js: creating readable streams, flowing and paused modes, events, push(), backpressure, async iteration and options.

A Readable stream is a source of data that you consume piece by piece instead of loading it all into memory. Files, HTTP requests on the server, child-process output, process.stdin and zlib decompressors are all readable streams. Each piece is a chunk: a Buffer or string by default, or any JavaScript value in object mode.

You can use a readable in three ways: attach a 'data' listener (flowing mode), call read() after a 'readable' event (paused mode), or loop with for await. The async loop is the simplest and handles backpressure and errors for you. To create your own, pass a read() function to the constructor and call this.push(chunk); push(null) ends the stream.

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

const source = new Readable({ read() {} });

Try it

Node.js A custom readable and for await

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 Flowing mode and events

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 Object mode and highWaterMark

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.Readable([options])
Option Description
read(size) Implementation called when the stream wants more data. Call this.push() inside it (or later, asynchronously).
highWaterMark Buffer size at which push() returns false. 65,536 bytes on Node.js 24 (it was 16 KiB before Node.js 22), 16 objects in object mode.
encoding Decode chunks to strings with this encoding, such as 'utf8'.
objectMode Allow any value as a chunk, and count the buffer in objects.
emitClose Emit 'close' after destroy. Default true.
autoDestroy Destroy the stream automatically after 'end' or an error. Default true.
destroy(err, cb) Custom cleanup called by destroy().
signal An AbortSignal that destroys the stream when aborted.

Key members: push(chunk) returns false when the buffer is full; read([size]), pipe(dest), pause(), resume(), setEncoding(), unshift(chunk), destroy([err]), [Symbol.asyncIterator](); properties readableFlowing, readableLength, readableEnded, readableObjectMode, destroyed; events data, end, error, close, readable, pause, resume. Iterator helpers (map, filter, take, toArray, forEach, ...) return or consume streams.

Errors: pushing after push(null) emits ERR_STREAM_PUSH_AFTER_EOF. A thrown error or destroy(err) emits 'error'; with no listener that is an uncaught exception.

Usage notes

  • Attaching a 'data' listener, calling resume() or pipe() switches to flowing mode. Attaching 'readable' switches to paused mode; the two styles should not be mixed.
  • A readable starts in a "null" flowing state and does nothing until you consume it. Data pushed before a consumer exists is buffered.
  • push() returning false is the producer's backpressure signal: stop pushing until read() is called again.
  • Always handle 'error'. In pipelines use stream.pipeline() instead of pipe(), so errors destroy every stream involved.
  • Chunks may split in the middle of a multi-byte character. Use setEncoding() or a StringDecoder, never chunk.toString() per chunk, for text.
  • Readable.from() is the easy way to wrap an iterable; Readable.toWeb() and Readable.fromWeb() convert to and from Web Streams.