hookified 1.3.0 → 1.5.0

package/dist/node/index.d.ts

@@ -1,28 +1,302 @@
+type IEventEmitter = {
+    /**
+     * Registers a listener for the specified event.
+     *
+     * @param eventName - The name (or symbol) of the event to listen for.
+     * @param listener - A callback function that will be invoked when the event is emitted.
+     * @returns The current instance of EventEmitter for method chaining.
+     *
+     * @example
+     * emitter.on('data', (message) => {
+     *   console.log(message);
+     * });
+     */
+    on(eventName: string | symbol, listener: (...arguments_: any[]) => void): IEventEmitter;
+    /**
+     * Alias for `on`. Registers a listener for the specified event.
+     *
+     * @param eventName - The name (or symbol) of the event to listen for.
+     * @param listener - A callback function that will be invoked when the event is emitted.
+     * @returns The current instance of EventEmitter for method chaining.
+     */
+    addListener(eventName: string | symbol, listener: (...arguments_: any[]) => void): IEventEmitter;
+    /**
+     * Registers a one-time listener for the specified event. The listener is removed after it is called once.
+     *
+     * @param eventName - The name (or symbol) of the event to listen for.
+     * @param listener - A callback function that will be invoked once when the event is emitted.
+     * @returns The current instance of EventEmitter for method chaining.
+     *
+     * @example
+     * emitter.once('close', () => {
+     *   console.log('The connection was closed.');
+     * });
+     */
+    once(eventName: string | symbol, listener: (...arguments_: any[]) => void): IEventEmitter;
+    /**
+     * Removes a previously registered listener for the specified event.
+     *
+     * @param eventName - The name (or symbol) of the event to stop listening for.
+     * @param listener - The specific callback function to remove.
+     * @returns The current instance of EventEmitter for method chaining.
+     *
+     * @example
+     * emitter.off('data', myListener);
+     */
+    off(eventName: string | symbol, listener: (...arguments_: any[]) => void): IEventEmitter;
+    /**
+     * Alias for `off`. Removes a previously registered listener for the specified event.
+     *
+     * @param eventName - The name (or symbol) of the event to stop listening for.
+     * @param listener - The specific callback function to remove.
+     * @returns The current instance of EventEmitter for method chaining.
+     */
+    removeListener(eventName: string | symbol, listener: (...arguments_: any[]) => void): IEventEmitter;
+    /**
+     * Emits the specified event, invoking all registered listeners with the provided arguments.
+     *
+     * @param eventName - The name (or symbol) of the event to emit.
+     * @param args - Arguments passed to each listener.
+     * @returns `true` if the event had listeners, `false` otherwise.
+     *
+     * @example
+     * emitter.emit('data', 'Hello World');
+     */
+    emit(eventName: string | symbol, ...arguments_: any[]): boolean;
+    /**
+     * Returns the number of listeners registered for the specified event.
+     *
+     * @param eventName - The name (or symbol) of the event.
+     * @returns The number of registered listeners.
+     *
+     * @example
+     * const count = emitter.listenerCount('data');
+     * console.log(count); // e.g., 2
+     */
+    listenerCount(eventName: string | symbol): number;
+    /**
+     * Removes all listeners for the specified event. If no event is specified, it removes all listeners for all events.
+     *
+     * @param eventName - (Optional) The name (or symbol) of the event.
+     * @returns The current instance of EventEmitter for method chaining.
+     *
+     * @example
+     * emitter.removeAllListeners('data');
+     */
+    removeAllListeners(eventName?: string | symbol): IEventEmitter;
+    /**
+     * Returns an array of event names for which listeners have been registered.
+     *
+     * @returns An array of event names (or symbols).
+     *
+     * @example
+     * const events = emitter.eventNames();
+     * console.log(events); // e.g., ['data', 'close']
+     */
+    eventNames(): Array<string | symbol>;
+    /**
+     * Returns an array of listeners registered for the specified event.
+     *
+     * @param eventName - The name (or symbol) of the event.
+     * @returns An array of listener functions.
+     *
+     * @example
+     * const listeners = emitter.listeners('data');
+     * console.log(listeners.length); // e.g., 2
+     */
+    listeners(eventName: string | symbol): Array<(...arguments_: any[]) => void>;
+    /**
+     * Returns an array of raw listeners for the specified event. This includes listeners wrapped by internal mechanisms (e.g., once-only listeners).
+     *
+     * @param eventName - The name (or symbol) of the event.
+     * @returns An array of raw listener functions.
+     *
+     * @example
+     * const rawListeners = emitter.rawListeners('data');
+     */
+    rawListeners(eventName: string | symbol): Array<(...arguments_: any[]) => void>;
+    /**
+     * Adds a listener to the beginning of the listeners array for the specified event.
+     *
+     * @param eventName - The name (or symbol) of the event to listen for.
+     * @param listener - A callback function that will be invoked when the event is emitted.
+     * @returns The current instance of EventEmitter for method chaining.
+     *
+     * @example
+     * emitter.prependListener('data', (message) => {
+     *   console.log('This will run first.');
+     * });
+     */
+    prependListener(eventName: string | symbol, listener: (...arguments_: any[]) => void): IEventEmitter;
+    /**
+     * Adds a one-time listener to the beginning of the listeners array for the specified event.
+     *
+     * @param eventName - The name (or symbol) of the event to listen for.
+     * @param listener - A callback function that will be invoked once when the event is emitted.
+     * @returns The current instance of EventEmitter for method chaining.
+     *
+     * @example
+     * emitter.prependOnceListener('data', (message) => {
+     *   console.log('This will run first and only once.');
+     * });
+     */
+    prependOnceListener(eventName: string | symbol, listener: (...arguments_: any[]) => void): IEventEmitter;
+};
+
 type EventListener = (...arguments_: any[]) => void;
-declare class Eventified {
-    _eventListeners: Map<string, EventListener[]>;
+declare class Eventified implements IEventEmitter {
+    _eventListeners: Map<string | symbol, EventListener[]>;
     _maxListeners: number;
     constructor();
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Gets an array of event names
+     * @returns {Array<string | symbol>} An array of event names
+     */
+    eventNames(): Array<string | symbol>;
+    /**
+     * Gets an array of 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
+     */
+    rawListeners(event?: string | symbol): EventListener[];
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Gets the maximum number of listeners that can be added for a single event
+     * @returns {number} The maximum number of listeners
+     */
     maxListeners(): number;
-    addListener(event: string, listener: EventListener): void;
-    on(event: string, listener: EventListener): void;
-    removeListener(event: string, listener: EventListener): void;
-    off(event: string, listener: EventListener): void;
-    emit(event: string, ...arguments_: any[]): void;
+    /**
+     * 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
+     */
+    addListener(event: string | symbol, listener: EventListener): IEventEmitter;
+    /**
+     * Adds a listener for a specific event
+     * @param {string | symbol} event
+     * @param {EventListener} listener
+     * @returns {IEventEmitter} returns the instance of the class for chaining
+     */
+    on(event: string | symbol, listener: EventListener): IEventEmitter;
+    /**
+     * 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
+     */
+    removeListener(event: string, listener: EventListener): IEventEmitter;
+    /**
+     * Removes a listener for a specific event
+     * @param {string | symbol} event
+     * @param {EventListener} listener
+     * @returns {IEventEmitter} returns the instance of the class for chaining
+     */
+    off(event: string | symbol, listener: EventListener): IEventEmitter;
+    /**
+     * 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
+     */
+    emit(event: string | symbol, ...arguments_: any[]): boolean;
+    /**
+     * 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
+     */
     listeners(event: string): EventListener[];
-    removeAllListeners(event?: string): void;
+    /**
+     * 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
+     */
+    removeAllListeners(event?: string): IEventEmitter;
+    /**
+     * Sets the maximum number of listeners that can be added for a single event
+     * @param {number} n The maximum number of listeners
+     * @returns {void}
+     */
     setMaxListeners(n: number): void;
+    /**
+     * Gets all listeners
+     * @returns {EventListener[]} An array of listeners
+     */
+    getAllListeners(): EventListener[];
 }
 
 type Hook = (...arguments_: any[]) => Promise<void> | void;
 declare class Hookified extends Eventified {
     _hooks: Map<string, Hook[]>;
     constructor();
+    /**
+     * Adds a handler function for a specific event
+     * @param {string} event
+     * @param {Hook} handler - this can be async or sync
+     * @returns {void}
+     */
     onHook(event: string, handler: Hook): void;
+    /**
+     * Adds a handler that only executes once for a specific event
+     * @param event
+     * @param handler
+     */
+    onceHook(event: string, handler: Hook): void;
+    /**
+     * Removes a handler function for a specific event
+     * @param {string} event
+     * @param {Hook} handler
+     * @returns {void}
+     */
     removeHook(event: string, handler: Hook): void;
+    /**
+     * Calls all handlers for a specific event
+     * @param {string} event
+     * @param {T[]} arguments_
+     * @returns {Promise<void>}
+     */
     hook<T>(event: string, ...arguments_: T[]): Promise<void>;
+    /**
+     * Gets all hooks
+     * @returns {Map<string, Hook[]>}
+     */
     get hooks(): Map<string, Hook[]>;
+    /**
+     * Gets all hooks for a specific event
+     * @param {string} event
+     * @returns {Hook[]}
+     */
     getHooks(event: string): Hook[] | undefined;
+    /**
+     * Removes all hooks
+     * @returns {void}
+     */
     clearHooks(): void;
 }
 

package/dist/node/index.js

@@ -6,13 +6,99 @@ var Eventified = class {
     this._eventListeners = /* @__PURE__ */ new Map();
     this._maxListeners = 100;
   }
+  /**
+   * 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, listener) {
+    const onceListener = (...arguments_) => {
+      this.off(eventName, onceListener);
+      listener(...arguments_);
+    };
+    this.on(eventName, onceListener);
+    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) {
+    if (!eventName) {
+      return this.getAllListeners().length;
+    }
+    const listeners = this._eventListeners.get(eventName);
+    return listeners ? listeners.length : 0;
+  }
+  /**
+   * Gets an array of event names
+   * @returns {Array<string | symbol>} An array of event names
+   */
+  eventNames() {
+    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} [event] (Optional) The event name
+   * @returns {EventListener[]} An array of listeners
+   */
+  rawListeners(event) {
+    if (!event) {
+      return this.getAllListeners();
+    }
+    return this._eventListeners.get(event) ?? [];
+  }
+  /**
+   * 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, listener) {
+    const listeners = this._eventListeners.get(eventName) ?? [];
+    listeners.unshift(listener);
+    this._eventListeners.set(eventName, listeners);
+    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, listener) {
+    const onceListener = (...arguments_) => {
+      this.off(eventName, onceListener);
+      listener(...arguments_);
+    };
+    this.prependListener(eventName, onceListener);
+    return this;
+  }
+  /**
+   * Gets the maximum number of listeners that can be added for a single event
+   * @returns {number} The maximum number of listeners
+   */
   maxListeners() {
     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
+   */
   addListener(event, listener) {
     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
+   */
   on(event, listener) {
     if (!this._eventListeners.has(event)) {
       this._eventListeners.set(event, []);
@@ -24,11 +110,24 @@ var Eventified = class {
       }
       listeners.push(listener);
     }
+    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
+   */
   removeListener(event, listener) {
     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
+   */
   off(event, listener) {
     const listeners = this._eventListeners.get(event) ?? [];
     const index = listeners.indexOf(listener);
@@ -38,29 +137,51 @@ var Eventified = class {
     if (listeners.length === 0) {
       this._eventListeners.delete(event);
     }
+    return this;
   }
-  // Emit an event
+  /**
+   * 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
+   */
   emit(event, ...arguments_) {
+    let result = false;
     const listeners = this._eventListeners.get(event);
     if (listeners && listeners.length > 0) {
       for (const listener of listeners) {
         listener(...arguments_);
+        result = 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
+   */
   listeners(event) {
     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
+   */
   removeAllListeners(event) {
     if (event) {
       this._eventListeners.delete(event);
     } else {
       this._eventListeners.clear();
     }
+    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}
+   */
   setMaxListeners(n) {
     this._maxListeners = n;
     for (const listeners of this._eventListeners.values()) {
@@ -69,6 +190,17 @@ var Eventified = class {
       }
     }
   }
+  /**
+   * Gets all listeners
+   * @returns {EventListener[]} An array of listeners
+   */
+  getAllListeners() {
+    let result = new Array();
+    for (const listeners of this._eventListeners.values()) {
+      result = result.concat(listeners);
+    }
+    return result;
+  }
 };
 
 // src/index.ts
@@ -78,7 +210,12 @@ var Hookified = class extends Eventified {
     super();
     this._hooks = /* @__PURE__ */ new Map();
   }
-  // Adds a handler function for a specific event
+  /**
+   * Adds a handler function for a specific event
+   * @param {string} event
+   * @param {Hook} handler - this can be async or sync
+   * @returns {void}
+   */
   onHook(event, handler) {
     const eventHandlers = this._hooks.get(event);
     if (eventHandlers) {
@@ -87,7 +224,24 @@ var Hookified = class extends Eventified {
       this._hooks.set(event, [handler]);
     }
   }
-  // Removes a specific handler function for a specific event
+  /**
+   * Adds a handler that only executes once for a specific event
+   * @param event
+   * @param handler
+   */
+  onceHook(event, handler) {
+    const hook = async (...arguments_) => {
+      this.removeHook(event, hook);
+      return handler(...arguments_);
+    };
+    this.onHook(event, hook);
+  }
+  /**
+   * Removes a handler function for a specific event
+   * @param {string} event
+   * @param {Hook} handler
+   * @returns {void}
+   */
   removeHook(event, handler) {
     const eventHandlers = this._hooks.get(event);
     if (eventHandlers) {
@@ -97,7 +251,12 @@ var Hookified = class 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<void>}
+   */
   async hook(event, ...arguments_) {
     const eventHandlers = this._hooks.get(event);
     if (eventHandlers) {
@@ -110,13 +269,25 @@ var Hookified = class extends Eventified {
       }
     }
   }
-  // Provides read-only access to the current handlers
+  /**
+   * Gets all hooks
+   * @returns {Map<string, Hook[]>}
+   */
   get hooks() {
     return this._hooks;
   }
+  /**
+   * Gets all hooks for a specific event
+   * @param {string} event
+   * @returns {Hook[]}
+   */
   getHooks(event) {
     return this._hooks.get(event);
   }
+  /**
+   * Removes all hooks
+   * @returns {void}
+   */
   clearHooks() {
     this._hooks.clear();
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hookified",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "Event and Middleware Hooks",
   "type": "module",
   "main": "dist/node/index.cjs",
@@ -57,12 +57,12 @@
   },
   "homepage": "https://github.com/jaredwray/hookified#readme",
   "devDependencies": {
-    "@vitest/coverage-v8": "^2.1.3",
-    "docula": "^0.9.3",
+    "@vitest/coverage-v8": "^2.1.4",
+    "docula": "^0.9.4",
     "rimraf": "^6.0.1",
-    "tsup": "^8.3.0",
+    "tsup": "^8.3.5",
     "typescript": "^5.6.3",
-    "vitest": "^2.1.3",
+    "vitest": "^2.1.4",
     "xo": "^0.59.3"
   },
   "files": [