Draft
This page is not complete.
This is an experimental technology
Check the Browser compatibility table carefully before using this in production.
The ReadableStream()
constructor creates and returns a readable stream object from the given handlers.
var readableStream = new ReadableStream(underlyingSource[, queueingStrategy]);
underlyingSource
can contain the following: 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()
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.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 DOMString
describing why the stream was cancelled.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
with a positive integer value to turn on the stream's auto-allocation feature. With this turned on, the stream implementation will automatically allocate an ArrayBuffer
with a size of the given integer, and call the underlying source code as if the consumer was using a BYOB reader.chunk
— this indicates the size to use for each chunk, in bytes.Note: You could define your own custom queueingStrategy
, or use an instance of ByteLengthQueueingStrategy
or CountQueueingStrategy
for this object value. If no queueingStrategy
is supplied, the default used is the same as a CountQueuingStrategy
with a high water mark of 1.
An instance of the ReadableStream
object.
bytes
nor undefined
.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); } });
Specification | Status | Comment |
---|---|---|
Streams The definition of 'ReadableStream()' in that specification. | Living Standard | Initial definition. |
Desktop | ||||||
---|---|---|---|---|---|---|
Chrome | Edge | Firefox | Internet Explorer | Opera | Safari | |
Basic support | 43 | 16 | 57
|
No | 30 | ? |
Mobile | |||||||
---|---|---|---|---|---|---|---|
Android webview | Chrome for Android | Edge Mobile | Firefox for Android | Opera for Android | iOS Safari | Samsung Internet | |
Basic support | 43 | 43 | 16 | 57
|
30 | ? | 4.0 |
© 2005–2018 Mozilla Developer Network and individual contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream/ReadableStream