ReadableStreamBYOBReader
Last update：2024-08-14 19:50:28
ReadableStreamBYOBReader
The ReadableStreamBYOBReader interface is used for readable stream operations and is based on the Web APIs standard ReadableStreamBYOBReader design. BYOB (Bring Your Own Buffer) means that data can be read from the stream into a user-provided buffer, thereby minimizing data copying and improving performance.
Note:
ReadableStreamBYOBReader objects cannot be directly constructed. You need to use the ReadableStream.getReader method to obtain one.
ReadableStreamBYOBReader instances are functionally identical to ReadableStreamDefaultReader except for the read method.
ReadableStreamBYOBReader is not instantiated via its constructor. Instead, it is retrieved from a ReadableStream:
const { readable, writable } = new TransformStream();
const reader = readable.getReader({ mode: 'byob' });
Methods
read(bufferArrayBufferView)
reader.read(bufferArrayBufferView: ArrayBufferView): Promise<ReadableStreamBYOBReadResult>
Parameters:
bufferArrayBufferView: AnArrayBufferViewrepresenting the developer-provided buffer view used to store the read data.
Return Value: Returns a Promise<ReadableStreamBYOBReadResult> object containing the result after the next available chunk of data is read into the passed-in buffer.
Description: Reads the next available chunk of data from the stream into the passed-in buffer and returns a Promise object.
Note:
The read method offers no control over the minimum number of bytes that should be read into the buffer. Even if you allocate a 1 MiB buffer, the kernel is perfectly within its rights to fulfill this read with a single byte, whether or not an EOF immediately follows.
In practice, the Workers team has found that read typically fills only 1% of the provided buffer.
readAtLeast(minBytes, bufferArrayBufferView)
reader.readAtLeast(minBytes: number, bufferArrayBufferView: ArrayBufferView): Promise<ReadableStreamBYOBReadResult>
Parameters:
minBytes: Anumberrepresenting the minimum number of bytes to be read.bufferArrayBufferView: AnArrayBufferViewrepresenting the developer-provided buffer view used to store the read data.
Return Value: Returns a Promise<ReadableStreamBYOBReadResult> object containing the result after the next available chunk of data is read into the passed-in buffer.
Description: Reads the next available chunk of data from the stream into the passed-in buffer and returns a Promise object. The Promise object will only resolve after at least minBytes bytes have been read.
readAtLeast is a non-standard extension to the Streams API that allows users to specify that at least minBytes bytes must be read into the buffer before resolving the read operation.
Properties
locked
- Type:
boolean(read-only) - Description: Indicates whether the readable stream is locked to the reader.
Methods
cancel()
reader.cancel(reason?: string): Promise<string>;
Parameters:
reason(optional): Astringrepresenting the reason for canceling the read operation.
Description: Closes the stream and ends the read operation.
Return Value: Returns a Promise object containing the cancellation reason string when the status is fulfilled.
releaseLock()
reader.releaseLock(): void;
Description: Cancels the association with the stream and releases the lock on the stream.