Implement [LegacyFactoryFunction]

README.md

@@ -421,6 +421,17 @@ 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 `(thisValue, globalObject, [...legacyFactoryFunctionArgs], { newTarget, wrapper })`, which is used for:
+
+- Setting up initial state that will always be used, such as caches or default values
+- `thisValue` holds the value of a new uninitialized implementation instance, which may be ignored by returning a different object, similarly to how constructors with overridden return values are implemented.
+- 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.
+- `newTarget` holds a reference to the value of `new.target` that the legacy factor function was invoked with.
+- `wrapper` holds a reference to the uninitialized wrapper instance, just like in `privateData` with the standard impl constructor.
+
 ### 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.
@@ -484,6 +495,7 @@ webidl2js is implementing an ever-growing subset of the Web IDL specification. S
 - `[Clamp]`
 - `[EnforceRange]`
 - `[Exposed]`
+- `[LegacyFactoryFunction]`
 - `[LegacyLenientThis]`
 - `[LegacyLenientSetter]`
 - `[LegacyNoInterfaceObject]`
@@ -510,7 +522,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

@@ -46,6 +46,7 @@ class Interface {
     this.attributes = new Map();
     this.staticAttributes = new Map();
     this.constants = new Map();
+    this.legacyFactoryFunction = null;
 
     this.indexedGetter = null;
     this.indexedSetter = null;
@@ -391,6 +392,24 @@ class Interface {
         throw new Error(msg);
       }
     }
+
+    for (const attr of this.idl.extAttrs) {
+      if (attr.name === "LegacyFactoryFunction") {
+        if (!attr.rhs || attr.rhs.type !== "identifier" || !attr.arguments) {
+          throw new Error(`[LegacyFactoryFunction] must take a named argument list`);
+        }
+
+        if (this.legacyFactoryFunction) {
+          // This is currently valid, but not used anywhere, and there are plans to disallow it:
+          // https://github.com/heycam/webidl/issues/878
+          throw new Error(
+            `Multiple [LegacyFactoryFunction] definitions are not supported on ${this.name}`
+          );
+        }
+
+        this.legacyFactoryFunction = attr;
+      }
+    }
   }
 
   get supportsIndexedProperties() {
@@ -1644,6 +1663,94 @@ class Interface {
     `;
   }
 
+  generateLegacyFactoryFunction() {
+    const { legacyFactoryFunction } = this;
+    if (!legacyFactoryFunction) {
+      return;
+    }
+
+    const name = legacyFactoryFunction.rhs.value;
+    if (!name) {
+      throw new Error(`Internal error: The legacy factory function does not have a name (in interface ${this.name})`);
+    }
+
+    const overloads = Overloads.getEffectiveOverloads("legacy factory function", name, 0, this);
+    let minOp = overloads[0];
+    for (let i = 1; i < overloads.length; ++i) {
+      if (overloads[i].nameList.length < minOp.nameList.length) {
+        minOp = overloads[i];
+      }
+    }
+
+    const args = minOp.nameList;
+    const conversions = Parameters.generateOverloadConversions(
+      this.ctx,
+      "legacy factory function",
+      name,
+      this,
+      `Failed to construct '${name}': `
+    );
+    this.requires.merge(conversions.requires);
+
+    const argsParam = conversions.hasArgs ? "args" : "[]";
+
+    this.str += `
+      function ${name}(${utils.formatArgs(args)}) {
+        if (new.target === undefined) {
+          throw new TypeError("Class constructor ${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:
+    this.str += `
+        ${this.isLegacyPlatformObj ? "let" : "const"} wrapper = makeWrapper(globalObject, newTarget);
+        exports._internalSetup(wrapper, globalObject);
+
+        const thisValue = Object.create(Impl.implementation.prototype);
+        const implResult = Impl.legacyFactoryFunction(thisValue, globalObject, ${argsParam});
+
+        Object.defineProperty(wrapper, implSymbol, {
+          value: utils.isObject(implResult) ? implResult : thisValue,
+          configurable: true
+        });
+
+    `;
+
+    if (this.isLegacyPlatformObj) {
+      this.str += `
+        wrapper = ${this.needsPerGlobalProxyHandler ?
+          "makeProxy(wrapper, globalObject)" :
+          "new Proxy(wrapper, proxyHandler)"};
+      `;
+    }
+
+    this.str += `
+
+        wrapper[implSymbol][utils.wrapperSymbol] = wrapper;
+        if (Impl.init) {
+          Impl.init(wrapper[implSymbol]);
+        }
+        return wrapper;
+      }
+
+      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;
 
@@ -1712,6 +1819,8 @@ class Interface {
       }
     }
 
+    this.generateLegacyFactoryFunction();
+
     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.legacyFactoryFunction];
   }
   throw new RangeError(`${type}s are not yet supported`);
 }