Add async iterable flavors

baselines/audioworklet.asynciterable.generated.d.ts

@@ -0,0 +1,8 @@
+/////////////////////////////
+/// AudioWorklet Async Iterable APIs
+/////////////////////////////
+
+interface ReadableStream<R = any> {
+    [Symbol.asyncIterator](options?: ReadableStreamIteratorOptions): AsyncIterableIterator<R>;
+    values(options?: ReadableStreamIteratorOptions): AsyncIterableIterator<R>;
+}

baselines/audioworklet.generated.d.ts

@@ -49,6 +49,17 @@ interface ReadableStreamDefaultReadValueResult<T> {
     value: T;
 }
 
+interface ReadableStreamIteratorOptions {
+    /**
+     * Asynchronously iterates over the chunks in the stream's internal queue.
+     *
+     * Asynchronously iterating over the stream will lock it, preventing any other consumer from acquiring a reader. The lock will be released if the async iterator's return() method is called, e.g. by breaking out of the loop.
+     *
+     * By default, calling the async iterator's return() method will also cancel the stream. To prevent this, use the stream's values() method, passing true for the preventCancel option.
+     */
+    preventCancel?: boolean;
+}
+
 interface ReadableWritablePair<R = any, W = any> {
     readable: ReadableStream<R>;
     /**

baselines/dom.asynciterable.generated.d.ts

@@ -0,0 +1,8 @@
+/////////////////////////////
+/// Window Async Iterable APIs
+/////////////////////////////
+
+interface ReadableStream<R = any> {
+    [Symbol.asyncIterator](options?: ReadableStreamIteratorOptions): AsyncIterableIterator<R>;
+    values(options?: ReadableStreamIteratorOptions): AsyncIterableIterator<R>;
+}

baselines/dom.generated.d.ts

@@ -1421,6 +1421,17 @@ interface ReadableStreamDefaultReadValueResult<T> {
     value: T;
 }
 
+interface ReadableStreamIteratorOptions {
+    /**
+     * Asynchronously iterates over the chunks in the stream's internal queue.
+     *
+     * Asynchronously iterating over the stream will lock it, preventing any other consumer from acquiring a reader. The lock will be released if the async iterator's return() method is called, e.g. by breaking out of the loop.
+     *
+     * By default, calling the async iterator's return() method will also cancel the stream. To prevent this, use the stream's values() method, passing true for the preventCancel option.
+     */
+    preventCancel?: boolean;
+}
+
 interface ReadableWritablePair<R = any, W = any> {
     readable: ReadableStream<R>;
     /**

baselines/serviceworker.asynciterable.generated.d.ts

@@ -0,0 +1,8 @@
+/////////////////////////////
+/// ServiceWorker Async Iterable APIs
+/////////////////////////////
+
+interface ReadableStream<R = any> {
+    [Symbol.asyncIterator](options?: ReadableStreamIteratorOptions): AsyncIterableIterator<R>;
+    values(options?: ReadableStreamIteratorOptions): AsyncIterableIterator<R>;
+}

baselines/serviceworker.generated.d.ts

@@ -435,6 +435,17 @@ interface ReadableStreamDefaultReadValueResult<T> {
     value: T;
 }
 
+interface ReadableStreamIteratorOptions {
+    /**
+     * Asynchronously iterates over the chunks in the stream's internal queue.
+     *
+     * Asynchronously iterating over the stream will lock it, preventing any other consumer from acquiring a reader. The lock will be released if the async iterator's return() method is called, e.g. by breaking out of the loop.
+     *
+     * By default, calling the async iterator's return() method will also cancel the stream. To prevent this, use the stream's values() method, passing true for the preventCancel option.
+     */
+    preventCancel?: boolean;
+}
+
 interface ReadableWritablePair<R = any, W = any> {
     readable: ReadableStream<R>;
     /**

baselines/sharedworker.asynciterable.generated.d.ts

@@ -0,0 +1,8 @@
+/////////////////////////////
+/// SharedWorker Async Iterable APIs
+/////////////////////////////
+
+interface ReadableStream<R = any> {
+    [Symbol.asyncIterator](options?: ReadableStreamIteratorOptions): AsyncIterableIterator<R>;
+    values(options?: ReadableStreamIteratorOptions): AsyncIterableIterator<R>;
+}

baselines/sharedworker.generated.d.ts

@@ -401,6 +401,17 @@ interface ReadableStreamDefaultReadValueResult<T> {
     value: T;
 }
 
+interface ReadableStreamIteratorOptions {
+    /**
+     * Asynchronously iterates over the chunks in the stream's internal queue.
+     *
+     * Asynchronously iterating over the stream will lock it, preventing any other consumer from acquiring a reader. The lock will be released if the async iterator's return() method is called, e.g. by breaking out of the loop.
+     *
+     * By default, calling the async iterator's return() method will also cancel the stream. To prevent this, use the stream's values() method, passing true for the preventCancel option.
+     */
+    preventCancel?: boolean;
+}
+
 interface ReadableWritablePair<R = any, W = any> {
     readable: ReadableStream<R>;
     /**

baselines/webworker.asynciterable.generated.d.ts

@@ -0,0 +1,8 @@
+/////////////////////////////
+/// Worker Async Iterable APIs
+/////////////////////////////
+
+interface ReadableStream<R = any> {
+    [Symbol.asyncIterator](options?: ReadableStreamIteratorOptions): AsyncIterableIterator<R>;
+    values(options?: ReadableStreamIteratorOptions): AsyncIterableIterator<R>;
+}

baselines/webworker.generated.d.ts

@@ -435,6 +435,17 @@ interface ReadableStreamDefaultReadValueResult<T> {
     value: T;
 }
 
+interface ReadableStreamIteratorOptions {
+    /**
+     * Asynchronously iterates over the chunks in the stream's internal queue.
+     *
+     * Asynchronously iterating over the stream will lock it, preventing any other consumer from acquiring a reader. The lock will be released if the async iterator's return() method is called, e.g. by breaking out of the loop.
+     *
+     * By default, calling the async iterator's return() method will also cancel the stream. To prevent this, use the stream's values() method, passing true for the preventCancel option.
+     */
+    preventCancel?: boolean;
+}
+
 interface ReadableWritablePair<R = any, W = any> {
     readable: ReadableStream<R>;
     /**

inputfiles/overridingTypes.jsonc

@@ -2332,6 +2332,13 @@
                             }
                         }
                     }
+                },
+                "iterator": {
+                    "type": {
+                        "0": {
+                            "overrideType": "R"
+                        }
+                    }
                 }
             },
             "ReadableStreamDefaultReader": {

src/build.ts

@@ -42,17 +42,26 @@ async function emitFlavor(
   const exposed = getExposedTypes(webidl, options.global, forceKnownTypes);
   mergeNamesakes(exposed);
 
-  const result = emitWebIdl(exposed, options.global[0], false);
+  const result = emitWebIdl(exposed, options.global[0], "");
   await fs.writeFile(
     new URL(`${options.name}.generated.d.ts`, options.outputFolder),
     result
   );
 
-  const iterators = emitWebIdl(exposed, options.global[0], true);
+  const iterators = emitWebIdl(exposed, options.global[0], "sync");
   await fs.writeFile(
     new URL(`${options.name}.iterable.generated.d.ts`, options.outputFolder),
     iterators
   );
+
+  const asyncIterators = emitWebIdl(exposed, options.global[0], "async");
+  await fs.writeFile(
+    new URL(
+      `${options.name}.asynciterable.generated.d.ts`,
+      options.outputFolder
+    ),
+    asyncIterators
+  );
 }
 
 async function emitDom() {

src/build/emitter.ts

@@ -135,7 +135,7 @@ function isEventHandler(p: Browser.Property) {
 export function emitWebIdl(
   webidl: Browser.WebIdl,
   global: string,
-  iterator: boolean
+  iterator: "" | "sync" | "async"
 ): string {
   // Global print target
   const printer = createTextWriter("\n");
@@ -225,7 +225,14 @@ export function emitWebIdl(
     getParentsWithConstant
   );
 
-  return iterator ? emitES6DomIterators() : emit();
+  switch (iterator) {
+    case "sync":
+      return emitES6DomIterators();
+    case "async":
+      return emitES2018DomAsyncIterators();
+    default:
+      return emit();
+  }
 
   function getTagNameToElementNameMap() {
     const htmlResult: Record<string, string> = {};
@@ -400,7 +407,7 @@ export function emitWebIdl(
   }
 
   function convertDomTypeToTsTypeSimple(objDomType: string): string {
-    if (objDomType === "sequence" && iterator) {
+    if (objDomType === "sequence" && iterator !== "") {
       return "Iterable";
     }
     if (baseTypeConversionMap.has(objDomType)) {
@@ -996,7 +1003,7 @@ export function emitWebIdl(
 
   // Emit forEach for iterators
   function emitIteratorForEach(i: Browser.Interface) {
-    if (!i.iterator) {
+    if (!i.iterator || i.iterator.async) {
       return;
     }
     const subtype = i.iterator.type.map(convertDomTypeToTsType);
@@ -1498,6 +1505,13 @@ export function emitWebIdl(
     return printer.getResult();
   }
 
+  function stringifySingleOrTupleTypes(types: string[]) {
+    if (types.length === 1) {
+      return types[0];
+    }
+    return `[${types.join(", ")}]`;
+  }
+
   function emitIterator(i: Browser.Interface) {
     // https://heycam.github.io/webidl/#dfn-indexed-property-getter
     const isIndexedPropertyGetter = (m: Browser.AnonymousMethod) =>
@@ -1518,7 +1532,7 @@ export function emitWebIdl(
     }
 
     function getIteratorSubtypes() {
-      if (i.iterator) {
+      if (i.iterator && !i.iterator.async) {
         if (i.iterator.type.length === 1) {
           return [convertDomTypeToTsType(i.iterator.type[0])];
         }
@@ -1536,13 +1550,6 @@ export function emitWebIdl(
       }
     }
 
-    function stringifySingleOrTupleTypes(types: string[]) {
-      if (types.length === 1) {
-        return types[0];
-      }
-      return `[${types.join(", ")}]`;
-    }
-
     function emitIterableDeclarationMethods(
       i: Browser.Interface,
       subtypes: string[]
@@ -1682,6 +1689,83 @@ export function emitWebIdl(
     }
   }
 
+  function emitAsyncIterator(i: Browser.Interface) {
+    function getAsyncIteratorSubtypes() {
+      if (i.iterator && i.iterator.kind === "iterable" && i.iterator.async) {
+        if (i.iterator.type.length === 1) {
+          return [convertDomTypeToTsType(i.iterator.type[0])];
+        }
+        return i.iterator.type.map(convertDomTypeToTsType);
+      }
+    }
+
+    function emitAsyncIterableDeclarationMethods(
+      i: Browser.Interface,
+      subtypes: string[],
+      paramsString: string
+    ) {
+      let methods;
+      if (subtypes.length === 1) {
+        // https://heycam.github.io/webidl/#value-asynchronously-iterable-declaration
+        const [valueType] = subtypes;
+        methods = [
+          {
+            name: "values",
+            definition: `AsyncIterableIterator<${valueType}>`,
+          },
+        ];
+      } else {
+        // https://heycam.github.io/webidl/#pair-asynchronously-iterable-declaration
+        const [keyType, valueType] = subtypes;
+        methods = [
+          {
+            name: "entries",
+            definition: `AsyncIterableIterator<[${keyType}, ${valueType}]>`,
+          },
+          {
+            name: "keys",
+            definition: `AsyncIterableIterator<${keyType}>`,
+          },
+          {
+            name: "values",
+            definition: `AsyncIterableIterator<${valueType}>`,
+          },
+        ];
+      }
+
+      const comments = i.iterator!.comments?.comment;
+
+      methods.forEach((m) => {
+        emitComments({ comment: comments?.[m.name] }, printer.printLine);
+        printer.printLine(`${m.name}(${paramsString}): ${m.definition};`);
+      });
+    }
+
+    const subtypes = getAsyncIteratorSubtypes();
+    if (subtypes) {
+      const name = getNameWithTypeParameter(
+        i.typeParameters,
+        extendConflictsBaseTypes[i.name] ? `${i.name}Base` : i.name
+      );
+      const paramsString = i.iterator!.param
+        ? paramsToString(i.iterator!.param)
+        : "";
+      printer.printLine("");
+      printer.printLine(`interface ${name} {`);
+      printer.increaseIndent();
+
+      printer.printLine(
+        `[Symbol.asyncIterator](${paramsString}): AsyncIterableIterator<${stringifySingleOrTupleTypes(
+          subtypes
+        )}>;`
+      );
+      emitAsyncIterableDeclarationMethods(i, subtypes, paramsString);
+
+      printer.decreaseIndent();
+      printer.printLine("}");
+    }
+  }
+
   function emitES6DomIterators() {
     printer.reset();
     printer.printLine("/////////////////////////////");
@@ -1692,4 +1776,15 @@ export function emitWebIdl(
 
     return printer.getResult();
   }
+
+  function emitES2018DomAsyncIterators() {
+    printer.reset();
+    printer.printLine("/////////////////////////////");
+    printer.printLine(`/// ${global} Async Iterable APIs`);
+    printer.printLine("/////////////////////////////");
+
+    allInterfaces.sort(compareName).forEach(emitAsyncIterator);
+
+    return printer.getResult();
+  }
 }

src/build/types.d.ts

@@ -196,7 +196,9 @@ export interface Interface {
 export interface Iterator {
   kind: "iterable" | "setlike" | "maplike";
   readonly: boolean;
+  async: boolean;
   type: Typed[];
+  param?: Param[];
   comments?: {
     comment: Record<string, string>;
   };

src/build/widlprocess.ts

@@ -199,13 +199,15 @@ function convertInterfaceCommon(
         addComments(method[member.name], commentMap, i.name, member.name);
       }
     } else if (
-      (member.type === "iterable" && !member.async) ||
+      member.type === "iterable" ||
       member.type === "maplike" ||
       member.type === "setlike"
     ) {
       result.iterator = {
         kind: member.type,
         readonly: member.readonly,
+        async: member.async,
+        param: member.arguments.map(convertArgument),
         type: member.idlType.map(convertIdlType),
       };
     }