From 1b79f68abf46824fedc645c05bc98a59574b4b08 Mon Sep 17 00:00:00 2001 From: Jared Wray Date: Wed, 16 Oct 2024 14:01:33 -0700 Subject: [PATCH] adding in jsdoc --- src/eventified.ts | 97 +++++++++++++++++++++++++++++++++++++++++++---- src/index.ts | 36 +++++++++++++++--- 2 files changed, 120 insertions(+), 13 deletions(-) diff --git a/src/eventified.ts b/src/eventified.ts index 9cf5985..1cd5c08 100644 --- a/src/eventified.ts +++ b/src/eventified.ts @@ -11,6 +11,12 @@ export class Eventified implements IEventEmitter { this._maxListeners = 100; // Default maximum number of listeners } + /** + * Adds a handler function for a specific event that will run only once + * @param {string | symbol} eventName + * @param {EventListener} listener + * @returns {IEventEmitter} returns the instance of the class for chaining + */ once(eventName: string | symbol, listener: EventListener): IEventEmitter { const onceListener: EventListener = (...arguments_: any[]) => { this.off(eventName as string, onceListener); @@ -22,6 +28,11 @@ export class Eventified implements IEventEmitter { return this; } + /** + * Gets the number of listeners for a specific event. If no event is provided, it returns the total number of listeners + * @param {string} eventName The event name. Not required + * @returns {number} The number of listeners + */ listenerCount(eventName?: string | symbol): number { if (!eventName) { return this.getAllListeners().length; @@ -31,10 +42,19 @@ export class Eventified implements IEventEmitter { return listeners ? listeners.length : 0; } + /** + * Gets an array of event names + * @returns {Array} An array of event names + */ eventNames(): Array { return Array.from(this._eventListeners.keys()); } + /** + * Gets an array of listeners for a specific event. If no event is provided, it returns all listeners + * @param {string} eventName (Optional) The event name + * @returns {EventListener[]} An array of listeners + */ rawListeners(eventName?: string | symbol): EventListener[] { if (!eventName) { return this.getAllListeners(); @@ -43,6 +63,12 @@ export class Eventified implements IEventEmitter { return this._eventListeners.get(eventName) ?? []; } + /** + * Prepends a listener to the beginning of the listeners array for the specified event + * @param {string | symbol} eventName + * @param {EventListener} listener + * @returns {IEventEmitter} returns the instance of the class for chaining + */ prependListener(eventName: string | symbol, listener: EventListener): IEventEmitter { const listeners = this._eventListeners.get(eventName) ?? []; listeners.unshift(listener); @@ -50,6 +76,12 @@ export class Eventified implements IEventEmitter { return this; } + /** + * Prepends a one-time listener to the beginning of the listeners array for the specified event + * @param {string | symbol} eventName + * @param {EventListener} listener + * @returns {IEventEmitter} returns the instance of the class for chaining + */ prependOnceListener(eventName: string | symbol, listener: EventListener): IEventEmitter { const onceListener: EventListener = (...arguments_: any[]) => { this.off(eventName as string, onceListener); @@ -61,16 +93,31 @@ export class Eventified implements IEventEmitter { return this; } + /** + * Gets the maximum number of listeners that can be added for a single event + * @returns {number} The maximum number of listeners + */ public maxListeners(): number { return this._maxListeners; } - // Add an event listener + /** + * Adds a listener for a specific event. It is an alias for the on() method + * @param {string | symbol} event + * @param {EventListener} listener + * @returns {IEventEmitter} returns the instance of the class for chaining + */ public addListener(event: string | symbol, listener: EventListener): IEventEmitter { this.on(event, listener); return this; } + /** + * Adds a listener for a specific event + * @param {string | symbol} event + * @param {EventListener} listener + * @returns {IEventEmitter} returns the instance of the class for chaining + */ public on(event: string | symbol, listener: EventListener): IEventEmitter { if (!this._eventListeners.has(event)) { this._eventListeners.set(event, []); @@ -89,12 +136,23 @@ export class Eventified implements IEventEmitter { return this; } - // Remove an event listener + /** + * Removes a listener for a specific event. It is an alias for the off() method + * @param {string | symbol} event + * @param {EventListener} listener + * @returns {IEventEmitter} returns the instance of the class for chaining + */ public removeListener(event: string, listener: EventListener): IEventEmitter { this.off(event, listener); return this; } + /** + * Removes a listener for a specific event + * @param {string | symbol} event + * @param {EventListener} listener + * @returns {IEventEmitter} returns the instance of the class for chaining + */ public off(event: string, listener: EventListener): IEventEmitter { const listeners = this._eventListeners.get(event) ?? []; const index = listeners.indexOf(listener); @@ -109,26 +167,41 @@ export class Eventified implements IEventEmitter { return this; } - // Emit an event - public emit(event: string, ...arguments_: any[]): boolean { + /** + * Calls all listeners for a specific event + * @param {string | symbol} event + * @param arguments_ The arguments to pass to the listeners + * @returns {boolean} Returns true if the event had listeners, false otherwise + */ + public emit(event: string | symbol, ...arguments_: any[]): boolean { + let result = false; const listeners = this._eventListeners.get(event); if (listeners && listeners.length > 0) { for (const listener of listeners) { // eslint-disable-next-line @typescript-eslint/no-unsafe-argument listener(...arguments_); + result = true; } } - return true; + return result; } - // Get all listeners for a specific event + /** + * Gets all listeners for a specific event. If no event is provided, it returns all listeners + * @param {string} event (Optional) The event name + * @returns {EventListener[]} An array of listeners + */ public listeners(event: string): EventListener[] { return this._eventListeners.get(event) ?? []; } - // Remove all listeners for a specific event + /** + * Removes all listeners for a specific event. If no event is provided, it removes all listeners + * @param {string} event (Optional) The event name + * @returns {IEventEmitter} returns the instance of the class for chaining + */ public removeAllListeners(event?: string): IEventEmitter { if (event) { this._eventListeners.delete(event); @@ -139,7 +212,11 @@ export class Eventified implements IEventEmitter { return this; } - // Set the maximum number of listeners for a single event + /** + * Sets the maximum number of listeners that can be added for a single event + * @param {number} n The maximum number of listeners + * @returns {void} + */ public setMaxListeners(n: number): void { this._maxListeners = n; for (const listeners of this._eventListeners.values()) { @@ -149,6 +226,10 @@ export class Eventified implements IEventEmitter { } } + /** + * Gets all listeners + * @returns {EventListener[]} An array of listeners + */ public getAllListeners(): EventListener[] { let result = new Array(); for (const listeners of this._eventListeners.values()) { diff --git a/src/index.ts b/src/index.ts index d61f4e8..ccc339e 100644 --- a/src/index.ts +++ b/src/index.ts @@ -10,7 +10,12 @@ export class Hookified extends Eventified { this._hooks = new Map(); } - // Adds a handler function for a specific event + /** + * Adds a handler function for a specific event + * @param {string} event + * @param {Hook} handler + * @returns {void} + */ onHook(event: string, handler: Hook) { const eventHandlers = this._hooks.get(event); if (eventHandlers) { @@ -20,7 +25,12 @@ export class Hookified extends Eventified { } } - // Removes a specific handler function for a specific event + /** + * Removes a handler function for a specific event + * @param {string} event + * @param {Hook} handler + * @returns {void} + */ removeHook(event: string, handler: Hook) { const eventHandlers = this._hooks.get(event); if (eventHandlers) { @@ -31,7 +41,12 @@ export class Hookified extends Eventified { } } - // Triggers all handlers for a specific event with provided data + /** + * Calls all handlers for a specific event + * @param {string} event + * @param {T[]} arguments_ + * @returns {Promise} + */ async hook(event: string, ...arguments_: T[]) { const eventHandlers = this._hooks.get(event); if (eventHandlers) { @@ -46,16 +61,27 @@ export class Hookified extends Eventified { } } - // Provides read-only access to the current handlers + /** + * Gets all hooks + * @returns {Map} + */ get hooks() { - // Creating a new map to prevent external modifications to the original map return this._hooks; } + /** + * Gets all hooks for a specific event + * @param {string} event + * @returns {Hook[]} + */ getHooks(event: string) { return this._hooks.get(event); } + /** + * Removes all hooks + * @returns {void} + */ clearHooks() { this._hooks.clear(); }