Support @template (#153)

* Add/implement parseJSDocTemplates.js

* partition.js: choose unique name for arr in loop

* src-transpiler/parseJSDocTemplates.js: make function type simply CapitalCase

* src-transpiler/parseJSDoc.js: Improve typing

* src-transpiler/index.js: export parseJSDocTemplates.js

* replaceType: handle arrays and unions

* Add unit tests

* ArrayPattern unit test changes

* Add test/typechecking/simple-ArrayPattern-output.mjs

* Update test/typechecking.json

* Integrate parseJSDocTemplates in src-transpiler/Asserter.js

* Add inspectTypeWithTemplates.js

* src-runtime/createType.js: Fix spelling

* Add test/typechecking/template-types-1.js

* Integrate as proper unit test: test/typechecking/template-types-1

Author: kungfooman

src-runtime/createType.js

@@ -5,7 +5,7 @@ import {createTypeFromMapping      } from "./createTypeFromMapping.js";
 /**
  * @param {string|import('./validateType.js').Type} expect - The supposed type information of said value.
  * @param {console["warn"]} warn - Function to warn with.
- * @returns {import('./validateType.js').Type|undefined} - New type that can be used for validatoin
+ * @returns {import('./validateType.js').Type|undefined} - New type that can be used for validation.
  */
 function createType(expect, warn) {
   const mapping = resolveType(expect, 'mapping', warn);

src-runtime/index.js

@@ -7,6 +7,7 @@ export * from './customTypes.js';
 export * from './customValidations.js';
 export * from './getTypeKeys.js';
 export * from './inspectType.js';
+export * from './inspectTypeWithTemplates.js';
 export * from './isObject.js';
 export * from './makeJSDoc.js';
 export * from './options.js';

src-runtime/inspectTypeWithTemplates.js

@@ -0,0 +1,21 @@
+import {inspectType} from "./inspectType.js";
+import {replaceType} from "./replaceType.js";
+function inspectTypeWithTemplates(value, expect, loc, name, templates) {
+  // console.log("old expect", expect);
+  for (const key in templates) {
+    expect = replaceType(expect, key, templates[key], console.warn);
+  }
+  // console.log("new expect", expect);
+  const ret = inspectType(value, expect, loc, name);
+  // if (ret) {
+    // Narrowing string|number down, for instance:
+    // templates["T"] = "number";
+    // We don't narrow down the possible template type based on first input type here,
+    // because after all it could be a union of all types. We can't know that from
+    // JS side. However I still like the idea of narrowing it down, so we
+    // could at least make it an option... and obviously we also have to integrate
+    // the NoInfer intrinsic, but that will be later PR's...
+  // }
+  return ret;
+}
+export {inspectTypeWithTemplates};

src-runtime/partition.js

@@ -14,8 +14,8 @@ function partition(arr, fn) {
   /** @type {any[]} */
   const fail = [];
   for (const element of arr) {
-    const arr = fn(element) ? pass : fail;
-    arr.push(element);
+    const pick = fn(element) ? pass : fail;
+    pick.push(element);
   }
   return [pass, fail];
 }

src-runtime/replaceType.js

@@ -5,6 +5,7 @@
  *  - add bunch of unit tests to test all possible cases
  *  - call it copyAndReplace?
  *  - if a subtype is a typedef and we change that without creating a copy, we invalidate that typedef... make a unit test
+ *  - add intersection type replacements for instance: 'fixed' & Key
  * @param {*} type - The type.
  * @param {*} search - The search.
  * @param {*} replace - The replace.
@@ -25,14 +26,23 @@ function replaceType(type, search, replace, warn) {
       properties[prop] = replaceType(val, search, replace, warn);
     }
     return type;
-  } else if (type.type === "tuple") {
+  } else if (type.type === 'tuple') {
     const {elements} = type;
-    const n = elements.length;
-    for (let i = 0; i < n; i++) {
-      const val = elements[i];
-      const replacedVal = replaceType(val, search, replace, warn);
-      elements[i] = replacedVal;
-      //if ()
+    const {length  } = elements;
+    for (let i = 0; i < length; i++) {
+      const element = elements[i];
+      elements[i] = replaceType(element, search, replace, warn);
+    }
+    return type;
+  } else if (type.type === 'array') {
+    type.elementType = replaceType(type.elementType, search, replace, warn);
+    return type;
+  } else if (type.type === 'union') {
+    const {members} = type;
+    const {length } = members;
+    for (let i = 0; i < length; i++) {
+      const member = members[i];
+      members[i] = replaceType(member, search, replace, warn);
     }
     return type;
   }

src-transpiler/Asserter.js

@@ -1,20 +1,21 @@
-import {requiredTypeofs  } from './expandType.js';
-import {expandTypeDepFree} from './expandTypeDepFree.js';
-import {nodeIsFunction   } from './nodeIsFunction.js';
-import {parseJSDoc       } from './parseJSDoc.js';
-import {parseJSDocSetter } from './parseJSDocSetter.js';
-import {parseJSDocTypedef} from './parseJSDocTypedef.js';
-import {statReset        } from './stat.js';
-import {Stringifier      } from './Stringifier.js';
+import {requiredTypeofs    } from './expandType.js';
+import {expandTypeDepFree  } from './expandTypeDepFree.js';
+import {nodeIsFunction     } from './nodeIsFunction.js';
+import {parseJSDoc         } from './parseJSDoc.js';
+import {parseJSDocSetter   } from './parseJSDocSetter.js';
+import {parseJSDocTemplates} from './parseJSDocTemplates.js';
+import {parseJSDocTypedef  } from './parseJSDocTypedef.js';
+import {statReset          } from './stat.js';
+import {Stringifier        } from './Stringifier.js';
 /** @typedef {import('@babel/types').Node              } Node               */
-/** @typedef {import("@babel/types").ClassMethod       } ClassMethod        */
-/** @typedef {import("@babel/types").ClassPrivateMethod} ClassPrivateMethod */
-/** @typedef {import('./stat.js').Stat                } Stat               */
+/** @typedef {import('@babel/types').ClassMethod       } ClassMethod        */
+/** @typedef {import('@babel/types').ClassPrivateMethod} ClassPrivateMethod */
+/** @typedef {import('./stat.js').Stat                 } Stat               */
 /**
  * @typedef {object} Options
  * @property {boolean} [forceCurly] - Determines whether curly braces are enforced in Stringifier.
  * @property {boolean} [validateDivision] - Indicates whether division operations should be validated.
- * @property {Function} [expandType] - A function that expands shorthand types into full descriptions.
+ * @property {import('./parseJSDoc.js').ExpandType} [expandType] - A function that expands shorthand types into full descriptions.
  * @property {string} [filename] - The name of a file to which the instance pertains.
  * @property {boolean} [addHeader] - Whether to add import declarations headers. Defaults to true.
  * @property {string[]} [ignoreLocations] - Ignore these locations because they are known false-positives.
@@ -219,9 +220,9 @@ class Asserter extends Stringifier {
   }
   /**
    * @param {Node} node - The Babel AST node.
-   * @returns {undefined | {}} The return value of `parseJSDoc`.
+   * @returns {string|undefined} The JSDoc comment of `node`.
    */
-  getJSDoc(node) {
+  getLeadingComment(node) {
     if (node.type === 'BlockStatement') {
       node = this.parent;
     }
@@ -245,26 +246,48 @@ class Asserter extends Stringifier {
     if (leadingComments && leadingComments.length) {
       const lastComment = leadingComments[leadingComments.length - 1];
       if (lastComment.type === "CommentBlock") {
-        if (lastComment.value.includes('@event')) {
-          return;
-        }
-        if (node.type === 'ClassMethod' && node.kind === 'set') {
-          const paramName = this.getNameOfParam(node.params[0]);
-          if (node.params.length !== 1) {
-            this.warn("getJSDoc> setters require exactly one argument");
-          }
-          const setterType = parseJSDocSetter(lastComment.value, this.expandType);
-          if (!setterType) {
-            return;
-          }
-          return {[paramName]: setterType};
-        }
-        if (lastComment.value.includes('@ignoreRTI')) {
-          return;
-        }
-        return parseJSDoc(lastComment.value, this.expandType);
+        return lastComment.value;
+      }
+    }
+  }
+  /**
+   * @param {Node} node - The Babel AST node.
+   * @todo ESLint problem:
+   * returns {import('./parseJSDoc.js').ParseJSDocReturnType} The return value of `parseJSDoc`
+   * returns {Record<string, import('./parseJSDoc.js').ExpandTypeReturnType> | undefined} The
+   * return value of `parseJSDoc`.
+   * @returns {Record<string, any>|undefined} asd
+   */
+  getJSDoc(node) {
+    const comment = this.getLeadingComment(node);
+    if (!comment) {
+      return;
+    }
+    if (comment.includes('@event')) {
+      return;
+    }
+    if (comment.includes('@ignoreRTI')) {
+      return;
+    }
+    // Need to do same resolving as in: this.getLeadingComment(node)
+    if (node.type === 'BlockStatement') {
+      node = this.parent;
+    }
+    if (node.type === 'ClassMethod' && node.kind === 'set') {
+      const paramName = this.getNameOfParam(node.params[0]);
+      if (node.params.length !== 1) {
+        this.warn("getJSDoc> setters require exactly one argument");
+      }
+      const setterType = parseJSDocSetter(comment, this.expandType);
+      if (!setterType) {
+        return;
       }
+      const params = {[paramName]: setterType};
+      return {templates: undefined, params};
     }
+    const templates = parseJSDocTemplates(comment);
+    const params = parseJSDoc(comment, this.expandType);
+    return {templates, params};
   }
   /**
    * Retrieves the name of a parameter from a Babel AST node.
@@ -283,8 +306,7 @@ class Asserter extends Stringifier {
         return param.left.name;
       }
     }
-    debugger;
-    this.warn("unable to extra name from param in specified way - may contain too much information");
+    this.warn("Unable to retrieve name from param in specified way - may contain too much information.");
     return this.toSource(param);
   }
   statsReset() {
@@ -391,6 +413,12 @@ class Asserter extends Stringifier {
       stat.unchecked++;
       return '';
     }
+    const {templates, params} = jsdoc;
+    if (!params) {
+      console.warn("This should never happen, please check your input code.", this.getLeadingComment(node), {jsdoc});
+      stat.unchecked++;
+      return '';
+    }
     stat.checked++;
     const {spaces} = this;
     let out = '';
@@ -399,17 +427,21 @@ class Asserter extends Stringifier {
     if (this.ignoreLocations.includes(loc)) {
       return '// IGNORE RTI TYPE VALIDATIONS, KNOWN ISSUES\n';
     }
+    if (templates) {
+      const tmp = JSON.stringify(templates, null, 2).replaceAll('\n', '\n' + spaces);
+      out += `\n${spaces}const rtiTemplates = ${tmp};`;
+    }
     //out += `${spaces}/*${spaces}  node.type=${node.type}\n${spaces}
     //  ${JSON.stringify(jsdoc)}\n${parent}\n${spaces}*/\n`;
-    for (let name in jsdoc) {
-      const type = jsdoc[name];
+    for (let name in params) {
+      const type = params[name];
       const hasParam = this.nodeHasParamName(node, name);
       if (!hasParam) {
         let testNode = node;
         if (node.type === 'BlockStatement') {
           testNode = this.parent;
         }
-        const paramIndex = Object.keys(jsdoc).findIndex(_ => _ === name);
+        const paramIndex = Object.keys(params).findIndex(_ => _ === name);
         const param = testNode.params[paramIndex];
         if (param) {
           const isObjectPattern = param.type === 'ObjectPattern';
@@ -439,7 +471,11 @@ class Asserter extends Stringifier {
                   continue;
                 }
                 const t = JSON.stringify(type.elementType, null, 2).replaceAll('\n', '\n' + spaces);
-                out += `${spaces}if (!inspectType(${element.name}, ${t}, '${loc}', '${name}')) {\n`;
+                if (templates) {
+                  out += `${spaces}if (!inspectTypeWithTemplates(${element.name}, ${t}, '${loc}', '${name}', rtiTemplates)) {\n`;
+                } else {
+                  out += `${spaces}if (!inspectType(${element.name}, ${t}, '${loc}', '${name}')) {\n`;
+                }
                 out += `${spaces}  youCanAddABreakpointHere();\n${spaces}}\n`;
               }
               continue;
@@ -465,7 +501,11 @@ class Asserter extends Stringifier {
                   continue;
                 }
                 const t = JSON.stringify(subType, null, 2).replaceAll('\n', '\n' + spaces);
-                out += `${spaces}if (!inspectType(${keyName}, ${t}, '${loc}', '${name}')) {\n`;
+                if (templates) {
+                  out += `${spaces}if (!inspectTypeWithTemplates(${keyName}, ${t}, '${loc}', '${name}', rtiTemplates)) {\n`;
+                } else {
+                  out += `${spaces}if (!inspectType(${keyName}, ${t}, '${loc}', '${name}')) {\n`;
+                }
                 out += `${spaces}  youCanAddABreakpointHere();\n${spaces}}\n`;
               }
               continue;
@@ -503,7 +543,11 @@ class Asserter extends Stringifier {
         out += '\n';
         first = false;
       }
-      out += `${spaces}if (${prevCheck}!inspectType(${name}, ${t}, '${loc}', '${name}')) {\n`;
+      if (templates) {
+        out += `${spaces}if (${prevCheck}!inspectTypeWithTemplates(${name}, ${t}, '${loc}', '${name}', rtiTemplates)) {\n`;
+      } else {
+        out += `${spaces}if (${prevCheck}!inspectType(${name}, ${t}, '${loc}', '${name}')) {\n`;
+      }
       out += `${spaces}  youCanAddABreakpointHere();\n${spaces}}\n`;
     }
     return out;

src-transpiler/index.js

@@ -17,6 +17,7 @@ export * from './extractNameAndOptionality.js';
 export * from './nodeIsFunction.js';
 export * from './parseJSDoc.js';
 export * from './parseJSDocSetter.js';
+export * from './parseJSDocTemplates.js';
 export * from './parseJSDocTypedef.js';
 export * from './simplifyType.js';
 export * from './Stringifier.js';

src-transpiler/parseJSDoc.js

@@ -1,17 +1,24 @@
 import {expandTypeDepFree} from "./expandTypeDepFree.js";
 import {simplifyType} from "./simplifyType.js";
+/**
+ * @typedef {ReturnType<typeof parseJSDoc>} ParseJSDocReturnType
+ */
+/**
+ * @typedef {typeof expandTypeDepFree} ExpandType
+ * @typedef {ReturnType<ExpandType>} ExpandTypeReturnType
+ */
 /**
  * Parses JSDoc comments to extract parameter type information.
  *
  * @param {string} src - The JSDoc comment string to parse.
- * @param {Function} [expandType] - An optional function to process the types found in the JSDoc.
- * @returns {Record<string, any> | undefined} An object mapping parameter names to their parsed types, or undefined if no parameters are found.
+ * @param {ExpandType} [expandType] - An optional function to process the types found in the JSDoc.
+ * @returns {Record<string, ExpandTypeReturnType> | undefined} An object mapping parameter names to their parsed types, or undefined if no parameters are found.
  */
 function parseJSDoc(src, expandType = expandTypeDepFree) {
   // Parse something like: @param {Object} [kwargs={}] Optional arguments.
   const regex = /@param \{(.*?)\} ([\[\]a-zA-Z0-9_$=\{\}\.'" ]+)/g;
   const matches = [...src.matchAll(regex)];
-  /** @type {Record<string, any>} */
+  /** @type {Record<string, ExpandTypeReturnType>} */
   const params = Object.create(null);
   matches.forEach(_ => {
     const type = expandType(_[1].trim());
@@ -35,7 +42,6 @@ function parseJSDoc(src, expandType = expandTypeDepFree) {
     const parts = name.split(/[\[\]]*\./);
     let properties = params;
     for (const part of parts) {
-      /** @type {object} */
       const toptype = properties[part];
       if (!toptype) {
         // No toptype means we resolved as far as possible, now we can add `simplifiedType`.

src-transpiler/parseJSDocTemplates.js

@@ -0,0 +1,29 @@
+import {expandTypeDepFree} from "./expandTypeDepFree.js";
+/**
+ * @typedef {typeof expandTypeDepFree} ExpandType
+ * @typedef {ReturnType<ExpandType>} ExpandTypeReturnType
+ */
+/**
+ * Parses JSDoc comments to extract parameter type information.
+ *
+ * @param {string} src - The JSDoc comment string to parse.
+ * @param {ExpandType} [expandType] - An optional function to process the types found in the JSDoc.
+ * @returns {Record<string, ExpandTypeReturnType> | undefined} An object mapping template names to their parsed types,
+ * or `undefined` if no template tags were found.
+ */
+function parseJSDocTemplates(src, expandType = expandTypeDepFree) {
+  const regexTemplateTyped = /@template \{(.*?)\} ([a-zA-Z0-9_$=]+)/g;
+  const matches = [...src.matchAll(regexTemplateTyped)];
+  if (!matches.length) {
+    return;
+  }
+  /** @type {Record<string, ExpandTypeReturnType>} */
+  const templates = Object.create(null);
+  matches.forEach(_ => {
+    const type = expandType(_[1].trim());
+    const name = _[2].trim();
+    templates[name] = type;
+  });
+  return templates;
+}
+export {parseJSDocTemplates};

test/replaceType/1.js

@@ -0,0 +1,35 @@
+// Mode: eval
+registerTypedef('TestObject', expandType(`{a: 'aa', b: 'bb', c: 'cc'}`));
+console.log("typedefs", typedefs);
+const mapping = expandType(`{
+  [Key in 1|2]: {
+    td: TestObject,
+    testkey: [Key, Key, Key],
+    bla: Key,
+    testArr: Key[],
+    testUnion: 'fixed'|Key,
+  }
+}`);
+const type = createTypeFromMapping(mapping, console.warn);
+const key = type.properties[1].properties.bla;
+console.log(`The key should be 1: ${key} (${key === 1})`, {type});
+function stringify(_) {
+  let ret = JSON.stringify(_, null, 2);
+  const regExp = /\[[\n ,0-9]*?\]/gm;
+  ret = ret.replace(regExp, (all) => {
+    return all.replace(/\n| /g, '');
+  });
+  // Turn this: "type": "array"
+  // Into this: type:  "array"
+  ret = ret.replaceAll(/\"([a-zA-Z0-9]+)\":+/g, "$1: ");
+  return ret;
+}
+function a() {
+  //const type = expandType("number|T");
+  //const type = expandType("[T, T, T]");
+  const type = expandType("T[]");
+  //const type = expandType("string");
+  const newType = replaceType(type, 'T', 'string', console.warn);
+  return stringify(newType);
+}
+setRight(stringify(type) + '\n\n' + a());