RE: [XHR]

From: Gomer Thomas [mailto:gomer@gomert-consulting.com] 

> I looked at the Streams specification, and it seems pretty immature and underspecified. I’m not sure it is usable by someone who doesn’t already know how it is supposed to work before reading the specification. How many of the major web browsers are supporting it?

Thanks for the feedback. Streams is intended to be a lower-level primitive used by other specifications, primarily. By reading it you're supposed to learn how to implement your own streams from basic underlying source APIs.

> (1) The constructor of the ReadableStream object is “defined” by 
> Constructor (underlyingSource = { }, {size, highWaterMark = 1 } = { } )
> The “specification” states that the underlyingSource object “can” implement various methods, but it does not say anything about how to create or identify a particular underlyingSource

As you noticed, specific underlying sources are left to other places. Those could be other specs, like Fetch:

https://fetch.spec.whatwg.org/#concept-construct-readablestream

or it could be used by authors directly:

https://streams.spec.whatwg.org/#example-rs-push-no-backpressure


> In my case I want to receive a stream from a remote HTTP server. What do I put in for the underlyingSource?

This is similar to asking the question "I want to create a promise for an animation. What do I put in the `new Promise(...)` constructor?" In other words, a ReadableStream is a data type that can stream anything, and the actual capability needs to be supplied by your code. Fetch supplies one underlying source, for HTTP responses.

> Also, what does the “highWaterMark” parameter mean? The “specification” says it is part of the queuing strategy object, but it does not say what it does.

Hmm, I think the links (if you follow them) are fairly clear. https://streams.spec.whatwg.org/#queuing-strategy. Do you have any suggestions on how to make it clearer?

> Is it the maximum number of bytes of unread data in the Stream? If so, it should say so.

Close; it is the maximum number of bytes before a backpressure signal is sent. But, that is already exactly what the above link (which was found by clicking the links "queuing strategy" in the constructor definition) says, so I am not sure what you are asking for.

> If the “size” parameter is omitted, is the underlyingSource free to send chunks of any size, including variable sizes?

Upon re-reading, I agree it's not 100% clear that the size() function maps to "The queuing strategy assigns a size to each chunk". However, the behavior of how the stream uses the size() function is defined in a lot of detail if you follow the spec. I agree maybe it could use some more non-normative notes explaining, and will work to add some, but in the end if you really want to understand what happens you need to either read the spec's algorithms or wait for someone to write an in-depth tutorial somewhere like MDN.

> (2) The ReadableStream class has a “getReader()” method, but the specification gives no hint as to the data type that this method returns. I suspect that it is an object of the ReadableStreamReader class, but if so it would be nice if the “specification” said so.

This is actually normatively defined if you click the link in the step "Return AcquireReadableStreamReader(this)," whose first line tells you what it constructs (indeed, a ReadableStreamReader).

Received on Thursday, 17 March 2016 18:56:49 UTC