Tracking issue for Web IDL async iterator support

[domenic]

A blocker for #963 is expanding Web IDL's async iterator support to be powerful enough for readable streams. The tracking issue over there is whatwg/webidl#800.

On this side I want to record a draft of the algorithms. After the following get done:

• Tweak async iterator algorithms webidl#802
• Async iterators should be allowed to have an optional return() algorithm webidl#804
• Async iterator get next steps should be allowed to reject webidl#803
• The actual async iterator PR tracked in Extending async iterators to support streams webidl#800

then it will look something like this:

Async iterator initialization steps, given a ReadableStream stream, async iterator iterator, and argument options:

1. Let reader be ? AcquireReadableStreamDefaultReader(stream).
2. Set iterator.[[reader]] to reader.
3. Set iterator.[[preventCancel]] to options["preventCancel"].

To get the next iteration result for ReadableStream given the async iterator iterator:

1. Let promise be a new promise.
2. Let reader be iterator.[[reader]].
3. If reader.[[ownerReadableStream]] is undefined, return a promise rejected with a TypeError exception.
4. Return the result of reacting to ! ReadableStreamDefaultReaderRead(reader) with a fulfillment handler that takes an argument result and performs the following steps:
   1. Assert: Type(result) is Object.
   2. Let done be ! Get(result, "done").
   3. Assert: Type(done) is Boolean.
   4. If done is true,
      1. Perform ! ReadableStreamReaderGenericRelease(reader).
      2. Return undefined.
   5. Let value be ! Get(result, "value").
   6. Return _value.

(The above will become a bit cleaner if we are able to move away from using actual ES objects for read results, which will likely happen as part of the general Web IDL conversion.)

To close the async iterator for ReadableStream given the async iterator iterator and argument value:

1. Let reader be iterator.[[asyncIteratorReader]].
2. If reader.[[ownerReadableStream]] is undefined, return a promise rejected with a TypeError exception.
3. If reader.[[readRequests]] is not empty, return a promise rejected with a TypeError exception.
4. If iterator.[[preventCancel]] is false, then:
   1. Let result be ! ReadableStreamReaderGenericCancel(reader, value).
   2. Perform ! ReadableStreamReaderGenericRelease(reader).
   3. Return result.
5. Perform ! ReadableStreamReaderGenericRelease(reader).
6. Return a promise resolved with undefined.

---

I think this all works, so that's good.

[Jack-Works]

Does it specify as async iterable in the specification? I found there is no @@asyncIterator on the ReadableStreamDefaultReader.prototype

[MattiasBuelens]

@Jack-Works The async iterator is defined on ReadableStream itself (instead of ReadableStreamDefaultReader), so you should expect to see ReadableStream.prototype[Symbol.asyncIterator]. (Note that the specification does not define the Symbol.asyncIterator method itself, instead it uses an async iterable declaration in its Web IDL. The actual Symbol.asyncIterator method is defined by Web IDL, which internally uses the steps from the "async iteration" section to create and advance the iterator.)

That said, the async iterator feature is fairly new and is not yet implemented in any browser. If you want to use it today, you're probably going to need a polyfill (shameless plug! 😁).