@depup/typedoc 0.28.17-depup.0

package/dist/lib/models/ContainerReflection.js

@@ -0,0 +1,159 @@
+import { Reflection, TraverseProperty } from "./Reflection.js";
+import { ReflectionCategory } from "./ReflectionCategory.js";
+import { ReflectionGroup } from "./ReflectionGroup.js";
+import { ReflectionKind } from "./kind.js";
+import { assertNever, removeIfPresent } from "#utils";
+/**
+ * @category Reflections
+ */
+export class ContainerReflection extends Reflection {
+    /**
+     * The children of this reflection. Do not add reflections to this array
+     * manually. Instead call {@link addChild}.
+     */
+    children;
+    /**
+     * Documents associated with this reflection.
+     *
+     * These are not children as including them as children requires code handle both
+     * types, despite being mostly unrelated and handled separately.
+     *
+     * Including them here in a separate array neatly handles that problem, but also
+     * introduces another one for rendering. When rendering, documents should really
+     * actually be considered part of the "children" of a reflection. For this reason,
+     * we also maintain a list of child declarations with child documents which is used
+     * when rendering.
+     */
+    documents;
+    /**
+     * Union of the {@link children} and {@link documents} arrays which dictates the
+     * sort order for rendering.
+     */
+    childrenIncludingDocuments;
+    /**
+     * All children grouped by their kind.
+     */
+    groups;
+    /**
+     * All children grouped by their category.
+     */
+    categories;
+    /**
+     * Return a list of all children of a certain kind.
+     *
+     * @param kind  The desired kind of children.
+     * @returns     An array containing all children with the desired kind.
+     */
+    getChildrenByKind(kind) {
+        return (this.children || []).filter((child) => child.kindOf(kind));
+    }
+    addChild(child) {
+        if (child.isDeclaration()) {
+            this.children ||= [];
+            this.children.push(child);
+            this.childrenIncludingDocuments ||= [];
+            this.childrenIncludingDocuments.push(child);
+        }
+        else if (child.isDocument()) {
+            this.documents ||= [];
+            this.documents.push(child);
+            this.childrenIncludingDocuments ||= [];
+            this.childrenIncludingDocuments.push(child);
+        }
+        else if (this.isDeclaration() && child.isSignature()) {
+            switch (child.kind) {
+                case ReflectionKind.CallSignature:
+                case ReflectionKind.ConstructorSignature:
+                    this.signatures ||= [];
+                    this.signatures.push(child);
+                    break;
+                case ReflectionKind.IndexSignature:
+                    this.indexSignatures ||= [];
+                    this.indexSignatures.push(child);
+                    break;
+                case ReflectionKind.GetSignature:
+                case ReflectionKind.SetSignature:
+                    throw new Error("Unsupported child type: " + ReflectionKind[child.kind]);
+                default:
+                    assertNever(child.kind);
+            }
+        }
+        else {
+            throw new Error("Unsupported child type: " + ReflectionKind[child.kind]);
+        }
+    }
+    removeChild(child) {
+        if (child.isDeclaration()) {
+            removeIfPresent(this.children, child);
+            if (this.children?.length === 0) {
+                delete this.children;
+            }
+        }
+        else {
+            removeIfPresent(this.documents, child);
+            if (this.documents?.length === 0) {
+                delete this.documents;
+            }
+        }
+        removeIfPresent(this.childrenIncludingDocuments, child);
+        if (this.childrenIncludingDocuments?.length === 0) {
+            delete this.childrenIncludingDocuments;
+        }
+    }
+    isContainer() {
+        return true;
+    }
+    traverse(callback) {
+        for (const child of this.children?.slice() || []) {
+            if (callback(child, TraverseProperty.Children) === false) {
+                return;
+            }
+        }
+        for (const child of this.documents?.slice() || []) {
+            if (callback(child, TraverseProperty.Documents) === false) {
+                return;
+            }
+        }
+    }
+    toObject(serializer) {
+        return {
+            ...super.toObject(serializer),
+            children: serializer.toObjectsOptional(this.children),
+            documents: serializer.toObjectsOptional(this.documents),
+            // If we only have one type of child, don't bother writing the duplicate info about
+            // ordering with documents to the serialized file.
+            childrenIncludingDocuments: this.children?.length && this.documents?.length
+                ? this.childrenIncludingDocuments?.map((refl) => refl.id)
+                : undefined,
+            groups: serializer.toObjectsOptional(this.groups),
+            categories: serializer.toObjectsOptional(this.categories),
+        };
+    }
+    fromObject(de, obj) {
+        super.fromObject(de, obj);
+        this.children = de.reviveMany(obj.children, (child) => de.constructReflection(child));
+        this.documents = de.reviveMany(obj.documents, (child) => de.constructReflection(child));
+        const byId = new Map();
+        for (const child of this.children || []) {
+            byId.set(child.id, child);
+        }
+        for (const child of this.documents || []) {
+            byId.set(child.id, child);
+        }
+        for (const id of obj.childrenIncludingDocuments || []) {
+            const child = byId.get(de.oldIdToNewId[id] ?? -1);
+            if (child) {
+                this.childrenIncludingDocuments ||= [];
+                this.childrenIncludingDocuments.push(child);
+                byId.delete(de.oldIdToNewId[id] ?? -1);
+            }
+        }
+        if (byId.size) {
+            // Anything left in byId wasn't included in the childrenIncludingDocuments array.
+            this.childrenIncludingDocuments ||= [];
+            this.childrenIncludingDocuments.push(...byId.values());
+        }
+        this.groups = de.reviveMany(obj.groups, (group) => new ReflectionGroup(group.title, this));
+        this.categories = de.reviveMany(obj.categories, (cat) => new ReflectionCategory(cat.title));
+    }
+}

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

@@ -0,0 +1,149 @@
+import { type ReferenceType, type SomeType } from "./types.js";
+import { type TraverseCallback } from "./Reflection.js";
+import { ContainerReflection } from "./ContainerReflection.js";
+import type { SignatureReflection } from "./SignatureReflection.js";
+import type { TypeParameterReflection } from "./TypeParameterReflection.js";
+import type { Deserializer, JSONOutput, Serializer } from "#serialization";
+import { type CommentDisplayPart } from "./Comment.js";
+import { SourceReference } from "./SourceReference.js";
+/**
+ * Stores hierarchical type data.
+ *
+ * @see {@link DeclarationReflection.typeHierarchy}
+ */
+export interface DeclarationHierarchy {
+    /**
+     * The types represented by this node in the hierarchy.
+     */
+    types: SomeType[];
+    /**
+     * The next hierarchy level.
+     */
+    next?: DeclarationHierarchy;
+    /**
+     * Is this the entry containing the target type?
+     */
+    isTarget?: boolean;
+}
+/**
+ * A reflection that represents a single declaration emitted by the TypeScript compiler.
+ *
+ * All parts of a project are represented by DeclarationReflection instances. The actual
+ * kind of a reflection is stored in its `kind` member.
+ * @category Reflections
+ */
+export declare class DeclarationReflection extends ContainerReflection {
+    readonly variant: "declaration" | "reference";
+    /**
+     * A list of all source files that contributed to this reflection.
+     */
+    sources?: SourceReference[];
+    /**
+     * Precomputed boost for search results, may be less than 1 to de-emphasize this member in search results.
+     * Does NOT include group/category values as they are computed when building the JS index.
+     *
+     * This is exposed purely for plugin use, see #3036 for details.
+     */
+    relevanceBoost?: number;
+    /**
+     * The escaped name of this declaration assigned by the TS compiler if there is an associated symbol.
+     * This is used to retrieve properties for analyzing inherited members.
+     *
+     * Not serialized, only useful during conversion. This is a `ts.__String`.
+     * @internal
+     */
+    escapedName?: string;
+    /**
+     * The type of the reflection.
+     *
+     * If the reflection represents a variable or a property, this is the value type.<br />
+     * If the reflection represents a signature, this is the return type.
+     */
+    type?: SomeType;
+    typeParameters?: TypeParameterReflection[];
+    /**
+     * A list of call signatures attached to this declaration.
+     *
+     * TypeDoc creates one declaration per function that may contain one or more
+     * signature reflections.
+     */
+    signatures?: SignatureReflection[];
+    /**
+     * The index signature of this declaration.
+     */
+    indexSignatures?: SignatureReflection[];
+    /**
+     * The get signature of this declaration.
+     */
+    getSignature?: SignatureReflection;
+    /**
+     * The set signature of this declaration.
+     */
+    setSignature?: SignatureReflection;
+    /**
+     * The default value of this reflection.
+     *
+     * Applies to function parameters, variables, and properties.
+     */
+    defaultValue?: string;
+    /**
+     * A type that points to the reflection that has been overwritten by this reflection.
+     *
+     * Applies to interface and class members.
+     */
+    overwrites?: ReferenceType;
+    /**
+     * A type that points to the reflection this reflection has been inherited from.
+     *
+     * Applies to interface and class members.
+     */
+    inheritedFrom?: ReferenceType;
+    /**
+     * A type that points to the reflection this reflection is the implementation of.
+     *
+     * Applies to class members.
+     */
+    implementationOf?: ReferenceType;
+    /**
+     * A list of all types this reflection extends (e.g. the parent classes).
+     */
+    extendedTypes?: SomeType[];
+    /**
+     * A list of all types that extend this reflection (e.g. the subclasses).
+     */
+    extendedBy?: ReferenceType[];
+    /**
+     * A list of all types this reflection implements.
+     */
+    implementedTypes?: SomeType[];
+    /**
+     * A list of all types that implement this reflection.
+     */
+    implementedBy?: ReferenceType[];
+    /**
+     * Contains a simplified representation of the type hierarchy suitable for being
+     * rendered in templates.
+     */
+    typeHierarchy?: DeclarationHierarchy;
+    /**
+     * The contents of the readme file of the module when found.
+     */
+    readme?: CommentDisplayPart[];
+    /**
+     * The version of the module when found.
+     */
+    packageVersion?: string;
+    isDeclaration(): this is DeclarationReflection;
+    hasGetterOrSetter(): boolean;
+    getAllSignatures(): SignatureReflection[];
+    getNonIndexSignatures(): SignatureReflection[];
+    getProperties(): DeclarationReflection[];
+    getChildOrTypePropertyByName(path: string[]): DeclarationReflection | undefined;
+    traverse(callback: TraverseCallback): void;
+    /**
+     * Return a string representation of this reflection.
+     */
+    toString(): string;
+    toObject(serializer: Serializer): JSONOutput.DeclarationReflection;
+    fromObject(de: Deserializer, obj: JSONOutput.DeclarationReflection | JSONOutput.ProjectReflection): void;
+}

package/dist/lib/models/DeclarationReflection.js

@@ -0,0 +1,287 @@
+import { ReflectionType } from "./types.js";
+import { TraverseProperty } from "./Reflection.js";
+import { ContainerReflection } from "./ContainerReflection.js";
+import { Comment } from "./Comment.js";
+import { SourceReference } from "./SourceReference.js";
+import { ReflectionSymbolId } from "./ReflectionSymbolId.js";
+import { ReflectionKind } from "./kind.js";
+import { i18n } from "#utils";
+/**
+ * A reflection that represents a single declaration emitted by the TypeScript compiler.
+ *
+ * All parts of a project are represented by DeclarationReflection instances. The actual
+ * kind of a reflection is stored in its `kind` member.
+ * @category Reflections
+ */
+export class DeclarationReflection extends ContainerReflection {
+    variant = "declaration";
+    /**
+     * A list of all source files that contributed to this reflection.
+     */
+    sources;
+    /**
+     * Precomputed boost for search results, may be less than 1 to de-emphasize this member in search results.
+     * Does NOT include group/category values as they are computed when building the JS index.
+     *
+     * This is exposed purely for plugin use, see #3036 for details.
+     */
+    relevanceBoost;
+    /**
+     * The escaped name of this declaration assigned by the TS compiler if there is an associated symbol.
+     * This is used to retrieve properties for analyzing inherited members.
+     *
+     * Not serialized, only useful during conversion. This is a `ts.__String`.
+     * @internal
+     */
+    escapedName;
+    /**
+     * The type of the reflection.
+     *
+     * If the reflection represents a variable or a property, this is the value type.<br />
+     * If the reflection represents a signature, this is the return type.
+     */
+    type;
+    typeParameters;
+    /**
+     * A list of call signatures attached to this declaration.
+     *
+     * TypeDoc creates one declaration per function that may contain one or more
+     * signature reflections.
+     */
+    signatures;
+    /**
+     * The index signature of this declaration.
+     */
+    indexSignatures;
+    /**
+     * The get signature of this declaration.
+     */
+    getSignature;
+    /**
+     * The set signature of this declaration.
+     */
+    setSignature;
+    /**
+     * The default value of this reflection.
+     *
+     * Applies to function parameters, variables, and properties.
+     */
+    defaultValue;
+    /**
+     * A type that points to the reflection that has been overwritten by this reflection.
+     *
+     * Applies to interface and class members.
+     */
+    overwrites;
+    /**
+     * A type that points to the reflection this reflection has been inherited from.
+     *
+     * Applies to interface and class members.
+     */
+    inheritedFrom;
+    /**
+     * A type that points to the reflection this reflection is the implementation of.
+     *
+     * Applies to class members.
+     */
+    implementationOf;
+    /**
+     * A list of all types this reflection extends (e.g. the parent classes).
+     */
+    extendedTypes;
+    /**
+     * A list of all types that extend this reflection (e.g. the subclasses).
+     */
+    extendedBy;
+    /**
+     * A list of all types this reflection implements.
+     */
+    implementedTypes;
+    /**
+     * A list of all types that implement this reflection.
+     */
+    implementedBy;
+    /**
+     * Contains a simplified representation of the type hierarchy suitable for being
+     * rendered in templates.
+     */
+    typeHierarchy;
+    /**
+     * The contents of the readme file of the module when found.
+     */
+    readme;
+    /**
+     * The version of the module when found.
+     */
+    packageVersion;
+    isDeclaration() {
+        return true;
+    }
+    hasGetterOrSetter() {
+        return !!this.getSignature || !!this.setSignature;
+    }
+    getAllSignatures() {
+        let result = [];
+        if (this.signatures) {
+            result = result.concat(this.signatures);
+        }
+        if (this.indexSignatures) {
+            result = result.concat(this.indexSignatures);
+        }
+        if (this.getSignature) {
+            result.push(this.getSignature);
+        }
+        if (this.setSignature) {
+            result.push(this.setSignature);
+        }
+        return result;
+    }
+    getNonIndexSignatures() {
+        return [].concat(this.signatures ?? [], this.setSignature ?? [], this.getSignature ?? []);
+    }
+    getProperties() {
+        if (this.children?.length) {
+            return this.children;
+        }
+        if (this.type?.type === "reflection") {
+            return this.type.declaration.children ?? [];
+        }
+        return [];
+    }
+    getChildOrTypePropertyByName(path) {
+        if (this.type?.type === "reflection") {
+            for (const child of this.type.declaration.children || []) {
+                if (path[0] === child.name) {
+                    if (path.length === 1) {
+                        return child;
+                    }
+                    return child.getChildOrTypePropertyByName(path.slice(1));
+                }
+            }
+        }
+        for (const child of this.children || []) {
+            if (path[0] === child.name) {
+                if (path.length === 1) {
+                    return child;
+                }
+                return child.getChildOrTypePropertyByName(path.slice(1));
+            }
+        }
+        return undefined;
+    }
+    traverse(callback) {
+        for (const parameter of this.typeParameters?.slice() || []) {
+            if (callback(parameter, TraverseProperty.TypeParameter) === false) {
+                return;
+            }
+        }
+        if (this.type instanceof ReflectionType) {
+            if (callback(this.type.declaration, TraverseProperty.TypeLiteral) === false) {
+                return;
+            }
+        }
+        for (const signature of this.signatures?.slice() || []) {
+            if (callback(signature, TraverseProperty.Signatures) === false) {
+                return;
+            }
+        }
+        for (const signature of this.indexSignatures?.slice() || []) {
+            if (callback(signature, TraverseProperty.IndexSignature) === false) {
+                return;
+            }
+        }
+        if (this.getSignature) {
+            if (callback(this.getSignature, TraverseProperty.GetSignature) ===
+                false) {
+                return;
+            }
+        }
+        if (this.setSignature) {
+            if (callback(this.setSignature, TraverseProperty.SetSignature) ===
+                false) {
+                return;
+            }
+        }
+        super.traverse(callback);
+    }
+    /**
+     * Return a string representation of this reflection.
+     */
+    toString() {
+        let result = super.toString();
+        if (this.typeParameters) {
+            const parameters = this.typeParameters.map((parameter) => parameter.name);
+            result += "<" + parameters.join(", ") + ">";
+        }
+        if (this.type) {
+            result += ": " + this.type.toString();
+        }
+        return result;
+    }
+    toObject(serializer) {
+        return {
+            ...super.toObject(serializer),
+            variant: this.variant,
+            packageVersion: this.packageVersion,
+            sources: serializer.toObjectsOptional(this.sources),
+            relevanceBoost: this.relevanceBoost === 1 ? undefined : this.relevanceBoost,
+            typeParameters: serializer.toObjectsOptional(this.typeParameters),
+            type: serializer.toObject(this.type),
+            signatures: serializer.toObjectsOptional(this.signatures),
+            indexSignatures: serializer.toObjectsOptional(this.indexSignatures),
+            getSignature: serializer.toObject(this.getSignature),
+            setSignature: serializer.toObject(this.setSignature),
+            defaultValue: this.defaultValue,
+            overwrites: serializer.toObject(this.overwrites),
+            inheritedFrom: serializer.toObject(this.inheritedFrom),
+            implementationOf: serializer.toObject(this.implementationOf),
+            extendedTypes: serializer.toObjectsOptional(this.extendedTypes),
+            extendedBy: serializer.toObjectsOptional(this.extendedBy),
+            implementedTypes: serializer.toObjectsOptional(this.implementedTypes),
+            implementedBy: serializer.toObjectsOptional(this.implementedBy),
+            readme: Comment.serializeDisplayParts(this.readme),
+        };
+    }
+    fromObject(de, obj) {
+        super.fromObject(de, obj);
+        if (obj.readme) {
+            this.readme = Comment.deserializeDisplayParts(de, obj.readme);
+        }
+        // This happens when merging multiple projects together.
+        // If updating this, also check ProjectReflection.fromObject.
+        if (obj.variant === "project") {
+            this.kind = ReflectionKind.Module;
+            this.packageVersion = obj.packageVersion;
+            this.project.files.fromObject(de, obj.files || {});
+            de.defer(() => {
+                for (const [id, sid] of Object.entries(obj.symbolIdMap || {})) {
+                    const refl = this.project.getReflectionById(de.oldIdToNewId[+id] ?? -1);
+                    if (refl) {
+                        this.project.registerSymbolId(refl, new ReflectionSymbolId(sid));
+                    }
+                    else {
+                        de.logger.warn(i18n.serialized_project_referenced_0_not_part_of_project(id));
+                    }
+                }
+            });
+            return;
+        }
+        this.packageVersion = obj.packageVersion;
+        this.sources = de.reviveMany(obj.sources, (src) => new SourceReference(src.fileName, src.line, src.character));
+        this.relevanceBoost = obj.relevanceBoost;
+        this.typeParameters = de.reviveMany(obj.typeParameters, (tp) => de.constructReflection(tp));
+        this.type = de.revive(obj.type, (t) => de.constructType(t));
+        this.signatures = de.reviveMany(obj.signatures, (r) => de.constructReflection(r));
+        this.indexSignatures = de.reviveMany(obj.indexSignatures, (r) => de.constructReflection(r));
+        this.getSignature = de.revive(obj.getSignature, (r) => de.constructReflection(r));
+        this.setSignature = de.revive(obj.setSignature, (r) => de.constructReflection(r));
+        this.defaultValue = obj.defaultValue;
+        this.overwrites = de.reviveType(obj.overwrites);
+        this.inheritedFrom = de.reviveType(obj.inheritedFrom);
+        this.implementationOf = de.reviveType(obj.implementationOf);
+        this.extendedTypes = de.reviveMany(obj.extendedTypes, (t) => de.reviveType(t));
+        this.extendedBy = de.reviveMany(obj.extendedBy, (t) => de.reviveType(t));
+        this.implementedTypes = de.reviveMany(obj.implementedTypes, (t) => de.reviveType(t));
+        this.implementedBy = de.reviveMany(obj.implementedBy, (t) => de.reviveType(t));
+    }
+}

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

@@ -0,0 +1,32 @@
+import type { Deserializer, JSONOutput, Serializer } from "#serialization";
+import { type CommentDisplayPart } from "./Comment.js";
+import { Reflection, type TraverseCallback } from "./Reflection.js";
+/**
+ * Non-TS reflection type which is used to represent markdown documents included in the docs.
+ */
+export declare class DocumentReflection extends Reflection {
+    readonly variant = "document";
+    /**
+     * The content to be displayed on the page for this reflection.
+     */
+    content: CommentDisplayPart[];
+    /**
+     * Frontmatter included in document
+     */
+    frontmatter: Record<string, unknown>;
+    /**
+     * A precomputed boost derived from the searchCategoryBoosts and searchGroupBoosts options, used when
+     * boosting search relevance scores at runtime. May be modified by plugins.
+     */
+    relevanceBoost?: number;
+    /**
+     * Child documents, if any are present.
+     */
+    children?: DocumentReflection[];
+    constructor(name: string, parent: Reflection, content: CommentDisplayPart[], frontmatter: Record<string, unknown>);
+    addChild(child: DocumentReflection): void;
+    isDocument(): this is DocumentReflection;
+    traverse(callback: TraverseCallback): void;
+    toObject(serializer: Serializer): JSONOutput.DocumentReflection;
+    fromObject(de: Deserializer, obj: JSONOutput.DocumentReflection): void;
+}

package/dist/lib/models/DocumentReflection.js

@@ -0,0 +1,66 @@
+import { Comment } from "./Comment.js";
+import { Reflection, TraverseProperty } from "./Reflection.js";
+import { ReflectionKind } from "./kind.js";
+/**
+ * Non-TS reflection type which is used to represent markdown documents included in the docs.
+ */
+export class DocumentReflection extends Reflection {
+    variant = "document";
+    /**
+     * The content to be displayed on the page for this reflection.
+     */
+    content;
+    /**
+     * Frontmatter included in document
+     */
+    frontmatter;
+    /**
+     * A precomputed boost derived from the searchCategoryBoosts and searchGroupBoosts options, used when
+     * boosting search relevance scores at runtime. May be modified by plugins.
+     */
+    relevanceBoost;
+    /**
+     * Child documents, if any are present.
+     */
+    children;
+    constructor(name, parent, content, frontmatter) {
+        super(name, ReflectionKind.Document, parent);
+        this.content = content;
+        this.frontmatter = frontmatter;
+        if (typeof frontmatter["title"] === "string") {
+            this.name = frontmatter["title"];
+            delete frontmatter["title"];
+        }
+    }
+    addChild(child) {
+        this.children ||= [];
+        this.children.push(child);
+    }
+    isDocument() {
+        return true;
+    }
+    traverse(callback) {
+        for (const child of this.children || []) {
+            if (callback(child, TraverseProperty.Documents) === false) {
+                return;
+            }
+        }
+    }
+    toObject(serializer) {
+        return {
+            ...super.toObject(serializer),
+            variant: this.variant,
+            content: Comment.serializeDisplayParts(this.content),
+            frontmatter: this.frontmatter,
+            relevanceBoost: this.relevanceBoost,
+            children: serializer.toObjectsOptional(this.children),
+        };
+    }
+    fromObject(de, obj) {
+        super.fromObject(de, obj);
+        this.content = Comment.deserializeDisplayParts(de, obj.content);
+        this.frontmatter = obj.frontmatter;
+        this.relevanceBoost = obj.relevanceBoost;
+        this.children = de.reviveMany(obj.children, (obj) => de.constructReflection(obj));
+    }
+}