@depup/typedoc 0.28.17-depup.0

package/dist/lib/output/themes/lib.js

@@ -0,0 +1,218 @@
+import { DeclarationReflection, ProjectReflection, ReferenceReflection, ReflectionKind, SignatureReflection, } from "../../models/index.js";
+import { DefaultMap, filterMap, JSX } from "#utils";
+export function stringify(data) {
+    if (typeof data === "bigint") {
+        return data.toString() + "n";
+    }
+    return JSON.stringify(data);
+}
+export function getDisplayName(refl) {
+    let version = "";
+    if ((refl instanceof DeclarationReflection || refl instanceof ProjectReflection) && refl.packageVersion) {
+        version = ` - v${refl.packageVersion}`;
+    }
+    return `${refl.name}${version}`;
+}
+export function toStyleClass(str) {
+    return str.replace(/(\w)([A-Z])/g, (_m, m1, m2) => m1 + "-" + m2).toLowerCase();
+}
+export function getKindClass(refl) {
+    if (refl instanceof ReferenceReflection) {
+        return getKindClass(refl.getTargetReflectionDeep());
+    }
+    return ReflectionKind.classString(refl.kind);
+}
+/**
+ * Insert word break tags ``<wbr>`` into the given string.
+ *
+ * Breaks the given string at ``_``, ``-`` and capital letters.
+ *
+ * @param str The string that should be split.
+ * @return The original string containing ``<wbr>`` tags where possible.
+ */
+export function wbr(str) {
+    // Keep this in sync with the same helper in Navigation.ts
+    // We use lookahead/lookbehind to indicate where the string should
+    // be split without consuming a character.
+    // (?<=[^A-Z])(?=[A-Z]) -- regular camel cased text
+    // (?<=[A-Z])(?=[A-Z][a-z]) -- acronym
+    // (?<=[_-])(?=[^_-]) -- snake
+    const parts = str.split(/(?<=[^A-Z])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])|(?<=[_-])(?=[^_-])/);
+    return parts.flatMap(p => [p, JSX.createElement("wbr", null)]).slice(0, -1);
+}
+export function join(joiner, list, cb) {
+    const result = [];
+    for (const item of list) {
+        if (result.length > 0) {
+            result.push(joiner);
+        }
+        result.push(cb(item));
+    }
+    return JSX.createElement(JSX.Fragment, null, result);
+}
+export function classNames(names, extraCss) {
+    const css = Object.keys(names)
+        .filter((key) => names[key])
+        .concat(extraCss || "")
+        .join(" ")
+        .trim()
+        .replace(/\s+/g, " ");
+    return css.length ? css : undefined;
+}
+export function hasTypeParameters(reflection) {
+    return ((reflection instanceof DeclarationReflection || reflection instanceof SignatureReflection) &&
+        reflection.typeParameters != null &&
+        reflection.typeParameters.length > 0);
+}
+export function renderTypeParametersSignature(context, typeParameters) {
+    if (!typeParameters || typeParameters.length === 0)
+        return JSX.createElement(JSX.Fragment, null);
+    return (JSX.createElement(JSX.Fragment, null,
+        JSX.createElement("span", { class: "tsd-signature-symbol" }, "<"),
+        join(JSX.createElement("span", { class: "tsd-signature-symbol" }, ", "), typeParameters, (item) => (JSX.createElement(JSX.Fragment, null,
+            (item.flags.isConst || item.varianceModifier) && (JSX.createElement("span", { class: "tsd-signature-keyword" },
+                item.flags.isConst && "const ",
+                item.varianceModifier && `${item.varianceModifier} `)),
+            JSX.createElement("span", { class: "tsd-signature-type tsd-kind-type-parameter" }, item.name),
+            !!item.type && (JSX.createElement(JSX.Fragment, null,
+                " ",
+                JSX.createElement("span", { class: "tsd-signature-keyword" }, "extends"),
+                " ",
+                context.type(item.type)))))),
+        JSX.createElement("span", { class: "tsd-signature-symbol" }, ">")));
+}
+/**
+ * Renders the reflection name with an additional `?` if optional.
+ */
+export function renderName(refl) {
+    if (refl.flags.isOptional) {
+        return JSX.createElement(JSX.Fragment, null,
+            wbr(refl.name),
+            "?");
+    }
+    return wbr(refl.name);
+}
+// This is cached to avoid slowness with large projects.
+const rootsCache = new WeakMap();
+export function getHierarchyRoots(project) {
+    const cached = rootsCache.get(project);
+    if (cached)
+        return cached;
+    const allClasses = project.getReflectionsByKind(ReflectionKind.ClassOrInterface);
+    const roots = allClasses.filter((refl) => {
+        // If nobody extends this class, there's no possible hierarchy to display.
+        if (!refl.implementedBy && !refl.extendedBy) {
+            return false;
+        }
+        // If we don't extend anything, then we are a root
+        if (!refl.implementedTypes && !refl.extendedTypes) {
+            return true;
+        }
+        // We might still be a root, if our extended/implemented types are not included
+        // in the documentation.
+        const types = [...(refl.implementedTypes || []), ...(refl.extendedTypes || [])];
+        return types.every((type) => !type.visit({
+            reference(ref) {
+                return ref.reflection !== undefined;
+            },
+        }));
+    });
+    const result = roots.sort((a, b) => a.name.localeCompare(b.name));
+    rootsCache.set(project, result);
+    return result;
+}
+export function isNoneSection(section) {
+    return section.title.toLocaleLowerCase() === "none";
+}
+function sortNoneSectionFirst(a, b) {
+    if (isNoneSection(a)) {
+        return -1;
+    }
+    if (isNoneSection(b)) {
+        return 1;
+    }
+    return 0;
+}
+export function getMemberSections(parent, childFilter = () => true) {
+    if (parent.categories?.length) {
+        return filterMap(parent.categories, (cat) => {
+            const children = cat.children.filter(childFilter);
+            if (!children.length)
+                return;
+            return {
+                title: cat.title,
+                description: cat.description,
+                children,
+            };
+        }).sort(sortNoneSectionFirst);
+    }
+    if (parent.groups?.length) {
+        return parent.groups.flatMap((group) => {
+            if (group.categories?.length) {
+                return filterMap(group.categories.slice().sort(sortNoneSectionFirst), (cat) => {
+                    const children = cat.children.filter(childFilter);
+                    if (!children.length)
+                        return;
+                    return {
+                        title: isNoneSection(cat) ? group.title : `${group.title} - ${cat.title}`,
+                        description: cat.description,
+                        children,
+                    };
+                });
+            }
+            const children = group.children.filter(childFilter);
+            if (!children.length)
+                return [];
+            return {
+                title: group.title,
+                description: group.description,
+                children,
+            };
+        }).sort(sortNoneSectionFirst);
+    }
+    if (parent.children?.length) {
+        return [{
+                title: "none",
+                children: parent.children || [],
+            }];
+    }
+    return [];
+}
+const nameCollisionCache = new WeakMap();
+function getNameCollisionCount(project, name) {
+    let collisions = nameCollisionCache.get(project);
+    if (collisions === undefined) {
+        collisions = new DefaultMap(() => 0);
+        for (const reflection of project.getReflectionsByKind(ReflectionKind.SomeExport)) {
+            collisions.set(reflection.name, collisions.get(reflection.name) + 1);
+        }
+        nameCollisionCache.set(project, collisions);
+    }
+    return collisions.get(name);
+}
+function getNamespacedPath(reflection) {
+    const path = [reflection];
+    let parent = reflection.parent;
+    while (parent?.kindOf(ReflectionKind.Namespace)) {
+        path.unshift(parent);
+        parent = parent.parent;
+    }
+    return path;
+}
+/**
+ * Returns a (hopefully) globally unique path for the given reflection.
+ *
+ * This only works for exportable symbols, so e.g. methods are not affected by this.
+ *
+ * If the given reflection has a globally unique name already, then it will be returned as is. If the name is
+ * ambiguous (i.e. there are two classes with the same name in different namespaces), then the namespaces path of the
+ * reflection will be returned.
+ */
+export function getUniquePath(reflection) {
+    if (reflection.kindOf(ReflectionKind.SomeExport)) {
+        if (getNameCollisionCount(reflection.project, reflection.name) >= 2) {
+            return getNamespacedPath(reflection);
+        }
+    }
+    return [reflection];
+}

package/dist/lib/serialization/components.d.ts

@@ -0,0 +1,22 @@
+import type { Serializer } from "./serializer.js";
+import type { ModelToObject } from "./schema.js";
+/**
+ * Represents Serializer plugin component.
+ *
+ * Like Converter plugins each {@link Serializer} plugin defines a predicate that instructs if an
+ * object can be serialized by it. This is done dynamically at runtime via a `supports` method.
+ */
+export interface SerializerComponent<T extends object> {
+    /**
+     * The priority this serializer should be executed with.
+     * A higher priority means the {@link Serializer} will be applied earlier.
+     */
+    readonly priority: number;
+    /**
+     * Technically this should return `item is T`, but that doesn't play nicely
+     * with inference, so allow the looser `boolean` return type.
+     * @param item
+     */
+    supports(item: unknown): boolean;
+    toObject(item: T, obj: Partial<ModelToObject<T>>, serializer: Serializer): Partial<ModelToObject<T>>;
+}

package/dist/lib/serialization/components.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/serialization/deserializer.d.ts

@@ -0,0 +1,70 @@
+import { type FileId, type FileRegistry, ProjectReflection, type ReflectionId, type ReflectionVariant, type TypeKindMap } from "#models";
+import { type Logger, type NormalizedPath } from "#utils";
+import * as JSONOutput from "./schema.js";
+export interface DeserializerComponent {
+    priority: number;
+    supports(model: unknown, obj: unknown): boolean;
+    fromObject(model: unknown, obj: unknown): void;
+}
+export interface Deserializable<T> {
+    fromObject(d: Deserializer, o: T): void;
+}
+/**
+ * Deserializes TypeDoc's JSON output back to {@link Reflection} instances.
+ *
+ * @group None
+ * @summary Deserializes TypeDoc's JSON output
+ */
+export declare class Deserializer {
+    logger: Logger;
+    private deferred;
+    private deserializers;
+    private activeReflection;
+    reflectionBuilders: {
+        [K in keyof ReflectionVariant]: (parent: NonNullable<ReflectionVariant[K]["parent"]>, obj: JSONOutput.ModelToObject<ReflectionVariant[K]>) => ReflectionVariant[K];
+    };
+    typeBuilders: {
+        [K in keyof TypeKindMap]: (obj: JSONOutput.ModelToObject<TypeKindMap[K]>, de: Deserializer) => TypeKindMap[K];
+    };
+    /**
+     * Only set when deserializing.
+     */
+    projectRoot: NormalizedPath;
+    oldIdToNewId: Record<ReflectionId, ReflectionId | undefined>;
+    oldFileIdToNewFileId: Record<FileId, FileId | undefined>;
+    project: ProjectReflection | undefined;
+    constructor(logger: Logger);
+    addDeserializer(de: DeserializerComponent): void;
+    /**
+     * Revive a single project into the structure it was originally created with.
+     * This is generally not appropriate for merging multiple projects since projects may
+     * contain reflections in their root, not inside a module.
+     */
+    reviveProject(name: string, projectObj: JSONOutput.ProjectReflection, options: {
+        projectRoot: NormalizedPath;
+        registry: FileRegistry;
+    }): ProjectReflection;
+    reviveProjects(name: string, projects: readonly JSONOutput.ProjectReflection[], options: {
+        projectRoot: NormalizedPath;
+        registry: FileRegistry;
+        alwaysCreateEntryPointModule: boolean;
+    }): ProjectReflection;
+    revive<T extends object, U extends Deserializable<T>>(source: NonNullable<T>, creator: (obj: T) => U): U;
+    revive<T extends object, U extends Deserializable<T>>(source: T | undefined, creator: (obj: T) => U): U | undefined;
+    reviveMany<T, U extends Deserializable<T>>(sourceArray: T[], creator: (obj: T) => U): U[];
+    reviveMany<T, U extends Deserializable<T>>(sourceArray: T[] | undefined, creator: (obj: T) => U): U[] | undefined;
+    reviveType<T extends JSONOutput.SomeType>(obj: T): TypeKindMap[T["type"]];
+    reviveType<T extends JSONOutput.SomeType>(obj: T | undefined): TypeKindMap[T["type"]] | undefined;
+    constructReflection<T extends JSONOutput.SomeReflection>(obj: T): ReflectionVariant[T["variant"]];
+    constructType<T extends JSONOutput.SomeType>(obj: T): TypeKindMap[T["type"]];
+    fromObject<T>(receiver: {
+        fromObject(d: Deserializer, o: T): void;
+    }, obj: T): void;
+    /**
+     * Defers work until the initial pass of serialization has been completed.
+     * This can be used to set up references which cannot be immediately restored.
+     *
+     * May only be called when deserializing.
+     */
+    defer(cb: (project: ProjectReflection) => void): void;
+}

package/dist/lib/serialization/deserializer.js

@@ -0,0 +1,235 @@
+import { ArrayType, ConditionalType, DeclarationReflection, DocumentReflection, IndexedAccessType, InferredType, IntersectionType, IntrinsicType, LiteralType, MappedType, NamedTupleMember, OptionalType, ParameterReflection, PredicateType, ProjectReflection, QueryType, ReferenceReflection, ReferenceType, Reflection, ReflectionKind, ReflectionType, RestType, SignatureReflection, TemplateLiteralType, TupleType, TypeOperatorType, TypeParameterReflection, UnionType, UnknownType, } from "#models";
+import { assert, insertPrioritySorted } from "#utils";
+import * as JSONOutput from "./schema.js";
+const supportedSchemaVersions = [JSONOutput.SCHEMA_VERSION];
+/**
+ * Deserializes TypeDoc's JSON output back to {@link Reflection} instances.
+ *
+ * @group None
+ * @summary Deserializes TypeDoc's JSON output
+ */
+export class Deserializer {
+    logger;
+    deferred = [];
+    deserializers = [];
+    activeReflection = [];
+    reflectionBuilders = {
+        declaration(parent, obj) {
+            return new DeclarationReflection(obj.name, obj.kind, parent);
+        },
+        document(parent, obj) {
+            return new DocumentReflection(obj.name, parent, [], {});
+        },
+        param(parent, obj) {
+            return new ParameterReflection(obj.name, obj.kind, parent);
+        },
+        project() {
+            throw new Error("Not supported, use Deserializer.reviveProject(s) instead.");
+        },
+        reference(parent, obj) {
+            // Ugly, but we don't have a reference yet!
+            return new ReferenceReflection(obj.name, 
+            /* target */ parent, parent);
+        },
+        signature(parent, obj) {
+            return new SignatureReflection(obj.name, obj.kind, parent);
+        },
+        typeParam(parent, obj) {
+            return new TypeParameterReflection(obj.name, parent, void 0);
+        },
+    };
+    typeBuilders = {
+        array(obj, de) {
+            return new ArrayType(de.reviveType(obj.elementType));
+        },
+        conditional(obj, de) {
+            return new ConditionalType(de.reviveType(obj.checkType), de.reviveType(obj.extendsType), de.reviveType(obj.trueType), de.reviveType(obj.falseType));
+        },
+        indexedAccess(obj, de) {
+            return new IndexedAccessType(de.reviveType(obj.objectType), de.reviveType(obj.indexType));
+        },
+        inferred(obj, de) {
+            return new InferredType(obj.name, de.reviveType(obj.constraint));
+        },
+        intersection(obj, de) {
+            return new IntersectionType(obj.types.map((t) => de.reviveType(t)));
+        },
+        intrinsic(obj) {
+            return new IntrinsicType(obj.name);
+        },
+        literal(obj) {
+            if (typeof obj.value === "object" && obj.value != null) {
+                return new LiteralType(BigInt(`${obj.value.negative ? "-" : ""}${obj.value.value}`));
+            }
+            return new LiteralType(obj.value);
+        },
+        mapped(obj, de) {
+            return new MappedType(obj.parameter, de.reviveType(obj.parameterType), de.reviveType(obj.templateType), obj.readonlyModifier, obj.optionalModifier, de.reviveType(obj.nameType));
+        },
+        optional(obj, de) {
+            return new OptionalType(de.reviveType(obj.elementType));
+        },
+        predicate(obj, de) {
+            return new PredicateType(obj.name, obj.asserts, de.reviveType(obj.targetType));
+        },
+        query(obj, de) {
+            return new QueryType(de.reviveType(obj.queryType));
+        },
+        reference(obj) {
+            // Correct reference will be restored in fromObject
+            return ReferenceType.createResolvedReference(obj.name, -2, null);
+        },
+        reflection(obj, de) {
+            return new ReflectionType(de.revive(obj.declaration, (o) => de.constructReflection(o)));
+        },
+        rest(obj, de) {
+            return new RestType(de.reviveType(obj.elementType));
+        },
+        templateLiteral(obj, de) {
+            return new TemplateLiteralType(obj.head, obj.tail.map(([t, s]) => [de.reviveType(t), s]));
+        },
+        tuple(obj, de) {
+            return new TupleType(obj.elements?.map((t) => de.reviveType(t)) || []);
+        },
+        namedTupleMember(obj, de) {
+            return new NamedTupleMember(obj.name, obj.isOptional, de.reviveType(obj.element));
+        },
+        typeOperator(obj, de) {
+            return new TypeOperatorType(de.reviveType(obj.target), obj.operator);
+        },
+        union(obj, de) {
+            return new UnionType(obj.types.map((t) => de.reviveType(t)));
+        },
+        unknown(obj) {
+            return new UnknownType(obj.name);
+        },
+    };
+    /**
+     * Only set when deserializing.
+     */
+    projectRoot;
+    oldIdToNewId = {};
+    oldFileIdToNewFileId = {};
+    project;
+    constructor(logger) {
+        this.logger = logger;
+    }
+    addDeserializer(de) {
+        insertPrioritySorted(this.deserializers, de);
+    }
+    /**
+     * Revive a single project into the structure it was originally created with.
+     * This is generally not appropriate for merging multiple projects since projects may
+     * contain reflections in their root, not inside a module.
+     */
+    reviveProject(name, projectObj, options) {
+        assert(this.deferred.length === 0, "Deserializer.defer was called when not deserializing");
+        if (!supportedSchemaVersions.includes(projectObj.schemaVersion)) {
+            throw new Error(`Attempted to deserialize version "${projectObj.schemaVersion}" JSON, which is not supported. Supported versions: ${supportedSchemaVersions.join(", ")}`);
+        }
+        const project = new ProjectReflection(name || projectObj.name, options.registry);
+        this.project = project;
+        this.projectRoot = options.projectRoot;
+        this.oldIdToNewId = { [projectObj.id]: project.id };
+        this.oldFileIdToNewFileId = {};
+        this.fromObject(project, projectObj);
+        const deferred = this.deferred;
+        this.deferred = [];
+        for (const def of deferred) {
+            def(project);
+        }
+        assert(this.deferred.length === 0, "Work may not be double deferred when deserializing.");
+        assert(this.activeReflection.length === 0, "Imbalanced reflection deserialization");
+        this.project = undefined;
+        this.projectRoot = undefined;
+        this.oldIdToNewId = {};
+        this.oldFileIdToNewFileId = {};
+        return project;
+    }
+    reviveProjects(name, projects, options) {
+        if (projects.length === 1 &&
+            !options.alwaysCreateEntryPointModule) {
+            return this.reviveProject(name, projects[0], options);
+        }
+        const project = new ProjectReflection(name, options.registry);
+        this.project = project;
+        this.projectRoot = options.projectRoot;
+        for (const proj of projects) {
+            assert(this.deferred.length === 0, "Deserializer.defer was called when not deserializing");
+            if (!supportedSchemaVersions.includes(proj.schemaVersion)) {
+                throw new Error(`Attempted to deserialize version "${proj.schemaVersion}" JSON, which is not supported. Supported versions: ${supportedSchemaVersions.join(", ")}`);
+            }
+            const projModule = new DeclarationReflection(proj.name, ReflectionKind.Module, project);
+            project.registerReflection(projModule, undefined, undefined);
+            project.addChild(projModule);
+            this.oldIdToNewId = { [proj.id]: projModule.id };
+            this.oldFileIdToNewFileId = {};
+            this.fromObject(projModule, proj);
+            const deferred = this.deferred;
+            this.deferred = [];
+            for (const def of deferred) {
+                def(project);
+            }
+            assert(this.deferred.length === 0, "Work may not be double deferred when deserializing.");
+            assert(this.activeReflection.length === 0, "Imbalanced reflection deserialization");
+        }
+        this.oldIdToNewId = {};
+        this.oldFileIdToNewFileId = {};
+        this.project = undefined;
+        this.projectRoot = undefined;
+        return project;
+    }
+    revive(source, creator) {
+        if (source) {
+            const revived = creator(source);
+            this.fromObject(revived, source);
+            return revived;
+        }
+    }
+    reviveMany(sourceArray, creator) {
+        if (sourceArray) {
+            return sourceArray.map((item) => {
+                const revived = creator(item);
+                this.fromObject(revived, item);
+                return revived;
+            });
+        }
+    }
+    reviveType(obj) {
+        return this.revive(obj, (o) => this.constructType(o));
+    }
+    constructReflection(obj) {
+        assert(this.activeReflection.length > 0);
+        const result = this.reflectionBuilders[obj.variant](this.activeReflection[this.activeReflection.length - 1], obj);
+        this.oldIdToNewId[obj.id] = result.id;
+        this.project.registerReflection(result, undefined, undefined);
+        return result;
+    }
+    constructType(obj) {
+        const result = this.typeBuilders[obj.type](obj, this);
+        return result;
+    }
+    fromObject(receiver, obj) {
+        if (receiver instanceof Reflection) {
+            this.activeReflection.push(receiver);
+        }
+        receiver.fromObject(this, obj);
+        for (const de of this.deserializers) {
+            if (de.supports(receiver, obj)) {
+                de.fromObject(receiver, obj);
+            }
+        }
+        if (receiver instanceof Reflection) {
+            this.activeReflection.pop();
+        }
+    }
+    /**
+     * Defers work until the initial pass of serialization has been completed.
+     * This can be used to set up references which cannot be immediately restored.
+     *
+     * May only be called when deserializing.
+     */
+    defer(cb) {
+        this.deferred.push(cb);
+    }
+}

package/dist/lib/serialization/events.d.ts

@@ -0,0 +1,17 @@
+import type { ProjectReflection } from "#models";
+import type { ProjectReflection as JSONProjectReflection } from "./schema.js";
+/**
+ * An event emitted by the {@link Serializer} class at the very beginning and
+ * ending of the a project serialization process.
+ *
+ * @see {@link Serializer.EVENT_BEGIN}
+ * @see {@link Serializer.EVENT_END}
+ */
+export declare class SerializeEvent {
+    /**
+     * The project the renderer is currently processing.
+     */
+    readonly project: ProjectReflection;
+    output: JSONProjectReflection | undefined;
+    constructor(project: ProjectReflection, output?: JSONProjectReflection);
+}

package/dist/lib/serialization/events.js

@@ -0,0 +1,18 @@
+/**
+ * An event emitted by the {@link Serializer} class at the very beginning and
+ * ending of the a project serialization process.
+ *
+ * @see {@link Serializer.EVENT_BEGIN}
+ * @see {@link Serializer.EVENT_END}
+ */
+export class SerializeEvent {
+    /**
+     * The project the renderer is currently processing.
+     */
+    project;
+    output;
+    constructor(project, output) {
+        this.project = project;
+        this.output = output;
+    }
+}

package/dist/lib/serialization/index.d.ts

@@ -0,0 +1,5 @@
+export type { SerializerComponent } from "./components.js";
+export { type Deserializable, Deserializer, type DeserializerComponent } from "./deserializer.js";
+export { SerializeEvent } from "./events.js";
+export * as JSONOutput from "./schema.js";
+export { Serializer, type SerializerEvents } from "./serializer.js";

package/dist/lib/serialization/index.js

@@ -0,0 +1,4 @@
+export { Deserializer } from "./deserializer.js";
+export { SerializeEvent } from "./events.js";
+export * as JSONOutput from "./schema.js";
+export { Serializer } from "./serializer.js";