ReadableStream: ReadableStream() constructor

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since January 2020.

Note: This feature is available in Web Workers.

The ReadableStream() constructor creates and returns a readable stream object from the given handlers.

Note that while all parameters are technically optional, omitting the underlyingSource will result in a stream that has no source, and that can't be read from (readers return a promise that will never be resolved).

Syntax

js
new ReadableStream()
new ReadableStream(underlyingSource)
new ReadableStream(underlyingSource, queuingStrategy)

Parameters

underlyingSource Optional

An object containing methods and properties that define how the constructed stream instance will behave. underlyingSource can contain the following:

start (controller) Optional

This is a method, called immediately when the object is constructed. The contents of this method are defined by the developer, and should aim to get access to the stream source, and do anything else required to set up the stream functionality. If this process is to be done asynchronously, it can return a promise to signal success or failure. The controller parameter passed to this method is a ReadableStreamDefaultController or a ReadableByteStreamController, depending on the value of the type property. This can be used by the developer to control the stream during set up.

pull (controller) Optional

This method, also defined by the developer, will be called repeatedly when the stream's internal queue of chunks is not full, up until it reaches its high water mark. If pull() returns a promise, then it won't be called again until that promise fulfills; if the promise rejects, the stream will become errored. The controller parameter passed to this method is a ReadableStreamDefaultController or a ReadableByteStreamController, depending on the value of the type property. This can be used by the developer to control the stream as more chunks are fetched. This function will not be called until start() successfully completes. Additionally, it will only be called repeatedly if it enqueues at least one chunk or fulfills a BYOB request; a no-op pull() implementation will not be continually called.

cancel (reason) Optional

This method, also defined by the developer, will be called if the app signals that the stream is to be cancelled (e.g., if ReadableStream.cancel() is called). The contents should do whatever is necessary to release access to the stream source. If this process is asynchronous, it can return a promise to signal success or failure. The reason parameter contains a string describing why the stream was cancelled.

type Optional

This property controls what type of readable stream is being dealt with. If it is included with a value set to "bytes", the passed controller object will be a ReadableByteStreamController capable of handling a BYOB (bring your own buffer)/byte stream. If it is not included, the passed controller will be a ReadableStreamDefaultController.

autoAllocateChunkSize Optional

For byte streams, the developer can set the autoAllocateChunkSize with a positive integer value to turn on the stream's auto-allocation feature. With this is set, the stream implementation will automatically allocate a view buffer of the specified size in ReadableByteStreamController.byobRequest when required.

This must be set to enable zero-copy transfers to be used with a default ReadableStreamDefaultReader. If not set, a default reader will still stream data, but ReadableByteStreamController.byobRequest will always be null and transfers to the consumer must be via the stream's internal queues.

queuingStrategy Optional

An object that optionally defines a queuing strategy for the stream. This takes two parameters:

highWaterMark

A non-negative integer — this defines the total size of all chunks that can be contained in the internal queue before backpressure is applied.

size(chunk)

A method containing a parameter chunk — this indicates the size to use for each chunk, in bytes.

Note: You could define your own custom queuingStrategy, or use an instance of ByteLengthQueuingStrategy or CountQueuingStrategy for this object value. If no queuingStrategy is supplied, the default used is the same as a CountQueuingStrategy with a high water mark of 1.

Return value

An instance of the ReadableStream object.

Exceptions

RangeError

Thrown if the supplied type value is neither "bytes" nor undefined.

Examples

In the following simple example, a custom ReadableStream is created using a constructor (see our Simple random stream example for the full code). The start() function generates a random string of text every second and enqueues it into the stream. A cancel() function is also provided to stop the generation if ReadableStream.cancel() is called for any reason.

When a button is pressed, the generation is stopped, the stream is closed using ReadableStreamDefaultController.close(), and another function is run, which reads the data back out of the stream.

js
let interval;
const stream = new ReadableStream({
  start(controller) {
    interval = setInterval(() => {
      let string = randomChars();

      // Add the string to the stream
      controller.enqueue(string);

      // show it on the screen
      let listItem = document.createElement("li");
      listItem.textContent = string;
      list1.appendChild(listItem);
    }, 1000);

    button.addEventListener("click", () => {
      clearInterval(interval);
      fetchStream();
      controller.close();
    });
  },
  pull(controller) {
    // We don't really need a pull in this example
  },
  cancel() {
    // This is called if the reader cancels,
    // so we should stop generating strings
    clearInterval(interval);
  },
});