ReadableStreamBYOBReader

The ReadableStreamBYOBReader from the Stream APIs outlines a reader for a ReadableStream that facilitates zero-copy reading from a byte source. This is utilized for efficient data transfer from sources that present the data as a series of anonymous bytes, such as files.

BYOB stands for “Bring Your Own Buffer”.

Constructor

ReadableStreamBYOBReader() Creates and returns a ReadableStreamBYOBReader object instance.

Instance properties

ReadableStreamBYOBReader.closed Returns a Promise that fulfills when the stream closes, or rejects if the stream throws an error or the reader’s lock is released. This property enables you to write code that responds to an end to the streaming process.

Instance methods

ReadableStreamBYOBReader.cancel() Returns a Promise that resolves when the stream is canceled. Calling this method signals a loss of interest in the stream by a consumer. The supplied reason argument will be given to the underlying source, which may or may not use it.

ReadableStreamBYOBReader.read() Passes a view into which data must be written, and returns a Promise that resolves with the next chunk in the stream or rejects with an indication that the stream is closed or has errored.

ReadableStreamBYOBReader.releaseLock() Releases the reader’s lock on the stream.

Examples

First create the reader using ReadableStream.getReader() on the stream, specifying mode: “byob” in the options parameter.

  const reader = stream.getReader({ mode: "byob" });
  let buffer = new ArrayBuffer(4000);

A function that uses the reader is shown below.

  readStream(reader);

  function readStream(reader) {
    let bytesReceived = 0;
    let offset = 0;

    while (offset < buffer.byteLength) {
      // read() returns a promise that resolves when a value has been received
      reader.read(new Uint8Array(buffer, offset, buffer.byteLength - offset))
        .then(function processBytes({ done, value }) {
          // Result objects contain two properties:
          // done  - true if the stream has already given all its data.
          // value - some data. Always undefined when done is true.

          if (done) {
            // There is no more data in the stream
            return;
          }

          buffer = value.buffer;
          offset += value.byteLength;
          bytesReceived += value.byteLength;

          // Read some more, and call this function again
          return reader.read(new Uint8Array(buffer, offset, buffer.byteLength - offset)).then(processBytes);
        });
    }
  }

For more information on ReadableStreamBYOBReader visit MDN Web Docs.