Web Streams and Interop

Two kinds of plug

When you travel abroad, your phone charger might not fit the wall socket. The electricity is the same; only the plug is different. You carry a small adapter.

Node has the same situation with streams. There are:

• Node streams: the Readable, Writable and Transform classes from node:stream that you used in the last two lessons. They have existed since the early days of Node.
• Web streams: ReadableStream, WritableStream and TransformStream. These are a web standard, the same classes that browsers, Deno, Bun and edge platforms use.

Both carry data in chunks. They just have different “plugs”. This lesson shows you web streams and the adapters that convert between the two.

Why web streams matter in Node

You meet web streams more and more:

• fetch() gives you the response body as a web ReadableStream.
• Code written for browsers or edge runtimes uses web streams.
• Handy built-in classes like CompressionStream and TextDecoderStream are web streams.

Web streams are stable in Node and available as globals. You can also import them from node:stream/web.

Reading a ReadableStream

Creating one

You create a ReadableStream by passing an object with a start method. It receives a controller, which you use to add chunks (enqueue) and to finish (close):

// names.mjs
const names = new ReadableStream({
  start(controller) {
    controller.enqueue('Asha');
    controller.enqueue('Ravi');
    controller.enqueue('Maya');
    controller.close(); // no more chunks
  },
});

For quick tests, ReadableStream.from() makes one from an array or any iterable:

const names = ReadableStream.from(['Asha', 'Ravi', 'Maya']);

Reading with a reader

The standard way to read is to get a reader and call read() until it says done:

const reader = names.getReader();

while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  console.log('read:', value);
}

read: Asha
read: Ravi
read: Maya

While a reader is active, the stream is locked: nobody else can read from it. reader.releaseLock() unlocks it.

Reading with for await

In Node, a ReadableStream is also async iterable, so the simpler for await loop works:

for await (const name of ReadableStream.from(['Asha', 'Ravi'])) {
  console.log('loop:', name);
}

loop: Asha
loop: Ravi

If you break out of the loop early, the stream is cancelled for you.

Producing data on demand with pull

start runs once. If you want to produce data only when the reader asks for it, use pull. It is called each time the stream wants another chunk:

// counter.mjs
let i = 0;
const counter = new ReadableStream({
  pull(controller) {
    i++;
    if (i > 3) controller.close();
    else controller.enqueue(`tick ${i}`);
  },
});

for await (const tick of counter) console.log(tick);

tick 1
tick 2
tick 3

This is how web streams handle backpressure: if nobody reads, pull is not called, so no data piles up.

Writing to a WritableStream

A WritableStream takes an object with a write(chunk) method and optional close():

// logger.mjs
const logger = new WritableStream({
  write(chunk) {
    console.log('writing:', chunk);
  },
  close() {
    console.log('closed');
  },
});

const writer = logger.getWriter();
await writer.write('hello');
await writer.write('world');
await writer.close();

writing: hello
writing: world
closed

writer.write() returns a promise. To respect backpressure when writing in a loop, wait for writer.ready before each write:

for (const line of lines) {
  await writer.ready; // resolves when the stream has room
  writer.write(line);
}

TransformStream, pipeThrough and pipeTo

A TransformStream changes chunks as they pass through. Its transform(chunk, controller) method calls controller.enqueue() with the result:

// upper.mjs
const upper = new TransformStream({
  transform(chunk, controller) {
    controller.enqueue(chunk.toUpperCase());
  },
});

const shouting = ReadableStream.from(['asha', 'ravi']).pipeThrough(upper);
for await (const name of shouting) console.log(name);

ASHA
RAVI

Web streams connect with two methods:

• readable.pipeThrough(transform): sends data through a transform and returns the transformed readable, so you can chain.
• readable.pipeTo(writable): sends everything into a writable and returns a promise that settles when it is done.

Both handle backpressure and pass errors along the chain.

Built-in web transform streams

Node ships several ready-made transforms as globals:

fetch bodies are web streams

The body of a fetch response is a ReadableStream of Uint8Array chunks. You can stream a large download instead of loading it all at once:

// download.mjs
const res = await fetch('https://example.com');

let bytes = 0;
for await (const chunk of res.body) {
  bytes += chunk.length;
}
console.log(bytes, 'bytes');

You will learn more about fetch in the fetch lesson.

The Response class also works the other way: wrap any stream of bytes in new Response(stream) to collect it in one go:

const stream = ReadableStream.from(['Hi ', 'Asha']).pipeThrough(new TextEncoderStream());
console.log(await new Response(stream).text()); // prints: Hi Asha

Converting between Node and web streams

Now the adapters. The node:stream classes have static methods to convert in both directions:

Duplex.toWeb() and Duplex.fromWeb() exist too, for streams that are both.

Node to web

// node-to-web.mjs
import { createReadStream } from 'node:fs';
import { Readable } from 'node:stream';

const webStream = Readable.toWeb(createReadStream('orders.txt'));
console.log(webStream instanceof ReadableStream); // prints: true

const text = await new Response(webStream).text();
console.log('chars:', text.length); // prints: chars: 158893

Now you can use the file with any code that expects a web stream, such as CompressionStream:

// web-gzip.mjs
import { createReadStream, createWriteStream } from 'node:fs';
import { Readable, Writable } from 'node:stream';

await Readable.toWeb(createReadStream('orders.txt'))
  .pipeThrough(new CompressionStream('gzip'))
  .pipeTo(Writable.toWeb(createWriteStream('orders.txt.gz')));

Web to Node

// web-to-node.mjs
import { Readable } from 'node:stream';

const web = ReadableStream.from(['Hello ', 'from ', 'the web\n']);
const nodeStream = Readable.fromWeb(web);

for await (const chunk of nodeStream) {
  process.stdout.write(chunk.toString()); // prints: Hello from the web
}

This is useful when a library hands you a web stream (for example a fetch body) and you want to use Node tools with it.

pipeline accepts web streams directly

pipeline() from node:stream/promises understands both kinds, so often you do not need to convert at all:

await pipeline(
  Readable.toWeb(createReadStream('orders.txt')).pipeThrough(new CompressionStream('gzip')),
  createWriteStream('orders-web.txt.gz'),
);

A web ReadableStream as the source, a Node Writable as the destination, one promise for the whole job.

Common mistakes

Reading a locked stream

// Wrong
const reader = stream.getReader();
const reader2 = stream.getReader(); // TypeError: Invalid state: ReadableStream is locked

Only one reader at a time. Call reader.releaseLock() first, or use stream.tee() to split a stream into two independent copies.

Giving Response a stream of strings

// Wrong
const lines = ReadableStream.from(['Hi ', 'Asha']);
await new Response(lines).text(); // TypeError: Received non-Uint8Array chunk

Response expects bytes. Add .pipeThrough(new TextEncoderStream()) first, or collect the strings yourself with for await.

Quick recap

• Web streams (ReadableStream, WritableStream, TransformStream) are the standard streams used by browsers and fetch. They are globals in Node.
• Create readables with start or pull, or with ReadableStream.from().
• Read with getReader() and read(), or with for await.
• Chain with pipeThrough(); finish with pipeTo(). Both handle backpressure.
• TextEncoderStream, TextDecoderStream, CompressionStream and DecompressionStream are built in.
• Convert with Readable.toWeb / Readable.fromWeb and Writable.toWeb / Writable.fromWeb.
• pipeline() from node:stream/promises accepts web and Node streams together.