Typed event emitters

CHANGELOG.md

@@ -1,11 +1,4 @@
-# Beta (full release: 2024-06-21)
-
-### To Do
-
--   Update website docs - consider if reworking website to just be a TypeDoc generated site is a good idea
-    `@license`, `@import`, `@hideGroups` `@hideCategories` sitemapBaseUrl, markedOptions -> markdownItOptions, markdownItLoader, navigation
-    sort - documents-first, documents-last, alphabetical-ignoring-documents
-    searchInDocuments, useHostedBaseUrlForAbsoluteLinks
+# Unreleased
 
 ### Breaking Changes
 
@@ -28,6 +21,8 @@
     This change was extended to apply not only to type aliases, but also other function-likes declared with variables and callable properties.
     As a part of this change, comments on the implementation signature of overloaded functions will now be added to the function reflection, and will
     not be inherited by signatures of that function, #2521.
+-   API: TypeDoc now uses a typed event emitter to provide improved type safety, this found a bug where `Converter.EVENT_CREATE_DECLARATION`
+    was emitted for `ProjectReflection` in some circumstances.
 -   API: `MapOptionDeclaration.mapError` has been removed.
 -   API: Deprecated `BindOption` decorator has been removed.
 -   API: `DeclarationReflection.indexSignature` has been renamed to `DeclarationReflection.indexSignatures`.

src/index.ts

@@ -1,6 +1,6 @@
-export { Application } from "./lib/application";
+export { Application, type ApplicationEvents } from "./lib/application";
 
-export { EventDispatcher, Event } from "./lib/utils/events";
+export { EventDispatcher } from "./lib/utils/events";
 export { resetReflectionID } from "./lib/models/reflections/abstract";
 /**
  * All symbols documented under the Models namespace are also available in the root import.
@@ -29,6 +29,7 @@ export {
     type MeaningKeyword,
     type ExternalResolveResult,
     type ExternalSymbolResolver,
+    type ConverterEvents,
 } from "./lib/converter";
 
 export {
@@ -47,6 +48,7 @@ export type {
     RenderTemplate,
     RendererHooks,
     NavigationElement,
+    RendererEvents,
 } from "./lib/output";
 
 export {
@@ -94,11 +96,10 @@ export type {
     JsDocCompatibility,
 } from "./lib/utils";
 
-export type { EventMap, EventCallback } from "./lib/utils/events";
-
 export {
     JSONOutput,
     Serializer,
+    type SerializerEvents,
     Deserializer,
     type Deserializable,
     type DeserializerComponent,

src/lib/application-events.ts

@@ -2,4 +2,4 @@ export const ApplicationEvents = {
     BOOTSTRAP_END: "bootstrapEnd",
     REVIVE: "reviveProject",
     VALIDATE_PROJECT: "validateProject",
-};
+} as const;

src/lib/application.ts

@@ -74,6 +74,12 @@ const DEFAULT_READERS = [
     new TSConfigReader(),
 ];
 
+export interface ApplicationEvents {
+    bootstrapEnd: [Application];
+    reviveProject: [ProjectReflection];
+    validateProject: [ProjectReflection];
+}
+
 /**
  * The default TypeDoc main application class.
  *
@@ -95,7 +101,8 @@ const DEFAULT_READERS = [
 @Component({ name: "application", internal: true })
 export class Application extends ChildableComponent<
     Application,
-    AbstractComponent<Application>
+    AbstractComponent<Application, {}>,
+    ApplicationEvents
 > {
     /**
      * The converter used to create the declaration reflections.
@@ -187,8 +194,8 @@ export class Application extends ChildableComponent<
         }
         super(null!); // We own ourselves
 
-        this.converter = this.addComponent<Converter>("converter", Converter);
-        this.renderer = this.addComponent<Renderer>("renderer", Renderer);
+        this.converter = new Converter(this);
+        this.renderer = new Renderer(this);
         this.logger.i18n = this.i18n;
     }
 

src/lib/converter/components.ts

@@ -3,4 +3,7 @@ import type { Converter } from "./converter";
 
 export { Component };
 
-export abstract class ConverterComponent extends AbstractComponent<Converter> {}
+export abstract class ConverterComponent extends AbstractComponent<
+    Converter,
+    {}
+> {}

src/lib/converter/context.ts

@@ -262,19 +262,6 @@ export class Context {
         this.project.registerReflection(reflection, symbol, void 0);
     }
 
-    /**
-     * Trigger a node reflection event.
-     *
-     * All events are dispatched on the current converter instance.
-     *
-     * @param name  The name of the event that should be triggered.
-     * @param reflection  The triggering reflection.
-     * @param node  The triggering TypeScript node if available.
-     */
-    trigger(name: string, reflection: Reflection, node?: ts.Node) {
-        this.converter.trigger(name, this, reflection, node);
-    }
-
     /** @internal */
     setActiveProgram(program: ts.Program | undefined) {
         this._program = program;

src/lib/converter/converter.ts

@@ -5,12 +5,16 @@ import {
     Comment,
     type CommentDisplayPart,
     type ContainerReflection,
+    type DeclarationReflection,
     DocumentReflection,
+    type ParameterReflection,
     ProjectReflection,
     type Reflection,
     ReflectionKind,
     type ReflectionSymbolId,
+    type SignatureReflection,
     type SomeType,
+    type TypeParameterReflection,
 } from "../models/index";
 import { Context } from "./context";
 import { ConverterComponent } from "./components";
@@ -49,6 +53,31 @@ import {
 import { basename, dirname, resolve } from "path";
 import type { FileRegistry } from "../models/FileRegistry";
 
+export interface ConverterEvents {
+    begin: [Context];
+    end: [Context];
+    createDeclaration: [Context, DeclarationReflection];
+    createSignature: [
+        Context,
+        SignatureReflection,
+        (
+            | ts.SignatureDeclaration
+            | ts.IndexSignatureDeclaration
+            | ts.JSDocSignature
+        )?,
+        ts.Signature?,
+    ];
+    createParameter: [Context, ParameterReflection, ts.Node?];
+    createTypeParameter: [
+        Context,
+        TypeParameterReflection,
+        ts.TypeParameterDeclaration?,
+    ];
+    resolveBegin: [Context];
+    resolveReflection: [Context, Reflection];
+    resolveEnd: [Context];
+}
+
 /**
  * Compiles source files using TypeScript and converts compiler symbols to reflections.
  */
@@ -59,7 +88,8 @@ import type { FileRegistry } from "../models/FileRegistry";
 })
 export class Converter extends ChildableComponent<
     Application,
-    ConverterComponent
+    ConverterComponent,
+    ConverterEvents
 > {
     /** @internal */
     @Option("externalPattern")
@@ -440,10 +470,6 @@ export class Converter extends ChildableComponent<
                 ? context.getComment(symbol, context.project.kind)
                 : context.getFileComment(node);
             this.processDocumentTags(context.project, context.project);
-            context.trigger(
-                Converter.EVENT_CREATE_DECLARATION,
-                context.project,
-            );
             moduleContext = context;
         } else {
             const reflection = context.createDeclarationReflection(

src/lib/converter/factories/index-signature.ts

@@ -46,8 +46,9 @@ export function convertIndexSignatures(context: Context, symbol: ts.Symbol) {
         context.scope.indexSignatures ||= [];
         context.scope.indexSignatures.push(index);
 
-        context.trigger(
+        context.converter.trigger(
             ConverterEvents.CREATE_SIGNATURE,
+            context,
             index,
             indexDeclaration,
         );

src/lib/converter/factories/signature.ts

@@ -211,7 +211,11 @@ function convertParameters(
         paramRefl.comment ||= context.getComment(param, paramRefl.kind);
 
         context.registerReflection(paramRefl, param);
-        context.trigger(ConverterEvents.CREATE_PARAMETER, paramRefl);
+        context.converter.trigger(
+            ConverterEvents.CREATE_PARAMETER,
+            context,
+            paramRefl,
+        );
 
         let type: ts.Type | ts.TypeNode | undefined;
         if (declaration) {
@@ -289,7 +293,11 @@ export function convertParameterNodes(
             paramRefl,
             context.getSymbolAtLocation(param),
         );
-        context.trigger(ConverterEvents.CREATE_PARAMETER, paramRefl);
+        context.converter.trigger(
+            ConverterEvents.CREATE_PARAMETER,
+            context,
+            paramRefl,
+        );
 
         paramRefl.type = context.converter.convertType(
             context.withScope(paramRefl),
@@ -377,7 +385,11 @@ function convertTypeParameters(
         }
 
         context.registerReflection(paramRefl, param.getSymbol());
-        context.trigger(ConverterEvents.CREATE_TYPE_PARAMETER, paramRefl);
+        context.converter.trigger(
+            ConverterEvents.CREATE_TYPE_PARAMETER,
+            context,
+            paramRefl,
+        );
 
         return paramRefl;
     });
@@ -418,7 +430,12 @@ export function createTypeParamReflection(
         paramRefl.comment = context.getJsDocComment(param.parent);
     }
 
-    context.trigger(ConverterEvents.CREATE_TYPE_PARAMETER, paramRefl, param);
+    context.converter.trigger(
+        ConverterEvents.CREATE_TYPE_PARAMETER,
+        context,
+        paramRefl,
+        param,
+    );
     return paramRefl;
 }
 
@@ -458,8 +475,9 @@ export function convertTemplateParameterNodes(
                 paramRefl.comment = context.getJsDocComment(param.parent);
             }
 
-            context.trigger(
+            context.converter.trigger(
                 ConverterEvents.CREATE_TYPE_PARAMETER,
+                context,
                 paramRefl,
                 param,
             );

src/lib/converter/index.ts

@@ -1,5 +1,5 @@
 export { Context } from "./context";
-export { Converter } from "./converter";
+export { Converter, type ConverterEvents } from "./converter";
 export type { CommentParserConfig } from "./comments/index";
 export { convertDefaultValue, convertExpression } from "./convert-expression";
 export type {

src/lib/converter/jsdoc.ts

@@ -123,7 +123,11 @@ function convertJsDocSignature(context: Context, node: ts.JSDocSignature) {
         context.scope,
     );
     context.registerReflection(reflection, symbol);
-    context.trigger(ConverterEvents.CREATE_DECLARATION, reflection);
+    context.converter.trigger(
+        ConverterEvents.CREATE_DECLARATION,
+        context,
+        reflection,
+    );
 
     const signature = new SignatureReflection(
         "__type",

src/lib/converter/plugins/CategoryPlugin.ts

@@ -43,13 +43,10 @@ export class CategoryPlugin extends ConverterComponent {
      * Create a new CategoryPlugin instance.
      */
     override initialize() {
-        this.listenTo(
-            this.owner,
-            {
-                [Converter.EVENT_BEGIN]: this.onBegin,
-                [Converter.EVENT_RESOLVE_END]: this.onEndResolve,
-            },
-            undefined,
+        this.owner.on(Converter.EVENT_BEGIN, this.onBegin.bind(this), -200);
+        this.owner.on(
+            Converter.EVENT_RESOLVE_END,
+            this.onEndResolve.bind(this),
             -200,
         );
     }

src/lib/converter/plugins/CommentPlugin.ts

@@ -155,15 +155,25 @@ export class CommentPlugin extends ConverterComponent {
      * Create a new CommentPlugin instance.
      */
     override initialize() {
-        this.listenTo(this.owner, {
-            [Converter.EVENT_CREATE_DECLARATION]: this.onDeclaration,
-            [Converter.EVENT_CREATE_SIGNATURE]: this.onDeclaration,
-            [Converter.EVENT_CREATE_TYPE_PARAMETER]: this.onCreateTypeParameter,
-            [Converter.EVENT_RESOLVE_BEGIN]: this.onBeginResolve,
-            [Converter.EVENT_RESOLVE]: this.onResolve,
-            [Converter.EVENT_END]: () => {
-                this._excludeKinds = undefined;
-            },
+        this.owner.on(
+            Converter.EVENT_CREATE_DECLARATION,
+            this.onDeclaration.bind(this),
+        );
+        this.owner.on(
+            Converter.EVENT_CREATE_SIGNATURE,
+            this.onDeclaration.bind(this),
+        );
+        this.owner.on(
+            Converter.EVENT_CREATE_TYPE_PARAMETER,
+            this.onCreateTypeParameter.bind(this),
+        );
+        this.owner.on(
+            Converter.EVENT_RESOLVE_BEGIN,
+            this.onBeginResolve.bind(this),
+        );
+        this.owner.on(Converter.EVENT_RESOLVE, this.onResolve.bind(this));
+        this.owner.on(Converter.EVENT_END, () => {
+            this._excludeKinds = undefined;
         });
     }
 

src/lib/converter/plugins/GroupPlugin.ts

@@ -63,25 +63,24 @@ export class GroupPlugin extends ConverterComponent {
      * Create a new GroupPlugin instance.
      */
     override initialize() {
-        this.listenTo(
-            this.owner,
-            {
-                [Converter.EVENT_RESOLVE_BEGIN]: () => {
-                    this.sortFunction = getSortFunction(
-                        this.application.options,
+        this.owner.on(
+            Converter.EVENT_RESOLVE_BEGIN,
+            () => {
+                this.sortFunction = getSortFunction(this.application.options);
+                GroupPlugin.WEIGHTS = this.groupOrder;
+                if (GroupPlugin.WEIGHTS.length === 0) {
+                    GroupPlugin.WEIGHTS = defaultGroupOrder.map((kind) =>
+                        this.application.internationalization.kindPluralString(
+                            kind,
+                        ),
                     );
-                    GroupPlugin.WEIGHTS = this.groupOrder;
-                    if (GroupPlugin.WEIGHTS.length === 0) {
-                        GroupPlugin.WEIGHTS = defaultGroupOrder.map((kind) =>
-                            this.application.internationalization.kindPluralString(
-                                kind,
-                            ),
-                        );
-                    }
-                },
-                [Converter.EVENT_RESOLVE_END]: this.onEndResolve,
+                }
             },
-            undefined,
+            -100,
+        );
+        this.owner.on(
+            Converter.EVENT_RESOLVE_END,
+            this.onEndResolve.bind(this),
             -100,
         );
     }