ReadableByteStreamController

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

Note: This feature is available inWeb Workers.

TheReadableByteStreamController interface of theStreams API represents a controller for areadable byte stream.It allows control of the state and internal queue of aReadableStream 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 anunderlyingSource object with the propertytype="bytes" is passed as an argument to theReadableStream() constructor.TheunderlyingSource object may also definestart() andpull() 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 itsbyobRequest property orenqueue() method.byobRequest is aReadableStreamBYOBRequest 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 useenqueue() in this case)!If the underlying source needs to pass data to the stream andbyobRequest isnull then the source can callenqueue() to add the data to the stream's internal queues.

Note that thebyobRequest 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 aReadableStreamBYOBReader (typically constructed by callingReadableStream.getReader() with the argument{ mode: 'byob' }).It is also enabled when using a default reader andautoAllocateChunkSize is specified in theReadableStream() constructor.

An underlying byte source can also use the controller toclose() the stream when all the data has been sent and report errors from the underlying source usingerror().The controller'sdesiredSize 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.

Constructor

None.ReadableByteStreamController instances are automatically created if anunderlyingSource with the propertytype="bytes" is passed to theReadableStream() constructor.

Instance properties

ReadableByteStreamController.byobRequestRead only: Returns the current BYOB pull request, ornull if there no outstanding request.
ReadableByteStreamController.desiredSizeRead only: Returns the desired size required to fill the stream's internal queue.

Instance methods

ReadableByteStreamController.close(): Closes the associated stream.
ReadableByteStreamController.enqueue(): Enqueues a given chunk in the associated stream.
ReadableByteStreamController.error(): Causes any future interactions with the associated stream to error.

Examples

The controller is used by an underlying source to transfer or enqueue data, to signal that the stream has no more data (has closed) or has errored. It is also used to signal the underlying source from "upstream" of the desired data rate, usingdesiredSize.

The example inUsing readable byte streams, in particularCreating a readable socket push byte stream, show most of these cases.