@@ -4070,8 +4089,9 @@ that have [=members=] with these names.
- The [=value pairs to iterate over=] are the list of key-value pairs with the key being the username and the
- value being the open Session object on the SessionManager
+ The [=value pairs to iterate over=] are the list of [=value pairs=] with the
+ [=value pair/key=] being the username and the [=value pair/value=] being the open
+ Session object on the SessionManager
object corresponding to that username, sorted by username.
@@ -4130,8 +4150,9 @@ must not also have an
An interface with an [=iterable declaration=]
and its [=inherited interfaces=]
must not have a
-[=maplike declaration=] or
-[=setlike declaration=].
+[=maplike declaration=],
+[=setlike declaration=], or
+[=asynchronously iterable declaration=].
The following extended attributes are applicable to [=iterable declarations=]:
[{{Exposed}}],
@@ -4149,6 +4170,144 @@ The following extended attributes are applicable to [=iterable declarations=]:
+
Asynchronously iterable declarations
+
+An [=interface=] can be declared to be asynchronously iterable by using an
+
asynchronously iterable declaration
+(matching
AsyncIterable) in the body of the
+[=interface=].
+
+
+ interface interface_identifier {
+ async iterable<key_type, value_type>;
+ };
+
+
+Objects that [=implement=] an [=interface=] that is declared to be asynchronously iterable support
+being iterated over asynchronously to obtain a sequence of values.
+
+Note: In the ECMAScript language binding, an interface that is asynchronously iterable will have
+
entries,
keys,
values,
+and {{@@asyncIterator}} properties on its [=interface prototype object=].
+
+Prose accompanying an [=interface=] with an [=asynchronously iterable declaration=] must define a
+
get the next iteration result algorithm.
+This algorithm receives a
[=this=] value, which is an instance of the [=interface=] that it
+is defined for, and the
current state.
+It must return a {{Promise}} that either resolves with undefined – to signal the end of the
+iteration – or a tuple with three elements:
+
+1. a value of the first type given in the declaration;
+1. a value of the second type given in the declaration;
+1. an opaque value that is passed back to the next invocation of the algorithm as the
+
[=current state=].
+
+The prose may also define
asynchronous iterator initialization steps for the
+[=interface=] with an [=asynchronously iterable declaration=], which would then be called with the
+newly created iterator object.
+
+[=Interfaces=] with an [=asynchronously iterable declaration=] must not have any
+[=interface members=] named "
entries", "
keys", or "
values",
+or have any [=inherited interfaces=] that have [=interface members=] with these names.
+
+
+
+ Consider the following interface
SessionManager, which allows access
+ to a number of
Session objects keyed by username:
+
+
+ [Exposed=Window]
+ interface SessionManager {
+ Session getSessionForUser(DOMString username);
+
+ async iterable<DOMString, Session>;
+ };
+
+ [Exposed=Window]
+ interface Session {
+ readonly attribute DOMString username;
+ // ...
+ };
+
+
+ The behavior of the iterator could be defined like so:
+
+
+
+ To [=get the next iteration result=] for SessionManager, run the
+ following steps:
+
+ 1. Let |promise| be a new promise.
+ 1. Let |key| be the following value, if it exists, or null otherwise:
+
+ : If current state is "not yet started"
+ :: the smallest username in this's open sessions, in lexicographical order
+
+ : Otherwise
+ :: the smallest username in this's open sessions that is greater than
+ current state, in lexicographical order
+
+
+ Note: current state might no longer be present in the open sessions.
+ 1. If |key| is null, then:
+ 1. Resolve |promise| with undefined.
+ 1. Otherwise:
+ 1. Let |session| be the Session object corresponding to |key|.
+ 1. Resolve |promise| with (|username|, |session|, |username|).
+ 1. Return |promise|.
+
+
+
+ In the ECMAScript language binding, the [=interface prototype object=] for the
+
SessionManager [=interface=] has a
values method that is a
+ function, which, when invoked, returns an asynchronous iterator object that itself has a
+
next method that returns the next value to be iterated over.
+ It has
keys and
entries methods that iterate over the usernames of
+ session objects and (username,
Session) object pairs, respectively.
+ It also has a {{@@asyncIterator}} method that allows a
SessionManager
+ to be used in a
for await..of loop that has the same value as the
+
entries method:
+
+
+ // Get an instance of SessionManager.
+ // Assume that it has sessions for two users, "anna" and "brian".
+ var sm = getSessionManager();
+
+ typeof SessionManager.prototype.values; // Evaluates to "function"
+ var it = sm.values(); // values() returns an iterator object
+ typeof it.next; // Evaluates to "function"
+
+ // This loop will log "anna" and then "brian".
+ for await (let username of sm.keys()) {
+ console.log(username);
+ }
+
+ // Yet another way of accomplishing the same.
+ for await (let [username, session] of sm) {
+ console.log(username);
+ }
+
+
+
+An [=interface=] must not have more than one [=asynchronously iterable declaration=].
+The [=inherited interfaces=] of an [=interface=] with an [=asynchronously iterable declaration=]
+must not also have an [=asynchronously iterable declaration=].
+An [=interface=] with an [=asynchronously iterable declaration=] and its [=inherited interfaces=]
+must not have a [=maplike declaration=], [=setlike declaration=], or [=iterable declaration=].
+
+The following extended attributes are applicable to [=asynchronously iterable declarations=]:
+[{{Exposed}}],
+[{{SecureContext}}].
+
+Issue: these [=extended attributes=] are not currently taken into account.
+When they are, the effect will be as you would expect.
+
+
+ AsyncIterable :
+ "async" "iterable" "<" TypeWithExtendedAttributes "," TypeWithExtendedAttributes ">" ";"
+
+
+
Maplike declarations
An [=interface=] can be declared to be
@@ -4219,6 +4378,7 @@ also have a [=maplike declaration=].
A maplike interface and its [=inherited interfaces=]
must not have an
[=iterable declaration=],
+an [=asynchronously iterable declaration=],
a [=setlike declaration=], or
an [=indexed property getter=].
@@ -4312,6 +4472,7 @@ also have a [=setlike declaration=].
A setlike interface and its [=inherited interfaces=]
must not have an
[=iterable declaration=],
+an [=asynchronously iterable declaration=],
a [=maplike declaration=], or
an [=indexed property getter=].
@@ -8790,6 +8951,7 @@ with the same [=identifier=].
There also must not be more than
one [=stringifier=]
or more than one [=iterable declaration=],
+[=asynchronously iterable declaration=],
[=maplike declaration=] or
[=setlike declaration=]
across those interfaces.
@@ -11534,6 +11696,48 @@ and the String "
values"
if the interface has a [=setlike declaration=].
+
@@asyncIterator
+
+If the [=interface=] has an [=asynchronously iterable declaration=], then a property must exist
+whose name is the {{@@asyncIterator}} symbol, with attributes
+{ \[[Writable]]:
true, \[[Enumerable]]:
false, \[[Configurable]]:
true }
+and whose value is a [=function object=].
+
+The location of the property is determined as follows:
+
+* If the interface was declared with the [{{Global}}] [=extended attribute=],
+ then the property exists on the single object that [=implements=] the interface.
+* Otherwise, the property exists solely on the interface’s [=interface prototype object=].
+
+
+
+ The [=function object=] is a [=built-in function object=] that, when invoked, must behave as
+ follows:
+
+ 1. Let |object| be the result of calling [$ToObject$] on the this value.
+ 1. If |object| [=is a platform object=], then [=perform a security check=], passing:
+ * the platform object |object|,
+ * the identifier "@@asyncIterator", and
+ * the type "method".
+ 1. Let |interface| be the [=interface=] on which the [=asynchronously iterable declaration=]
+ is declared.
+ 1. If |object| does not [=implement=] |interface|, then [=ECMAScript/throw=] a
+ {{ECMAScript/TypeError}}.
+ 1. Let |iterator| be a newly created [=default asynchronous iterator object=] for |interface|
+ with |object| as its [=default asynchronous iterator object/target=] and
+ "key+value" as its [=default asynchronous iterator object/kind=].
+ 1. Run the [=asynchronous iterator initialization steps=] for |interface| with |iterator|, if
+ any.
+ 1. Return |iterator|.
+
+
+The value of the {{@@asyncIterator}} [=function object=]’s
length property
+is the Number value
0.
+
+The value of the {{@@asyncIterator}} [=function object=]’s
name property
+is the String value "
entries".
+
+
forEach
If the [=interface=] has any of the following:
@@ -11576,8 +11780,8 @@ then the [=function object=] is {{%ArrayProto_forEach%}}.
1. Let |i| be 0.
1. While |i| is less than the length of |pairs|:
1. Let |pair| be the entry in |pairs| at index |i|.
- 1. Let |key| be |pair|’s key.
- 1. Let |value| be |pair|’s value.
+ 1. Let |key| be |pair|’s [=value pair/key=].
+ 1. Let |value| be |pair|’s [=value pair/value=].
1. [=Invoke=] |callback| with |thisArg|
(or
undefined, if the argument was not supplied)
as the [=callback this value=] and |value|, |key| and
this as its arguments.
@@ -11638,7 +11842,7 @@ property is the String value "
forEach".
entries
-If the [=interface=] has an [=iterable declaration=],
+If the [=interface=] has an [=iterable declaration=] or an [=asynchronously iterable declaration=],
then an
entries data property must exist with attributes
{ \[[Writable]]:
true, \[[Enumerable]]:
true, \[[Configurable]]:
true }
and whose value is a [=function object=].
@@ -11656,10 +11860,12 @@ If the interface has a [=pair iterator=],
then the [=function object=] is
the value of the {{@@iterator}} property.
+If the interface has an [=asynchronously iterable declaration=], then the [=function object=] is
+the value of the {{@@asyncIterator}} property.
keys
-If the [=interface=] has an [=iterable declaration=],
+If the [=interface=] has an [=iterable declaration=] or an [=asynchronously iterable declaration=],
then a
keys data property must exist with attributes
{ \[[Writable]]:
true, \[[Enumerable]]:
true, \[[Configurable]]:
true }
and whose value is a [=function object=].
@@ -11685,7 +11891,7 @@ then the [=function object=] is {{%ArrayProto_keys%}}.
* the identifier "
keys", and
* the type "
method".
1. Let |interface| be the [=interface=]
- on which the [=iterable declaration=] is declared on.
+ on which the [=iterable declaration=] is declared.
1. If |object| does not [=implement=] |interface|,
then [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
1. Let |iterator| be a newly created [=default iterator object=]
@@ -11693,6 +11899,28 @@ then the [=function object=] is {{%ArrayProto_keys%}}.
1. Return |iterator|.
+
+ If the interface has an [=asynchronously iterable declaration=], then the method, when invoked,
+ must behave as follows:
+
+ 1. Let |object| be the result of calling [$ToObject$] on the this value.
+ 1. If |object| [=is a platform object=], then [=perform a security check=], passing:
+ * the platform object |object|,
+ * the identifier "keys", and
+ * the type "method".
+ 1. Let |interface| be the [=interface=] on which the [=asynchronously iterable declaration=]
+ is declared.
+ 1. If |object| does not [=implement=] |interface|, then [=ECMAScript/throw=] a
+ {{ECMAScript/TypeError}}.
+ 1. Let |iterator| be a newly created [=default asynchronous iterator object=] for |interface|
+ with |object| as its [=default asynchronous iterator object/target=] and
+ "key" as its [=default asynchronous iterator object/kind=].
+ 1. Run the [=asynchronous iterator initialization steps=] for |interface| with |iterator|, if
+ any.
+ 1. Return |iterator|.
+
+
The value of the [=function object=]’s
+
+ If the interface has an [=asynchronously iterable declaration=], then the method, when invoked,
+ must behave as follows:
+
+ 1. Let |object| be the result of calling [$ToObject$] on the this value.
+ 1. If |object| [=is a platform object=], then [=perform a security check=], passing:
+ * the platform object |object|,
+ * the identifier "entries", and
+ * the type "method".
+ 1. Let |interface| be the [=interface=] on which the [=asynchronously iterable declaration=]
+ is declared.
+ 1. If |object| does not [=implement=] |interface|, then [=ECMAScript/throw=] a
+ {{ECMAScript/TypeError}}.
+ 1. Let |iterator| be a newly created [=default asynchronous iterator object=] for |interface|
+ with |object| as its [=default asynchronous iterator object/target=] and
+ "value" as its [=default asynchronous iterator object/kind=].
+ 1. Run the [=asynchronous iterator initialization steps=] for |interface| with |iterator|, if
+ any.
+ 1. Return |iterator|.
+
+
The value of the [=function object=]’s