skip to content

In Node.js 24, how do objectMode and highWaterMark govern buffering in a custom Readable or Transform, and what should the implementation do when push() returns false?

level: seniorimportance: should knowfreq 25%

answer

  1. threshold, not a limit
  2. bytes versus objects
  3. two buffers on a Transform
  4. stop pushing until _read again

basics

~20 s

highWaterMark is a buffering threshold: bytes in byte mode (64 KiB default in Node 24, 16 KiB on Windows), objects in object mode (default 16). When push() returns false, a Readable stops pushing until Node calls _read() again.

solid answer

~40 s

`highWaterMark` is the level at which a stream stops asking for data. In byte mode it counts bytes, defaulting to 64 KiB in Node 24 (16 KiB on Windows); in object mode it counts items, defaulting to 16, whatever their size. A Transform has two buffers, so `readableObjectMode`, `writableObjectMode` and the per-side high water marks let it take bytes and emit objects. `push()` returning `false` means the buffer is full: the chunk is still queued, but a custom `Readable` should stop pushing and wait for Node to call `_read()` again. In a `Transform`, Node holds your callback until the consumer reads, which pauses the input for you.

code

javascript · 37 lines
javascript
import { Readable } from 'node:stream';

// Wraps a paged source. _read pushes until push() returns false,
// then waits for Node to call _read again.
export class PagedReader extends Readable {
  constructor(fetchPage) {
    super({ objectMode: true, highWaterMark: 100 });
    this.fetchPage = fetchPage;
    this.page = 0;
    this.items = [];
    this.loading = false;
  }

  _read() {
    this.#fill();
  }

  #fill() {
    while (this.items.length > 0) {
      if (!this.push(this.items.shift())) return;
    }
    if (this.loading) return;
    this.loading = true;
    this.fetchPage(this.page++).then(
      (items) => {
        this.loading = false;
        if (items.length === 0) {
          this.push(null);
          return;
        }
        this.items = items;
        this.#fill();
      },
      (err) => this.destroy(err),
    );
  }
}

go deeper

for a junior

Recall the two units: bytes by default, objects in object mode, with defaults of 64 KiB and 16.

for a middle

Explain that push() returning false is a request to stop, and how a Readable resumes when Node calls _read() again.

for a senior

Show the object-mode memory trap, the per-side options on a mixed-mode Transform, and why a Transform pauses its input by holding your callback.

for a principal

Set defaults the team can reason about: item granularity in object mode, explicit high water marks for heavy records, and memory budgets summed across a chain.

## What `highWaterMark` measures Every `Readable` and `Writable` in `node:stream` keeps an internal buffer, and **`highWaterMark`** is the level at which the stream stops asking for more. The unit depends on the mode: | Stream mode | `highWaterMark` counts | Node 24 default | |---|---|---| | Byte mode (`Buffer` chunks) | Bytes | `65536` (64 KiB) on Linux and macOS, `16384` (16 KiB) on Windows | | Strings, not decoded | UTF-16 code units | Same number as above | | After `readable.setEncoding()` | Characters | Same number as above | | Object mode | Objects (chunks) | `16` | `stream.getDefaultHighWaterMark(objectMode)` returns the current default and `stream.setDefaultHighWaterMark(objectMode, value)` changes it process-wide. The byte default was raised in v22.0.0, a semver-major change, so a service upgraded from Node 20 can buffer more in streams that rely on the default. It is a **threshold, not a limit**. The docs say so in those words: it decides when the stream stops asking for data, not how much memory it can use. ## Object mode counts items, not memory In **object mode** each pushed value counts as one, whatever its size. Sixteen 10 MB arrays are "16" to the stream. A Readable that pushes whole query pages, or a Transform that emits large decoded records, can hold far more memory than the number suggests. The fix is to choose the unit deliberately: push individual rows rather than pages, or lower `highWaterMark` for heavy objects. ## Per-side settings on a Transform A `Transform` is a `Duplex` with **two buffers**. The options are per side: - `readableObjectMode` / `writableObjectMode` set object mode on one side only. - `readableHighWaterMark` / `writableHighWaterMark` size each side; a plain `highWaterMark` overrides both. - A Transform that takes bytes and emits objects therefore counts its input in bytes (64 KiB) and its output in objects (16) by default. Pushing a non-buffer value into a byte-mode readable side fails with `ERR_INVALID_ARG_TYPE`, and pushing `null` in any mode means **end of stream**. ## What `push()` returning `false` asks of you `push(chunk)` returns `true` while the readable buffer is below `highWaterMark` and `false` once it reaches it. The data is still accepted when it returns `false`; it is a request to stop producing. **In a custom `Readable`** you own the producer, so you must honour it: 1. In `_read()`, push items until `push()` returns `false`, then return. 2. Do not push again until Node calls `_read()` again; it does so once the consumer has read the buffer back below `highWaterMark`. 3. If the source is asynchronous, start one fetch, push its results, and keep a flag so overlapping `_read()` calls do not start parallel fetches. 4. Push `null` when the source is exhausted, and report failures with `this.destroy(err)`; the docs call throwing from `_read()` undefined behaviour. Two details matter. `_read()` is not called again until you push more data, so a `_read()` that returns without pushing and without arranging a later push stalls the stream. And ignoring the return value, as in a `while` loop that pushes every item unconditionally, defeats backpressure: the buffer grows without bound. **In a custom `Transform`** Node applies backpressure for you. After your `_transform` callback, if the chunk's output left the readable buffer at or above its `highWaterMark`, the Transform **holds that callback** until the consumer reads, so the next input chunk waits. You may push several items for one input chunk even after `push()` returned `false`; the overshoot is bounded by one chunk's output, and the paused input does the rest. ## Choosing the values - Leave the defaults for byte streams unless measurements say otherwise; the 64 KiB default already suits file and socket I/O. - In object mode, size `highWaterMark` by **memory per item**, not by habit. - Set both sides explicitly on a mixed-mode Transform when the objects are large. - Remember that each stage of a chain adds its own buffers, so worst-case memory is the sum across stages. - Avoid `stream.setDefaultHighWaterMark()` in library code: it changes the default for every stream in the process, including ones the library does not own. A useful habit when reviewing a custom stream is to ask two questions: what does one unit of `highWaterMark` cost in memory here, and where does the code stop producing when `push()` says the buffer is full? If either has no answer, the stream's memory is bounded only by the speed of its consumer.

  • A Readable in object mode pushes whole result pages of 5,000 rows. What does highWaterMark 16 mean for memory?
    Up to about 16 pages, or 80,000 rows, can sit in the buffer before `push()` returns `false`, because object mode counts each page as one. Push individual rows instead, or lower `highWaterMark`, so the threshold reflects memory rather than call count.
  • Does push() returning false mean the chunk was rejected?
    No. The chunk was queued; `false` only says the buffer has reached `highWaterMark` and the producer should stop. That is why it is a threshold rather than a limit: ignoring it keeps adding data to the buffer instead of failing.

  • highWaterMark caps the memory a stream can use, so pushes past it are dropped.
  • In object mode highWaterMark is measured in bytes of the objects.
  • When push() returns false the chunk was rejected and must be pushed again.
  • A Transform shares a single buffer between its input and output sides.
  • _read() keeps being called on a timer even if it pushed nothing.

Assumes Node 24; v22.0.0 raised the default byte-mode highWaterMark, now 64 KiB (16 KiB on Windows), while the object-mode default stays 16.