This proposal adds syntactic support for asynchronous iteration using the AsyncIterable and AsyncIterator protocols. It introduces a new IterationStatement, for
-await
-of
, and adds syntax for creating async generator functions and methods.
See the proposal repository for background material and discussion.
This proposal depends upon the async functions proposal.
Specification Name | [[Description]] | Value and Purpose |
---|---|---|
@@asyncIterator |
"Symbol.asyncIterator"
|
A method that returns the default AsyncIterator for an object. Called by the semantics of the for -await -of statement.
|
Intrinsic Name | Global Name | ECMAScript Language Association |
---|---|---|
|
The initial value of the prototype property of |
|
|
The constructor of async iterator objects ( |
|
|
The initial value of the prototype property of |
|
|
An object that all standard built-in async iterator objects indirectly inherit from | |
|
The prototype of async-from-sync iterator objects ( |
The
Algorithm steps that say
mean the same thing as:
where all variables in the above steps, with the exception of completion, are ephemeral and visible only in the steps pertaining to Await.
Await can be combined with the ?
and !
prefixes, so that for example
means the same thing as:
An
When an
The length
property of an
An
When an
The length
property of an
This abstract operation has been modified to accept an optional parameter hint which indicates whether we should attempt to find an async iterator for the object. Existing call sites which use the optional method parameter (Array.from
and IterableToArrayLike) must be updated to pass the
The abstract operation GetIterator with argument obj and optional arguments hint and method performs the following steps:
"next"
).The abstract operation AsyncIteratorClose with arguments iteratorRecord and completion is used to notify an async iterator that it should perform any actions it would normally perform when it has reached its completed state:
"return"
).The abstract operation AsyncGeneratorFunctionCreate requires the arguments: kind which is one of (
"generator"
).return
StatementA return
statement causes a function to cease execution and return a value to the caller. If
This section is extended by Annex
It is only necessary to apply this rule if the extension specified in
for
-in
for
-of
, and for
-await
-of
StatementsIf
The last rule means that the other rules are applied even if parentheses surround
"let"
.
With argument labelSet.
This section is extended by Annex
With argument labelSet.
This section is extended by Annex
With arguments iterationSet and labelSet.
This section is extended by Annex
This section is extended by Annex
This section is extended by Annex
With argument labelSet.
This section is extended by Annex
The abstract operation ForIn/OfHeadEvaluation is called with arguments TDZnames, expr, and iterationKind. The value of iterationKind is either or,
The abstract operation ForIn/OfBodyEvaluation is called with arguments lhs, stmt, iteratorRecord, lhsKind, and labelSet, and optional argument iteratorKind. The value of lhsKind is either
"throw"
).throw
method are propagated. Normal completions from an inner throw
method are processed similarly to an inner next
.throw
method, this throw is going to terminate the yield*
loop. But first we need to give iterator a chance to clean up.yield*
protocol violation: iterator does not have a throw
method."return"
).Abstract operations relating to async generator objects are defined in
eval
or the arguments
."*default*"
».
"*default*"
is used within this specification as a synthetic name for hoistable anonymous functions that are defined using export declarations.
With parameter symbol.
With parameter symbol.
Static semantic rules that depend upon substructure generally do not look into function definitions.
With parameters functionObject and
"%AsyncGeneratorPrototype%"
, « [[AsyncGeneratorState]], [[AsyncGeneratorContext]], [[AsyncGeneratorQueue]] »).With parameter scope.
"prototype"
, PropertyDescriptor{[[Value]]: prototype, [[Writable]]: "prototype"
, PropertyDescriptor{[[Value]]: prototype, [[Writable]]: "default"
).An anonymous export default
declaration.
With parameter object and enumerable.
"prototype"
, PropertyDescriptor{[[Value]]: prototype, [[Writable]]: "prototype"
, PropertyDescriptor{[[Value]]: prototype, [[Writable]]: "prototype"
, PropertyDescriptor{[[Value]]: prototype, [[Writable]]: The
The abstract operation CreateDynamicFunction is called with arguments constructor, newTarget, kind, and args. constructor is the constructor function that is performing this action, newTarget is the constructor that new
was initially applied to, kind is either "normal"
, "generator"
, or "async"
, or "async generator"
, and args is a
"normal"
, then"%FunctionPrototype%"
."generator"
, then"%Generator%"
."async"
,"async"
"%AsyncFunctionPrototype%"
."async generator"
"%AsyncGenerator%"
.","
(a comma), and nextArgString."generator"
or "async generator"
, then"async"
or "async generator"
, then"generator"
, then"prototype"
, PropertyDescriptor{[[Value]]: prototype, [[Writable]]: "async generator"
, then"prototype"
, PropertyDescriptor{[[Value]]: prototype, [[Writable]]: "normal"
, perform "prototype"
property."anonymous"
).A prototype
property is created for every non-async function created using CreateDynamicFunction to provide for the possibility that the function will be used as a constructor.
The initial value of Symbol.asyncIterator
is the well known symbol @@asyncIterator (
This property has the attributes { [[Writable]]:
The AsyncIterable interface includes the properties described in
Property | Value | Requirements |
---|---|---|
@@asyncIterator |
A function that returns an AsyncIterator object. | The returned object must conform to the AsyncIterator interface. |
An object that implements the AsyncIterator interface must include the properties in
Property | Value | Requirements |
---|---|---|
next |
A function that returns a promise for an IteratorResult object. |
The returned promise, when fulfilled, must fulfill with an object which conforms to the IteratorResult interface. If a previous call to the Additionally, the IteratorResult object that serves as a fulfillment value should have a |
Arguments may be passed to the next function but their interpretation and validity is dependent upon the target AsyncIterator. The for
-await
-of
statement and other common users of AsyncIterators do not pass any arguments, so AsyncIterator objects that expect to be used in such a manner must be prepared to deal with being called with no arguments.
Property | Value | Requirements |
---|---|---|
return |
A function that returns a promise for an IteratorResult object. |
The returned promise, when fulfilled, must fulfill with an object which conforms to the IteratorResult interface. Invoking this method notifies the AsyncIterator object that the caller does not intend to make any more Additionally, the IteratorResult object that serves as a fulfillment value should have a |
throw |
A function that returns a promise for an IteratorResult object. |
The returned promise, when fulfilled, must fulfill with an object which conforms to the IteratorResult interface. Invoking this method notifies the AsyncIterator object that the caller has detected an error condition. The argument may be used to identify the error condition and typically will be an exception object. A typical response is to return a rejected promise which rejects with the value passed as the argument. If the returned promise is fulfilled, the IteratorResult fulfillment value will typically have a |
Typically callers of these methods should check for their existence before invoking them. Certain ECMAScript language features including for
-await
-of
and yield*
call these methods after performing an existence check.
The value of the [[Prototype]] internal slot of the %AsyncIteratorPrototype% object is the intrinsic object
All objects defined in this specification that implement the AsyncIterator interface also inherit from %AsyncIteratorPrototype%. ECMAScript code may also define objects that inherit from %AsyncIteratorPrototype%.The %AsyncIteratorPrototype% object provides a place where additional methods that are applicable to all async iterator objects may be added.
The following steps are taken:
The value of the name
property of this function is "[Symbol.asyncIterator]"
.
An Async-from-Sync Iterator object is an async iterator that adapts a specific synchronous iterator. There is not a named constructor for Async-from-Sync Iterator objects. Instead, Async-from-Sync iterator objects are created by the
The abstract operation CreateAsyncFromSyncIterator is used to create an async iterator
All Async-from-Sync Iterator Objects inherit properties from the %AsyncFromSyncIteratorPrototype% intrinsic object. The %AsyncFromSyncIteratorPrototype% object is an ordinary object and its [[Prototype]] internal slot is the
"return"
)."throw"
).The initial value of the @@toStringTag property is the String value "Async-from-Sync Iterator"
.
This property has the attributes { [[Writable]]:
An async-from-sync iterator value unwrap function is an anonymous built-in function that is used by methods of value
field of an IteratorResult object, in order to wait for its value if it is a promise and re-package the result in a new "unwrapped" IteratorResult object. Each async iterator value unwrap function has a [[Done]] internal slot.
When an async-from-sync iterator value unwrap function F is called with argument value, the following steps are taken:
Async-from-Sync Iterator instances are ordinary objects that inherit properties from the
Internal Slot | Description |
---|---|
[[SyncIteratorRecord]] |
A |
The abstract operation GeneratorYield with argument iterNextObj performs the following steps:
"suspendedYield"
.AsyncGenerator Function objects are functions that are usually created by evaluating
The AsyncGeneratorFunction
constructor is the %AsyncGeneratorFunction% intrinsic. When AsyncGeneratorFunction
is called as a function rather than as a constructor, it creates and initializes a new AsyncGeneratorFunction object. Thus the function call AsyncGeneratorFunction (...)
is equivalent to the object creation expression new AsyncGeneratorFunction (...)
with the same arguments.
AsyncGeneratorFunction
is designed to be subclassable. It may be used as the value of an extends
clause of a class definition. Subclass constructors that intend to inherit the specified AsyncGeneratorFunction
behaviour must include a super
call to the AsyncGeneratorFunction
constructor to create and initialize subclass instances with the internal slots necessary for built-in AsyncGeneratorFunction behaviour. All ECMAScript syntactic forms for defining async generator function objects create direct instances of AsyncGeneratorFunction
. There is no syntactic means to create instances of AsyncGeneratorFunction
subclasses.
The last argument specifies the body (executable code) of an async generator function; any preceding arguments specify formal parameters.
When the AsyncGeneratorFunction
function is called with some arguments p1, p2, … , pn, body (where n might be 0, that is, there are no "p" arguments, and where body might also not be provided), the following steps are taken:
"async generator"
, args).
See NOTE for
The AsyncGeneratorFunction
constructor is a standard built-in function object that inherits from the Function
constructor. The value of the [[Prototype]] internal slot of the AsyncGeneratorFunction
constructor is the intrinsic object
The value of the [[Extensible]] internal slot of the AsyncGeneratorFunction constructor is
The value of the name
property of the AsyncGeneratorFunction is "AsyncGeneratorFunction"
.
The AsyncGeneratorFunction
constructor has the following properties:
This is a data property with a value of 1. This property has the attributes { [[Writable]]:
The initial value of AsyncGeneratorFunction.prototype
is the intrinsic object %AsyncGenerator%.
This property has the attributes { [[Writable]]:
The AsyncGeneratorFunction prototype object is an ordinary object. It is not a function object and does not have an [[ECMAScriptCode]] internal slot or any other of the internal slots listed in
The value of the [[Prototype]] internal slot of the AsyncGeneratorFunction prototype object is the
The initial value of AsyncGeneratorFunction.prototype.constructor
is the intrinsic object
This property has the attributes { [[Writable]]:
The value of AsyncGeneratorFunction.prototype.prototype
is the
This property has the attributes { [[Writable]]:
The initial value of the @@toStringTag property is the String value "AsyncGeneratorFunction"
.
This property has the attributes { [[Writable]]:
Every AsyncGeneratorFunction instance is an ECMAScript function object and has the internal slots listed in "generator"
.
Each AsyncGeneratorFunction instance has the following own properties:
The value of the length
property is an integer that indicates the typical number of arguments expected by the AsyncGeneratorFunction. However, the language permits the function to be invoked with some other number of arguments. The behaviour of an AsyncGeneratorFunction when invoked on a number of arguments other than the number specified by its length
property depends on the function.
This property has the attributes { [[Writable]]:
The specification for the name
property of Function instances given in
Whenever an AsyncGeneratorFunction instance is created another ordinary object is also created and is the initial value of the async generator function's prototype
property. The value of the prototype property is used to initialize the [[Prototype]] internal slot of a newly created AsyncGenerator object when the generator function object is invoked using [[Call]].
This property has the attributes { [[Writable]]:
Unlike function instances, the object that is the value of the an AsyncGeneratorFunction's prototype
property does not have a constructor
property whose value is the AsyncGeneratorFunction instance.
An AsyncGenerator object is an instance of an async generator function and conforms to both the AsyncIterator and AsyncIterable interfaces.
AsyncGenerator instances directly inherit properties from the object that is the value of the prototype
property of the AsyncGenerator function that created the instance. AsyncGenerator instances indirectly inherit properties from the AsyncGenerator Prototype intrinsic,
The AsyncGenerator prototype object is the %AsyncGeneratorPrototype% intrinsic. It is also the initial value of the prototype
property of the
The AsyncGenerator prototype is an ordinary object. It is not an AsyncGenerator instance and does not have an [[AsyncGeneratorState]] internal slot.
The value of the [[Prototype]] internal slot of the AsyncGenerator prototype object is the intrinsic object
All AsyncGenerator instances indirectly inherit properties of the AsyncGenerator prototype object.
The initial value of AsyncGenerator.prototype.constructor
is the intrinsic object
This property has the attributes { [[Writable]]:
this
value.this
value.this
value.The initial value of the @@toStringTag property is the String value "AsyncGenerator"
.
This property has the attributes { [[Writable]]:
AsyncGenerator instances are initially created with the internal slots described below:
Internal Slot | Description |
---|---|
[[AsyncGeneratorState]] | The current execution state of the async generator. The possible values are: "suspendedStart" , "suspendedYield" , "executing" , "awaiting-return" , and "completed" . |
[[AsyncGeneratorContext]] | The |
[[AsyncGeneratorQueue]] | A |
The AsyncGeneratorRequest is a
They have the following fields:
Field Name | Value | Meaning |
---|---|---|
[[Completion]] | A |
The completion which should be used to resume the async generator. |
[[Capability]] | A PromiseCapability record | The promise capabilities associated with this request. |
"completed"
."suspendedStart"
."executing"
."awaiting-return"
, return "suspendedStart"
, then"completed"
."completed"
."completed"
, then"awaiting-return"
."completed"
, then return ! "suspendedStart"
or "suspendedYield"
."executing"
.An
When an
"completed"
.The length
property of an
An
When an
"completed"
.The length
property of an
"executing"
, thenThe abstract operation AsyncGeneratorYield with argument value performs the following steps:
"suspendedYield"
.The specification contains many locations which mention generators that also should be updated to mention async generators. The ones with significant normative impact have been patched above. Here we attempt to enumerate all other places that will need minor updates.
AsyncGenerator
constructor.
"caller"
and "arguments"
prohibitions.
AsyncGeneratorFunction
subclass.