Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Streams and readline

Node.js highWaterMark

Explains highWaterMark in Node.js streams: the buffer threshold behind backpressure, default sizes, how it differs in object mode, and when to tune it.

highWaterMark is the size, in bytes (or in objects for object mode), at which a stream considers its internal buffer full. It is not a hard limit. A writable accepts data beyond it but answers false to write(); a readable stops asking its source for more data.

That one number is what turns a fast producer and a slow consumer into a stable pipeline instead of a memory leak. You set it per stream through the constructor option highWaterMark, and read it from readableHighWaterMark or writableHighWaterMark.

NODE
const stream = new Readable({ highWaterMark: 1024 });
console.log(stream.readableHighWaterMark);

Try it

Node.js Defaults and overrides

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.

Node.js A source that stops at the mark

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.

How it works

  • Writable: write() returns chunk buffered size < highWaterMark. After a false, 'drain' fires when the buffer drops back to empty.
  • Readable: after each push, if the buffered size is below highWaterMark, _read() is called again. Once the buffer is at or above it, the stream stops calling _read() until the consumer reads.
  • Transform and Duplex: each side has its own mark. Pass readableHighWaterMark and writableHighWaterMark separately, or highWaterMark for both.

Defaults

Stream Default
Byte streams (Readable, Writable, Transform) 65536 bytes (64 KiB) in current Node.js versions (16 KiB before Node 22)
Object mode streams 16 objects
fs.createReadStream() 65536 bytes (also the chunk size)
fs.createWriteStream() 16384 bytes

Use stream.getDefaultHighWaterMark(objectMode) and stream.setDefaultHighWaterMark(objectMode, value) to read or change the process-wide defaults.

Usage notes

  • A single chunk larger than the mark is still accepted whole; the mark is checked after adding data.
  • A mark of 0 is allowed and makes every write() return false while a write is in flight.
  • Bigger marks improve throughput for file and network copies at the cost of memory per connection; with thousands of concurrent streams the multiplication matters.
  • In object mode, the mark counts objects regardless of how large they are.
  • Do not raise the mark to hide a missing 'drain' handler. The right fix is to respect write() return values or use pipeline().
  • writableLength and readableLength show how full each buffer currently is.