typedoc 0.28.0-beta.2 → 0.28.1

package/dist/index.d.ts

@@ -37,7 +37,7 @@ export * from "./lib/models/index.js";
 /** @primaryExport */
 export * as Configuration from "./lib/utils/options/index.js";
 export { BaseRouter, CategoryRouter, DefaultTheme, DefaultThemeRenderContext, GroupRouter, IndexEvent, KindDirRouter, KindRouter, MarkdownEvent, PageEvent, PageKind, Renderer, RendererEvent, Slugger, StructureDirRouter, StructureRouter, Theme, } from "./lib/output/index.js";
-export type { Icons, NavigationElement, PageDefinition, PageHeading, RendererEvents, RendererHooks, RenderTemplate, Router, } from "./lib/output/index.js";
+export type { Icons, NavigationElement, PageDefinition, PageHeading, RendererEvents, RendererHooks, RenderTemplate, Router, RouterTarget, } from "./lib/output/index.js";
 export { Outputs } from "./lib/output/output.js";
 export { ArgumentsReader, CommentStyle, EntryPointStrategy, normalizePath, Option, OptionDefaults, Options, PackageJsonReader, ParameterHint, ParameterType, TSConfigReader, TypeDocReader, ValidatingFileRegistry, } from "./lib/utils/index.js";
 export type { ArrayDeclarationOption, BooleanDeclarationOption, DeclarationOption, DeclarationOptionBase, DeclarationOptionToOptionType, DocumentationEntryPoint, FancyConsoleLogger, FlagsDeclarationOption, JsDocCompatibility, KeyToDeclaration, ManuallyValidatedOption, MapDeclarationOption, MixedDeclarationOption, NumberDeclarationOption, ObjectDeclarationOption, OptionsReader, OutputSpecification, ParameterTypeToOptionTypeMap, SortStrategy, StringDeclarationOption, TypeDocOptionMap, TypeDocOptions, TypeDocOptionValues, ValidationOptions, } from "./lib/utils/index.js";

package/dist/lib/application.d.ts

@@ -102,7 +102,7 @@ export declare class Application extends AbstractComponent<Application, Applicat
     /**
      * Initialize TypeDoc, loading plugins if applicable.
      */
-    static bootstrapWithPlugins(options?: Partial<TypeDocOptions>, readers?: readonly OptionsReader[]): Promise<Application>;
+    static bootstrapWithPlugins(options?: TypeDocOptions, readers?: readonly OptionsReader[]): Promise<Application>;
     /**
      * Initialize TypeDoc without loading plugins.
      *
@@ -115,10 +115,10 @@ export declare class Application extends AbstractComponent<Application, Applicat
      * @param options Options to set during initialization
      * @param readers Option readers to use to discover options from config files.
      */
-    static bootstrap(options?: Partial<TypeDocOptions>, readers?: readonly OptionsReader[]): Promise<Application>;
+    static bootstrap(options?: TypeDocOptions, readers?: readonly OptionsReader[]): Promise<Application>;
     private _bootstrap;
     /** @internal */
-    setOptions(options: Partial<TypeDocOptions>, reportErrors?: boolean): boolean;
+    setOptions(options: TypeDocOptions, reportErrors?: boolean): boolean;
     /**
      * Return the path to the TypeScript compiler.
      */

package/dist/lib/converter/converter.d.ts

@@ -189,8 +189,20 @@ export declare class Converter extends AbstractComponent<Application, ConverterE
     resolveExternalLink(ref: DeclarationReference, refl: Reflection, part: CommentDisplayPart | undefined, symbolId: ReflectionSymbolId | undefined): ExternalResolveResult | string | undefined;
     resolveLinks(comment: Comment, owner: Reflection): void;
     resolveLinks(parts: readonly CommentDisplayPart[], owner: Reflection): CommentDisplayPart[];
+    /**
+     * Permit deferred conversion steps to take place. Until this is called, {@link deferConversion}
+     * will throw if used.
+     * @since 0.28.1
+     */
+    permitDeferredConversion(): void;
+    /**
+     * Finalize deferred conversion, must be called by the caller of {@link permitDeferredConversion}
+     * @since 0.28.1
+     */
+    finalizeDeferredConversion(): void;
     /**
      * Defer a conversion step until later. This may only be called during conversion.
+     * @since 0.28.0
      */
     deferConversion(cb: () => void): void;
     /**

package/dist/lib/converter/converter.js

@@ -372,8 +372,33 @@ let Converter = (() => {
                 return resolvePartLinks(owner, comment, (ref, part, refl, id) => this.resolveExternalLink(ref, part, refl, id), { preserveLinkText: this.preserveLinkText });
             }
         }
+        /**
+         * Permit deferred conversion steps to take place. Until this is called, {@link deferConversion}
+         * will throw if used.
+         * @since 0.28.1
+         */
+        permitDeferredConversion() {
+            ok(!this._deferPermitted, "Attempted to allow deferred conversion when already permitted");
+            this._deferPermitted = true;
+        }
+        /**
+         * Finalize deferred conversion, must be called by the caller of {@link permitDeferredConversion}
+         * @since 0.28.1
+         */
+        finalizeDeferredConversion() {
+            this.application.logger.verbose(`Have ${this._defer.length} initial deferred tasks`);
+            let count = 0;
+            while (this._defer.length) {
+                ++count;
+                const first = this._defer.shift();
+                first();
+            }
+            this.application.logger.verbose(`Ran ${count} total deferred tasks`);
+            this._deferPermitted = false;
+        }
         /**
          * Defer a conversion step until later. This may only be called during conversion.
+         * @since 0.28.0
          */
         deferConversion(cb) {
             ok(this._deferPermitted, "Attempted to defer conversion when not permitted");
@@ -386,8 +411,7 @@ let Converter = (() => {
          * @returns An array containing all errors generated by the TypeScript compiler.
          */
         compile(entryPoints, context) {
-            ok(!this._deferPermitted);
-            this._deferPermitted = true;
+            this.permitDeferredConversion();
             let createModuleReflections = entryPoints.length > 1;
             if (!createModuleReflections) {
                 const opts = this.application.options;
@@ -404,15 +428,7 @@ let Converter = (() => {
                 entryContext.setActiveProgram(entry.program);
                 this.convertExports(entryContext, entry, createModuleReflections);
             }
-            this.application.logger.verbose(`Have ${this._defer.length} initial deferred tasks`);
-            let count = 0;
-            while (this._defer.length) {
-                ++count;
-                const first = this._defer.shift();
-                first();
-            }
-            this.application.logger.verbose(`Ran ${count} total deferred tasks`);
-            this._deferPermitted = false;
+            this.finalizeDeferredConversion();
         }
         convertExports(context, entryPoint, createModuleReflections) {
             const node = entryPoint.sourceFile;

package/dist/lib/converter/plugins/IncludePlugin.js

@@ -1,9 +1,8 @@
 import path from "path";
-import fs from "fs";
 import { ConverterComponent } from "../components.js";
 import { ConverterEvents } from "../converter-events.js";
 import { MinimalSourceFile } from "#utils";
-import { isFile } from "../../utils/fs.js";
+import { isFile, readFile } from "../../utils/fs.js";
 import { dedent, escapeRegExp, i18n } from "#utils";
 import { normalizePath } from "#node-utils";
 /**
@@ -51,7 +50,7 @@ export class IncludePlugin extends ConverterComponent {
                 this.logger.error(i18n.include_0_in_1_specified_2_circular_include_3(part.tag, refl.getFriendlyFullName(), part.text, included.join("\n\t")));
             }
             else if (isFile(file)) {
-                const text = fs.readFileSync(file, "utf-8");
+                const text = readFile(file).replaceAll("\r\n", "\n");
                 const ext = path.extname(file).substring(1);
                 const includedText = regionTarget
                     ? this.getRegions(refl, file, ext, part.text, text, regionTarget, part.tag, part.tag === "@includeCode")

package/dist/lib/converter/symbols.js

@@ -586,7 +586,8 @@ function convertVariable(context, symbol, exportSymbol) {
     setModifiers(symbol, declaration, reflection);
     reflection.defaultValue = convertDefaultValue(declaration);
     context.finalizeDeclarationReflection(reflection);
-    return ts.SymbolFlags.Property;
+    // Exclude ValueModule to handle `module.exports = []`
+    return ts.SymbolFlags.Property | ts.SymbolFlags.ValueModule;
 }
 function isEnumLike(checker, type, location) {
     if (!location || !hasAllFlags(type.flags, ts.TypeFlags.Object)) {

package/dist/lib/converter/types.js

@@ -122,7 +122,7 @@ const arrayConverter = {
         return new ArrayType(convertType(context, node.elementType));
     },
     convertType(context, type) {
-        const params = context.checker.getTypeArguments(type);
+        const params = type.aliasTypeArguments || context.checker.getTypeArguments(type);
         // This is *almost* always true... except for when this type is in the constraint of a type parameter see GH#1408
         // assert(params.length === 1);
         assert(params.length > 0);

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

@@ -415,7 +415,7 @@ export declare class ReflectionType extends Type {
     readonly type = "reflection";
     constructor(declaration: DeclarationReflection);
     protected getTypeString(): string;
-    needsParenthesis(): boolean;
+    needsParenthesis(where: TypeContext): boolean;
     toObject(serializer: Serializer): JSONOutput.ReflectionType;
 }
 /**

package/dist/lib/models/types.js

@@ -917,7 +917,13 @@ export class ReflectionType extends Type {
         }
         return `{ ${parts.join("; ")} }`;
     }
-    needsParenthesis() {
+    needsParenthesis(where) {
+        if (this.declaration.children || this.declaration.indexSignatures) {
+            return false;
+        }
+        if (this.declaration.signatures?.length === 1) {
+            return where === TypeContext.arrayElement || where === TypeContext.unionElement;
+        }
         return false;
     }
     toObject(serializer) {

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

@@ -1,5 +1,5 @@
 import { AbstractComponent } from "../utils/component.js";
-import type { ProjectReflection, Reflection } from "../models/index.js";
+import type { ProjectReflection } from "../models/index.js";
 import type { Renderer } from "./renderer.js";
 import { PageEvent, RendererEvent } from "./events.js";
 export declare abstract class RendererComponent extends AbstractComponent<Renderer, {}> {
@@ -15,7 +15,7 @@ export declare abstract class ContextAwareRendererComponent extends RendererComp
     /**
      * The reflection that is currently processed.
      */
-    protected page?: PageEvent<Reflection>;
+    protected page?: PageEvent;
     /**
      * The url of the document that is being currently generated.
      * Set when a page begins rendering.
@@ -49,5 +49,5 @@ export declare abstract class ContextAwareRendererComponent extends RendererComp
      *
      * @param page  An event object describing the current render operation.
      */
-    protected onBeginPage(page: PageEvent<Reflection>): void;
+    protected onBeginPage(page: PageEvent): void;
 }

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

@@ -1,6 +1,6 @@
 import type { ProjectReflection } from "../models/ProjectReflection.js";
-import type { DeclarationReflection, DocumentReflection, ReflectionKind } from "../models/index.js";
-import type { PageDefinition, PageKind } from "./router.js";
+import { type DeclarationReflection, type DocumentReflection, Reflection, type ReflectionKind } from "../models/index.js";
+import type { PageDefinition, PageKind, RouterTarget } from "./router.js";
 /**
  * An event emitted by the {@link Renderer} class at the very beginning and
  * ending of the entire rendering process.
@@ -47,7 +47,7 @@ export interface PageHeading {
  * @see {@link Renderer.EVENT_BEGIN_PAGE}
  * @see {@link Renderer.EVENT_END_PAGE}
  */
-export declare class PageEvent<out Model = unknown> {
+export declare class PageEvent<out Model extends RouterTarget = RouterTarget> {
     /**
      * The project the renderer is currently processing.
      */
@@ -102,6 +102,7 @@ export declare class PageEvent<out Model = unknown> {
      */
     static readonly END = "endPage";
     constructor(model: Model);
+    isReflectionEvent(): this is PageEvent<Reflection>;
 }
 /**
  * An event emitted when markdown is being parsed. Allows other plugins to manipulate the result.

package/dist/lib/output/events.js

@@ -1,3 +1,4 @@
+import { Reflection, } from "../models/index.js";
 /**
  * An event emitted by the {@link Renderer} class at the very beginning and
  * ending of the entire rendering process.
@@ -106,6 +107,9 @@ export class PageEvent {
     constructor(model) {
         this.model = model;
     }
+    isReflectionEvent() {
+        return this.model instanceof Reflection;
+    }
 }
 /**
  * An event emitted when markdown is being parsed. Allows other plugins to manipulate the result.

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

@@ -6,4 +6,4 @@ export { DefaultTheme, type NavigationElement, type RenderTemplate } from "./the
 export { DefaultThemeRenderContext } from "./themes/default/DefaultThemeRenderContext.js";
 export type { Icons } from "./themes/default/partials/icon.js";
 export { Slugger } from "./themes/default/Slugger.js";
-export { BaseRouter, CategoryRouter, GroupRouter, KindDirRouter, KindRouter, type PageDefinition, PageKind, type Router, StructureDirRouter, StructureRouter, } from "./router.js";
+export { BaseRouter, CategoryRouter, GroupRouter, KindDirRouter, KindRouter, type PageDefinition, PageKind, type Router, type RouterTarget, StructureDirRouter, StructureRouter, } from "./router.js";

package/dist/lib/output/plugins/JavascriptIndexPlugin.js

@@ -34,6 +34,7 @@ var __runInitializers = (this && this.__runInitializers) || function (thisArg, i
 };
 import * as Path from "path";
 import lunr from "lunr";
+import { Reflection } from "../../models/index.js";
 import { RendererComponent } from "../components.js";
 import { IndexEvent, RendererEvent } from "../events.js";
 import { Option, writeFile } from "../../utils/index.js";
@@ -112,8 +113,9 @@ let JavascriptIndexPlugin = (() => {
             const theme = this.owner.theme;
             const rows = [];
             const initialSearchResults = this.owner
-                .router.getLinkableReflections()
-                .filter((refl) => (refl.isDeclaration() || refl.isDocument()) &&
+                .router.getLinkTargets()
+                .filter((refl) => refl instanceof Reflection &&
+                (refl.isDeclaration() || refl.isDocument()) &&
                 refl.name &&
                 !refl.flags.isExternal);
             const indexEvent = new IndexEvent(initialSearchResults);

package/dist/lib/output/renderer.d.ts

@@ -79,8 +79,8 @@ export interface RendererHooks {
 }
 export interface RendererEvents {
     beginRender: [RendererEvent];
-    beginPage: [PageEvent<Reflection>];
-    endPage: [PageEvent<Reflection>];
+    beginPage: [PageEvent];
+    endPage: [PageEvent];
     endRender: [RendererEvent];
     parseMarkdown: [MarkdownEvent];
     prepareIndex: [IndexEvent];

package/dist/lib/output/renderer.js

@@ -263,7 +263,7 @@ let Renderer = (() => {
             await this.runPreRenderJobs(output);
             this.application.logger.verbose(`There are ${pages.length} pages to write.`);
             for (const page of pages) {
-                this.renderDocument(outputDirectory, page);
+                this.renderDocument(outputDirectory, page, project);
             }
             this.postRenderAsyncJobs.push(async (o) => await this.theme.postRender(o));
             await Promise.all(this.postRenderAsyncJobs.map((job) => job(output)));
@@ -286,13 +286,13 @@ let Renderer = (() => {
          * @param page An event describing the current page.
          * @return TRUE if the page has been saved to disc, otherwise FALSE.
          */
-        renderDocument(outputDirectory, page) {
+        renderDocument(outputDirectory, page, project) {
             const momento = this.hooks.saveMomento();
             const event = new PageEvent(page.model);
             event.url = page.url;
             event.filename = path.join(outputDirectory, page.url);
             event.pageKind = page.kind;
-            event.project = page.model.project;
+            event.project = project;
             this.trigger(PageEvent.BEGIN, event);
             event.contents = this.theme.render(event);
             this.trigger(PageEvent.END, event);

package/dist/lib/output/router.d.ts

@@ -1,9 +1,12 @@
 import type { Application } from "../application.js";
-import { type ProjectReflection, type Reflection, ReflectionKind } from "../models/index.js";
+import { ProjectReflection, Reflection, ReflectionKind } from "../models/index.js";
 import { type TypeDocOptionMap } from "../utils/index.js";
 import { Slugger } from "./themes/default/Slugger.js";
 /**
  * The type of page which should be rendered. This may be extended in the future.
+ *
+ * Note: TypeDoc any string may be used as the page kind. TypeDoc defines a few
+ * described by this object.
  * @enum
  */
 export declare const PageKind: {
@@ -12,11 +15,20 @@ export declare const PageKind: {
     readonly Document: "document";
     readonly Hierarchy: "hierarchy";
 };
-export type PageKind = (typeof PageKind)[keyof typeof PageKind];
-export interface PageDefinition {
+export type PageKind = (typeof PageKind)[keyof typeof PageKind] | string & {};
+/**
+ * A router target is something that may be linked to within a page. Notably,
+ * {@link Reflection} is compatible with this interface. TypeDoc supports non-reflection
+ * router targets, but does not currently create any.
+ */
+export type RouterTarget = {
+    name: string;
+    parent: RouterTarget;
+} | Reflection;
+export interface PageDefinition<out Model extends RouterTarget = RouterTarget> {
     readonly url: string;
     readonly kind: PageKind;
-    readonly model: Reflection;
+    readonly model: Model;
 }
 /**
  * Interface which routers must conform to.
@@ -28,36 +40,36 @@ export interface Router {
      */
     buildPages(project: ProjectReflection): PageDefinition[];
     /**
-     * Can be used to check if the reflection can be linked to.
+     * Can be used to check if the target can be linked to.
      */
-    hasUrl(reflection: Reflection): boolean;
+    hasUrl(target: RouterTarget): boolean;
     /**
-     * Get a list of all reflections which can be linked to.
+     * Get a list of all targets which can be linked to.
      * This is used for creating the search index.
      */
-    getLinkableReflections(): Reflection[];
+    getLinkTargets(): RouterTarget[];
     /**
-     * Gets an anchor for this reflection within its containing page.
-     * May be undefined if this reflection owns its own page.
+     * Gets an anchor for this target within its containing page.
+     * May be undefined if this target owns its own page.
      */
-    getAnchor(refl: Reflection): string | undefined;
+    getAnchor(refl: RouterTarget): string | undefined;
     /**
-     * Returns true if the reflection has its own page, false if embedded within
+     * Returns true if the target has its own page, false if embedded within
      * another page.
      */
-    hasOwnDocument(refl: Reflection): boolean;
+    hasOwnDocument(refl: RouterTarget): boolean;
     /**
      * Should return a URL which when clicked on the page containing `from`
      * takes the user to the page/anchor containing `to`.
      */
-    relativeUrl(from: Reflection, to: Reflection): string;
+    relativeUrl(from: RouterTarget, to: RouterTarget): string;
     /**
      * Should return a URL relative to the project base. This is used for
      * determining links to items in the assets folder.
      */
-    baseRelativeUrl(from: Reflection, target: string): string;
+    baseRelativeUrl(from: RouterTarget, target: string): string;
     /**
-     * Get the full URL to the reflection. In TypeDoc's default router this
+     * Get the full URL to the target. In TypeDoc's default router this
      * is equivalent to `relativeUrl(project, refl)`, but this might not be
      * the case for custom routers which place the project somewhere else
      * besides `index.html`.
@@ -65,13 +77,13 @@ export interface Router {
      * The URL returned by this by the frontend JS when building dynamic URLs
      * for the search, full hierarchy, and navigation components.
      */
-    getFullUrl(refl: Reflection): string;
+    getFullUrl(refl: RouterTarget): string;
     /**
-     * Responsible for getting a slugger for the given reflection. If a
-     * reflection is not associated with a page, the slugger for the parent
-     * reflection should be returned instead.
+     * Responsible for getting a slugger for the given target. If a
+     * target is not associated with a page, the slugger for the parent
+     * target should be returned instead.
      */
-    getSlugger(reflection: Reflection): Slugger;
+    getSlugger(reflection: RouterTarget): Slugger;
 }
 /**
  * Base router class intended to make it easier to implement a router.
@@ -84,36 +96,36 @@ export declare abstract class BaseRouter implements Router {
     readonly application: Application;
     extension: string;
     protected usedFileNames: Set<string>;
-    protected sluggers: Map<Reflection, Slugger>;
-    protected fullUrls: Map<Reflection, string>;
-    protected anchors: Map<Reflection, string>;
+    protected sluggers: Map<RouterTarget, Slugger>;
+    protected fullUrls: Map<RouterTarget, string>;
+    protected anchors: Map<RouterTarget, string>;
     protected accessor sluggerConfiguration: TypeDocOptionMap["sluggerConfiguration"];
     protected accessor includeHierarchySummary: boolean;
     constructor(application: Application);
     /**
-     * Should return the base-relative desired file name for a reflection.
+     * Should return the base-relative desired file name for a router target.
      * This name may not be used exactly as TypeDoc will detect conflicts
      * and automatically introduce a unique identifier to the URL to resolve
      * them.
      */
-    protected abstract getIdealBaseName(reflection: Reflection): string;
+    protected abstract getIdealBaseName(reflection: RouterTarget): string;
     buildPages(project: ProjectReflection): PageDefinition[];
-    hasUrl(reflection: Reflection): boolean;
-    getLinkableReflections(): Reflection[];
-    getAnchor(refl: Reflection): string | undefined;
-    hasOwnDocument(refl: Reflection): boolean;
-    relativeUrl(from: Reflection, to: Reflection): string;
-    baseRelativeUrl(from: Reflection, target: string): string;
-    getFullUrl(refl: Reflection): string;
-    getSlugger(reflection: Reflection): Slugger;
+    hasUrl(target: RouterTarget): boolean;
+    getLinkTargets(): RouterTarget[];
+    getAnchor(target: RouterTarget): string | undefined;
+    hasOwnDocument(target: RouterTarget): boolean;
+    relativeUrl(from: RouterTarget, to: RouterTarget): string;
+    baseRelativeUrl(from: RouterTarget, target: string): string;
+    getFullUrl(target: RouterTarget): string;
+    getSlugger(target: RouterTarget): Slugger;
     /**
      * Should the page kind to use if a reflection should have its own rendered
      * page in the output. Note that once `undefined` is returned, children of
      * that reflection will not have their own document.
      */
-    protected getPageKind(reflection: Reflection): PageKind | undefined;
-    protected buildChildPages(reflection: Reflection, outPages: PageDefinition[]): void;
-    protected buildAnchors(reflection: Reflection, pageReflection: Reflection): void;
+    protected getPageKind(target: RouterTarget): PageKind | undefined;
+    protected buildChildPages(target: RouterTarget, outPages: PageDefinition[]): void;
+    protected buildAnchors(target: RouterTarget, pageTarget: RouterTarget): void;
     /** Strip non-url safe characters from the specified string. */
     protected getUrlSafeName(name: string): string;
     protected getFileName(baseName: string): string;