ReadableStreamBYOBReader: read() method

view

The view that data is to be read into.

A Promise, which fulfills/rejects with a result depending on the state of the stream.

The following are possible:

• If a chunk is available and the stream is still active, the promise fulfills with an object of the form:

  js

  { value: theChunk, done: false }
  

  theChunk is a view containing the new data. This is a view of the same type and over the same backing memory as the view passed to the read() method. The original view will be detached and no longer usable.

• If the stream is closed, the promise fulfills with an object of the form (where theChunk has the same properties as above):

  js

  { value: theChunk, done: true }
  

• If the stream is cancelled, the promise fulfills with an object of the form:

  js

  { value: undefined, done: true }
  

  In this case the backing memory is discarded.

• If the stream throws an error, the promise rejects with the relevant error.

TypeError

The source object is not a ReadableStreamBYOBReader, the stream has no owner, the view is not an object or has become detached, the view's length is 0, or ReadableStreamBYOBReader.releaseLock() is called (when there's is a pending read request).

The example code here is taken from the live examples in Using readable byte streams.

First we create the reader using ReadableStream.getReader() on the stream, specifying mode: "byob" in the options parameter. We also need create an ArrayBuffer, which is the "backing memory" of the views that we will write into.

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

A function that uses the reader is shown below. This calls the read() method recursively to read data into the buffer. The method takes a Uint8Array typed array which is a view over the part of the original array buffer that has not yet been written. The parameters of the view are calculated from the data that was received in previous calls, which define an offset into the original array buffer.

readStream(reader);

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

  while (offset < buffer.byteLength) {
    // read() returns a promise that fulfills 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. 'undefined' if the reader is canceled.

        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
        // Note that here we create a new view over the original buffer.
        return reader
          .read(new Uint8Array(buffer, offset, buffer.byteLength - offset))
          .then(processBytes);
      });
  }
}

When there is no more data in the stream, the read() method fulfills with an object with the property done set to true, and the function returns.

• ReadableStreamBYOBReader() constructor
• Using readable byte stream