Add async iterable<T> type to WebIDL

index.bs

@@ -34,6 +34,7 @@ urlPrefix: https://tc39.es/ecma262/; spec: ecmascript
     type: argument
         text: NewTarget; url: sec-built-in-function-objects
     type: abstract-op
+        text: CreateAsyncFromSyncIterator; url: sec-createasyncfromsynciterator
         text: Completion; url: sec-completion-record-specification-type
         text: IsInteger; url: sec-isinteger
         text: Type; url: sec-ecmascript-data-types-and-values
@@ -68,6 +69,7 @@ urlPrefix: https://tc39.es/ecma262/; spec: ecmascript
             text: internal slot
         text: own property; url: sec-own-property
         text: PromiseCapability; url: sec-promisecapability-records
+        text: Iterator; url: sec-iterator-records
         text: element size; url: table-the-typedarray-constructors
 urlPrefix: https://tc39.es/proposal-resizablearraybuffer/; spec: RESIZABLE-BUFFERS-PROPOSAL
     type: abstract-op
@@ -1671,6 +1673,7 @@ The type of the attribute, after resolving typedefs, must not be a
 [=nullable type|nullable=] or non-nullable version of any of the following types:
 
 *   a [=sequence type=]
+*   an [=async iterable type=]
 *   a [=dictionary type=]
 *   a [=record type=]
 *   a [=union type=]
@@ -3360,6 +3363,7 @@ the following algorithm returns <i>true</i>.
                 <th><div><span>interface-like</span></div>
                 <th><div><span>callback function</span></div>
                 <th><div><span>dictionary-like</span></div>
+                <th><div><span>async iterable</span></div>
                 <th><div><span>sequence-like</span></div>
         </thead>
         <tr>
@@ -3375,6 +3379,7 @@ the following algorithm returns <i>true</i>.
             <td>●
             <td>
             <td>●
+            <td>●
         <tr>
             <th>boolean
             <td class="belowdiagonal">
@@ -3388,6 +3393,7 @@ the following algorithm returns <i>true</i>.
             <td>●
             <td>●
             <td>●
+            <td>●
         <tr>
             <th>numeric types
             <td class="belowdiagonal">
@@ -3401,6 +3407,7 @@ the following algorithm returns <i>true</i>.
             <td>●
             <td>●
             <td>●
+            <td>●
         <tr>
             <th>bigint
             <td class="belowdiagonal">
@@ -3414,6 +3421,7 @@ the following algorithm returns <i>true</i>.
             <td>●
             <td>●
             <td>●
+            <td>●
         <tr>
             <th>string types
             <td class="belowdiagonal">
@@ -3427,6 +3435,7 @@ the following algorithm returns <i>true</i>.
             <td>●
             <td>●
             <td>●
+            <td>●
         <tr>
             <th>object
             <td class="belowdiagonal">
@@ -3440,6 +3449,7 @@ the following algorithm returns <i>true</i>.
             <td>
             <td>
             <td>
+            <td>
         <tr>
             <th>symbol
             <td class="belowdiagonal">
@@ -3453,6 +3463,7 @@ the following algorithm returns <i>true</i>.
             <td>●
             <td>●
             <td>●
+            <td>●
         <tr>
             <th>interface-like
             <td class="belowdiagonal">
@@ -3466,6 +3477,7 @@ the following algorithm returns <i>true</i>.
             <td>●
             <td>●
             <td>●
+            <td>●
         <tr>
             <th>callback function
             <td class="belowdiagonal">
@@ -3479,6 +3491,7 @@ the following algorithm returns <i>true</i>.
             <td>
             <td>(c)
             <td>●
+            <td>●
         <tr>
             <th>dictionary-like
             <td class="belowdiagonal">
@@ -3492,6 +3505,21 @@ the following algorithm returns <i>true</i>.
             <td class="belowdiagonal">
             <td>
             <td>●
+            <td>●
+        <tr>
+            <th>async iterable
+            <td class="belowdiagonal">
+            <td class="belowdiagonal">
+            <td class="belowdiagonal">
+            <td class="belowdiagonal">
+            <td class="belowdiagonal">
+            <td class="belowdiagonal">
+            <td class="belowdiagonal">
+            <td class="belowdiagonal">
+            <td class="belowdiagonal">
+            <td class="belowdiagonal">
+            <td>
+            <td>
         <tr>
             <th>sequence-like
             <td class="belowdiagonal">
@@ -3504,6 +3532,7 @@ the following algorithm returns <i>true</i>.
             <td class="belowdiagonal">
             <td class="belowdiagonal">
             <td class="belowdiagonal">
+            <td class="belowdiagonal">
             <td>
     </table>
 
@@ -4069,7 +4098,7 @@ The following extended attributes are applicable to [=iterable declarations=]:
 </pre>
 
 
-<h4 id="idl-async-iterable">Asynchronously iterable declarations</h4>
+<h4 oldids="idl-async-iterable" id="idl-async-iterable-declaration">Asynchronously iterable declarations</h4>
 
 An [=interface=] can be declared to be asynchronously iterable by using an
 <dfn id="dfn-async-iterable-declaration" export>asynchronously iterable declaration</dfn>
@@ -5676,6 +5705,7 @@ are known as <dfn id="dfn-object-type" export>object types</dfn>.
         StringType Null
         identifier Null
         "sequence" "&lt;" TypeWithExtendedAttributes "&gt;" Null
+        "async iterable" "&lt;" TypeWithExtendedAttributes "&gt;" Null
         "object" Null
         "symbol" Null
         BufferRelatedType Null
@@ -6177,6 +6207,42 @@ 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
+type whose values are references to objects that can produce an [=async iterator=].
+
+Async iterables are passed by reference in language bindings where they are represented by an object.
+This means that passing an async iterable to a [=platform object=] will result in a reference to the
+async iterable being kept by that object. Similarly, any async iterable returned from a platform
+object will be a reference to the same object and modifications made to it will be visible to the
+platform object. This is in contrast to sequences, which are always passed by value.
+
+Note: Async iterables can not be constructed from IDL. If returned from an operation, or used as the
+type of a dictionary member, the async iterable will have originated from the host environment and
+have been turned into an IDL type via a language binding. Instead of returning an async iterable
+from an IDL operation, the operation may want to return an [=interface=] that has an
+[=asynchronously iterable declaration=].
+
+Async iterables must not be used as the type of an [=attribute=] or [=constant=].
+
+There is no way to represent an async iterable value in IDL.
+
+<h5 id="idl-async-iterator-object" lt="async-iterator" dfn export>Async iterator objects</h5>
+
+An <dfn lt="async iterator" export>async iterator&lt;|T|&gt;</dfn> value is a reference to an object
+that can produce a sequence of values asynchronously. The async iterator value is parameterized by a
+type |T|, which defines the types of values produced by this async iterator.
+
+Async iterators, unlike sequences, do not have a fixed length and can be infinite. Values are
+asynchronously produced as the async iterator is iterated over.
+
+Async iterators are values, not types, and thus cannot be used as a type in IDL. They can only be
+created from [=async iterable types=]. Thus, async iterators can not be used as the type of an IDL
+operation parameter, an IDL interface attribute, or an IDL dictionary member. Instead an
+[=async iterable type=] should be used.
 
 <h4 id="idl-record" lt="record" dfn export>Record types — record&lt;|K|, |V|&gt;</h4>
 
@@ -8115,6 +8181,161 @@ JavaScript Array values.
 </div>
 
 
+<h4 id="js-async-iterable">Async iterable — async iterable&lt;|T|&gt;</h4>
+
+IDL <a lt="async iterable type">async iterable&lt;|T|&gt;</a> values are represented by a JavaScript
+object, a JavaScript method, and a flag indicating whether the method is expected to produce a
+<code>sync</code> or <code>async</code> iterator.
+
+<div id="js-to-async-iterable" algorithm="convert a JavaScript value to async iterable">
+    A JavaScript value |V| is [=converted to an IDL value|converted=]
+    to an IDL <a lt="async iterable type">async iterable&lt;<var ignore>T</var>&gt;</a> value as follows:
+
+    1.  If <a abstract-op>Type</a>(|V|) is not Object,
+        [=JavaScript/throw=] a <l spec=ecmascript>{{TypeError}}</l>.
+    1.  Let |method| be [=?=] <a abstract-op>GetMethod</a>(obj, {{%Symbol.asyncIterator%}}).
+    1.  If |method| is undefined:
+        1.  Set |syncMethod| to [=?=] <a abstract-op>GetMethod</a>(obj, {{%Symbol.iterator%}}).
+        1.  If |syncMethod| is undefined, [=JavaScript/throw=] a <l spec=ecmascript>{{TypeError}}</l>.
+        1.  Return the IDL async iterable value that represents a reference to the JavaScript object
+            |V|, the JavaScript method |syncMethod|, and the flag <code>sync</code>.
+    1.  Return the IDL async iterable value that represents a reference to the JavaScript object
+        |V|, the JavaScript method |method|, and the flag <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 is
+    [=converted to a JavaScript value|converted=] to a JavaScript object as follows:
+
+    1.  Return the JavaScript object that represents the same async iterable as the IDL value.
+</div>
+
+<h5 id="js-async-iterator">Async iterators</h5>
+
+IDL [=async iterator=] values are represented by JavaScript [=Iterator=] records.
+
+Async iterators can only be created from an [=async iterable type=].
+
+<h5 id="js-async-iterator-iteration">Iterating async iterator</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|,
+    perform the following steps:
+
+    1.  Let |object| be the |iterable|'s JavaScript object.
+    1.  Let |method| be the |iterable|'s JavaScript method.
+    1.  Let |iterator| be [=?=] <a abstract-op>GetIteratorFromMethod</a>(|object|, |method|).
+    1.  If |iterable| has a flag that shows that it is expected to produce a
+        <code>sync</code> iterator, then:
+        1. Set |iterator| to <a abstract-op>CreateAsyncFromSyncIterator</a>(|iterator|).
+    1.  Return an IDL [=async iterator=] value with type parameter |T| that represents |iterator|.
+
+</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&lt;<var>T</var>&gt;</a></code> |iterator|,
+    perform the following steps:
+
+    1.  Let |iteratorRecord| be the [=Iterator=] represented by |iterator|.
+    1.  Let |nextResult| be the result of calling <a abstract-op>IteratorNext</a>(|iteratorRecord|).
+    1.  If |nextResult| is an abrupt completion, return [=a promise rejected with=]
+        |nextResult|.\[[Value]].
+    1.  Let |nextPromise| be [=a promise resolved with=] |nextResult|.\[[Value]].
+    1.  Return the result of [=reacting=] to |nextPromise| with the following fulfillment
+        steps, given |iterResult|:
+        1.  If <a abstract-op>Type</a>(|iterResult|) is not Object, [=JavaScript/throw=] a
+            <l spec=ecmascript>{{TypeError}}</l>.
+        1.  Let |done| be [=?=] <a abstract-op>IteratorComplete</a>(|iterResult|).
+        1.  If |done| is true:
+            1.  Return [=end of iteration=].
+        1.  Otherwise:
+            1.  Let |V| be [=?=] <a abstract-op>IteratorValue</a>(|iterResult|).
+            1.  Let |value| be the result of [=converted to an IDL value|converting=] |V| to an IDL
+                value of type |T|.
+            1.  Return |value|.
+
+</div>
+
+<div algorithm>
+
+    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:
+
+    1.  Let |iteratorRecord| be the [=Iterator=] represented by |iterator|.
+    1.  Let |iteratorObj| be |iteratorRecord|.\[[Iterator]].
+    1.  Let |returnMethod| be <a abstract-op>GetMethod</a>(|iteratorObj|, "return").
+    1.  If |returnMethod| is an abrupt completion, return [=a promise rejected with=]
+        |returnMethod|.\[[Value]].
+    1.  If |returnMethod| is <emu-val>undefined</emu-val>, return [=a promise resolved with=]
+        <emu-val>undefined</emu-val>.
+    1.  Let |returnResult| be <a abstract-op>Call</a>(|returnMethod|.\[[Value]], |iteratorObj|, « |reason| »).
+    1.  If |returnResult| is an abrupt completion, return [=a promise rejected with=]
+        |returnResult|.\[[Value]].
+    1.  Let |returnPromise| be [=a promise resolved with=] |returnResult|.\[[Value]].
+    1.  Return the result of [=reacting=] to |returnPromise| with the following fulfillment steps,
+        given |returnPromiseResult|:
+        1.  If <a abstract-op>Type</a>(|returnPromiseResult|) is not Object, [=JavaScript/throw=] a
+            <l spec=ecmascript>{{TypeError}}</l>.
+        1.  Return <emu-val>undefined</emu-val>.
+
+</div>
+
+<div class="example" id="example-js-async-iterable">
+
+    <code>concatN</code> is an [=operation=] that returns a promise that will be fulfilled with the
+    concatenation of all the strings yielded by the async iterable passed to it. It stops
+    concatenating and closes the iterator once the async iterable has yielded N strings.
+
+    <pre>
+        interface I {
+          Promise&lt;DOMString> concat(async iterable&lt;DOMString> strings, unsigned long maxN);
+        };
+    </pre>
+
+<div algorithm="concatN">
+
+    The <code>concatN(|iterable|, |maxN|)</code> method steps are:
+
+    1.  Let |promise| be [=a new promise=].
+    1.  Let |result| be the empty string.
+    1.  Let |n| be 0.
+    1.  Let |iterator| be the result of <a lt="open an async iterable">opening</a> |iterable|.
+    1.  Let |step| be a sequence of steps that will be used to process the async iterable:
+        1.  Let |next| be the result of <a lt="get an async iterator next value">getting the next value</a> of |iterator|.
+        1.  [=React=] to |next|:
+            -   If |next| was fulfilled with value |v|:
+                1.  If |v| is [=end of iteration=], [=resolve=] |promise| with |result|.
+                1.  Set |result| to the result of concatenating |result| and |v|.
+                1.  Set |n| to |n| + 1.
+                1.  If |n| is |maxN|, then:
+                    1.  Let |finish| be the result of <a lt="close an async iterator">closing</a>
+                        |iterator| with reason <emu-val>undefined</emu-val>.
+                    1.  [=React=] to |finish|:
+                        -   If |finish| was fulfilled, [=resolve=] |promise| with |result|.
+                        -   If |finish| was rejected with reason |r|, [=reject=] |promise| with |r|.
+                1.  Otherwise:
+                    1.  Call |step|.
+            -   If |next| was rejected with reason |r|, [=reject=] |promise| with |r|.
+    1.  Call |step|.
+    1.  Return |promise|.
+
+</div>
+</div>
+
+
+</div>
+
+
 <h4 id="js-record" oldids="es-record">Records — record&lt;|K|, |V|&gt;</h4>
 
 IDL [=record=]&lt;|K|, |V|&gt; values are represented by
@@ -11226,6 +11447,23 @@ Note: The HTML Standard defines how a security check is performed. [[!HTML]]
         1.  Otherwise: if <a abstract-op>Type</a>(|V|) is Object and
             there is an entry in |S| that has one of the
             following types at position |i| of its type list,
+            *   an [=async iterable type=]
+            *   a [=nullable type|nullable=] version of any of the above types
+            *   an [=annotated type=] whose [=annotated types/inner type=] is one of the above types
+            *   a [=union type=], [=nullable type|nullable=] union type, or [=annotated type|annotated=] union type
+                that has one of the above types in its [=flattened member types=]
+
+            and after performing the following steps,
+
+            1.  Let |method| be [=?=] <a abstract-op>GetMethod</a>(|V|, {{%Symbol.asyncIterator%}}).
+
+            |method| is not <emu-val>undefined</emu-val>, then remove from |S| all
+            other entries.
+
+        1.  Otherwise: if <a abstract-op>Type</a>(|V|) is Object and
+            there is an entry in |S| that has one of the
+            following types at position |i| of its type list,
+            *   an [=async iterable type=]
             *   a [=sequence type=]
             *   a [=nullable type|nullable=] [=sequence type=]
             *   an [=annotated type=] whose [=annotated types/inner type=] is a [=sequence type=]
@@ -11390,11 +11628,11 @@ Note: The HTML Standard defines how a security check is performed. [[!HTML]]
     Generally, the inspection of the value at the distinguishing argument index does not have any
     side effects, and the only side effects in the overload resolution algorithm are the result of
     converting the JavaScript values to IDL values.
-    (An exception exists when one of the overloads has a [=sequence type=] or [=frozen array type=]
-    at the distinguishing argument index.
-    In this case, we attempt to get the {{%Symbol.iterator%}} property to determine the appropriate
-    overload, and perform the conversion of the distinguishing argument separately before continuing
-    with the next step.)
+    (An exception exists when one of the overloads has an [=async iterable type=], [=sequence type=]
+    or [=frozen array type=] at the distinguishing argument index.
+    In this case, we attempt to get the {{%Symbol.asyncIterator%}} / {{%Symbol.iterator%}} property
+    to determine the appropriate overload, and perform the conversion of the distinguishing argument
+    separately before continuing with the next step.)
 
     At this point, we have determined which overload to use.  We now
     convert the remaining arguments, from the distinguishing argument onwards,