Search across all documentation pages
A stream is Node's answer to a question every I/O-heavy program eventually faces: what do you do when the data is too large, too slow-arriving, or too open-ended to reasonably hold in memory all at once? Instead of returning a value in one shot, a stream hands you data as a sequence of smaller pieces over time, arriving as they become available.
Streams Basics shows working code for the four stream types, and Backpressure, Readable & Writable Patterns, and Transform & Duplex each go deep on one piece of the picture. This page is the frame around all of them: why streams exist, how the pieces cooperate, and the feedback mechanism that makes the whole system safe under load.
await readFile() call never asks of you.stream/promises pipeline, HTTP response streaming.Before streams, the obvious way to handle a file or network payload in Node was to read the whole thing into memory, then operate on the complete result - simple to reason about, but only viable if the data is small and finite.
Node's core APIs (http, fs, net, zlib, and more) are built around a different idea instead: expose data as a sequence of discrete chunks, each a Buffer, string, or (in object mode) an arbitrary JavaScript value, delivered as they become ready rather than all at once. A stream is the object that manages that sequence - producing chunks (a Readable), consuming them (a Writable), or both.
A useful analogy: think of a stream as a conveyor belt between two workstations rather than a single crate delivered by forklift. The belt moves items one at a time, the receiving station can work on each item as it arrives instead of waiting for the whole shipment, and - critically - the belt can be told to slow down or stop if the receiving station falls behind, rather than piling boxes on the floor.
Node defines four stream types, each a role on that belt:
Readable -> produces chunks (e.g. fs.createReadStream)
Writable -> consumes chunks (e.g. fs.createWriteStream)
Duplex -> both, independently (e.g. a TCP socket)
Transform -> both, with output derived (e.g. zlib.createGzip)
from input (a Duplex subtype)
Every stream type is built on EventEmitter - a Readable emits 'data' and 'end', a Writable emits 'drain' and 'finish', and every stream can emit 'error'. That shared foundation is why streams compose the way they do: connecting streams is really connecting event producers to event consumers, with the stream classes managing the bookkeeping (internal buffers, state machines) on top.
The single most important piece of that bookkeeping is backpressure. Every Writable has an internal buffer with a configurable highWaterMark (a soft byte or object-count ceiling); when a producer writes faster than a consumer can drain that buffer, writable.write() starts returning false as a signal to pause. A stream API that ignores this signal and keeps writing anyway defeats the entire memory-bounding purpose of using a stream in the first place - the internal buffer just grows without limit instead. Backpressure covers the drain event and manual pause/resume mechanics in full.
pipe() (and its safer modern counterpart, stream/promises' pipeline()) exists specifically so you rarely have to manage that feedback loop by hand: piping a Readable into a Writable wires up backpressure handling, forwards 'data' chunks, and (in pipeline()'s case) propagates errors and guarantees cleanup on either side failing.
import { pipeline } from 'node:stream/promises';
import { createReadStream, createWriteStream } from 'node:fs';
import { createGzip } from 'node:zlib';
// Each stage only ever holds a bounded window of data in memory -
// not the whole file - and backpressure from the write stage
// automatically slows the read stage if disk I/O falls behind.
await pipeline(
createReadStream('input.log'),
createGzip(),
createWriteStream('input.log.gz'),
);That snippet also demonstrates why Transform streams matter as their own category: createGzip() is simultaneously a Writable (accepting raw bytes) and a Readable (emitting compressed bytes), with its output causally derived from its input - a shape distinct enough from a general Duplex (whose read and write sides are independent, like a TCP socket's two directions) that Node models it as its own subclass. Transform & Duplex covers building custom versions of both.
Streams interact directly with the event loop's I/O model: a Readable sourced from a file or socket doesn't poll for data, it relies on the underlying libuv I/O completion mechanism to deliver chunks as the OS makes them available, which is part of why streaming I/O scales well under Node's single-threaded, non-blocking design rather than fighting it.
Error handling is the sharpest operational edge in this whole model. Because a pipeline is really several independently-emitting EventEmitters wired together, an unhandled 'error' on any one of them crashes the process by default - and a naive pipe() chain doesn't automatically destroy every other stream in the chain when one link fails, which can leak open file descriptors or sockets. stream/promises' pipeline() was built specifically to close that gap: it destroys every stream in the chain on any failure and surfaces one rejected Promise instead of scattered events to listen for. stream/promises Pipeline covers this in depth, and Streams Best Practices turns it into concrete rules.
HTTP is one of the highest-leverage places this model shows up in practice: both the incoming request and the outgoing response in Node's http module are streams, which means a proxy or reverse-proxy-adjacent service can forward a large request body or response without ever buffering the whole thing - Streaming HTTP Responses covers the header-timing and chunked-transfer-encoding details that come with that.
| Approach | Strength | Weakness | Best Fit |
|---|---|---|---|
Buffer entire payload (readFile, req.body middleware) | Simple, synchronous-feeling code; easy to reason about | Memory scales with payload size; no progress until fully loaded | Small, bounded payloads (config files, small JSON bodies) |
Manual pipe() chains | No extra dependency; direct control | Error handling and cleanup across the chain are the caller's responsibility | Simple, single-stage forwarding with careful error listeners |
stream/promises pipeline() | Automatic cleanup and error propagation across every stage | Slightly more ceremony than a bare pipe() call | Any multi-stage or production pipeline |
Async iteration (for await...of a Readable) | Reads naturally like sequential code; integrates with async/await | Only covers the consuming side; still needs care composing multiple stages | Simple chunk-by-chunk consumption logic |
readFile." They're not about speed for a single read - they're about bounding memory and letting processing start before input is fully available, which matters most exactly when payloads are large or open-ended.pipe() handles errors for you." It forwards data and manages backpressure, but an error on one stream in a pipe() chain doesn't automatically destroy the others - pipeline() was built to close that specific gap.highWaterMark mechanics as a multi-gigabyte file copy.They let code process data that's too large, too slow-arriving, or too open-ended to reasonably hold entirely in memory - by handing it over in bounded chunks over time instead of as one complete value.
Every stream class is built on EventEmitter - Readables emit 'data'/'end', Writables emit 'drain'/'finish', and all streams can emit 'error'; the stream classes add buffering and state-machine logic on top of that shared event foundation.
It's the feedback signal a Writable gives when its internal buffer is full - write() returns false, telling the producer to pause until a 'drain' event says it's safe to resume - which is what keeps a fast producer from growing memory without bound when writing to a slower consumer.
pipeline() (from node:stream/promises) destroys every stream in a multi-stage chain if any one of them errors, and resolves or rejects a single Promise for the whole operation - a bare pipe() chain doesn't propagate errors or clean up other stages automatically, which can leak open handles.
No - object mode lets a stream carry arbitrary JavaScript values instead of bytes or strings, which is how patterns like streaming parsed rows or JSON records through a processing pipeline work; highWaterMark then counts objects rather than bytes.
Yes - for small, bounded data (a config file, a small JSON body) buffering the whole thing is simpler and the memory cost is negligible; streaming earns its complexity specifically when payload size is large or unknown ahead of time.
A stream sourced from a file or socket relies on libuv's I/O completion mechanism to deliver chunks as the OS makes them ready, rather than polling - so streaming I/O fits Node's non-blocking model instead of working against it.
Because 'error' is a special EventEmitter event - if no listener is registered for it, Node treats it as an uncaught exception and terminates the process by default, which is why every stream in a chain needs error handling, not just the first one.
A Duplex has two independent sides - what you write and what you read aren't related (a TCP socket, for example). A Transform is a specialized Duplex where the output is derived directly from the input, like a gzip compressor turning raw bytes in into compressed bytes out.
Yes - any Readable is async-iterable, so for await (const chunk of readable) works and reads naturally as sequential code, while the stream still delivers chunks (and respects backpressure) under the hood exactly as it would with raw event listeners.
stream/promises Pipeline - safe multi-stage composition with automatic cleanupStack versions: This page was written for Node.js 24 LTS and TypeScript 5.6+.
Reviewed by Chris St. John·Last updated Jul 19, 2026