skip to content

Classes and Reading Modes

The four stream classes and the two ways a Readable hands you data: push or pull. Asked because a stream resumed with no 'data' listener attached drops chunks before a consumer is ready.

on this pageshow

explore

questions

6

In Node.js's node:stream module, what are the four fundamental stream classes, and how does a Transform differ from a plain Duplex?

level: juniorimportance: must knowfreq 70%

answer

  1. source, destination, or both
  2. a TCP socket versus gzip
  3. two buffers, two sides
  4. output derived from input

basics

~20 s

Readable is a source, Writable a destination, Duplex is both with two independent sides (a TCP socket), and Transform is a Duplex whose output is computed from what was written to it (gzip, a cipher).

solid answer

~40 s

`node:stream` defines four fundamental classes. A `Readable` is a source you consume, such as `fs.createReadStream()` or `process.stdin`; a `Writable` is a destination you write to, such as `fs.createWriteStream()` or the response in an HTTP server. A `Duplex` implements both interfaces with two separate internal buffers, and its two sides need not be related: a `net.Socket` reads what the peer sends and writes what you send. A `Transform` is a `Duplex` whose readable output is derived from the data written into it, such as `zlib.createGzip()`; `PassThrough` is the trivial Transform that forwards its input unchanged. Object mode is a separate axis: a stream of any of the four classes can carry JavaScript values instead of bytes.

code

javascript · 13 lines
javascript
import { Readable, Writable, Duplex, Transform, PassThrough } from 'node:stream';
import { createGzip } from 'node:zlib';
import { Socket } from 'node:net';

const gzip = createGzip();
const socket = new Socket();

console.log(gzip instanceof Transform);   // true
console.log(socket instanceof Duplex);    // true
console.log(socket instanceof Transform); // false
console.log(socket instanceof Readable);  // true
console.log(socket instanceof Writable);  // true
console.log(new PassThrough() instanceof Transform); // true

go deeper

for a junior

Name the four classes with one core example each, and say in one sentence what makes a Transform special compared with a Duplex.

for a middle

Explain that a Duplex has two independent buffers and sides, that Transform is a Duplex with related output, and that object mode is orthogonal to the class.

for a senior

Use the class to predict behaviour: why a socket can be half-closed, why a Transform in a chain can fail on either side, and which base class a new stream should extend.

for a principal

Treat the class as part of an API contract: decide what a library returns, document the chunk type and mode, and keep object-mode and byte streams from being mixed by callers.

## The four classes at a glance A **stream** in Node.js is an object that hands data over piece by piece instead of all at once, so a 2 GB file or an endless socket never has to fit in memory. Every stream in `node:stream` is an instance of one of four fundamental classes, and every core API that streams (files, sockets, HTTP, compression, child processes) returns one of them. | Class | Role | Core examples | |---|---|---| | `Readable` | a **source** you consume | `fs.createReadStream()`, `process.stdin`, the request object in an HTTP server, a child's `stdout` | | `Writable` | a **destination** you write to | `fs.createWriteStream()`, `process.stdout`, the response object in an HTTP server, a child's `stdin` | | `Duplex` | **both**, with independent sides | `net.Socket` | | `Transform` | a `Duplex` whose output is **computed from its input** | `zlib.createGzip()`, crypto cipher and hash streams | ## Readable and Writable: the two interfaces - A **Readable** exposes events such as `'data'`, `'readable'`, `'end'` and `'error'`, plus methods such as `read()`, `pause()`, `resume()` and `pipe()`. It is also async-iterable, so `for await (const chunk of readable)` works. - A **Writable** exposes `write()`, `end()` and events such as `'drain'`, `'finish'` and `'error'`. - Each keeps an **internal buffer** whose size threshold is its `highWaterMark`; how a writer honours that threshold is the subject of the backpressure lesson, not this one. ## Duplex: two independent sides A **Duplex** implements both interfaces at once and keeps **two separate internal buffers**, one per direction. The key word is *independent*: nothing says the bytes you read have anything to do with the bytes you wrote. - On a `net.Socket`, the readable side delivers what the remote peer sent, and the writable side carries what your code sends. The two flow at different rates and are buffered separately. - The `allowHalfOpen` constructor option (default `true` for `Duplex`) decides whether ending the readable side automatically ends the writable side. - Duplex options let each side be configured separately: `readableObjectMode`, `writableObjectMode`, `readableHighWaterMark`, `writableHighWaterMark`. - `instanceof` reflects the dual nature: a Duplex is `instanceof Readable` through its prototype and also `instanceof Writable`, which Node arranged in v6.8.0. ## Transform: a Duplex with a relationship A **Transform** is a `Duplex` in which the output *is related to* the input: you write raw bytes into a gzip stream and read compressed bytes out; you write plaintext into a cipher and read ciphertext. Because it is still a Duplex, it still has two buffers, and it can be placed between a Readable and a Writable in a chain. 1. A source (`Readable`) produces chunks. 2. One or more `Transform` streams convert them (decompress, decrypt, parse). 3. A destination (`Writable`) consumes the result. `PassThrough` is the degenerate Transform whose output equals its input. The docs describe it as mostly for examples and testing, though it is also handy as a placeholder you can hand out before the real source exists. ## Object mode is a separate axis The four classes say **which direction** data moves. **Object mode** says **what** moves. By default streams carry strings, `Buffer`, `TypedArray` or `DataView` chunks; with `objectMode: true` a stream carries any JavaScript value except `null`, which is reserved to signal the end of a Readable. Object mode is set at construction, and it is not a fifth class: a Readable, Writable, Duplex or Transform can each run in either mode. ## Why the distinction matters in practice - Knowing that a socket is a Duplex explains why closing one side does not necessarily close the other, and why it has two buffers to watch. - Knowing that a Transform is a Duplex explains why it can sit between two streams in a chain and why errors can come from either side. - Choosing the right base class is the first step in writing your own stream; implementing `_transform` and `_read` is covered in the lesson on custom streams. - Knowing which class a core API returns tells you which methods exist: a `Readable` has no `write()`, a `Writable` has no `'data'` event, and only the Duplex family offers both. - Reading a stack trace or a heap snapshot gets easier when you recognise `ReadStream`, `Socket`, `Gzip` and `PassThrough` as concrete subclasses of these four. A one-line way to remember it: **Readable produces, Writable consumes, Duplex does both independently, Transform does both with the output depending on the input.**

  • Why is a net.Socket a Duplex but not a Transform?
    Because its two sides are unrelated. The readable side carries bytes the remote peer sent and the writable side carries bytes your code sends; nothing you write comes back out transformed. A Transform promises that its output is derived from its input, which is true of a gzip or cipher stream but not of a network connection.
  • What does allowHalfOpen control on a Duplex stream?
    Whether the writable side stays open after the readable side ends. With the `Duplex` default of `true`, receiving the end of the incoming data does not end your outgoing side, so you can still send a reply. Set to `false`, the writable side is ended automatically when the readable side ends. The TCP-socket material covers how the network modules set it.
  • When is PassThrough useful outside of tests?
    When you must hand out a stream before the real source exists, or need one fixed object that several producers can feed. You return a `PassThrough` immediately, then pipe the real source into it later; consumers read from the PassThrough the whole time. It forwards chunks unchanged, so it adds a buffer but no processing.

A Duplex is a phone call: what you hear and what you say are two separate conversations on one line. A Transform is an interpreter: what comes out is what you just said, converted.

  • A Duplex is just a Transform whose output equals its input.
  • A Transform keeps one shared buffer for input and output.
  • A net.Socket is a Transform because it both reads and writes.
  • Object mode is a fifth kind of stream class.
  • Node streams can only carry Buffer chunks.
open as a page

In Node.js, what is the difference between flowing and paused mode on a stream.Readable, and which calls switch a stream between them?

level: middleimportance: must knowfreq 68%

basics

~20 s

In flowing mode a Readable pushes chunks to 'data' listeners as soon as they arrive; in paused mode you pull them with read(). A 'data' listener, resume() or pipe() starts the flow; pause() or unpiping every destination stops it.

open as a page

In Node.js, how does for await...of over a stream.Readable differ from an async 'data' handler, and what does an early break do to the stream?

level: middleimportance: should knowfreq 55%

basics

~20 s

for await reads one chunk, waits for the loop body, then reads the next, and throws stream errors into the loop; a 'data' handler's promise is ignored. An early break destroys the stream unless you use readable.iterator({ destroyOnReturn: false }).

open as a page

When a Node.js service wraps a queue consumer as Readable.from(messages(), { highWaterMark: 16 * 1024 }), why do thousands of unprocessed messages pile up in memory?

level: seniorimportance: should knowfreq 40%

basics

~20 s

Readable.from() creates an object-mode stream, where highWaterMark counts values, not bytes. A value of 16,384 tells Node to prefetch up to 16,384 messages from the generator before it stops pulling. Use a small count instead.

open as a page

Why does a Node.js log-tailing service lose its early lines when it calls readline.createInterface() on fs.createReadStream(), awaits a queue connection, and only then iterates with for await?

level: seniorimportance: should knowfreq 35%

basics

~20 s

readline.createInterface() starts consuming its input immediately, switching the file stream to flowing and emitting 'line' events. The for await iterator only listens once the loop starts, so lines emitted during the await are lost. Create the interface after the await.

open as a page

Your team's shared Node.js library streams data to Node 24 services and to browser code: should its public API return a Node Readable or a web ReadableStream, and why?

level: principalimportance: nice to knowfreq 25%

basics

~20 s

If browsers or other runtimes consume it, return a web ReadableStream, the standard type fetch bodies use, and let Node callers convert with Readable.fromWeb(). If only Node code consumes it, a Node Readable fits its ecosystem better.

open as a page