Group: WHATWG
H1: Streams
Shortname: streams
Text Macro: TWITTER streamsstandard
Text Macro: LATESTRD 2026-08
Abstract: This specification provides APIs for creating, composing, and consuming streams of data
Abstract: that map efficiently to low-level I/O primitives.
Translation: ja https://triple-underscore.github.io/Streams-ja.html
Translation: zh-Hans https://htmlspecs.com/streams/
Translation: ko https://ko.htmlspecs.com/streams/
!Demos: streams.spec.whatwg.org/demos
Indent: 1
Markup Shorthands: markdown yes

spec:webidl; type:dfn; text:resolve
spec:webidl; type:dfn; text:new
spec:infra; type:dfn; text:list
spec:html; type:dfn; text:entangle
spec:html; type:dfn; text:message port post message steps
spec:html; type:dfn; text:port message queue

urlPrefix: https://tc39.es/ecma262/; spec: ECMASCRIPT
 type: interface
  text: ArrayBuffer; url: #sec-arraybuffer-objects
  text: DataView; url: #sec-dataview-objects
  text: SharedArrayBuffer; url: #sec-sharedarraybuffer-objects
  text: Uint8Array; url: #sec-typedarray-objects
 type: dfn
  text: abstract operation; url: #sec-algorithm-conventions-abstract-operations
  text: array; url: #sec-array-objects
  text: async generator; url: #sec-asyncgenerator-objects
  text: async iterable; url: #sec-asynciterable-interface
  text: internal slot; url: #sec-object-internal-methods-and-internal-slots
  text: iterable; url: #sec-iterable-interface
  text: realm; url: #sec-code-realms
  text: the current Realm; url: #current-realm
  text: the typed array constructors table; url: #table-49
  text: typed array; url: #sec-typedarray-objects
  url: sec-ecmascript-language-types-bigint-type
   text: is a BigInt
   text: is not a BigInt
  url: sec-ecmascript-language-types-boolean-type
   text: is a Boolean
   text: is not a Boolean
  url: sec-ecmascript-language-types-number-type
   text: is a Number
   text: is not a Number
  url: sec-ecmascript-language-types-string-type
   text: is a String
   text: is not a String
  url: sec-ecmascript-language-types-symbol-type
   text: is a Symbol
   text: is not a Symbol
  url: sec-object-type
   text: is an Object
   text: is not an Object
 type: abstract-op
  text: IsInteger; url: #sec-isinteger
 text: TypeError; url: #sec-native-error-types-used-in-this-standard-typeerror; type: exception
 text: map; url: #sec-array.prototype.map; type: method; for: Array.prototype

Introduction

Model

Readable streams

Writable streams

Transform streams

Pipe chains and backpressure

Internal queues and queuing strategies

Locking

Under the covers, these high-level operations actually use a reader or writer themselves.

Conventions

The reasons for the usage of these foreign JavaScript specification conventions are largely historical. We urge you to avoid following our example when writing your own web specifications. In this specification, all numbers are represented as double-precision 64-bit IEEE 754 floating point values (like the JavaScript [=Number type=] or Web IDL {{unrestricted double}} type), and all arithmetic operations performed on them must be done in the standard way for such values. This is particularly important for the data structure described in [[#queue-with-sizes]]. [[!IEEE-754]]

Readable streams

Using readable streams

The {{ReadableStream}} class

Interface definition

Internal slots

The underlying source API

start(controller)

A function that is called immediately during creation of the {{ReadableStream}}.

Typically this is used to adapt a [=push source=] by setting up relevant event listeners, as in the example of [[#example-rs-push-no-backpressure]], or to acquire access to a [=pull source=], as in [[#example-rs-pull]].

If this setup process is asynchronous, it can return a promise to signal success or failure; a rejected promise will error the stream. Any thrown exceptions will be re-thrown by the {{ReadableStream()}} constructor.

pull(controller)

A function that is called whenever the stream's [=internal queue=] of chunks becomes not full, i.e. whenever the queue's [=desired size to fill a stream's internal queue|desired size=] becomes positive. Generally, it will be called repeatedly until the queue reaches its [=high water mark=] (i.e. until the desired size becomes non-positive).

For [=push sources=], this can be used to resume a paused flow, as in [[#example-rs-push-backpressure]]. For [=pull sources=], it is used to acquire new [=chunks=] to enqueue into the stream, as in [[#example-rs-pull]].

This function will not be called until {{UnderlyingSource/start|start()}} successfully completes. Additionally, it will only be called repeatedly if it enqueues at least one chunk or fulfills a BYOB request; a no-op {{UnderlyingSource/pull|pull()}} implementation will not be continually called.

If the function returns a promise, then it will not be called again until that promise fulfills. (If the promise rejects, the stream will become errored.) This is mainly used in the case of pull sources, where the promise returned represents the process of acquiring a new chunk. Throwing an exception is treated the same as returning a rejected promise.

cancel(reason)

A function that is called whenever the [=consumer=] [=cancel a readable stream|cancels=] the stream, via {{ReadableStream/cancel()|stream.cancel()}} or {{ReadableStreamGenericReader/cancel()|reader.cancel()}}. It takes as its argument the same value as was passed to those methods by the consumer.

Readable streams can additionally be canceled under certain conditions during [=piping=]; see the definition of the {{ReadableStream/pipeTo()}} method for more details.

For all streams, this is generally used to release access to the underlying resource; see for example [[#example-rs-push-no-backpressure]].

If the shutdown process is asynchronous, it can return a promise to signal success or failure; the result will be communicated via the return value of the cancel() method that was called. Throwing an exception is treated the same as returning a rejected promise.

Even if the cancelation process fails, the stream will still close; it will not be put into an errored state. This is because a failure in the cancelation process doesn't matter to the consumer's view of the stream, once they've expressed disinterest in it by canceling. The failure is only communicated to the immediate caller of the corresponding method.

This is different from the behavior of the {{UnderlyingSink/close}} and {{UnderlyingSink/abort}} options of a {{WritableStream}}'s [=underlying sink=], which upon failure put the corresponding {{WritableStream}} into an errored state. Those correspond to specific actions the [=producer=] is requesting and, if those actions fail, they indicate something more persistently wrong.

type (byte streams only)

Can be set to "bytes" to signal that the constructed {{ReadableStream}} is a readable byte stream. This ensures that the resulting {{ReadableStream}} will successfully be able to vend [=BYOB readers=] via its {{ReadableStream/getReader()}} method. It also affects the |controller| argument passed to the {{UnderlyingSource/start|start()}} and {{UnderlyingSource/pull|pull()}} methods; see below.

For an example of how to set up a readable byte stream, including using the different controller interface, see [[#example-rbs-push]].

Setting any value other than "{{ReadableStreamType/bytes}}" or undefined will cause the {{ReadableStream()}} constructor to throw an exception.

autoAllocateChunkSize (byte streams only)

Can be set to a positive integer to cause the implementation to automatically allocate buffers for the underlying source code to write into. In this case, when a [=consumer=] is using a [=default reader=], the stream implementation will automatically allocate an {{ArrayBuffer}} of the given size, so that {{ReadableByteStreamController/byobRequest|controller.byobRequest}} is always present, as if the consumer was using a [=BYOB reader=].

This is generally used to cut down on the amount of code needed to handle consumers that use default readers, as can be seen by comparing [[#example-rbs-push]] without auto-allocation to [[#example-rbs-pull]] with auto-allocation.

Constructor, methods, and properties

stream = new {{ReadableStream/constructor(underlyingSource, strategy)|ReadableStream}}(underlyingSource[, strategy])

Creates a new {{ReadableStream}} wrapping the provided [=underlying source=]. See [[#underlying-source-api]] for more details on the underlyingSource argument.

The |strategy| argument represents the stream's [=queuing strategy=], as described in [[#qs-api]]. If it is not provided, the default behavior will be the same as a {{CountQueuingStrategy}} with a [=high water mark=] of 1.

stream = {{ReadableStream/from(asyncIterable)|ReadableStream.from}}(asyncIterable)

Creates a new {{ReadableStream}} wrapping the provided [=iterable=] or [=async iterable=].

This can be used to adapt various kinds of objects into a [=readable stream=], such as an [=array=], an [=async generator=], or a Node.js readable stream.

isLocked = stream.{{ReadableStream/locked}}

Returns whether or not the readable stream is [=locked to a reader=].

await stream.{{ReadableStream/cancel(reason)|cancel}}([ reason ])

[=cancel a readable stream|Cancels=] the stream, signaling a loss of interest in the stream by a consumer. The supplied reason argument will be given to the underlying source's {{UnderlyingSource/cancel|cancel()}} method, which might or might not use it.

The returned promise will fulfill if the stream shuts down successfully, or reject if the underlying source signaled that there was an error doing so. Additionally, it will reject with a {{TypeError}} (without attempting to cancel the stream) if the stream is currently [=locked to a reader|locked=].

reader = stream.{{ReadableStream/getReader(options)|getReader}}()

Creates a {{ReadableStreamDefaultReader}} and [=locked to a reader|locks=] the stream to the new reader. While the stream is locked, no other reader can be acquired until this one is [=release a read lock|released=].

This functionality is especially useful for creating abstractions that desire the ability to consume a stream in its entirety. By getting a reader for the stream, you can ensure nobody else can interleave reads with yours or cancel the stream, which would interfere with your abstraction.

reader = stream.{{ReadableStream/getReader(options)|getReader}}({ {{ReadableStreamGetReaderOptions/mode}}: "{{ReadableStreamReaderMode/byob}}" })

Creates a {{ReadableStreamBYOBReader}} and [=locked to a reader|locks=] the stream to the new reader.

This call behaves the same way as the no-argument variant, except that it only works on [=readable byte streams=], i.e. streams which were constructed specifically with the ability to handle "bring your own buffer" reading. The returned [=BYOB reader=] provides the ability to directly read individual [=chunks=] from the stream via its {{ReadableStreamBYOBReader/read()}} method, into developer-supplied buffers, allowing more precise control over allocation.

readable = stream.{{ReadableStream/pipeThrough(transform, options)|pipeThrough}}({ {{ReadableWritablePair/writable}}, {{ReadableWritablePair/readable}} }[, { {{StreamPipeOptions/preventClose}}, {{StreamPipeOptions/preventAbort}}, {{StreamPipeOptions/preventCancel}}, {{StreamPipeOptions/signal}} }])

Provides a convenient, chainable way of [=piping=] this [=readable stream=] through a [=transform stream=] (or any other { writable, readable } pair). It simply pipes the stream into the writable side of the supplied pair, and returns the readable side for further use.

Piping a stream will [=locked to a reader|lock=] it for the duration of the pipe, preventing any other consumer from acquiring a reader.

await stream.{{ReadableStream/pipeTo(destination, options)|pipeTo}}(destination[, { {{StreamPipeOptions/preventClose}}, {{StreamPipeOptions/preventAbort}}, {{StreamPipeOptions/preventCancel}}, {{StreamPipeOptions/signal}} }])

[=piping|Pipes=] this [=readable stream=] to a given [=writable stream=] |destination|. The way in which the piping process behaves under various error conditions can be customized with a number of passed options. It returns a promise that fulfills when the piping process completes successfully, or rejects if any errors were encountered. Piping a stream will [=locked to a reader|lock=] it for the duration of the pipe, preventing any other consumer from acquiring a reader. Errors and closures of the source and destination streams propagate as follows: * An error in this source [=readable stream=] will [=abort a writable stream|abort=] |destination|, unless {{StreamPipeOptions/preventAbort}} is truthy. The returned promise will be rejected with the source's error, or with any error that occurs during aborting the destination. * An error in |destination| will [=cancel a readable stream|cancel=] this source [=readable stream=], unless {{StreamPipeOptions/preventCancel}} is truthy. The returned promise will be rejected with the destination's error, or with any error that occurs during canceling the source. * When this source [=readable stream=] closes, |destination| will be closed, unless {{StreamPipeOptions/preventClose}} is truthy. The returned promise will be fulfilled once this process completes, unless an error is encountered while closing the destination, in which case it will be rejected with that error. * If |destination| starts out closed or closing, this source [=readable stream=] will be [=cancel a readable stream|canceled=], unless {{StreamPipeOptions/preventCancel}} is true. The returned promise will be rejected with an error indicating piping to a closed stream failed, or with any error that occurs during canceling the source.

The {{StreamPipeOptions/signal}} option can be set to an {{AbortSignal}} to allow aborting an ongoing pipe operation via the corresponding {{AbortController}}. In this case, this source [=readable stream=] will be [=cancel a readable stream|canceled=], and |destination| [=abort a writable stream|aborted=], unless the respective options {{StreamPipeOptions/preventCancel}} or {{StreamPipeOptions/preventAbort}} are set.

[branch1, branch2] = stream.{{ReadableStream/tee()|tee}}()

[=tee a readable stream|Tees=] this readable stream, returning a two-element array containing the two resulting branches as new {{ReadableStream}} instances.

Teeing a stream will [=locked to a reader|lock=] it, preventing any other consumer from acquiring a reader. To [=cancel a readable stream|cancel=] the stream, cancel both of the resulting branches; a composite cancellation reason will then be propagated to the stream's [=underlying source=].

If this stream is a [=readable byte stream=], then each branch will receive its own copy of each [=chunk=]. If not, then the chunks seen in each branch will be the same object. If the chunks are not immutable, this could allow interference between the two branches.

Asynchronous iteration

for await (const chunk of stream) { ... }

for await (const chunk of stream.values({ {{ReadableStreamIteratorOptions/preventCancel}}: true })) { ... }

Asynchronously iterates over the [=chunks=] in the stream's internal queue.

Asynchronously iterating over the stream will [=locked to a reader|lock=] it, preventing any other consumer from acquiring a reader. The lock will be released if the async iterator's `return()` method is called, e.g. by `break`ing out of the loop.

By default, calling the async iterator's `return()` method will also [=cancel a readable stream|cancel=] the stream. To prevent this, use the stream's `values()` method, passing true for the {{ReadableStreamIteratorOptions/preventCancel}} option.

Transfer via `postMessage()`

destination.postMessage(rs, { transfer: [rs] });

Sends a {{ReadableStream}} to another frame, window, or worker.

The transferred stream can be used exactly like the original. The original will become [=locked to a reader|locked=] and no longer directly usable.

The {{ReadableStreamGenericReader}} mixin

Mixin definition

Internal slots

Methods and properties

The {{ReadableStreamDefaultReader}} class

Interface definition

Internal slots

Constructor, methods, and properties

reader = new {{ReadableStreamDefaultReader(stream)|ReadableStreamDefaultReader}}(|stream|)

This is equivalent to calling |stream|.{{ReadableStream/getReader()}}.

await reader.{{ReadableStreamGenericReader/closed}}

Returns a promise that will be fulfilled when the stream becomes closed, or rejected if the stream ever errors or the reader's lock is [=release a read lock|released=] before the stream finishes closing.

await reader.{{ReadableStreamGenericReader/cancel(reason)|cancel}}([ reason ])

If the reader is [=active reader|active=], behaves the same as |stream|.{{ReadableStream/cancel(reason)|cancel}}(reason).

{ value, done } = await reader.{{ReadableStreamDefaultReader/read()|read}}()

Returns a promise that allows access to the next [=chunk=] from the stream's internal queue, if available.

• If the chunk does become available, the promise will be fulfilled with an object of the form { value: theChunk, done: false }.
• If the stream becomes closed, the promise will be fulfilled with an object of the form { value: undefined, done: true }.
• If the stream becomes errored, the promise will be rejected with the relevant error.

If reading a chunk causes the queue to become empty, more data will be pulled from the [=underlying source=].

reader.{{ReadableStreamDefaultReader/releaseLock()|releaseLock}}()

[=release a read lock|Releases the reader's lock=] on the corresponding stream. After the lock is released, the reader is no longer [=active reader|active=]. If the associated stream is errored when the lock is released, the reader will appear errored in the same way from now on; otherwise, the reader will appear closed.

If the reader's lock is released while it still has pending read requests, then the promises returned by the reader's {{ReadableStreamDefaultReader/read()}} method are immediately rejected with a {{TypeError}}. Any unread chunks remain in the stream's [=internal queue=] and can be read later by acquiring a new reader.

The {{ReadableStreamBYOBReader}} class

Interface definition

Internal slots

The [=read-into request/close steps=] take a [=chunk=] so that it can return the backing memory to the caller if possible. For example, {{ReadableStreamBYOBReader/read()|byobReader.read(chunk)}} will fulfill with { value: newViewOnSameMemory, done: true } for closed streams. If the stream is [=cancel a readable stream|canceled=], the backing memory is discarded and {{ReadableStreamBYOBReader/read()|byobReader.read(chunk)}} fulfills with the more traditional { value: undefined, done: true } instead.

Constructor, methods, and properties

reader = new {{ReadableStreamBYOBReader(stream)|ReadableStreamBYOBReader}}(|stream|)

This is equivalent to calling |stream|.{{ReadableStream/getReader}}({ {{ReadableStreamGetReaderOptions/mode}}: "{{ReadableStreamReaderMode/byob}}" }).

await reader.{{ReadableStreamGenericReader/closed}}

Returns a promise that will be fulfilled when the stream becomes closed, or rejected if the stream ever errors or the reader's lock is [=release a read lock|released=] before the stream finishes closing.

await reader.{{ReadableStreamGenericReader/cancel(reason)|cancel}}([ reason ])

If the reader is [=active reader|active=], behaves the same |stream|.{{ReadableStream/cancel(reason)|cancel}}(reason).

{ value, done } = await reader.{{ReadableStreamBYOBReader/read()|read}}(view[, { {{ReadableStreamBYOBReaderReadOptions/min}} }])

Attempts to read bytes into |view|, and returns a promise resolved with the result:

• If the chunk does become available, the promise will be fulfilled with an object of the form { value: newView, done: false }. In this case, |view| will be [=ArrayBuffer/detached=] and no longer usable, but newView will be a new view (of the same type) onto the same backing memory region, with the chunk's data written into it.
• If the stream becomes closed, the promise will be fulfilled with an object of the form { value: newView, done: true }. In this case, |view| will be [=ArrayBuffer/detached=] and no longer usable, but newView will be a new view (of the same type) onto the same backing memory region, with no modifications, to ensure the memory is returned to the caller.
• If the reader is [=cancel a readable stream|canceled=], the promise will be fulfilled with an object of the form { value: undefined, done: true }. In this case, the backing memory region of |view| is discarded and not returned to the caller.
• If the stream becomes errored, the promise will be rejected with the relevant error.

If reading a chunk causes the queue to become empty, more data will be pulled from the [=underlying source=].

If {{ReadableStreamBYOBReaderReadOptions/min}} is given, then the promise will only be fulfilled as soon as the given minimum number of elements are available. Here, the "number of elements" is given by newView's length (for typed arrays) or newView's byteLength (for {{DataView}}s). If the stream becomes closed, then the promise is fulfilled with the remaining elements in the stream, which might be fewer than the initially requested amount. If not given, then the promise resolves when at least one element is available.

reader.{{ReadableStreamBYOBReader/releaseLock()|releaseLock}}()

[=release a read lock|Releases the reader's lock=] on the corresponding stream. After the lock is released, the reader is no longer [=active reader|active=]. If the associated stream is errored when the lock is released, the reader will appear errored in the same way from now on; otherwise, the reader will appear closed.

If the reader's lock is released while it still has pending read requests, then the promises returned by the reader's {{ReadableStreamBYOBReader/read()}} method are immediately rejected with a {{TypeError}}. Any unread chunks remain in the stream's [=internal queue=] and can be read later by acquiring a new reader.

The {{ReadableStreamDefaultController}} class

Interface definition

Internal slots

Methods and properties

desiredSize = controller.{{ReadableStreamDefaultController/desiredSize}}

Returns the [=desired size to fill a stream's internal queue|desired size to fill the controlled stream's internal queue=]. It can be negative, if the queue is over-full. An [=underlying source=] ought to use this information to determine when and how to apply [=backpressure=].

controller.{{ReadableStreamDefaultController/close()|close}}()

Closes the controlled readable stream. [=Consumers=] will still be able to read any previously-enqueued [=chunks=] from the stream, but once those are read, the stream will become closed.

controller.{{ReadableStreamDefaultController/enqueue()|enqueue}}(chunk)

Enqueues the given [=chunk=] chunk in the controlled readable stream.

controller.{{ReadableStreamDefaultController/error()|error}}(e)

Errors the controlled readable stream, making all future interactions with it fail with the given error e.

Internal methods

The {{ReadableByteStreamController}} class

Interface definition

Internal slots

Methods and properties

byobRequest = controller.{{ReadableByteStreamController/byobRequest}}

Returns the current BYOB pull request, or null if there isn't one.

desiredSize = controller.{{ReadableByteStreamController/desiredSize}}

Returns the [=desired size to fill a stream's internal queue|desired size to fill the controlled stream's internal queue=]. It can be negative, if the queue is over-full. An [=underlying byte source=] ought to use this information to determine when and how to apply [=backpressure=].

controller.{{ReadableByteStreamController/close()|close}}()

Closes the controlled readable stream. [=Consumers=] will still be able to read any previously-enqueued [=chunks=] from the stream, but once those are read, the stream will become closed.

controller.{{ReadableByteStreamController/enqueue()|enqueue}}(chunk)

Enqueues the given [=chunk=] chunk in the controlled readable stream. The chunk has to be an {{ArrayBufferView}} instance, or else a {{TypeError}} will be thrown.

controller.{{ReadableByteStreamController/error()|error}}(e)

Errors the controlled readable stream, making all future interactions with it fail with the given error e.

Internal methods

The {{ReadableStreamBYOBRequest}} class

Interface definition

Internal slots

Methods and properties

view = byobRequest.{{ReadableStreamBYOBRequest/view}}

Returns the view for writing in to, or null if the BYOB request has already been responded to.

byobRequest.{{ReadableStreamBYOBRequest/respond()|respond}}(bytesWritten)

Indicates to the associated [=readable byte stream=] that bytesWritten bytes were written into {{ReadableStreamBYOBRequest/view}}, causing the result be surfaced to the [=consumer=].

After this method is called, {{ReadableStreamBYOBRequest/view}} will be transferred and no longer modifiable.

byobRequest.{{ReadableStreamBYOBRequest/respondWithNewView()|respondWithNewView}}(view)

Indicates to the associated [=readable byte stream=] that instead of writing into {{ReadableStreamBYOBRequest/view}}, the [=underlying byte source=] is providing a new {{ArrayBufferView}}, which will be given to the [=consumer=] of the [=readable byte stream=].

The new |view| has to be a view onto the same backing memory region as {{ReadableStreamBYOBRequest/view}}, i.e. its buffer has to equal (or be a transferred version of) {{ReadableStreamBYOBRequest/view}}'s buffer. Its byteOffset has to equal {{ReadableStreamBYOBRequest/view}}'s byteOffset, and its byteLength (representing the number of bytes written) has to be less than or equal to that of {{ReadableStreamBYOBRequest/view}}.

After this method is called, view will be transferred and no longer modifiable.

Abstract operations

Working with readable streams

Various abstract operations performed here include object creation (often of promises), which usually would require specifying a realm for the created object. However, because of the locking, none of these objects can be observed by author code. As such, the realm used to create them does not matter.

Interfacing with controllers

\[[CancelSteps]](reason)

The controller's steps that run in reaction to the stream being [=cancel a readable stream|canceled=], used to clean up the state stored in the controller and inform the [=underlying source=].

\[[PullSteps]](readRequest)

The controller's steps that run when a [=default reader=] is read from, used to pull from the controller any queued [=chunks=], or pull from the [=underlying source=] to get more chunks.

\[[ReleaseSteps]]()

The controller's steps that run when a [=readable stream reader|reader=] is [=release a read lock|released=], used to clean up reader-specific resources stored in the controller.

Readers

Default controllers

Byte stream controllers

Writable streams

Using writable streams

The {{WritableStream}} class

Interface definition

Internal slots

The [=WritableStream/[[inFlightCloseRequest]]=] slot and [=WritableStream/[[closeRequest]]=] slot are mutually exclusive. Similarly, no element will be removed from [=WritableStream/[[writeRequests]]=] while [=WritableStream/[[inFlightWriteRequest]]=] is not undefined. Implementations can optimize storage for these slots based on these invariants. A pending abort request is a [=struct=] used to track a request to abort the stream before that request is finally processed. It has the following [=struct/items=]: : promise :: A promise returned from [$WritableStreamAbort$] : reason :: A JavaScript value that was passed as the abort reason to [$WritableStreamAbort$] : was already erroring :: A boolean indicating whether or not the stream was in the "`erroring`" state when [$WritableStreamAbort$] was called, which impacts the outcome of the abort request

The underlying sink API

start(controller)

A function that is called immediately during creation of the {{WritableStream}}.

Typically this is used to acquire access to the [=underlying sink=] resource being represented.

If this setup process is asynchronous, it can return a promise to signal success or failure; a rejected promise will error the stream. Any thrown exceptions will be re-thrown by the {{WritableStream()}} constructor.

write(chunk, controller)

A function that is called when a new [=chunk=] of data is ready to be written to the [=underlying sink=]. The stream implementation guarantees that this function will be called only after previous writes have succeeded, and never before {{UnderlyingSink/start|start()}} has succeeded or after {{UnderlyingSink/close|close()}} or {{UnderlyingSink/abort|abort()}} have been called.

This function is used to actually send the data to the resource presented by the [=underlying sink=], for example by calling a lower-level API.

If the process of writing data is asynchronous, and communicates success or failure signals back to its user, then this function can return a promise to signal success or failure. This promise return value will be communicated back to the caller of {{WritableStreamDefaultWriter/write()|writer.write()}}, so they can monitor that individual write. Throwing an exception is treated the same as returning a rejected promise.

Note that such signals are not always available; compare e.g. [[#example-ws-no-backpressure]] with [[#example-ws-backpressure]]. In such cases, it's best to not return anything.

The promise potentially returned by this function also governs whether the given chunk counts as written for the purposes of computed the [=desired size to fill a stream's internal queue|desired size to fill the stream's internal queue=]. That is, during the time it takes the promise to settle, {{WritableStreamDefaultWriter/desiredSize|writer.desiredSize}} will stay at its previous value, only increasing to signal the desire for more chunks once the write succeeds.

Finally, the promise potentially returned by this function is used to ensure that well-behaved [=producers=] do not attempt to mutate the [=chunk=] before it has been fully processed. (This is not guaranteed by any specification machinery, but instead is an informal contract between [=producers=] and the [=underlying sink=].)

close()

A function that is called after the [=producer=] signals, via {{WritableStreamDefaultWriter/close()|writer.close()}}, that they are done writing [=chunks=] to the stream, and subsequently all queued-up writes have successfully completed.

This function can perform any actions necessary to finalize or flush writes to the [=underlying sink=], and release access to any held resources.

If the shutdown process is asynchronous, the function can return a promise to signal success or failure; the result will be communicated via the return value of the called {{WritableStreamDefaultWriter/close()|writer.close()}} method. Additionally, a rejected promise will error the stream, instead of letting it close successfully. Throwing an exception is treated the same as returning a rejected promise.

abort(reason)

A function that is called after the [=producer=] signals, via {{WritableStream/abort()|stream.abort()}} or {{WritableStreamDefaultWriter/abort()|writer.abort()}}, that they wish to [=abort a writable stream|abort=] the stream. It takes as its argument the same value as was passed to those methods by the producer.

Writable streams can additionally be aborted under certain conditions during [=piping=]; see the definition of the {{ReadableStream/pipeTo()}} method for more details.

This function can clean up any held resources, much like {{UnderlyingSink/close|close()}}, but perhaps with some custom handling.

If the shutdown process is asynchronous, the function can return a promise to signal success or failure; the result will be communicated via the return value of the called {{WritableStreamDefaultWriter/abort()|writer.abort()}} method. Throwing an exception is treated the same as returning a rejected promise. Regardless, the stream will be errored with a new {{TypeError}} indicating that it was aborted.

type

This property is reserved for future use, so any attempts to supply a value will throw an exception.

Constructor, methods, and properties

stream = new {{WritableStream/constructor(underlyingSink, strategy)|WritableStream}}(underlyingSink[, strategy)

Creates a new {{WritableStream}} wrapping the provided [=underlying sink=]. See [[#underlying-sink-api]] for more details on the underlyingSink argument.

The |strategy| argument represents the stream's [=queuing strategy=], as described in [[#qs-api]]. If it is not provided, the default behavior will be the same as a {{CountQueuingStrategy}} with a [=high water mark=] of 1.

isLocked = stream.{{WritableStream/locked}}

Returns whether or not the writable stream is [=locked to a writer=].

await stream.{{WritableStream/abort(reason)|abort}}([ reason ])

[=abort a writable stream|Aborts=] the stream, signaling that the producer can no longer successfully write to the stream and it is to be immediately moved to an errored state, with any queued-up writes discarded. This will also execute any abort mechanism of the [=underlying sink=].

The returned promise will fulfill if the stream shuts down successfully, or reject if the underlying sink signaled that there was an error doing so. Additionally, it will reject with a {{TypeError}} (without attempting to cancel the stream) if the stream is currently [=locked to a writer|locked=].

await stream.{{WritableStream/close()|close}}()

Closes the stream. The [=underlying sink=] will finish processing any previously-written [=chunks=], before invoking its close behavior. During this time any further attempts to write will fail (without erroring the stream).

The method returns a promise that will fulfill if all remaining [=chunks=] are successfully written and the stream successfully closes, or rejects if an error is encountered during this process. Additionally, it will reject with a {{TypeError}} (without attempting to cancel the stream) if the stream is currently [=locked to a writer|locked=].

writer = stream.{{WritableStream/getWriter()|getWriter}}()

Creates a [=writer=] (an instance of {{WritableStreamDefaultWriter}}) and [=locked to a writer|locks=] the stream to the new writer. While the stream is locked, no other writer can be acquired until this one is [=release a write lock|released=].

This functionality is especially useful for creating abstractions that desire the ability to write to a stream without interruption or interleaving. By getting a writer for the stream, you can ensure nobody else can write at the same time, which would cause the resulting written data to be unpredictable and probably useless.

Transfer via `postMessage()`

destination.postMessage(ws, { transfer: [ws] });

Sends a {{WritableStream}} to another frame, window, or worker.

The transferred stream can be used exactly like the original. The original will become [=locked to a writer|locked=] and no longer directly usable.

The {{WritableStreamDefaultWriter}} class

Interface definition

Internal slots

Constructor, methods, and properties

writer = new {{WritableStreamDefaultWriter(stream)|WritableStreamDefaultWriter}}(|stream|)

This is equivalent to calling |stream|.{{WritableStream/getWriter()}}.

await writer.{{WritableStreamDefaultWriter/closed}}

Returns a promise that will be fulfilled when the stream becomes closed, or rejected if the stream ever errors or the writer's lock is [=release a write lock|released=] before the stream finishes closing.

desiredSize = writer.{{WritableStreamDefaultWriter/desiredSize}}

Returns the [=desired size to fill a stream's internal queue|desired size to fill the stream's internal queue=]. It can be negative, if the queue is over-full. A [=producer=] can use this information to determine the right amount of data to write.

It will be null if the stream cannot be successfully written to (due to either being errored, or having an abort queued up). It will return zero if the stream is closed. And the getter will throw an exception if invoked when the writer's lock is [=release a write lock|released=].

await writer.{{WritableStreamDefaultWriter/ready}}

Returns a promise that will be fulfilled when the [=desired size to fill a stream's internal queue|desired size to fill the stream's internal queue=] transitions from non-positive to positive, signaling that it is no longer applying [=backpressure=]. Once the [=desired size to fill a stream's internal queue|desired size=] dips back to zero or below, the getter will return a new promise that stays pending until the next transition.

If the stream becomes errored or aborted, or the writer's lock is [=release a write lock|released=], the returned promise will become rejected.

await writer.{{WritableStreamDefaultWriter/abort(reason)|abort}}([ reason ])

If the reader is [=active writer|active=], behaves the same as |stream|.{{WritableStream/abort(reason)|abort}}(reason).

await writer.{{WritableStreamDefaultWriter/close()|close}}()

If the reader is [=active writer|active=], behaves the same as |stream|.{{WritableStream/close()|close}}().

writer.{{WritableStreamDefaultWriter/releaseLock()|releaseLock}}()

[=release a write lock|Releases the writer's lock=] on the corresponding stream. After the lock is released, the writer is no longer [=active writer|active=]. If the associated stream is errored when the lock is released, the writer will appear errored in the same way from now on; otherwise, the writer will appear closed.

Note that the lock can still be released even if some ongoing writes have not yet finished (i.e. even if the promises returned from previous calls to {{WritableStreamDefaultWriter/write()}} have not yet settled). It's not necessary to hold the lock on the writer for the duration of the write; the lock instead simply prevents other [=producers=] from writing in an interleaved manner.

await writer.{{WritableStreamDefaultWriter/write(chunk)|write}}(chunk)

Writes the given [=chunk=] to the writable stream, by waiting until any previous writes have finished successfully, and then sending the [=chunk=] to the [=underlying sink=]'s {{UnderlyingSink/write|write()}} method. It will return a promise that fulfills with undefined upon a successful write, or rejects if the write fails or stream becomes errored before the writing process is initiated.

Note that what "success" means is up to the [=underlying sink=]; it might indicate simply that the [=chunk=] has been accepted, and not necessarily that it is safely saved to its ultimate destination.

If chunk is mutable, [=producers=] are advised to avoid mutating it after passing it to {{WritableStreamDefaultWriter/write()}}, until after the promise returned by {{WritableStreamDefaultWriter/write()}} settles. This ensures that the [=underlying sink=] receives and processes the same value that was passed in.

The {{WritableStreamDefaultController}} class

Interface definition

Internal slots

Methods and properties

controller.{{WritableStreamDefaultController/signal}}

An AbortSignal that can be used to abort the pending write or close operation when the stream is [=abort a writable stream|aborted=].

controller.{{WritableStreamDefaultController/error()|error}}(e)

Closes the controlled writable stream, making all future interactions with it fail with the given error e.

This method is rarely used, since usually it suffices to return a rejected promise from one of the [=underlying sink=]'s methods. However, it can be useful for suddenly shutting down a stream in response to an event outside the normal lifecycle of interactions with the [=underlying sink=].

Internal methods

The reason these are in method form, instead of as abstract operations, is to make it clear that the writable stream implementation is decoupled from the controller implementation, and could in the future be expanded with other controllers, as long as those controllers implemented such internal methods. A similar scenario is seen for readable streams (see [[#rs-abstract-ops-used-by-controllers]]), where there actually are multiple controller types and as such the counterpart internal methods are used polymorphically.

Abstract operations

Working with writable streams

Interfacing with controllers

\[[AbortSteps]](reason)

The controller's steps that run in reaction to the stream being [=abort a writable stream|aborted=], used to clean up the state stored in the controller and inform the [=underlying sink=].

\[[ErrorSteps]]()

The controller's steps that run in reaction to the stream being errored, used to clean up the state stored in the controller.

Writers

Default controllers

Transform streams

Using transform streams

The {{TransformStream}} class

Interface definition

Internal slots

The transformer API

start(controller)

A function that is called immediately during creation of the {{TransformStream}}.

Typically this is used to enqueue prefix [=chunks=], using {{TransformStreamDefaultController/enqueue()|controller.enqueue()}}. Those chunks will be read from the [=readable side=] but don't depend on any writes to the [=writable side=].

If this initial process is asynchronous, for example because it takes some effort to acquire the prefix chunks, the function can return a promise to signal success or failure; a rejected promise will error the stream. Any thrown exceptions will be re-thrown by the {{TransformStream()}} constructor.

transform(chunk, controller)

A function called when a new [=chunk=] originally written to the [=writable side=] is ready to be transformed. The stream implementation guarantees that this function will be called only after previous transforms have succeeded, and never before {{Transformer/start|start()}} has completed or after {{Transformer/flush|flush()}} has been called.

This function performs the actual transformation work of the transform stream. It can enqueue the results using {{TransformStreamDefaultController/enqueue()|controller.enqueue()}}. This permits a single chunk written to the writable side to result in zero or multiple chunks on the [=readable side=], depending on how many times {{TransformStreamDefaultController/enqueue()|controller.enqueue()}} is called. [[#example-ts-lipfuzz]] demonstrates this by sometimes enqueuing zero chunks.

If the process of transforming is asynchronous, this function can return a promise to signal success or failure of the transformation. A rejected promise will error both the readable and writable sides of the transform stream.

The promise potentially returned by this function is used to ensure that well-behaved [=producers=] do not attempt to mutate the [=chunk=] before it has been fully transformed. (This is not guaranteed by any specification machinery, but instead is an informal contract between [=producers=] and the [=transformer=].)

If no {{Transformer/transform|transform()}} method is supplied, the identity transform is used, which enqueues chunks unchanged from the writable side to the readable side.

flush(controller)

A function called after all [=chunks=] written to the [=writable side=] have been transformed by successfully passing through {{Transformer/transform|transform()}}, and the writable side is about to be closed.

Typically this is used to enqueue suffix chunks to the [=readable side=], before that too becomes closed. An example can be seen in [[#example-ts-lipfuzz]].

If the flushing process is asynchronous, the function can return a promise to signal success or failure; the result will be communicated to the caller of {{WritableStreamDefaultWriter/write()|stream.writable.write()}}. Additionally, a rejected promise will error both the readable and writable sides of the stream. Throwing an exception is treated the same as returning a rejected promise.

(Note that there is no need to call {{TransformStreamDefaultController/terminate()|controller.terminate()}} inside {{Transformer/flush|flush()}}; the stream is already in the process of successfully closing down, and terminating it would be counterproductive.)

cancel(reason)

A function called when the [=readable side=] is cancelled, or when the [=writable side=] is aborted.

Typically this is used to clean up underlying transformer resources when the stream is aborted or cancelled.

If the cancellation process is asynchronous, the function can return a promise to signal success or failure; the result will be communicated to the caller of {{WritableStream/abort()|stream.writable.abort()}} or {{ReadableStream/cancel()|stream.readable.cancel()}}. Throwing an exception is treated the same as returning a rejected promise.

(Note that there is no need to call {{TransformStreamDefaultController/terminate()|controller.terminate()}} inside {{Transformer/cancel|cancel()}}; the stream is already in the process of cancelling/aborting, and terminating it would be counterproductive.)

readableType

This property is reserved for future use, so any attempts to supply a value will throw an exception.

writableType

This property is reserved for future use, so any attempts to supply a value will throw an exception.

Constructor and properties

stream = new {{TransformStream/constructor(transformer, writableStrategy, readableStrategy)|TransformStream}}([transformer[, writableStrategy[, readableStrategy]]])

Creates a new {{TransformStream}} wrapping the provided [=transformer=]. See [[#transformer-api]] for more details on the transformer argument.

If no transformer argument is supplied, then the result will be an [=identity transform stream=]. See this example for some cases where that can be useful.

The writableStrategy and readableStrategy arguments are the [=queuing strategy=] objects for the [=writable side|writable=] and [=readable side|readable=] sides respectively. These are used in the construction of the {{WritableStream}} and {{ReadableStream}} objects and can be used to add buffering to a {{TransformStream}}, in order to smooth out variations in the speed of the transformation, or to increase the amount of buffering in a [=pipe=]. If they are not provided, the default behavior will be the same as a {{CountQueuingStrategy}}, with respective [=high water marks=] of 1 and 0.

readable = stream.{{TransformStream/readable}}

Returns a {{ReadableStream}} representing the [=readable side=] of this transform stream.

writable = stream.{{TransformStream/writable}}

Returns a {{WritableStream}} representing the [=writable side=] of this transform stream.

Transfer via `postMessage()`

destination.postMessage(ts, { transfer: [ts] });

Sends a {{TransformStream}} to another frame, window, or worker.

The transferred stream can be used exactly like the original. Its [=readable side|readable=] and [=writable sides=] will become locked and no longer directly usable.

The {{TransformStreamDefaultController}} class

Interface definition

Internal slots

Methods and properties

desiredSize = controller.{{TransformStreamDefaultController/desiredSize}}

Returns the [=desired size to fill a stream's internal queue|desired size to fill the readable side's internal queue=]. It can be negative, if the queue is over-full.

controller.{{TransformStreamDefaultController/enqueue()|enqueue}}(chunk)

Enqueues the given [=chunk=] chunk in the [=readable side=] of the controlled transform stream.

controller.{{TransformStreamDefaultController/error()|error}}(e)

Errors both the [=readable side=] and the [=writable side=] of the controlled transform stream, making all future interactions with it fail with the given error e. Any [=chunks=] queued for transformation will be discarded.

controller.{{TransformStreamDefaultController/terminate()|terminate}}()

Closes the [=readable side=] and errors the [=writable side=] of the controlled transform stream. This is useful when the [=transformer=] only needs to consume a portion of the [=chunks=] written to the [=writable side=].

Abstract operations

Working with transform streams

Default controllers

Default sinks

Default sources

Queuing strategies

The queuing strategy API

highWaterMark

A non-negative number indicating the [=high water mark=] of the stream using this queuing strategy.

size(chunk) (non-byte streams only)

A function that computes and returns the finite non-negative size of the given [=chunk=] value.

The result is used to determine [=backpressure=], manifesting via the appropriate desiredSize property: either {{ReadableStreamDefaultController/desiredSize|defaultController.desiredSize}}, {{ReadableByteStreamController/desiredSize|byteController.desiredSize}}, or {{WritableStreamDefaultWriter/desiredSize|writer.desiredSize}}, depending on where the queuing strategy is being used. For readable streams, it also governs when the [=underlying source=]'s {{UnderlyingSource/pull|pull()}} method is called.

This function has to be idempotent and not cause side effects; very strange results can occur otherwise.

For [=readable byte streams=], this function is not used, as chunks are always measured in bytes.

The {{ByteLengthQueuingStrategy}} class

It is not necessary to use {{ByteLengthQueuingStrategy}} with [=readable byte streams=], as they always measure chunks in bytes. Attempting to construct a byte stream with a {{ByteLengthQueuingStrategy}} will fail.

Interface definition

Internal slots

Constructor and properties

strategy = new {{ByteLengthQueuingStrategy/constructor(init)|ByteLengthQueuingStrategy}}({ {{QueuingStrategyInit/highWaterMark}} })

Creates a new {{ByteLengthQueuingStrategy}} with the provided [=high water mark=].

Note that the provided high water mark will not be validated ahead of time. Instead, if it is negative, NaN, or not a number, the resulting {{ByteLengthQueuingStrategy}} will cause the corresponding stream constructor to throw.

highWaterMark = strategy.{{ByteLengthQueuingStrategy/highWaterMark}}

Returns the [=high water mark=] provided to the constructor.

strategy.{{ByteLengthQueuingStrategy/size}}(chunk)

Measures the size of chunk by returning the value of its byteLength property.

The {{CountQueuingStrategy}} class

Interface definition

Internal slots

Constructor and properties

strategy = new {{CountQueuingStrategy/constructor(init)|CountQueuingStrategy}}({ {{QueuingStrategyInit/highWaterMark}} })

Creates a new {{CountQueuingStrategy}} with the provided [=high water mark=].

Note that the provided high water mark will not be validated ahead of time. Instead, if it is negative, NaN, or not a number, the resulting {{CountQueuingStrategy}} will cause the corresponding stream constructor to throw.

highWaterMark = strategy.{{CountQueuingStrategy/highWaterMark}}

Returns the [=high water mark=] provided to the constructor.

strategy.{{CountQueuingStrategy/size}}(chunk)

Measures the size of chunk by always returning 1. This ensures that the total queue size is a count of the number of chunks in the queue.

Abstract operations

Supporting abstract operations

Queue-with-sizes

Due to the limited precision of floating-point arithmetic, the framework specified here, of keeping a running total in the \[[queueTotalSize]] slot, is not equivalent to adding up the size of all [=chunks=] in \[[queue]]. (However, this only makes a difference when there is a huge (~10¹⁵) variance in size between chunks, or when trillions of chunks are enqueued.) In what follows, a value-with-size is a [=struct=] with the two [=struct/items=] value and size.

Transferable streams

Miscellaneous

Using streams in other specifications

If your specification wants to interface with streams in a way not supported here, file an issue. This section is intended to grow organically as needed.

Readable streams

Creation and manipulation

Subclasses of {{ReadableStream}} will use the [=ReadableStream/set up=] or [=ReadableStream/set up with byte reading support=] operations directly on the [=this=] value inside their constructor steps.

A {{ReadableStream}} needs more data if its [=ReadableStream/desired size to fill up to the high water mark=] is greater than zero.

Implementations could do something equivalent to transferring, e.g. if they want to write into the memory from another thread. But they would need to make a few adjustments to how they implement the [=ReadableStream/enqueue=] and [=ReadableStream/close=] algorithms to keep the same observable consequences. In specification-land, transferring and detaching is just disallowed. Specifications should, when possible, [=ArrayBufferView/write=] into the [=ReadableStream/current BYOB request view=] when it is non-null, and then call [=ReadableStream/enqueue=] with that view. They should only [=ArrayBufferView/create=] a new {{ArrayBufferView}} to pass to [=ReadableStream/enqueue=] when the [=ReadableStream/current BYOB request view=] is null, or when they have more bytes on hand than the [=ReadableStream/current BYOB request view=]'s [=BufferSource/byte length=]. This avoids unnecessary copies and better respects the wishes of the stream's [=consumer=]. The following [=ReadableStream/pull from bytes=] algorithm implements these requirements, for the common case where bytes are derived from a [=byte sequence=] that serves as the specification-level representation of an [=underlying byte source=]. Note that it is conservative and leaves bytes in the [=byte sequence=], instead of aggressively [=ReadableStream/enqueueing=] them, so callers of this algorithm might want to use the number of remaining bytes as a [=backpressure=] signal.

Reading

To read a chunk from a {{ReadableStreamDefaultReader}} |reader|, given a [=read request=] |readRequest|, perform ! [$ReadableStreamDefaultReaderRead$](|reader|, |readRequest|).

To release a {{ReadableStreamDefaultReader}} |reader|, perform ! [$ReadableStreamDefaultReaderRelease$](|reader|).

To cancel a {{ReadableStreamDefaultReader}} |reader| with |reason|, perform ! [$ReadableStreamReaderGenericCancel$](|reader|, |reason|). The return value will be a promise that either fulfills with undefined, or rejects with a failure reason.

To cancel a {{ReadableStream}} |stream| with |reason|, return ! [$ReadableStreamCancel$](|stream|, |reason|). The return value will be a promise that either fulfills with undefined, or rejects with a failure reason.

Introspection

A {{ReadableStream}} |stream| is readable if |stream|.[=ReadableStream/[[state]]=] is "`readable`".

A {{ReadableStream}} |stream| is closed if |stream|.[=ReadableStream/[[state]]=] is "`closed`".

A {{ReadableStream}} |stream| is errored if |stream|.[=ReadableStream/[[state]]=] is "`errored`".

A {{ReadableStream}} |stream| is locked if ! [$IsReadableStreamLocked$](|stream|) returns true.

Writable streams

Creation and manipulation

To error a {{WritableStream}} |stream| given a JavaScript value |e|, perform ! [$WritableStreamDefaultControllerErrorIfNeeded$](|stream|.[=WritableStream/[[controller]]=], |e|).

The signal of a {{WritableStream}} |stream| is |stream|.[=WritableStream/[[controller]]=].[=WritableStreamDefaultController/[[abortController]]=]'s [=AbortController/signal=]. Specifications can [=AbortSignal/add=] or [=AbortSignal/remove=] algorithms to this {{AbortSignal}}, or consult whether it is [=AbortSignal/aborted=] and its [=AbortSignal/abort reason=].

The usual usage is, after [=WritableStream/setting up=] the {{WritableStream}}, [=AbortSignal/add=] an algorithm to its [=WritableStream/signal=], which aborts any ongoing write operation to the [=underlying sink=]. Then, inside the [=WritableStream/set up/writeAlgorithm=], once the [=underlying sink=] has responded, check if the [=WritableStream/signal=] is [=AbortSignal/aborted=], and [=reject=] the returned promise with the signal's [=AbortSignal/abort reason=] if so.

Writing

To write a chunk to a {{WritableStreamDefaultWriter}} |writer|, given a value |chunk|, return ! [$WritableStreamDefaultWriterWrite$](|writer|, |chunk|).

To release a {{WritableStreamDefaultWriter}} |writer|, perform ! [$WritableStreamDefaultWriterRelease$](|writer|).

To close a {{WritableStream}} |stream|, return ! [$WritableStreamClose$](|stream|). The return value will be a promise that either fulfills with undefined, or rejects with a failure reason.

To abort a {{WritableStream}} |stream| with |reason|, return ! [$WritableStreamAbort$](|stream|, |reason|). The return value will be a promise that either fulfills with undefined, or rejects with a failure reason.

Transform streams

Creation and manipulation

To enqueue the JavaScript value |chunk| into a {{TransformStream}} |stream|, perform ! [$TransformStreamDefaultControllerEnqueue$](|stream|.[=TransformStream/[[controller]]=], |chunk|).

To terminate a {{TransformStream}} |stream|, perform ! [$TransformStreamDefaultControllerTerminate$](|stream|.[=TransformStream/[[controller]]=]).

To error a {{TransformStream}} |stream| given a JavaScript value |e|, perform ! [$TransformStreamDefaultControllerError$](|stream|.[=TransformStream/[[controller]]=], |e|).

Wrapping into a custom class

There's no need to create a wrapper class if you don't need any API beyond what the base {{TransformStream}} class provides. The most common driver for such a wrapper is needing custom [=constructor steps=], but if your conceptual transform stream isn't meant to be constructed, then using {{TransformStream}} directly is fine.

Other stream pairs

Duplex streams

A basic example of a duplex stream, created through JavaScript instead of through specification prose, is found in [[#example-both]]. It illustrates this carry-over behavior. Another consideration is how to handle the creation of duplex streams which need to be acquired asynchronously, e.g. via establishing a connection. The preferred pattern here is to have a constructible class with a promise-returning property that fulfills with the actual duplex stream object. That duplex stream object can also then expose any information that is only available asynchronously, e.g. connection data. The container class can then provide convenience APIs, such as a function to close the entire connection instead of only closing individual sides.

An example of this more complex type of duplex stream is the still-being-specified `WebSocketStream`. See its explainer and design notes. Because duplex streams obey the `readable`/`writable` property contract, they can be used with {{ReadableStream/pipeThrough()}}. This doesn't always make sense, but it could in cases where the underlying resource is in fact performing some sort of transformation.

For an arbitrary WebSocket, piping through a WebSocket-derived duplex stream doesn't make sense. However, if the WebSocket server is specifically written so that it responds to incoming messages by sending the same data back in some transformed form, then this could be useful and convenient.

Endpoint pairs

WebRTC Encoded Transform is an example of this technique, with its {{RTCRtpScriptTransformer}} interface which has both `readable` and `writable` attributes. Despite such endpoint pairs obeying the `readable`/`writable` property contract, it never makes sense to pass them to {{ReadableStream/pipeThrough()}}.

Piping

Examples of creating streams

A transform stream that replaces template tags

For simplicity, LipFuzzTransformer performs unescaped text substitutions. In real applications, a template system that performs context-aware escaping is good practice for security and robustness.

A transform stream created from a sync mapper function

Using an identity transform stream as a primitive to create new readable streams

Acknowledgments