@tsed/hooks 8.19.2 → 8.19.3

package/lib/esm/Hooks.js

@@ -1,11 +1,42 @@
 function match(ref, item) {
     return !ref || !item.ref || (ref && item.ref === ref);
 }
+/**
+ * A lightweight event management system for registering, emitting, and managing hook listeners.
+ *
+ * The Hooks class provides a flexible event system that supports:
+ * - Registering listeners with optional references for targeted management
+ * - One-time event listeners
+ * - Synchronous and asynchronous event emission
+ * - Value transformation through alter hooks
+ * - Listener removal by callback or reference
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * const hooks = new Hooks();
+ *
+ * // Register a listener
+ * hooks.on("user:created", (user) => {
+ *   console.log("User created:", user);
+ * });
+ *
+ * // Emit an event
+ * hooks.emit("user:created", [{name: "John"}]);
+ *
+ * // Alter a value through hooks
+ * const modified = hooks.alter("transform:data", {value: 10}, []);
+ * ```
+ *
+ * @public
+ */
 export class Hooks {
     #listeners = new Map();
     /**
-     * Check if an event has listeners
-     * @param event
+     * Check if an event has registered listeners.
+     *
+     * @param event - The event name to check
+     * @returns `true` if the event has at least one listener, `false` otherwise
      */
     has(event) {
         return !!this.#listeners.get(event)?.length;
@@ -85,11 +116,29 @@ export class Hooks {
         }
     }
     /**
-     * Trigger an event, listener alter given value and return it.
-     * @param event
-     * @param value
-     * @param args
-     * @param callThis
+     * Transform a value by passing it through all registered listeners sequentially.
+     *
+     * Each listener receives the value (potentially modified by previous listeners) and returns
+     * a new or modified value. The final transformed value is returned after all listeners
+     * have been applied. This is useful for implementing middleware-like transformation chains.
+     *
+     * ### Usage
+     *
+     * ```typescript
+     * hooks.on("format:name", (name) => name.trim());
+     * hooks.on("format:name", (name) => name.toUpperCase());
+     *
+     * const result = hooks.alter("format:name", "  john  ");
+     * // result: "JOHN"
+     * ```
+     *
+     * @typeParam Arg - The type of the input value
+     * @typeParam AlteredArg - The type of the returned value (can be different from input)
+     * @param event - The event name
+     * @param value - The initial value to transform
+     * @param args - Additional arguments passed to each listener
+     * @param callThis - The context (`this`) to use when calling listeners
+     * @returns The final transformed value after all listeners have been applied
      */
     alter(event, value, args = [], callThis = null) {
         const items = this.#listeners.get(event);
@@ -101,11 +150,34 @@ export class Hooks {
         return value;
     }
     /**
-     * Trigger an event, async listener alter given value and return it.
-     * @param event
-     * @param value
-     * @param args
-     * @param callThis
+     * Transform a value asynchronously by passing it through all registered listeners sequentially.
+     *
+     * Similar to `alter`, but each listener can be async and is awaited before the next listener
+     * is called. The value is transformed sequentially through the chain of async listeners.
+     * This is useful for async transformation pipelines like data validation, sanitization, or enrichment.
+     *
+     * ### Usage
+     *
+     * ```typescript
+     * hooks.on("process:data", async (data) => {
+     *   return await validateData(data);
+     * });
+     *
+     * hooks.on("process:data", async (data) => {
+     *   return await enrichData(data);
+     * });
+     *
+     * const result = await hooks.asyncAlter("process:data", rawData);
+     * // result: enriched and validated data
+     * ```
+     *
+     * @typeParam Arg - The type of the input value
+     * @typeParam AlteredArg - The type of the returned value (can be different from input)
+     * @param event - The event name
+     * @param value - The initial value to transform
+     * @param args - Additional arguments passed to each listener
+     * @param callThis - The context (`this`) to use when calling listeners
+     * @returns A promise resolving to the final transformed value after all listeners have been applied
      */
     async asyncAlter(event, value, args = [], callThis = null) {
         const items = this.#listeners.get(event);
@@ -116,15 +188,117 @@ export class Hooks {
         }
         return value;
     }
+    /**
+     * Remove all registered listeners and clean up the hooks instance.
+     *
+     * This method clears all event listeners from the instance, effectively resetting it
+     * to an empty state. Useful for cleanup operations, testing, or when disposing of
+     * a Hooks instance.
+     *
+     * ### Usage
+     *
+     * ```typescript
+     * const hooks = new Hooks();
+     * hooks.on("event1", callback1);
+     * hooks.on("event2", callback2);
+     *
+     * hooks.destroy();
+     * // All listeners are now removed
+     * ```
+     */
     destroy() {
         this.#listeners.clear();
     }
 }
+/**
+ * Global singleton instance of the Hooks class.
+ *
+ * This instance provides a centralized event management system that can be used
+ * throughout an application without needing to create and pass around separate
+ * Hooks instances.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * import {hooks} from "@tsed/hooks";
+ *
+ * hooks.on("app:started", () => {
+ *   console.log("Application started");
+ * });
+ *
+ * hooks.emit("app:started", []);
+ * ```
+ *
+ * @public
+ */
 export const hooks = new Hooks();
+/**
+ * Functional helper to register a hook listener on the global hooks instance.
+ *
+ * This is a convenience function bound to the global `hooks.on` method,
+ * allowing for a more concise functional programming style.
+ *
+ * @public
+ * @see {@link Hooks.on}
+ */
 export const $on = hooks.on.bind(hooks);
+/**
+ * Functional helper to register a one-time hook listener on the global hooks instance.
+ *
+ * This is a convenience function bound to the global `hooks.once` method.
+ * The listener will be automatically removed after being invoked once.
+ *
+ * @public
+ * @see {@link Hooks.once}
+ */
 export const $once = hooks.once.bind(hooks);
+/**
+ * Functional helper to remove hook listeners from the global hooks instance.
+ *
+ * This is a convenience function bound to the global `hooks.off` method,
+ * supporting removal by event name and callback, or by reference.
+ *
+ * @public
+ * @see {@link Hooks.off}
+ */
 export const $off = hooks.off.bind(hooks);
+/**
+ * Functional helper to emit synchronous events on the global hooks instance.
+ *
+ * This is a convenience function bound to the global `hooks.emit` method,
+ * triggering all registered listeners for the specified event.
+ *
+ * @public
+ * @see {@link Hooks.emit}
+ */
 export const $emit = hooks.emit.bind(hooks);
+/**
+ * Functional helper to emit asynchronous events on the global hooks instance.
+ *
+ * This is a convenience function bound to the global `hooks.asyncEmit` method,
+ * awaiting all listener promises in parallel.
+ *
+ * @public
+ * @see {@link Hooks.asyncEmit}
+ */
 export const $asyncEmit = hooks.asyncEmit.bind(hooks);
+/**
+ * Functional helper to alter values through synchronous hooks on the global hooks instance.
+ *
+ * This is a convenience function bound to the global `hooks.alter` method,
+ * allowing listeners to transform a value sequentially.
+ *
+ * @public
+ * @see {@link Hooks.alter}
+ */
 export const $alter = hooks.alter.bind(hooks);
+/**
+ * Functional helper to alter values through asynchronous hooks on the global hooks instance.
+ *
+ * This is a convenience function bound to the global `hooks.asyncAlter` method,
+ * allowing async listeners to transform a value sequentially.
+ *
+ * @public
+ * @see {@link Hooks.asyncAlter}
+ */
 export const $asyncAlter = hooks.asyncAlter.bind(hooks);

package/lib/types/Hooks.d.ts

@@ -1,99 +1,455 @@
+/**
+ * A reference that can be used to identify and manage hook listeners.
+ *
+ * This type allows various kinds of values to be used as references when registering
+ * hook listeners, enabling flexible listener management and targeted event emission.
+ *
+ * @public
+ */
 export type HookRef = string | symbol | any | Function;
+/**
+ * A function that handles hook events.
+ *
+ * Hook listeners are invoked when their associated event is emitted or altered,
+ * receiving the event arguments as parameters.
+ *
+ * @public
+ */
 export type HookListener = Function;
+/**
+ * A lightweight event management system for registering, emitting, and managing hook listeners.
+ *
+ * The Hooks class provides a flexible event system that supports:
+ * - Registering listeners with optional references for targeted management
+ * - One-time event listeners
+ * - Synchronous and asynchronous event emission
+ * - Value transformation through alter hooks
+ * - Listener removal by callback or reference
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * const hooks = new Hooks();
+ *
+ * // Register a listener
+ * hooks.on("user:created", (user) => {
+ *   console.log("User created:", user);
+ * });
+ *
+ * // Emit an event
+ * hooks.emit("user:created", [{name: "John"}]);
+ *
+ * // Alter a value through hooks
+ * const modified = hooks.alter("transform:data", {value: 10}, []);
+ * ```
+ *
+ * @public
+ */
 export declare class Hooks {
     #private;
     /**
-     * Check if an event has listeners
-     * @param event
+     * Check if an event has registered listeners.
+     *
+     * @param event - The event name to check
+     * @returns `true` if the event has at least one listener, `false` otherwise
      */
     has(event: string): boolean;
     /**
-     * Listen a hook event
-     * @param event The event name
-     * @param ref The reference of the listener
-     * @param cb The callback
+     * Register a listener for a hook event with an optional reference.
+     *
+     * The reference can be used later to remove all listeners associated with it,
+     * or to emit events targeting only listeners with a specific reference.
+     *
+     * ### Usage
+     *
+     * ```typescript
+     * // Register a listener without reference
+     * hooks.on("user:created", (user) => {
+     *   console.log("User created:", user);
+     * });
+     *
+     * // Register a listener with reference
+     * hooks.on("user:created", MyController, (user) => {
+     *   console.log("Controller notified:", user);
+     * });
+     * ```
+     *
+     * @param event - The event name to listen to
+     * @param ref - Optional reference to associate with this listener
+     * @param cb - The callback function to invoke when the event is emitted
+     * @returns The Hooks instance for method chaining
      */
     on(event: string, ref: HookRef, cb: HookListener): this;
     /**
-     * Listen a hook event
-     * @param event The event name
-     * @param cb The callback
+     * Register a listener for a hook event.
+     *
+     * @param event - The event name to listen to
+     * @param cb - The callback function to invoke when the event is emitted
+     * @returns The Hooks instance for method chaining
      */
     on(event: string, cb: HookListener): this;
     /**
-     * Listen a hook event once
+     * Register a one-time listener for a hook event with an optional reference.
+     *
+     * The listener will be automatically removed after being invoked once.
+     * This is useful for handling events that should only trigger a single action.
+     *
+     * ### Usage
+     *
+     * ```typescript
+     * // Listen once without reference
+     * hooks.once("app:ready", () => {
+     *   console.log("App is ready!");
+     * });
      *
-     * @param event The event name
-     * @param ref The reference of the listener
-     * @param cb The callback
+     * // Listen once with reference
+     * hooks.once("initialization:complete", MyService, () => {
+     *   console.log("Service initialized");
+     * });
+     * ```
+     *
+     * @param event - The event name to listen to
+     * @param ref - Optional reference to associate with this listener
+     * @param cb - The callback function to invoke when the event is emitted
+     * @returns The Hooks instance for method chaining
      */
     once(event: string, ref: HookRef, cb: HookListener): this;
     /**
-     * Listen a hook event once
-     * @param event
-     * @param cb
+     * Register a one-time listener for a hook event.
+     *
+     * The listener will be automatically removed after being invoked once.
+     *
+     * @param event - The event name to listen to
+     * @param cb - The callback function to invoke when the event is emitted
+     * @returns The Hooks instance for method chaining
      */
     once(event: string, cb: HookListener): this;
     /**
-     * Remove a listener attached to an event
-     * @param ref
+     * Remove all listeners associated with a specific reference.
+     *
+     * This will remove all listeners across all events that were registered
+     * with the given reference, regardless of the event name.
+     *
+     * ### Usage
+     *
+     * ```typescript
+     * // Register listeners with a reference
+     * hooks.on("event1", MyController, callback1);
+     * hooks.on("event2", MyController, callback2);
+     *
+     * // Remove all listeners for MyController
+     * hooks.off(MyController);
+     * ```
+     *
+     * @param ref - The reference to remove all associated listeners
+     * @returns The Hooks instance for method chaining
      */
     off(ref: HookRef): this;
     /**
-     * Remove a listener attached to an event
-     * @param event
-     * @param cb
+     * Remove a specific listener from an event.
+     *
+     * This will only remove the exact callback function from the specified event.
+     *
+     * ### Usage
+     *
+     * ```typescript
+     * const callback = (data) => console.log(data);
+     * hooks.on("my:event", callback);
+     *
+     * // Remove the specific callback
+     * hooks.off("my:event", callback);
+     * ```
+     *
+     * @param event - The event name
+     * @param cb - The callback function to remove
+     * @returns The Hooks instance for method chaining
      */
     off(event: string, cb: HookListener): this;
     /**
-     * Trigger an event without arguments.
-     * @param event The event name
+     * Trigger an event and invoke all registered listeners synchronously.
+     *
+     * This method calls all listeners registered for the specified event without any arguments.
+     *
+     * ### Usage
+     *
+     * ```typescript
+     * hooks.on("app:started", () => console.log("App started"));
+     * hooks.emit("app:started");
+     * ```
+     *
+     * @param event - The event name to emit
      */
     emit(event: string): void;
     /**
-     * Trigger an event and call listener.
-     * @param event
-     * @param args
-     * @param callThis
+     * Trigger an event and invoke all registered listeners with arguments.
+     *
+     * All listeners for the event will be called synchronously with the provided arguments.
+     *
+     * ### Usage
+     *
+     * ```typescript
+     * hooks.on("user:created", (user, timestamp) => {
+     *   console.log("User created:", user, "at", timestamp);
+     * });
+     *
+     * hooks.emit("user:created", [{name: "John"}, Date.now()]);
+     * ```
+     *
+     * @param event - The event name to emit
+     * @param args - Array of arguments to pass to the listeners
      */
     emit(event: string, args: unknown[]): void;
     /**
-     * Trigger an event with arguments and call only listener attached to the given ref.
-     * @param event The event name
-     * @param ref The reference of the listener
-     * @param args The arguments
+     * Trigger an event and invoke only listeners attached to a specific reference.
+     *
+     * This allows targeted event emission to listeners registered with a particular reference,
+     * while ignoring listeners without that reference.
+     *
+     * ### Usage
+     *
+     * ```typescript
+     * hooks.on("data:update", MyController, (data) => {
+     *   console.log("Controller notified:", data);
+     * });
+     *
+     * // Only triggers listeners with MyController reference
+     * hooks.emit("data:update", MyController, [{id: 1}]);
+     * ```
+     *
+     * @param event - The event name to emit
+     * @param ref - The reference to target specific listeners
+     * @param args - Optional array of arguments to pass to the listeners
      */
     emit(event: string, ref: HookRef, args?: unknown[]): void;
     /**
-     * Trigger an event and call async listener.
-     * @param event The event name
+     * Trigger an event and invoke all registered listeners asynchronously.
+     *
+     * All listeners are called in parallel and the method waits for all promises to resolve.
+     * This is useful when listeners perform async operations like database queries or API calls.
+     *
+     * ### Usage
+     *
+     * ```typescript
+     * hooks.on("user:created", async (user) => {
+     *   await sendWelcomeEmail(user);
+     * });
+     *
+     * await hooks.asyncEmit("user:created");
+     * ```
+     *
+     * @param event - The event name to emit
+     * @returns A promise that resolves when all listeners have completed
      */
     asyncEmit(event: string): Promise<void>;
+    /**
+     * Trigger an event and invoke all registered listeners asynchronously with arguments.
+     *
+     * All listeners are called in parallel with the provided arguments,
+     * and the method waits for all promises to resolve.
+     *
+     * ### Usage
+     *
+     * ```typescript
+     * hooks.on("order:created", async (order, userId) => {
+     *   await notifyUser(userId, order);
+     * });
+     *
+     * await hooks.asyncEmit("order:created", [orderData, 123]);
+     * ```
+     *
+     * @param event - The event name to emit
+     * @param args - Array of arguments to pass to the listeners
+     * @returns A promise that resolves when all listeners have completed
+     */
     asyncEmit(event: string, args: unknown[]): Promise<void>;
+    /**
+     * Trigger an event asynchronously for listeners with a specific reference.
+     *
+     * Only listeners registered with the specified reference will be invoked.
+     * All matching listeners are called in parallel.
+     *
+     * ### Usage
+     *
+     * ```typescript
+     * hooks.on("data:sync", MyService, async (data) => {
+     *   await syncToDatabase(data);
+     * });
+     *
+     * await hooks.asyncEmit("data:sync", MyService, [newData]);
+     * ```
+     *
+     * @param event - The event name to emit
+     * @param ref - The reference to target specific listeners
+     * @param args - Optional array of arguments to pass to the listeners
+     * @returns A promise that resolves when all listeners have completed
+     */
     asyncEmit(event: string, ref: HookRef, args?: unknown[]): Promise<void>;
     /**
-     * Trigger an event, listener alter given value and return it.
-     * @param event
-     * @param value
-     * @param args
-     * @param callThis
+     * Transform a value by passing it through all registered listeners sequentially.
+     *
+     * Each listener receives the value (potentially modified by previous listeners) and returns
+     * a new or modified value. The final transformed value is returned after all listeners
+     * have been applied. This is useful for implementing middleware-like transformation chains.
+     *
+     * ### Usage
+     *
+     * ```typescript
+     * hooks.on("format:name", (name) => name.trim());
+     * hooks.on("format:name", (name) => name.toUpperCase());
+     *
+     * const result = hooks.alter("format:name", "  john  ");
+     * // result: "JOHN"
+     * ```
+     *
+     * @typeParam Arg - The type of the input value
+     * @typeParam AlteredArg - The type of the returned value (can be different from input)
+     * @param event - The event name
+     * @param value - The initial value to transform
+     * @param args - Additional arguments passed to each listener
+     * @param callThis - The context (`this`) to use when calling listeners
+     * @returns The final transformed value after all listeners have been applied
      */
     alter<Arg = unknown, AlteredArg = Arg>(event: string, value: Arg, args?: unknown[], callThis?: unknown): AlteredArg;
     /**
-     * Trigger an event, async listener alter given value and return it.
-     * @param event
-     * @param value
-     * @param args
-     * @param callThis
+     * Transform a value asynchronously by passing it through all registered listeners sequentially.
+     *
+     * Similar to `alter`, but each listener can be async and is awaited before the next listener
+     * is called. The value is transformed sequentially through the chain of async listeners.
+     * This is useful for async transformation pipelines like data validation, sanitization, or enrichment.
+     *
+     * ### Usage
+     *
+     * ```typescript
+     * hooks.on("process:data", async (data) => {
+     *   return await validateData(data);
+     * });
+     *
+     * hooks.on("process:data", async (data) => {
+     *   return await enrichData(data);
+     * });
+     *
+     * const result = await hooks.asyncAlter("process:data", rawData);
+     * // result: enriched and validated data
+     * ```
+     *
+     * @typeParam Arg - The type of the input value
+     * @typeParam AlteredArg - The type of the returned value (can be different from input)
+     * @param event - The event name
+     * @param value - The initial value to transform
+     * @param args - Additional arguments passed to each listener
+     * @param callThis - The context (`this`) to use when calling listeners
+     * @returns A promise resolving to the final transformed value after all listeners have been applied
      */
     asyncAlter<Arg = unknown, AlteredArg = Arg>(event: string, value: Arg, args?: unknown[], callThis?: unknown): Promise<AlteredArg>;
+    /**
+     * Remove all registered listeners and clean up the hooks instance.
+     *
+     * This method clears all event listeners from the instance, effectively resetting it
+     * to an empty state. Useful for cleanup operations, testing, or when disposing of
+     * a Hooks instance.
+     *
+     * ### Usage
+     *
+     * ```typescript
+     * const hooks = new Hooks();
+     * hooks.on("event1", callback1);
+     * hooks.on("event2", callback2);
+     *
+     * hooks.destroy();
+     * // All listeners are now removed
+     * ```
+     */
     destroy(): void;
 }
+/**
+ * Global singleton instance of the Hooks class.
+ *
+ * This instance provides a centralized event management system that can be used
+ * throughout an application without needing to create and pass around separate
+ * Hooks instances.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * import {hooks} from "@tsed/hooks";
+ *
+ * hooks.on("app:started", () => {
+ *   console.log("Application started");
+ * });
+ *
+ * hooks.emit("app:started", []);
+ * ```
+ *
+ * @public
+ */
 export declare const hooks: Hooks;
+/**
+ * Functional helper to register a hook listener on the global hooks instance.
+ *
+ * This is a convenience function bound to the global `hooks.on` method,
+ * allowing for a more concise functional programming style.
+ *
+ * @public
+ * @see {@link Hooks.on}
+ */
 export declare const $on: typeof hooks.on;
+/**
+ * Functional helper to register a one-time hook listener on the global hooks instance.
+ *
+ * This is a convenience function bound to the global `hooks.once` method.
+ * The listener will be automatically removed after being invoked once.
+ *
+ * @public
+ * @see {@link Hooks.once}
+ */
 export declare const $once: typeof hooks.once;
+/**
+ * Functional helper to remove hook listeners from the global hooks instance.
+ *
+ * This is a convenience function bound to the global `hooks.off` method,
+ * supporting removal by event name and callback, or by reference.
+ *
+ * @public
+ * @see {@link Hooks.off}
+ */
 export declare const $off: typeof hooks.off;
+/**
+ * Functional helper to emit synchronous events on the global hooks instance.
+ *
+ * This is a convenience function bound to the global `hooks.emit` method,
+ * triggering all registered listeners for the specified event.
+ *
+ * @public
+ * @see {@link Hooks.emit}
+ */
 export declare const $emit: typeof hooks.emit;
+/**
+ * Functional helper to emit asynchronous events on the global hooks instance.
+ *
+ * This is a convenience function bound to the global `hooks.asyncEmit` method,
+ * awaiting all listener promises in parallel.
+ *
+ * @public
+ * @see {@link Hooks.asyncEmit}
+ */
 export declare const $asyncEmit: typeof hooks.asyncEmit;
+/**
+ * Functional helper to alter values through synchronous hooks on the global hooks instance.
+ *
+ * This is a convenience function bound to the global `hooks.alter` method,
+ * allowing listeners to transform a value sequentially.
+ *
+ * @public
+ * @see {@link Hooks.alter}
+ */
 export declare const $alter: typeof hooks.alter;
+/**
+ * Functional helper to alter values through asynchronous hooks on the global hooks instance.
+ *
+ * This is a convenience function bound to the global `hooks.asyncAlter` method,
+ * allowing async listeners to transform a value sequentially.
+ *
+ * @public
+ * @see {@link Hooks.asyncAlter}
+ */
 export declare const $asyncAlter: typeof hooks.asyncAlter;

package/package.json

@@ -2,7 +2,7 @@
   "name": "@tsed/hooks",
   "description": "Hooks module for Ts.ED Framework",
   "type": "module",
-  "version": "8.19.2",
+  "version": "8.19.3",
   "source": "./src/index.ts",
   "main": "./lib/esm/index.js",
   "module": "./lib/esm/index.js",
@@ -27,8 +27,8 @@
   },
   "devDependencies": {
     "@tsed/monorepo-utils": "3.0.0",
-    "@tsed/typescript": "8.19.2",
-    "@tsed/vitest": "8.19.2",
+    "@tsed/typescript": "8.19.3",
+    "@tsed/vitest": "8.19.3",
     "eslint": "9.12.0",
     "typescript": "5.9.3",
     "vite": "7.1.11",