BREAKING CHANGE: Move types in supplement.d.ts to class properties

lib/productions/argument.js

@@ -14,7 +14,14 @@ import {
   dictionaryIncludesRequiredField,
 } from "../validators/helpers.js";
 
+/** @import {Type} from "./type.js" */
+
 export class Argument extends Base {
+  /** @type {Type} */
+  idlType;
+  /** @type {Default | null} */
+  default;
+
   /**
    * @param {import("../tokeniser.js").Tokeniser} tokeniser
    */

lib/productions/array-base.js

@@ -1,4 +1,12 @@
+/** @import {Token} from "../tokeniser.js" */
+
 export class ArrayBase extends Array {
+  /** @type {Record<string, Token | undefined>} */
+  tokens;
+  /** @type {Token[]} */
+  source;
+  parent;
+
   constructor({ source, tokens }) {
     super();
     Object.defineProperties(this, {

lib/productions/attribute.js

@@ -10,7 +10,12 @@ import {
   autoParenter,
 } from "./helpers.js";
 
+/** @import {Type} from "./type.js" */
+
 export class Attribute extends Base {
+  /** @type {Type} */
+  idlType;
+
   /**
    * @param {import("../tokeniser.js").Tokeniser} tokeniser
    * @param {object} [options]

lib/productions/base.js

@@ -1,26 +1,55 @@
+/** @import {ExtendedAttributes} from "./extended-attributes.js" */
+/** @import {Token} from "../tokeniser.js" */
+/** @import {Definitions} from "../validator.js" */
+/** @import {Writer} from "../writer.js" */
+
 export class Base {
+  /** @type {Record<string, Token | undefined>} */
+  tokens;
+  /** @type {Token[]} */
+  source;
+  /** @type {ExtendedAttributes | undefined} */
+  extAttrs;
+  /** @type {this} */
+  this;
+  /** @type {*} */
+  parent;
+
   /**
    * @param {object} initializer
    * @param {Base["source"]} initializer.source
    * @param {Base["tokens"]} initializer.tokens
    */
   constructor({ source, tokens }) {
     Object.defineProperties(this, {
-      source: { value: source },
-      tokens: { value: tokens, writable: true },
-      parent: { value: null, writable: true },
-      this: { value: this }, // useful when escaping from proxy
+      source: { value: source, enumerable: false },
+      tokens: { value: tokens, writable: true, enumerable: false },
+      parent: { value: null, writable: true, enumerable: false },
+      this: { value: this, enumerable: false }, // useful when escaping from proxy
     });
   }
 
+  /**
+   * @param {Definitions} defs
+   * @returns {IterableIterator<any>}
+   */
+  // eslint-disable-next-line no-unused-vars
+  *validate(defs) {}
+
+  /**
+   * @param {Writer} w
+   * @returns {*}
+   */
+  // eslint-disable-next-line no-unused-vars
+  write(w) {}
+
   toJSON() {
     const json = { type: undefined, name: undefined, inheritance: undefined };
     let proto = this;
     while (proto !== Object.prototype) {
       const descMap = Object.getOwnPropertyDescriptors(proto);
       for (const [key, value] of Object.entries(descMap)) {
         if (value.enumerable || value.get) {
-          // @ts-ignore - allow indexing here
           json[key] = this[key];
         }
       }

lib/productions/callback-interface.js

@@ -1,4 +1,4 @@
-import { Container } from "./container.js";
+import { Container, parseContainer } from "./container.js";
 import { Operation } from "./operation.js";
 import { Constant } from "./constant.js";
 
@@ -15,7 +15,7 @@ export class CallbackInterface extends Container {
     if (!tokens.base) {
       return;
     }
-    return Container.parse(
+    return parseContainer(
       tokeniser,
       new CallbackInterface({ source: tokeniser.source, tokens }),
       {

lib/productions/callback.js

@@ -7,7 +7,15 @@ import {
 } from "./helpers.js";
 import { validationError } from "../error.js";
 
+/** @import {Type} from "./type.js" */
+/** @import {Argument} from "./argument.js" */
+
 export class CallbackFunction extends Base {
+  /** @type {Type} */
+  idlType;
+  /** @type {Argument[]} */
+  arguments;
+
   /**
    * @param {import("../tokeniser.js").Tokeniser} tokeniser
    */

lib/productions/constant.js

@@ -9,6 +9,9 @@ import {
 } from "./helpers.js";
 
 export class Constant extends Base {
+  /** @type {Type} */
+  idlType;
+
   /**
    * @param {import("../tokeniser.js").Tokeniser} tokeniser
    */

lib/productions/constructor.js

@@ -1,7 +1,12 @@
 import { Base } from "./base.js";
 import { argument_list, autoParenter } from "./helpers.js";
 
+/** @import {Argument} from "./argument.js" */
+
 export class Constructor extends Base {
+  /** @type {Argument[]} */
+  arguments;
+
   /**
    * @param {import("../tokeniser.js").Tokeniser} tokeniser
    */

lib/productions/container.js

@@ -2,8 +2,10 @@ import { Base } from "./base.js";
 import { ExtendedAttributes } from "./extended-attributes.js";
 import { unescape, autoParenter } from "./helpers.js";
 
+/** @import {Tokeniser} from "../tokeniser.js" */
+
 /**
- * @param {import("../tokeniser.js").Tokeniser} tokeniser
+ * @param {Tokeniser} tokeniser
  */
 function inheritance(tokeniser) {
   const colon = tokeniser.consume(":");
@@ -19,7 +21,7 @@ function inheritance(tokeniser) {
 /**
  * Parser callback.
  * @callback ParserCallback
- * @param {import("../tokeniser.js").Tokeniser} tokeniser
+ * @param {Tokeniser} tokeniser
  * @param {...*} args
  */
 
@@ -30,45 +32,11 @@ function inheritance(tokeniser) {
  */
 
 export class Container extends Base {
-  /**
-   * @param {import("../tokeniser.js").Tokeniser} tokeniser
-   * @param {*} instance TODO: This should be {T extends Container}, but see https://github.com/microsoft/TypeScript/issues/4628
-   * @param {*} args
-   */
-  static parse(tokeniser, instance, { inheritable, allowedMembers }) {
-    const { tokens, type } = instance;
-    tokens.name =
-      tokeniser.consumeKind("identifier") ||
-      tokeniser.error(`Missing name in ${type}`);
-    tokeniser.current = instance;
-    instance = autoParenter(instance);
-    if (inheritable) {
-      Object.assign(tokens, inheritance(tokeniser));
-    }
-    tokens.open = tokeniser.consume("{") || tokeniser.error(`Bodyless ${type}`);
-    instance.members = [];
-    while (true) {
-      tokens.close = tokeniser.consume("}");
-      if (tokens.close) {
-        tokens.termination =
-          tokeniser.consume(";") ||
-          tokeniser.error(`Missing semicolon after ${type}`);
-        return instance.this;
-      }
-      const ea = ExtendedAttributes.parse(tokeniser);
-      let mem;
-      for (const [parser, ...args] of allowedMembers) {
-        mem = autoParenter(parser(tokeniser, ...args));
-        if (mem) {
-          break;
-        }
-      }
-      if (!mem) {
-        tokeniser.error("Unknown member");
-      }
-      mem.extAttrs = ea;
-      instance.members.push(mem.this);
-    }
+  /** @type {any[]} */
+  members;
+
+  get type() {
+    return "";
   }
 
   get partial() {
@@ -125,3 +93,50 @@ export class Container extends Base {
     );
   }
 }
+
+/**
+ * @param {Tokeniser} tokeniser
+ * @param {Container} instance
+ * @param {object} args
+ * @param {boolean} [args.inheritable]
+ * @param {AllowedMember[]} [args.allowedMembers]
+ */
+export function parseContainer(
+  tokeniser,
+  instance,
+  { inheritable, allowedMembers },
+) {
+  const { tokens, type } = instance;
+  tokens.name =
+    tokeniser.consumeKind("identifier") ||
+    tokeniser.error(`Missing name in ${type}`);
+  tokeniser.current = instance;
+  instance = autoParenter(instance);
+  if (inheritable) {
+    Object.assign(tokens, inheritance(tokeniser));
+  }
+  tokens.open = tokeniser.consume("{") || tokeniser.error(`Bodyless ${type}`);
+  instance.members = [];
+  while (true) {
+    tokens.close = tokeniser.consume("}");
+    if (tokens.close) {
+      tokens.termination =
+        tokeniser.consume(";") ||
+        tokeniser.error(`Missing semicolon after ${type}`);
+      return instance.this;
+    }
+    const ea = ExtendedAttributes.parse(tokeniser);
+    let mem;
+    for (const [parser, ...args] of allowedMembers) {
+      mem = autoParenter(parser(tokeniser, ...args));
+      if (mem) {
+        break;
+      }
+    }
+    if (!mem) {
+      tokeniser.error("Unknown member");
+    }
+    mem.extAttrs = ea;
+    instance.members.push(mem.this);
+  }
+}

lib/productions/default.js

@@ -1,7 +1,12 @@
 import { Base } from "./base.js";
 import { const_data, const_value } from "./helpers.js";
 
+/** @import {Token} from "../tokeniser.js" */
+
 export class Default extends Base {
+  /** @type {Token[]} */
+  expression;
+
   /**
    * @param {import("../tokeniser.js").Tokeniser} tokeniser
    */

lib/productions/dictionary.js

@@ -1,4 +1,4 @@
-import { Container } from "./container.js";
+import { Container, parseContainer } from "./container.js";
 import { Field } from "./field.js";
 
 export class Dictionary extends Container {
@@ -14,7 +14,7 @@ export class Dictionary extends Container {
     if (!tokens.base) {
       return;
     }
-    return Container.parse(
+    return parseContainer(
       tokeniser,
       new Dictionary({ source: tokeniser.source, tokens }),
       {

lib/productions/enum.js

@@ -35,6 +35,9 @@ export class EnumValue extends WrappedToken {
 }
 
 export class Enum extends Base {
+  /** @type {EnumValue[]} */
+  values;
+
   /**
    * @param {import("../tokeniser.js").Tokeniser} tokeniser
    */

lib/productions/extended-attributes.js

@@ -50,7 +50,12 @@ function extAttrListItems(tokeniser) {
   );
 }
 
+/** @import {Argument} from "./argument.js" */
+
 export class ExtendedAttributeParameters extends Base {
+  /** @type {WrappedToken[] | Argument[]} */
+  list;
+
   /**
    * @param {import("../tokeniser.js").Tokeniser} tokeniser
    */
@@ -121,6 +126,9 @@ export class ExtendedAttributeParameters extends Base {
 }
 
 export class SimpleExtendedAttribute extends Base {
+  /** @type {ExtendedAttributeParameters} */
+  params;
+
   /**
    * @param {import("../tokeniser.js").Tokeniser} tokeniser
    */
@@ -138,7 +146,7 @@ export class SimpleExtendedAttribute extends Base {
   constructor({ source, tokens, params }) {
     super({ source, tokens });
     params.parent = this;
-    Object.defineProperty(this, "params", { value: params });
+    Object.defineProperty(this, "params", { value: params, enumerable: false });
   }
 
   get type() {

lib/productions/field.js

@@ -7,7 +7,14 @@ import {
 import { ExtendedAttributes } from "./extended-attributes.js";
 import { Default } from "./default.js";
 
+/** @import {Type} from "./type.js" */
+
 export class Field extends Base {
+  /** @type {Type} */
+  idlType;
+  /** @type {Default} */
+  default;
+
   /**
    * @param {import("../tokeniser.js").Tokeniser} tokeniser
    */

lib/productions/index.js

@@ -3,7 +3,7 @@ export { Attribute } from "./attribute.js";
 export { Base } from "./base.js";
 export { Constant } from "./constant.js";
 export { Constructor } from "./constructor.js";
-export { Container } from "./container.js";
+export { Container, parseContainer } from "./container.js";
 export { Default } from "./default.js";
 export {
   ExtendedAttributes,

lib/productions/interface.js

@@ -1,4 +1,4 @@
-import { Container } from "./container.js";
+import { Container, parseContainer } from "./container.js";
 import { Attribute } from "./attribute.js";
 import { Operation } from "./operation.js";
 import { Constant } from "./constant.js";
@@ -41,7 +41,7 @@ export class Interface extends Container {
    */
   static parse(tokeniser, base, { extMembers = [], partial = null } = {}) {
     const tokens = { partial, base };
-    return Container.parse(
+    return parseContainer(
       tokeniser,
       new Interface({ source: tokeniser.source, tokens }),
       {