skip to content

Your team's shared Node.js library streams data to Node 24 services and to browser code: should its public API return a Node Readable or a web ReadableStream, and why?

level: principalimportance: nice to knowfreq 25%

answer

  1. who consumes it, and where
  2. WHATWG standard versus Node ecosystem
  3. toWeb and fromWeb at the boundary
  4. both are async iterable

basics

~20 s

If browsers or other runtimes consume it, return a web ReadableStream, the standard type fetch bodies use, and let Node callers convert with Readable.fromWeb(). If only Node code consumes it, a Node Readable fits its ecosystem better.

solid answer

~40 s

It depends on who consumes the stream. A **web `ReadableStream`** is the WHATWG standard: global in Node since v18, stable in `node:stream/web` since v21, the type a `fetch()` response body already is, and available in browsers. A **Node `Readable`** fits Node's own ecosystem: `pipe()`, object mode, and the fs, http and zlib APIs. For a library shared with browser code, I would return a web `ReadableStream` and let Node callers wrap it with `Readable.fromWeb()`; the converters `Readable.toWeb()` and `Readable.fromWeb()` were marked stable in Node 24.0.0. Both types are async iterable, so many callers can just `for await` either one. What I would avoid is exposing both types inconsistently, which makes callers guess which cancellation and error semantics apply.

go deeper

for a junior

Know that Node has its own Readable and also supports the web ReadableStream that fetch() returns, and that they can be converted.

for a middle

Name Readable.toWeb() and Readable.fromWeb(), and explain that both kinds are async iterable but differ in cancellation and object mode.

for a senior

Choose a stream type per call site, convert once at the boundary, and debug mismatches such as a fetch body passed where a Node stream was expected.

for a principal

Own the library contract: pick one documented return type based on consumers, decide whether an async iterable is a better neutral contract, and set the minimum Node version.

## The decision A **shared library** that produces data incrementally (decoded records, an export, a proxied response body) has to pick the stream type its public API returns. In Node 24 there are two real options, and the choice is lasting: changing the return type later breaks every caller. | | Node `Readable` (`node:stream`) | Web `ReadableStream` (`node:stream/web`, global) | |---|---|---| | Standard | Node-specific API | WHATWG Streams Standard | | Where it runs | Node | Node, browsers, other JavaScript runtimes | | Status in Node 24 | stable core API | stable since v21.0.0; global since v18.0.0 | | Produced by | fs, net, http, zlib, child processes | `fetch()` response bodies, `Blob.stream()`, web APIs | | Value types | byte mode or object mode | any value; byte streams via `type: 'bytes'` | | Consumption | `pipe()`, `'data'`, `for await`, `stream.pipeline` | readers, `pipeTo`/`pipeThrough`, `for await`, `stream.pipeline` | | Cancellation | `destroy()`; `break` destroys unless `destroyOnReturn: false` | `cancel()`; `break` cancels unless `values({ preventCancel: true })` | ## Arguments for a web ReadableStream - **Portability**: the same code runs where the browser bundle runs, with no polyfill of Node's stream module. - **It is already what callers have**: the body of a `fetch()` response is a `ReadableStream<Uint8Array>`, so a library that proxies or transforms HTTP bodies avoids converting twice. - **Node accepts it widely**: `stream.pipeline()` and `stream.finished()` accept web streams, `node:stream/consumers` functions such as `text()` and `json()` accept both kinds, and `Readable.fromWeb()` wraps one for code that needs a Node stream. ## Arguments for a Node Readable - **Ecosystem fit**: if every caller is a Node service that pipes into files, sockets or zlib, a Node `Readable` plugs in directly. - **Object mode and familiarity**: object-mode semantics, `highWaterMark` in items and the long-documented event model are what most Node engineers already know. - **Less wrapping on hot paths**: each conversion adds an adapter layer between the two buffering models, which is worth measuring rather than assuming on a high-throughput path. ## Converting at the boundary Node 24 ships converters on each class: 1. `Readable.toWeb(readable)` returns a `ReadableStream`; `Readable.fromWeb(readableStream, options)` returns a `Readable` and accepts `objectMode`, `highWaterMark`, `encoding` and `signal`. 2. `Writable.toWeb()` / `Writable.fromWeb()` and `Duplex.toWeb()` / `Duplex.fromWeb()` do the same for the other classes. 3. All six were added in v17.0.0 and marked **stable in v24.0.0**; `Readable.toWeb()` gained a `type: 'bytes'` option in v24.14.0, and `Duplex.toWeb()` a `readableType` option in v24.15.0. Convert once, at the library's edge, rather than back and forth inside it. ## A decision procedure a lead can apply - **Who consumes it?** Any browser, edge or non-Node consumer: return a web `ReadableStream`. Node only: a Node `Readable` is reasonable. - **What does it carry?** Records rather than bytes: decide whether callers want object-mode semantics or would be just as happy with an async iterable. - **Could an async iterable be the contract?** Both stream types are async iterable, and `Readable.from()` turns any async iterable into a Node stream. Returning `AsyncIterable<T>` keeps the library neutral, at the cost of losing explicit stream methods. - **Document cancellation**: state whether abandoning iteration cancels the upstream work, since Node streams are destroyed and web streams are cancelled by default when a `for await` loop exits early. - **Accept liberally, return one type**: inputs can take either kind (normalising with `Readable.fromWeb()` or `Readable.toWeb()`), but the return type should be one documented type. ## Mistakes that show up after release - Handing a `fetch()` body to code that calls `.pipe()` or listens for `'data'`: a web stream has neither, so the call fails at run time. - Converting an object-mode `Readable` with `Readable.toWeb()` and documenting the result as bytes: the web stream carries whatever values the Node stream emitted. - Converting back and forth inside the library, which adds an adapter layer per hop and makes errors harder to trace. - Leaving cancellation undocumented, so a caller's early exit keeps upstream work running, or stops it unexpectedly. ## Across release lines The Node 26 docs show the same converters and list the stable marking of `Readable.fromWeb()` and `Readable.toWeb()` as also backported to v22.17.0. The decision above does not depend on that release, but a library supporting Node 22 should check that its minimum version has the stable converters.

  • How does early exit from for await differ between a Node Readable and a web ReadableStream?
    Both clean up by default. Leaving the loop destroys a Node `Readable` unless you iterate `readable.iterator({ destroyOnReturn: false })`, and cancels a web `ReadableStream` unless you iterate `stream.values({ preventCancel: true })`. A library should document which one callers get, because cancellation usually propagates to the upstream work.
  • A Node service receives the web stream from fetch() and must write it to a file. What is the simplest correct wiring?
    Pass the body straight to `stream.pipeline()` from `node:stream/promises` with an `fs.createWriteStream()` destination; pipeline accepts web streams directly. Alternatively wrap it with `Readable.fromWeb(body)` first when the rest of the code expects a Node `Readable`. Error handling and cleanup across the chain are covered in the backpressure lesson.

  • Web streams are still experimental in Node, so libraries should avoid them.
  • A Node Readable runs unchanged in the browser.
  • Readable.toWeb() copies the whole stream into memory first.
  • A library should return both stream types depending on a flag.
  • for await works only on Node streams, not on web streams.

Assumes Node.js 24: web streams are stable since v21.0.0 and global since v18.0.0, and the toWeb/fromWeb converters were marked stable in v24.0.0.