Support async iterables

[domenic]

For whatwg/streams#1035 it'd be great if webidl2js supported async iterators.

Note that our parser (webidl2.js) supports async value iterators but not yet arguments to async iterators: see the PRs linked in w3c/webidl2.js#464.

Inspecting Headers-impl.js / the generated Headers.js in jsdom, our current iterator support works by having the impl class supply a [Symbol.iterator]() method. Then, in the generated next() method, it does Array.from(impl), snapshotting the entire thing as an array. Finally it returns the appropriately-indexed value in the array. I don't think that strategy is great for async iterators. (Nor is it especially good for sync iterators...)

One idea is to follow the spec structure entirely. We'd add new symbols to utils.js:

• utils.getTheNextIterationResult
• utils.asyncIteratorReturn
• utils.asyncIteratorInit

and the generated code would call into these. This would allow fairly straightforward implementation of https://whatpr.org/streams/1035.html#rs-asynciterator .

There might be something more clever we could do with impl-class [Symbol.asyncIterator] methods, taking advantage of their coroutine nature. For example, maybe this would work?

class ReadableStreamImpl {
  [Symbol.asyncIterator]({ preventCancel }) {
    // Async iterator initialization steps go here, before any yields or awaits. E.g.:
    const reader = AcquireReadableStreamDefaultReader(this);

    let returnWasCalled = true;
    try {
      while (true) {
        // Get the next iteration result steps go here, e.g.:
        const { value, done } = await ReadableStreamDefaultReaderRead(reader);
        if (done) {
          returnWasCalled = false;
          break;
        }
        yield value;
      }
    } catch (e) {
     // Async iterator return steps go here, with arg = e?
     } finally {
      // Async iterator return steps go here again, with arg = undefined?
    }
  }
}

I'm not so sure about that though, especially the return handling.

[TimothyGu]

(Nor is it especially good for sync iterators...)

In my defense, that's how the spec is written, and handles edge cases (e.g., values are deleted during iteration) just as well as the spec. I'm sure we can find a more efficient pattern if we tried hard enough, but that'd lead us to deviate from specs, so it's a tradeoff.

To give a sense of the complexity here, consider this transcript:

const h = new Headers();
h.set('b', '1');
h.set('d', '2');
const it = h.keys();
console.log(it.next().value); // gives b
h.set('a', '3');
console.log(it.next().value); // gives b still, as when sorted it is now the second element
console.log(it.next().value); // gives d
console.log(it.next().done); // gives true

(Chrome does not implement this, though Firefox does, as well as the spec.)

Is iterator invalidation an issue for async iterables? I'm assuming no. Which would be good.

Of the two ideas for async iterables, I'd rather go with the "have separate methods for each thing." In my experience, the more cleverness is generated (as opposed to written) the better. It would also allow us to check for bugs in specs.