ReadableStreamBYOBRequest extension type

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).

ReadableStreamBYOBRequest objects are created in "BYOB mode" when a consumer makes a request for data and the stream's internal queue is empty. (The stream will resolve the consumer's request directly if it already has buffered data). An underlying byte source can access active BYOB requests through its controller's ReadableByteStreamController.byobRequest property, which will be set to null if there is no outstanding request.

An underlying source that supports "BYOB mode" should check for ReadableByteStreamController.byobRequest and must use it for transferring data, if present. If data arrives from the underlying source when ReadableByteStreamController.byobRequest is null, it can be queued using ReadableByteStreamController.enqueue. This might happen when an underlying push source receives new data when the stream's internal buffers are not empty.

An underlying source uses the request by writing data to the BYOB request's view and then calling respond(), or by calling respondWithNewView() and passing a new view as an argument. Note that the "new view" must actually be a view over the same buffer as the original view, starting at the same offset. This might be used to return a shorter buffer if the underlying source is unable to fill the entire original view.

Note that a ReadableByteStreamController is only created for underlying sources when type="bytes" is specified for the source in the ReadableStream() constructor. "BYOB mode" is enabled when either autoAllocateChunkSize is specified in the ReadableController() constructor or when using a ReadableStreamBYOBReader (typically constructed by calling ReadableStream.getReader with the argument { mode: 'byob' }).