typedoc 0.23.26 → 0.24.0-beta.1

package/dist/lib/models/ReflectionCategory.js

@@ -35,5 +35,17 @@ class ReflectionCategory {
                 : undefined,
         };
     }
+    fromObject(de, obj) {
+        if (obj.children) {
+            de.defer((project) => {
+                for (const childId of obj.children || []) {
+                    const child = project.getReflectionById(de.oldIdToNewId[childId] ?? -1);
+                    if (child?.isDeclaration()) {
+                        this.children.push(child);
+                    }
+                }
+            });
+        }
+    }
 }
 exports.ReflectionCategory = ReflectionCategory;

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

@@ -1,6 +1,6 @@
-import type { ReflectionCategory } from "./ReflectionCategory";
+import { ReflectionCategory } from "./ReflectionCategory";
 import type { DeclarationReflection } from ".";
-import type { Serializer, JSONOutput } from "../serialization";
+import type { Serializer, JSONOutput, Deserializer } from "../serialization";
 /**
  * A group of reflections. All reflections in a group are of the same kind.
  *
@@ -32,4 +32,5 @@ export declare class ReflectionGroup {
      */
     allChildrenHaveOwnDocument(): boolean;
     toObject(serializer: Serializer): JSONOutput.ReflectionGroup;
+    fromObject(de: Deserializer, obj: JSONOutput.ReflectionGroup): void;
 }

package/dist/lib/models/ReflectionGroup.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ReflectionGroup = void 0;
+const ReflectionCategory_1 = require("./ReflectionCategory");
 /**
  * A group of reflections. All reflections in a group are of the same kind.
  *
@@ -36,5 +37,24 @@ class ReflectionGroup {
             categories: serializer.toObjectsOptional(this.categories),
         };
     }
+    fromObject(de, obj) {
+        if (obj.categories) {
+            this.categories = obj.categories.map((catObj) => {
+                const cat = new ReflectionCategory_1.ReflectionCategory(catObj.title);
+                de.fromObject(cat, catObj);
+                return cat;
+            });
+        }
+        if (obj.children) {
+            de.defer((project) => {
+                for (const childId of obj.children || []) {
+                    const child = project.getReflectionById(de.oldIdToNewId[childId] ?? -1);
+                    if (child?.isDeclaration()) {
+                        this.children.push(child);
+                    }
+                }
+            });
+        }
+    }
 }
 exports.ReflectionGroup = ReflectionGroup;

package/dist/lib/models/comments/comment.d.ts

@@ -1,5 +1,5 @@
 import type { Reflection } from "../reflections";
-import type { Serializer, JSONOutput } from "../../serialization";
+import type { Serializer, Deserializer, JSONOutput } from "../../serialization";
 export type CommentDisplayPart = {
     kind: "text";
     text: string;
@@ -42,6 +42,7 @@ export declare class CommentTag {
     constructor(tag: `@${string}`, text: CommentDisplayPart[]);
     clone(): CommentTag;
     toObject(): JSONOutput.CommentTag;
+    fromObject(de: Deserializer, obj: JSONOutput.CommentTag): void;
 }
 /**
  * A model that represents a comment.
@@ -55,12 +56,6 @@ export declare class Comment {
      * rendering, but can be useful in tests.
      */
     static combineDisplayParts(parts: readonly CommentDisplayPart[] | undefined): string;
-    /**
-     * Helper function to convert an array of comment display parts into markdown suitable for
-     * passing into Marked. `urlTo` will be used to resolve urls to any reflections linked to with
-     * `@link` tags.
-     */
-    static displayPartsToMarkdown(parts: readonly CommentDisplayPart[], urlTo: (ref: Reflection) => string): string;
     /**
      * Helper utility to clone {@link Comment.summary} or {@link CommentTag.content}
      */
@@ -76,6 +71,10 @@ export declare class Comment {
         text: string;
         target?: string | Reflection | undefined;
     })[];
+    static serializeDisplayParts(parts: CommentDisplayPart[]): JSONOutput.CommentDisplayPart[];
+    /** @hidden no point in showing this signature in api docs */
+    static serializeDisplayParts(parts: CommentDisplayPart[] | undefined): JSONOutput.CommentDisplayPart[] | undefined;
+    static deserializeDisplayParts(de: Deserializer, parts: JSONOutput.CommentDisplayPart[]): CommentDisplayPart[];
     /**
      * The content of the comment which is not associated with a block tag.
      */
@@ -88,6 +87,11 @@ export declare class Comment {
      * All modifier tags present on the comment, e.g. `@alpha`, `@beta`.
      */
     modifierTags: Set<string>;
+    /**
+     * Label associated with this reflection, if any (https://tsdoc.org/pages/tags/label/)
+     * Added by the CommentPlugin during resolution.
+     */
+    label?: string;
     /**
      * Creates a new Comment instance.
      */
@@ -134,4 +138,5 @@ export declare class Comment {
      */
     removeTags(tagName: `@${string}`): void;
     toObject(serializer: Serializer): JSONOutput.Comment;
+    fromObject(de: Deserializer, obj: JSONOutput.Comment): void;
 }

package/dist/lib/models/comments/comment.js

@@ -2,21 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Comment = exports.CommentTag = void 0;
 const utils_1 = require("../../utils");
-function serializeDisplayPart(part) {
-    switch (part.kind) {
-        case "text":
-        case "code":
-            return part;
-        case "inline-tag": {
-            return {
-                ...part,
-                target: typeof part.target === "object"
-                    ? part.target.id
-                    : part.target,
-            };
-        }
-    }
-}
 /**
  * A model that represents a single TypeDoc comment tag.
  *
@@ -41,9 +26,14 @@ class CommentTag {
         return {
             tag: this.tag,
             name: this.name,
-            content: this.content.map(serializeDisplayPart),
+            content: Comment.serializeDisplayParts(this.content),
         };
     }
+    fromObject(de, obj) {
+        // tag already set by Comment.fromObject
+        this.name = obj.name;
+        this.content = Comment.deserializeDisplayParts(de, obj.content);
+    }
 }
 exports.CommentTag = CommentTag;
 /**
@@ -75,60 +65,64 @@ class Comment {
         return result;
     }
     /**
-     * Helper function to convert an array of comment display parts into markdown suitable for
-     * passing into Marked. `urlTo` will be used to resolve urls to any reflections linked to with
-     * `@link` tags.
+     * Helper utility to clone {@link Comment.summary} or {@link CommentTag.content}
      */
-    static displayPartsToMarkdown(parts, urlTo) {
-        const result = [];
-        for (const part of parts) {
+    static cloneDisplayParts(parts) {
+        return parts.map((p) => ({ ...p }));
+    }
+    static serializeDisplayParts(parts) {
+        return parts?.map((part) => {
             switch (part.kind) {
                 case "text":
                 case "code":
-                    result.push(part.text);
-                    break;
-                case "inline-tag":
-                    switch (part.tag) {
-                        case "@label":
-                        case "@inheritdoc": // Shouldn't happen
-                            break; // Not rendered.
-                        case "@link":
-                        case "@linkcode":
-                        case "@linkplain": {
-                            if (part.target) {
-                                const url = typeof part.target === "string"
-                                    ? part.target
-                                    : urlTo(part.target);
-                                const text = part.tag === "@linkcode"
-                                    ? `<code>${part.text}</code>`
-                                    : part.text;
-                                result.push(url
-                                    ? `<a href="${url}">${text}</a>`
-                                    : part.text);
-                            }
-                            else {
-                                result.push(part.text);
-                            }
-                            break;
-                        }
-                        default:
-                            // Hmm... probably want to be able to render these somehow, so custom inline tags can be given
-                            // special rendering rules. Future capability. For now, just render their text.
-                            result.push(`{${part.tag} ${part.text}}`);
-                            break;
+                    return { ...part };
+                case "inline-tag": {
+                    return {
+                        ...part,
+                        target: typeof part.target === "object"
+                            ? part.target.id
+                            : part.target,
+                    };
+                }
+            }
+        });
+    }
+    //Since display parts are plain objects, this lives here
+    static deserializeDisplayParts(de, parts) {
+        const links = [];
+        const result = parts.map((part) => {
+            switch (part.kind) {
+                case "text":
+                case "code":
+                    return { ...part };
+                case "inline-tag": {
+                    if (typeof part.target !== "number") {
+                        // TS isn't quite smart enough here...
+                        return { ...part };
                     }
-                    break;
-                default:
-                    (0, utils_1.assertNever)(part);
+                    else {
+                        const part2 = {
+                            kind: part.kind,
+                            tag: part.tag,
+                            text: part.text,
+                        };
+                        links.push([part.target, part2]);
+                        return part2;
+                    }
+                }
             }
+        });
+        if (links.length) {
+            de.defer((project) => {
+                for (const [oldId, part] of links) {
+                    part.target = project.getReflectionById(de.oldIdToNewId[oldId] ?? -1);
+                    if (!part.target) {
+                        de.logger.warn(`Serialized project contained a link to ${oldId} (${part.text}), which was not a part of the project.`);
+                    }
+                }
+            });
         }
-        return result.join("");
-    }
-    /**
-     * Helper utility to clone {@link Comment.summary} or {@link CommentTag.content}
-     */
-    static cloneDisplayParts(parts) {
-        return parts.map((p) => ({ ...p }));
+        return result;
     }
     /**
      * Creates a new Comment instance.
@@ -145,6 +139,7 @@ class Comment {
         this.summary = summary;
         this.blockTags = blockTags;
         this.modifierTags = modifierTags;
+        extractLabelTag(this);
     }
     /**
      * Create a deep clone of this comment.
@@ -208,12 +203,30 @@ class Comment {
     }
     toObject(serializer) {
         return {
-            summary: this.summary.map(serializeDisplayPart),
+            summary: Comment.serializeDisplayParts(this.summary),
             blockTags: serializer.toObjectsOptional(this.blockTags),
             modifierTags: this.modifierTags.size > 0
                 ? Array.from(this.modifierTags)
                 : undefined,
+            label: this.label,
         };
     }
+    fromObject(de, obj) {
+        this.summary = Comment.deserializeDisplayParts(de, obj.summary);
+        this.blockTags =
+            obj.blockTags?.map((tagObj) => {
+                const tag = new CommentTag(tagObj.tag, []);
+                de.fromObject(tag, tagObj);
+                return tag;
+            }) || [];
+        this.modifierTags = new Set(obj.modifierTags);
+        this.label = obj.label;
+    }
 }
 exports.Comment = Comment;
+function extractLabelTag(comment) {
+    const index = comment.summary.findIndex((part) => part.kind === "inline-tag" && part.tag === "@label");
+    if (index !== -1) {
+        comment.label = comment.summary.splice(index, 1)[0].text;
+    }
+}

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

@@ -0,0 +1,29 @@
+import ts from "typescript";
+import type { JSONOutput, Serializer } from "../../serialization/index";
+/**
+ * See {@link ReflectionSymbolId}
+ */
+export type ReflectionSymbolIdString = string & {
+    readonly __reflectionSymbolId: unique symbol;
+};
+/**
+ * This exists so that TypeDoc can store a unique identifier for a `ts.Symbol` without
+ * keeping a reference to the `ts.Symbol` itself. This identifier should be stable across
+ * runs so long as the symbol is exported from the same file.
+ */
+export declare class ReflectionSymbolId {
+    readonly fileName: string;
+    readonly qualifiedName: string;
+    /**
+     * Note: This is **not** serialized. It exists for sorting by declaration order, but
+     * should not be needed when deserializing from JSON.
+     */
+    pos: number;
+    constructor(symbol: ts.Symbol, declaration?: ts.Declaration);
+    constructor(json: JSONOutput.ReflectionSymbolId);
+    getStableKey(): ReflectionSymbolIdString;
+    toObject(serializer: Serializer): {
+        sourceFileName: string;
+        qualifiedName: string;
+    };
+}

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

@@ -0,0 +1,94 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReflectionSymbolId = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const typescript_1 = __importDefault(require("typescript"));
+const fs_2 = require("../../utils/fs");
+const tsutils_1 = require("../../utils/tsutils");
+const validation_1 = require("../../utils/validation");
+/**
+ * This exists so that TypeDoc can store a unique identifier for a `ts.Symbol` without
+ * keeping a reference to the `ts.Symbol` itself. This identifier should be stable across
+ * runs so long as the symbol is exported from the same file.
+ */
+class ReflectionSymbolId {
+    constructor(symbol, declaration) {
+        if ("name" in symbol) {
+            declaration ?? (declaration = symbol?.declarations?.[0]);
+            this.fileName = declaration?.getSourceFile().fileName ?? "\0";
+            if (symbol.declarations?.some(typescript_1.default.isSourceFile)) {
+                this.qualifiedName = "";
+            }
+            else {
+                this.qualifiedName = (0, tsutils_1.getQualifiedName)(symbol, symbol.name);
+            }
+            this.pos = declaration?.pos ?? Infinity;
+        }
+        else {
+            this.fileName = symbol.sourceFileName;
+            this.qualifiedName = symbol.qualifiedName;
+            this.pos = Infinity;
+        }
+    }
+    getStableKey() {
+        if (Number.isFinite(this.pos)) {
+            return `${this.fileName}\0${this.qualifiedName}\0${this.pos}`;
+        }
+        else {
+            return `${this.fileName}\0${this.qualifiedName}`;
+        }
+    }
+    toObject(serializer) {
+        return {
+            sourceFileName: (0, path_1.isAbsolute)(this.fileName)
+                ? (0, path_1.relative)(serializer.projectRoot, resolveDeclarationMaps(this.fileName))
+                : this.fileName,
+            qualifiedName: this.qualifiedName,
+        };
+    }
+}
+exports.ReflectionSymbolId = ReflectionSymbolId;
+const declarationMapCache = new Map();
+/**
+ * See also getTsSourceFromJsSource in package-manifest.ts.
+ */
+function resolveDeclarationMaps(file) {
+    if (!file.endsWith(".d.ts"))
+        return file;
+    if (declarationMapCache.has(file))
+        return declarationMapCache.get(file);
+    const mapFile = file + ".map";
+    if (!(0, fs_1.existsSync)(mapFile))
+        return file;
+    let sourceMap;
+    try {
+        sourceMap = JSON.parse((0, fs_2.readFile)(mapFile));
+    }
+    catch {
+        return file;
+    }
+    if ((0, validation_1.validate)({
+        file: String,
+        sourceRoot: (0, validation_1.optional)(String),
+        sources: [Array, String],
+    }, sourceMap)) {
+        // There's a pretty large assumption in here that we only have
+        // 1 source file per js file. This is a pretty standard typescript approach,
+        // but people might do interesting things with transpilation that could break this.
+        let source = sourceMap.sources[0];
+        // If we have a sourceRoot, trim any leading slash from the source, and join them
+        // Similar to how it's done at https://github.com/mozilla/source-map/blob/58819f09018d56ef84dc41ba9c93f554e0645169/lib/util.js#L412
+        if (sourceMap.sourceRoot !== undefined) {
+            source = source.replace(/^\//, "");
+            source = (0, path_1.join)(sourceMap.sourceRoot, source);
+        }
+        const result = (0, path_1.resolve)(mapFile, "..", source);
+        declarationMapCache.set(file, result);
+        return result;
+    }
+    return file;
+}

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

@@ -1,9 +1,10 @@
-import type { SourceReference } from "../sources/file";
-import type { Comment } from "../comments/comment";
+import { Comment } from "../comments/comment";
 import type { ProjectReflection } from "./project";
 import type { NeverIfInternal } from "../../utils";
 import { ReflectionKind } from "./kind";
-import type { Serializer, JSONOutput } from "../../serialization";
+import type { Serializer, Deserializer, JSONOutput } from "../../serialization";
+import type { ReflectionVariant } from "./variant";
+import type { DeclarationReflection } from "./declaration";
 /**
  * Reset the reflection id.
  *
@@ -70,6 +71,7 @@ export declare class ReflectionFlags extends Array<string> {
     private setSingleFlag;
     private static serializedFlags;
     toObject(): JSONOutput.ReflectionFlags;
+    fromObject(obj: JSONOutput.ReflectionFlags): void;
 }
 export declare enum TraverseProperty {
     Children = 0,
@@ -100,6 +102,10 @@ export interface TraverseCallback {
  * contains a list of all children grouped and sorted for rendering.
  */
 export declare abstract class Reflection {
+    /**
+     * Discriminator representing the type of reflection represented by this object.
+     */
+    abstract readonly variant: keyof ReflectionVariant;
     /**
      * Unique id of this reflection.
      */
@@ -108,24 +114,10 @@ export declare abstract class Reflection {
      * The symbol name of this reflection.
      */
     name: string;
-    /**
-     * The original name of the TypeScript declaration.
-     */
-    originalName: string;
-    /**
-     * Label associated with this reflection, if any (https://tsdoc.org/pages/tags/label/)
-     * Added by the CommentPlugin during resolution.
-     */
-    label?: string;
     /**
      * The kind of this reflection.
      */
     kind: ReflectionKind;
-    /**
-     * The human readable string representation of the kind of this reflection.
-     * Set during the resolution phase by GroupPlugin
-     */
-    kindString?: string;
     flags: ReflectionFlags;
     /**
      * The reflection this reflection is a child of.
@@ -136,10 +128,6 @@ export declare abstract class Reflection {
      * The parsed documentation comment attached to this reflection.
      */
     comment?: Comment;
-    /**
-     * A list of all source files that contributed to this reflection.
-     */
-    sources?: SourceReference[];
     /**
      * The url of this reflection in the generated documentation.
      * TODO: Reflections shouldn't know urls exist. Move this to a serializer.
@@ -157,12 +145,6 @@ export declare abstract class Reflection {
      * TODO: Reflections shouldn't know how they are rendered. Move this to the correct serializer.
      */
     hasOwnDocument?: boolean;
-    /**
-     * A list of generated css classes that should be applied to representations of this
-     * reflection in the generated markup.
-     * TODO: Reflections shouldn't know about CSS. Move this property to the correct serializer.
-     */
-    cssClasses?: string;
     /**
      * Url safe alias for this reflection.
      *
@@ -216,19 +198,11 @@ export declare abstract class Reflection {
      * Return whether this reflection is the root / project reflection.
      */
     isProject(): this is ProjectReflection;
+    isDeclaration(): this is DeclarationReflection;
     /**
-     * Check if this reflection has been marked with the `@deprecated` tag.
+     * Check if this reflection or any of its parents have been marked with the `@deprecated` tag.
      */
     isDeprecated(): boolean;
-    /**
-     * Try to find a reflection by its name.
-     *
-     * @return The found reflection or null.
-     * @deprecated This method not be used, it naively splits the name by a `.` and searches recursively up
-     * the parent tree, which is not how any other name resolver works. If you are currently using this and
-     * need another method, please open an issue. For tests {@link getChildByName} should generally be sufficient.
-     */
-    findReflectionByName(arg: string | string[]): Reflection | undefined;
     /**
      * Traverse all potential child reflections of this reflection.
      *
@@ -249,4 +223,5 @@ export declare abstract class Reflection {
      */
     toStringHierarchy(indent?: string): string;
     toObject(serializer: Serializer): JSONOutput.Reflection;
+    fromObject(de: Deserializer, obj: JSONOutput.Reflection): void;
 }

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

@@ -2,19 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Reflection = exports.TraverseProperty = exports.ReflectionFlags = exports.ReflectionFlag = exports.resetReflectionID = void 0;
 const assert_1 = require("assert");
+const comment_1 = require("../comments/comment");
 const utils_1 = require("./utils");
 const kind_1 = require("./kind");
-/**
- * Holds all data models used by TypeDoc.
- *
- * The {@link BaseReflection} is base class of all reflection models. The subclass {@link ProjectReflection}
- * serves as the root container for the current project while {@link DeclarationReflection} instances
- * form the structure of the project. Most of the other classes in this namespace are referenced by this
- * two base classes.
- *
- * The models {@link NavigationItem} and {@link UrlMapping} are special as they are only used by the {@link Renderer}
- * while creating the final output.
- */
 /**
  * Current reflection id.
  */
@@ -171,6 +161,14 @@ class ReflectionFlags extends Array {
             .filter((flag) => this[flag])
             .map((flag) => [flag, true]));
     }
+    fromObject(obj) {
+        for (const key of Object.keys(obj)) {
+            const flagName = key.substring(2); // isPublic => Public
+            if (flagName in ReflectionFlag) {
+                this.setFlag(ReflectionFlag[flagName], true);
+            }
+        }
+    }
 }
 exports.ReflectionFlags = ReflectionFlags;
 ReflectionFlags.serializedFlags = [
@@ -220,7 +218,6 @@ class Reflection {
         this.id = REFLECTION_ID++;
         this.parent = parent;
         this.name = name;
-        this.originalName = name;
         this.kind = kind;
         // If our parent is external, we are too.
         if (parent?.flags.isExternal) {
@@ -349,8 +346,11 @@ class Reflection {
     isProject() {
         return false;
     }
+    isDeclaration() {
+        return false;
+    }
     /**
-     * Check if this reflection has been marked with the `@deprecated` tag.
+     * Check if this reflection or any of its parents have been marked with the `@deprecated` tag.
      */
     isDeprecated() {
         if (this.comment?.getTag("@deprecated")) {
@@ -358,26 +358,6 @@ class Reflection {
         }
         return this.parent?.isDeprecated() ?? false;
     }
-    /**
-     * Try to find a reflection by its name.
-     *
-     * @return The found reflection or null.
-     * @deprecated This method not be used, it naively splits the name by a `.` and searches recursively up
-     * the parent tree, which is not how any other name resolver works. If you are currently using this and
-     * need another method, please open an issue. For tests {@link getChildByName} should generally be sufficient.
-     */
-    findReflectionByName(arg) {
-        const names = Array.isArray(arg)
-            ? arg
-            : (0, utils_1.splitUnquotedString)(arg, ".");
-        const reflection = this.getChildByName(names);
-        if (reflection) {
-            return reflection;
-        }
-        else if (this.parent) {
-            return this.parent.findReflectionByName(names);
-        }
-    }
     /**
      * Traverse all potential child reflections of this reflection.
      *
@@ -413,14 +393,26 @@ class Reflection {
         return {
             id: this.id,
             name: this.name,
+            variant: this.variant,
             kind: this.kind,
-            kindString: this.kindString,
             flags: this.flags.toObject(),
             comment: this.comment && !this.comment.isEmpty()
                 ? serializer.toObject(this.comment)
                 : undefined,
-            originalName: this.originalName !== this.name ? this.originalName : undefined,
         };
     }
+    fromObject(de, obj) {
+        // DO NOT copy id from obj. When deserializing reflections
+        // they should be given new ids since they belong to a different project.
+        this.name = obj.name;
+        // Skip copying variant, we know it's already the correct value because the deserializer
+        // will construct the correct class type.
+        this.kind = obj.kind;
+        this.flags.fromObject(obj.flags);
+        // Parent is set during construction, so we don't need to do it here.
+        this.comment = de.revive(obj.comment, () => new comment_1.Comment());
+        // url, anchor, hasOwnDocument, _alias, _aliases are set during rendering and only relevant during render.
+        // It doesn't make sense to serialize them to json, or restore them.
+    }
 }
 exports.Reflection = Reflection;