Merge branch 'master' into feat/ext-attr/legacy-factory-function

Author: ExE-Boss

README.md

@@ -385,7 +385,7 @@ stringifier           DOMString operation(); // `toString()` is not needed.
 
 IDL indexed and named properties require multiple things on the implementation class to work properly.
 
-The first is the getters, (optional) setters, and (optional) deleters operations. Much like stringifiers, getters, setters, and deleters can either be standalone or aliased to a named operation (though not an attribute). If an operation is standalone, then the implementation class must implement following symbol-named methods. The `utils` object below refers to the default export from the generated utilities file `utils.js`.
+The first is the getters, (optional) setters, and (optional) deleters operations. Much like stringifiers, getters, setters, and deleters can either be standalone or aliased to a named operation (though not an attribute). If an operation is standalone, then the implementation class must implement the following symbol-named methods. The `utils` object below refers to the default export from the generated utilities file `utils.js`.
 
 - Getters: `utils.indexedGet`, `utils.namedGet`
 - Setters: `utils.indexedSetNew`, `utils.indexedSetExisting`, `utils.namedSetNew`, `utils.namedSetExisting`
@@ -395,6 +395,20 @@ The second is the interface's supported property indices/names. By default, the
 
 If the getter function always returns a constant value for unsupported properties, webidl2js also offers a non-standard extended attribute `[WebIDL2JSValueAsUnsupported]` (documented below) that would simply call the getter function to check if a property index/name is supported, so that `supportsPropertyIndex`/`supportsPropertyName` would not need to be implemented separately. However, when using the extended attribute, be very sure that the value specified in the attribute is returned *if and only if* the property is unsupported.
 
+### Iterables
+
+For synchronous value iterable declarations, there is no need to add implementation-class code: they will be automatically generated based on the indexed property getter and `length` property.
+
+For synchronous pair iterable declarations, the implementation class needs to implement the `[Symbol.iterator]()` property, returning an iterable of `[key, value]` pairs. These can be impls; the generated code will convert them into wrappers as necessary.
+
+### Async iterables
+
+[Asynchronous iterable declarations](https://heycam.github.io/webidl/#idl-async-iterable) require the implementation class to implement the following symbol-named methods, corresponding to algorithms from the Web IDL specification. The `utils` object below refers to the default export from the generated utilities file `utils.js`.
+
+- `utils.asyncIteratorNext`: corresponds to the [get the next iteration result](https://heycam.github.io/webidl/#dfn-get-the-next-iteration-result) algorithm, and receives a single argument containing an instance of the generated async iterator. For pair asynchronous iterables, the return value must be a `[key, value]` pair array, or `utils.asyncIteratorEOI` to signal the end of the iteration. For value asynchronous iterables, the return value must be the value, or `utils.asyncIteratorEOI` to signal the end of the iteration.
+- `utils.asyncIteratorInit`: corresponds to the [asynchronous iterator initialization steps](https://heycam.github.io/webidl/#asynchronous-iterator-initialization-steps), and receives two arguments: the instance of the generated async iterator, and an array containing the post-conversion arguments. This method is optional.
+- `utils.asyncIteratorReturn`: corresponds to the [asynchronous iterator return](https://heycam.github.io/webidl/#asynchronous-iterator-return) algorithm, and receives two arguments: the instance of the generated async iterator, and the argument passed to the `return()` method. This method is optional. Note that if you include it, you need to annote the async iterable declaration with [`[WebIDL2JSHasReturnSteps]`](#webidl2jshasreturnsteps).
+
 ### Other, non-exposed data and functionality
 
 Your implementation class can contain other properties and methods in support of the wrapped properties and methods that the wrapper class calls into. These can be used to factor out common algorithms, or store private state, or keep caches, or anything of the sort.
@@ -459,6 +473,7 @@ webidl2js is implementing an ever-growing subset of the Web IDL specification. S
   - Stringifiers
   - Named and indexed `getter`/`setter`/`deleter` declarations
   - `iterable<>` declarations
+  - `async iterable<>` declarations
   - Class strings (with the semantics of [heycam/webidl#357](https://github.com/heycam/webidl/pull/357))
 - Dictionary types
 - Enumeration types
@@ -512,7 +527,17 @@ Notable missing features include:
 
 ## Nonstandard extended attributes
 
-One non-standard extended attribute is baked in to webidl2js:
+A couple of non-standard extended attributes are baked in to webidl2js:
+
+### `[WebIDL2JSCallWithGlobal]`
+
+When the `[WebIDL2JSCallWithGlobal]` extended attribute is specified on static IDL operations, the generated interface code passes the [current global object](https://html.spec.whatwg.org/multipage/webappapis.html#current-global-object) as the first parameter to the implementation code. All other parameters follow `globalObject` and are unchanged. This could be used to implement factory functions that create objects in the current realm.
+
+### `[WebIDL2JSHasReturnSteps]`
+
+This extended attribute can be applied to async iterable declarations. It declares that the implementation class will implement the `[idlUtils.asyncIteratorReturn]()` method.
+
+This is necessary because we need to figure out at code-generation time whether to generate a `return()` method on the async iterator prototype. At that point, only the Web IDL is available, not the implementation class properties. So, we need a signal in the Web IDL itself.
 
 ### `[WebIDL2JSValueAsUnsupported=value]`
 

lib/constructs/async-iterable.js

@@ -0,0 +1,70 @@
+"use strict";
+
+const utils = require("../utils");
+const { generateAsyncIteratorArgConversions } = require("../parameters");
+
+class AsyncIterable {
+  constructor(ctx, I, idl) {
+    this.ctx = ctx;
+    this.interface = I;
+    this.idl = idl;
+    this.name = idl.type;
+  }
+
+  get isValue() {
+    return this.idl.idlType.length === 1;
+  }
+
+  get isPair() {
+    return this.idl.idlType.length === 2;
+  }
+
+  get isAsync() {
+    return true;
+  }
+
+  get hasReturnSteps() {
+    return Boolean(utils.getExtAttr(this.idl.extAttrs, "WebIDL2JSHasReturnSteps"));
+  }
+
+  generateFunction(key, kind, requires) {
+    const conv = generateAsyncIteratorArgConversions(
+      this.ctx, this.idl, this.interface, `Failed to execute '${key}' on '${this.interface.name}': `);
+    requires.merge(conv.requires);
+
+    this.interface.addMethod(this.interface.defaultWhence, key, [], `
+      if (!exports.is(this)) {
+        throw new TypeError("'${key}' called on an object that is not a valid instance of ${this.interface.name}.");
+      }
+
+      ${conv.body}
+
+      const asyncIterator = exports.createDefaultAsyncIterator(this, "${kind}");
+      if (this[implSymbol][utils.asyncIteratorInit]) {
+        this[implSymbol][utils.asyncIteratorInit](asyncIterator, args);
+      }
+      return asyncIterator;
+    `);
+  }
+
+  generate() {
+    const whence = this.interface.defaultWhence;
+    const requires = new utils.RequiresMap(this.ctx);
+
+    // https://heycam.github.io/webidl/#define-the-asynchronous-iteration-methods
+
+    if (this.isPair) {
+      this.generateFunction("keys", "key", requires);
+      this.generateFunction("values", "value", requires);
+      this.generateFunction("entries", "key+value", requires);
+      this.interface.addProperty(whence, Symbol.asyncIterator, `${this.interface.name}.prototype.entries`);
+    } else {
+      this.generateFunction("values", "value", requires);
+      this.interface.addProperty(whence, Symbol.asyncIterator, `${this.interface.name}.prototype.values`);
+    }
+
+    return { requires };
+  }
+}
+
+module.exports = AsyncIterable;

lib/constructs/attribute.js

@@ -29,7 +29,7 @@ class Attribute {
 
     let brandCheck = `
       if (!exports.is(esValue)) {
-        throw new TypeError("Illegal invocation");
+        throw new TypeError("'$KEYWORD$ ${this.idl.name}' called on an object that is not a valid instance of ${this.interface.name}.");
       }
     `;
     let getterBody = `return utils.tryWrapperForImpl(esValue[implSymbol]["${this.idl.name}"]);`;
@@ -78,11 +78,13 @@ class Attribute {
     addMethod(this.idl.name, [], `
       ${promiseHandlingBefore}
       const esValue = this !== null && this !== undefined ? this : globalObject;
-      ${brandCheck}
+      ${brandCheck.replace("$KEYWORD$", "get")}
       ${getterBody}
       ${promiseHandlingAfter}
     `, "get", { configurable });
 
+    brandCheck = brandCheck.replace("$KEYWORD$", "set");
+
     if (!this.idl.readonly) {
       if (async) {
         throw new Error(`Illegal promise-typed attribute "${this.idl.name}" in interface "${this.interface.idl.name}"`);
@@ -159,7 +161,7 @@ class Attribute {
       addMethod("toString", [], `
         const esValue = this;
         if (!exports.is(esValue)) {
-          throw new TypeError("Illegal invocation");
+          throw new TypeError("'toString' called on an object that is not a valid instance of ${this.interface.name}.");
         }
 
         ${getterBody}