typedoc 0.23.26 → 0.24.0-beta.1

package/dist/lib/models/reflections/reference.d.ts

@@ -1,6 +1,6 @@
-import { Reflection } from "./abstract";
 import { DeclarationReflection } from "./declaration";
-import type { Serializer, JSONOutput } from "../../serialization";
+import type { Serializer, JSONOutput, Deserializer } from "../../serialization";
+import type { Reflection } from "./abstract";
 /**
  * Describes a reflection which does not exist at this location, but is referenced. Used for imported reflections.
  *
@@ -15,17 +15,13 @@ import type { Serializer, JSONOutput } from "../../serialization";
  * ```
  */
 export declare class ReferenceReflection extends DeclarationReflection {
+    readonly variant = "reference";
     private _target;
-    private _project?;
     /**
      * Creates a reference reflection. Should only be used within the factory function.
-     * @param name
-     * @param state
-     * @param parent
-     *
      * @internal
      */
-    constructor(name: string, state: ReferenceReflection["_target"], parent?: Reflection);
+    constructor(name: string, reflection: Reflection, parent?: Reflection);
     /**
      * Tries to get the reflection that is referenced. This may be another reference reflection.
      * To fully resolve any references, use {@link tryGetTargetReflectionDeep}.
@@ -47,6 +43,6 @@ export declare class ReferenceReflection extends DeclarationReflection {
      */
     getTargetReflectionDeep(): Reflection;
     getChildByName(arg: string | string[]): Reflection | undefined;
-    private _ensureProject;
     toObject(serializer: Serializer): JSONOutput.ReferenceReflection;
+    fromObject(de: Deserializer, obj: JSONOutput.ReferenceReflection): void;
 }

package/dist/lib/models/reflections/reference.js

@@ -1,7 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ReferenceReflection = void 0;
-const abstract_1 = require("./abstract");
 const declaration_1 = require("./declaration");
 const kind_1 = require("./kind");
 /**
@@ -20,29 +19,19 @@ const kind_1 = require("./kind");
 class ReferenceReflection extends declaration_1.DeclarationReflection {
     /**
      * Creates a reference reflection. Should only be used within the factory function.
-     * @param name
-     * @param state
-     * @param parent
-     *
      * @internal
      */
-    constructor(name, state, parent) {
+    constructor(name, reflection, parent) {
         super(name, kind_1.ReflectionKind.Reference, parent);
-        this._target = state;
+        this.variant = "reference";
+        this._target = reflection.id;
     }
     /**
      * Tries to get the reflection that is referenced. This may be another reference reflection.
      * To fully resolve any references, use {@link tryGetTargetReflectionDeep}.
      */
     tryGetTargetReflection() {
-        this._ensureProject();
-        if (this._target instanceof abstract_1.Reflection) {
-            return this._target;
-        }
-        const target = this._project.getReflectionFromSymbol(this._target);
-        if (target)
-            this._target = target;
-        return target;
+        return this.project.getReflectionById(this._target);
     }
     /**
      * Tries to get the reflection that is referenced, this will fully resolve references.
@@ -60,7 +49,6 @@ class ReferenceReflection extends declaration_1.DeclarationReflection {
      * To fully resolve any references, use {@link getTargetReflectionDeep}.
      */
     getTargetReflection() {
-        this._ensureProject();
         const target = this.tryGetTargetReflection();
         if (!target) {
             throw new Error("Reference was unresolved.");
@@ -81,24 +69,20 @@ class ReferenceReflection extends declaration_1.DeclarationReflection {
     getChildByName(arg) {
         return this.getTargetReflection().getChildByName(arg);
     }
-    _ensureProject() {
-        if (this._project) {
-            return;
-        }
-        let project = this.parent;
-        while (project && !project.isProject()) {
-            project = project.parent;
-        }
-        this._project = project;
-        if (!this._project) {
-            throw new Error("Reference reflection has no project and is unable to resolve.");
-        }
-    }
     toObject(serializer) {
         return {
             ...super.toObject(serializer),
+            variant: this.variant,
             target: this.tryGetTargetReflection()?.id ?? -1,
         };
     }
+    fromObject(de, obj) {
+        super.fromObject(de, obj);
+        de.defer((project) => {
+            this._target =
+                project.getReflectionById(de.oldIdToNewId[obj.target] ?? -1)
+                    ?.id ?? -1;
+        });
+    }
 }
 exports.ReferenceReflection = ReferenceReflection;

package/dist/lib/models/reflections/signature.d.ts

@@ -4,11 +4,17 @@ import type { ParameterReflection } from "./parameter";
 import type { TypeParameterReflection } from "./type-parameter";
 import type { DeclarationReflection } from "./declaration";
 import type { ReflectionKind } from "./kind";
-import type { Serializer, JSONOutput } from "../../serialization";
+import type { Serializer, JSONOutput, Deserializer } from "../../serialization";
+import { SourceReference } from "../sources/file";
 export declare class SignatureReflection extends Reflection {
+    readonly variant = "signature";
     constructor(name: string, kind: SignatureReflection["kind"], parent: DeclarationReflection);
     kind: ReflectionKind.SetSignature | ReflectionKind.GetSignature | ReflectionKind.IndexSignature | ReflectionKind.CallSignature | ReflectionKind.ConstructorSignature;
     parent: DeclarationReflection;
+    /**
+     * A list of all source files that contributed to this reflection.
+     */
+    sources?: SourceReference[];
     parameters?: ParameterReflection[];
     typeParameters?: TypeParameterReflection[];
     type?: SomeType;
@@ -44,4 +50,5 @@ export declare class SignatureReflection extends Reflection {
      */
     toString(): string;
     toObject(serializer: Serializer): JSONOutput.SignatureReflection;
+    fromObject(de: Deserializer, obj: JSONOutput.SignatureReflection): void;
 }

package/dist/lib/models/reflections/signature.js

@@ -3,9 +3,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SignatureReflection = void 0;
 const types_1 = require("../types");
 const abstract_1 = require("./abstract");
+const file_1 = require("../sources/file");
 class SignatureReflection extends abstract_1.Reflection {
     constructor(name, kind, parent) {
         super(name, kind, parent);
+        this.variant = "signature";
     }
     /**
      * Traverse all potential child reflections of this reflection.
@@ -50,6 +52,8 @@ class SignatureReflection extends abstract_1.Reflection {
     toObject(serializer) {
         return {
             ...super.toObject(serializer),
+            variant: this.variant,
+            sources: serializer.toObjectsOptional(this.sources),
             typeParameter: serializer.toObjectsOptional(this.typeParameters),
             parameters: serializer.toObjectsOptional(this.parameters),
             type: serializer.toObject(this.type),
@@ -58,5 +62,15 @@ class SignatureReflection extends abstract_1.Reflection {
             implementationOf: serializer.toObject(this.implementationOf),
         };
     }
+    fromObject(de, obj) {
+        super.fromObject(de, obj);
+        this.sources = de.reviveMany(obj.sources, (t) => new file_1.SourceReference(t.fileName, t.line, t.character));
+        this.typeParameters = de.reviveMany(obj.typeParameter, (t) => de.constructReflection(t));
+        this.parameters = de.reviveMany(obj.parameters, (t) => de.constructReflection(t));
+        this.type = de.reviveType(obj.type);
+        this.overwrites = de.reviveType(obj.overwrites);
+        this.inheritedFrom = de.reviveType(obj.inheritedFrom);
+        this.implementationOf = de.reviveType(obj.implementationOf);
+    }
 }
 exports.SignatureReflection = SignatureReflection;

package/dist/lib/models/reflections/type-parameter.d.ts

@@ -1,7 +1,8 @@
 import type { SomeType } from "../types";
 import { Reflection } from "./abstract";
 import type { DeclarationReflection } from "./declaration";
-import type { Serializer, JSONOutput } from "../../serialization";
+import type { Serializer, JSONOutput, Deserializer } from "../../serialization";
+import type { SignatureReflection } from "./signature";
 /**
  * Modifier flags for type parameters, added in TS 4.7
  * @enum
@@ -11,12 +12,14 @@ export declare const VarianceModifier: {
     readonly out: "out";
     readonly inOut: "in out";
 };
-export type VarianceModifier = (typeof VarianceModifier)[keyof typeof VarianceModifier];
+export type VarianceModifier = typeof VarianceModifier[keyof typeof VarianceModifier];
 export declare class TypeParameterReflection extends Reflection {
-    parent?: DeclarationReflection;
+    readonly variant = "typeParam";
+    parent?: DeclarationReflection | SignatureReflection;
     type?: SomeType;
     default?: SomeType;
     varianceModifier?: VarianceModifier;
-    constructor(name: string, constraint: SomeType | undefined, defaultType: SomeType | undefined, parent: Reflection, varianceModifier: VarianceModifier | undefined);
+    constructor(name: string, parent: Reflection, varianceModifier: VarianceModifier | undefined);
     toObject(serializer: Serializer): JSONOutput.TypeParameterReflection;
+    fromObject(de: Deserializer, obj: JSONOutput.TypeParameterReflection): void;
 }

package/dist/lib/models/reflections/type-parameter.js

@@ -13,19 +13,25 @@ exports.VarianceModifier = {
     inOut: "in out",
 };
 class TypeParameterReflection extends abstract_1.Reflection {
-    constructor(name, constraint, defaultType, parent, varianceModifier) {
+    constructor(name, parent, varianceModifier) {
         super(name, kind_1.ReflectionKind.TypeParameter, parent);
-        this.type = constraint;
-        this.default = defaultType;
+        this.variant = "typeParam";
         this.varianceModifier = varianceModifier;
     }
     toObject(serializer) {
         return {
             ...super.toObject(serializer),
+            variant: this.variant,
             type: serializer.toObject(this.type),
             default: serializer.toObject(this.default),
             varianceModifier: this.varianceModifier,
         };
     }
+    fromObject(de, obj) {
+        super.fromObject(de, obj);
+        this.type = de.reviveType(obj.type);
+        this.default = de.reviveType(obj.default);
+        this.varianceModifier = obj.varianceModifier;
+    }
 }
 exports.TypeParameterReflection = TypeParameterReflection;

package/dist/lib/models/reflections/variant.d.ts

@@ -0,0 +1,18 @@
+import type { DeclarationReflection } from "./declaration";
+import type { ParameterReflection } from "./parameter";
+import type { ProjectReflection } from "./project";
+import type { ReferenceReflection } from "./reference";
+import type { SignatureReflection } from "./signature";
+import type { TypeParameterReflection } from "./type-parameter";
+/**
+ * A map of known {@link Reflection} concrete subclasses.
+ * This is used during deserialization to reconstruct serialized objects.
+ */
+export interface ReflectionVariant {
+    declaration: DeclarationReflection;
+    param: ParameterReflection;
+    project: ProjectReflection;
+    reference: ReferenceReflection;
+    signature: SignatureReflection;
+    typeParam: TypeParameterReflection;
+}

package/dist/lib/models/reflections/variant.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/lib/models/sources/file.d.ts

@@ -1,3 +1,4 @@
+import type { Deserializer } from "../../serialization/deserializer";
 import type { SourceReference as JSONSourceReference } from "../../serialization/schema";
 /**
  * Represents references of reflections to their defining source files.
@@ -27,4 +28,5 @@ export declare class SourceReference {
     url?: string;
     constructor(fileName: string, line: number, character: number);
     toObject(): JSONSourceReference;
+    fromObject(_de: Deserializer, obj: JSONSourceReference): void;
 }

package/dist/lib/models/sources/file.js

@@ -21,5 +21,8 @@ class SourceReference {
             url: this.url,
         };
     }
+    fromObject(_de, obj) {
+        this.url = obj.url;
+    }
 }
 exports.SourceReference = SourceReference;

package/dist/lib/models/types.d.ts

@@ -1,9 +1,10 @@
-import type * as ts from "typescript";
+import * as ts from "typescript";
 import type { Context } from "../converter";
-import { Reflection } from "./reflections/abstract";
+import type { Reflection } from "./reflections/abstract";
 import type { DeclarationReflection } from "./reflections/declaration";
 import type { ProjectReflection } from "./reflections/project";
-import type { Serializer, JSONOutput } from "../serialization";
+import type { Serializer, JSONOutput, Deserializer } from "../serialization";
+import { ReflectionSymbolId } from "./reflections/ReflectionSymbolId";
 import type { DeclarationReference } from "../converter/comments/declarationReference";
 /**
  * Base class of all type definitions.
@@ -24,6 +25,7 @@ export declare abstract class Type {
     visit<T>(visitor: Partial<TypeVisitor<T>>): T | undefined;
     stringify(context: TypeContext): string;
     abstract toObject(serializer: Serializer): JSONOutput.SomeType;
+    fromObject(_de: Deserializer, _obj: JSONOutput.SomeType): void;
     abstract needsParenthesis(context: TypeContext): boolean;
     /**
      * Implementation method for `toString`. `needsParenthesis` will be used to determine if
@@ -46,9 +48,9 @@ export interface TypeKindMap {
     reference: ReferenceType;
     reflection: ReflectionType;
     rest: RestType;
-    "template-literal": TemplateLiteralType;
+    templateLiteral: TemplateLiteralType;
     tuple: TupleType;
-    "named-tuple-member": NamedTupleMember;
+    namedTupleMember: NamedTupleMember;
     typeOperator: TypeOperatorType;
     union: UnionType;
     unknown: UnknownType;
@@ -89,7 +91,7 @@ export declare const TypeContext: {
     readonly tupleElement: "tupleElement";
     readonly unionElement: "unionElement";
 };
-export type TypeContext = (typeof TypeContext)[keyof typeof TypeContext];
+export type TypeContext = typeof TypeContext[keyof typeof TypeContext];
 /**
  * Represents an array type.
  *
@@ -231,8 +233,8 @@ export declare class MappedType extends Type {
  * ```
  */
 export declare class OptionalType extends Type {
-    readonly type = "optional";
     elementType: SomeType;
+    readonly type = "optional";
     constructor(elementType: SomeType);
     protected getTypeString(): string;
     needsParenthesis(): boolean;
@@ -277,9 +279,9 @@ export declare class PredicateType extends Type {
  * ```
  */
 export declare class QueryType extends Type {
-    readonly queryType: ReferenceType;
+    queryType: ReferenceType;
     readonly type = "query";
-    constructor(reference: ReferenceType);
+    constructor(queryType: ReferenceType);
     protected getTypeString(): string;
     /**
      * @privateRemarks
@@ -302,7 +304,7 @@ export declare class ReferenceType extends Type {
     /**
      * The name of the referenced type.
      *
-     * If the symbol cannot be found cause it's not part of the documentation this
+     * If the symbol cannot be found because it's not part of the documentation this
      * can be used to represent the type.
      */
     name: string;
@@ -315,12 +317,14 @@ export declare class ReferenceType extends Type {
      */
     get reflection(): Reflection | undefined;
     /**
-     * Don't use this if at all possible. It will eventually go away since models may not
-     * retain information from the original TS objects to enable documentation generation from
-     * previously generated JSON.
-     * @internal
+     * If not resolved, the symbol id of the reflection, otherwise undefined.
+     */
+    get symbolId(): ReflectionSymbolId | undefined;
+    /**
+     * Checks if this type is a reference type because it uses a name, but is intentionally not pointing
+     * to a reflection. This happens for type parameters and when representing a mapped type.
      */
-    getSymbol(): ts.Symbol | undefined;
+    isIntentionallyBroken(): boolean;
     /**
      * Convert this reference type to a declaration reference used for resolution of external types.
      */
@@ -332,7 +336,6 @@ export declare class ReferenceType extends Type {
     qualifiedName: string;
     /**
      * The package that this type is referencing.
-     * Will only be set for `ReferenceType`s pointing to a symbol within `node_modules`.
      */
     package?: string;
     /**
@@ -343,13 +346,14 @@ export declare class ReferenceType extends Type {
     private _target;
     private _project;
     private constructor();
-    static createResolvedReference(name: string, target: Reflection | number, project: ProjectReflection): ReferenceType;
+    static createResolvedReference(name: string, target: Reflection | number, project: ProjectReflection | null): ReferenceType;
     static createSymbolReference(symbol: ts.Symbol, context: Context, name?: string): ReferenceType;
     /** @internal this is used for type parameters, which don't actually point to something */
     static createBrokenReference(name: string, project: ProjectReflection): ReferenceType;
     protected getTypeString(): string;
     needsParenthesis(): boolean;
     toObject(serializer: Serializer): JSONOutput.ReferenceType;
+    fromObject(de: Deserializer, obj: JSONOutput.ReferenceType): void;
 }
 /**
  * Represents a type which has it's own reflection like literal types.
@@ -362,8 +366,8 @@ export declare class ReferenceType extends Type {
  * ```
  */
 export declare class ReflectionType extends Type {
-    readonly type = "reflection";
     declaration: DeclarationReflection;
+    readonly type = "reflection";
     constructor(declaration: DeclarationReflection);
     protected getTypeString(): "Object" | "Function";
     needsParenthesis(): boolean;
@@ -393,7 +397,7 @@ export declare class RestType extends Type {
 export declare class TemplateLiteralType extends Type {
     head: string;
     tail: [SomeType, string][];
-    readonly type = "template-literal";
+    readonly type = "templateLiteral";
     constructor(head: string, tail: [SomeType, string][]);
     protected getTypeString(): string;
     needsParenthesis(): boolean;
@@ -428,7 +432,7 @@ export declare class NamedTupleMember extends Type {
     name: string;
     isOptional: boolean;
     element: SomeType;
-    readonly type = "named-tuple-member";
+    readonly type = "namedTupleMember";
     constructor(name: string, isOptional: boolean, element: SomeType);
     /**
      * Return a string representation of this type.