Newly available Newly available. Verify your target environments before adopting.

Readable byte streams

The ReadableByteStreamController interface of the Streams API represents a controller for a readable byte stream. It allows control of the state and internal queue of a ReadableStream with an underlying byte source, and enables efficient zero-copy transfer of data from the underlying source to a consumer when the stream's internal queue is empty.

An instance of this controller type is created if an underlyingSource object with the property type="bytes" is passed as an argument to the ReadableStream() constructor. The underlyingSource object may also define start() and pull() callback functions. These are called with the controller as a parameter, in order to set up the underlying source, and request data when needed.

The underlying source uses the controller to supply data to the stream via its byobRequest property or enqueue() method. byobRequest is a ReadableStreamBYOBRequest object that represents a pending request from a consumer to make a zero-copy transfer of data direct to a consumer. byobRequest must be used to copy data if it exists (do not use enqueue() in this case)! If the underlying source needs to pass data to the stream and byobRequest is null then the source can call enqueue() to add the data to the stream's internal queues.

Note that the byobRequest is only created in "BYOB mode" when there is a request from a reader and the stream's internal queue is empty. "BYOB mode" is enabled when using a ReadableStreamBYOBReader (typically constructed by calling ReadableStream.getReader() with the argument { mode: 'byob' }). It is also enabled when using a default reader and autoAllocateChunkSize is specified in the ReadableStream() constructor.

An underlying byte source can also use the controller to close() the stream when all the data has been sent and report errors from the underlying source using error(). The controller's desiredSize property is used to apply "backpressure", informing the underlying source of the size of the internal queue (small values indicate that the queue is filling up, hinting to the underlying source that it is be desirable to pause or throttle the inflow).

Note that even though the controller is primarily used by the underlying byte source, there is no reason it cannot be stored used by other parts of the system to signal the stream.

Files, Clipboard and Streams

Browser support

Feature	Desktop				Mobile
Feature	Chrome	Edge	Firefox	Safari	Chrome Android	Safari iOS
`ReadableByteStreamController`	89	89	102	26.4	89	26.4
`byobRequest` The byobRequest read-only property of the ReadableByteStreamController interface returns the current BYOB request, or null if there are no pending requests.	89	89	102	26.4	89	26.4
`close` The close() method of the ReadableByteStreamController interface closes the associated stream.	89	89	102	26.4	89	26.4
`desiredSize` The desiredSize read-only property of the ReadableByteStreamController interface returns the number of bytes required to fill the stream's internal queue to its "desired size".	89	89	102	26.4	89	26.4
`enqueue` The enqueue() method of the ReadableByteStreamController interface enqueues a given chunk on the associated readable byte stream (the chunk is transferred into the stream's internal queues).	89	89	102	26.4	89	26.4
`error` The error() method of the ReadableByteStreamController interface causes any future interactions with the associated stream to error with the specified reason.	89	89	102	26.4	89	26.4
`ReadableStreamBYOBReader` The ReadableStreamBYOBReader interface of the Streams API defines a reader for a ReadableStream that supports zero-copy reading from an underlying byte source. It is used for efficient copying from underlying sources where the data is delivered as an "anonymous" sequence of bytes, such as files.	89	89	102	26.4	89	26.4
`cancel` The cancel() method of the ReadableStreamBYOBReader interface returns a Promise that resolves when the stream is canceled. Calling this method signals a loss of interest in the stream by a consumer.	89	89	102	26.4	89	26.4
`closed` The closed read-only property of the ReadableStreamBYOBReader interface returns a Promise that fulfills when the stream closes, or rejects if the stream throws an error or the reader's lock is released.	89	89	102	26.4	89	26.4
`read` The read() method of the ReadableStreamBYOBReader interface is used to read data into a view on a user-supplied buffer from an associated readable byte stream. A request for data will be satisfied from the stream's internal queues if there is any data present. If the stream queues are empty, the request may be supplied as a zero-copy transfer from the…	89	89	102	26.4	89	26.4
`read (options min parameter)` `options.min` parameter	140	140	134		140
`ReadableStreamBYOBReader` The ReadableStreamBYOBReader() constructor creates and returns a ReadableStreamBYOBReader object instance.	89	89	102	26.4	89	26.4
`releaseLock` The releaseLock() method of the ReadableStreamBYOBReader interface releases the reader's lock on the stream. After the lock is released, the reader is no longer active.	89	89	102	26.4	89	26.4
`releaseLock (reject pending read request)` `releaseLock()` rejects pending read requests	105	105	102		105
`ReadableStreamBYOBRequest` The ReadableStreamBYOBRequest interface of the Streams API represents a "pull request" for data from an underlying source that will made as a zero-copy transfer to a consumer (bypassing the stream's internal queues).	89	89	102	26.4	89	26.4
`respond` The respond() method of the ReadableStreamBYOBRequest interface is used to signal to the associated readable byte stream that the specified number of bytes were written into the ReadableStreamBYOBRequest.view.	89	89	102	26.4	89	26.4
`respondWithNewView` The respondWithNewView() method of the ReadableStreamBYOBRequest interface specifies a new view that the consumer of the associated readable byte stream should write to instead of ReadableStreamBYOBRequest.view.	89	89	102	26.4	89	26.4
`view` The view getter property of the ReadableStreamBYOBRequest interface returns the current view.	89	89	102	26.4	89	26.4

1+Supported (version) Not supported ※Has note Sub-feature descriptions sourced from MDN Web Docs (CC BY-SA 2.5)

Use cases

Using Readable byte streams

The ReadableByteStreamController interface of the Streams API represents a controller for a readable byte stream.

Cautions

May not be supported in older browsers.

Implementation notes

Some APIs require a secure context (HTTPS) or user activation. Check the requirements before use.

Browser support

Use cases

Using Readable byte streams

Cautions

Implementation notes

Related links