Extending async iterators to support streams

[domenic]

I'd like to work on (this week) extending Web IDL's async iterators support to encompass the pattern we use in Streams. /cc @ricea

The basic idea is to add async iterable<value_type>(...params). This completes the matrix of sync/async vs. value/pair, by filling out the async value quadrant.

The params are passed to the (already specced for key/value async iterators) asynchronous iterator initialization steps. This is necessary for the Streams design, and fairly reasonable IMO, although unprecedented in Web IDL so far.

Points for discussion:

• The streams API would like to pick the method alias name, namely getIterator(). For this I'd envision syntax like async iterable<value_type> getIterator(...params). However, this was not implemented anywhere yet, so maybe we should instead have Web IDL generate a values() method. That is my current thinking.

• Since I need params here, I could add them to async iterators generally, or to all iterators. I think the cleanest way to cut this would be to add them to all async iterators, but not bother at this point for sync iterators.

• Should we generate keys() and entries() for these value async iterators? My initial leaning is to generate them (and in this way), as otherwise they're the odd iterator out. If we do, I'd much prefer to follow the array/value sync iterator precedent and have the keys be 0-based indices, instead of having them just be aliases of the values.

• Should we generate a forEach() function? My initial leaning is no just because of the added complexity. (E.g., do we allow each callback to return a promise? So much promise handling.) This would make it an exception among the rest of the iterator matrix, and it could be vaguely useful sometimes, but I guess we can always add it later.

• Probably we should require that all arguments in ...params are optional, so that for-await-of still works. (This matches Streams.)

[ricea]

However, this was not implemented anywhere yet, so maybe we should instead have Web IDL generate a values() method. That is my current thinking.

Agreed (unless we find someone has implemented getIterator() already).

My initial leaning is to generate them (and in this way), as otherwise they're the odd iterator out. If we do, I'd much prefer to follow the array/value sync iterator precedent and have the keys be 0-based indices, instead of having them just be aliases of the values.

Streams are not indexable, so returning indices would not be useful for anything.

https://heycam.github.io/webidl/#idl-iterable says "A value iterator must only be declared on an interface that supports indexed properties." But a stream is not that kind of thing at all: for one thing, it does not (and cannot) have a length property.

My conclusion is that we should not support keys() and entries() because they imply semantics which streams do not have.

Should we generate a forEach() function?

I would argue "no", since we want to encourage the for await ... of syntax instead.

[domenic]

I put up a draft at #808 but I didn't get to the part where asyncIterable.values(...args) gets the args passed to the async iterator initialization algorithm.

Memo to self: our argument list conversion routines all go through the overload resolution algorithm. Currently this accepts operations and extended attributes, the latter to support [NamedConstructor]. We could extend this to support async iterable declarations as well, and that's probably the path of least resistance. Then, maybe manually construct an effective overload set, pass it in, and use the arguments that result?

If we want to disallow overloads of async iterator declarations, then we could extract only steps 15-16 of the overload resolution algorithm, since they are the only ones applicable when there's no overloads. Disallowing overloads is probably necessary anyway, because we require all arguments to be optional?