The WHATWG Streams API spec provides an API for representing and handling a stream of data in JavaScript. This W3C spec is intended to extend the WHATWG spec to meet requirements specific to the browser environment.

Introduction

Web applications should have the ability to acquire, manipulate, and pass data in a wide variety of forms, including as a sequence of data made available over time. The WHATWG Streams API specification defines the basic representation for streams of data, and programmatic ways to read and write streams of data and errors raised on those operations. This W3C spec had been defining a Streams API, but has been merged into the effort at WHATWG. Feedback made for the W3C spec has been incorporated into the WHATWG Streams API specification. Currently, the goal of this spec is for discussing and defining extensions to meet requirements specific to the browser environment.

The WritableStream interface defines a general protocol for data consuming APIs to communicate with data producing code. In these cases, the data consuming API, such as a decoder, provides a WritableStream for other applications to write to, enabling the decoder to begin decoding data as it becomes available.

The ReadableStream interface defines a general protocol for data producing APIs to communicate with data consuming code. This interface represents the potential for an infinite amount of data which are obtained over time and read once.

The WritableByteStream interface is extended version of WritableStream which has functionality for high performance binary data handling.

The ReadableByteStream interface is extended version of ReadableStream which has functionality for high performance binary data handling. As well as Blob, it might be worth providing a way to get a URL from which we can load data stored in a ReadableByteStream.

The example below demonstrates how to obtain a ReadableByteStream from XMLHttpRequest to begin playing a large video in readystate LOADING. The example takes the ReadableByteStream from a producer, XMLHttpRequest, and gives it to a consumer, the video tag.

function handler() {
  if (this.readyState == this.LOADING) {
    var rbs = this.response;
    var rbsURL = URL.createObjectURL(rbs);
    document.getElementById("placeToPlayMyVideo").src = rbsURL;
  }
}

var client = new XMLHttpRequest();
client.onreadystatechange = handler;
client.open("GET", "/myvideo");
client.responseType = "stream";
client.send();

Extension to WritableByteStream

It might be worth adding an option to pass a pair of a DOMString and an encoding identifier to the write() method. This parameter could be provided as an attribute of the stream instead of the argument of the write() method as it's not likely to be changed frequently.

Extension to ReadableByteStream

It was discussed that the ReadableByteStream should provide a method to read data in various form such as Blob, ArrayBuffer, etc. However, the stream may receive data from the underlying sink without preceding read() call. It would be inefficient to create a data holder of the type specified on read() call. Type specification method should be done on the API instead of being included in the Streams API. The same argument applies to the functionality to specify the encoding using which the read data will be converted into a DOMString.

Stream Consumers and Producers

Byte streams can be both produced and consumed by various APIs. APIs which create streams are identified as producers, and ones which read and act on a byte stream are known as consumers. This section identifies some of the notable APIs where Streams may be produced and consumed.

The list of producers and consumers below is not an exhaustive list. It is placed here as informative for the time being.

Stream Consumers

This section outlines APIs which can consume a byte stream

Stream Producers

This section outlines APIs which can produce a byte stream

Security Considerations

A ReadableByteStream should have the same security considerations as a Blob. This is outlined in 6.8. Security Considerations of the File API specification. [[!FILE-API]] Because a ReadableByteStream uses a Blob URI, cross origin requests on a ReadableByteStream will not be supported.

Acknowledgements

Thanks to Eliot Graff for editorial assistance. Special thanks to the W3C. The editor would like to thank Adrian Bateman, Anne van Kesteren, Austin William Wright, Aymeric Vitte, Domenic Denicola, Elliott Sprehn, Francois-Xavier Kowalski, Harris Syed, Isaac Schlueter, Jonas Sicking, Kenneth Russell, Kinuko Yasuda, Lindsay Verola, Michael Davidson, Rob Manson, Taiju Tsuiki, Yusuke Suzuki, Yutaka Hirano, for their contributions to this specification.

Warning:
This is an older spec snapshot. Implementors and reviewers should instead read the latest specification, which is up to date with the latest changes and bug fixes.