Implement [LegacyFactoryFunction]

Author: ExE-Boss

README.md

@@ -282,11 +282,11 @@ Creates a new instance of the wrapper class and corresponding implementation cla
 
 This is useful inside implementation class files, where it is easiest to only deal with impls, not wrappers.
 
-#### `new(globalObject)`
+#### `new(globalObject, newTarget)`
 
 Creates a new instance of the wrapper class and corresponding implementation class, but without invoking the implementation class constructor logic. Then returns the implementation class.
 
-This corresponds to the [Web IDL "new" algorithm](https://heycam.github.io/webidl/#new), and is useful when implementing specifications that initialize objects in different ways than their constructors do.
+This corresponds to the [WebIDL "create a new object implementing the interface"](https://heycam.github.io/webidl/#new) and ["internally create a new object implementing the interface"](https://heycam.github.io/webidl/#internally-create-a-new-object-implementing-the-interface) algorithms, and is useful when implementing specifications that initialize objects in different ways than their constructors do.
 
 #### `setup(obj, globalObject, constructorArgs, privateData)`
 
@@ -407,6 +407,24 @@ It is often useful for implementation classes to inherit from each other, if the
 
 However, it is not required! The wrapper classes will have a correct inheritance chain, regardless of the implementation class inheritance chain. Just make sure that, either via inheritance or manual implementation, you implement all of the expected operations and attributes.
 
+### The `[LegacyFactoryFunction]` extended attribute
+
+For interfaces which have the `[LegacyFactoryFunction]` extended attribute, the implementation class file must contain the `legacyFactoryFunction` export, with the signature `(globalObject, legacyFactoryFunctionArgs, legacyFactoryFunctionName)`, which is used for:
+
+- Setting up initial state that will always be used, such as caches or default values
+- Keep a reference to the relevant `globalObject` for later consumption.
+- Processing constructor arguments `legacyFactoryFunctionArgs` passed to the legacy factory function constructor, if the legacy factory function takes arguments.
+- Switching on the `legacyFactoryFunctionName`, if the interface defines multiple legacy factory functions, eg.:
+
+  ```webidl
+  [LegacyFactoryFunction=OverloadedLegacyFactoryFunction(DOMString arg1),
+   LegacyFactoryFunction=OverloadedLegacyFactoryFunction(long arg1, long arg2),
+   LegacyFactoryFunction=SimpleLegacyFactoryFunction(optional DOMString src)]
+  interface SomeInterface {};
+  ```
+
+The `legacyFactoryFunction` export is called with a `this` value of a new uninitialized implementation instance, which may be ignored by returning a different object, similarly to how constructors with overridden return types are implemented.
+
 ### The init export
 
 In addition to the `implementation` export, for interfaces, your implementation class file can contain an `init` export. This would be a function taking as an argument an instance of the implementation class, and is called when any wrapper/implementation pairs are constructed (such as by the exports of the [generated wrapper module](https://github.com/jsdom/webidl2js#for-interfaces)). In particular, it is called even if they are constructed by [`new()`](newglobalobject), which does not invoke the implementation class constructor.
@@ -469,6 +487,7 @@ webidl2js is implementing an ever-growing subset of the Web IDL specification. S
 - `[Clamp]`
 - `[EnforceRange]`
 - `[Exposed]`
+- `[LegacyFactoryFunction]`
 - `[LegacyLenientThis]`
 - `[LegacyLenientSetter]`
 - `[LegacyNoInterfaceObject]`
@@ -494,7 +513,6 @@ Notable missing features include:
 - `[AllowShared]`
 - `[Default]` (for `toJSON()` operations)
 - `[Global]`'s various consequences, including the named properties object and `[[SetPrototypeOf]]`
-- `[LegacyFactoryFunction]`
 - `[LegacyNamespace]`
 - `[LegacyTreatNonObjectAsNull]`
 - `[SecureContext]`

lib/constructs/interface.js

@@ -33,6 +33,65 @@ const defaultClassMethodDescriptor = {
   writable: true
 };
 
+class LegacyFactoryFunction {
+  constructor(ctx, I, idl) {
+    this.ctx = ctx;
+    this.interface = I;
+    this.idls = [idl];
+    this.name = idl.rhs.value;
+  }
+
+  generate() {
+    const requires = new utils.RequiresMap(this.ctx);
+
+    let str = "";
+
+    if (!this.name) {
+      throw new Error(`Internal error: this legacy factory function does not have a name (in interface ${this.interface.name})`);
+    }
+
+    const overloads = Overloads.getEffectiveOverloads("legacy factory function", this.name, 0, this.interface);
+    let minOp = overloads[0];
+    for (let i = 1; i < overloads.length; ++i) {
+      if (overloads[i].nameList.length < minOp.nameList.length) {
+        minOp = overloads[i];
+      }
+    }
+
+    const argNames = minOp.nameList;
+
+    const conversions = Parameters.generateOverloadConversions(
+      this.ctx, "legacy factory function", this.name, this.interface, `Failed to construct '${this.name}': `);
+    requires.merge(conversions.requires);
+
+    const setupArgs = [
+      "globalObject",
+      conversions.hasArgs ? "args" : "[]",
+      `"${this.name}"`
+    ];
+
+    str += `
+      if (new.target === undefined) {
+        throw new TypeError("Class constructor ${this.name} cannot be invoked without 'new'");
+      }
+
+      ${conversions.body}
+    `;
+
+    // This implements the WebIDL legacy factory function behavior, as well as support for overridding
+    // the return type, which is used by HTML's element legacy factory functions:
+    str += `
+      const thisArgument = exports.new(globalObject, new.target);
+      const result = Impl.legacyFactoryFunction.call(thisArgument, ${formatArgs(setupArgs)});
+      return utils.tryWrapperForImpl(utils.isObject(result) ? result : thisArgument);
+    `;
+
+    this.interface.addLegacyFactoryFunction(this.name, argNames, str);
+
+    return { requires };
+  }
+}
+
 class Interface {
   constructor(ctx, idl, opts) {
     this.ctx = ctx;
@@ -54,6 +113,7 @@ class Interface {
     this.attributes = new Map();
     this.staticAttributes = new Map();
     this.constants = new Map();
+    this.legacyFactoryFunctions = new Map();
 
     this.indexedGetter = null;
     this.indexedSetter = null;
@@ -70,6 +130,7 @@ class Interface {
     this._outputStaticMethods = new Map();
     this._outputProperties = new Map();
     this._outputStaticProperties = new Map();
+    this._outputLegacyFactoryFunctions = new Map();
 
     const global = utils.getExtAttr(this.idl.extAttrs, "Global");
     this.isGlobal = Boolean(global);
@@ -181,6 +242,10 @@ class Interface {
     this._outputStaticMethods.set(propName, { type, args, body, descriptor });
   }
 
+  addLegacyFactoryFunction(name, args, body) {
+    this._outputLegacyFactoryFunctions.set(name, { args, body });
+  }
+
   // whence is either "instance" or "prototype"
   addProperty(whence, propName, str, {
     configurable = true,
@@ -394,6 +459,22 @@ class Interface {
         throw new Error(msg);
       }
     }
+
+    for (const attr of this.idl.extAttrs) {
+      if (attr.name === "LegacyFactoryFunction") {
+        if (attr.rhs.type !== "identifier" || !attr.arguments) {
+          throw new Error(`[LegacyFactoryFunction] must take a named argument list`);
+        }
+
+        const name = attr.rhs.value;
+
+        if (!this.legacyFactoryFunctions.has(name)) {
+          this.legacyFactoryFunctions.set(name, new LegacyFactoryFunction(this.ctx, this, attr));
+        } else {
+          this.legacyFactoryFunctions.get(name).idls.push(attr);
+        }
+      }
+    }
   }
 
   get supportsIndexedProperties() {
@@ -1125,17 +1206,25 @@ class Interface {
 
   generateIface() {
     this.str += `
-      function makeWrapper(globalObject) {
+      function makeWrapper(globalObject, newTarget) {
         if (globalObject[ctorRegistrySymbol] === undefined) {
           throw new Error('Internal error: invalid global object');
         }
 
-        const ctor = globalObject[ctorRegistrySymbol]["${this.name}"];
-        if (ctor === undefined) {
-          throw new Error('Internal error: constructor ${this.name} is not installed on the passed global object');
+        let prototype;
+        if (newTarget !== undefined) {
+          ({ prototype } = newTarget);
+        }
+
+        if (!utils.isObject(prototype)) {
+          const ctor = globalObject[ctorRegistrySymbol]["${this.name}"];
+          if (ctor === undefined) {
+            throw new Error('Internal error: constructor ${this.name} is not installed on the passed global object');
+          }
+          ({ prototype } = ctor);
         }
 
-        return Object.create(ctor.prototype);
+        return Object.create(prototype);
       }
     `;
 
@@ -1203,8 +1292,8 @@ class Interface {
         return wrapper;
       };
 
-      exports.new = globalObject => {
-        ${this.isLegacyPlatformObj ? "let" : "const"} wrapper = makeWrapper(globalObject);
+      exports.new = (globalObject, newTarget) => {
+        ${this.isLegacyPlatformObj ? "let" : "const"} wrapper = makeWrapper(globalObject, newTarget);
 
         exports._internalSetup(wrapper, globalObject);
         Object.defineProperty(wrapper, implSymbol, {
@@ -1314,6 +1403,11 @@ class Interface {
       const data = member.generate();
       this.requires.merge(data.requires);
     }
+
+    for (const legacyFactoryFunction of this.legacyFactoryFunctions.values()) {
+      const data = legacyFactoryFunction.generate();
+      this.requires.merge(data.requires);
+    }
   }
 
   generateOffInstanceMethods() {
@@ -1478,6 +1572,31 @@ class Interface {
     }
   }
 
+  generateLegacyFactoryFunctions() {
+    for (const [name, { args, body }] of this._outputLegacyFactoryFunctions) {
+      this.str += `
+        {
+          function ${name}(${formatArgs(args)}) {
+            ${body}
+          }
+
+          Object.defineProperty(${name}, "prototype", {
+            configurable: false,
+            enumerable: false,
+            writable: false,
+            value: ${this.name}.prototype
+          })
+
+          Object.defineProperty(globalObject, "${name}", {
+            configurable: true,
+            writable: true,
+            value: ${name}
+          });
+        }
+      `;
+    }
+  }
+
   generateInstall() {
     const { idl, name } = this;
 
@@ -1543,6 +1662,8 @@ class Interface {
       }
     }
 
+    this.generateLegacyFactoryFunctions();
+
     this.str += `
       };
     `;

lib/overloads.js

@@ -11,6 +11,8 @@ function getOperations(type, A, I) {
     case "constructor": {
       return I.constructorOperations;
     }
+    case "legacy factory function":
+      return I.legacyFactoryFunctions.get(A).idls;
   }
   throw new RangeError(`${type}s are not yet supported`);
 }