rules/interop.md
GitHubInterop with classic streams and Web Streams
The adapters were added in v26.1.0 and v24.20.0 and are at Stability 1. They need --experimental-stream-iter.
Classic stream.Readable → iter
from(readable)andpull(readable, ...)work directly, becauseReadable.prototypeimplements[Symbol.for('Stream.toAsyncStreamable')](). That method yieldsUint8Array[]batches drained from the internal buffer. Object-mode and encoded streams are normalized to bytes.fromReadable(readable)does the same explicitly. It also accepts duck-typed objects withread,pipe,destroy,onandremoveListener, and it caches the result per instance.Readable.prototype[Symbol.for('Stream.toAsyncStreamable')]exists even without the flag (observed on v26.13.0 and main). The docs say it requires the flag.
iter → classic stream.Readable
toReadable(asyncSource[, { highWaterMark = 65536, signal }])returns a byte-mode Readable, with each chunk pushed separately. Use it to feedstream.pipeline(), an HTTPres, or any API that expects a Readable.toReadableSync(syncSource[, { highWaterMark }])returns a Readable whoseread()pulls synchronously.- A non-Error failure reason is wrapped in an
ERR_FALSY_VALUE_REJECTIONorERR_OPERATION_FAILEDerror, with the original value on.reason.
iter → classic stream.Writable
fromWritable(writable[, { backpressure }])returns a Writer forpipeTo(). The policies are'strict'(the default),'unbounded'(recommended withpipeTo) and'drop-newest'.'drop-oldest'throwsERR_INVALID_ARG_VALUE. Its sync methods always returnfalseor-1. Object-mode writables are rejected. The result is cached per instance and policy.
Classic Writable API over an iter Writer
toWritable(writer)returns astream.Writablewhose_writetrieswriteSyncand thenwrite, and whose_finaltriesendSyncand thenend. Destroying it early callswriter.fail(). Use it to hand apush()writer or anfh.writer()to code that expects a Writable.
Web Streams
- A web
ReadableStream→ iter: pass it tofrom(). It is async iterable, and string chunks are encoded. - iter → web
ReadableStream: useReadable.toWeb(toReadable(source)). - iter → web
WritableStream: any object withwrite()is a Writer:There is no built-in web adapter.const w = ws.getWriter(); await pipeTo(source, { write: (c) => w.write(c), end: () => w.close(), fail: (r) => w.abort(r) });
Protocol symbols (on Stream, and as named exports)
| Symbol | Implement it to |
|---|---|
Symbol.for('Stream.toAsyncStreamable') |
let from() convert your object (it may return a string, bytes, an iterable, or a promise of one) |
Symbol.for('Stream.toStreamable') |
let fromSync() and from() convert your object synchronously |
Symbol.for('Stream.drainableProtocol') |
make a writer work with ondrain() (return null, or a promise) |
Symbol.for('Stream.broadcastProtocol') |
have Broadcast.from(obj) return your BroadcastChannel |
Symbol.for('Stream.shareProtocol'), Symbol.for('Stream.shareSyncProtocol') |
have Share.from()/SyncShare.fromSync() return your Share |
Using Symbol.for(...) lets a library take part in these protocols without importing node:stream/iter, so its
code still loads when the flag is off.