Skip to content
Tutorials Center
My learning

Topics

Lesson 39 of 133 ยท Streams

Web Streams in Node.js

Use the standard Web Streams API in Node.js - ReadableStream, WritableStream, TransformStream, CompressionStream, TextDecoderStream, fetch bodies and conversion to and from Node streams.

Node's classic streams (Readable, Writable, Transform) were invented before the web had any streaming story. Later, browsers got their own standard: the Web Streams API (ReadableStream, WritableStream, TransformStream). It is the type behind fetch() response bodies, Blob.stream(), CompressionStream and many other web APIs. Node implements the same standard, available as globals, so code you write for streams can run in browsers, Deno, Bun, edge runtimes and Node alike.

This lesson shows the Web Streams model, how it differs from Node streams, the built-in helpers (CompressionStream, TextDecoderStream), how fetch gives you a stream, and how to convert between the two worlds. If you are new to streaming, start with Streams Fundamentals.

Two families of streams

Node streams Web streams
Import node:stream globals (also node:stream/web)
Chunks Buffers, strings or objects Anything; bytes are Uint8Array
Reading events, read(), for await getReader().read(), for await
Connecting pipeline(a, b, c) a.pipeThrough(t).pipeTo(w)
Backpressure write() return value, drain desiredSize, ready promise, built in
Runs in Node only Node, browsers, Deno, Bun

Node streams are deeply integrated with Node APIs (fs, net, http, zlib). Web streams are the portable standard. Modern Node code uses both, and you convert at the boundary.

ReadableStream

A ReadableStream is created with an underlying source: an object whose start, pull and cancel methods produce data. pull(controller) is called when the internal queue has room (pull-driven, like _read). You hand chunks over with controller.enqueue(chunk) and end the stream with controller.close().

Node.js A ReadableStream you can pull from

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.

getReader() locks the stream to that reader: only the reader may read until it calls releaseLock(). Each read() returns a promise for { value, done }. A stream can only have one reader at a time, which prevents two parts of a program from fighting over chunks.

ReadableStream is also an async iterable, so you can skip the reader:

Node.js for await over a ReadableStream

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.

ReadableStream.from(iterable) is the Web Streams counterpart of Readable.from. The endless stream shows that pull is only called while there is room in the queue and someone is reading, which is backpressure again, this time without any drain event. The stream's highWaterMark (default 1 chunk) is the queue size, and controller.desiredSize tells a source how much room is left.

WritableStream and TransformStream

A WritableStream takes an underlying sink with write(chunk), close() and abort(reason). The methods can return promises, and the stream waits for them before sending the next chunk, which is how backpressure arrives.

A TransformStream is a pair: a writable side you write into and a readable side you read from. You give it a transform(chunk, controller) function (and optionally flush(controller)). The names deliberately echo Node's, but notice that you push with controller.enqueue() and no callback is needed: return a promise if the work is async.

Node.js pipeThrough and pipeTo

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.

pipeThrough(transform) returns the transform's readable side so you can keep chaining; pipeTo(writable) returns a promise that resolves when the whole pipe is done and rejects on error. Errors propagate and cancel the other streams, so pipeTo gives you much of what pipeline gives Node streams. The options object accepts a signal for cancellation, as in pipeline and Backpressure.

Built-in transform streams

The web platform ships ready-made transforms, and Node has them as globals:

  • TextEncoderStream: strings to UTF-8 Uint8Array chunks.
  • TextDecoderStream: bytes to strings, correctly handling characters split across chunks.
  • CompressionStream and DecompressionStream: 'gzip', 'deflate', 'deflate-raw' (and newer formats in newer runtimes).

They make small stream jobs easy. Here is a gzip round trip entirely in memory:

Node.js Compressing and decompressing with web streams

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.

1f 8b are the two bytes that start every gzip file. Blob.stream() is another source of web streams. Node's own zlib module offers more formats and options; CompressionStream is the portable choice. The helpers in node:stream/consumers accept web streams as well as Node streams.

fetch bodies are web streams

The body of a fetch response is a ReadableStream of Uint8Array chunks. You can process a download as it arrives rather than waiting for all of it. The example starts a tiny server on the loopback address (there is no external network in this editor) that sends a message in pieces.

Node.js Streaming a fetch response

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.

If you only need the whole body, await response.text() or .json() is simpler, but those buffer the entire response. For large downloads or incremental output (a progress bar, server-sent events, NDJSON feeds), consume response.body as a stream.

Note also that a Response can wrap a stream: new Response(readableStream) makes a response whose body is produced lazily. That is how streaming responses are returned by fetch-style handlers in edge runtimes.

Converting between Node streams and web streams

node:stream provides the bridges, both ways:

  • Readable.toWeb(nodeReadable) and Readable.fromWeb(webReadable)
  • Writable.toWeb(nodeWritable) and Writable.fromWeb(webWritable)
  • Duplex.toWeb(...) and Duplex.fromWeb(...)

Backpressure is preserved in both directions. These are the glue between Node I/O and portable code.

Node.js Crossing the bridge both ways

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.

Readable.fromWeb creates a byte stream by default, so for chunks that are not bytes (like the numbers above) you must pass { objectMode: true }; without it Node throws ERR_INVALID_ARG_TYPE just as in Readable Streams. Typical real-world use: open a file with fs.createReadStream (a Node stream), convert it with Readable.toWeb and pass it to a function written against the standard API; or take response.body from fetch and feed it to fs.createWriteStream via Readable.fromWeb.

Choosing between them

  • Writing for Node servers and scripts with files, sockets, HTTP and zlib: Node streams and pipeline, since the whole ecosystem speaks them.
  • Writing portable libraries or code that also runs in the browser or at the edge: Web Streams.
  • Handling fetch and Blob: web streams, converting at the edges.
  • Simple transformations: async generators work with both worlds, because both are async iterable.

Performance note: Node's own streams are generally faster for raw file and network throughput today. Web streams trade some speed for portability, so benchmark if you push very high throughput.

Locking is the most common source of confusion. A stream with a reader (or a pipe in progress) is locked, and a second getReader() or pipeTo() throws. Use stream.tee() to split one stream into two independent branches, and remember that tee buffers the data of the slower branch.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which method connects a ReadableStream to a TransformStream and returns the transform's readable side?

    pipeThrough(transform) returns the transform's readable side so you can chain; pipeTo(writable) ends the chain and returns a promise.
  2. 2. What is the type of response.body from fetch()?

    fetch bodies are standard ReadableStreams. Convert with Readable.fromWeb() to use them with Node APIs.
  3. 3. Why use TextDecoderStream instead of decoding each Uint8Array chunk yourself?

    The decoder keeps incomplete byte sequences between chunks, just like setEncoding on Node streams.
  4. 4. What happens when you call getReader() on a stream that already has a reader?

    A stream has at most one reader. Use tee() to create two branches.
  5. 5. How do you turn a Node.js Readable into a web ReadableStream?

    Readable.toWeb() creates a web stream from a Node stream and keeps backpressure working. Readable.fromWeb() converts the other way.

Summary

  • Web Streams (ReadableStream, WritableStream, TransformStream) are the portable standard and are global in Node.
  • A ReadableStream is built from an underlying source with start, pull and cancel; read it with getReader() or for await, and note that reading locks it.
  • Chain with pipeThrough() and finish with pipeTo(); both propagate errors and accept a signal.
  • TextEncoderStream, TextDecoderStream, CompressionStream and DecompressionStream are ready-made transforms.
  • fetch() response bodies are web streams, so large downloads can be processed incrementally.
  • Readable.toWeb/fromWeb (and the Writable and Duplex versions) bridge Node and web streams with backpressure preserved.
  • Use Node streams for Node-specific I/O and web streams for portable code and web APIs; async iteration is the common ground.

Next: Stream Patterns and Recipes