Re: [whatwg/webidl] Add `async iterable<T>` type to WebIDL (PR #1397)

@domenic commented on this pull request.

This looks really nice now! Just a few more editorial tidbits. Also be sure to fill out the template in the OP.

> @@ -6177,6 +6207,34 @@ sequence is used.
 Any [=list=] can be implicitly treated as a <code>sequence&lt;|T|&gt;</code>, as long as it contains
 only [=list/items=] that are of type |T|.
 
+<!-- Note: if we ever add synchronous iterable types, we should add a note here about why sequences and iterables are not the same. -->
+
+<h4 id="idl-async-iterable-type" lt="async iterable" dfn export>Async iterable types — async iterable&lt;|T|&gt;</h4>
+
+The <dfn lt="async iterable type" export>async iterable&lt;|T|&gt;</dfn> type is a parameterized

I'm still not clear why we're using a different style here than the other parameterized type classes. We should say "An async iterable type", with no `<T>`.

> +            "<code>sync</code>".
+    1.  Return an IDL [=async iterable=] value with [=JS async iterable/object=] set to |V|,
+        [=JS async iterable/method=] set to |method|, and [=JS async iterable/type=] set to
+        "<code>async</code>".
+</div>
+
+<div id="async-iterable-to-js" algorithm="convert an async iterable to a JavaScript value">
+    An IDL <a lt="async iterable type">async iterable&lt;<var ignore>T</var>&gt;</a> value |V| is
+    [=converted to a JavaScript value|converted=] to a JavaScript object as follows:
+
+    1.  Return |V|'s [=JS async iterable/object=].
+</div>
+
+<h5 id="js-async-iterator">Async iterators</h5>
+
+<dfn lt="async iterator" export>Async iterator</dfn> values are represented by a [=struct=] with the following [=struct/items=]:

```suggestion
<dfn lt="async iterator" export>Async iterators</dfn> are [=structs=] with the following [=struct/items=]:
```

> +
+<div id="async-iterable-to-js" algorithm="convert an async iterable to a JavaScript value">
+    An IDL <a lt="async iterable type">async iterable&lt;<var ignore>T</var>&gt;</a> value |V| is
+    [=converted to a JavaScript value|converted=] to a JavaScript object as follows:
+
+    1.  Return |V|'s [=JS async iterable/object=].
+</div>
+
+<h5 id="js-async-iterator">Async iterators</h5>
+
+<dfn lt="async iterator" export>Async iterator</dfn> values are represented by a [=struct=] with the following [=struct/items=]:
+
+* <dfn for="JS async iterator">underlying record</dfn>, an [=Iterator=] record
+* <dfn for="JS async iterator">type parameter</dfn>, an IDL type representing the type of values produced by the async iterator
+
+An [=async iterable=] is not directly iterated over. Instead, it is first opened to create

This sentence is a dupe of the one right after it, so can be deleted.

Given that, this section is pretty small. How about just moving the definition of "async iterator" into the "Iterating async iterators" section, after that intro sentence?

> +
+* <dfn for="JS async iterator">underlying record</dfn>, an [=Iterator=] record
+* <dfn for="JS async iterator">type parameter</dfn>, an IDL type representing the type of values produced by the async iterator
+
+An [=async iterable=] is not directly iterated over. Instead, it is first opened to create
+a [=async iterator=]. The [=async iterator=] can be asynchronously iterated over to produce values.
+
+<h5 id="js-async-iterator-iteration">Iterating async iterators</h5>
+
+[=Async iterables=] are not directly iterated over. They are first opened, to create a new
+[=async iterator=], and then the [=async iterator=] is iterated over.
+
+<div algorithm>
+
+    To <dfn id="async-iterable-open" export lt="open an async iterable">open</dfn> an
+    <code><a lt="async iterable type">async iterable&lt;<var>T</var>&gt;</a></code> |iterable|:

I *think* we should be linking to "async iterable", not "async iterable type", since we're talking about instances? I'm not sure; you can check other cases where we distinguish to see if that's the practice.

> +
+    1.  Let |iterator| be [=?=] <a abstract-op>GetIteratorFromMethod</a>(|iterable|'s
+        [=JS async iterable/object=], |iterable|'s [=JS async iterable/method=]).
+    1.  If |iterable|'s [=JS async iterable/type=] is "<code>sync</code>", set |iterator| to
+        <a abstract-op>CreateAsyncFromSyncIterator</a>(|iterator|).
+    1.  Return an [=async iterator=] value with [=JS async iterator/underlying record=] set to |iterator| and
+        [=JS async iterator/type parameter=] set to |T|.
+
+</div>
+
+
+
+<div algorithm>
+
+    To <dfn id="async-iterator-get-next-value" export lt="get an async iterator next value">get the next value</dfn> of an
+    <code><a lt="async iterator">async iterator</a></code> |iterator|:

```suggestion
    [=async iterator=] |iterator|:
```

> +        [=JS async iterable/object=], |iterable|'s [=JS async iterable/method=]).
+    1.  If |iterable|'s [=JS async iterable/type=] is "<code>sync</code>", set |iterator| to
+        <a abstract-op>CreateAsyncFromSyncIterator</a>(|iterator|).
+    1.  Return an [=async iterator=] value with [=JS async iterator/underlying record=] set to |iterator| and
+        [=JS async iterator/type parameter=] set to |T|.
+
+</div>
+
+
+
+<div algorithm>
+
+    To <dfn id="async-iterator-get-next-value" export lt="get an async iterator next value">get the next value</dfn> of an
+    <code><a lt="async iterator">async iterator</a></code> |iterator|:
+
+    1.  Let |nextResult| be the result of calling

```suggestion
    1.  Let |nextResult| be
```

> +    To <dfn id="async-iterator-close" export lt="close an async iterator">close</dfn> an
+    <code><a lt="async iterator">async iterator&lt;<var ignore>T</var>&gt;</a></code> |iterator|,
+    with a reason |reason|, perform the following steps:

```suggestion
    To <dfn id="async-iterator-close" export lt="close an async iterator">close</dfn> an
    <code><a lt="async iterator">async iterator&lt;<var ignore>T</var>&gt;</a></code> |iterator|
    with a reason |reason|:
```

-- 
Reply to this email directly or view it on GitHub:
https://github.com/whatwg/webidl/pull/1397#pullrequestreview-2214654096
You are receiving this because you are subscribed to this thread.

Message ID: <whatwg/webidl/pull/1397/review/2214654096@github.com>