@runtime-type-inspector/transpiler 5.0.4 → 5.0.5

package/index.cjs

@@ -449,9 +449,9 @@
 	    TypeQuery = _ts$SyntaxKind.TypeQuery,
 	    TypeOperator = _ts$SyntaxKind.TypeOperator,
 	    KeyOfKeyword = _ts$SyntaxKind.KeyOfKeyword,
-	    ReadonlyKeyword = _ts$SyntaxKind.ReadonlyKeyword;
-	    _ts$SyntaxKind.UniqueKeyword;
-	    var ConstructorType = _ts$SyntaxKind.ConstructorType,
+	    ReadonlyKeyword = _ts$SyntaxKind.ReadonlyKeyword,
+	    UniqueKeyword = _ts$SyntaxKind.UniqueKeyword,
+	    ConstructorType = _ts$SyntaxKind.ConstructorType,
 	    NamedTupleMember = _ts$SyntaxKind.NamedTupleMember,
 	    MappedType = _ts$SyntaxKind.MappedType,
 	    MinusToken = _ts$SyntaxKind.MinusToken,
@@ -639,6 +639,11 @@
 	        // readonly erased at runtime, same shape as the inner type.
 	        return toSourceTS(node.type);
 	      }
+	      if (node.operator === UniqueKeyword) {
+	        // `unique symbol` is a symbol at runtime; the uniqueness refers to
+	        // a specific declaration which we cannot track here.
+	        return toSourceTS(node.type);
+	      }
 	      console.warn("unimplemented TypeOperator", node);
 	      return 'any';
 	    case TypeReference:
@@ -1370,7 +1375,7 @@
 	    return expandTypeDepFree(type.slice(9).trim());
 	  }
 	  if (type === 'unique symbol') {
-	    return 'any';
+	    return 'symbol';
 	  }
 	  // Conditionals before nullable: `A extends B ? C : D?` must keep the
 	  // nullable on the false branch, not lift it over the whole condition.
@@ -2634,6 +2639,21 @@
 	  var matches = _toConsumableArray(src.matchAll(regexTemplateTyped));
 	  /** @type {Record<string, ExpandTypeReturnType>} */
 	  var templates = Object.create(null);
+	  // `@template {Constraint} [Name=Default]` (or `[Name]`): constraint wins,
+	  // the default only matters when nothing is inferred.
+	  var regexTemplateConstrainedDefault = /@template \{(.*?)\}\s*\[([a-zA-Z0-9_$]+)(?:=([^\]]+))?\]/g;
+	  var _iterator = _createForOfIteratorHelper(src.matchAll(regexTemplateConstrainedDefault)),
+	    _step;
+	  try {
+	    for (_iterator.s(); !(_step = _iterator.n()).done;) {
+	      var match = _step.value;
+	      templates[match[2]] = expandType(match[1].trim());
+	    }
+	  } catch (err) {
+	    _iterator.e(err);
+	  } finally {
+	    _iterator.f();
+	  }
 	  matches.forEach(function (_) {
 	    var type = expandType(_[1].trim());
 	    var name = _[2].trim();
@@ -2641,34 +2661,34 @@
 	  });
 	  // `@template [A=X]` defaults: constraint X under name A.
 	  var regexTemplateDefault = /@template \[([a-zA-Z0-9_$]+)=([^\]]+)\]/g;
-	  var _iterator = _createForOfIteratorHelper(src.matchAll(regexTemplateDefault)),
-	    _step;
+	  var _iterator2 = _createForOfIteratorHelper(src.matchAll(regexTemplateDefault)),
+	    _step2;
 	  try {
-	    for (_iterator.s(); !(_step = _iterator.n()).done;) {
-	      var match = _step.value;
-	      templates[match[1]] = expandType(match[2].trim());
+	    for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
+	      var _match = _step2.value;
+	      templates[_match[1]] = expandType(_match[2].trim());
 	    }
 	    // Bare `@template T`: unconstrained, stands in as any.
 	  } catch (err) {
-	    _iterator.e(err);
+	    _iterator2.e(err);
 	  } finally {
-	    _iterator.f();
+	    _iterator2.f();
 	  }
 	  var regexTemplateBare = /@template ([a-zA-Z0-9_$]+)(?![a-zA-Z0-9_$])/g;
-	  var _iterator2 = _createForOfIteratorHelper(src.matchAll(regexTemplateBare)),
-	    _step2;
+	  var _iterator3 = _createForOfIteratorHelper(src.matchAll(regexTemplateBare)),
+	    _step3;
 	  try {
-	    for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
-	      var _match = _step2.value;
-	      var name = _match[1];
+	    for (_iterator3.s(); !(_step3 = _iterator3.n()).done;) {
+	      var _match2 = _step3.value;
+	      var name = _match2[1];
 	      if (!(name in templates)) {
 	        templates[name] = 'any';
 	      }
 	    }
 	  } catch (err) {
-	    _iterator2.e(err);
+	    _iterator3.e(err);
 	  } finally {
-	    _iterator2.f();
+	    _iterator3.f();
 	  }
 	  if (!Object.keys(templates).length) {
 	    return;
@@ -5363,6 +5383,115 @@
 	        params: params
 	      };
 	    }
+	    /**
+	     * Reads `@template` bindings from every lexically enclosing scope, outer
+	     * to inner: classes (declaration or expression, incl. `export` wrappers)
+	     * and functions with their own `@template` tags. Class templates scope
+	     * over the constructor and methods, mirroring TypeScript:
+	     * `new Asset('x', ...)` infers `K` from the constructor's `@param {K}`
+	     * occurrences. Inner scopes shadow outer names on conflict.
+	     * @param {Node} node - The function or block node being checked.
+	     * @returns {Record<string, any>|undefined} Merged scope templates or undefined.
+	     */
+	  }, {
+	    key: "getScopeTemplates",
+	    value: function getScopeTemplates(node) {
+	      var fnNode = node;
+	      if (node.type === 'BlockStatement') {
+	        fnNode = this.parent;
+	      }
+	      var anchorIdx = this.parents.findLastIndex(function (_) {
+	        return _ === node;
+	      });
+	      if (anchorIdx === -1) {
+	        return;
+	      }
+	      var merged;
+	      for (var i = 0; i <= anchorIdx; i++) {
+	        var ancestor = this.parents[i];
+	        if (!ancestor || ancestor === fnNode) {
+	          // Never inherit the node's own bindings: they merge separately and win.
+	          continue;
+	        }
+	        var templates = void 0;
+	        if (ancestor.type === 'ClassDeclaration' || ancestor.type === 'ClassExpression') {
+	          templates = this.classTemplatesOf(ancestor);
+	        } else if (nodeIsFunctionLike(ancestor)) {
+	          templates = this.functionTemplatesOf(ancestor);
+	        }
+	        if (templates) {
+	          merged = _objectSpread2(_objectSpread2({}, merged), templates);
+	        }
+	      }
+	      return merged;
+	    }
+	    /**
+	     * Reads the `@template` bindings off one class node.
+	     * @param {Node} classDecl - The ClassDeclaration or ClassExpression node.
+	     * @returns {Record<string, any>|undefined} Its templates or undefined.
+	     */
+	  }, {
+	    key: "classTemplatesOf",
+	    value: function classTemplatesOf(classDecl) {
+	      var _leadingComments;
+	      var leadingComments = classDecl.leadingComments;
+	      if (!leadingComments) {
+	        var exportNamed = this.findParentOfType(classDecl, 'ExportNamedDeclaration');
+	        leadingComments = exportNamed === null || exportNamed === void 0 ? void 0 : exportNamed.leadingComments;
+	        if (!leadingComments) {
+	          var exportDefault = this.findParentOfType(classDecl, 'ExportDefaultDeclaration');
+	          leadingComments = exportDefault === null || exportDefault === void 0 ? void 0 : exportDefault.leadingComments;
+	        }
+	        if (!leadingComments && classDecl.type === 'ClassExpression') {
+	          // `/** @template K */ const Box = class {...}`: the comment lives on
+	          // the declaration, mirroring function-expression handling.
+	          var varDecl = this.findParentOfType(classDecl, 'VariableDeclaration');
+	          leadingComments = varDecl === null || varDecl === void 0 ? void 0 : varDecl.leadingComments;
+	        }
+	      }
+	      if (!((_leadingComments = leadingComments) !== null && _leadingComments !== void 0 && _leadingComments.length)) {
+	        return;
+	      }
+	      var lastComment = leadingComments[leadingComments.length - 1];
+	      if (lastComment.type !== 'CommentBlock') {
+	        return;
+	      }
+	      return parseJSDocTemplates(lastComment.value);
+	    }
+	    /**
+	     * Reads the `@template` bindings off one enclosing function: its own
+	     * leading comment, resolving the same `export`/declarator wrappers the
+	     * node's own JSDoc lookup uses.
+	     * @param {Node} fnNode - The enclosing function-like node.
+	     * @returns {Record<string, any>|undefined} Its templates or undefined.
+	     */
+	  }, {
+	    key: "functionTemplatesOf",
+	    value: function functionTemplatesOf(fnNode) {
+	      var _leadingComments2;
+	      var leadingComments;
+	      if (fnNode.type === 'FunctionDeclaration') {
+	        var _fnNode$leadingCommen, _this$findParentOfTyp;
+	        leadingComments = (_fnNode$leadingCommen = fnNode.leadingComments) !== null && _fnNode$leadingCommen !== void 0 ? _fnNode$leadingCommen : (_this$findParentOfTyp = this.findParentOfType(fnNode, 'ExportNamedDeclaration')) === null || _this$findParentOfTyp === void 0 ? void 0 : _this$findParentOfTyp.leadingComments;
+	      } else if (fnNode.type === 'FunctionExpression') {
+	        var _this$getLeadingComme;
+	        leadingComments = (_this$getLeadingComme = this.getLeadingCommentsNodeForFunctionExpression(fnNode)) === null || _this$getLeadingComme === void 0 ? void 0 : _this$getLeadingComme.leadingComments;
+	      } else if (fnNode.type === 'ArrowFunctionExpression') {
+	        var _this$getLeadingComme2;
+	        leadingComments = (_this$getLeadingComme2 = this.getLeadingCommentsNodeForArrowFunctionExpression(fnNode)) === null || _this$getLeadingComme2 === void 0 ? void 0 : _this$getLeadingComme2.leadingComments;
+	      } else {
+	        // ObjectMethod, ClassMethod, ClassPrivateMethod: docs sit on the node.
+	        leadingComments = fnNode.leadingComments;
+	      }
+	      if (!((_leadingComments2 = leadingComments) !== null && _leadingComments2 !== void 0 && _leadingComments2.length)) {
+	        return;
+	      }
+	      var lastComment = leadingComments[leadingComments.length - 1];
+	      if (lastComment.type !== 'CommentBlock') {
+	        return;
+	      }
+	      return parseJSDocTemplates(lastComment.value);
+	    }
 	    /**
 	     * Retrieves the name of a parameter from a Babel AST node.
 	     *
@@ -5510,7 +5639,7 @@
 	        stat.checked++;
 	        return this.emitDefaultChecks(node, inferred, true);
 	      }
-	      var templates = jsdoc.templates,
+	      var ownTemplates = jsdoc.templates,
 	        params = jsdoc.params;
 	      if (!params) {
 	        console.warn("This should never happen, please check your input code.", this.getLeadingComment(node), {
@@ -5519,6 +5648,11 @@
 	        stat.unchecked++;
 	        return '';
 	      }
+	      // Lexically enclosing `@template`s (classes and functions) scope over
+	      // this node: merge them under method-local templates so `K` in
+	      // `@param {K}` resolves jointly. Inner scopes shadow outer ones.
+	      var scopeTemplates = this.getScopeTemplates(node);
+	      var templates = scopeTemplates ? _objectSpread2(_objectSpread2({}, scopeTemplates), ownTemplates) : ownTemplates;
 	      stat.checked++;
 	      var spaces = this.spaces;
 	      var out = '';
@@ -6606,6 +6740,11 @@
 	          argument: keyofArg
 	        };
 	      }
+	      if (node.operator === 'unique') {
+	        // `unique symbol` is a symbol at runtime; uniqueness refers to a
+	        // specific declaration which we cannot track here.
+	        return toSourceBabelTS(node.typeAnnotation);
+	      }
 	      console.warn('unimplemented TSTypeOperator', node.operator);
 	      return 'any';
 	    case 'TSQualifiedName':

package/index.mjs

@@ -1,6 +1,21 @@
 import { parse } from '@babel/parser';
 import ts from 'typescript';
 
+function _extends() {
+  _extends = Object.assign ? Object.assign.bind() : function (target) {
+    for (var i = 1; i < arguments.length; i++) {
+      var source = arguments[i];
+      for (var key in source) {
+        if (Object.prototype.hasOwnProperty.call(source, key)) {
+          target[key] = source[key];
+        }
+      }
+    }
+    return target;
+  };
+  return _extends.apply(this, arguments);
+}
+
 /**
  * @typedef DocType
  * @property {boolean} optional - Type is optional.
@@ -406,6 +421,11 @@ function toSourceTS(node) {
         // readonly erased at runtime, same shape as the inner type.
         return toSourceTS(node.type);
       }
+      if (node.operator === UniqueKeyword) {
+        // `unique symbol` is a symbol at runtime; the uniqueness refers to
+        // a specific declaration which we cannot track here.
+        return toSourceTS(node.type);
+      }
       console.warn("unimplemented TypeOperator", node);
       return 'any';
     case TypeReference:
@@ -1119,7 +1139,7 @@ function expandTypeDepFree(type) {
     return expandTypeDepFree(type.slice(9).trim());
   }
   if (type === 'unique symbol') {
-    return 'any';
+    return 'symbol';
   }
   // Conditionals before nullable: `A extends B ? C : D?` must keep the
   // nullable on the false branch, not lift it over the whole condition.
@@ -1365,21 +1385,6 @@ function expandTypeDepFree(type) {
   return type;
 }
 
-function _extends() {
-  _extends = Object.assign ? Object.assign.bind() : function (target) {
-    for (var i = 1; i < arguments.length; i++) {
-      var source = arguments[i];
-      for (var key in source) {
-        if (Object.prototype.hasOwnProperty.call(source, key)) {
-          target[key] = source[key];
-        }
-      }
-    }
-    return target;
-  };
-  return _extends.apply(this, arguments);
-}
-
 /**
  * Extracts the parameter name and its optionality from a JSDoc parameter string.
  *
@@ -2303,6 +2308,12 @@ function parseJSDocTemplates(src, expandType = expandTypeDepFree) {
   const matches = [...src.matchAll(regexTemplateTyped)];
   /** @type {Record<string, ExpandTypeReturnType>} */
   const templates = Object.create(null);
+  // `@template {Constraint} [Name=Default]` (or `[Name]`): constraint wins,
+  // the default only matters when nothing is inferred.
+  const regexTemplateConstrainedDefault = /@template \{(.*?)\}\s*\[([a-zA-Z0-9_$]+)(?:=([^\]]+))?\]/g;
+  for (const match of src.matchAll(regexTemplateConstrainedDefault)) {
+    templates[match[2]] = expandType(match[1].trim());
+  }
   matches.forEach(_ => {
     const type = expandType(_[1].trim());
     const name = _[2].trim();
@@ -4916,6 +4927,107 @@ class Asserter extends Stringifier {
       params
     };
   }
+  /**
+   * Reads `@template` bindings from every lexically enclosing scope, outer
+   * to inner: classes (declaration or expression, incl. `export` wrappers)
+   * and functions with their own `@template` tags. Class templates scope
+   * over the constructor and methods, mirroring TypeScript:
+   * `new Asset('x', ...)` infers `K` from the constructor's `@param {K}`
+   * occurrences. Inner scopes shadow outer names on conflict.
+   * @param {Node} node - The function or block node being checked.
+   * @returns {Record<string, any>|undefined} Merged scope templates or undefined.
+   */
+  getScopeTemplates(node) {
+    let fnNode = node;
+    if (node.type === 'BlockStatement') {
+      fnNode = this.parent;
+    }
+    const anchorIdx = this.parents.findLastIndex(_ => _ === node);
+    if (anchorIdx === -1) {
+      return;
+    }
+    let merged;
+    for (let i = 0; i <= anchorIdx; i++) {
+      const ancestor = this.parents[i];
+      if (!ancestor || ancestor === fnNode) {
+        // Never inherit the node's own bindings: they merge separately and win.
+        continue;
+      }
+      let templates;
+      if (ancestor.type === 'ClassDeclaration' || ancestor.type === 'ClassExpression') {
+        templates = this.classTemplatesOf(ancestor);
+      } else if (nodeIsFunctionLike(ancestor)) {
+        templates = this.functionTemplatesOf(ancestor);
+      }
+      if (templates) {
+        merged = _extends({}, merged, templates);
+      }
+    }
+    return merged;
+  }
+  /**
+   * Reads the `@template` bindings off one class node.
+   * @param {Node} classDecl - The ClassDeclaration or ClassExpression node.
+   * @returns {Record<string, any>|undefined} Its templates or undefined.
+   */
+  classTemplatesOf(classDecl) {
+    var _leadingComments;
+    let leadingComments = classDecl.leadingComments;
+    if (!leadingComments) {
+      const exportNamed = this.findParentOfType(classDecl, 'ExportNamedDeclaration');
+      leadingComments = exportNamed == null ? void 0 : exportNamed.leadingComments;
+      if (!leadingComments) {
+        const exportDefault = this.findParentOfType(classDecl, 'ExportDefaultDeclaration');
+        leadingComments = exportDefault == null ? void 0 : exportDefault.leadingComments;
+      }
+      if (!leadingComments && classDecl.type === 'ClassExpression') {
+        // `/** @template K */ const Box = class {...}`: the comment lives on
+        // the declaration, mirroring function-expression handling.
+        const varDecl = this.findParentOfType(classDecl, 'VariableDeclaration');
+        leadingComments = varDecl == null ? void 0 : varDecl.leadingComments;
+      }
+    }
+    if (!((_leadingComments = leadingComments) != null && _leadingComments.length)) {
+      return;
+    }
+    const lastComment = leadingComments[leadingComments.length - 1];
+    if (lastComment.type !== 'CommentBlock') {
+      return;
+    }
+    return parseJSDocTemplates(lastComment.value);
+  }
+  /**
+   * Reads the `@template` bindings off one enclosing function: its own
+   * leading comment, resolving the same `export`/declarator wrappers the
+   * node's own JSDoc lookup uses.
+   * @param {Node} fnNode - The enclosing function-like node.
+   * @returns {Record<string, any>|undefined} Its templates or undefined.
+   */
+  functionTemplatesOf(fnNode) {
+    var _leadingComments2;
+    let leadingComments;
+    if (fnNode.type === 'FunctionDeclaration') {
+      var _fnNode$leadingCommen, _this$findParentOfTyp;
+      leadingComments = (_fnNode$leadingCommen = fnNode.leadingComments) != null ? _fnNode$leadingCommen : (_this$findParentOfTyp = this.findParentOfType(fnNode, 'ExportNamedDeclaration')) == null ? void 0 : _this$findParentOfTyp.leadingComments;
+    } else if (fnNode.type === 'FunctionExpression') {
+      var _this$getLeadingComme;
+      leadingComments = (_this$getLeadingComme = this.getLeadingCommentsNodeForFunctionExpression(fnNode)) == null ? void 0 : _this$getLeadingComme.leadingComments;
+    } else if (fnNode.type === 'ArrowFunctionExpression') {
+      var _this$getLeadingComme2;
+      leadingComments = (_this$getLeadingComme2 = this.getLeadingCommentsNodeForArrowFunctionExpression(fnNode)) == null ? void 0 : _this$getLeadingComme2.leadingComments;
+    } else {
+      // ObjectMethod, ClassMethod, ClassPrivateMethod: docs sit on the node.
+      leadingComments = fnNode.leadingComments;
+    }
+    if (!((_leadingComments2 = leadingComments) != null && _leadingComments2.length)) {
+      return;
+    }
+    const lastComment = leadingComments[leadingComments.length - 1];
+    if (lastComment.type !== 'CommentBlock') {
+      return;
+    }
+    return parseJSDocTemplates(lastComment.value);
+  }
   /**
    * Retrieves the name of a parameter from a Babel AST node.
    *
@@ -5064,7 +5176,7 @@ class Asserter extends Stringifier {
       return this.emitDefaultChecks(node, inferred, true);
     }
     const {
-      templates,
+      templates: ownTemplates,
       params
     } = jsdoc;
     if (!params) {
@@ -5074,6 +5186,11 @@ class Asserter extends Stringifier {
       stat.unchecked++;
       return '';
     }
+    // Lexically enclosing `@template`s (classes and functions) scope over
+    // this node: merge them under method-local templates so `K` in
+    // `@param {K}` resolves jointly. Inner scopes shadow outer ones.
+    const scopeTemplates = this.getScopeTemplates(node);
+    const templates = scopeTemplates ? _extends({}, scopeTemplates, ownTemplates) : ownTemplates;
     stat.checked++;
     const {
       spaces
@@ -6071,6 +6188,11 @@ function toSourceBabelTS(node) {
           argument: keyofArg
         };
       }
+      if (node.operator === 'unique') {
+        // `unique symbol` is a symbol at runtime; uniqueness refers to a
+        // specific declaration which we cannot track here.
+        return toSourceBabelTS(node.typeAnnotation);
+      }
       console.warn('unimplemented TSTypeOperator', node.operator);
       return 'any';
     case 'TSQualifiedName':

package/package.json

@@ -4,7 +4,7 @@
     "ts2js": "ts2js.js"
   },
   "name": "@runtime-type-inspector/transpiler",
-  "version": "5.0.4",
+  "version": "5.0.5",
   "description": "Validating JSDoc types at runtime for high-quality types - Trust is good, control is better.",
   "main": "index.cjs",
   "module": "index.mjs",
@@ -22,7 +22,7 @@
   "homepage": "https://github.com/kungfooman/RuntimeTypeInspector.js#readme",
   "dependencies": {
     "@babel/parser": "^7.23.0",
-    "@runtime-type-inspector/runtime": "^5.0.4",
+    "@runtime-type-inspector/runtime": "^5.0.5",
     "typescript": "^5.1.6"
   },
   "files": [