typedoc 0.28.6 → 0.28.8

package/dist/lib/internationalization/locales/en.d.cts

@@ -66,6 +66,7 @@ declare const _default: {
     readonly not_all_search_group_boosts_used_0: "Not all groups specified in searchGroupBoosts were used in the documentation. The unused groups were:\n\t{0}";
     readonly comment_for_0_includes_categoryDescription_for_1_but_no_child_in_group: "Comment for {0} includes @categoryDescription for \"{1}\", but no child is placed in that category";
     readonly comment_for_0_includes_groupDescription_for_1_but_no_child_in_group: "Comment for {0} includes @groupDescription for \"{1}\", but no child is placed in that group";
+    readonly comment_for_0_specifies_1_as_sort_strategy_but_only_2_is_valid: "Comment for {0} specifies @sortStrategy with \"{1}\", which is an invalid sort strategy, the following are valid:\n\t{2}";
     readonly label_0_for_1_cannot_be_referenced: "The label \"{0}\" for {1} cannot be referenced with a declaration reference. Labels may only contain A-Z, 0-9, and _, and may not start with a number";
     readonly modifier_tag_0_is_mutually_exclusive_with_1_in_comment_for_2: "The modifier tag {0} is mutually exclusive with {1} in the comment for {2}";
     readonly signature_0_has_unused_param_with_name_1: "The signature {0} has an @param with name \"{1}\", which was not used";
@@ -258,13 +259,15 @@ declare const _default: {
     readonly useHostedBaseUrlForAbsoluteLinks_requires_hostedBaseUrl: "The useHostedBaseUrlForAbsoluteLinks option requires that hostedBaseUrl be set";
     readonly favicon_must_have_one_of_the_following_extensions_0: "Favicon must have one of the following extensions: {0}";
     readonly option_0_must_be_an_object: "The '{0}' option must be a non-array object";
+    readonly option_0_must_be_an_array_of_string: "The '{0}' option must be set to an array of strings";
+    readonly option_0_must_be_an_array_of_string_or_functions: "The '{0}' option must be set to an array of strings/functions";
     readonly option_0_must_be_a_function: "The '{0}' option must be a function";
     readonly option_0_must_be_object_with_urls: "{0} must be an object with string labels as keys and URL values";
     readonly visibility_filters_only_include_0: "visibilityFilters can only include the following non-@ keys: {0}";
     readonly visibility_filters_must_be_booleans: "All values of visibilityFilters must be booleans";
     readonly option_0_values_must_be_numbers: "All values of {0} must be numbers";
     readonly option_0_values_must_be_array_of_tags: "{0} must be an array of valid tag names";
-    readonly option_0_specified_1_but_only_2_is_valid: "{0} may only specify known values, and invalid values were provided ({1}). The valid sort strategies are:\n{2}";
+    readonly option_0_specified_1_but_only_2_is_valid: "{0} may only specify known values, and invalid values were provided ({1}). The valid options are:\n{2}";
     readonly option_outputs_must_be_array: "\"outputs\" option must be an array of { name: string, path: string, options?: TypeDocOptions } values.";
     readonly specified_output_0_has_not_been_defined: "Specified output \"{0}\" has not been defined.";
     readonly alert_note: "Note";

package/dist/lib/models/Comment.js

@@ -74,7 +74,7 @@ export class CommentTag {
      */
     similarTo(other) {
         return (this.tag === other.tag &&
-            this.name === other.tag &&
+            this.name === other.name &&
             Comment.combineDisplayParts(this.content) ===
                 Comment.combineDisplayParts(other.content));
     }

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

@@ -49,6 +49,7 @@ export declare abstract class ContainerReflection extends Reflection {
     getChildrenByKind(kind: ReflectionKind): DeclarationReflection[];
     addChild(child: Reflection): void;
     removeChild(child: DeclarationReflection | DocumentReflection): void;
+    isContainer(): this is ContainerReflection;
     traverse(callback: TraverseCallback): void;
     toObject(serializer: Serializer): JSONOutput.ContainerReflection;
     fromObject(de: Deserializer, obj: JSONOutput.ContainerReflection): void;

package/dist/lib/models/ContainerReflection.js

@@ -100,6 +100,9 @@ export class ContainerReflection extends Reflection {
             delete this.childrenIncludingDocuments;
         }
     }
+    isContainer() {
+        return true;
+    }
     traverse(callback) {
         for (const child of this.children?.slice() || []) {
             if (callback(child, TraverseProperty.Children) === false) {

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

@@ -10,6 +10,7 @@ import type { ParameterReflection } from "./ParameterReflection.js";
 import type { ReferenceReflection } from "./ReferenceReflection.js";
 import type { SignatureReflection } from "./SignatureReflection.js";
 import type { TypeParameterReflection } from "./TypeParameterReflection.js";
+import type { ContainerReflection } from "./ContainerReflection.js";
 /**
  * Reset the reflection id.
  *
@@ -193,6 +194,7 @@ export declare abstract class Reflection {
     isParameter(): this is ParameterReflection;
     isDocument(): this is DocumentReflection;
     isReference(): this is ReferenceReflection;
+    isContainer(): this is ContainerReflection;
     /**
      * Check if this reflection or any of its parents have been marked with the `@deprecated` tag.
      */

package/dist/lib/models/Reflection.js

@@ -419,6 +419,9 @@ let Reflection = (() => {
         isReference() {
             return this.variant === "reference";
         }
+        isContainer() {
+            return false;
+        }
         /**
          * Check if this reflection or any of its parents have been marked with the `@deprecated` tag.
          */

package/dist/lib/output/themes/default/partials/moduleReflection.js

@@ -8,7 +8,7 @@ export function moduleReflection(context, mod) {
         mod.hasComment() && (JSX.createElement("section", { class: "tsd-panel tsd-comment" },
             context.commentSummary(mod),
             context.commentTags(mod))),
-        mod.isDeclaration() && mod.kind === ReflectionKind.Module && mod.readme?.length && (JSX.createElement("section", { class: "tsd-panel tsd-typography" },
+        mod.isDeclaration() && mod.kind === ReflectionKind.Module && !!mod.readme?.length && (JSX.createElement("section", { class: "tsd-panel tsd-typography" },
             JSX.createElement(JSX.Raw, { html: context.markdown(mod.readme) }))),
         sections.map((section) => {
             if (!isNoneSection(section)) {

package/dist/lib/output/themes/default/partials/navigation.js

@@ -53,7 +53,7 @@ export function settings(context) {
                 context.icons.chevronDown(),
                 JSX.createElement("h3", null, i18n.theme_settings())),
             JSX.createElement("div", { class: "tsd-accordion-details" },
-                visibilityOptions.length && (JSX.createElement("div", { class: "tsd-filter-visibility" },
+                !!visibilityOptions.length && (JSX.createElement("div", { class: "tsd-filter-visibility" },
                     JSX.createElement("span", { class: "settings-label" }, i18n.theme_member_visibility()),
                     JSX.createElement("ul", { id: "tsd-filter-options" }, ...visibilityOptions))),
                 JSX.createElement("div", { class: "tsd-theme-toggle" },

package/dist/lib/output/themes/default/templates/hierarchy.js

@@ -21,7 +21,7 @@ function fullHierarchy(context, root, seen) {
         JSX.createElement("a", { href: context.urlTo(root) },
             context.reflectionIcon(root),
             root.name),
-        children.length && JSX.createElement("ul", null, children)));
+        !!children.length && JSX.createElement("ul", null, children)));
 }
 export function hierarchyTemplate(context, props) {
     const seen = new Set();

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

@@ -37,7 +37,7 @@ export declare const SCHEMA_VERSION = "2.0";
 export type ModelToObject<T> = [T] extends [Array<infer U>] ? ModelToObject<U>[] : [
     M.SomeType
 ] extends [T] ? SomeType : _ModelToObject<T>;
-type _ModelToObject<T> = T extends Primitive ? T : Required<T> extends Required<M.ReflectionGroup> ? ReflectionGroup : Required<T> extends Required<M.ReflectionCategory> ? ReflectionCategory : T extends M.ReflectionVariant[keyof M.ReflectionVariant] ? ReflectionVariantMap[T["variant"]] : T extends M.SomeType ? TypeKindMap[T["type"]] : T extends M.Type ? SomeType : T extends M.Comment ? Comment : T extends M.CommentTag ? CommentTag : T extends M.CommentDisplayPart ? CommentDisplayPart : T extends M.SourceReference ? SourceReference : T extends M.FileRegistry ? FileRegistry : never;
+type _ModelToObject<T> = T extends Primitive ? T : Required<T> extends Required<M.ReflectionGroup> ? ReflectionGroup : Required<T> extends Required<M.ReflectionCategory> ? ReflectionCategory : T extends M.ReflectionVariant[keyof M.ReflectionVariant] ? ReflectionVariantMap[T["variant"]] : T extends M.SomeType ? TypeKindMap[T["type"]] : T extends M.Type ? SomeType : T extends M.Comment ? Comment : T extends M.CommentTag ? CommentTag : T extends M.CommentDisplayPart ? CommentDisplayPart : T extends M.SourceReference ? SourceReference : T extends M.FileRegistry ? FileRegistry : T extends M.ReflectionSymbolId ? ReflectionSymbolId : never;
 type Primitive = string | number | undefined | null | boolean;
 type ToSerialized<T> = T extends Primitive ? T : T extends bigint ? {
     value: string;

package/dist/lib/utils/options/declaration.d.ts

@@ -2,8 +2,9 @@ import type { BundledTheme as ShikiTheme } from "@gerrit0/mini-shiki";
 import type { SortStrategy } from "../sort.js";
 import type { EntryPointStrategy } from "../entry-point.js";
 import type { ReflectionKind } from "../../models/kind.js";
-import { type GlobString, type LogLevel, type NeverIfInternal, type NormalizedPath, type NormalizedPathOrModule } from "#utils";
+import { type GlobString, type LogLevel, type NeverIfInternal, type NormalizedPath, type NormalizedPathOrModule, type NormalizedPathOrModuleOrFunction } from "#utils";
 import type { TranslationProxy } from "../../internationalization/internationalization.js";
+import type { Application } from "../../application.js";
 /** @enum */
 export declare const EmitStrategy: {
     readonly both: "both";
@@ -40,7 +41,7 @@ export declare const rootPackageOptions: readonly ["plugin", "packageOptions", "
  * @interface
  */
 export type TypeDocOptions = {
-    [K in keyof TypeDocOptionMap]?: unknown extends TypeDocOptionMap[K] ? unknown : TypeDocOptionMap[K] extends ManuallyValidatedOption<infer ManuallyValidated> ? ManuallyValidated : TypeDocOptionMap[K] extends NormalizedPath[] | NormalizedPathOrModule[] | GlobString[] ? string[] : TypeDocOptionMap[K] extends NormalizedPath ? string : TypeDocOptionMap[K] extends string | string[] | number | boolean ? TypeDocOptionMap[K] : TypeDocOptionMap[K] extends Record<string, boolean> ? Partial<TypeDocOptionMap[K]> | boolean : keyof TypeDocOptionMap[K] | TypeDocOptionMap[K][keyof TypeDocOptionMap[K]];
+    [K in keyof TypeDocOptionMap]?: unknown extends TypeDocOptionMap[K] ? unknown : TypeDocOptionMap[K] extends ManuallyValidatedOption<infer ManuallyValidated> ? ManuallyValidated : TypeDocOptionMap[K] extends NormalizedPath[] | NormalizedPathOrModule[] | NormalizedPathOrModuleOrFunction[] | GlobString[] ? string[] : TypeDocOptionMap[K] extends NormalizedPath ? string : TypeDocOptionMap[K] extends string | string[] | number | boolean ? TypeDocOptionMap[K] : TypeDocOptionMap[K] extends Record<string, boolean> ? Partial<TypeDocOptionMap[K]> | boolean : keyof TypeDocOptionMap[K] | TypeDocOptionMap[K][keyof TypeDocOptionMap[K]];
 };
 /**
  * Describes all TypeDoc specific options as returned by {@link Options.getValue}, this is
@@ -50,7 +51,7 @@ export type TypeDocOptions = {
  * @interface
  */
 export type TypeDocOptionValues = {
-    [K in keyof TypeDocOptionMap]: unknown extends TypeDocOptionMap[K] ? unknown : TypeDocOptionMap[K] extends ManuallyValidatedOption<infer ManuallyValidated> ? ManuallyValidated : TypeDocOptionMap[K] extends string | string[] | GlobString[] | number | boolean | Record<string, boolean> ? TypeDocOptionMap[K] : TypeDocOptionMap[K][keyof TypeDocOptionMap[K]];
+    [K in keyof TypeDocOptionMap]: unknown extends TypeDocOptionMap[K] ? unknown : TypeDocOptionMap[K] extends ManuallyValidatedOption<infer ManuallyValidated> ? ManuallyValidated : TypeDocOptionMap[K] extends string | string[] | GlobString[] | NormalizedPathOrModule[] | NormalizedPathOrModuleOrFunction[] | number | boolean | Record<string, boolean> ? TypeDocOptionMap[K] : TypeDocOptionMap[K][keyof TypeDocOptionMap[K]];
 };
 /**
  * Describes TypeDoc options suitable for setting within the `packageOptions` setting.
@@ -78,7 +79,7 @@ export interface TypeDocOptionMap {
     options: NormalizedPath;
     tsconfig: NormalizedPath;
     compilerOptions: unknown;
-    plugin: NormalizedPathOrModule[];
+    plugin: NormalizedPathOrModuleOrFunction[];
     lang: string;
     locales: ManuallyValidatedOption<Record<string, Record<string, string>>>;
     packageOptions: ManuallyValidatedOption<TypeDocPackageOptions>;
@@ -276,7 +277,7 @@ export type JsDocCompatibility = {
 /**
  * Converts a given TypeDoc option key to the type of the declaration expected.
  */
-export type KeyToDeclaration<K extends keyof TypeDocOptionMap> = TypeDocOptionMap[K] extends boolean ? BooleanDeclarationOption : TypeDocOptionMap[K] extends string | NormalizedPath ? StringDeclarationOption : TypeDocOptionMap[K] extends number ? NumberDeclarationOption : TypeDocOptionMap[K] extends GlobString[] ? GlobArrayDeclarationOption : TypeDocOptionMap[K] extends string[] | NormalizedPath[] | NormalizedPathOrModule[] ? ArrayDeclarationOption : unknown extends TypeDocOptionMap[K] ? MixedDeclarationOption | ObjectDeclarationOption : TypeDocOptionMap[K] extends ManuallyValidatedOption<unknown> ? (MixedDeclarationOption & {
+export type KeyToDeclaration<K extends keyof TypeDocOptionMap> = TypeDocOptionMap[K] extends boolean ? BooleanDeclarationOption : TypeDocOptionMap[K] extends string | NormalizedPath ? StringDeclarationOption : TypeDocOptionMap[K] extends number ? NumberDeclarationOption : TypeDocOptionMap[K] extends GlobString[] ? GlobArrayDeclarationOption : TypeDocOptionMap[K] extends string[] | NormalizedPath[] | NormalizedPathOrModule[] | NormalizedPathOrModuleOrFunction[] ? ArrayDeclarationOption : unknown extends TypeDocOptionMap[K] ? MixedDeclarationOption | ObjectDeclarationOption : TypeDocOptionMap[K] extends ManuallyValidatedOption<unknown> ? (MixedDeclarationOption & {
     validate(value: unknown, i18n: TranslationProxy): void;
 }) | (ObjectDeclarationOption & {
     validate(value: unknown, i18n: TranslationProxy): void;
@@ -306,20 +307,26 @@ export declare enum ParameterType {
     PathArray = 8,
     /**
      * Resolved according to the config directory if it starts with `.`
+     * @deprecated since 0.28.8, will be removed in 0.29
      */
     ModuleArray = 9,
+    /**
+     * Resolved according to the config directory if it starts with `.`
+     * @internal - only intended for use with the plugin option
+     */
+    PluginArray = 10,
     /**
      * Relative to the config directory.
      */
-    GlobArray = 10,
+    GlobArray = 11,
     /**
      * An object which partially merges user-set values into the defaults.
      */
-    Object = 11,
+    Object = 12,
     /**
      * An object with true/false flags
      */
-    Flags = 12
+    Flags = 13
 }
 export interface DeclarationOptionBase {
     /**
@@ -401,7 +408,7 @@ export interface BooleanDeclarationOption extends DeclarationOptionBase {
     defaultValue?: boolean;
 }
 export interface ArrayDeclarationOption extends DeclarationOptionBase {
-    type: ParameterType.Array | ParameterType.PathArray | ParameterType.ModuleArray;
+    type: ParameterType.Array | ParameterType.PathArray | ParameterType.ModuleArray | ParameterType.PluginArray;
     /**
      * If not specified defaults to an empty array.
      */
@@ -482,6 +489,7 @@ export interface ParameterTypeToOptionTypeMap {
     [ParameterType.Array]: string[];
     [ParameterType.PathArray]: NormalizedPath[];
     [ParameterType.ModuleArray]: NormalizedPathOrModule[];
+    [ParameterType.PluginArray]: Array<NormalizedPathOrModule | ((app: Application) => void | Promise<void>)>;
     [ParameterType.GlobArray]: GlobString[];
     [ParameterType.Flags]: Record<string, boolean>;
     [ParameterType.Map]: unknown;

package/dist/lib/utils/options/declaration.js

@@ -112,21 +112,45 @@ export var ParameterType;
     ParameterType[ParameterType["PathArray"] = 8] = "PathArray";
     /**
      * Resolved according to the config directory if it starts with `.`
+     * @deprecated since 0.28.8, will be removed in 0.29
      */
     ParameterType[ParameterType["ModuleArray"] = 9] = "ModuleArray";
+    /**
+     * Resolved according to the config directory if it starts with `.`
+     * @internal - only intended for use with the plugin option
+     */
+    ParameterType[ParameterType["PluginArray"] = 10] = "PluginArray";
     /**
      * Relative to the config directory.
      */
-    ParameterType[ParameterType["GlobArray"] = 10] = "GlobArray";
+    ParameterType[ParameterType["GlobArray"] = 11] = "GlobArray";
     /**
      * An object which partially merges user-set values into the defaults.
      */
-    ParameterType[ParameterType["Object"] = 11] = "Object";
+    ParameterType[ParameterType["Object"] = 12] = "Object";
     /**
      * An object with true/false flags
      */
-    ParameterType[ParameterType["Flags"] = 12] = "Flags";
+    ParameterType[ParameterType["Flags"] = 13] = "Flags";
 })(ParameterType || (ParameterType = {}));
+function toStringArray(value, option) {
+    if (Array.isArray(value) && value.every(v => typeof v === "string")) {
+        return value;
+    }
+    else if (typeof value === "string") {
+        return [value];
+    }
+    throw new Error(i18n.option_0_must_be_an_array_of_string(option.name));
+}
+function toStringOrFunctionArray(value, option) {
+    if (Array.isArray(value) && value.every(v => typeof v === "string" || typeof v === "function")) {
+        return value;
+    }
+    else if (typeof value === "string") {
+        return [value];
+    }
+    throw new Error(i18n.option_0_must_be_an_array_of_string_or_functions(option.name));
+}
 const converters = {
     [ParameterType.String](value, option) {
         // eslint-disable-next-line @typescript-eslint/no-base-to-string
@@ -164,40 +188,28 @@ const converters = {
         return !!value;
     },
     [ParameterType.Array](value, option) {
-        let strArrValue = [];
-        if (Array.isArray(value)) {
-            strArrValue = value.map(String);
-        }
-        else if (typeof value === "string") {
-            strArrValue = [value];
-        }
+        const strArrValue = toStringArray(value, option);
         option.validate?.(strArrValue);
         return strArrValue;
     },
     [ParameterType.PathArray](value, option, configPath) {
-        let strArrValue = [];
-        if (Array.isArray(value)) {
-            strArrValue = value.map(String);
-        }
-        else if (typeof value === "string") {
-            strArrValue = [value];
-        }
+        const strArrValue = toStringArray(value, option);
         const normalized = strArrValue.map((path) => normalizePath(resolve(configPath, path)));
         option.validate?.(normalized);
         return normalized;
     },
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
     [ParameterType.ModuleArray](value, option, configPath) {
-        let strArrValue = [];
-        if (Array.isArray(value)) {
-            strArrValue = value.map(String);
-        }
-        else if (typeof value === "string") {
-            strArrValue = [value];
-        }
+        const strArrValue = toStringArray(value, option);
         const resolved = resolveModulePaths(strArrValue, configPath);
         option.validate?.(resolved);
         return resolved;
     },
+    [ParameterType.PluginArray](value, option, configPath) {
+        const arrayValue = toStringOrFunctionArray(value, option);
+        const resolved = arrayValue.map(plugin => typeof plugin === "function" ? plugin : resolveModulePath(plugin, configPath));
+        return resolved;
+    },
     [ParameterType.GlobArray](value, option, configPath) {
         const toGlobString = (v) => {
             const s = String(v);
@@ -210,7 +222,8 @@ const converters = {
             }
             return createGlobString(configPath, s);
         };
-        const globs = Array.isArray(value) ? value.map(toGlobString) : [toGlobString(value)];
+        const strArrValue = toStringArray(value, option);
+        const globs = strArrValue.map(toGlobString);
         option.validate?.(globs);
         return globs;
     },
@@ -329,12 +342,19 @@ const defaultGetters = {
     [ParameterType.PathArray](option) {
         return (option.defaultValue?.map((value) => normalizePath(resolve(process.cwd(), value))) ?? []);
     },
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
     [ParameterType.ModuleArray](option) {
         if (option.defaultValue) {
             return resolveModulePaths(option.defaultValue, process.cwd());
         }
         return [];
     },
+    [ParameterType.PluginArray](option) {
+        if (option.defaultValue) {
+            return resolveModulePaths(option.defaultValue, process.cwd());
+        }
+        return [];
+    },
     [ParameterType.GlobArray](option) {
         return (option.defaultValue ?? []).map(g => createGlobString(normalizePath(process.cwd()), g));
     },
@@ -347,12 +367,13 @@ export function getDefaultValue(option) {
     return getters[option.type ?? ParameterType.String](option);
 }
 function resolveModulePaths(modules, configPath) {
-    return modules.map((path) => {
-        if (path.startsWith(".")) {
-            return normalizePath(resolve(configPath, path));
-        }
-        return normalizePath(path);
-    });
+    return modules.map(path => resolveModulePath(path, configPath));
+}
+function resolveModulePath(path, configPath) {
+    if (path.startsWith(".")) {
+        return normalizePath(resolve(configPath, path));
+    }
+    return normalizePath(path);
 }
 function isTsNumericEnum(map) {
     return Object.values(map).every((key) => map[map[key]] === key);

package/dist/lib/utils/options/readers/arguments.js

@@ -4,7 +4,9 @@ import { i18n } from "#utils";
 const ARRAY_OPTION_TYPES = new Set([
     ParameterType.Array,
     ParameterType.PathArray,
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
     ParameterType.ModuleArray,
+    ParameterType.PluginArray,
     ParameterType.GlobArray,
 ]);
 /**

package/dist/lib/utils/options/sources/typedoc.js

@@ -740,10 +740,7 @@ export function addTypeDocOptions(options) {
         type: ParameterType.Array,
         defaultValue: OptionDefaults.sort,
         validate(value) {
-            const invalid = new Set(value);
-            for (const v of SORT_STRATEGIES) {
-                invalid.delete(v);
-            }
+            const invalid = setDifference(value, SORT_STRATEGIES);
             if (invalid.size !== 0) {
                 throw new Error(i18n.option_0_specified_1_but_only_2_is_valid("sort", Array.from(invalid).join(", "), SORT_STRATEGIES.join(", ")));
             }
@@ -804,7 +801,7 @@ export function addTypeDocOptions(options) {
     options.addDeclaration({
         name: "plugin",
         help: () => i18n.help_plugin(),
-        type: ParameterType.ModuleArray,
+        type: ParameterType.PluginArray,
     });
     options.addDeclaration({
         name: "logLevel",

package/dist/lib/utils/options/tsdoc-defaults.d.ts

@@ -1,5 +1,5 @@
 export declare const tsdocBlockTags: readonly ["@defaultValue", "@deprecated", "@example", "@param", "@privateRemarks", "@remarks", "@returns", "@see", "@throws", "@typeParam"];
-export declare const blockTags: readonly ["@defaultValue", "@deprecated", "@example", "@param", "@privateRemarks", "@remarks", "@returns", "@see", "@throws", "@typeParam", "@author", "@callback", "@category", "@categoryDescription", "@default", "@document", "@extends", "@augments", "@yields", "@group", "@groupDescription", "@import", "@inheritDoc", "@jsx", "@license", "@module", "@mergeModuleWith", "@prop", "@property", "@return", "@satisfies", "@since", "@template", "@type", "@typedef", "@summary", "@preventInline", "@inlineType", "@preventExpand", "@expandType"];
+export declare const blockTags: readonly ["@defaultValue", "@deprecated", "@example", "@param", "@privateRemarks", "@remarks", "@returns", "@see", "@throws", "@typeParam", "@author", "@callback", "@category", "@categoryDescription", "@default", "@document", "@extends", "@augments", "@yields", "@group", "@groupDescription", "@import", "@inheritDoc", "@jsx", "@license", "@module", "@mergeModuleWith", "@prop", "@property", "@return", "@satisfies", "@since", "@sortStrategy", "@template", "@type", "@typedef", "@summary", "@preventInline", "@inlineType", "@preventExpand", "@expandType"];
 export declare const tsdocInlineTags: readonly ["@link", "@inheritDoc", "@label"];
 export declare const inlineTags: readonly ["@link", "@inheritDoc", "@label", "@linkcode", "@linkplain", "@include", "@includeCode"];
 export declare const tsdocModifierTags: readonly ["@alpha", "@beta", "@eventProperty", "@experimental", "@internal", "@override", "@packageDocumentation", "@public", "@readonly", "@sealed", "@virtual"];

package/dist/lib/utils/options/tsdoc-defaults.js

@@ -35,6 +35,7 @@ export const blockTags = [
     "@return",
     "@satisfies",
     "@since",
+    "@sortStrategy",
     "@template", // Alias for @typeParam
     "@type",
     "@typedef",

package/dist/lib/utils/plugins.d.ts

@@ -1,2 +1,3 @@
 import type { Application } from "../application.js";
-export declare function loadPlugins(app: Application, plugins: readonly string[]): Promise<void>;
+import { type NormalizedPathOrModuleOrFunction } from "#utils";
+export declare function loadPlugins(app: Application, plugins: readonly NormalizedPathOrModuleOrFunction[]): Promise<void>;

package/dist/lib/utils/plugins.js

@@ -6,27 +6,33 @@ export async function loadPlugins(app, plugins) {
     for (const plugin of plugins) {
         const pluginDisplay = getPluginDisplayName(plugin);
         try {
-            let instance;
-            // Try importing first to avoid warnings about requiring ESM being experimental.
-            // If that fails due to importing a directory, fall back to require.
-            try {
-                // On Windows, we need to ensure this path is a file path.
-                // Or we'll get ERR_UNSUPPORTED_ESM_URL_SCHEME
-                const esmPath = isAbsolute(plugin)
-                    ? pathToFileURL(plugin).toString()
-                    : plugin;
-                instance = await import(esmPath);
+            let initFunction;
+            if (typeof plugin === "function") {
+                initFunction = plugin;
             }
-            catch (error) {
-                if (error.code === "ERR_UNSUPPORTED_DIR_IMPORT") {
-                    // eslint-disable-next-line @typescript-eslint/no-require-imports
-                    instance = require(plugin);
+            else {
+                let instance;
+                // Try importing first to avoid warnings about requiring ESM being experimental.
+                // If that fails due to importing a directory, fall back to require.
+                try {
+                    // On Windows, we need to ensure this path is a file path.
+                    // Or we'll get ERR_UNSUPPORTED_ESM_URL_SCHEME
+                    const esmPath = isAbsolute(plugin)
+                        ? pathToFileURL(plugin).toString()
+                        : plugin;
+                    instance = await import(esmPath);
                 }
-                else {
-                    throw error;
+                catch (error) {
+                    if (error.code === "ERR_UNSUPPORTED_DIR_IMPORT") {
+                        // eslint-disable-next-line @typescript-eslint/no-require-imports
+                        instance = require(plugin);
+                    }
+                    else {
+                        throw error;
+                    }
                 }
+                initFunction = instance.load;
             }
-            const initFunction = instance.load;
             if (typeof initFunction === "function") {
                 await initFunction(app);
                 app.logger.info(i18n.loaded_plugin_0(pluginDisplay));
@@ -44,6 +50,9 @@ export async function loadPlugins(app, plugins) {
     }
 }
 function getPluginDisplayName(plugin) {
+    if (typeof plugin === "function") {
+        return plugin.name || "function";
+    }
     const path = nicePath(plugin);
     if (path.startsWith("./node_modules/")) {
         return path.substring("./node_modules/".length);

package/dist/lib/utils/sort.d.ts

@@ -7,4 +7,5 @@ import type { Options } from "./options/index.js";
 import type { DocumentReflection } from "../models/index.js";
 export declare const SORT_STRATEGIES: readonly ["source-order", "alphabetical", "alphabetical-ignoring-documents", "enum-value-ascending", "enum-value-descending", "enum-member-source-order", "static-first", "instance-first", "visibility", "required-first", "kind", "external-last", "documents-first", "documents-last"];
 export type SortStrategy = (typeof SORT_STRATEGIES)[number];
-export declare function getSortFunction(opts: Options): (reflections: (DeclarationReflection | DocumentReflection)[]) => void;
+export declare function isValidSortStrategy(strategy: string): strategy is SortStrategy;
+export declare function getSortFunction(opts: Options, strategies?: readonly SortStrategy[]): (reflections: (DeclarationReflection | DocumentReflection)[]) => void;

package/dist/lib/utils/sort.js

@@ -124,7 +124,10 @@ const sorts = {
             b.kindOf(ReflectionKind.Document));
     },
 };
-export function getSortFunction(opts) {
+export function isValidSortStrategy(strategy) {
+    return SORT_STRATEGIES.includes(strategy);
+}
+export function getSortFunction(opts, strategies = opts.getValue("sort")) {
     const kindSortOrder = opts
         .getValue("kindSortOrder")
         .map((k) => ReflectionKind[k]);
@@ -133,7 +136,6 @@ export function getSortFunction(opts) {
             kindSortOrder.push(ReflectionKind[kind]);
         }
     }
-    const strategies = opts.getValue("sort");
     const data = { kindSortOrder };
     return function sortReflections(reflections) {
         reflections.sort((a, b) => {

package/dist/lib/utils-common/array.d.ts

@@ -50,9 +50,8 @@ export declare function zip<T extends Iterable<any>[]>(...args: T): Iterable<{
     [K in keyof T]: T[K] extends Iterable<infer U> ? U : T[K];
 }>;
 export declare function filterMap<T, U>(iter: Iterable<T> | undefined, fn: (item: T) => U | undefined): U[];
-export declare function firstDefined<T, U>(array: readonly T[] | undefined, callback: (element: T, index: number) => U | undefined): U | undefined;
+export declare function firstDefined<T, U>(array: readonly T[], callback: (element: T, index: number) => U | undefined): U | undefined;
 export declare function filter<T>(array: readonly T[] | undefined, predicate: (value: T, index: number, array: readonly T[]) => boolean): readonly T[];
 export declare function aggregate<T>(arr: T[], fn: (item: T) => number): number;
-export declare function aggregateWithJoiner<T>(arr: T[], fn: (item: T) => number, joiner: string): number;
 export declare function joinArray<T>(arr: readonly T[] | undefined, joiner: string, mapper: (item: T) => string): string;
 export declare function maxElementByScore<T>(arr: readonly T[], score: (a: T) => number): T | undefined;

package/dist/lib/utils-common/array.js

@@ -115,9 +115,6 @@ export function filterMap(iter, fn) {
     return result;
 }
 export function firstDefined(array, callback) {
-    if (array === undefined) {
-        return undefined;
-    }
     for (let i = 0; i < array.length; i++) {
         const result = callback(array[i], i);
         if (result !== undefined) {
@@ -132,10 +129,6 @@ export function filter(array, predicate) {
 export function aggregate(arr, fn) {
     return arr.reduce((sum, it) => sum + fn(it), 0);
 }
-export function aggregateWithJoiner(arr, fn, joiner) {
-    return (arr.reduce((sum, it) => sum + fn(it), 0) +
-        (arr.length - 1) * joiner.length);
-}
 export function joinArray(arr, joiner, mapper) {
     if (arr?.length) {
         return arr.map(mapper).join(joiner);

package/dist/lib/utils-common/jsx.elements.d.ts

@@ -131,7 +131,7 @@ export interface JsxElement {
     props: object | null;
     children: JsxChildren[];
 }
-export type JsxChildren = JsxElement | string | number | null | undefined | JsxChildren[];
+export type JsxChildren = JsxElement | string | number | boolean | bigint | null | undefined | JsxChildren[];
 /**
  * The common properties that may appear on any HTML element.
  *

package/dist/lib/utils-common/jsx.js

@@ -71,7 +71,7 @@ export function setRenderSettings(options) {
     renderPretty = options.pretty;
 }
 export function renderElement(element) {
-    if (!element || typeof element === "boolean") {
+    if (!element) {
         return "";
     }
     const { tag, props, children } = element;
@@ -128,12 +128,12 @@ export function renderElement(element) {
     return html;
     function renderChildren(children) {
         for (const child of children) {
-            if (!child)
+            if (typeof child === "boolean")
                 continue;
             if (Array.isArray(child)) {
                 renderChildren(child);
             }
-            else if (typeof child === "string" || typeof child === "number") {
+            else if (typeof child === "string" || typeof child === "number" || typeof child === "bigint") {
                 html += escapeHtml(child.toString());
             }
             else {
@@ -148,7 +148,7 @@ export function renderElement(element) {
  * @internal
  */
 export function renderElementToText(element) {
-    if (!element || typeof element === "boolean") {
+    if (!element) {
         return "";
     }
     const { tag, props, children } = element;
@@ -170,12 +170,13 @@ export function renderElementToText(element) {
     return html;
     function renderChildren(children) {
         for (const child of children) {
-            if (!child)
+            if (typeof child === "boolean")
                 continue;
             if (Array.isArray(child)) {
                 renderChildren(child);
             }
-            else if (typeof child === "string" || typeof child === "number") {
+            else if (typeof child === "string" || typeof child === "number" || typeof child === "bigint") {
+                // Turn non-breaking spaces into regular spaces
                 html += child.toString().replaceAll("\u00A0", " ");
             }
             else {

package/dist/lib/utils-common/map.d.ts

@@ -15,7 +15,7 @@ export declare class StableKeyMap<K extends {
     has(key: K): boolean;
     clear(): void;
     delete(key: K): boolean;
-    forEach(callbackfn: (value: V, key: K, map: Map<K, V>) => void, thisArg?: any): void;
+    forEach(callbackfn: (value: V, key: K, map: StableKeyMap<K, V>) => void, thisArg?: any): void;
     entries(): IterableIterator<[K, V]>;
     keys(): IterableIterator<K>;
     values(): IterableIterator<V>;