ReadableStream

The ReadableStream interface of the Streams API represents a readable stream of byte data. The Fetch API offers a concrete instance of a ReadableStream through the body property of a Response object.

Constructor

ReadableStream()

Creates and returns a readable stream object from the given handlers.

Properties

ReadableStream.locked Read only

The locked getter returns whether or not the readable stream is locked to a reader.

Methods

ReadableStream.cancel()

Cancels the stream, signaling 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.

ReadableStream.getIterator()

Creates a ReadableStream async iterator instance and locks the stream to it. While the stream is locked, no other reader can be acquired until this one is released.

ReadableStream.getReader()

Creates a reader and locks the stream to it. While the stream is locked, no other reader can be acquired until this one is released.

ReadableStream.pipeThrough()

Provides a chainable way of piping the current stream through a transform stream or any other writable/readable pair.

ReadableStream.pipeTo()

Pipes the current ReadableStream to a given WritableStream and returns a promise that fulfills when the piping process completes successfully, or rejects if any errors were encountered.

ReadableStream.tee()

The tee method tees this readable stream, returning a two-element array containing the two resulting branches as new ReadableStream instances. Each of those streams receives the same incoming data.

ReadableStream[@@asyncIterator]()

Alias of getIterator method.

Examples

In the following example, an artificial Response is created to stream HTML fragments fetched from another resource to the browser.

It demonstrates the usage of a ReadableStream in combination with a Uint8Array.

fetch("https://www.example.org/").then((response) => {
  const reader = response.body.getReader();
  const stream = new ReadableStream({
    start(controller) {
      // The following function handles each data chunk
      function push() {
        // "done" is a Boolean and value a "Uint8Array"
        reader.read().then(({ done, value }) => {
          // Is there no more data to read?
          if (done) {
            // Tell the browser that we have finished sending data
            controller.close();
            return;
          }

          // Get the data and send it to the browser via the controller
          controller.enqueue(value);
          push();
        });
      };
      
      push();
    }
  });

  return new Response(stream, { headers: { "Content-Type": "text/html" } });
});

Specifications

Browser compatibility

See Also

• WHATWG Stream Visualiser, for a basic visualisation of readable, writable, and transform streams.