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.
const stream = new Readable({ highWaterMark: 1024 }); console.log(stream.readableHighWaterMark);
Try it
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.
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()returnschunk buffered size < highWaterMark. After afalse,'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
readableHighWaterMarkandwritableHighWaterMarkseparately, orhighWaterMarkfor 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
0is allowed and makes everywrite()returnfalsewhile 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 respectwrite()return values or usepipeline(). writableLengthandreadableLengthshow how full each buffer currently is.