Iterable Streams API

Introduction

This document proposes the Iterable Streams API, a streaming interface designed around the following principles:

1. Streams are iterables: An async stream is an AsyncIterable<Uint8Array[]>; a sync stream is an Iterable<Uint8Array[]>. There is no custom stream class. Consumption uses for await...of and for...of.

2. Batched chunks: Iterables yield Uint8Array[] (arrays of chunks) rather than individual chunks, amortizing the cost of each async iteration tick.

3. Bytes only: All streams carry Uint8Array data exclusively. Strings are automatically UTF-8 encoded.

4. Pull-through transforms: Transform pipelines are lazy. No data flows until the consumer pulls.

5. Explicit backpressure: Backpressure is controlled by a configurable backpressure policy ("strict", "block", "drop-oldest", "drop-newest").

6. Clean sync/async separation: Synchronous and asynchronous APIs are fully separated.

7. Explicit multi-consumer: Sharing a stream among multiple consumers requires explicit opt-in via broadcast channel (push model) or shared source (pull model).

This specification is intended for use by web-interoperable runtimes as defined by WinterTC, though any ECMAScript-based runtime may implement it.

Copyright

© 2026 Ecma International

Permission under Ecma’s copyright to copy, modify, prepare derivative works of, and distribute this work, with or without modification, for any purpose and without fee or royalty is hereby granted, provided that you include the full text of this copyright notice on ALL copies of the work or portions thereof.

THIS WORK IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE DOCUMENT WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.

1. Scope

This proposal defines the Iterable Streams API, a bytes-only streaming interface built on the ECMAScript iteration protocols. It specifies:

• A Stream namespace providing factory functions for creating, transforming, consuming, and composing byte streams.

• A Writer interface for push-based data production with explicit backpressure.

• Transform pipeline semantics based on pull-through lazy evaluation.

• Multi-consumer patterns for sharing a single source across multiple consumers.

• Bidirectional duplex channels for full-duplex communication.

• Protocol symbols enabling user-defined objects to participate in streaming.

2. Conformance

A conforming implementation of this specification shall provide the namespace, interfaces, and functions listed herein. A conforming implementation shall also conform to [ECMASCRIPT] and [WEBIDL].

Conforming implementations must support AbortSignal and AbortController as defined in [DOM].

Note: AbortSignal and AbortController are the only normative dependency this specification has on the DOM Standard. They are required because ECMAScript does not yet define a language-level cancellation protocol. Should TC39 adopt such a protocol in the future, a subsequent revision of this specification may remove the DOM dependency in favor of the language-native mechanism.

3. Normative references

The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document.

4. Terms and definitions

For the purposes of this document, the terms and definitions given in [ECMASCRIPT], the DOM Standard [DOM], the Encoding Standard [ENCODING], and the following apply.

4.1. web-interoperable runtime

ECMAScript-based runtime environment as defined by WinterTC

4.2. batched chunks

an array of Uint8Array objects (Uint8Array[]) representing a group of byte chunks yielded as a single iteration step to amortize the cost of async iteration

4.3. backpressure policy

a BackpressurePolicy value controlling the behavior when an internal buffer is full

4.4. push stream

a stream created by push() consisting of a bonded Writer and async iterable pair, where data written to the writer flows to the iterable

4.5. pull pipeline

a lazy transform chain created by pull() or pullSync() that only processes data when the consumer iterates

4.6. broadcast channel

a push-model multi-consumer pattern where data written to a single Writer is delivered to all subscribed consumers

4.7. shared source

a pull-model multi-consumer pattern where a single source is consumed on-demand as multiple consumers pull data, with a shared buffer for slower consumers to catch up

5. Core concepts

5.1. Streams as iterables

In this API, a stream is not a custom class. It is a standard ECMAScript iterable. An async byte stream conforms to the AsyncIterable<Uint8Array[]> protocol, and a sync byte stream conforms to the Iterable<Uint8Array[]> protocol. Consumers iterate streams using for await...of or for...of.

5.2. Batched chunks

Every iteration step yields a Uint8Array[] (an array of one or more chunks) rather than a single Uint8Array. This batching amortizes the per-tick cost of async iteration across multiple chunks.

Consumers should iterate the inner array:

for await (const chunks of readable) {
  for (const chunk of chunks) {
    // Process individual Uint8Array chunk
  }
}

5.3. Backpressure

Backpressure is the mechanism by which a consumer signals to a producer that it should slow down. In this API, backpressure is managed through backpressure policies:

• **"strict"** (default): Catches producers that ignore backpressure. Properly awaited writes wait for buffer space; un-awaited writes exceeding the buffer limit cause a rejection. Both the slots buffer and pending writes queue are limited by highWaterMark.

• **"block"**: Async writes wait for buffer space. Sync writes return false when the buffer is full. The pending writes queue is unbounded.

• **"drop-oldest"**: Oldest buffered data is discarded to make room for new data. Writes never block.

• **"drop-newest"**: Incoming data is silently discarded when buffer is full. Writes never block.

The highWaterMark option controls the buffer size in slots (chunk batches), not bytes. It is clamped to a minimum of 1. Implementations may also apply a reasonable upper limit; the specific maximum is implementation-defined, but must be at least 1024.

5.4. Pull and push models

The pull model is fundamental; the push model builds on it by bonding a Writer to a pull-based iterable.

• Pull model: Data flows only when the consumer iterates, pulling through any transform chain back to the source. Created via pull(), from(), and share().

• Push model: A Writer bonded to a pull-based iterable, allowing a producer to write data that consumers pull via iteration. Created via push() and broadcast().

Transforms are strictly lazy in both models: no transform function executes until the consumer iterates.

5.5. Try-fallback pattern

The Writer interface provides synchronous variants of its write and end methods (writeSync(), writevSync(), endSync()) alongside the async versions. The intended usage is a try-fallback pattern: attempt the synchronous method first, and if it indicates failure, fall back to the async version. (fail() is unconditionally synchronous and does not participate in this pattern.)

For writeSync() and writevSync(), a return value of false indicates the synchronous attempt was not accepted. For endSync(), a return value of −1 indicates the same. In either case, the caller should fall back to the async method and await it:

// Try sync, fall back to async
if (!writer.writeSync(chunk)) {
  await writer.write(chunk);
}

// End with try-fallback
const n = writer.endSync();
if (n < 0) {
  await writer.end();
}

This pattern enables high-performance paths where synchronous writes succeed (e.g., buffer has space), while still handling backpressure correctly when they do not. The Writer synchronous methods never throw on backpressure; they return a failure indicator, leaving the caller to decide whether to await, retry, or drop. (SyncWriter has different semantics; see § 6.5 The SyncWriter interface.)

6. Web IDL definitions

6.1. BackpressurePolicy

enum BackpressurePolicy {
  "strict",
  "block",
  "drop-oldest",
  "drop-newest"
};

The BackpressurePolicy enum defines the backpressure policy options described in § 5.3 Backpressure.

6.2. Stream type aliases

typedef object ByteReadableStream;
typedef object SyncByteReadableStream;

A ByteReadableStream is an object conforming to the AsyncIterable<Uint8Array[]> protocol: it has a Symbol.asyncIterator method that returns an async iterator yielding batched chunks.

A SyncByteReadableStream is an object conforming to the Iterable<Uint8Array[]> protocol: it has a Symbol.iterator method that returns an iterator yielding batched chunks.

These are structural types defined by the ECMAScript iteration protocols, not interfaces with a prototype chain. The typedef object declaration is used because Web IDL cannot directly express parameterized iterable types as values. See the editorial note on any types for further discussion.

6.3. Options dictionaries

dictionary WriteOptions {
  AbortSignal signal;
};

dictionary PushStreamOptions {
  unsigned long highWaterMark = 4;
  BackpressurePolicy backpressure = "strict";
  AbortSignal signal;
};

dictionary PullOptions {
  AbortSignal signal;
};

dictionary PipeToOptions {
  AbortSignal signal;
  boolean preventClose = false;
  boolean preventFail = false;
};

dictionary PipeToSyncOptions {
  boolean preventClose = false;
  boolean preventFail = false;
};

dictionary ConsumeOptions {
  AbortSignal signal;
  [EnforceRange] unsigned long long limit;
};

dictionary ConsumeSyncOptions {
  [EnforceRange] unsigned long long limit;
};

dictionary TextConsumeOptions : ConsumeOptions {
  DOMString encoding = "utf-8";
};

dictionary TextConsumeSyncOptions : ConsumeSyncOptions {
  DOMString encoding = "utf-8";
};

This specification defines "utf-8" as the only normative value for the encoding and encoding members. Implementations may support additional encodings as defined by [ENCODING], but only "utf-8" is required for conformance. If an unsupported encoding is provided, the implementation must throw a RangeError.

dictionary MergeOptions {
  AbortSignal signal;
};

dictionary BroadcastOptions {
  unsigned long highWaterMark = 16;
  BackpressurePolicy backpressure = "strict";
  AbortSignal signal;
};

dictionary ShareOptions {
  unsigned long highWaterMark = 16;
  BackpressurePolicy backpressure = "strict";
  AbortSignal signal;
};

dictionary ShareSyncOptions {
  unsigned long highWaterMark = 16;
  BackpressurePolicy backpressure = "strict";
};

Note: The default highWaterMark for BroadcastOptions, ShareOptions, and ShareSyncOptions is 16, compared to 4 for PushStreamOptions and DuplexOptions. Multi-consumer patterns benefit from a larger buffer because the slowest consumer governs backpressure, so a larger buffer provides more headroom before fast consumers are stalled by a slow one.

dictionary DuplexDirectionOptions {
  unsigned long highWaterMark;
  BackpressurePolicy backpressure;
};

dictionary DuplexOptions {
  unsigned long highWaterMark = 4;
  BackpressurePolicy backpressure = "strict";
  DuplexDirectionOptions a;
  DuplexDirectionOptions b;
  AbortSignal signal;
};

dictionary TransformCallbackOptions {
  required AbortSignal signal;
};

callback StatelessTransformFn = any (sequence<Uint8Array>? chunks, TransformCallbackOptions options);
callback SyncStatelessTransformFn = any (sequence<Uint8Array>? chunks);

dictionary PushStreamResult {
  required Writer writer;
  required ByteReadableStream readable;
};

dictionary BroadcastResult {
  required Writer writer;
  required Broadcast broadcast;
};

6.4. The Writer interface

interface Writer {
  readonly attribute long? desiredSize;

  Promise<undefined> write((Uint8Array or USVString) chunk, optional WriteOptions options = {});
  Promise<undefined> writev(sequence<(Uint8Array or USVString)> chunks, optional WriteOptions options = {});
  boolean writeSync((Uint8Array or USVString) chunk);
  boolean writevSync(sequence<(Uint8Array or USVString)> chunks);

  Promise<unsigned long long> end(optional WriteOptions options = {});
  long long endSync();

  undefined fail(optional any reason);
};

The Writer interface is the API for producing data. See § 7.2 The Writer interface for full semantics.

Note: Writer is an interface, not a concrete class. Any object implementing this interface can serve as a writer. Implementations should support both Symbol.asyncDispose and Symbol.dispose (calling fail() with no argument), enabling both await using and using syntax.

6.5. The SyncWriter interface

interface SyncWriter {
  readonly attribute long? desiredSize;

  boolean write((Uint8Array or USVString) chunk);
  boolean writev(sequence<(Uint8Array or USVString)> chunks);
  unsigned long long end();
  undefined fail(optional any reason);
};

The SyncWriter interface is a synchronous interface for producing data. Like Writer, it is an interface, not a concrete class. Any object conforming to this interface can serve as a sync writer. Implementations of SyncWriter should support Symbol.dispose (calling fail() with no argument), enabling using syntax.

SyncWriter follows the same backpressure policies as Writer with adaptations for synchronous operation:

• With "block", write() and writev() always enqueue the chunk(s) and return true when the buffer has space, or enqueue and return false when the buffer is full. The false return is a backpressure signal; the data is still accepted, but the caller should slow down.

• With "strict", writes that exceed the buffer capacity throw a RangeError.

• With "drop-oldest" and "drop-newest", writes behave as described in § 5.3 Backpressure: the oldest or newest data is discarded respectively. Writes never fail.

• end() throws a TypeError if the writer is already closed or errored. Unlike endSync() which returns −1 as a fallback indicator, end() has no async counterpart to fall back to and throws on failure.

• fail() transitions the writer to the errored state. If the writer is already closed or errored, it is a no-op.

6.6. The Broadcast interface

interface Broadcast {
  readonly attribute unsigned long consumerCount;
  readonly attribute unsigned long bufferSize;

  ByteReadableStream push(any... args);

  undefined cancel(optional any reason);
};

The Broadcast interface is the consumer-facing side of a broadcast channel. The push() method accepts an optional sequence of transforms followed by an optional PullOptions dictionary, and returns a ByteReadableStream. See § 13.1 Broadcast for full semantics.

Note: Broadcast is an interface, not a concrete class. Any object conforming to this interface can serve as a broadcast. Implementations should support Symbol.dispose, calling cancel() with no argument, enabling using declarations.

6.7. The Share interface

interface Share {
  readonly attribute unsigned long consumerCount;
  readonly attribute unsigned long bufferSize;

  ByteReadableStream pull(any... args);

  undefined cancel(optional any reason);
};

The Share interface is the consumer-facing side of a shared source. The pull() method accepts an optional sequence of transforms followed by an optional PullOptions dictionary, and returns an object conforming to AsyncIterable<Uint8Array[]>. See § 13.2 Share for full semantics.

Note: Share is an interface, not a concrete class. Any object conforming to this interface can serve as a share. Implementations should support Symbol.dispose, calling cancel() with no argument.

6.8. The SyncShare interface

interface SyncShare {
  readonly attribute unsigned long consumerCount;
  readonly attribute unsigned long bufferSize;

  SyncByteReadableStream pull(any... args);

  undefined cancel(optional any reason);
};

The SyncShare interface is the synchronous counterpart of Share. pull() accepts an optional sequence of sync transforms and returns an object conforming to Iterable<Uint8Array[]>.

Note: Like Share, SyncShare is an interface, not a concrete class. Implementations should support Symbol.dispose, calling cancel() with no argument.

6.9. The DuplexChannel interface

interface DuplexChannel {
  readonly attribute Writer writer;
  readonly attribute ByteReadableStream readable;

  Promise<undefined> close();
};

The DuplexChannel interface represents one end of a bidirectional communication channel. The readable attribute is an object conforming to AsyncIterable<Uint8Array[]>.

Note: DuplexChannel is an interface, not a concrete class. Runtimes and applications may provide their own implementations (e.g., wrapping native sockets or WebSockets) as long as they conform to this interface. DuplexChannel implements Symbol.asyncDispose, enabling await using syntax for automatic cleanup.

6.10. The Stream namespace

[Exposed=*]
namespace Stream {
  /* Push stream creation */
  PushStreamResult push(any... args);

  /* Stream factories */
  ByteReadableStream from(any input);
  SyncByteReadableStream fromSync(any input);

  /* Pull pipelines */
  ByteReadableStream pull(any source, any... args);
  SyncByteReadableStream pullSync(any source, any... args);

  /* Pipe operations */
  Promise<unsigned long long> pipeTo(any source, any... args);
  unsigned long long pipeToSync(any source, any... args);

  /* Consumers */
  Promise<Uint8Array> bytes(any source, optional ConsumeOptions options = {});
  Uint8Array bytesSync(any source, optional ConsumeSyncOptions options = {});
  Promise<USVString> text(any source, optional TextConsumeOptions options = {});
  USVString textSync(any source, optional TextConsumeSyncOptions options = {});
  Promise<ArrayBuffer> arrayBuffer(any source, optional ConsumeOptions options = {});
  ArrayBuffer arrayBufferSync(any source, optional ConsumeSyncOptions options = {});
  Promise<sequence<Uint8Array>> array(any source, optional ConsumeOptions options = {});
  sequence<Uint8Array> arraySync(any source, optional ConsumeSyncOptions options = {});

  /* Utilities */
  StatelessTransformFn tap(any callback);
  SyncStatelessTransformFn tapSync(any callback);
  ByteReadableStream merge(any... args);
  Promise<boolean>? ondrain(any drainable);

  /* Multi-consumer */
  BroadcastResult broadcast(optional BroadcastOptions options = {});
  Share share(any source, optional ShareOptions options = {});
  SyncShare shareSync(any source, optional ShareSyncOptions options = {});

  /* Duplex */
  sequence<DuplexChannel> duplex(optional DuplexOptions options = {});
};

Note: Many methods in the Stream namespace accept variadic arguments where the final argument may be an options dictionary and preceding arguments are transforms. The argument parsing for each method is described in its respective section.

7. Push streams

7.1. Stream.push()

The returned readable is an async iterable yielding batched chunks. There is no sync variant of push() because push streams are inherently asynchronous.

Note: Transforms passed to push() are applied lazily when the consumer pulls, not when the producer writes.

7.2. The Writer interface

A Writer provides the interface for producing data. Implementations of Writer are returned by push(), broadcast(), and duplex(), but any object conforming to this interface can serve as a writer.

7.2.1. Writer.desiredSize

desiredSize reflects capacity in the slots buffer only; it does not account for writes waiting in the pending writes queue. When the backpressure policy is "block", a desiredSize of 0 means the slots buffer is full, regardless of how many additional writes are queued in the pending writes queue behind it. It is not a measurement of total queued items.

Note: Unlike the WHATWG Streams API, desiredSize is never negative. A value of 0 is the signal that the buffer is full; producers should await their writes or use ondrain() before writing more.

7.2.2. Writer.write()

7.2.3. Writer.writev()

7.2.4. Writer.writeSync() / Writer.writevSync()

The writevSync(chunks) method performs the same steps but enqueues the full batch as a single slot. Like writev(), the operation is all-or-nothing: it returns true only if all chunks are accepted, or false if none are. A return of false is the signal to use the try-fallback pattern and await writev().

7.2.5. Writer.end() / Writer.endSync()

A writer in the closing state has had end() called but has not yet fully drained its buffered data to the consumer.

Note: No assumption should be made about why endSync() returns −1. The writer may be errored, the buffer may not be empty, the underlying resource may not support synchronous close, or the implementation may simply not support it. The caller should always fall back to end().

7.2.6. Writer.fail()

Note: fail() is unconditionally synchronous. If called while the writer is closing, it short-circuits the graceful drain initiated by end().

7.2.7. Disposal

Implementations of Writer should support both Symbol.asyncDispose and Symbol.dispose:

• Symbol.asyncDispose: If the writer is open, calls fail() with no argument and returns a resolved promise. If the writer is closing (end was called, draining), returns the pending end promise, allowing the graceful drain to complete. If the writer is closed or errored, returns a resolved promise.

• Symbol.dispose: Calls fail() with no argument unconditionally (cannot wait for drain).

8. Stream factories

8.1. Stream.from()

Note: WHATWG ReadableStream objects implement Symbol.asyncIterator and are therefore accepted by step 6. However, ReadableStream yields individual chunks (not Uint8Array[] batches), so each chunk is normalized and wrapped into a single-element batch. No special-casing of ReadableStream is required or defined by this specification.

8.2. Stream.fromSync()

9. Pull pipelines

9.1. Stream.pull()

9.2. Stream.pullSync()

9.3. Transforms

Transforms come in two forms, distinguished by whether the value is a function or an object:

Stateless transforms are plain functions with the signature: (chunks, options) => result where chunks is Uint8Array[] | null and options is a TransformCallbackOptions. The function is called once per batch. When chunks is null, it is a flush signal indicating end-of-stream.

Stateful transforms are objects with a transform property whose value is a function with the signature: (source, options) => AsyncIterable where source is an AsyncIterable<Uint8Array[] | null> and options is a TransformCallbackOptions. The function receives the entire upstream source and returns an async iterable of output chunks.

Transform return values are flexible. A transform may return: null (no output), Uint8Array[] (a batch), a single Uint8Array, a USVString (UTF-8 encoded), an iterable or async iterable (flattened), or a promise (awaited, async only).

stateful₄( stateless₃( stateful₂( stateless₁( source ) ) ) )

10. Pipe operations

10.1. Stream.pipeTo()

10.2. Stream.pipeToSync()

11. Consumers

Consumer functions are terminal operations that collect an entire stream into memory. All consumers accept any input that from() can normalize. The optional limit parameter protects against unbounded memory growth; exceeding it throws a RangeError.

11.1. Stream.bytes() / Stream.bytesSync()

The bytesSync(source, options) method performs the same algorithm synchronously using fromSync() for normalization.

11.2. Stream.text() / Stream.textSync()

Note: The fatal: true default means invalid byte sequences throw a TypeError rather than being silently replaced.

The textSync(source, options) method performs the same algorithm synchronously.

11.3. Stream.arrayBuffer() / Stream.arrayBufferSync()

The arrayBufferSync(source, options) method performs the same algorithm synchronously.

11.4. Stream.array() / Stream.arraySync()

The arraySync(source, options) method performs the same algorithm synchronously.

12. Utilities

12.1. Stream.tap() / Stream.tapSync()

The tapSync(callback) method creates a synchronous tap transform.

Note: tap does not prevent the callback from mutating chunks in-place. The guarantee is only that the callback’s return value is ignored.

12.2. Stream.merge()

12.3. Stream.ondrain()

Note: await null evaluates to null, which is falsy. The pattern const canWrite = await Stream.ondrain(writer); if (!canWrite) return; works correctly even when the protocol is not supported.

13. Multi-consumer streams

13.1. Broadcast

13.1.1. Stream.broadcast()

13.1.2. Broadcast backpressure

Backpressure in a broadcast channel is governed entirely by the slowest consumer. Each consumer maintains a cursor into the shared circular buffer. The desiredSize of the broadcast’s Writer is determined by the consumer whose cursor is furthest behind: the consumer with the most unconsumed data.

Concretely:

• The shared buffer cannot overwrite entries that the slowest consumer has not yet read. The effective buffer capacity, from the writer’s perspective, is the distance between the write position and the slowest consumer’s cursor.

• When the slowest consumer falls behind and the buffer fills, the configured backpressure policy applies to the writer: "strict" rejects excess writes, "block" causes writes to wait, "drop-oldest" advances the slowest cursor (discarding unread data for that consumer), and "drop-newest" discards incoming writes.

• Faster consumers that have already read all available data will wait for the next write. They are never the bottleneck.

• When a slow consumer detaches (its iterator returns or throws), backpressure is immediately recalculated based on the remaining consumers. This may unblock pending writes if the detached consumer was the slowest.

• If there are no consumers, writes succeed up to the buffer capacity as governed by the backpressure policy. Data remains in the buffer and is available to consumers that attach before it is overwritten. Late-joining consumers begin reading from the oldest entry still in the buffer at the time they call push().

Note: Because a single slow consumer can stall all producers, callers should consider using "drop-oldest" or "drop-newest" policies when consumers may have widely varying consumption rates and the data is tolerant of loss.

13.1.3. Broadcast.push()

13.1.4. Broadcast.cancel()

The cancel(reason) method cancels all consumers. If reason is provided, each consumer sees it as an error; otherwise they see clean completion.

Implementations should support Symbol.dispose by calling cancel() with no argument.

13.2. Share

13.2.1. Stream.share()

13.2.2. Share buffering and backpressure

A shared source uses a shared buffer and per-consumer cursors in the same manner as a broadcast channel, with one key difference: data enters the buffer by being pulled from the upstream source rather than pushed by a writer.

• Each consumer maintains a cursor into the shared buffer. When a consumer pulls and its cursor points to data already in the buffer, it reads directly without pulling from the upstream source.

• When a consumer pulls and no data is available at its cursor position, the shared source pulls the next batch from the upstream source iterator, stores it in the shared buffer, and advances the cursor.

• Only one pull from the upstream source occurs at a time, regardless of how many consumers request data concurrently. If multiple consumers are waiting for the next batch, a single upstream pull satisfies all of them.

• The shared buffer is trimmed as all consumers advance past buffered entries. An entry is eligible for removal only when every active consumer’s cursor has moved beyond it.

• When the slowest consumer falls behind and the buffer reaches capacity, the configured backpressure policy determines what happens when a faster consumer attempts to pull new data from upstream. With "strict", the pull is rejected. The faster consumer receives an error indicating the buffer is full, but the consumer’s iterator remains valid and subsequent pulls may succeed once the slow consumer advances. With "block", the pull is blocked until the slowest consumer advances and frees buffer space. With "drop-oldest", the oldest entry is discarded (advancing the slowest cursor) to make room for the new upstream pull. With "drop-newest", the upstream pull result is discarded.

Note: A rejected pull under "strict" does not terminate the consumer’s iterator. Within the constraints of the async iterator protocol, the .next() call returns a rejected promise, but the iterator is not put into a "done" state. The consumer may retry by calling .next() again. However, if the consumer is using for await...of, the rejected promise will cause the loop to exit and the iterator to be closed via .return(). This is standard async iterator protocol behavior, not specific to this API.

• When a slow consumer detaches, the buffer may be trimmed and blocked consumers may be unblocked, just as with broadcast.

• If there are no consumers, no upstream pulls occur (the source is lazy).

13.2.3. Share.pull()

13.2.4. Share.cancel()

The cancel(reason) method cancels all consumers and closes the source iterator. Implementations should support Symbol.dispose by calling cancel() with no argument.

13.2.5. Stream.shareSync()

14. Duplex channels

14.1. Stream.duplex()

Example:

const [client, server] = Stream.duplex();
{
  await using conn = client;
  await conn.writer.write('Hello');
} // conn.close() called automatically

15. Protocol symbols

Protocol symbols allow user-defined objects to participate in the streaming API. All symbols are created via Symbol.for(), allowing third-party code to implement protocols without importing these symbols directly.

15.1. ToStreamable protocols

Symbol.for('Stream.toStreamable')

A method returning a synchronous streamable representation. The return value may be any type accepted by from() or fromSync(): a USVString, ArrayBuffer, ArrayBufferView, or an object with Symbol.iterator. Used by both sync and async paths.

Symbol.for('Stream.toAsyncStreamable')

A method returning (or returning a promise resolving to) an async streamable representation. Used by from() only (not by sync functions). When both protocols are present, async paths prefer toAsyncStreamable.

15.2. Multi-consumer protocols

Symbol.for('Stream.broadcastProtocol')

A method accepting an optional BroadcastOptions and returning a Broadcast object. Enables custom types to provide optimized broadcast implementations.

Symbol.for('Stream.shareProtocol')

A method accepting an optional ShareOptions and returning a Share object.

Symbol.for('Stream.shareSyncProtocol')

A method accepting an optional ShareSyncOptions and returning a SyncShare object.

15.3. Drainable protocol

Symbol.for('Stream.drainableProtocol')

A method returning null or a promise resolving to a boolean. Used by ondrain() to wait for backpressure to clear. Return values: null if drain is not applicable; promise resolving to true when ready; promise resolving to false if the writer closed; promise rejecting if the writer errored. Writer objects returned by push() and broadcast() automatically implement this protocol.

16. Abstract operations

16.1. Parse variadic transform arguments

Note: The convention across all variadic methods is that the options dictionary, when present, is always the final argument. Transforms precede it in definition order. For pipeTo() and pipeToSync(), the argument order is (transforms..., writer, options?): the writer is either the final argument (when no options are provided) or second-to-last (when options are provided), with any number of transforms preceding it.

16.2. Notify drain waiters

16.3. UTF-8 encode

Acknowledgements

The design of this API was informed by practical experience with the WHATWG Streams Standard [STREAMS], Node.js streams, and streaming patterns in server-side 5 JavaScript runtimes including Cloudflare Workers, Deno, and Bun.

enum BackpressurePolicy {
  "strict",
  "block",
  "drop-oldest",
  "drop-newest"
};

typedef object ByteReadableStream;
typedef object SyncByteReadableStream;

dictionary WriteOptions {
  AbortSignal signal;
};

dictionary PushStreamOptions {
  unsigned long highWaterMark = 4;
  BackpressurePolicy backpressure = "strict";
  AbortSignal signal;
};

dictionary PullOptions {
  AbortSignal signal;
};

dictionary PipeToOptions {
  AbortSignal signal;
  boolean preventClose = false;
  boolean preventFail = false;
};

dictionary PipeToSyncOptions {
  boolean preventClose = false;
  boolean preventFail = false;
};

dictionary ConsumeOptions {
  AbortSignal signal;
  [EnforceRange] unsigned long long limit;
};

dictionary ConsumeSyncOptions {
  [EnforceRange] unsigned long long limit;
};

dictionary TextConsumeOptions : ConsumeOptions {
  DOMString encoding = "utf-8";
};

dictionary TextConsumeSyncOptions : ConsumeSyncOptions {
  DOMString encoding = "utf-8";
};

dictionary MergeOptions {
  AbortSignal signal;
};

dictionary BroadcastOptions {
  unsigned long highWaterMark = 16;
  BackpressurePolicy backpressure = "strict";
  AbortSignal signal;
};

dictionary ShareOptions {
  unsigned long highWaterMark = 16;
  BackpressurePolicy backpressure = "strict";
  AbortSignal signal;
};

dictionary ShareSyncOptions {
  unsigned long highWaterMark = 16;
  BackpressurePolicy backpressure = "strict";
};

dictionary DuplexDirectionOptions {
  unsigned long highWaterMark;
  BackpressurePolicy backpressure;
};

dictionary DuplexOptions {
  unsigned long highWaterMark = 4;
  BackpressurePolicy backpressure = "strict";
  DuplexDirectionOptions a;
  DuplexDirectionOptions b;
  AbortSignal signal;
};

dictionary TransformCallbackOptions {
  required AbortSignal signal;
};

callback StatelessTransformFn = any (sequence<Uint8Array>? chunks, TransformCallbackOptions options);
callback SyncStatelessTransformFn = any (sequence<Uint8Array>? chunks);

dictionary PushStreamResult {
  required Writer writer;
  required ByteReadableStream readable;
};

dictionary BroadcastResult {
  required Writer writer;
  required Broadcast broadcast;
};

interface Writer {
  readonly attribute long? desiredSize;

  Promise<undefined> write((Uint8Array or USVString) chunk, optional WriteOptions options = {});
  Promise<undefined> writev(sequence<(Uint8Array or USVString)> chunks, optional WriteOptions options = {});
  boolean writeSync((Uint8Array or USVString) chunk);
  boolean writevSync(sequence<(Uint8Array or USVString)> chunks);

  Promise<unsigned long long> end(optional WriteOptions options = {});
  long long endSync();

  undefined fail(optional any reason);
};

interface SyncWriter {
  readonly attribute long? desiredSize;

  boolean write((Uint8Array or USVString) chunk);
  boolean writev(sequence<(Uint8Array or USVString)> chunks);
  unsigned long long end();
  undefined fail(optional any reason);
};

interface Broadcast {
  readonly attribute unsigned long consumerCount;
  readonly attribute unsigned long bufferSize;

  ByteReadableStream push(any... args);

  undefined cancel(optional any reason);
};

interface Share {
  readonly attribute unsigned long consumerCount;
  readonly attribute unsigned long bufferSize;

  ByteReadableStream pull(any... args);

  undefined cancel(optional any reason);
};

interface SyncShare {
  readonly attribute unsigned long consumerCount;
  readonly attribute unsigned long bufferSize;

  SyncByteReadableStream pull(any... args);

  undefined cancel(optional any reason);
};

interface DuplexChannel {
  readonly attribute Writer writer;
  readonly attribute ByteReadableStream readable;

  Promise<undefined> close();
};

[Exposed=*]
namespace Stream {
  /* Push stream creation */
  PushStreamResult push(any... args);

  /* Stream factories */
  ByteReadableStream from(any input);
  SyncByteReadableStream fromSync(any input);

  /* Pull pipelines */
  ByteReadableStream pull(any source, any... args);
  SyncByteReadableStream pullSync(any source, any... args);

  /* Pipe operations */
  Promise<unsigned long long> pipeTo(any source, any... args);
  unsigned long long pipeToSync(any source, any... args);

  /* Consumers */
  Promise<Uint8Array> bytes(any source, optional ConsumeOptions options = {});
  Uint8Array bytesSync(any source, optional ConsumeSyncOptions options = {});
  Promise<USVString> text(any source, optional TextConsumeOptions options = {});
  USVString textSync(any source, optional TextConsumeSyncOptions options = {});
  Promise<ArrayBuffer> arrayBuffer(any source, optional ConsumeOptions options = {});
  ArrayBuffer arrayBufferSync(any source, optional ConsumeSyncOptions options = {});
  Promise<sequence<Uint8Array>> array(any source, optional ConsumeOptions options = {});
  sequence<Uint8Array> arraySync(any source, optional ConsumeSyncOptions options = {});

  /* Utilities */
  StatelessTransformFn tap(any callback);
  SyncStatelessTransformFn tapSync(any callback);
  ByteReadableStream merge(any... args);
  Promise<boolean>? ondrain(any drainable);

  /* Multi-consumer */
  BroadcastResult broadcast(optional BroadcastOptions options = {});
  Share share(any source, optional ShareOptions options = {});
  SyncShare shareSync(any source, optional ShareSyncOptions options = {});

  /* Duplex */
  sequence<DuplexChannel> duplex(optional DuplexOptions options = {});
};