The ReadableStream()
constructor creates and returns a readable stream object from the given handlers.
Syntax
var readableStream = new ReadableStream(underlyingSource[, queuingStrategy]);
Parameters
- underlyingSource
- An object containing methods and properties that define how the constructed stream instance will behave.
underlyingSource
can contain the following:- start(controller)
- 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 fuctionality. 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 aReadableStreamDefaultController
or aReadableByteStreamController
, depending on the value of thetype
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. Thecontroller
parameter passed to this method is aReadableStreamDefaultController
or aReadableByteStreamController
, depending on the value of thetype
property. This can be used by the developer to control the stream as more chunks are fetched. - 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. Thereason
parameter contains aDOMString
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 aReadableByteStreamController
capable of handling a BYOB (bring your own buffer)/byte stream. If it is not included, the passed controller will be aReadableStreamDefaultController
. - 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 turned on, the stream implementation will automatically allocate anArrayBuffer
with a size of the given integer, and the consumer can also use a default reader.
- 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 number of 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 ofByteLengthQueuingStrategy
orCountQueuingStrategy
for this object value. If noqueuingStrategy
is supplied, the default used is the same as aCountQueuingStrategy
with a high water mark of 1.
Return value
An instance of the ReadableStream
object.
Exceptions
- RangeError
- The supplied type value is neither
"bytes"
norundefined
.
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()
fuction 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.
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', function() { 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); } });
Specifications
Specification | Status | Comment |
---|---|---|
Streams The definition of 'ReadableStream()' in that specification. |
Living Standard | Initial definition. |
Browser compatibility
The compatibility table on this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request.
Desktop | Mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
ReadableStream() constructor | Chrome Full support 43 | Edge Full support 79 | Firefox
Full support
65
| IE No support No | Opera Full support 30 | Safari Full support 10.1 | WebView Android Full support 43 | Chrome Android Full support 43 | Firefox Android
Full support
65
| Opera Android Full support 30 | Safari iOS Full support 10.3 | Samsung Internet Android Full support 4.0 |
Legend
- Full support
- Full support
- No support
- No support
- Experimental. Expect behavior to change in the future.
- Experimental. Expect behavior to change in the future.
- User must explicitly enable this feature.
- User must explicitly enable this feature.