liveBook · Manning

Push stream

As explained in Secrets of the JavaScript Ninja, Third Edition

A push stream is a stream whose source produces data proactively rather than only in response to consumer requests.

A push stream produces and enqueues data without waiting for the consumer to request it. In a JavaScript ReadableStream, a start method can enqueue values and close the stream when production is finished. If the consumer reads each value as soon as it arrives, the internal queue may stay small; that depends on the consumer’s pace. section 11.2.1

Listing 11.5 Creating a ReadableStream
import { setTimeout } from "node:timers/promises";
 
const ninjas = [
  "Leonardo",
  "Donatello",
  "Raphael",
  "Michelangelo",
];
 
const source = new ReadableStream<string>({
  async start(controller) { #A
    for (const ninja of ninjas) { #A
      controller.enqueue(ninja); #A
      await setTimeout(100); #A
    } #A
    controller.close(); #A
  },
});

const received: string[] = []; #B
for await (const ninja of source) { #B
  received.push(ninja); #B
} #B

console.assert(
  received.length === 4,
  "Four ninjas were received",
);

This ReadableStream enqueues four values from start, pauses between them, then closes; a for-await loop consumes them. section 11.2.1

A pull stream instead enqueues data when the consumer asks for it. The two approaches can look identical to consumers, but their production timing can affect performance. A stream can also combine start and pull, pushing initially and pulling later. section 11.2.1 section 11.3.1

Choose based on the work and resource tradeoffs:

  • Push can suit parsing an entire XML file quickly; pull can suit extracting information from large files while minimizing memory use. section 11.3.1
  • Do not assume a consumer’s high watermark controls a push source: for push streams it is only an optional hint and may have no effect. Check the stream’s documentation or implementation. section 11.3.2

How Secrets of the JavaScript Ninja, Third Edition covers it

How deep it goes
Works through start, enqueueing, closing, buffering, and performance tradeoffs, while noting that push-stream backpressure may be unreliable.
Examples
Uses a timed ReadableStream that enqueues four values and an XML-parser comparison to illustrate practical tradeoffs.
What you can do after
Evaluate whether proactive production suits an application’s throughput or memory needs, and check how its stream handles buffering.
How it connects
Connects push streams to pull streams, ReadableStream, async iteration, and backpressure.

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.