typedoc 0.22.13 → 0.22.16

package/dist/lib/models/types.js

@@ -1,15 +1,27 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.UnknownType = exports.UnionType = exports.TypeOperatorType = exports.NamedTupleMember = exports.TupleType = exports.TemplateLiteralType = exports.RestType = exports.ReflectionType = exports.ReferenceType = exports.QueryType = exports.PredicateType = exports.OptionalType = exports.MappedType = exports.LiteralType = exports.IntrinsicType = exports.IntersectionType = exports.InferredType = exports.IndexedAccessType = exports.ConditionalType = exports.ArrayType = exports.makeRecursiveVisitor = exports.Type = void 0;
+exports.UnknownType = exports.UnionType = exports.TypeOperatorType = exports.NamedTupleMember = exports.TupleType = exports.TemplateLiteralType = exports.RestType = exports.ReflectionType = exports.ReferenceType = exports.QueryType = exports.PredicateType = exports.OptionalType = exports.MappedType = exports.LiteralType = exports.IntrinsicType = exports.IntersectionType = exports.InferredType = exports.IndexedAccessType = exports.ConditionalType = exports.ArrayType = exports.TypeContext = exports.makeRecursiveVisitor = exports.Type = void 0;
 const abstract_1 = require("./reflections/abstract");
 /**
  * Base class of all type definitions.
  */
 class Type {
+    /**
+     * Return a string representation of this type.
+     */
+    toString() {
+        return this.stringify(exports.TypeContext.none);
+    }
     visit(visitor) {
         var _a;
         return (_a = visitor[this.type]) === null || _a === void 0 ? void 0 : _a.call(visitor, this);
     }
+    stringify(context) {
+        if (this.needsParenthesis(context)) {
+            return `(${this.getTypeString()})`;
+        }
+        return this.getTypeString();
+    }
 }
 exports.Type = Type;
 function makeRecursiveVisitor(visitor) {
@@ -46,10 +58,13 @@ function makeRecursiveVisitor(visitor) {
             type.objectType.visit(recursiveVisitor);
         },
         inferred(type) {
-            var _a;
+            var _a, _b;
             (_a = visitor.inferred) === null || _a === void 0 ? void 0 : _a.call(visitor, type);
+            (_b = type.constraint) === null || _b === void 0 ? void 0 : _b.visit(recursiveVisitor);
         },
         intersection(type) {
+            var _a;
+            (_a = visitor.intersection) === null || _a === void 0 ? void 0 : _a.call(visitor, type);
             type.types.forEach((t) => t.visit(recursiveVisitor));
         },
         intrinsic(type) {
@@ -121,40 +136,36 @@ function makeRecursiveVisitor(visitor) {
     return recursiveVisitor;
 }
 exports.makeRecursiveVisitor = makeRecursiveVisitor;
-// A lower binding power means that if contained within a type
-// with a higher binding power the type must be parenthesized.
-// 999 = never have parenthesis
-// -1 = always have parenthesis
-const BINDING_POWERS = {
-    array: 999,
-    conditional: 70,
-    conditionalCheckType: 150,
-    indexedAccess: 999,
-    inferred: 999,
-    intersection: 120,
-    intrinsic: 999,
-    literal: 999,
-    mapped: 999,
-    optional: 999,
-    predicate: 999,
-    query: 900,
-    reference: 999,
-    reflection: 999,
-    rest: 999,
-    "template-literal": 999,
-    tuple: 999,
-    "named-tuple-member": 999,
-    typeOperator: 900,
-    union: 100,
-    // We should always wrap these in parenthesis since we don't know what they contain.
-    unknown: -1,
+/**
+ * Enumeration that can be used when traversing types to track the location of recursion.
+ * Used by TypeDoc internally to track when to output parenthesis when rendering.
+ * @enum
+ */
+exports.TypeContext = {
+    none: "none",
+    templateLiteralElement: "templateLiteralElement",
+    arrayElement: "arrayElement",
+    indexedAccessElement: "indexedAccessElement",
+    conditionalCheck: "conditionalCheck",
+    conditionalExtends: "conditionalExtends",
+    conditionalTrue: "conditionalTrue",
+    conditionalFalse: "conditionalFalse",
+    indexedIndex: "indexedIndex",
+    indexedObject: "indexedObject",
+    inferredConstraint: "inferredConstraint",
+    intersectionElement: "intersectionElement",
+    mappedName: "mappedName",
+    mappedParameter: "mappedParameter",
+    mappedTemplate: "mappedTemplate",
+    optionalElement: "optionalElement",
+    predicateTarget: "predicateTarget",
+    queryTypeTarget: "queryTypeTarget",
+    typeOperatorTarget: "typeOperatorTarget",
+    referenceTypeArgument: "referenceTypeArgument",
+    restElement: "restElement",
+    tupleElement: "tupleElement",
+    unionElement: "unionElement", // here | 1
 };
-function wrap(type, bp) {
-    if (BINDING_POWERS[type.type] < bp) {
-        return `(${type})`;
-    }
-    return type.toString();
-}
 /**
  * Represents an array type.
  *
@@ -168,8 +179,11 @@ class ArrayType extends Type {
         this.type = "array";
         this.elementType = elementType;
     }
-    toString() {
-        return wrap(this.elementType, BINDING_POWERS.array) + "[]";
+    getTypeString() {
+        return this.elementType.stringify(exports.TypeContext.arrayElement) + "[]";
+    }
+    needsParenthesis() {
+        return false;
     }
 }
 exports.ArrayType = ArrayType;
@@ -189,17 +203,45 @@ class ConditionalType extends Type {
         this.falseType = falseType;
         this.type = "conditional";
     }
-    toString() {
+    getTypeString() {
         return [
-            wrap(this.checkType, BINDING_POWERS.conditionalCheckType),
+            this.checkType.stringify(exports.TypeContext.conditionalCheck),
             "extends",
-            this.extendsType,
+            this.extendsType.stringify(exports.TypeContext.conditionalExtends),
             "?",
-            this.trueType,
+            this.trueType.stringify(exports.TypeContext.conditionalTrue),
             ":",
-            this.falseType, // no need to wrap
+            this.falseType.stringify(exports.TypeContext.conditionalFalse),
         ].join(" ");
     }
+    needsParenthesis(context) {
+        const map = {
+            none: false,
+            templateLiteralElement: false,
+            arrayElement: true,
+            indexedAccessElement: false,
+            conditionalCheck: true,
+            conditionalExtends: true,
+            conditionalTrue: false,
+            conditionalFalse: false,
+            indexedIndex: false,
+            indexedObject: true,
+            inferredConstraint: true,
+            intersectionElement: true,
+            mappedName: false,
+            mappedParameter: false,
+            mappedTemplate: false,
+            optionalElement: true,
+            predicateTarget: false,
+            queryTypeTarget: false,
+            typeOperatorTarget: true,
+            referenceTypeArgument: false,
+            restElement: true,
+            tupleElement: false,
+            unionElement: true,
+        };
+        return map[context];
+    }
 }
 exports.ConditionalType = ConditionalType;
 /**
@@ -212,8 +254,16 @@ class IndexedAccessType extends Type {
         this.indexType = indexType;
         this.type = "indexedAccess";
     }
-    toString() {
-        return `${this.objectType}[${this.indexType}]`;
+    getTypeString() {
+        return [
+            this.objectType.stringify(exports.TypeContext.indexedObject),
+            "[",
+            this.indexType.stringify(exports.TypeContext.indexedIndex),
+            "]",
+        ].join("");
+    }
+    needsParenthesis() {
+        return false;
     }
 }
 exports.IndexedAccessType = IndexedAccessType;
@@ -225,14 +275,46 @@ exports.IndexedAccessType = IndexedAccessType;
  * ```
  */
 class InferredType extends Type {
-    constructor(name) {
+    constructor(name, constraint) {
         super();
         this.name = name;
+        this.constraint = constraint;
         this.type = "inferred";
     }
-    toString() {
+    getTypeString() {
+        if (this.constraint) {
+            return `infer ${this.name} extends ${this.constraint.stringify(exports.TypeContext.inferredConstraint)}`;
+        }
         return `infer ${this.name}`;
     }
+    needsParenthesis(context) {
+        const map = {
+            none: false,
+            templateLiteralElement: false,
+            arrayElement: true,
+            indexedAccessElement: false,
+            conditionalCheck: false,
+            conditionalExtends: false,
+            conditionalTrue: false,
+            conditionalFalse: false,
+            indexedIndex: false,
+            indexedObject: true,
+            inferredConstraint: false,
+            intersectionElement: false,
+            mappedName: false,
+            mappedParameter: false,
+            mappedTemplate: false,
+            optionalElement: true,
+            predicateTarget: false,
+            queryTypeTarget: false,
+            typeOperatorTarget: false,
+            referenceTypeArgument: false,
+            restElement: true,
+            tupleElement: false,
+            unionElement: false,
+        };
+        return map[context];
+    }
 }
 exports.InferredType = InferredType;
 /**
@@ -248,11 +330,39 @@ class IntersectionType extends Type {
         this.types = types;
         this.type = "intersection";
     }
-    toString() {
+    getTypeString() {
         return this.types
-            .map((t) => wrap(t, BINDING_POWERS.intersection))
+            .map((t) => t.stringify(exports.TypeContext.intersectionElement))
             .join(" & ");
     }
+    needsParenthesis(context) {
+        const map = {
+            none: false,
+            templateLiteralElement: false,
+            arrayElement: true,
+            indexedAccessElement: false,
+            conditionalCheck: true,
+            conditionalExtends: false,
+            conditionalTrue: false,
+            conditionalFalse: false,
+            indexedIndex: false,
+            indexedObject: true,
+            inferredConstraint: false,
+            intersectionElement: false,
+            mappedName: false,
+            mappedParameter: false,
+            mappedTemplate: false,
+            optionalElement: true,
+            predicateTarget: false,
+            queryTypeTarget: false,
+            typeOperatorTarget: true,
+            referenceTypeArgument: false,
+            restElement: true,
+            tupleElement: false,
+            unionElement: false,
+        };
+        return map[context];
+    }
 }
 exports.IntersectionType = IntersectionType;
 /**
@@ -268,9 +378,12 @@ class IntrinsicType extends Type {
         this.name = name;
         this.type = "intrinsic";
     }
-    toString() {
+    getTypeString() {
         return this.name;
     }
+    needsParenthesis() {
+        return false;
+    }
 }
 exports.IntrinsicType = IntrinsicType;
 /**
@@ -290,19 +403,22 @@ class LiteralType extends Type {
     /**
      * Return a string representation of this type.
      */
-    toString() {
+    getTypeString() {
         if (typeof this.value === "bigint") {
             return this.value.toString() + "n";
         }
         return JSON.stringify(this.value);
     }
+    needsParenthesis() {
+        return false;
+    }
 }
 exports.LiteralType = LiteralType;
 /**
  * Represents a mapped type.
  *
  * ```ts
- * { -readonly [K in keyof U & string as `a${K}`]?: Foo }
+ * { -readonly [K in Parameter as Name]?: Template }
  * ```
  */
 class MappedType extends Type {
@@ -316,7 +432,7 @@ class MappedType extends Type {
         this.nameType = nameType;
         this.type = "mapped";
     }
-    toString() {
+    getTypeString() {
         var _a, _b;
         const read = {
             "+": "readonly ",
@@ -328,8 +444,22 @@ class MappedType extends Type {
             "-": "-?",
             "": "",
         }[(_b = this.optionalModifier) !== null && _b !== void 0 ? _b : ""];
-        const name = this.nameType ? ` as ${this.nameType}` : "";
-        return `{ ${read}[${this.parameter} in ${this.parameterType}${name}]${opt}: ${this.templateType} }`;
+        const parts = [
+            "{ ",
+            read,
+            "[",
+            this.parameter,
+            " in ",
+            this.parameterType.stringify(exports.TypeContext.mappedParameter),
+        ];
+        if (this.nameType) {
+            parts.push(" as ", this.nameType.stringify(exports.TypeContext.mappedName));
+        }
+        parts.push("]", opt, ": ", this.templateType.stringify(exports.TypeContext.mappedTemplate), " }");
+        return parts.join("");
+    }
+    needsParenthesis() {
+        return false;
     }
 }
 exports.MappedType = MappedType;
@@ -346,8 +476,11 @@ class OptionalType extends Type {
         this.type = "optional";
         this.elementType = elementType;
     }
-    toString() {
-        return wrap(this.elementType, BINDING_POWERS.optional) + "?";
+    getTypeString() {
+        return this.elementType.stringify(exports.TypeContext.optionalElement) + "?";
+    }
+    needsParenthesis() {
+        return false;
     }
 }
 exports.OptionalType = OptionalType;
@@ -373,13 +506,16 @@ class PredicateType extends Type {
     /**
      * Return a string representation of this type.
      */
-    toString() {
+    getTypeString() {
         const out = this.asserts ? ["asserts", this.name] : [this.name];
         if (this.targetType) {
-            out.push("is", this.targetType.toString());
+            out.push("is", this.targetType.stringify(exports.TypeContext.predicateTarget));
         }
         return out.join(" ");
     }
+    needsParenthesis() {
+        return false;
+    }
 }
 exports.PredicateType = PredicateType;
 /**
@@ -395,8 +531,17 @@ class QueryType extends Type {
         this.type = "query";
         this.queryType = reference;
     }
-    toString() {
-        return `typeof ${this.queryType.toString()}`;
+    getTypeString() {
+        return `typeof ${this.queryType.stringify(exports.TypeContext.queryTypeTarget)}`;
+    }
+    /**
+     * @privateRemarks
+     * An argument could be made that this ought to return true for indexedObject
+     * since precedence is different than on the value side... if someone really cares
+     * they can easily use a custom theme to change this.
+     */
+    needsParenthesis() {
+        return false;
     }
 }
 exports.QueryType = QueryType;
@@ -477,18 +622,21 @@ class ReferenceType extends Type {
     static createBrokenReference(name, project) {
         return new ReferenceType(name, -1, project);
     }
-    toString() {
+    getTypeString() {
         const name = this.reflection ? this.reflection.name : this.name;
         let typeArgs = "";
         if (this.typeArguments && this.typeArguments.length > 0) {
             typeArgs += "<";
             typeArgs += this.typeArguments
-                .map((arg) => arg.toString())
+                .map((arg) => arg.stringify(exports.TypeContext.referenceTypeArgument))
                 .join(", ");
             typeArgs += ">";
         }
         return name + typeArgs;
     }
+    needsParenthesis() {
+        return false;
+    }
 }
 exports.ReferenceType = ReferenceType;
 /**
@@ -507,7 +655,10 @@ class ReflectionType extends Type {
         this.type = "reflection";
         this.declaration = declaration;
     }
-    toString() {
+    // This really ought to do better, but I'm putting off investing effort here until
+    // I'm fully convinced that keeping this is a good idea. Currently, I'd much rather
+    // change object types to not create reflections.
+    getTypeString() {
         if (!this.declaration.children && this.declaration.signatures) {
             return "Function";
         }
@@ -515,6 +666,9 @@ class ReflectionType extends Type {
             return "Object";
         }
     }
+    needsParenthesis() {
+        return false;
+    }
 }
 exports.ReflectionType = ReflectionType;
 /**
@@ -530,8 +684,11 @@ class RestType extends Type {
         this.elementType = elementType;
         this.type = "rest";
     }
-    toString() {
-        return `...${wrap(this.elementType, BINDING_POWERS.rest)}`;
+    getTypeString() {
+        return `...${this.elementType.stringify(exports.TypeContext.restElement)}`;
+    }
+    needsParenthesis() {
+        return false;
     }
 }
 exports.RestType = RestType;
@@ -548,16 +705,22 @@ class TemplateLiteralType extends Type {
         this.tail = tail;
         this.type = "template-literal";
     }
-    toString() {
+    getTypeString() {
         return [
             "`",
             this.head,
             ...this.tail.map(([type, text]) => {
-                return "${" + type + "}" + text;
+                return ("${" +
+                    type.stringify(exports.TypeContext.templateLiteralElement) +
+                    "}" +
+                    text);
             }),
             "`",
         ].join("");
     }
+    needsParenthesis() {
+        return false;
+    }
 }
 exports.TemplateLiteralType = TemplateLiteralType;
 /**
@@ -573,8 +736,15 @@ class TupleType extends Type {
         this.type = "tuple";
         this.elements = elements;
     }
-    toString() {
-        return "[" + this.elements.join(", ") + "]";
+    getTypeString() {
+        return ("[" +
+            this.elements
+                .map((t) => t.stringify(exports.TypeContext.tupleElement))
+                .join(", ") +
+            "]");
+    }
+    needsParenthesis() {
+        return false;
     }
 }
 exports.TupleType = TupleType;
@@ -596,8 +766,11 @@ class NamedTupleMember extends Type {
     /**
      * Return a string representation of this type.
      */
-    toString() {
-        return `${this.name}${this.isOptional ? "?" : ""}: ${this.element}`;
+    getTypeString() {
+        return `${this.name}${this.isOptional ? "?" : ""}: ${this.element.stringify(exports.TypeContext.tupleElement)}`;
+    }
+    needsParenthesis() {
+        return false;
     }
 }
 exports.NamedTupleMember = NamedTupleMember;
@@ -616,8 +789,36 @@ class TypeOperatorType extends Type {
         this.operator = operator;
         this.type = "typeOperator";
     }
-    toString() {
-        return `${this.operator} ${this.target.toString()}`;
+    getTypeString() {
+        return `${this.operator} ${this.target.stringify(exports.TypeContext.typeOperatorTarget)}`;
+    }
+    needsParenthesis(context) {
+        const map = {
+            none: false,
+            templateLiteralElement: false,
+            arrayElement: true,
+            indexedAccessElement: false,
+            conditionalCheck: false,
+            conditionalExtends: false,
+            conditionalTrue: false,
+            conditionalFalse: false,
+            indexedIndex: false,
+            indexedObject: true,
+            inferredConstraint: false,
+            intersectionElement: false,
+            mappedName: false,
+            mappedParameter: false,
+            mappedTemplate: false,
+            optionalElement: true,
+            predicateTarget: false,
+            queryTypeTarget: false,
+            typeOperatorTarget: false,
+            referenceTypeArgument: false,
+            restElement: false,
+            tupleElement: false,
+            unionElement: false,
+        };
+        return map[context];
     }
 }
 exports.TypeOperatorType = TypeOperatorType;
@@ -635,12 +836,53 @@ class UnionType extends Type {
         this.type = "union";
         this.normalize();
     }
-    toString() {
-        return this.types.map((t) => wrap(t, BINDING_POWERS.union)).join(" | ");
+    getTypeString() {
+        return this.types
+            .map((t) => t.stringify(exports.TypeContext.unionElement))
+            .join(" | ");
+    }
+    needsParenthesis(context) {
+        const map = {
+            none: false,
+            templateLiteralElement: false,
+            arrayElement: true,
+            indexedAccessElement: false,
+            conditionalCheck: true,
+            conditionalExtends: false,
+            conditionalTrue: false,
+            conditionalFalse: false,
+            indexedIndex: false,
+            indexedObject: true,
+            inferredConstraint: false,
+            intersectionElement: true,
+            mappedName: false,
+            mappedParameter: false,
+            mappedTemplate: false,
+            optionalElement: true,
+            predicateTarget: false,
+            queryTypeTarget: false,
+            typeOperatorTarget: true,
+            referenceTypeArgument: false,
+            restElement: false,
+            tupleElement: false,
+            unionElement: false,
+        };
+        return map[context];
     }
     normalize() {
-        const trueIndex = this.types.findIndex((t) => t instanceof LiteralType && t.value === true);
-        const falseIndex = this.types.findIndex((t) => t instanceof LiteralType && t.value === false);
+        let trueIndex = -1;
+        let falseIndex = -1;
+        for (let i = 0; i < this.types.length && (trueIndex === -1 || falseIndex === -1); i++) {
+            const t = this.types[i];
+            if (t instanceof LiteralType) {
+                if (t.value === true) {
+                    trueIndex = i;
+                }
+                if (t.value === false) {
+                    falseIndex = i;
+                }
+            }
+        }
         if (trueIndex !== -1 && falseIndex !== -1) {
             this.types.splice(Math.max(trueIndex, falseIndex), 1);
             this.types.splice(Math.min(trueIndex, falseIndex), 1, new IntrinsicType("boolean"));
@@ -657,8 +899,15 @@ class UnknownType extends Type {
         this.type = "unknown";
         this.name = name;
     }
-    toString() {
+    getTypeString() {
         return this.name;
     }
+    /**
+     * Always returns true if not at the root level, we have no idea what's in here, so wrap it in parenthesis
+     * to be extra safe.
+     */
+    needsParenthesis(context) {
+        return context !== exports.TypeContext.none;
+    }
 }
 exports.UnknownType = UnknownType;