liveBook · Manning

Buffering

As explained in Secrets of the JavaScript Ninja, Third Edition

The temporary storage of produced data before it is consumed.

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

How Secrets of the JavaScript Ninja, Third Edition covers it

How deep it goes
Works through byte-length checks and ReadableStream queue behavior, including defaults, high-water-mark limits, and the memory–throughput tradeoff.
Examples
Uses an HTTP request body, a PNG header, a pull stream producing numbers, and a sink with periodic delays.
What it assumes
Assumes familiarity with JavaScript arrays and strings while defining raw buffers, typed arrays, and stream-queue behavior.
What you can do after
Operate/configure it by checking buffered byte lengths and adjusting a stream’s high watermark to balance waiting against memory use.
How it connects
Connects Buffer, typed arrays, DataView, streams, and backpressure through byte interpretation and producer–consumer flow.

Also explained in

Compare how 8 books explain buffering →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Secrets of the JavaScript Ninja, Third Edition. The section links point to the parts of the book it draws on.