[Web API] Implement async iteration of ReadableStream

[Rumyra]

Acceptance Criteria

• [x] The listed features are documented sufficiently on MDN
• [x] BCD is updated
• [x] Interactive example and data repos are updated if appropriate
• [x] The content has been reviewed as needed

For folks helping with Firefox related documentation

• [x] Set bugs to dev-doc-complete
• [x] Add entry to Firefox release notes if feature is enabled in release
• [ ] Add entry to Firefox experimental features page if feature is not yet enabled in release

Features to document

Updates to DOM streams

Related Gecko bugs

https://bugzilla.mozilla.org/show_bug.cgi?id=1734244

Other

• [x] Check content open issues to see if any pertain to the subject matter. If there are any that can be closed because of the work, do so. If there are any that can be fixed relatively quickly because of the knowledge from completing this issue and you have time, feel free to go ahead and fix them.
• [x] Check if glossary updates are required for the feature you're documenting - whether an existing term needs to be updated or a new term should be added.
• [x] Check if BCD update means that content pages need to have experimental markup removed or deprecated markup added (front matter tags and macros).

[hamishwillee]

Updated: OK. I have a reasonable idea of the main usage. But trying to confirm the right way to cancel a stream that is being read in this way, to handle errors, and to polyfill, in

• https://github.com/whatwg/streams/issues/1255
• https://bugzilla.mozilla.org/show_bug.cgi?id=1734244#c27

---

This one is going to be tricky because I'm not great with async, iterables, or streams. This is initial research + brain dump.

1. The spec section of interest is here: https://streams.spec.whatwg.org/#rs-asynciterator

2. The spec has normative info which says the

   for await (const chunk of stream) { ... }
   for await (const chunk of stream.values({ [preventCancel](https://streams.spec.whatwg.org/#dom-readablestreamiteratoroptions-preventcancel): true })) { ... }

   Asynchronously iterates over the chunks in the stream’s internal queue.

   Asynchronously iterating over the stream will lock it, preventing any other consumer from acquiring a reader. The lock will be released if the async iterator’s return() method is called, e.g. by breaking out of the loop.

   By default, calling the async iterator’s return() method will also cancel the stream. To prevent this, use the stream’s values() method, passing true for the preventCancel option.

   • So now you can basically consume the chunks of a stream, returning a promise each time that you can wait on/
   • You can also throw to get out of it, and return done when done.
3. The interface (IDL here now includes:

   async iterable<any>(optional ReadableStreamIteratorOptions options = {});

   where options is an optional object that may define the boolean preventCancel with default value false.

   • To me this looks like magic - is it a function? It is a something else? What I do know is that it is the magic we have to document as it is what allows ReadableStream to be iterated.
     4. There are some precursor discussions/examples as food for thought in https://jakearchibald.com/2017/async-iterators-and-generators/#a-shorter-implementation
     5. Nodejs supports something similar, which might inform documentation: https://2ality.com/2019/11/nodejs-streams-async-iteration.html#reading-from-readable-streams-via-for-await-of
     6. Original discussion for spec https://github.com/whatwg/streams/issues/778

There are a bunch of things I am not sure of.

• What happens if you try this on an unsupported browser.
• What you should do to handle that case ^^^
• ?

[hamishwillee]

Status:

• [x] BCD
  • [x] https://github.com/mdn/browser-compat-data/pull/18824
  • [x] https://github.com/mdn/browser-compat-data/pull/18867
• [x] Docs
  • [x] #24310
  • [x] #25284
• [x] Release notes - #24370
• [x] dev-doc-complete

[hamishwillee]

@Rumyra What I have done so far is enough for a release - release note, basic update to ReadableStream, and BCD.

However this is not yet done- I still need to update "Using Readable streams. I have most of my runnable test code in place, but that will be a separate PR. Anything to do with streams is a bit challenging.

[hamishwillee]

OK, tried to finish this off. I'll close this if it gets through reviews.