In Node.js's node:stream module, what are the four fundamental stream classes, and how does a Transform differ from a plain Duplex?
answer
- source, destination, or both
- a TCP socket versus gzip
- two buffers, two sides
- output derived from input
basics
~20 sReadable 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 linesimport { 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); // truego deeper
Name the four classes with one core example each, and say in one sentence what makes a Transform special compared with a Duplex.
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.
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.
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.