feat: implement new async_iterable syntax (#819)

* feat: implement new async_iterable syntax

* Update README.md

Author: saschanaz

README.md

@@ -745,7 +745,7 @@ For `"Infinity"`:
 
 * `negative`: Boolean indicating whether this is negative Infinity or not.
 
-### `iterable<>`, `async iterable<>`, `maplike<>`, and `setlike<>` declarations
+### `iterable<>`, `async_iterable<>`, `maplike<>`, and `setlike<>` declarations
 
 These appear as members of interfaces that look like this:
 
@@ -755,7 +755,7 @@ These appear as members of interfaces that look like this:
   "idlType": /* One or two types */ ,
   "readonly": false, // only for maplike and setlike
   "async": false, // iterable can be async
-  "arguments": [], // only for async iterable
+  "arguments": [], // only for async_iterable
   "extAttrs": [],
   "parent": { ... }
 }
@@ -766,8 +766,8 @@ The fields are as follows:
 * `type`: Always one of "iterable", "maplike" or "setlike".
 * `idlType`: An array with one or more [IDL Types](#idl-type) representing the declared type arguments.
 * `readonly`: `true` if the maplike or setlike is declared as read only.
-* `async`: `true` if the type is async iterable.
-* `arguments`: An array of arguments if exists, empty otherwise. Currently only `async iterable` supports the syntax.
+* `async`: `true` if the type is `async iterable`. Note that it's false for the new `async_iterable`.
+* `arguments`: An array of arguments if exists, empty otherwise. Currently only `async_iterable` supports the syntax.
 * `extAttrs`: An array of [extended attributes](#extended-attributes).
 * `parent`: The container of this type as an Object.
 

lib/productions/iterable.js

@@ -1,3 +1,4 @@
+import { validationError } from "../error.js";
 import { Base } from "./base.js";
 import {
   type_with_extended_attributes,
@@ -23,16 +24,18 @@ export class IterableLike extends Base {
       ? tokeniser.consume("maplike", "setlike")
       : tokens.async
         ? tokeniser.consume("iterable")
-        : tokeniser.consume("iterable", "maplike", "setlike");
+        : tokeniser.consume("iterable", "async_iterable", "maplike", "setlike");
     if (!tokens.base) {
       tokeniser.unconsume(start_position);
       return;
     }
 
     const { type } = ret;
     const secondTypeRequired = type === "maplike";
-    const secondTypeAllowed = secondTypeRequired || type === "iterable";
-    const argumentAllowed = ret.async && type === "iterable";
+    const secondTypeAllowed =
+      secondTypeRequired || type === "iterable" || type === "async_iterable";
+    const argumentAllowed =
+      type === "async_iterable" || (ret.async && type === "iterable");
 
     tokens.open =
       tokeniser.consume("<") ||
@@ -86,6 +89,18 @@ export class IterableLike extends Base {
   }
 
   *validate(defs) {
+    if (this.async && this.type === "iterable") {
+      const message = "`async iterable` is now changed to `async_iterable`.";
+      yield validationError(
+        this.tokens.async,
+        this,
+        "obsolete-async-iterable-syntax",
+        message,
+        {
+          autofix: autofixAsyncIterableSyntax(this),
+        },
+      );
+    }
     for (const type of this.idlType) {
       yield* type.validate(defs);
     }
@@ -114,3 +129,18 @@ export class IterableLike extends Base {
     );
   }
 }
+
+/**
+ * @param {IterableLike} iterableLike
+ */
+function autofixAsyncIterableSyntax(iterableLike) {
+  return () => {
+    const async = iterableLike.tokens.async;
+    iterableLike.tokens.base = {
+      ...async,
+      type: "async_iterable",
+      value: "async_iterable",
+    };
+    delete iterableLike.tokens.async;
+  };
+}

lib/tokeniser.js

@@ -72,6 +72,7 @@ const nonRegexTerminals = [
   "NaN",
   "ObservableArray",
   "Promise",
+  "async_iterable",
   "bigint",
   "boolean",
   "byte",

test/autofix.js

@@ -360,4 +360,20 @@ describe("Writer template functions", () => {
     `;
     expect(autofix(input)).toBe(output);
   });
+
+  it("should replace `async iterable` to `async_iterable`", () => {
+    const input = `
+      [Exposed=Window]
+      interface AsyncIterable {
+        async iterable<long, short>;
+      };
+    `;
+    const output = `
+      [Exposed=Window]
+      interface AsyncIterable {
+        async_iterable<long, short>;
+      };
+    `;
+    expect(autofix(input)).toBe(output);
+  });
 });

test/invalid/baseline/argument-dict-default.txt

@@ -10,6 +10,6 @@
 (dict-arg-default) Validation error at line 18 in argument-dict-default.webidl, inside `interface X -> operation z -> argument union`:
   undefined z(optional Union union);
                              ^ Optional dictionary arguments must have a default value of `{}`.
-(dict-arg-default) Validation error at line 22 in argument-dict-default.webidl, inside `interface X -> iterable -> argument union`:
+(dict-arg-default) Validation error at line 22 in argument-dict-default.webidl, inside `interface X -> async_iterable -> argument union`:
 DOMString>(optional Union union);
                           ^ Optional dictionary arguments must have a default value of `{}`.

test/invalid/baseline/argument-dict-nullable.txt

@@ -19,6 +19,6 @@ boolean or Dict)? union = {})
 (no-nullable-dict-arg) Validation error at line 17 in argument-dict-nullable.webidl, inside `interface X -> operation r -> argument req`:
   undefined r(Required? req);
                         ^ Dictionary arguments cannot be nullable.
-(no-nullable-dict-arg) Validation error at line 19 in argument-dict-nullable.webidl, inside `interface X -> iterable -> argument dict`:
+(no-nullable-dict-arg) Validation error at line 19 in argument-dict-nullable.webidl, inside `interface X -> async_iterable -> argument dict`:
 >(optional Dict? dict);
                  ^ Dictionary arguments cannot be nullable.

test/invalid/baseline/argument-dict-optional.txt

@@ -13,6 +13,6 @@
 (dict-arg-optional) Validation error at line 38 in argument-dict-optional.webidl, inside `interface mixin Container -> operation op8 -> argument lastRequired`:
   undefined op8(Optional lastRequired, optional DOMString yay
                          ^ Dictionary argument must be optional if it has no required fields
-(dict-arg-optional) Validation error at line 44 in argument-dict-optional.webidl, inside `interface ContainerInterface -> iterable -> argument shouldBeOptional`:
+(dict-arg-optional) Validation error at line 44 in argument-dict-optional.webidl, inside `interface ContainerInterface -> async_iterable -> argument shouldBeOptional`:
 <DOMString>(Optional shouldBeOptional);
                      ^ Dictionary argument must be optional if it has no required fields

test/invalid/baseline/async-iterable-readonly.txt

@@ -1,3 +1,3 @@
 Syntax error at line 3 in async-iterable-readonly.webidl, since `interface AsyncIterable`:
-  readonly async iterable<long
+  readonly async_iterable<long,
   ^ Missing return type

test/invalid/baseline/async-space-iterable.txt

@@ -0,0 +1,3 @@
+(obsolete-async-iterable-syntax) Validation error at line 3 in async-space-iterable.webidl:
+  async iterable<long,
+  ^ `async iterable` is now changed to `async_iterable`.

test/invalid/idl/argument-dict-default.webidl

@@ -19,5 +19,5 @@ interface X {
   undefined z2(optional Union union = {});
   undefined r(Required req);
 
-  async iterable<DOMString>(optional Union union);
+  async_iterable<DOMString>(optional Union union);
 };