When data arrives faster than it can be used—or before it is ready to be interpreted—buffering holds it temporarily. In JavaScript, that can mean keeping incoming bytes in memory or letting a stream queue chunks ahead of a consumer. The two uses solve different problems: preserving raw data and managing the flow of work. section 11.1.1 section 11.3.1
An HTTP body illustrates why raw bytes matter. Content-Length counts bytes, but a JavaScript string’s length counts characters; decoding the body before checking its size can give the wrong comparison. Node.js can receive the body as Buffer chunks, combine them with Buffer.concat, check the resulting byte length, and decode to UTF-8 afterward. A chunk boundary is not necessarily a text boundary: one UTF-8 character can span two chunks. section 11.1.1
A buffer is a block of memory, not a declaration of what its bytes mean. Node.js Buffer supports byte access because it inherits from Uint8Array. Typed arrays provide numeric views of buffered data; DataView is useful when a format mixes types or requires a specified byte order for multi-byte values. For example, a PNG header combines text, numeric fields, and a checksum in one byte sequence. section 11.1.2 section 11.1.3
A pull stream with one chunk ready
A ReadableStream whose pull method enqueues one number can prepare the next number before the consumer requests it. With the default high watermark of 1, it buffers a chunk; after the consumer reads that chunk, the stream pulls again. Set the high watermark to 0 when the consumer should drive pulls directly. section 11.3.1 section 11.3.2
Listing 11.9 Speeding up throughout by raising the high watermark
import { setTimeout } from "node:timers/promises";
const totalChunks = 100;
const flushInterval = 10;
function createSource() { #A
let remaining = totalChunks; #A
return new ReadableStream<number>({ #A
async pull(controller) { #A
await setTimeout(0); #A
controller.enqueue(remaining); #A
if (--remaining === 0) controller.close(); #A
}, #A
}); #A
} #A
async function timeWithHighWaterMark(
highWaterMark: number,
) {
let count = 0;
const sink = new WritableStream<number>( #B
{ #B
async write() { #B
if (++count % flushInterval === 0) { #B
await setTimeout(10); #B
} #B
}, #B
}, #B
{ highWaterMark }, #B
); #B
const start = performance.now(); #C
await createSource().pipeTo(sink); #C
return Math.round(performance.now() - start); #C
}
const time1 = await timeWithHighWaterMark(1);
const time10 = await timeWithHighWaterMark(10);
console.log(`highWaterMark 1: ${time1}ms`);
console.log(`highWaterMark 10: ${time10}ms`);
console.assert(
time10 < time1,
"Higher highWaterMark, higher throughput",
);
The source produces chunks while a writable sink occasionally pauses. Compare the sink’s highWaterMark settings to see how buffering more chunks during a pause can improve throughput at the cost of memory. section 11.3.2
For a pull-only ReadableStream, the high watermark is a queue target, not a strict maximum: one pull can enqueue several chunks. Its default is 1, or 0 for a byte stream. A larger target can reduce consumer wait time but uses more memory. This backpressure setting lets the consumer influence production, although some streams may ignore it. section 11.3.2 section 11.4







