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?
answer
- who consumes it, and where
- WHATWG standard versus Node ecosystem
- toWeb and fromWeb at the boundary
- both are async iterable
basics
~20 sIf 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 sIt 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
Know that Node has its own Readable and also supports the web ReadableStream that fetch() returns, and that they can be converted.
Name Readable.toWeb() and Readable.fromWeb(), and explain that both kinds are async iterable but differ in cancellation and object mode.
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.
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.