feat: enhance EventEmitter typing and remove unused index signatures for improved type safety

Author: ido-pluto

src/download/download-engine/download-file/download-engine-file.ts

@@ -41,7 +41,6 @@ export type DownloadEngineFileEvents = {
     save: (progress: SaveProgressInfo) => void;
     finished: () => void;
     closed: () => void;
-    [key: string]: any;
 };
 
 const DEFAULT_CHUNKS_SIZE_FOR_CHUNKS_PROGRAM = 1024 * 1024 * 5; // 5MB

src/download/download-engine/engine/base-download-engine.ts

@@ -49,7 +49,6 @@ export type BaseDownloadEngineEvents = {
     save: (progress: SaveProgressInfo) => void;
     finished: () => void;
     closed: () => void;
-    [key: string]: any;
 };
 
 export const DEFAULT_BASE_DOWNLOAD_ENGINE_OPTIONS: Partial<BaseDownloadEngineOptions> = {

src/download/download-engine/engine/download-engine-multi-download.ts

@@ -7,7 +7,16 @@ import {DownloadFlags, DownloadStatus} from "../download-file/progress-status-fi
 import {DownloadEngineRemote} from "./DownloadEngineRemote.js";
 import {promiseWithResolvers} from "../utils/promiseWithResolvers.js";
 
-export type DownloadEngineMultiAllowedEngines = BaseDownloadEngine | DownloadEngineRemote | DownloadEngineMultiDownload<any>;
+type BaseDownloadEngineEventName = Extract<keyof BaseDownloadEngineEvents, string>;
+
+export type BaseDownloadEngineEventTarget = {
+    on<Key extends BaseDownloadEngineEventName>(eventName: Key, listener: BaseDownloadEngineEvents[Key]): unknown;
+    off<Key extends BaseDownloadEngineEventName>(eventName: Key, listener: BaseDownloadEngineEvents[Key]): unknown;
+    once<Key extends BaseDownloadEngineEventName>(eventName: Key, listener: BaseDownloadEngineEvents[Key]): unknown;
+};
+
+type DownloadEngineMultiAllowedEngineCore = BaseDownloadEngine | DownloadEngineRemote | DownloadEngineMultiDownload<any>;
+export type DownloadEngineMultiAllowedEngines = DownloadEngineMultiAllowedEngineCore & BaseDownloadEngineEventTarget;
 
 type DownloadEngineMultiDownloadEvents<Engine = DownloadEngineMultiAllowedEngines> = BaseDownloadEngineEvents & {
     childDownloadStarted: (engine: Engine) => void

src/utils/EventEmitter.ts

@@ -1,26 +1,34 @@
 type AnyListener = (...args: any[]) => void;
 
-type KnownKeys<T> = {
-    [Key in keyof T]: string extends Key ? never : number extends Key ? never : symbol extends Key ? never : Key;
-}[keyof T];
-
-type KnownEventName<Events extends object> = Extract<KnownKeys<Events>, string | symbol>;
-type KnownEventListener<Events extends object, Key extends KnownEventName<Events>> = Events[Key] extends AnyListener ? Events[Key] : never;
 type ListenerArgs<Listener> = Listener extends (...args: infer Args) => void ? Args : never;
 type StoredListener = AnyListener & {
     _originalListener?: AnyListener;
 };
 type StoredEvent = StoredListener | StoredListener[];
 type EventName = string | symbol;
+type KnownEventName<Events extends object> = Extract<{
+    [Key in keyof Events]: Key extends EventName
+        ? string extends Key
+            ? never
+            : number extends Key
+                ? never
+                : symbol extends Key
+                    ? never
+                    : Key
+        : never;
+}[keyof Events], EventName>;
+type EventListener<Events extends object, Key extends EventName> = Key extends keyof Events ? Events[Key] extends AnyListener ? Events[Key] : never : AnyListener;
+type EventListenerArgs<Events extends object, Key extends EventName> = ListenerArgs<EventListener<Events, Key>>;
+type SuggestedEventName<Events extends object, ExtraEvents extends EventName> = KnownEventName<Events> | (ExtraEvents & {});
+type HasBroadEventKeys<Events extends object> = string extends keyof Events ? true : symbol extends keyof Events ? true : false;
+type DefaultExtraEvents<Events extends object> = HasBroadEventKeys<Events> extends true ? EventName : never;
 
 export type EventMap = Record<PropertyKey, AnyListener>;
 
-export class EventEmitter<Events extends object = Record<string, never>> {
+export class EventEmitter<Events extends object = EventMap, ExtraEvents extends EventName = DefaultExtraEvents<Events>> {
     private _events = new Map<EventName, StoredEvent>();
 
-    public on<Key extends KnownEventName<Events>>(eventName: Key, listener: KnownEventListener<Events, Key>): this;
-    public on(eventName: EventName, listener: AnyListener): this;
-    public on(eventName: EventName, listener: AnyListener): this {
+    public on<Key extends SuggestedEventName<Events, ExtraEvents>>(eventName: Key, listener: EventListener<Events, Key>): this {
         const current = this._events.get(eventName);
 
         if (current === undefined) {
@@ -37,27 +45,21 @@ export class EventEmitter<Events extends object = Record<string, never>> {
         return this;
     }
 
-    public addListener<Key extends KnownEventName<Events>>(eventName: Key, listener: KnownEventListener<Events, Key>): this;
-    public addListener(eventName: EventName, listener: AnyListener): this;
-    public addListener(eventName: EventName, listener: AnyListener): this {
+    public addListener<Key extends SuggestedEventName<Events, ExtraEvents>>(eventName: Key, listener: EventListener<Events, Key>): this {
         return this.on(eventName, listener);
     }
 
-    public once<Key extends KnownEventName<Events>>(eventName: Key, listener: KnownEventListener<Events, Key>): this;
-    public once(eventName: EventName, listener: AnyListener): this;
-    public once(eventName: EventName, listener: AnyListener): this {
+    public once<Key extends SuggestedEventName<Events, ExtraEvents>>(eventName: Key, listener: EventListener<Events, Key>): this {
         const onceListener: StoredListener = (...args) => {
-            this.off(eventName, onceListener);
+            this.off(eventName, onceListener as EventListener<Events, Key>);
             listener(...args);
         };
 
         onceListener._originalListener = listener;
-        return this.on(eventName, onceListener);
+        return this.on(eventName, onceListener as EventListener<Events, Key>);
     }
 
-    public off<Key extends KnownEventName<Events>>(eventName: Key, listener: KnownEventListener<Events, Key>): this;
-    public off(eventName: EventName, listener: AnyListener): this;
-    public off(eventName: EventName, listener: AnyListener): this {
+    public off<Key extends SuggestedEventName<Events, ExtraEvents>>(eventName: Key, listener: EventListener<Events, Key>): this {
         const current = this._events.get(eventName);
 
         if (current === undefined) {
@@ -98,9 +100,7 @@ export class EventEmitter<Events extends object = Record<string, never>> {
         return this;
     }
 
-    public removeListener<Key extends KnownEventName<Events>>(eventName: Key, listener: KnownEventListener<Events, Key>): this;
-    public removeListener(eventName: EventName, listener: AnyListener): this;
-    public removeListener(eventName: EventName, listener: AnyListener): this {
+    public removeListener<Key extends SuggestedEventName<Events, ExtraEvents>>(eventName: Key, listener: EventListener<Events, Key>): this {
         return this.off(eventName, listener);
     }
 
@@ -114,9 +114,7 @@ export class EventEmitter<Events extends object = Record<string, never>> {
         return this;
     }
 
-    public emit0<Key extends KnownEventName<Events>>(eventName: Key): boolean;
-    public emit0(eventName: EventName): boolean;
-    public emit0(eventName: EventName): boolean {
+    public emit0<Key extends SuggestedEventName<Events, ExtraEvents>>(eventName: Key): boolean {
         const current = this._events.get(eventName);
 
         if (current === undefined) {
@@ -151,9 +149,7 @@ export class EventEmitter<Events extends object = Record<string, never>> {
         return true;
     }
 
-    public emit1<Key extends KnownEventName<Events>>(eventName: Key, a1: ListenerArgs<KnownEventListener<Events, Key>>[0]): boolean;
-    public emit1(eventName: EventName, a1: any): boolean;
-    public emit1(eventName: EventName, a1: any): boolean {
+    public emit1<Key extends SuggestedEventName<Events, ExtraEvents>>(eventName: Key, a1: EventListenerArgs<Events, Key>[0]): boolean {
         const current = this._events.get(eventName);
 
         if (current === undefined) {
@@ -188,9 +184,7 @@ export class EventEmitter<Events extends object = Record<string, never>> {
         return true;
     }
 
-    public emit2<Key extends KnownEventName<Events>>(eventName: Key, a1: ListenerArgs<KnownEventListener<Events, Key>>[0], a2: ListenerArgs<KnownEventListener<Events, Key>>[1]): boolean;
-    public emit2(eventName: EventName, a1: any, a2: any): boolean;
-    public emit2(eventName: EventName, a1: any, a2: any): boolean {
+    public emit2<Key extends SuggestedEventName<Events, ExtraEvents>>(eventName: Key, a1: EventListenerArgs<Events, Key>[0], a2: EventListenerArgs<Events, Key>[1]): boolean {
         const current = this._events.get(eventName);
 
         if (current === undefined) {
@@ -225,9 +219,7 @@ export class EventEmitter<Events extends object = Record<string, never>> {
         return true;
     }
 
-    public emit<Key extends KnownEventName<Events>>(eventName: Key, ...args: ListenerArgs<KnownEventListener<Events, Key>>): boolean;
-    public emit(eventName: EventName, ...args: any[]): boolean;
-    public emit(eventName: EventName, ...args: any[]): boolean {
+    public emit<Key extends SuggestedEventName<Events, ExtraEvents>>(eventName: Key, ...args: EventListenerArgs<Events, Key>): boolean {
         switch (args.length) {
             case 0:
                 return this.emit0(eventName);
@@ -270,22 +262,20 @@ export class EventEmitter<Events extends object = Record<string, never>> {
         return Array.from(this._events.keys());
     }
 
-    public listeners<Key extends KnownEventName<Events>>(eventName: Key): KnownEventListener<Events, Key>[];
-    public listeners(eventName: EventName): AnyListener[];
-    public listeners(eventName: EventName): AnyListener[] {
+    public listeners<Key extends SuggestedEventName<Events, ExtraEvents>>(eventName: Key): EventListener<Events, Key>[] {
         const current = this._events.get(eventName);
 
         if (current === undefined) {
             return [];
         }
 
         if (!Array.isArray(current)) {
-            return [this._unwrapListener(current)];
+            return [this._unwrapListener(current) as EventListener<Events, Key>];
         }
 
-        const listeners = new Array<AnyListener>(current.length);
+        const listeners = new Array<EventListener<Events, Key>>(current.length);
         for (let index = 0; index < current.length; index++) {
-            listeners[index] = this._unwrapListener(current[index]);
+            listeners[index] = this._unwrapListener(current[index]) as EventListener<Events, Key>;
         }
 
         return listeners;

test/eventEmitter.test.ts

@@ -1,10 +1,13 @@
 import {describe, expect, test, vi} from "vitest";
 import {EventEmitter} from "../src/utils/EventEmitter.js";
 
+type Assert<T extends true> = T;
+type IsAny<T> = 0 extends (1 & T) ? true : false;
+type IsExact<T, Expected> = [T] extends [Expected] ? ([Expected] extends [T] ? true : false) : false;
+
 type TestEvents = {
     data: (value: number, label: string) => void;
     closed: () => void;
-    [key: string]: any;
 };
 
 describe("EventEmitter", () => {
@@ -45,6 +48,10 @@ describe("EventEmitter", () => {
         const emitter = new EventEmitter<TestEvents>();
 
         emitter.on("data", (value, label) => {
+            type ValueIsNotAny = Assert<IsAny<typeof value> extends false ? true : false>;
+            type LabelIsNotAny = Assert<IsAny<typeof label> extends false ? true : false>;
+            type ValueIsNumber = Assert<IsExact<typeof value, number>>;
+            type LabelIsString = Assert<IsExact<typeof label, string>>;
             const typedValue: number = value;
             const typedLabel: string = label;
 
@@ -53,7 +60,18 @@ describe("EventEmitter", () => {
         });
 
         const typedListeners: Array<(value: number, label: string) => void> = emitter.listeners("data");
+        type TypedListenersAreExact = Assert<IsExact<typeof typedListeners, Array<(value: number, label: string) => void>>>;
+        emitter.emit("data", 1, "ok");
+
+        // @ts-expect-error data listeners receive a number as the first argument
+        emitter.on("data", (value: string) => {
+            void value;
+        });
+
+        // @ts-expect-error data emits require a string label as the second argument
+        emitter.emit("data", 1, 2);
 
+        void (true as TypedListenersAreExact);
         expect(typedListeners).toHaveLength(1);
     });
 
@@ -68,6 +86,16 @@ describe("EventEmitter", () => {
         expect(emitter.eventNames()).toContain(eventName);
     });
 
+    test("supports unknown event names without affecting known event typing", () => {
+        const emitter = new EventEmitter<TestEvents, string | symbol>();
+        const listener = vi.fn();
+
+        emitter.on("custom", listener);
+
+        expect(emitter.emit("custom", 1, "label")).toBe(true);
+        expect(listener).toHaveBeenCalledWith(1, "label");
+    });
+
     test("keeps emit order stable when listeners remove each other", () => {
         const emitter = new EventEmitter<TestEvents>();
         const calls: string[] = [];