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.
import { Readable } from 'node:stream'; const source = new Readable({ read() {} });
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.
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 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, callingresume()orpipe()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()returningfalseis the producer's backpressure signal: stop pushing untilread()is called again.- Always handle
'error'. In pipelines usestream.pipeline()instead ofpipe(), so errors destroy every stream involved. - Chunks may split in the middle of a multi-byte character. Use
setEncoding()or aStringDecoder, neverchunk.toString()per chunk, for text. Readable.from()is the easy way to wrap an iterable;Readable.toWeb()andReadable.fromWeb()convert to and from Web Streams.