Streams

1. Introduction

2. Model

A chunk is a single piece of data that is written to or read from a stream. It can be of any type; streams can even contain chunks of different types. A chunk will often not be the most atomic unit of data for a given stream; for example a byte stream might contain chunks consisting of 16 KiB Uint8Array s, instead of single bytes.

2.1. Readable Streams

A readable stream represents a source of data, from which you can read. In other words, data comes out of a readable stream. Concretely, a readable stream is an instance of the ReadableStream class.

Although a readable stream can be created with arbitrary behavior, most readable streams wrap a lower-level I/O source, called the underlying source . There are two types of underlying source: push sources and pull sources.

Push sources push data at you, whether or not you are listening for it. They may also provide a mechanism for pausing and resuming the flow of data. An example push source is a TCP socket, where data is constantly being pushed from the OS level, at a rate that can be controlled by changing the TCP window size.

Pull sources require you to request data from them. The data may be available synchronously, e.g. if it is held by the operating system’s in-memory buffers, or asynchronously, e.g. if it has to be read from disk. An example pull source is a file handle, where you seek to specific locations and read specific amounts.

Readable streams are designed to wrap both types of sources behind a single, unified interface. The implementation details of a source are provided by an object with certain methods and properties. It is passed to the ReadableStream() constructor.

Chunks are enqueued into the stream by the stream’s underlying source . They can then be read one at a time via the stream’s public interface, in particular by using a readable stream reader acquired using the stream’s getReader() method.

Code that reads from a readable stream using its public interface is known as a consumer .

Consumers also have the ability to cancel a readable stream, using its cancel() method. This indicates that the consumer has lost interest in the stream, and will immediately close the stream, throw away any queued chunks , and execute any cancellation mechanism of the underlying source .

Consumers can also tee a readable stream using its tee() method. This will lock the stream, making it no longer directly usable; however, it will create two new streams, called branches , which can be consumed independently.

For streams representing bytes, an extended version of the readable stream is provided to handle bytes efficiently, in particular by minimizing copies. The underlying source for such a readable stream is called an underlying byte source . A readable stream whose underlying source is an underlying byte source is sometimes called a readable byte stream . Consumers of a readable byte stream can acquire a BYOB reader using the stream’s getReader() method.

2.2. Writable Streams

A writable stream represents a destination for data, into which you can write. In other words, data goes in to a writable stream. Concretely, a writable stream is an instance of the WritableStream class.

Analogously to readable streams, most writable streams wrap a lower-level I/O sink, called the underlying sink . Writable streams work to abstract away some of the complexity of the underlying sink, by queuing subsequent writes and only delivering them to the underlying sink one by one.

Chunks are written to the stream via its public interface, and are passed one at a time to the stream’s underlying sink . The implementation details of the sink are provided by an object with certain methods that is passed to the WritableStream() constructor.

Code that writes into a writable stream using its public interface is known as a producer .

Producers also have the ability to abort a writable stream, using its abort() method. This indicates that the producer believes something has gone wrong, and that future writes should be discontinued. It puts the stream in an errored state, even without a signal from the underlying sink .

2.3. Transform Streams

A transform stream consists of a pair of streams: a writable stream, stream , known as its writable side , and a readable stream. stream , known as its readable side . In a manner specific to the transform stream in question, writes to the writable side result in new data being made available for reading from the readable side.

Concretely, any object with a writable property and a readable property can serve as a transform stream. However, we plan to provide a the standard TransformStream class which makes it much easier to create such a pair that is properly entangled. It wraps a transformer object which defines the specific transformation to be performed.

An identity transform stream is a type of transform stream which forwards all chunks written to its writable side to its readable side , without any changes. This can be useful in a variety of scenarios . By default, the TransformStream constructor will create an identity transform stream, when no transform method is present on the transformer object.

Some examples of potential transform streams include:

• A GZIP compressor, to which uncompressed bytes are written and from which compressed bytes are read;
• A video decoder, to which encoded bytes are written and from which uncompressed video frames are read;
• A text decoder, to which bytes are written and from which strings are read;
• A CSV-to-JSON converter, to which strings representing lines of a CSV file are written and from which corresponding JavaScript objects are read.

2.4. Pipe Chains and Backpressure

Streams are primarily used by piping them to each other. A readable stream can be piped directly to a writable stream, using its pipeTo() method, or it can be piped through one or more transform streams first, using its pipeThrough() method.

A set of streams piped together in this way is referred to as a pipe chain . In a pipe chain, the original source is the underlying source of the first readable stream in the chain; the ultimate sink is the underlying sink of the final writable stream in the chain.

Once a pipe chain is constructed, it will propagate signals regarding how fast chunks should flow through it. If any step in the chain cannot yet accept chunks, it propagates a signal backwards through the pipe chain, until eventually the original source is told to stop producing chunks so fast. This process of normalizing flow from the original source according to how fast the chain can process chunks is called backpressure .

Concretely, the original source is given the controller.desiredSize (or byteController.desiredSize ) value, and can then adjust its rate of data flow accordingly. This value is derived from the writer.desiredSize corresponding to the ultimate sink , which gets updated as the ultimate sink finishes writing chunks . The pipeTo() method used to construct the chain automatically ensures this information propagates back through the pipe chain .

When teeing a readable stream, the backpressure signals from its two branches will aggregate, such that if neither branch is read from, a backpressure signal will be sent to the underlying source of the original stream.

Piping locks the readable and writable streams, preventing them from being manipulated for the duration of the pipe operation. This allows the implementation to perform important optimizations, such as directly shuttling data from the underlying source to the underlying sink while bypassing many of the intermediate queues.

2.5. Internal Queues and Queuing Strategies

Both readable and writable streams maintain internal queues , which they use for similar purposes. In the case of a readable stream, the internal queue contains chunks that have been enqueued by the underlying source , but not yet read by the consumer. In the case of a writable stream, the internal queue contains chunks which have been written to the stream by the producer, but not yet processed and acknowledged by the underlying sink .

A queuing strategy is an object that determines how a stream should signal backpressure based on the state of its internal queue . The queuing strategy assigns a size to each chunk , and compares the total size of all chunks in the queue to a specified number, known as the high water mark . The resulting difference, high water mark minus total size, is used to determine the desired size to fill the stream’s queue .

For readable streams, an underlying source can use this desired size as a backpressure signal, slowing down chunk generation so as to try to keep the desired size above or at zero. For writable streams, a producer can behave similarly, avoiding writes that would cause the desired size to go negative.

Concretely, a queueing strategy is given by any JavaScript object with a highWaterMark property and a size() method.

2.6. Locking

A readable stream reader , or simply reader, is an object that allows direct reading of chunks from a readable stream . Without a reader, a consumer can only perform high-level operations on the readable stream: canceling the stream, or piping the readable stream to a writable stream. A reader is acquired via the stream’s getReader() method.

A readable byte stream has the ability to vend two types of readers: default readers and BYOB readers . BYOB ("bring your own buffer") readers allow reading into a developer-supplied buffer, thus minimizing copies. A non-byte readable stream can only vend default readers. Default readers are instances of the ReadableStreamDefaultReader class, while BYOB readers are instances of ReadableStreamBYOBReader .

Similarly, a writable stream writer , or simply writer, is an object that allows direct writing of chunks to a writable stream . Without a writer, a producer can only perform the high-level operations of aborting the stream or piping a readable stream to the writable stream. Writers are represented by the WritableStreamDefaultWriter class.

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

A given readable or writable stream only has at most one reader or writer at a time. We say in this case the stream is locked , and that the reader or writer is active . This state can be determined using the readableStream.locked or writableStream.locked properties.

A reader or writer also has the capability to release its lock , which makes it no longer active, and allows further readers or writers to be acquired. This is done via the defaultReader.releaseLock() , byobReader.releaseLock() , or writer.releaseLock() method, as appropriate.

3. Readable Streams

3.1. Using Readable Streams

readableStream.pipeTo(writableStream)
  .then(() => console.log("All data successfully written!"))
  .catch(e => console.error("Something went wrong!", e));

readableStream.pipeTo(new WritableStream({
  write(chunk) {
    console.log("Chunk received", chunk);
  },
  close() {
    console.log("All data successfully read!");
  },
  abort(e) {
    console.error("Something went wrong!", e);
  }
}));

const reader = readableStream.getReader();
reader.read().then(
  ({ value, done }) => {
    if (done) {
      console.log("The stream was already closed!");
    } else {
      console.log(value);
    }
  },
  e => console.error("The stream became errored and cannot be read from!", e)
);

const reader = readableStream.getReader({ mode: "byob" });
let startingAB = new ArrayBuffer(1024);
readInto(startingAB)
  .then(buffer => console.log("The first 1024 bytes:", buffer))
  .catch(e => console.error("Something went wrong!", e));
function readInto(buffer, offset = 0) {
  if (offset === buffer.byteLength) {
    return Promise.resolve(buffer);
  }
  const view = new Uint8Array(buffer, offset, buffer.byteLength - offset);
  return reader.read(view).then(newView => {
    return readInto(newView.buffer, offset + newView.byteLength);
  });
}

3.2. Class ReadableStream

The ReadableStream class is a concrete instance of the general readable stream concept. It is adaptable to any chunk type, and maintains an internal queue to keep track of data supplied by the underlying source but not yet read by any consumer.

3.2.1. Class Definition

This section is non-normative.

If one were to write the ReadableStream class in something close to the syntax of [ECMASCRIPT] , it would look like

class ReadableStream {
  constructor(underlyingSource = {}, { size, highWaterMark } = {})
  get locked()
  cancel(reason)
  getReader()
  pipeThrough({ writable, readable }, options)
  pipeTo(dest, { preventClose, preventAbort, preventCancel } = {})
  tee()
}

3.2.2. Internal Slots

Instances of ReadableStream are created with the internal slots described in the following table:

3.2.3. new ReadableStream( underlyingSource = {}, { size , highWaterMark } = {})

3.2.4. Properties of the ReadableStream Prototype

3.2.4.1. get locked

3.2.4.2. cancel( reason )

3.2.4.3. getReader({ mode } = {})

function readAllChunks(readableStream) {
  const reader = readableStream.getReader();
  const chunks = [];
  return pump();
  function pump() {
    return reader.read().then(({ value, done }) => {
      if (done) {
        return chunks;
      }
      chunks.push(value);
      return pump();
    });
  }
}

3.2.4.4. pipeThrough({ writable , readable }, options )

httpResponseBody
  .pipeThrough(decompressorTransform)
  .pipeThrough(ignoreNonImageFilesTransform)
  .pipeTo(mediaGallery);

3.2.4.5. pipeTo( dest , { preventClose , preventAbort , preventCancel } = {})

3.2.4.6. tee()

const [forLocal, forRemote] = readableStream.tee();
Promise.all([
  forLocal.pipeTo(cacheEntry),
  forRemote.pipeTo(httpRequestBody)
])
.then(() => console.log("Saved the stream to the cache and also uploaded it!"))
.catch(e => console.error("Either caching or uploading failed: ", e));

3.3. General Readable Stream Abstract Operations

The following abstract operations, unlike most in this specification, are meant to be generally useful by other specifications, instead of just being part of the implementation of this spec’s classes.

3.3.1. AcquireReadableStreamBYOBReader ( stream ) throws

This abstract operation is meant to be called from other specifications that may wish to acquire a BYOB reader for a given stream.

3.3.2. AcquireReadableStreamDefaultReader ( stream ) throws

This abstract operation is meant to be called from other specifications that may wish to acquire a default reader for a given stream.

3.3.3. IsReadableStream ( x ) nothrow

3.3.4. IsReadableStreamDisturbed ( stream ) nothrow

This abstract operation is meant to be called from other specifications that may wish to query whether or not a readable stream has ever been read from or canceled.

3.3.5. IsReadableStreamLocked ( stream ) nothrow

This abstract operation is meant to be called from other specifications that may wish to query whether or not a readable stream is locked to a reader .

3.3.6. ReadableStreamTee ( stream , cloneForBranch2 ) throws

This abstract operation is meant to be called from other specifications that may wish to tee a given readable stream.

The second argument, cloneForBranch2 , governs whether or not the data from the original stream will be cloned (using HTML’s serializable objects framework) before appearing in the second of the returned branches. This is useful for scenarios where both branches are to be consumed in such a way that they might otherwise interfere with each other, such as by transferring their chunks . However, it does introduce a noticable asymmetry between the two branches, and limits the possible chunks to serializable ones. [HTML]

In this standard

1. Assert: ! IsReadableStream ( stream ) is true .
2. Assert: Type ( cloneForBranch2 ) is Boolean.
3. Let reader be ? AcquireReadableStreamDefaultReader ( stream ).
4. Let teeState be Record {[[closedOrErrored]]: false , [[canceled1]]: false , [[canceled2]]: false , [[reason1]]: undefined , [[reason2]]: undefined , [[promise]]: a new promise }.
5. Let pull be a new ReadableStreamTee pull function .
6. Set pull .[[reader]] to reader , pull .[[teeState]] to teeState , and pull .[[cloneForBranch2]] to cloneForBranch2 .
7. Let cancel1 be a new ReadableStreamTee branch 1 cancel function .
8. Set cancel1 .[[stream]] to stream and cancel1 .[[teeState]] to teeState .
9. Let cancel2 be a new ReadableStreamTee branch 2 cancel function .
10. Set cancel2 .[[stream]] to stream and cancel2 .[[teeState]] to teeState .
11. Let underlyingSource1 be ! ObjectCreate ( %ObjectPrototype% ).
12. Perform ! CreateDataProperty ( underlyingSource1 , "pull" , pull ).
13. Perform ! CreateDataProperty ( underlyingSource1 , "cancel" , cancel1 ).
14. Let branch1Stream be ! Construct ( ReadableStream , underlyingSource1 ).
15. Let underlyingSource2 be ! ObjectCreate ( %ObjectPrototype% ).
16. Perform ! CreateDataProperty ( underlyingSource2 , "pull" , pull ).
17. Perform ! CreateDataProperty ( underlyingSource2 , "cancel" , cancel2 ).
18. Let branch2Stream be ! Construct ( ReadableStream , underlyingSource2 ).
19. Set pull .[[branch1]] to branch1Stream .[[readableStreamController]].
20. Set pull .[[branch2]] to branch2Stream .[[readableStreamController]].
21. Upon rejection of reader .[[closedPromise]] with reason r ,
    1. If teeState .[[closedOrErrored]] is false , then:
       1. Perform ! ReadableStreamDefaultControllerError ( pull .[[branch1]], r ).
       2. Perform ! ReadableStreamDefaultControllerError ( pull .[[branch2]], r ).
       3. Set teeState .[[closedOrErrored]] to true .
22. Return « branch1Stream , branch2Stream ».

A ReadableStreamTee pull function is an anonymous built-in function that pulls data from a given readable stream reader and enqueues it into two other streams ("branches" of the associated tee). Each

1. Let reader be F .[[reader]], branch1 be F .[[branch1]], branch2 be F .[[branch2]], teeState be F .[[teeState]], and cloneForBranch2 be F .[[cloneForBranch2]].
2. Return the result of transforming ! ReadableStreamDefaultReaderRead ( reader ) with a fulfillment handler which takes the argument result and performs the following steps:
   1. Assert: Type ( result ) is Object.
   2. Let value be ? Get ( result , "value" ).
   3. Let done be ? Get ( result , "done" ).
   4. Assert: Type ( done ) is Boolean.
   5. If done is true and teeState .[[closedOrErrored]] is false ,
      1. If teeState .[[canceled1]] is false ,
         1. Perform ! ReadableStreamDefaultControllerClose ( branch1 ).
      2. If teeState .[[canceled2]] is false ,
         1. Perform ! ReadableStreamDefaultControllerClose ( branch2 ).
      3. Set teeState .[[closedOrErrored]] to true .
   6. If teeState .[[closedOrErrored]] is true , return.
   7. Let value1 and value2 be value .
   8. If teeState .[[canceled2]] is false and cloneForBranch2 is true , set value2 to ? StructuredDeserialize ( StructuredSerialize ( value2 ), the current Realm Record ).
   9. If teeState .[[canceled1]] is false , perform ? ReadableStreamDefaultControllerEnqueue ( branch1 , value1 ).
   10. If teeState .[[canceled2]] is false , perform ? ReadableStreamDefaultControllerEnqueue ( branch2 , value2 ).

A ReadableStreamTee branch 1 cancel function is an anonymous built-in function that reacts to the cancellation of the first of the two branches of the associated tee. Each

1. Let stream be F .[[stream]] and teeState be F .[[teeState]].
2. Set teeState .[[canceled1]] to true .
3. Set teeState .[[reason1]] to reason .
4. If teeState .[[canceled2]] is true ,
   1. Let compositeReason be ! CreateArrayFromList (« teeState .[[reason1]], teeState .[[reason2]] »).
   2. Let cancelResult be ! ReadableStreamCancel ( stream , compositeReason ).
   3. Resolve teeState .[[promise]] with cancelResult .
5. Return teeState .[[promise]].

A ReadableStreamTee branch 2 cancel function is an anonymous built-in function that reacts to the cancellation of the second of the two branches of the associated tee. Each

1. Let stream be F .[[stream]] and teeState be F .[[teeState]].
2. Set teeState .[[canceled2]] to true .
3. Set teeState .[[reason2]] to reason .
4. If teeState .[[canceled1]] is true ,
   1. Let compositeReason be ! CreateArrayFromList (« teeState .[[reason1]], teeState .[[reason2]] »).
   2. Let cancelResult be ! ReadableStreamCancel ( stream , compositeReason ).
   3. Resolve teeState .[[promise]] with cancelResult .
5. Return teeState .[[promise]].

3.4. The Interface Between Readable Streams and Controllers

In terms of specification factoring, the way that the ReadableStream class encapsulates the behavior of both simple readable streams and readable byte streams into a single class is by centralizing most of the potentially-varying logic inside the two controller classes, ReadableStreamDefaultController and ReadableByteStreamController . Those classes define most of the stateful internal slots and abstract operations for how a stream’s internal queue is managed and how it interfaces with its underlying source or underlying byte source .

Each controller class defines two internal methods, which are called by the ReadableStream algorithms:

[[CancelSteps]]( reason )

The controller’s steps that run in reaction to the stream being canceled , used to clean up the state stored in the controller and inform the underlying source .

[[PullSteps]]()

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.

(These are defined as internal methods, instead of as abstract operations, so that they can be called polymorphically by the ReadableStream algorithms, without having to branch on which type of controller is present.)

The rest of this section concerns abstract operations that go in the other direction: they are used by the controller implementations to affect their associated ReadableStream object. This translates internal state changes of the controller into developer-facing results visible through the ReadableStream 's public API.

3.4.1. ReadableStreamAddReadIntoRequest ( stream ) nothrow

3.4.2. ReadableStreamAddReadRequest ( stream ) nothrow

3.4.3. ReadableStreamCancel ( stream , reason ) nothrow

3.4.4. ReadableStreamClose ( stream ) nothrow

3.4.5. ReadableStreamError ( stream , e ) nothrow

3.4.6. ReadableStreamFulfillReadIntoRequest ( stream , chunk , done ) nothrow

3.4.7. ReadableStreamFulfillReadRequest ( stream , chunk , done ) nothrow

3.4.8. ReadableStreamGetNumReadIntoRequests ( stream ) nothrow

3.4.9. ReadableStreamGetNumReadRequests ( stream ) nothrow

3.4.10. ReadableStreamHasBYOBReader ( stream ) nothrow

3.4.11. ReadableStreamHasDefaultReader ( stream ) nothrow

3.5. Class ReadableStreamDefaultReader

The ReadableStreamDefaultReader class represents a default reader designed to be vended by a ReadableStream instance.

3.5.1. Class Definition

class ReadableStreamDefaultReader {
  constructor(stream)
  get closed()
  cancel(reason)
  read()
  releaseLock()
}

3.5.2. Internal Slots

Instances of ReadableStreamDefaultReader are created with the internal slots described in the following table:

3.5.3. new ReadableStreamDefaultReader( stream )

3.5.4. Properties of the ReadableStreamDefaultReader Prototype

3.5.4.1. get closed

3.5.4.2. cancel( reason )

3.5.4.3. read()

3.5.4.4. releaseLock()

3.6. Class ReadableStreamBYOBReader

The ReadableStreamBYOBReader class represents a BYOB reader designed to be vended by a ReadableStream instance.

3.6.1. Class Definition

class ReadableStreamBYOBReader {
  constructor(stream)
  get closed()
  cancel(reason)
  read(view)
  releaseLock()
}

3.6.2. Internal Slots

Instances of ReadableStreamBYOBReader are created with the internal slots described in the following table:

3.6.3. new ReadableStreamBYOBReader( stream )

3.6.4. Properties of the ReadableStreamBYOBReader Prototype

3.6.4.1. get closed

3.6.4.2. cancel( reason )

3.6.4.3. read( view )

3.6.4.4. releaseLock()

3.7. Readable Stream Reader Abstract Operations

3.7.1. IsReadableStreamDefaultReader ( x ) nothrow

3.7.2. IsReadableStreamBYOBReader ( x ) nothrow

3.7.3. ReadableStreamReaderGenericCancel ( reader , reason ) nothrow

3.7.4. ReadableStreamReaderGenericInitialize ( reader , stream ) nothrow

3.7.5. ReadableStreamReaderGenericRelease ( reader ) nothrow

3.7.6. ReadableStreamBYOBReaderRead ( reader , view ) nothrow

3.7.7. ReadableStreamDefaultReaderRead ( reader ) nothrow

3.8. Class ReadableStreamDefaultController

The ReadableStreamDefaultController class has methods that allow control of a ReadableStream 's state and internal queue . When constructing a ReadableStream that is not a readable byte stream , the underlying source is given a corresponding ReadableStreamDefaultController instance to manipulate.

3.8.1. Class Definition

class ReadableStreamDefaultController {
  constructor(stream, underlyingSource, size, highWaterMark)
  get desiredSize()
  close()
  enqueue(chunk)
  error(e)
}

3.8.2. Internal Slots

Instances of ReadableStreamDefaultController are created with the internal slots described in the following table:

3.8.3. new ReadableStreamDefaultController( stream , underlyingSource , size , highWaterMark )

3.8.4. Properties of the ReadableStreamDefaultController Prototype

3.8.4.1. get desiredSize

3.8.4.2. close()

3.8.4.3. enqueue( chunk )

3.8.4.4. error( e )

3.8.5. Readable Stream Default Controller Internal Methods

The following are additional internal methods implemented by each ReadableStreamDefaultController instance. The readable stream implementation will polymorphically call to either these or their counterparts for BYOB controllers.

3.8.5.1. [[CancelSteps]] ( reason )

3.8.5.2. [[PullSteps]] ()

3.9. Readable Stream Default Controller Abstract Operations

3.9.1. IsReadableStreamDefaultController ( x ) nothrow

3.9.2. ReadableStreamDefaultControllerCallPullIfNeeded ( controller ) nothrow

3.9.3. ReadableStreamDefaultControllerShouldCallPull ( controller ) nothrow

3.9.4. ReadableStreamDefaultControllerClose ( controller ) nothrow

This abstract operation can be called by other specifications that wish to close a readable stream, in the same way a developer-created stream would be closed by its associated controller object. Specifications should not do this to streams they did not create, and must ensure they have obeyed the preconditions (listed here as asserts).

3.9.5. ReadableStreamDefaultControllerEnqueue ( controller , chunk ) throws

This abstract operation can be called by other specifications that wish to enqueue chunks in a readable stream, in the same way a developer would enqueue chunks using the stream’s associated controller object. Specifications should not do this to streams they did not create, and must ensure they have obeyed the preconditions (listed here as asserts).

3.9.6. ReadableStreamDefaultControllerError ( controller , e ) nothrow

This abstract operation can be called by other specifications that wish to move a readable stream to an errored state, in the same way a developer would error a stream using its associated controller object. Specifications should not do this to streams they did not create, and must ensure they have obeyed the precondition (listed here as an assert).

3.9.7. ReadableStreamDefaultControllerErrorIfNeeded ( controller , e ) nothrow

3.9.8. ReadableStreamDefaultControllerGetDesiredSize ( controller ) nothrow

This abstract operation can be called by other specifications that wish to determine the desired size to fill this stream’s internal queue , similar to how a developer would consult the desiredSize property of the stream’s associated controller object. Specifications should not use this on streams they did not create.

3.9.9. ReadableStreamDefaultControllerHasBackpressure ( controller ) nothrow

This abstract operation is used in the implementation of TransformStream.

3.9.10. ReadableStreamDefaultControllerCanCloseOrEnqueue ( controller ) nothrow

3.10. Class ReadableByteStreamController

The ReadableByteStreamController class has methods that allow control of a ReadableStream 's state and internal queue . When constructing a ReadableStream , the underlying byte source is given a corresponding ReadableByteStreamController instance to manipulate.

3.10.1. Class Definition

class ReadableByteStreamController {
  constructor(stream, underlyingByteSource, highWaterMark)
  get byobRequest()
  get desiredSize()
  close()
  enqueue(chunk)
  error(e)
}

3.10.2. Internal Slots

Instances of ReadableByteStreamController are created with the internal slots described in the following table:

3.10.3. new ReadableByteStreamController( stream , underlyingByteSource , highWaterMark )

3.10.4. Properties of the ReadableByteStreamController Prototype

3.10.4.1. get byobRequest

3.10.4.2. get desiredSize

3.10.4.3. close()

3.10.4.4. enqueue( chunk )

3.10.4.5. error( e )

3.10.5. Readable Stream BYOB Controller Internal Methods

The following are additional internal methods implemented by each ReadableByteStreamController instance. The readable stream implementation will polymorphically call to either these or their counterparts for default controllers.

3.10.5.1. [[CancelSteps]] ( reason )

3.10.5.2. [[PullSteps]] ()

3.11. Class ReadableStreamBYOBRequest

The ReadableStreamBYOBRequest class represents a pull into request in a ReadableByteStreamController .

3.11.1. Class Definition

class ReadableStreamBYOBRequest {
  constructor(controller, view)
  get view()
  respond(bytesWritten)
  respondWithNewView(view)
}

3.11.2. Internal Slots

Instances of ReadableStreamBYOBRequest are created with the internal slots described in the following table:

3.11.3. new ReadableStreamBYOBRequest( controller , view )

3.11.4. Properties of the ReadableStreamBYOBRequest Prototype

3.11.4.1. get view

3.11.4.2. respond( bytesWritten )

3.11.4.3. respondWithNewView( view )

3.12. Readable Stream BYOB Controller Abstract Operations

3.12.1. IsReadableStreamBYOBRequest ( x ) nothrow

3.12.2. IsReadableByteStreamController ( x ) nothrow

3.12.3. ReadableByteStreamControllerCallPullIfNeeded ( controller ) nothrow

3.12.4. ReadableByteStreamControllerClearPendingPullIntos ( controller ) nothrow

3.12.5. ReadableByteStreamControllerClose ( controller ) throws

3.12.6. ReadableByteStreamControllerCommitPullIntoDescriptor ( stream , pullIntoDescriptor ) nothrow

3.12.7. ReadableByteStreamControllerConvertPullIntoDescriptor ( pullIntoDescriptor ) nothrow

3.12.8. ReadableByteStreamControllerEnqueue ( controller , chunk ) nothrow

3.12.9. ReadableByteStreamControllerEnqueueChunkToQueue ( controller , buffer , byteOffset , byteLength ) nothrow

3.12.10. ReadableByteStreamControllerError ( controller , e ) nothrow

3.12.11. ReadableByteStreamControllerFillHeadPullIntoDescriptor ( controller , size , pullIntoDescriptor ) nothrow

3.12.12. ReadableByteStreamControllerFillPullIntoDescriptorFromQueue ( controller , pullIntoDescriptor ) nothrow

3.12.13. ReadableByteStreamControllerGetDesiredSize ( controller ) nothrow

3.12.14. ReadableByteStreamControllerHandleQueueDrain ( controller ) nothrow

3.12.15. ReadableByteStreamControllerInvalidateBYOBRequest ( controller ) nothrow

3.12.16. ReadableByteStreamControllerProcessPullIntoDescriptorsUsingQueue ( controller ) nothrow

3.12.17. ReadableByteStreamControllerPullInto ( controller , view ) nothrow

3.12.18. ReadableByteStreamControllerRespond ( controller , bytesWritten ) throws

3.12.19. ReadableByteStreamControllerRespondInClosedState ( controller , firstDescriptor ) nothrow

3.12.20. ReadableByteStreamControllerRespondInReadableState ( controller , bytesWritten , pullIntoDescriptor ) throws

3.12.21. ReadableByteStreamControllerRespondInternal ( controller , bytesWritten ) throws

3.12.22. ReadableByteStreamControllerRespondWithNewView ( controller , view ) throws

3.12.23. ReadableByteStreamControllerShiftPendingPullInto ( controller ) nothrow

3.12.24. ReadableByteStreamControllerShouldCallPull ( controller ) nothrow

4. Writable Streams

4.1. Using Writable Streams

readableStream.pipeTo(writableStream)
  .then(() => console.log("All data successfully written!"))
  .catch(e => console.error("Something went wrong!", e));

function writeArrayToStream(array, writableStream) {
  const writer = writableStream.getWriter();
  array.forEach(chunk => writer.write(chunk));
  return writer.close();
}
writeArrayToStream([1, 2, 3, 4, 5], writableStream)
  .then(() => console.log("All done!"))
  .catch(e => console.error("Error with the stream: " + e));

writer.write("i am a chunk of data")
  .then(() => console.log("chunk successfully written!"))
  .catch(e => console.error(e));

async function writeRandomBytesForever(writableStream) {
  const writer = writableStream.getWriter();
  while (true) {
    await writer.ready;
    const bytes = new Uint8Array(writer.desiredSize);
    window.crypto.getRandomValues(bytes);
    await writer.write(bytes);
  }
}
writeRandomBytesForever(myWritableStream).catch(e => console.error("Something broke", e));

4.2. Class WritableStream

4.2.1. Class Definition

class WritableStream {
  constructor(underlyingSink = {}, { size, highWaterMark = 1 } = {})
  get locked()
  abort(reason)
  getWriter()
}

4.2.2. Internal Slots

Instances of WritableStream are created with the internal slots described in the following table:

The [[inFlightCloseRequest]] slot and [[closeRequest]] slot are mutually exclusive. Similarly, no element will be removed from [[writeRequests]] while [[inFlightWriteRequest]] is not undefined . Implementations can optimize storage for these slots based on these invariants.

4.2.3. new WritableStream( underlyingSink = {}, { size , highWaterMark = 1 } = {})

4.2.4. Properties of the WritableStream Prototype

4.2.4.1. get locked

4.2.4.2. abort( reason )

4.2.4.3. getWriter()

4.3. General Writable Stream Abstract Operations

The following abstract operations, unlike most in this specification, are meant to be generally useful by other specifications, instead of just being part of the implementation of this spec’s classes.

4.3.1. AcquireWritableStreamDefaultWriter ( stream ) throws

4.3.2. IsWritableStream ( x ) nothrow

4.3.3. IsWritableStreamLocked ( stream ) nothrow

This abstract operation is meant to be called from other specifications that may wish to query whether or not a writable stream is locked to a writer .

4.3.4. WritableStreamAbort ( stream , reason ) nothrow

4.4. Writable Stream Abstract Operations Used by Controllers

To allow future flexibility to add different writable stream behaviors (similar to the distinction between default readable streams and readable byte streams ), much of the internal state of a writable stream is encapsulated by the WritableStreamDefaultController class.

The abstract operations in this section are interfaces that are used by the controller implementation to affect its associated WritableStream object, translating the controller’s internal state changes into developer-facing results visible through the WritableStream 's public API.

4.4.1. WritableStreamAddWriteRequest ( stream ) nothrow

4.4.2. WritableStreamDealWithRejection ( stream , error ) nothrow

4.4.3. WritableStreamStartErroring ( stream , reason ) nothrow

4.4.4. WritableStreamFinishErroring ( stream ) nothrow

4.4.5. WritableStreamFinishInFlightWrite ( stream ) nothrow

4.4.6. WritableStreamFinishInFlightWriteWithError ( stream , error ) nothrow

4.4.7. WritableStreamFinishInFlightClose ( stream ) nothrow

4.4.8. WritableStreamFinishInFlightCloseWithError ( stream , error ) nothrow

4.4.9. WritableStreamCloseQueuedOrInFlight ( stream ) nothrow

4.4.10. WritableStreamHasOperationMarkedInFlight ( stream ) nothrow

4.4.11. WritableStreamMarkCloseRequestInFlight ( stream ) nothrow

4.4.12. WritableStreamMarkFirstWriteRequestInFlight ( stream ) nothrow

4.4.13. WritableStreamRejectCloseAndClosedPromiseIfNeeded ( stream ) nothrow

4.4.14. WritableStreamUpdateBackpressure ( stream , backpressure ) nothrow

4.5. Class WritableStreamDefaultWriter

The WritableStreamDefaultWriter class represents a writable stream writer designed to be vended by a WritableStream instance.

4.5.1. Class Definition

class WritableStreamDefaultWriter {
  constructor(stream)
  get closed()
  get desiredSize()
  get ready()
  abort(reason)
  close()
  releaseLock()
  write(chunk)
}

4.5.2. Internal Slots

Instances of WritableStreamDefaultWriter are created with the internal slots described in the following table:

4.5.3. new WritableStreamDefaultWriter( stream )

4.5.4. Properties of the WritableStreamDefaultWriter Prototype

4.5.4.1. get closed

4.5.4.2. get desiredSize

4.5.4.3. get ready

4.5.4.4. abort( reason )

4.5.4.5. close()

4.5.4.6. releaseLock()

4.5.4.7. write( chunk )

4.6. Writable Stream Writer Abstract Operations

4.6.1. IsWritableStreamDefaultWriter ( x ) nothrow

4.6.2. WritableStreamDefaultWriterAbort ( writer , reason ) nothrow

4.6.3. WritableStreamDefaultWriterClose ( writer ) nothrow

4.6.4. WritableStreamDefaultWriterCloseWithErrorPropagation ( writer ) nothrow

This abstract operation helps implement the error propagation semantics of pipeTo() .

4.6.5. WritableStreamDefaultWriterEnsureClosedPromiseRejected( writer , error ) nothrow

4.6.6. WritableStreamDefaultWriterEnsureReadyPromiseRejected( writer , error ) nothrow

4.6.7. WritableStreamDefaultWriterGetDesiredSize ( writer ) nothrow

4.6.8. WritableStreamDefaultWriterRelease ( writer ) nothrow

4.6.9. WritableStreamDefaultWriterWrite ( writer , chunk ) nothrow

4.7. Class WritableStreamDefaultController

The WritableStreamDefaultController class has methods that allow control of a WritableStream 's state. When constructing a WritableStream , the underlying sink is given a corresponding WritableStreamDefaultController instance to manipulate.

4.7.1. Class Definition

class WritableStreamDefaultController {
  constructor(stream, underlyingSink, size, highWaterMark)
  error(e)
}

4.7.2. Internal Slots

Instances of WritableStreamDefaultController are created with the internal slots described in the following table:

4.7.3. new WritableStreamDefaultController( stream , underlyingSink , size , highWaterMark )

4.7.4. Properties of the WritableStreamDefaultController Prototype

4.7.4.1. error( e )

4.7.5. Writable Stream Default Controller Internal Methods

The following are additional internal methods implemented by each WritableStreamDefaultController instance. The writable stream implementation will call into these.

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, where there actually are multiple controller types and as such the counterpart internal methods are used polymorphically.

4.7.5.1. [[AbortSteps]]( reason )

4.7.5.2. [[ErrorSteps]]()

4.7.5.3. [[StartSteps]]()

4.8. Writable Stream Default Controller Abstract Operations

4.8.1. IsWritableStreamDefaultController ( x ) nothrow

4.8.2. WritableStreamDefaultControllerClose ( controller ) nothrow

4.8.3. WritableStreamDefaultControllerGetChunkSize ( controller , chunk ) nothrow

4.8.4. WritableStreamDefaultControllerGetDesiredSize ( controller ) nothrow

4.8.5. WritableStreamDefaultControllerWrite ( controller , chunk , chunkSize ) nothrow

4.8.6. WritableStreamDefaultControllerAdvanceQueueIfNeeded ( controller ) nothrow

4.8.7. WritableStreamDefaultControllerErrorIfNeeded ( controller , error ) nothrow

4.8.8. WritableStreamDefaultControllerProcessClose ( controller ) nothrow

4.8.9. WritableStreamDefaultControllerProcessWrite ( controller , chunk ) nothrow

4.8.10. WritableStreamDefaultControllerGetBackpressure ( controller ) nothrow

4.8.11. WritableStreamDefaultControllerError ( controller , error ) nothrow

5. Transform Streams

5.1. Using Transform Streams

readableStream  .pipeThrough(transformStream)  .pipeTo(writableStream)  .then(() => console.log("All data successfully transformed!"))  .catch(e => console.error("Something went wrong!", e));

const writer = transformStream.writable.getWriter();
writer.write("input chunk");
transformStream.readable.pipeTo(anotherWritableStream);

const { writable, readable } = new TransformStream();
fetch("...", { body: readable }).then(response => /* ... */);
writable.write(new Uint8Array([0x73, 0x74, 0x72, 0x65, 0x61, 0x6D, 0x73, 0x21]));
writable.close();

const writableStrategy = new ByteLengthQueuingStrategy({ highWaterMark: 1024 * 1024 });
readableStream
  .pipeThrough(new TransformStream(undefined, writableStrategy))  .pipeTo(writableStream);

5.2. Class TransformStream

5.2.1. Class Definition