implement lowering of for await loops

Author: evanw

CHANGELOG.md

@@ -2,6 +2,39 @@
 
 ## Unreleased
 
+* Lower `for await` loops
+
+    This release lowers `for await` loops to the equivalent `for` loop containing `await` when esbuild is configured such that `for await` loops are unsupported. This transform still requires at least generator functions to be supported since esbuild's lowering of `await` currently relies on generators. This new transformation is modeled after what the TypeScript compiler does. Here's an example:
+
+    ```js
+    async function f() {
+      for await (let x of y)
+        x()
+    }
+    ```
+
+    The code above will now become the following code with `--target=es2017` (omitting the code for the `__forAwait` helper function):
+
+    ```js
+    async function f() {
+      try {
+        for (var iter = __forAwait(y), more, temp, error; more = !(temp = await iter.next()).done; more = false) {
+          let x = temp.value;
+          x();
+        }
+      } catch (temp) {
+        error = [temp];
+      } finally {
+        try {
+          more && (temp = iter.return) && await temp.call(iter);
+        } finally {
+          if (error)
+            throw error[0];
+        }
+      }
+    }
+    ```
+
 * Automatically fix invalid `supported` configurations ([#2497](https://github.com/evanw/esbuild/issues/2497))
 
     The `--target=` setting lets you tell esbuild to target a specific version of one or more JavaScript runtimes such as `chrome80,node14` and esbuild will restrict its output to only those features supported by all targeted JavaScript runtimes. More recently, esbuild introduced the `--supported:` setting that lets you override which features are supported on a per-feature basis. However, this now lets you configure nonsensical things such as `--supported:async-await=false --supported:async-generator=true`. Previously doing this could result in esbuild building successfully but producing invalid output.
@@ -15,7 +48,6 @@
 
     * `generator=false` implies:
         * `async-generator=false`
-        * `for-await=false`
 
     * `class-field=false` implies:
         * `class-private-field=false`

internal/bundler/bundler.go

@@ -2134,7 +2134,7 @@ func applyOptionDefaults(options *config.Options) {
 
 	// Automatically fix invalid configurations of unsupported features
 	fixInvalidUnsupportedJSFeatureOverrides(options, compat.AsyncAwait, compat.AsyncGenerator|compat.ForAwait|compat.TopLevelAwait)
-	fixInvalidUnsupportedJSFeatureOverrides(options, compat.Generator, compat.AsyncGenerator|compat.ForAwait)
+	fixInvalidUnsupportedJSFeatureOverrides(options, compat.Generator, compat.AsyncGenerator)
 	fixInvalidUnsupportedJSFeatureOverrides(options, compat.ClassField, compat.ClassPrivateField)
 	fixInvalidUnsupportedJSFeatureOverrides(options, compat.ClassStaticField, compat.ClassPrivateStaticField)
 	fixInvalidUnsupportedJSFeatureOverrides(options, compat.Class,

internal/bundler/bundler_lower_test.go

@@ -2297,3 +2297,45 @@ func TestLowerRegExpNameCollision(t *testing.T) {
 		},
 	})
 }
+
+func TestLowerForAwait2017(t *testing.T) {
+	lower_suite.expectBundled(t, bundled{
+		files: map[string]string{
+			"/entry.js": `
+				export default [
+					async () => { for await (x of y) z(x) },
+					async () => { for await (x.y of y) z(x) },
+					async () => { for await (let x of y) z(x) },
+					async () => { for await (const x of y) z(x) },
+				]
+			`,
+		},
+		entryPaths: []string{"/entry.js"},
+		options: config.Options{
+			Mode:                  config.ModePassThrough,
+			AbsOutputFile:         "/out.js",
+			UnsupportedJSFeatures: es(2017),
+		},
+	})
+}
+
+func TestLowerForAwait2015(t *testing.T) {
+	lower_suite.expectBundled(t, bundled{
+		files: map[string]string{
+			"/entry.js": `
+				export default [
+					async () => { for await (x of y) z(x) },
+					async () => { for await (x.y of y) z(x) },
+					async () => { for await (let x of y) z(x) },
+					async () => { for await (const x of y) z(x) },
+				]
+			`,
+		},
+		entryPaths: []string{"/entry.js"},
+		options: config.Options{
+			Mode:                  config.ModePassThrough,
+			AbsOutputFile:         "/out.js",
+			UnsupportedJSFeatures: es(2015),
+		},
+	})
+}

internal/bundler/snapshots/snapshots_lower.txt

@@ -626,6 +626,154 @@ export { ns };
 let ns2 = 123;
 export { ns2 as sn };
 
+================================================================================
+TestLowerForAwait2015
+---------- /out.js ----------
+export default [
+  () => __async(void 0, null, function* () {
+    try {
+      for (var iter = __forAwait(y), more, temp, error; more = !(temp = yield iter.next()).done; more = false) {
+        x = temp.value;
+        z(x);
+      }
+    } catch (temp) {
+      error = [temp];
+    } finally {
+      try {
+        more && (temp = iter.return) && (yield temp.call(iter));
+      } finally {
+        if (error)
+          throw error[0];
+      }
+    }
+  }),
+  () => __async(void 0, null, function* () {
+    try {
+      for (var iter = __forAwait(y), more, temp, error; more = !(temp = yield iter.next()).done; more = false) {
+        x.y = temp.value;
+        z(x);
+      }
+    } catch (temp) {
+      error = [temp];
+    } finally {
+      try {
+        more && (temp = iter.return) && (yield temp.call(iter));
+      } finally {
+        if (error)
+          throw error[0];
+      }
+    }
+  }),
+  () => __async(void 0, null, function* () {
+    try {
+      for (var iter = __forAwait(y), more, temp, error; more = !(temp = yield iter.next()).done; more = false) {
+        let x2 = temp.value;
+        z(x2);
+      }
+    } catch (temp) {
+      error = [temp];
+    } finally {
+      try {
+        more && (temp = iter.return) && (yield temp.call(iter));
+      } finally {
+        if (error)
+          throw error[0];
+      }
+    }
+  }),
+  () => __async(void 0, null, function* () {
+    try {
+      for (var iter = __forAwait(y), more, temp, error; more = !(temp = yield iter.next()).done; more = false) {
+        const x2 = temp.value;
+        z(x2);
+      }
+    } catch (temp) {
+      error = [temp];
+    } finally {
+      try {
+        more && (temp = iter.return) && (yield temp.call(iter));
+      } finally {
+        if (error)
+          throw error[0];
+      }
+    }
+  })
+];
+
+================================================================================
+TestLowerForAwait2017
+---------- /out.js ----------
+export default [
+  async () => {
+    try {
+      for (var iter = __forAwait(y), more, temp, error; more = !(temp = await iter.next()).done; more = false) {
+        x = temp.value;
+        z(x);
+      }
+    } catch (temp) {
+      error = [temp];
+    } finally {
+      try {
+        more && (temp = iter.return) && await temp.call(iter);
+      } finally {
+        if (error)
+          throw error[0];
+      }
+    }
+  },
+  async () => {
+    try {
+      for (var iter = __forAwait(y), more, temp, error; more = !(temp = await iter.next()).done; more = false) {
+        x.y = temp.value;
+        z(x);
+      }
+    } catch (temp) {
+      error = [temp];
+    } finally {
+      try {
+        more && (temp = iter.return) && await temp.call(iter);
+      } finally {
+        if (error)
+          throw error[0];
+      }
+    }
+  },
+  async () => {
+    try {
+      for (var iter = __forAwait(y), more, temp, error; more = !(temp = await iter.next()).done; more = false) {
+        let x2 = temp.value;
+        z(x2);
+      }
+    } catch (temp) {
+      error = [temp];
+    } finally {
+      try {
+        more && (temp = iter.return) && await temp.call(iter);
+      } finally {
+        if (error)
+          throw error[0];
+      }
+    }
+  },
+  async () => {
+    try {
+      for (var iter = __forAwait(y), more, temp, error; more = !(temp = await iter.next()).done; more = false) {
+        const x2 = temp.value;
+        z(x2);
+      }
+    } catch (temp) {
+      error = [temp];
+    } finally {
+      try {
+        more && (temp = iter.return) && await temp.call(iter);
+      } finally {
+        if (error)
+          throw error[0];
+      }
+    }
+  }
+];
+
 ================================================================================
 TestLowerNullishCoalescingAssignmentIssue1493
 ---------- /out.js ----------

internal/js_parser/js_parser.go

@@ -6595,10 +6595,16 @@ func (p *parser) parseStmt(opts parseStmtOpts) js_ast.Stmt {
 				p.log.AddError(&p.tracker, awaitRange, "Cannot use \"await\" outside an async function")
 				isForAwait = false
 			} else {
-				didGenerateError := p.markSyntaxFeature(compat.ForAwait, awaitRange)
-				if p.fnOrArrowDataParse.isTopLevel && !didGenerateError {
+				didGenerateError := false
+				if p.fnOrArrowDataParse.isTopLevel {
 					p.topLevelAwaitKeyword = awaitRange
-					p.markSyntaxFeature(compat.TopLevelAwait, awaitRange)
+					didGenerateError = p.markSyntaxFeature(compat.TopLevelAwait, awaitRange)
+				}
+				if !didGenerateError && p.options.unsupportedJSFeatures.Has(compat.AsyncAwait) && p.options.unsupportedJSFeatures.Has(compat.Generator) {
+					// If for-await loops aren't supported, then we only support lowering
+					// if either async/await or generators is supported. Otherwise we
+					// cannot lower for-await loops.
+					p.markSyntaxFeature(compat.ForAwait, awaitRange)
 				}
 			}
 			p.lexer.Next()
@@ -9827,6 +9833,10 @@ func (p *parser) visitAndAppendStmt(stmts []js_ast.Stmt, stmt js_ast.Stmt) []js_
 
 		p.lowerObjectRestInForLoopInit(s.Init, &s.Body)
 
+		if s.IsAwait && p.options.unsupportedJSFeatures.Has(compat.ForAwait) {
+			return p.lowerForAwaitLoop(stmt.Loc, s, stmts)
+		}
+
 	case *js_ast.STry:
 		p.pushScopeForVisitPass(js_ast.ScopeBlock, stmt.Loc)
 		if p.fnOrArrowDataVisit.tryBodyCount == 0 {