Skip to content
Tutorials Center
My learning

Topics

Lesson 106 of 156 ยท Browser APIs

Streams API in the Browser

Process data chunk by chunk with ReadableStream, TransformStream and WritableStream - pipes, backpressure, tee(), and streaming fetch with progress.

When you call await response.json(), the browser first downloads the entire body, keeps it in memory, and only then hands it to you. That is fine for a small JSON file. It is a poor fit for a 2 GB log, a video, a live feed of tokens from an AI model, or a file upload that should show a progress bar. For these, you want to handle data piece by piece as it arrives, without ever holding all of it at once.

The Streams API gives JavaScript exactly that. A ReadableStream produces chunks, a WritableStream consumes them, and a TransformStream sits in the middle and changes them. You connect them with pipes, and the system automatically slows fast producers down when consumers can't keep up (this is called backpressure). Streams are built into modern browsers and also into Node.js, so every demo in this lesson runs in the editor.

Three kinds of streams

flowchart LR
  A["ReadableStream<br/>(source of chunks)"] -->|"pipeThrough()"| B["TransformStream<br/>(changes chunks)"]
  B -->|"pipeTo()"| C["WritableStream<br/>(sink)"]
  C -.->|"backpressure:<br/>please slow down"| A

Chunks flow forward through pipes; backpressure signals travel backward so nothing is produced faster than it can be consumed.

  • A ReadableStream is where data comes from: a fetch() body, a file, a camera, or a source you write yourself.
  • A WritableStream is where data goes: a file, a network upload, or your own function that handles each chunk.
  • A TransformStream is a pair of both. You write into one end and read the changed data from the other.

A chunk can be any JavaScript value: bytes (Uint8Array), strings or objects. Streams from fetch() and files always carry bytes.

Creating and reading a ReadableStream

You create a readable stream by giving it an underlying source, an object with callbacks. pull(controller) is called whenever the stream wants more data; you answer by calling controller.enqueue(chunk), and you call controller.close() when there is nothing left.

To consume a stream you ask it for a reader with getReader(). reader.read() returns a promise for { done, value }. A stream can have only one reader at a time (it becomes locked), which prevents two pieces of code from stealing each other's chunks.

JS A countdown stream and two ways to read it

Press Run (or Ctrl + Enter) to see the console output here.

No output.

for await...of over a stream is the shortest way to read it. If you leave the loop early with break, the stream is cancelled for you. (Safari added async iteration of streams late, so for older Safari versions use the getReader() loop, or check Symbol.asyncIterator in ReadableStream.prototype.) See async iteration for how this kind of loop works.

Transforming with pipes

Real streams almost never arrive in neat pieces. A network may deliver "apple\nban" and then "ana\nche", cutting a word in half. A TransformStream is the right place to fix that: it keeps a small buffer between chunks and emits clean units.

You write a transform(chunk, controller) function that is called for every incoming chunk, and an optional flush(controller) that runs once when the input ends so you can emit whatever is left over.

readable.pipeThrough(transform) returns the readable side of the transform, so pipes chain like a pipeline. readable.pipeTo(writable) ends the chain and returns a promise that resolves when everything has been written.

JS Bytes to lines with a TransformStream pipeline

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice TextDecoderStream. Decoding each byte chunk with a separate TextDecoder.decode() call can break a multi-byte character (like an emoji or an accented letter) that straddles two chunks. The stream version keeps that state for you. Other built-in transforms include TextEncoderStream, CompressionStream and DecompressionStream (gzip and deflate), so you can compress a file while it uploads:

JavaScript
// Read-only: gzip a Blob without loading a copy into memory
const compressed = file.stream().pipeThrough(new CompressionStream("gzip"));
const response = new Response(compressed);
const gzippedBlob = await response.blob();

A WritableStream

A writable stream wraps a sink: write(chunk) is called for each chunk, close() when the input ends normally and abort(reason) when something goes wrong upstream. If write() returns a promise, the stream waits for it before sending the next chunk, which is how a slow consumer pushes back on the producer.

Backpressure

Imagine a producer that reads a disk at 1 GB per second feeding a consumer that uploads at 1 MB per second. Without any control, the chunks pile up in memory. Streams solve this with a queue and a high-water mark. Each stream holds a small queue; when the queue is at its limit, the stream stops calling pull() until the consumer drains it.

You can see this by counting how often pull() runs. With a high-water mark of 2, the source fills a two-item queue on its own, then makes one more item for every item that is read:

JS Backpressure: pull only when there is room

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The producer made exactly two items before anyone asked, and afterward it stays one step ahead of the reader instead of racing to the end. The same mechanism works across a whole pipeline, which is why pipeTo() is better than a hand-written while loop. The default queue size is one chunk for most streams. For byte streams, ByteLengthQueuingStrategy measures the queue in bytes instead of chunks.

Cancelling and errors

reader.cancel(reason) (or stream.cancel()) tells the source to stop and release its resources: for a fetch() body, that closes the network connection. controller.error(err) makes the stream fail, and every later read() rejects. When you finish with a reader but keep the stream, call reader.releaseLock() so another reader can take over.

Streaming fetch

The real payoff comes from fetch(). The response.body property is a ReadableStream of bytes, available as soon as the response headers arrive. That lets you show progress, start rendering early, or stop a download midway.

JavaScript
// Read-only: download with a progress bar
const response = await fetch("/downloads/big-file.bin");
const total = Number(response.headers.get("Content-Length")); // may be missing
const reader = response.body.getReader();

let received = 0;
const chunks = [];
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  chunks.push(value);
  received += value.length;
  if (total) progress.value = received / total;
}
const blob = new Blob(chunks);

Two caveats. Content-Length is the compressed size when the server uses gzip or Brotli, while the chunks you read are already decompressed, so the percentage can exceed 100. And if the server doesn't send the header at all, show an indeterminate indicator. See fetch for the basics and AbortController for cancelling a request from the outside.

A Response can also be built from a stream, which makes it easy to test code that reads one. The demo below reproduces the progress loop with an in-memory body, and then shows tee(), which splits one stream into two independent copies so two consumers can each read everything:

JS Progress from a stream, and tee()

Press Run (or Ctrl + Enter) to see the console output here.

No output.

tee() has a catch: if one branch is read much faster than the other, the stream buffers the difference for the slow branch, so memory use can grow. Use it for small things like "show this image and cache it", not for unbounded data.

Streaming responses piece by piece

Streams shine for formats that arrive over time: lines of newline-delimited JSON, text from a language model, or server-sent progress messages. Compose the pieces you already know:

JavaScript
// Read-only: show text as it arrives
const response = await fetch("/api/story");
const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  output.textContent += value; // each value is a decoded string
}

For real-time two-way messaging, a WebSocket is a better fit; streams are for one body flowing in one direction.

Uploading a stream

Browsers are starting to allow a ReadableStream as the body of a fetch() request (with duplex: "half"), which would let you upload data as you generate it. Support is not universal and it requires HTTP/2 or later, so treat it as a progressive enhancement and test in your target browsers. Downloads, on the other hand, can be streamed everywhere.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What is the main benefit of reading a response body as a stream instead of calling response.text()?

    Streams let you start working on the first chunk immediately and keep only a small part of the data in memory at any moment.
  2. 2. What does a TransformStream's flush() method do?

    flush() is the place to emit data you were holding back, such as a final line that had no trailing newline.
  3. 3. What is backpressure?

    Each stream has a queue with a high-water mark. When it is full, pull() is not called again until the consumer reads some chunks.
  4. 4. Why use TextDecoderStream instead of decoding each byte chunk separately with TextDecoder?

    A character can be cut between two chunks. The stream remembers the incomplete bytes and finishes the character when the next chunk arrives.
  5. 5. What does readable.tee() return?

    tee() locks the original stream and gives you two branches, each of which receives all of the chunks.

Summary

  • Streams process data chunk by chunk, so memory use stays small and work can start before the data is complete.
  • A ReadableStream produces chunks (start/pull plus controller.enqueue and close), a WritableStream consumes them, and a TransformStream changes them. Read with getReader() or for await...of.
  • Connect streams with pipeThrough() and pipeTo(). Use TextDecoderStream, TextEncoderStream, CompressionStream and DecompressionStream instead of reinventing them.
  • Backpressure is automatic: a full queue stops pull() until the consumer catches up. Cancel with reader.cancel().
  • response.body from fetch() is a stream of bytes, ideal for progress bars and incremental rendering; Content-Length may be missing or compressed. tee() makes two copies of one stream.

Next: Service Workers and the Cache API - intercept network requests and make your app work offline.