RE: [XHR]

Can we get an idl definition too? You shouldn't need to read the algorithm
to know the return types.
On Mar 17, 2016 12:09 PM, "Domenic Denicola" <d@domenic.me> wrote:

> 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).
>
>