Stage 3 Draft / June 7, 2017

Async Iteration

1Introduction

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.

Note

This proposal depends upon the async functions proposal.

2Well-Known Symbols

Editor's Note

The spec's existing Table 1 in 6.1.5.1 should be expanded with the following rows:

Table 1: Well-known Symbols
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.

3Well-Known Intrinsic Objects

Editor's Note

The spec's existing Table 7 in 6.1.7.4 should be expanded with the following rows:

Table 2: Well-known Intrinsic Objects
Intrinsic Name Global Name ECMAScript Language Association
%AsyncGenerator% The initial value of the prototype property of %AsyncGeneratorFunction%
%AsyncGeneratorFunction% The constructor of async iterator objects (11.3.1)
%AsyncGeneratorPrototype% The initial value of the prototype property of %AsyncGenerator%
%AsyncIteratorPrototype% An object that all standard built-in async iterator objects indirectly inherit from
%AsyncFromSyncIteratorPrototype% The prototype of async-from-sync iterator objects (11.1.3)

4The Completion Record Specification Type

Editor's Note
This patch adds clauses to 6.2.2.

4.1Await

Editor's Note

The AsyncFunctionAwait abstract operation could probably be refactored in terms of this primitive.

Algorithm steps that say

  1. Let completion be Await(promise).

mean the same thing as:

  1. Let asyncContext be the running execution context.
  2. Let promiseCapability be ! NewPromiseCapability(%Promise%).
  3. Perform ! Call(promiseCapability.[[Resolve]], undefined, « promise »).
  4. Let onFulfilled be a new built-in function object as defined in Await Fulfilled Functions.
  5. Let onRejected be a new built-in function object as defined in Await Rejected Functions.
  6. Set onFulfilled and onRejected's [[AsyncContext]] internal slots to asyncContext.
  7. Let throwawayCapability be NewPromiseCapability(%Promise%).
  8. Set throwawayCapability.[[Promise]].[[PromiseIsHandled]] to true.
  9. Perform ! PerformPromiseThen(promiseCapability.[[Promise]], onFulfilled, onRejected, throwawayCapability).
  10. Remove asyncContext from the execution context stack and restore the execution context that is at the top of the execution context stack as the running execution context.
  11. Set the code evaluation state of asyncContext such that when evaluation is resumed with a Completion completion, the following steps of the algorithm that invoked Await will be performed, with completion available.

where all variables in the above steps, with the exception of completion, are ephemeral and visible only in the steps pertaining to Await.

Note

Await can be combined with the ? and ! prefixes, so that for example

  1. Let value be ? Await(promise).

means the same thing as:

  1. Let value be Await(promise).
  2. ReturnIfAbrupt(value).

4.1.1Await Fulfilled Functions

An Await fulfilled function is an anonymous built-in function that is used as part of the Await specification device to deliver the promise fulfillment value to the caller as a normal completion. Each Await fulfilled function has an [[AsyncContext]] internal slot.

When an Await fulfilled function F is called with argument value, the following steps are taken:

  1. Let asyncContext be F.[[AsyncContext]].
  2. Let prevContext be the running execution context.
  3. Suspend prevContext.
  4. Push asyncContext onto the execution context stack; asyncContext is now the running execution context.
  5. Resume the suspended evaluation of asyncContext using NormalCompletion(value) as the result of the operation that suspended it.
  6. Assert: When we reach this step, asyncContext has already been removed from the execution context stack and prevContext is the currently running execution context.
  7. Return undefined.

The length property of an Await fulfilled function is 1.

4.1.2Await Rejected Functions

An Await rejected function is an anonymous built-in function that is used as part of the Await specification device to deliver the promise rejection reason to the caller as an abrupt throw completion. Each Await rejected function has an [[AsyncContext]] internal slot.

When an Await rejected function F is called with argument reason, the following steps are taken:

  1. Let asyncContext be F.[[AsyncContext]].
  2. Let prevContext be the running execution context.
  3. Suspend prevContext.
  4. Push asyncContext onto the execution context stack; asyncContext is now the running execution context.
  5. Resume the suspended evaluation of asyncContext using Completion{[[Type]]: throw, [[Value]]: reason, [[Target]]: empty} as the result of the operation that suspended it.
  6. Assert: When we reach this step, asyncContext has already been removed from the execution context stack and prevContext is the currently running execution context.
  7. Return undefined.

The length property of an Await rejected function is 1.

5Operations on Iterator Objects

Editor's Note
These patches modify clauses of and add clauses to 7.4.

5.1GetIterator ( obj [ , method ][ , hint ] )

Note

This method has been modified to accept an optional parameter hint which indicates whether we should attempt to find an async iterator for the object. The method parameter has been removed. Call sites which use the optional method parameter (Array.from and IterableToArrayLike) must be updated to call the function directly instead.

The abstract operation GetIterator with argument obj and optional argument hint performs the following steps:

  1. If hint was not passed, let hint be normal.
  2. Let method be undefined.
  3. If hint is async,
    1. Set method to ? GetMethod(obj, @@asyncIterator).
    2. If method is undefined,
      1. Let syncMethod be ? GetMethod(obj, @@iterator).
      2. Let syncIterator be ? Call(syncMethod, obj).
      3. Return ? CreateAsyncFromSyncIterator(syncIterator).
  4. Otherwise, set method to ? GetMethod(obj, @@iterator).
  5. If method was not passed, then
    1. Let method be ? GetMethod(obj, @@iterator).
  6. Let iterator be ? Call(method, obj).
  7. If Type(iterator) is not Object, throw a TypeError exception.
  8. Return iterator.

5.2AsyncIteratorClose ( iterator, completion )

The abstract operation AsyncIteratorClose with arguments iterator 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:

  1. Assert: Type(iterator) is Object.
  2. Assert: completion is a Completion Record.
  3. Let return be ? GetMethod(iterator, "return").
  4. If return is undefined, return Completion(completion).
  5. Let innerResult be Call(return, iterator, « »).
  6. If innerResult.[[Type]] is normal, set innerResult to Await(innerResult.[[Value]]).
  7. If completion.[[Type]] is throw, return Completion(completion).
  8. If innerResult.[[Type]] is throw, return Completion(innerResult).
  9. If Type(innerResult.[[Value]]) is not Object, throw a TypeError exception.
  10. Return Completion(completion).

6ECMAScript Function Objects

Editor's Note
This patch adds a clause to 9.2.

6.1AsyncGeneratorFunctionCreate (kind, ParameterList, Body, Scope, Strict)

The abstract operation AsyncGeneratorFunctionCreate requires the arguments: kind which is one of (Normal, Method), a parameter list production specified by ParameterList, a body production specified by Body, a Lexical Environment specified by Scope, and a Boolean flag Strict. AsyncGeneratorFunctionCreate performs the following steps:

  1. Let functionPrototype be the intrinsic object %AsyncGenerator%.
  2. Let F be ! FunctionAllocate(functionPrototype, Strict, "generator").
  3. Return ! FunctionInitialize(F, kind, ParameterList, Body, Scope).

7Iteration Statements

Editor's Note
These patches modify clauses of and add clauses to 13.7.

Syntax

IterationStatement[Yield, Await, Return]:doStatement[?Yield, ?Await, ?Return]while(Expression[+In, ?Yield, ?Await]); while(Expression[+In, ?Yield, ?Await])Statement[?Yield, ?Await, ?Return] for([lookahead ∉ { let [ }]Expression[~In, ?Yield, ?Await]opt;Expression[+In, ?Yield, ?Await]opt;Expression[+In, ?Yield, ?Await]opt)Statement[?Yield, ?Await, ?Return] for(varVariableDeclarationList[~In, ?Yield, ?Await];Expression[+In, ?Yield, ?Await]opt;Expression[+In, ?Yield, ?Await]opt)Statement[?Yield, ?Await, ?Return] for(LexicalDeclaration[~In, ?Yield, ?Await]Expression[+In, ?Yield, ?Await]opt;Expression[+In, ?Yield, ?Await]opt)Statement[?Yield, ?Await, ?Return] for([lookahead ∉ { let [ }]LeftHandSideExpression[?Yield, ?Await]inExpression[+In, ?Yield, ?Await])Statement[?Yield, ?Await, ?Return] for(varForBinding[?Yield, ?Await]inExpression[+In, ?Yield, ?Await])Statement[?Yield, ?Await, ?Return] for(ForDeclaration[?Yield, ?Await]inExpression[+In, ?Yield, ?Await])Statement[?Yield, ?Await, ?Return] for([lookahead ≠ let]LeftHandSideExpression[?Yield, ?Await]ofAssignmentExpression[+In, ?Yield, ?Await])Statement[?Yield, ?Await, ?Return] for(varForBinding[?Yield, ?Await]ofAssignmentExpression[+In, ?Yield, ?Await])Statement[?Yield, ?Await, ?Return] for(ForDeclaration[?Yield, ?Await]ofAssignmentExpression[+In, ?Yield, ?Await])Statement[?Yield, ?Await, ?Return] [+Await]forawait([lookahead ≠ let]LeftHandSideExpression[?Yield, ?Await]ofAssignmentExpression[+In, ?Yield, ?Await])Statement[?Yield, ?Await, ?Return] [+Await]forawait(varForBinding[?Yield, ?Await]ofAssignmentExpression[+In, ?Yield, ?Await])Statement[?Yield, ?Await, ?Return] [+Await]forawait(ForDeclaration[?Yield, ?Await]ofAssignmentExpression[+In, ?Yield, ?Await])Statement[?Yield, ?Await, ?Return] ForDeclaration[Yield, Await]:LetOrConstForBinding[?Yield, ?Await] ForBinding[Yield, Await]:BindingIdentifier[?Yield, ?Await] BindingPattern[?Yield, ?Await] Note

This section is extended by Annex B.3.6.

7.1Semantics

7.1.1Static Semantics: Early Errors

IterationStatement:doStatementwhile(Expression); while(Expression)Statement for(Expressionopt;Expressionopt;Expressionopt)Statement for(varVariableDeclarationList;Expressionopt;Expressionopt)Statement for(LexicalDeclarationExpressionopt;Expressionopt)Statement for(LeftHandSideExpressioninExpression)Statement for(varForBindinginExpression)Statement for(ForDeclarationinExpression)Statement for(LeftHandSideExpressionofAssignmentExpression)Statement for(varForBindingofAssignmentExpression)Statement for(ForDeclarationofAssignmentExpression)Statement forawait(LeftHandSideExpressionofAssignmentExpression)Statement forawait(varForBindingofAssignmentExpression)Statement forawait(ForDeclarationofAssignmentExpression)Statement Note

It is only necessary to apply this rule if the extension specified in B.3.2 is implemented.

7.2The for-in and, for-of, and for-await-of Statements

7.2.1Static Semantics: Early Errors

IterationStatement:for(LeftHandSideExpressioninExpression)Statement for(LeftHandSideExpressionofAssignmentExpression)Statement forawait(LeftHandSideExpressionofAssignmentExpression)Statement

If LeftHandSideExpression is either an ObjectLiteral or an ArrayLiteral and if the lexical token sequence matched by LeftHandSideExpression can be parsed with no tokens left over using AssignmentPattern as the goal symbol then the following rules are not applied. Instead, the Early Error rules for AssignmentPattern are used.

Note

The last rule means that the other rules are applied even if parentheses surround Expression.

IterationStatement:for(ForDeclarationinExpression)Statement for(ForDeclarationofAssignmentExpression)Statement forawait(ForDeclarationofAssignmentExpression)Statement
  • It is a Syntax Error if the BoundNames of ForDeclaration contains "let".
  • It is a Syntax Error if any element of the BoundNames of ForDeclaration also occurs in the VarDeclaredNames of Statement.
  • It is a Syntax Error if the BoundNames of ForDeclaration contains any duplicate entries.

7.2.2Static Semantics: ContainsDuplicateLabels

With argument labelSet.

IterationStatement:for(LeftHandSideExpressioninExpression)Statement for(varForBindinginExpression)Statement for(ForDeclarationinExpression)Statement for(LeftHandSideExpressionofAssignmentExpression)Statement for(varForBindingofAssignmentExpression)Statement for(ForDeclarationofAssignmentExpression)Statement forawait(LeftHandSideExpressionofAssignmentExpression)Statement forawait(varForBindingofAssignmentExpression)Statement forawait(ForDeclarationofAssignmentExpression)Statement
  1. Return ContainsDuplicateLabels of Statement with argument labelSet.
Note

This section is extended by Annex B.3.6.

7.2.3Static Semantics: ContainsUndefinedBreakTarget

With argument labelSet.

IterationStatement:for(LeftHandSideExpressioninExpression)Statement for(varForBindinginExpression)Statement for(ForDeclarationinExpression)Statement for(LeftHandSideExpressionofAssignmentExpression)Statement for(varForBindingofAssignmentExpression)Statement for(ForDeclarationofAssignmentExpression)Statement forawait(LeftHandSideExpressionofAssignmentExpression)Statement forawait(varForBindingofAssignmentExpression)Statement forawait(ForDeclarationofAssignmentExpression)Statement
  1. Return ContainsUndefinedBreakTarget of Statement with argument labelSet.
Note

This section is extended by Annex B.3.6.

7.2.4Static Semantics: ContainsUndefinedContinueTarget

With arguments iterationSet and labelSet.

IterationStatement:for(LeftHandSideExpressioninExpression)Statement for(varForBindinginExpression)Statement for(ForDeclarationinExpression)Statement for(LeftHandSideExpressionofAssignmentExpression)Statement for(varForBindingofAssignmentExpression)Statement for(ForDeclarationofAssignmentExpression)Statement forawait(LeftHandSideExpressionofAssignmentExpression)Statement forawait(varForBindingofAssignmentExpression)Statement forawait(ForDeclarationofAssignmentExpression)Statement
  1. Return ContainsUndefinedContinueTarget of Statement with arguments iterationSet and « ».
Note

This section is extended by Annex B.3.6.

7.2.5Static Semantics: VarDeclaredNames

IterationStatement:for(LeftHandSideExpressioninExpression)Statement
  1. Return the VarDeclaredNames of Statement.
IterationStatement:for(varForBindinginExpression)Statement
  1. Let names be the BoundNames of ForBinding.
  2. Append to names the elements of the VarDeclaredNames of Statement.
  3. Return names.
IterationStatement:for(ForDeclarationinExpression)Statement
  1. Return the VarDeclaredNames of Statement.
IterationStatement:for(LeftHandSideExpressionofAssignmentExpression)Statement forawait(LeftHandSideExpressionofAssignmentExpression)Statement
  1. Return the VarDeclaredNames of Statement.
IterationStatement:for(varForBindingofAssignmentExpression)Statement forawait(varForBindingofAssignmentExpression)Statement
  1. Let names be the BoundNames of ForBinding.
  2. Append to names the elements of the VarDeclaredNames of Statement.
  3. Return names.
IterationStatement:for(ForDeclarationofAssignmentExpression)Statement forawait(ForDeclarationofAssignmentExpression)Statement
  1. Return the VarDeclaredNames of Statement.
Note

This section is extended by Annex B.3.6.

7.2.6Static Semantics: VarScopedDeclarations

IterationStatement:for(LeftHandSideExpressioninExpression)Statement
  1. Return the VarScopedDeclarations of Statement.
IterationStatement:for(varForBindinginExpression)Statement
  1. Let declarations be a List containing ForBinding.
  2. Append to declarations the elements of the VarScopedDeclarations of Statement.
  3. Return declarations.
IterationStatement:for(ForDeclarationinExpression)Statement
  1. Return the VarScopedDeclarations of Statement.
IterationStatement:for(LeftHandSideExpressionofAssignmentExpression)Statement forawait(LeftHandSideExpressionofAssignmentExpression)Statement
  1. Return the VarScopedDeclarations of Statement.
IterationStatement:for(varForBindingofAssignmentExpression)Statement forawait(varForBindingofAssignmentExpression)Statement
  1. Let declarations be a List containing ForBinding.
  2. Append to declarations the elements of the VarScopedDeclarations of Statement.
  3. Return declarations.
IterationStatement:for(ForDeclarationofAssignmentExpression)Statement forawait(ForDeclarationofAssignmentExpression)Statement
  1. Return the VarScopedDeclarations of Statement.
Note

This section is extended by Annex B.3.6.

7.2.7Runtime Semantics: LabelledEvaluation

With argument labelSet.

IterationStatement:for(LeftHandSideExpressioninExpression)Statement
  1. Let keyResult be ? ForIn/OfHeadEvaluation(« », Expression, enumerate).
  2. Return ? ForIn/OfBodyEvaluation(LeftHandSideExpression, Statement, keyResult, assignment, labelSet).
IterationStatement:for(varForBindinginExpression)Statement
  1. Let keyResult be ? ForIn/OfHeadEvaluation(« », Expression, enumerate).
  2. Return ? ForIn/OfBodyEvaluation(ForBinding, Statement, keyResult, varBinding, labelSet).
IterationStatement:for(ForDeclarationinExpression)Statement
  1. Let keyResult be the result of performing ? ForIn/OfHeadEvaluation(BoundNames of ForDeclaration, Expression, enumerate).
  2. Return ? ForIn/OfBodyEvaluation(ForDeclaration, Statement, keyResult, lexicalBinding, labelSet).
IterationStatement:for(LeftHandSideExpressionofAssignmentExpression)Statement
  1. Let keyResult be the result of performing ? ForIn/OfHeadEvaluation(« », AssignmentExpression, iterate).
  2. Return ? ForIn/OfBodyEvaluation(LeftHandSideExpression, Statement, keyResult, assignment, labelSet).
IterationStatement:for(varForBindingofAssignmentExpression)Statement
  1. Let keyResult be the result of performing ? ForIn/OfHeadEvaluation(« », AssignmentExpression, iterate).
  2. Return ? ForIn/OfBodyEvaluation(ForBinding, Statement, keyResult, varBinding, labelSet).
IterationStatement:for(ForDeclarationofAssignmentExpression)Statement
  1. Let keyResult be the result of performing ? ForIn/OfHeadEvaluation(BoundNames of ForDeclaration, AssignmentExpression, iterate).
  2. Return ? ForIn/OfBodyEvaluation(ForDeclaration, Statement, keyResult, lexicalBinding, labelSet).
IterationStatement:forawait(LeftHandSideExpressionofAssignmentExpression)Statement
  1. Let keyResult be the result of performing ? ForIn/OfHeadEvaluation(« », AssignmentExpression, async-iterate).
  2. Return ? ForIn/OfBodyEvaluation(LeftHandSideExpression, Statement, keyResult, assignment, labelSet, async).
IterationStatement:forawait(varForBindingofAssignmentExpression)Statement
  1. Let keyResult be the result of performing ? ForIn/OfHeadEvaluation(« », AssignmentExpression, async-iterate).
  2. Return ? ForIn/OfBodyEvaluation(ForBinding, Statement, keyResult, varBinding, labelSet, async).
IterationStatement:forawait(ForDeclarationofAssignmentExpression)Statement
  1. Let keyResult be the result of performing ? ForIn/OfHeadEvaluation(BoundNames of ForDeclaration, AssignmentExpression, async-iterate).
  2. Return ? ForIn/OfBodyEvaluation(ForDeclaration, Statement, keyResult, lexicalBinding, labelSet, async).
Note

This section is extended by Annex B.3.6.

7.2.8Runtime Semantics: ForIn/OfHeadEvaluation ( TDZnames, expr, iterationKind )

The abstract operation ForIn/OfHeadEvaluation is called with arguments TDZnames, expr, and iterationKind. The value of iterationKind is either enumerate or, iterate, or async-iterate.

  1. Let oldEnv be the running execution context's LexicalEnvironment.
  2. If TDZnames is not an empty List, then
    1. Assert: TDZnames has no duplicate entries.
    2. Let TDZ be ! NewDeclarativeEnvironment(oldEnv).
    3. Let TDZEnvRec be TDZ's EnvironmentRecord.
    4. For each string name in TDZnames, do
      1. Perform ! TDZEnvRec.CreateMutableBinding(name, false).
    5. Set the running execution context's LexicalEnvironment to TDZ.
  3. Let exprRef be the result of evaluating the production that is expr.
  4. Set the running execution context's LexicalEnvironment to oldEnv.
  5. Let exprValue be ? GetValue(exprRef).
  6. If iterationKind is enumerate, then
    1. If exprValue.[[Value]] is null or undefined, then
      1. Return Completion{[[Type]]: break, [[Value]]: empty, [[Target]]: empty}.
    2. Let obj be ? ToObject(exprValue).
    3. Return ? obj.[[Enumerate]]().
  7. Else,
    1. If iterationKind is async-iterate, let iteratorHint be async.
    2. Else, let iteratorHint be normal.
    3. Return ? GetIterator(exprValue, iteratorHint).

7.2.9Runtime Semantics: ForIn/OfBodyEvaluation ( lhs, stmt, iterator, lhsKind, labelSet [ , iteratorKind ] )

The abstract operation ForIn/OfBodyEvaluation is called with arguments lhs, stmt, iterator, lhsKind, and labelSet, and optional argument iteratorKind. The value of lhsKind is either assignment, varBinding or lexicalBinding. The value of iteratorKind is either normal or async.

  1. If iteratorKind was not passed, let iteratorKind be normal.
  2. Let oldEnv be the running execution context's LexicalEnvironment.
  3. Let V be undefined.
  4. Let destructuring be IsDestructuring of lhs.
  5. If destructuring is true and if lhsKind is assignment, then
    1. Assert: lhs is a LeftHandSideExpression.
    2. Let assignmentPattern be the parse of the source text corresponding to lhs using AssignmentPattern as the goal symbol.
  6. Repeat
    1. Let nextResult be ? IteratorNext(iterator).
    2. Let nextResult be ? Invoke(iterator, "next", « »).
    3. If iteratorKind is async, then set nextResult to ? Await(nextResult).
    4. If Type(nextResult) is not Object, throw a TypeError exception.
    5. Let done be ? IteratorComplete(nextResult).
    6. If done is true, return NormalCompletion(V).
    7. Let nextValue be ? IteratorValue(nextResult).
    8. If lhsKind is either assignment or varBinding, then
      1. If destructuring is false, then
        1. Let lhsRef be the result of evaluating lhs (it may be evaluated repeatedly).
    9. Else,
      1. Assert: lhsKind is lexicalBinding.
      2. Assert: lhs is a ForDeclaration.
      3. Let iterationEnv be NewDeclarativeEnvironment(oldEnv).
      4. Perform BindingInstantiation for lhs passing iterationEnv as the argument.
      5. Set the running execution context's LexicalEnvironment to iterationEnv.
      6. If destructuring is false, then
        1. Assert: lhs binds a single name.
        2. Let lhsName be the sole element of BoundNames of lhs.
        3. Let lhsRef be ResolveBinding(lhsName).
        4. Assert: lhsRef is not an abrupt completion.
    10. If destructuring is false, then
      1. If lhsRef is an abrupt completion, then
        1. Let status be lhsRef.
      2. Else if lhsKind is lexicalBinding, then
        1. Let status be InitializeReferencedBinding(lhsRef, nextValue).
      3. Else,
        1. Let status be PutValue(lhsRef, nextValue).
    11. Else,
      1. If lhsKind is assignment, then
        1. Let status be the result of performing DestructuringAssignmentEvaluation of assignmentPattern using nextValue as the argument.
      2. Else if lhsKind is varBinding, then
        1. Assert: lhs is a ForBinding.
        2. Let status be the result of performing BindingInitialization for lhs passing nextValue and undefined as the arguments.
      3. Else,
        1. Assert: lhsKind is lexicalBinding.
        2. Assert: lhs is a ForDeclaration.
        3. Let status be the result of performing BindingInitialization for lhs passing nextValue and iterationEnv as arguments.
    12. If status is an abrupt completion, then
      1. Set the running execution context's LexicalEnvironment to oldEnv.
      2. If iteratorKind is async, return ? AsyncIteratorClose(iterator, status).
      3. Return ? IteratorClose(iterator, status).
    13. Let result be the result of evaluating stmt.
    14. Set the running execution context's LexicalEnvironment to oldEnv.
    15. If ! LoopContinues(result, labelSet) is false, return ? IteratorClose(iterator, UpdateEmpty(result, V))then
      1. Let status be UpdateEmpty(result, V).
      2. If iteratorKind is async, return ? AsyncIteratorClose(iterator, status).
      3. Return ? IteratorClose(iterator, status).
    16. If result.[[Value]] is not empty, let V be result.[[Value]].

8ECMAScript Language: Functions and Classes

Editor's Note
These patches modify clauses of and add clauses to 14.

8.1Method Definitions

8.1.1Static Semantics: SpecialMethod

MethodDefinition:PropertyName(UniqueFormalParameters){FunctionBody}
  1. Return false.
MethodDefinition:GeneratorMethod AsyncGeneratorMethod getPropertyName(){FunctionBody} setPropertyName(PropertySetParameterList){FunctionBody}
  1. Return true.

8.2Generator Definitions

8.2.1Runtime Semantics: Evaluation

YieldExpression:yield
  1. Let generatorKind be ! GetGeneratorKind().
  2. If generatorKind is async, then return ? AsyncGeneratorYield(undefined).
  3. Otherwise, rReturn ? GeneratorYield(CreateIterResultObject(undefined, false)).
YieldExpression:yieldAssignmentExpression
  1. Let generatorKind be ! GetGeneratorKind().
  2. Let exprRef be the result of evaluating AssignmentExpression.
  3. Let value be ? GetValue(exprRef).
  4. If generatorKind is async, then return ? AsyncGeneratorYield(value).
  5. Otherwise, rReturn ? GeneratorYield(CreateIterResultObject(value, false)).
YieldExpression:yield*AssignmentExpression
  1. Let generatorKind be ! GetGeneratorKind().
  2. Let exprRef be the result of evaluating AssignmentExpression.
  3. Let value be ? GetValue(exprRef).
  4. Let iterator be ? GetIterator(value, generatorKind).
  5. Let received be NormalCompletion(undefined).
  6. Repeat
    1. If received.[[Type]] is normal, then
      1. Let innerResult be ? IteratorNext(iterator, received.[[Value]]).
      2. Let innerResult be ? Invoke(iterator, "next", « received.[[Value]] »).
      3. If generatorKind is async, then set innerResult to ? Await(innerResult).
      4. If Type(innerResult) is not Object, throw a TypeError exception.
      5. Let done be ? IteratorComplete(innerResult).
      6. If done is true, then
        1. Let resultValue be Return ? IteratorValue(innerResult).
        2. If generatorKind is async, then set resultValue to ? Await(resultValue).
        3. Return resultValue.
      7. If generatorKind is async, then let received be AsyncGeneratorYield(? IteratorValue(innerResult)).
      8. Else, lLet received be GeneratorYield(innerResult).
    2. Else if received.[[Type]] is throw, then
      1. Let throw be ? GetMethod(iterator, "throw").
      2. If throw is not undefined, then
        1. Let innerResult be ? Call(throw, iterator, « received.[[Value]] »).
        2. If generatorKind is async, then set innerResult to ? Await(innerResult).
        3. NOTE: Exceptions from the inner iterator throw method are propagated. Normal completions from an inner throw method are processed similarly to an inner next.
        4. If Type(innerResult) is not Object, throw a TypeError exception.
        5. Let done be ? IteratorComplete(innerResult).
        6. If done is true, then
          1. Let resultValue be Return ? IteratorValue(innerResult).
          2. If generatorKind is async, then set resultValue to ? Await(resultValue).
          3. Return resultValue.
        7. If generatorKind is async, then let received be AsyncGeneratorYield(? IteratorValue(innerResult)).
        8. Else, lLet received be GeneratorYield(innerResult).
      3. Else,
        1. NOTE: If iterator does not have a throw method, this throw is going to terminate the yield* loop. But first we need to give iterator a chance to clean up.
        2. Let closeCompletion be Completion{[[Type]]: normal, [[Value]]: empty, [[Target]]: empty}.
        3. If generatorKind is async, perform ? AsyncIteratorClose(iterator, closeCompletion).
        4. Else, pPerform ? IteratorClose(iterator, Completion{[[Type]]: normal, [[Value]]: empty, [[Target]]: empty}closeCompletion).
        5. NOTE: The next step throws a TypeError to indicate that there was a yield* protocol violation: iterator does not have a throw method.
        6. Throw a TypeError exception.
    3. Else,
      1. Assert: received.[[Type]] is return.
      2. Let return be ? GetMethod(iterator, "return").
      3. If return is undefined, return Completion(received).
      4. Let innerReturnResult be ? Call(return, iterator, « received.[[Value]] »).
      5. If generatorKind is async, then set innerReturnResult to ? Await(innerReturnResult).
      6. If Type(innerReturnResult) is not Object, throw a TypeError exception.
      7. Let done be ? IteratorComplete(innerReturnResult).
      8. If done is true, then
        1. Let value be ? IteratorValue(innerReturnResult).
        2. If generatorKind is async, then set value to ? Await(value).
        3. Return Completion{[[Type]]: return, [[Value]]: value, [[Target]]: empty}.
      9. If generatorKind is async, then let received be AsyncGeneratorYield(? IteratorValue(innerResult)).
      10. Else, lLet received be GeneratorYield(innerResult).

8.3Async Generator Function Definitions

Syntax

AsyncGeneratorMethod[Yield, Await]:async[no LineTerminator here]*PropertyName[?Yield, ?Await](UniqueFormalParameters[+Yield, +Await]){AsyncGeneratorBody} AsyncGeneratorDeclaration[Yield, Await, Default]:async[no LineTerminator here]function*BindingIdentifier[?Yield, ?Await](FormalParameters[+Yield, +Await]){AsyncGeneratorBody} [+Default]async[no LineTerminator here]function*(FormalParameters[+Yield, +Await]){AsyncGeneratorBody} AsyncGeneratorExpression:async[no LineTerminator here]function*BindingIdentifier[+Yield, +Await]opt(FormalParameters[+Yield, +Await]){AsyncGeneratorBody} AsyncGeneratorBody:FunctionBody[+Yield, +Await] Note 1

YieldExpression and AwaitExpression cannot be used within the FormalParameters of an async generator function because any expressions that are part of FormalParameters are evaluated before the resulting async generator object is in a resumable state.

Note 2

Abstract operations relating to async generator objects are defined in 11.4.3.

8.3.1Static Semantics: Early Errors

AsyncGeneratorMethod:*PropertyName(UniqueFormalParameters){AsyncGeneratorBody} AsyncGeneratorDeclaration:function*BindingIdentifier(FormalParameters){AsyncGeneratorBody} AsyncGeneratorDeclaration:function*(FormalParameters){AsyncGeneratorBody} AsyncGeneratorDeclaration:function*BindingIdentifieropt(FormalParameters){AsyncGeneratorBody}

8.3.2Static Semantics: BoundNames

AsyncGeneratorDeclaration:function*BindingIdentifier(FormalParameters){AsyncGeneratorBody}
  1. Return the BoundNames of BindingIdentifier.
AsyncGeneratorDeclaration:function*(FormalParameters){AsyncGeneratorBody}
  1. Return « "*default*" ».
Note

"*default*" is used within this specification as a synthetic name for hoistable anonymous functions that are defined using export declarations.

8.3.3Static Semantics: ComputedPropertyContains

With parameter symbol.

AsyncGeneratorMethod:*PropertyName(UniqueFormalParameters){AsyncGeneratorBody}
  1. Return the result of ComputedPropertyContains for PropertyName with argument symbol.

8.3.4Static Semantics: Contains

With parameter symbol.

AsyncGeneratorDeclaration:function*BindingIdentifier(FormalParameters){AsyncGeneratorBody} AsyncGeneratorDeclaration:function*(FormalParameters){AsyncGeneratorBody} AsyncGeneratorExpression:function*BindingIdentifieropt(FormalParameters){AsyncGeneratorBody}
  1. Return false.
Note

Static semantic rules that depend upon substructure generally do not look into function definitions.

8.3.5Static Semantics: HasDirectSuper

AsyncGeneratorMethod:*PropertyName(UniqueFormalParameters){AsyncGeneratorBody}
  1. If UniqueFormalParameters Contains SuperCall is true, return true.
  2. Return AsyncGeneratorBody Contains SuperCall.

8.3.6Static Semantics: HasName

AsyncGeneratorExpression:function*(FormalParameters){AsyncGeneratorBody}
  1. Return false.
AsyncGeneratorExpression:function*BindingIdentifier(FormalParameters){AsyncGeneratorBody}
  1. Return true.

8.3.7Static Semantics: IsConstantDeclaration

AsyncGeneratorDeclaration:function*BindingIdentifier(FormalParameters){AsyncGeneratorBody} AsyncGeneratorDeclaration:function*(FormalParameters){AsyncGeneratorBody}
  1. Return false.

8.3.8Static Semantics: IsFunctionDefinition

AsyncGeneratorExpression:function*BindingIdentifieropt(FormalParameters){AsyncGeneratorBody}
  1. Return true.

8.3.9Static Semantics: PropName

AsyncGeneratorMethod:*PropertyName(UniqueFormalParameters){AsyncGeneratorBody}
  1. Return PropName of PropertyName.

8.3.10Runtime Semantics: EvaluateBody

With parameters functionObject and List argumentsList.

AsyncGeneratorBody:FunctionBody
  1. Perform ? FunctionDeclarationInstantiation(functionObject, argumentsList).
  2. Let generator be ? OrdinaryCreateFromConstructor(functionObject, "%AsyncGeneratorPrototype%", « [[AsyncGeneratorState]], [[AsyncGeneratorContext]], [[AsyncGeneratorQueue]] »).
  3. Perform ! AsyncGeneratorStart(generator, FunctionBody).
  4. Return Completion{[[Type]]: return, [[Value]]: generator, [[Target]]: empty}.

8.3.11Runtime Semantics: InstantiateFunctionObject

With parameter scope.

AsyncGeneratorDeclaration:async[no LineTerminator here]function*BindingIdentifier(FormalParameters){AsyncGeneratorBody}
  1. If the function code for AsyncGeneratorDeclaration is strict mode code, let strict be true. Otherwise let strict be false.
  2. Let name be StringValue of BindingIdentifier.
  3. Let F be ! AsyncGeneratorFunctionCreate(Normal, FormalParameters, AsyncGeneratorBody, scope, strict).
  4. Let prototype be ! ObjectCreate(%AsyncGeneratorPrototype%).
  5. Perform ! DefinePropertyOrThrow(F, "prototype", PropertyDescriptor{[[Value]]: prototype, [[Writable]]: true, [[Enumerable]]: false, [[Configurable]]: false}).
  6. Perform ! SetFunctionName(F, name).
  7. Return F.
AsyncGeneratorDeclaration:async[no LineTerminator here]function*(FormalParameters){AsyncGeneratorBody}
  1. If the function code for AsyncGeneratorDeclaration is strict mode code, let strict be true. Otherwise let strict be false.
  2. Let F be AsyncGeneratorFunctionCreate(Normal, FormalParameters, AsyncGeneratorBody, scope, strict).
  3. Let prototype be ObjectCreate(%AsyncGeneratorPrototype%).
  4. Perform DefinePropertyOrThrow(F, "prototype", PropertyDescriptor{[[Value]]: prototype, [[Writable]]: true, [[Enumerable]]: false, [[Configurable]]: false}).
  5. Perform SetFunctionName(F, "default").
  6. Return F.
Note

An anonymous AsyncGeneratorDeclaration can only occur as part of an export default declaration.

8.3.12Runtime Semantics: PropertyDefinitionEvaluation

With parameter object and enumerable.

AsyncGeneratorMethod:async[no LineTerminator here]*PropertyName(UniqueFormalParameters){AsyncGeneratorBody}
  1. Let propKey be the result of evaluating PropertyName.
  2. ReturnIfAbrupt(propKey).
  3. If the function code for this AsyncGeneratorMethod is strict mode code, let strict be true. Otherwise let strict be false.
  4. Let scope be the running execution context's LexicalEnvironment.
  5. Let closure be ! AsyncGeneratorFunctionCreate(Method, UniqueFormalParameters, AsyncGeneratorBody, scope, strict).
  6. Perform ! MakeMethod(closure, object).
  7. Let prototype be ! ObjectCreate(%AsyncGeneratorPrototype%).
  8. Perform ! DefinePropertyOrThrow(closure, "prototype", PropertyDescriptor{[[Value]]: prototype, [[Writable]]: true, [[Enumerable]]: false, [[Configurable]]: false}).
  9. Perform ! SetFunctionName(closure, propKey).
  10. Let desc be PropertyDescriptor{[[Value]]: closure, [[Writable]]: true, [[Enumerable]]: enumerable, [[Configurable]]: true}.
  11. Return ? DefinePropertyOrThrow(object, propKey, desc).

8.3.13Runtime Semantics: Evaluation

AsyncGeneratorExpression:async[no LineTerminator here]function*(FormalParameters){AsyncGeneratorBody}
  1. If the function code for this AsyncGeneratorExpression is strict mode code, let strict be true. Otherwise let strict be false.
  2. Let scope be the LexicalEnvironment of the running execution context.
  3. Let closure be ! AsyncGeneratorFunctionCreate(Normal, FormalParameters, AsyncGeneratorBody, scope, strict).
  4. Let prototype be ! ObjectCreate(%AsyncGeneratorPrototype%).
  5. Perform ! DefinePropertyOrThrow(closure, "prototype", PropertyDescriptor{[[Value]]: prototype, [[Writable]]: true, [[Enumerable]]: false, [[Configurable]]: false}).
  6. Return closure.
AsyncGeneratorExpression:async[no LineTerminator here]function*BindingIdentifier(FormalParameters){AsyncGeneratorBody}
  1. If the function code for this AsyncGeneratorExpression is strict mode code, let strict be true. Otherwise let strict be false.
  2. Let scope be the running execution context's LexicalEnvironment.
  3. Let funcEnv be ! NewDeclarativeEnvironment(scope).
  4. Let envRec be funcEnv's EnvironmentRecord.
  5. Let name be StringValue of BindingIdentifier.
  6. Perform ! envRec.CreateImmutableBinding(name).
  7. Let closure be ! AsyncGeneratorFunctionCreate(Normal, FormalParameters, AsyncGeneratorBody, funcEnv, strict).
  8. Let prototype be ! ObjectCreate(%AsyncGeneratorPrototype%).
  9. Perform ! DefinePropertyOrThrow(closure, "prototype", PropertyDescriptor{[[Value]]: prototype, [[Writable]]: true, [[Enumerable]]: false, [[Configurable]]: false}).
  10. Perform ! SetFunctionName(closure, name).
  11. Perform ! envRec.InitializeBinding(name, closure).
  12. Return closure.
Note

The BindingIdentifier in an AsyncGeneratorExpression can be referenced from inside the AsyncGeneratorExpression's AsyncGeneratorBody to allow the generator code to call itself recursively. However, unlike in an AsyncGeneratorDeclaration, the BindingIdentifier in an AsyncGeneratorExpression cannot be referenced from and does not affect the scope enclosing the AsyncGeneratorExpression.

9Runtime Semantics: CreateDynamicFunction(constructor, newTarget, kind, args)

Editor's Note
This patch modifies 19.2.1.1.1.

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 List containing the actual argument values that were passed to constructor. The following steps are taken:

  1. Assert: The execution context stack has at least two elements.
  2. Let callerContext be the second to top element of the execution context stack.
  3. Let callerRealm be callerContext's Realm.
  4. Let calleeRealm be the current Realm Record.
  5. Perform ? HostEnsureCanCompileStrings(callerRealm, calleeRealm).
  6. If newTarget is undefined, let newTarget be constructor.
  7. If kind is "normal", then
    1. Let goal be the grammar symbol FunctionBody[~Yield, ~Await].
    2. Let parameterGoal be the grammar symbol FormalParameters[~Yield, ~Await].
    3. Let fallbackProto be "%FunctionPrototype%".
  8. Else if kind is "generator", then
    1. Let goal be the grammar symbol GeneratorBody.
    2. Let parameterGoal be the grammar symbol FormalParameters[+Yield, ~Await].
    3. Let fallbackProto be "%Generator%".
  9. Else,
  10. Else if kind is "async",
    1. Assert: kind is "async"
    2. Let goal be the grammar symbol AsyncFunctionBody.
    3. Let parameterGoal be the grammar symbol FormalParameters[~Yield, +Await].
    4. Let fallbackProto be "%AsyncFunctionPrototype%".
  11. Else,
    1. Assert: kind is "async generator"
    2. Let goal be the grammar symbol AsyncGeneratorBody.
    3. Let parameterGoal be the grammar symbol FormalParameters[+Yield, +Await].
    4. Let fallbackProto be "%AsyncGenerator%".
  12. Let argCount be the number of elements in args.
  13. Let P be the empty String.
  14. If argCount = 0, let bodyText be the empty String.
  15. Else if argCount = 1, let bodyText be args[0].
  16. Else argCount > 1,
    1. Let firstArg be args[0].
    2. Let P be ? ToString(firstArg).
    3. Let k be 1.
    4. Repeat, while k < argCount-1
      1. Let nextArg be args[k].
      2. Let nextArgString be ? ToString(nextArg).
      3. Let P be the result of concatenating the previous value of P, the String "," (a comma), and nextArgString.
      4. Increase k by 1.
    5. Let bodyText be args[k].
  17. Let bodyText be ? ToString(bodyText).
  18. Let parameters be the result of parsing P, interpreted as UTF-16 encoded Unicode text as described in 6.1.4, using parameterGoal as the goal symbol. Throw a SyntaxError exception if the parse fails.
  19. Let body be the result of parsing bodyText, interpreted as UTF-16 encoded Unicode text as described in 6.1.4, using goal as the goal symbol. Throw a SyntaxError exception if the parse fails.
  20. If bodyText is strict mode code, let strict be true, else let strict be false.
  21. If any static semantics errors are detected for parameters or body, throw a SyntaxError or a ReferenceError exception, depending on the type of the error. If strict is true, the Early Error rules for UniqueFormalParameters:FormalParameters are applied. Parsing and early error detection may be interweaved in an implementation-dependent manner.
  22. If ContainsUseStrict of body is true and IsSimpleParameterList of parameters is false, throw a SyntaxError exception.
  23. If any element of the BoundNames of parameters also occurs in the LexicallyDeclaredNames of body, throw a SyntaxError exception.
  24. If body Contains SuperCall is true, throw a SyntaxError exception.
  25. If parameters Contains SuperCall is true, throw a SyntaxError exception.
  26. If body Contains SuperProperty is true, throw a SyntaxError exception.
  27. If parameters Contains SuperProperty is true, throw a SyntaxError exception.
  28. If kind is "generator" or "async generator", then
    1. If parameters Contains YieldExpression is true, throw a SyntaxError exception.
  29. If kind is "async" or "async generator", then
    1. If parameters Contains AwaitExpression is true, throw a SyntaxError exception.
  30. If strict is true, then
    1. If BoundNames of parameters contains any duplicate elements, throw a SyntaxError exception.
  31. Let proto be ? GetPrototypeFromConstructor(newTarget, fallbackProto).
  32. Let F be FunctionAllocate(proto, strict, kind).
  33. Let realmF be F.[[Realm]].
  34. Let scope be realmF.[[GlobalEnv]].
  35. Perform FunctionInitialize(F, Normal, parameters, body, scope).
  36. If kind is "generator", then
    1. Let prototype be ObjectCreate(%GeneratorPrototype%).
    2. Perform DefinePropertyOrThrow(F, "prototype", PropertyDescriptor{[[Value]]: prototype, [[Writable]]: true, [[Enumerable]]: false, [[Configurable]]: false}).
  37. Else if kind is "async generator", then
    1. Let prototype be ObjectCreate(%AsyncGeneratorPrototype%).
    2. Perform DefinePropertyOrThrow(F, "prototype", PropertyDescriptor{[[Value]]: prototype, [[Writable]]: true, [[Enumerable]]: false, [[Configurable]]: false}).
  38. Else if kind is "normal", perform MakeConstructor(F).
  39. NOTE: Async functions are not constructable and do not have a [[Construct]] internal method or a "prototype" property.
  40. Perform SetFunctionName(F, "anonymous").
  41. Return F.
Note

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.

10Properties of the Symbol Constructor

Editor's Note
This patch add a clause to 19.4.2.

10.1Symbol.asyncIterator

The initial value of Symbol.asyncIterator is the well known symbol @@asyncIterator (Table 1).

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.

11Control Abstraction Objects

Editor's Note
These patches modify clauses of and add clauses to 25.

11.1Iteration

11.1.1Common Iteration Interfaces

11.1.1.1The AsyncIterable Interface

The AsyncIterable interface includes the properties described in Table 3:

Table 3: AsyncIterable Interface Required Properties
Property Value Requirements
@@asyncIterator A function that returns an AsyncIterator object. The returned object must conform to the AsyncIterator interface.

11.1.1.2The AsyncIterator Interface

An object that implements the AsyncIterator interface must include the properties in Table 4. Such objects may also implement the properties in Table 5.

Table 4: AsyncIterator Interface Required Properties
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 next method of an AsyncIterator has returned a promise for an IteratorResult object whose done property is true, then all subsequent calls to the next method of that object should also return a promise for an IteratorResult object whose done property is true. However, this requirement is not enforced.

Additionally, the IteratorResult object that serves as a fulfillment value should have a value property whose value is not a promise (or "thenable"). However, this requirement is also not enforced.

Note 1

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.

Table 5: AsyncIterator Interface Optional Properties
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 next method calls to the AsyncIterator. The returned promise will fulfill with an IteratorResult object which will typically have a done property whose value is true, and a value property with the value passed as the argument of the return method. However, this requirement is not enforced.

Additionally, the IteratorResult object that serves as a fulfillment value should have a value property whose value is not a promise (or "thenable"). If the argument value is used in the typical manner, then if it is a rejected promise, a promise rejected with the same reason should be returned; if it is a fulfilled promise, then its fulfillment value should be used as the value property of the returned promise's IteratorResult object fulfillment value. However, these requirements are also not enforced.

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 done property whose value is true. Additionally, it should have a value property whose value is not a promise (or "thenable"), but this requirement is not enforced.

Note 2

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.

11.1.1.2.1Async Iterator Value Unwrap Functions

An async iterator value unwrap function is an anonymous built-in function that is used when processing the 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 iterator unwrap function F is called with argument value, the following steps are taken:

  1. Return ! CreateIterResultObject(value, F.[[Done]]).

11.1.2The %AsyncIteratorPrototype% Object

The value of the [[Prototype]] internal slot of the %AsyncIteratorPrototype% object is the intrinsic object %ObjectPrototype%. The %AsyncIteratorPrototype% object is an ordinary object. The initial value of the [[Extensible]] internal slot of the %AsyncIteratorPrototype% object is true.

Note

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.

11.1.2.1%AsyncIteratorPrototype% [ @@asyncIterator ] ( )

The following steps are taken:

  1. Return the this value.

The value of the name property of this function is "[Symbol.asyncIterator]".

11.1.3Async-from-Sync Iterator Objects

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 CreateAsyncFromSyncIterator abstract operation as needed.

11.1.3.1CreateAsyncFromSyncIterator(syncIterator) Abstract Operation

The abstract operation CreateAsyncFromSyncIterator is used to create an async iterator from a synchronous iterator. It performs the following steps:

  1. If Type(syncIterator) is not Object, throw a TypeError exception.
  2. Let asyncIterator be ! ObjectCreate(%AsyncFromSyncIteratorPrototype%, « [[SyncIterator]] »).
  3. Set asyncIterator.[[SyncIterator]] to syncIterator.
  4. Return asyncIterator.

11.1.3.2The %AsyncFromSyncIteratorPrototype% Object

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 %AsyncIteratorPrototype% intrinsic object. In addition, %AsyncFromSyncIteratorPrototype% has the following properties:

11.1.3.2.1%AsyncFromSyncIteratorPrototype%.next ( value )

  1. Let O be the this value.
  2. Let promiseCapability be ! NewPromiseCapability(%Promise%).
  3. If Type(O) is not Object, or if O does not have a [[SyncIterator]] internal slot, then
    1. Let badIteratorError be a new TypeError exception.
    2. Perform ! Call(promiseCapability.[[Reject]], undefined, « badIteratorError »).
    3. Return promiseCapability.[[Promise]].
  4. Let syncIterator be O.[[SyncIterator]].
  5. Let nextResult be IteratorNext(syncIterator, value).
  6. IfAbruptRejectPromise(nextResult, promiseCapability).
  7. Let nextDone be IteratorComplete(nextResult).
  8. IfAbruptRejectPromise(nextDone, promiseCapability).
  9. Let nextValue be IteratorValue(nextResult).
  10. IfAbruptRejectPromise(nextValue, promiseCapability).
  11. Let valueWrapperCapability be ! NewPromiseCapability(%Promise%).
  12. Perform ! Call(valueWrapperCapability.[[Resolve]], undefined, « nextValue »).
  13. Let onFulfilled be a new built-in function object as defined in Async Iterator Value Unwrap Functions.
  14. Set onFulfilled.[[Done]] to nextDone.
  15. Perform ! PerformPromiseThen(valueWrapperCapability.[[Promise]], onFulfilled, undefined, promiseCapability).
  16. Return promiseCapability.[[Promise]].

11.1.3.2.2%AsyncFromSyncIteratorPrototype%.return ( value )

  1. Let O be the this value.
  2. Let promiseCapability be ! NewPromiseCapability(%Promise%).
  3. If Type(O) is not Object, or if O does not have a [[SyncIterator]] internal slot, then
    1. Let badIteratorError be a new TypeError exception.
    2. Perform ! Call(promiseCapability.[[Reject]], undefined, « badIteratorError »).
    3. Return promiseCapability.[[Promise]].
  4. Let syncIterator be O.[[SyncIterator]].
  5. Let return be GetMethod(syncIterator, "return").
  6. IfAbruptRejectPromise(return, promiseCapability).
  7. If return is undefined, then
    1. Let iterResult be ! CreateIterResultObject(value, true).
    2. Perform ! Call(promiseCapability.[[Resolve]], undefined, « iterResult »).
    3. Return promiseCapability.[[Promise]].
  8. Let returnResult be Call(return, syncIterator, « value »).
  9. IfAbruptRejectPromise(returnResult, promiseCapability).
  10. If Type(returnResult) is not Object,
    1. Perform ! Call(promiseCapability.[[Reject]], undefined, « a TypeError exception »).
    2. Return promiseCapability.[[Promise]].
  11. Let returnDone be IteratorComplete(returnResult).
  12. IfAbruptRejectPromise(returnDone, promiseCapability).
  13. Let returnValue be IteratorValue(returnResult).
  14. IfAbruptRejectPromise(returnValue, promiseCapability).
  15. Let valueWrapperCapability be ! NewPromiseCapability(%Promise%).
  16. Perform ! Call(valueWrapperCapability.[[Resolve]], undefined, « returnValue »).
  17. Let onFulfilled be a new built-in function object as defined in Async Iterator Value Unwrap Functions.
  18. Set onFulfilled.[[Done]] to returnDone.
  19. Perform ! PerformPromiseThen(valueWrapperCapability.[[Promise]], onFulfilled, undefined, promiseCapability).
  20. Return promiseCapability.[[Promise]].

11.1.3.2.3%AsyncFromSyncIteratorPrototype%.throw ( value )

  1. Let O be the this value.
  2. Let promiseCapability be ! NewPromiseCapability(%Promise%).
  3. If Type(O) is not Object, or if O does not have a [[SyncIterator]] internal slot, then
    1. Let badIteratorError be a new TypeError exception.
    2. Perform ! Call(promiseCapability.[[Reject]], undefined, « badIteratorError »).
    3. Return promiseCapability.[[Promise]].
  4. Let syncIterator be O.[[SyncIterator]].
  5. Let throw be GetMethod(syncIterator, "throw").
  6. IfAbruptRejectPromise(throw, promiseCapability).
  7. If throw is undefined, then
    1. Perform ! Call(promiseCapability.[[Reject]], undefined, « value »).
    2. Return promiseCapability.[[Promise]].
  8. Let throwResult be Call(throw, syncIterator, « value »).
  9. IfAbruptRejectPromise(throwResult, promiseCapability).
  10. If Type(throwResult) is not Object,
    1. Perform ! Call(promiseCapability.[[Reject]], undefined, « a TypeError exception »).
    2. Return promiseCapability.[[Promise]].
  11. Let throwDone be IteratorComplete(throwResult).
  12. IfAbruptRejectPromise(throwDone, promiseCapability).
  13. Let throwValue be IteratorValue(throwResult).
  14. IfAbruptRejectPromise(throwValue, promiseCapability).
  15. Let valueWrapperCapability be ! NewPromiseCapability(%Promise%).
  16. Perform ! Call(valueWrapperCapability.[[Resolve]], undefined, « throwValue »).
  17. Let onFulfilled be a new built-in function object as defined in Async Iterator Value Unwrap Functions.
  18. Set onFulfilled.[[Done]] to throwDone.
  19. Perform ! PerformPromiseThen(valueWrapperCapability.[[Promise]], onFulfilled, undefined, promiseCapability).
  20. Return promiseCapability.[[Promise]].

11.1.3.2.4%AsyncFromSyncIteratorPrototype% [ @@toStringTag ]

The initial value of the @@toStringTag property is the String value "Async-from-Sync Iterator".

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.

11.1.3.3Properties of Async-from-Sync Iterator Instances

Async-from-Sync Iterator instances are ordinary objects that inherit properties from the %AsyncFromSyncIteratorPrototype% intrinsic object. Async-from-Sync Iterator instances are initially created with the internal slots listed in Table 6.

Table 6: Internal Slots of Async-from-Sync Iterator Instances
Internal Slot Description
[[SyncIterator]] The original synchronous iterator which is being adapted.

11.2Generator Objects

11.2.1Generator Abstract Operations

11.2.1.1GetGeneratorKind ( )

  1. Let genContext be the running execution context.
  2. Assert: genContext has a Generator component.
  3. Let generator be the Generator component of genContext.
  4. If generator has an [[AsyncGeneratorState]] internal slot, return async.
  5. Else, return normal.

11.2.1.2GeneratorYield ( iterNextObj )

The abstract operation GeneratorYield with argument iterNextObj performs the following steps:

  1. Assert: iterNextObj is an Object that implements the IteratorResult interface.
  2. Let genContext be the running execution context.
  3. Assert: genContext is the execution context of a generator.
  4. Let generator be the value of the Generator component of genContext.
  5. Assert: GetGeneratorKind() is normal.
  6. Set generator.[[GeneratorState]] to "suspendedYield".
  7. Remove genContext from the execution context stack and restore the execution context that is at the top of the execution context stack as the running execution context.
  8. Set the code evaluation state of genContext such that when evaluation is resumed with a Completion resumptionValue the following steps will be performed:
    1. Return resumptionValue.
    2. NOTE: This returns to the evaluation of the YieldExpression that originally called this abstract operation.
  9. Return NormalCompletion(iterNextObj).
  10. NOTE: This returns to the evaluation of the operation that had most previously resumed evaluation of genContext.

11.3AsyncGeneratorFunction Objects

AsyncGenerator Function objects are functions that are usually created by evaluating AsyncGeneratorDeclaration, AsyncGeneratorExpression, and AsyncGeneratorMethod syntactic productions. They may also be created by calling the %AsyncGeneratorFunction% intrinsic.

11.3.1The AsyncGeneratorFunction Constructor

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.

11.3.1.1AsyncGeneratorFunction ( p1, p2, ..., pn, body )

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:

  1. Let C be the active function object.
  2. Let args be the argumentsList that was passed to this function by [[Call]] or [[Construct]].
  3. Return ? CreateDynamicFunction(C, NewTarget, "async generator", args).
Note

See NOTE for 19.2.1.1.

11.3.2Properties of the AsyncGeneratorFunction Constructor

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 %Function%.

The value of the [[Extensible]] internal slot of the AsyncGeneratorFunction constructor is true.

The value of the name property of the AsyncGeneratorFunction is "AsyncGeneratorFunction".

The AsyncGeneratorFunction constructor has the following properties:

11.3.2.1AsyncGeneratorFunction.length

This is a data property with a value of 1. This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.

11.3.2.2AsyncGeneratorFunction.prototype

The initial value of AsyncGeneratorFunction.prototype is the intrinsic object %AsyncGenerator%.

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.

11.3.3Properties of the AsyncGeneratorFunction Prototype Object

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 Table 27 or Table 7. In addition to being the value of the prototype property of the %AsyncGeneratorFunction% intrinsic, it is the %AsyncGenerator% intrinsic.

The value of the [[Prototype]] internal slot of the AsyncGeneratorFunction prototype object is the %FunctionPrototype% intrinsic object. The initial value of the [[Extensible]] internal slot of the AsyncGeneratorFunction prototype object is true.

11.3.3.1AsyncGeneratorFunction.prototype.constructor

The initial value of AsyncGeneratorFunction.prototype.constructor is the intrinsic object %AsyncGeneratorFunction%.

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.

11.3.3.2AsyncGeneratorFunction.prototype.prototype

The value of AsyncGeneratorFunction.prototype.prototype is the %AsyncGeneratorPrototype% intrinsic object.

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.

11.3.3.3AsyncGeneratorFunction.prototype [ @@toStringTag ]

The initial value of the @@toStringTag property is the String value "AsyncGeneratorFunction".

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.

11.3.4AsyncGeneratorFunction Instances

Every AsyncGeneratorFunction instance is an ECMAScript function object and has the internal slots listed in Table 27. The value of the [[FunctionKind]] internal slot for all such instances is "generator".

Each AsyncGeneratorFunction instance has the following own properties:

11.3.4.1length

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]]: false, [[Enumerable]]: false, [[Configurable]]: true }.

11.3.4.2name

The specification for the name property of Function instances given in 19.2.4.2 also applies to AsyncGeneratorFunction instances.

11.3.4.3prototype

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]]: true, [[Enumerable]]: false, [[Configurable]]: false }.

Note

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.

11.4AsyncGenerator Objects

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, %AsyncGeneratorPrototype%.

11.4.1Properties of AsyncGenerator Prototype

The AsyncGenerator prototype object is the %AsyncGeneratorPrototype% intrinsic. It is also the initial value of the prototype property of the %AsyncGenerator% intrinsic (the AsyncGeneratorFunction.prototype).

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 %AsyncIteratorPrototype%. The initial value of the [[Extensible]] internal slot of the AsyncGenerator prototype object is true.

All AsyncGenerator instances indirectly inherit properties of the AsyncGenerator prototype object.

11.4.1.1AsyncGenerator.prototype.constructor

The initial value of AsyncGenerator.prototype.constructor is the intrinsic object %AsyncGenerator%.

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.

11.4.1.2AsyncGenerator.prototype.next ( value )

  1. Let generator be the this value.
  2. Let completion be NormalCompletion(value).
  3. Return ! AsyncGeneratorEnqueue(generator, completion).

11.4.1.3AsyncGenerator.prototype.return ( value )

  1. Let generator be the this value.
  2. Let completion be Completion{[[Type]]: return, [[Value]]: value, [[Target]]: empty}.
  3. Return ! AsyncGeneratorEnqueue(generator, completion).

11.4.1.4AsyncGenerator.prototype.throw ( exception )

  1. Let generator be the this value.
  2. Let completion be Completion{[[Type]]: throw, [[Value]]: exception, [[Target]]: empty}.
  3. Return ! AsyncGeneratorEnqueue(generator, completion).

11.4.1.5AsyncGenerator.prototype [ @@toStringTag ]

The initial value of the @@toStringTag property is the String value "AsyncGenerator".

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.

11.4.2Properties of AsyncGenerator Instances

AsyncGenerator instances are initially created with the internal slots described below:

Table 7: Internal Slots of AsyncGenerator Instances
Internal Slot Description
[[AsyncGeneratorState]] The current execution state of the async generator. The possible values are: undefined, "suspendedStart", "suspendedYield", "executing", and "completed".
[[AsyncGeneratorContext]] The execution context that is used when executing the code of this async generator.
[[AsyncGeneratorQueue]] A List of AsyncGeneratorRequest records which represent requests to resume the async generator.

11.4.3AsyncGenerator Abstract Operations

11.4.3.1AsyncGeneratorRequest Records

The AsyncGeneratorRequest is a Record value used to store information about how an async generator should be resumed and contains capabilities for fulfilling or rejecting the corresponding promise.

They have the following fields:

Table 8: AsyncGeneratorRequest Record Fields
Field Name Value Meaning
[[Completion]] A Completion record The completion which should be used to resume the async generator.
[[Capability]] A PromiseCapability record The promise capabilities associated with this request.

11.4.3.2AsyncGeneratorStart ( generator, generatorBody )

  1. Assert: generator is an AsyncGenerator instance.
  2. Assert: generator.[[AsyncGeneratorState]] is undefined.
  3. Let genContext be the running execution context.
  4. Set the Generator component of genContext to generator.
  5. Set the code evaluation state of genContext such that when evaluation is resumed for that execution context the following steps will be performed:
    1. Let result be the result of evaluating generatorBody.
    2. Assert: If we return here, the async generator either threw an exception or performed either an implicit or explicit return.
    3. Remove genContext from the execution context stack and restore the execution context that is at the top of the execution context stack as the running execution context.
    4. Set generator.[[AsyncGeneratorState]] to "completed".
    5. If result is a normal completion, let resultValue be undefined.
    6. Else,
      1. Let resultValue be result.[[Value]].
      2. If result.[[Type]] is not return, then
        1. Return ! AsyncGeneratorReject(generator, resultValue).
    7. Return ! AsyncGeneratorResolve(generator, resultValue, true).
  6. Set generator.[[AsyncGeneratorContext]] to genContext.
  7. Set generator.[[AsyncGeneratorState]] to "suspendedStart".
  8. Set generator.[[AsyncGeneratorQueue]] to a new empty List.
  9. Return undefined.

11.4.3.3AsyncGeneratorResolve ( generator, value, done )

  1. Assert: generator is an AsyncGenerator instance.
  2. Let queue be generator.[[AsyncGeneratorQueue]].
  3. Assert: queue is not an empty List.
  4. Remove the first element from queue and let next be the value of that element.
  5. Let promiseCapability be next.[[Capability]].
  6. Let valueWrapperCapability be ! NewPromiseCapability(%Promise%).
  7. Perform ! Call(valueWrapperCapability.[[Resolve]], undefined, « value »).
  8. Let onFulfilled be a new built-in function object as defined in Async Iterator Value Unwrap Functions.
  9. Set onFulfilled.[[Done]] to done.
  10. Perform ! PerformPromiseThen(valueWrapperCapability.[[Promise]], onFulfilled, undefined, promiseCapability).
  11. Perform ! AsyncGeneratorResumeNext(generator).
  12. Return undefined.

11.4.3.4AsyncGeneratorReject ( generator, exception )

  1. Assert: generator is an AsyncGenerator instance.
  2. Let queue be generator.[[AsyncGeneratorQueue]].
  3. Assert: queue is not an empty List.
  4. Remove the first element from queue and let next be the value of that element.
  5. Let promiseCapability be next.[[Capability]].
  6. Perform ! Call(promiseCapability.[[Reject]], undefined, « exception »).
  7. Perform ! AsyncGeneratorResumeNext(generator).
  8. Return undefined.

11.4.3.5AsyncGeneratorResumeNext ( generator )

  1. Assert: generator is an AsyncGenerator instance.
  2. Let state be generator.[[AsyncGeneratorState]].
  3. Assert: state is not "executing".
  4. Let queue be generator.[[AsyncGeneratorQueue]].
  5. If queue is an empty List, return undefined.
  6. Let next be the value of the first element of queue.
  7. Assert: next is an AsyncGeneratorRequest record.
  8. Let completion be next.[[Completion]].
  9. If completion is an abrupt completion, then
    1. If state is "suspendedStart", then
      1. Set generator.[[AsyncGeneratorState]] to "completed".
      2. Set state to "completed".
    2. If state is "completed", then
      1. If completion.[[Type]] is return, then return ! AsyncGeneratorResolve(generator, completion.[[Value]], true).
      2. Else, return ! AsyncGeneratorReject(generator, completion.[[Value]]).
  10. Else if state is "completed", then return ! AsyncGeneratorResolve(generator, undefined, true).
  11. Assert: state is either "suspendedStart" or "suspendedYield".
  12. Let genContext be generator.[[AsyncGeneratorContext]].
  13. Let callerContext be the running execution context.
  14. Suspend callerContext.
  15. Set generator.[[AsyncGeneratorState]] to "executing".
  16. Push genContext onto the execution context stack; genContext is now the running execution context.
  17. Resume the suspended evaluation of genContext using completion as the result of the operation that suspended it. Let result be the completion record returned by the resumed computation.
  18. Assert: result is never an abrupt completion.
  19. Assert: When we return here, genContext has already been removed from the execution context stack and callerContext is the currently running execution context.
  20. Return undefined.

11.4.3.6AsyncGeneratorEnqueue ( generator, completion )

  1. Assert: completion is a Completion Record.
  2. Let promiseCapability be ! NewPromiseCapability(%Promise%).
  3. If Type(generator) is not Object, or if generator does not have an [[AsyncGeneratorState]] internal slot, then
    1. Let badGeneratorError be a new TypeError exception.
    2. Perform ! Call(promiseCapability.[[Reject]], undefined, « badGeneratorError »).
    3. Return promiseCapability.[[Promise]].
  4. Let queue be generator.[[AsyncGeneratorQueue]].
  5. Let request be AsyncGeneratorRequest{[[Completion]]: completion, [[Capability]]: promiseCapability}.
  6. Append request to the end of queue.
  7. Let state be generator.[[AsyncGeneratorState]].
  8. If state is not "executing", then
    1. Perform ! AsyncGeneratorResumeNext(generator).
  9. Return promiseCapability.[[Promise]].

11.4.3.7AsyncGeneratorYield ( value )

The abstract operation AsyncGeneratorYield with argument value performs the following steps:

  1. Let genContext be the running execution context.
  2. Assert: genContext is the execution context of a generator.
  3. Let generator be the value of the Generator component of genContext.
  4. Assert: GetGeneratorKind() is async.
  5. Set generator.[[AsyncGeneratorState]] to "suspendedYield".
  6. Remove genContext from the execution context stack and restore the execution context that is at the top of the execution context stack as the running execution context.
  7. Set the code evaluation state of genContext such that when evaluation is resumed with a Completion resumptionValue the following steps will be performed:
    1. Return resumptionValue.
    2. NOTE: This returns to the evaluation of the YieldExpression production that originally called this abstract operation.
  8. Return ! AsyncGeneratorResolve(generator, value, false).
  9. NOTE: This returns to the evaluation of the operation that had most previously resumed evaluation of genContext.

12Miscellaneous Patches

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.