ES2018 Feature: Async Iteration (for-await-of)

[JosephPecoraro]

Syntax:

A variation of the for-of iteration statement which iterates over async iterable objects (async generator). An example usage would be:

for await (const line of readLines(filePath)) {
  console.log(line);
}

async function* generator() { }

Async for-of statements are only allowed within async functions:

 IterationStatement[Yield, Await, Return]:
     ...
+    [+Await] for await ( [lookahead ≠ let] LeftHandSideExpression[?Yield, ?Await] of AssignmentExpression[+In, ?Yield, ?Await] ) Statement[?Yield, ?Await, ?Return]
+    [+Await] for await ( var ForBinding[?Yield, ?Await] of AssignmentExpression[+In, ?Yield, ?Await] ) Statement[?Yield, ?Await, ?Return]
+    [+Await] for await ( ForDeclaration[?Yield, ?Await] of AssignmentExpression[+In, ?Yield, ?Await] ) Statement[?Yield, ?Await, ?Return]

And async generator functions / methods are introduced:

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

Spec:

TC39:
https://github.com/tc39/proposal-async-iteration
https://tc39.es/proposal-async-iteration/

ESTree:
https://github.com/estree/estree/blob/master/es2018.md

---

extend interface ForOfStatement {
  await: boolean;
}

---

Additional considerations

• Supported in Chrome, Safari. (Firefox?)
• Supported in Node, jsc

Remaining Tasks:

• Update ForOfStatement node and docs (nodes.ts, docs/syntax-tree-format.md)
• Update Parser for for-await-of (parser.ts in parseForStatement)
• Update Parser for async generators (parser.ts allow for AsyncFunctionExpression, AsyncFunctionDeclaration which is a generator)
• Provide Unit Tests and Coverage
• Update test262 (~test262.git#2ee3864136) / test262-stream (~1.3.0)

Test Cases

Valid:

async function f() { for await (let x of []) {} }
async function *g() { for await (let x of []) {} }
o = { async method() { for await (let x of []) {} } }
o = { async *method() { for await (let x of []) {} } }

Invalid:

function f() { for await (let x of []) {} }
function *g() { for await (let x of []) {} }
o = { method() { for await (let x of []) {} } }
o = { *method() { for await (let x of []) {} } }

[imsamurai]

any news?