ReadableStreamBYOBReader: read() method

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 in Web Workers.

The read() method of the ReadableStreamBYOBReader interface is used to read data into a view on a user-supplied buffer from an associated readable byte stream. A request for data will be satisfied from the stream's internal queues if there is any data present. If the stream queues are empty, the request may be supplied as a zero-copy transfer from the underlying byte source.

The method takes as an argument a view on a buffer that supplied data is to be read into, and returns a Promise. The promise fulfills with an object that has properties value and done when data comes available, or if the stream is cancelled. If the stream is errored, the promise will be rejected with the relevant error object.

When a chunk of data is supplied, the value property will contain a new view. This will be a view over the same buffer/backing memory (and of the same type) as the original view passed to the read() method, now populated with the new chunk of data. Note that once the promise fulfills, the original view passed to the method will be detached and no longer usable. The promise will fulfill with a value: undefined if the stream has been cancelled. In this case the backing memory region of view is discarded and not returned to the caller (all previously read data in the view's buffer is lost).

The done property indicates whether or not more data is expected. The value is set true if the stream is closed or cancelled, and false otherwise.

The method also has an optional options.min argument that can be used to specify the minimum number of elements that must be available before the promise will fulfill, while the stream is active. The view returned in the value property will always have at least this number of elements, except when the stream is closed.

Syntax

js
read(view)
read(view, options)

Parameters

view

The view that data is to be read into.

options Optional

Options are as follows:

min

The minimum number of elements to read before the promise will fulfill while the stream is active. If not given, the promise will resolve with at least one element, up to the maximum size of the view. This number must not be bigger than the view that is being read into.

Return value

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.

Exceptions

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, options.min is 0, or ReadableStreamBYOBReader.releaseLock() is called (when there's a pending read request).

RangeError

The options.min value is larger than the view being written into.

Examples

Reading into a view

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.

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

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

Reading a minimum number of elements

This example is almost exactly the same as the previous one, except that we've modified the code to read a minimum of 101 elements on each iteration.

We've also made it into a live example. Note that most of the code is not relevant to the example and is therefore hidden. For more information see Using readable byte streams.

JavaScript

js
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), {
        min: 101,
      })
      .then(async function processText({ 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) {
          logConsumer(
            `readStream() complete. Read ${value.byteLength} bytes (total: ${bytesReceived})`,
          );
          return;
        }

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

        //logConsumer(`Read ${bytesReceived} bytes: ${value}`);
        logConsumer(`Read ${value.byteLength} bytes (total: ${bytesReceived})`);
        result += value;

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

Result

The logging from the underlying push source (left) and consumer (right) are shown below. Note that if the browser supports the options.min argument then at least 101 elements are returned every time (and often more), except when the stream closes.

Specifications

Specification
Streams Standard
# ref-for-byob-reader-read③

Browser compatibility

BCD tables only load in the browser

See also