hookified 1.15.0 → 2.0.0

package/dist/node/index.d.cts

@@ -8,16 +8,16 @@ type Logger = {
 };
 type EventEmitterOptions = {
     /**
-     * Logger instance for logging errors.
+     * Logger instance for logging events.
      */
-    logger?: Logger;
+    eventLogger?: Logger;
     /**
      * Whether to throw an error when emit 'error' and there are no listeners. Default is false and only emits an error event.
      */
     throwOnEmitError?: boolean;
     /**
      * Whether to throw on 'error' when there are no listeners. This is the standard functionality in EventEmitter
-     * @default false - in v2 this will be set to true by default
+     * @default true
      */
     throwOnEmptyListeners?: boolean;
 };
@@ -166,8 +166,12 @@ type IEventEmitter = {
     prependOnceListener(eventName: string | symbol, listener: (...arguments_: any[]) => void): IEventEmitter;
 };
 type EventListener = (...arguments_: any[]) => void;
-type Hook = (...arguments_: any[]) => Promise<void> | void;
-type HookEntry = {
+type HookFn = (...arguments_: any[]) => Promise<void> | void;
+interface IHook {
+    /**
+     * Unique identifier for the hook. Auto-generated via crypto.randomUUID() if not provided.
+     */
+    id?: string;
     /**
      * The event name for the hook
      */
@@ -175,14 +179,64 @@ type HookEntry = {
     /**
      * The handler function for the hook
      */
-    handler: Hook;
+    handler: HookFn;
+}
+type WaterfallHookResult = {
+    /**
+     * The hook function that produced this result
+     */
+    hook: WaterfallHookFn;
+    /**
+     * The value returned by the hook
+     */
+    result: any;
 };
-type HookifiedOptions = {
+type WaterfallHookContext = {
     /**
-     * Whether an error should be thrown when a hook throws an error. Default is false and only emits an error event.
-     * @deprecated - this will be deprecated in version 2. Please use throwOnHookError.
+     * The original arguments passed to the waterfall execution, before any hooks processed them.
+     */
+    initialArgs: any;
+    /**
+     * Array of results from previous hooks in execution order, each containing the hook and its result.
+     * Empty for the first hook.
+     */
+    results: WaterfallHookResult[];
+};
+type WaterfallHookFn = (context: WaterfallHookContext) => Promise<any> | any;
+interface IWaterfallHook extends IHook {
+    /**
+     * Array of hook functions that are called sequentially.
+     * Each hook receives a WaterfallHookContext with initialArgs and results.
+     */
+    hooks: WaterfallHookFn[];
+    /**
+     * Adds a hook function to the end of the waterfall chain
+     */
+    addHook(hook: WaterfallHookFn): void;
+    /**
+     * Removes a specific hook function from the waterfall chain
+     */
+    removeHook(hook: WaterfallHookFn): boolean;
+}
+type OnHookOptions = {
+    /**
+     * Per-call override for useHookClone.
+     * When true, hook objects are cloned before storing.
+     * When false, the original IHook reference is stored directly.
+     * When undefined, falls back to the instance-level useHookClone setting.
+     * @type {boolean}
      */
-    throwHookErrors?: boolean;
+    useHookClone?: boolean;
+    /**
+     * Controls where the hook is inserted in the handlers array.
+     * - "Top": Insert at the beginning (index 0), before all existing handlers.
+     * - "Bottom": Append to the end, after all existing handlers. This is the default.
+     * - number: Insert at a specific index. Values are clamped to the array bounds.
+     */
+    position?: "Top" | "Bottom" | number;
+};
+type PrependHookOptions = Omit<OnHookOptions, "position">;
+type HookifiedOptions = {
     /**
      * Whether an error should be thrown when a hook throws an error. Default is false and only emits an error event.
      */
@@ -205,26 +259,33 @@ type HookifiedOptions = {
      * @default true
      */
     allowDeprecated?: boolean;
+    /**
+     * Whether to clone hook objects before storing. Default is true.
+     * When false, the original IHook reference is stored directly.
+     * @type {boolean}
+     * @default true
+     */
+    useHookClone?: boolean;
 } & EventEmitterOptions;
 
 declare class Eventified implements IEventEmitter {
     private readonly _eventListeners;
     private _maxListeners;
-    private _logger?;
+    private _eventLogger?;
     private _throwOnEmitError;
     private _throwOnEmptyListeners;
     private _errorEvent;
     constructor(options?: EventEmitterOptions);
     /**
-     * Gets the logger
+     * Gets the event logger
      * @returns {Logger}
      */
-    get logger(): Logger | undefined;
+    get eventLogger(): Logger | undefined;
     /**
-     * Sets the logger
-     * @param {Logger} logger
+     * Sets the event logger
+     * @param {Logger} eventLogger
      */
-    set logger(logger: Logger | undefined);
+    set eventLogger(eventLogger: Logger | undefined);
     /**
      * Gets whether an error should be thrown when an emit throws an error. Default is false and only emits an error event.
      * @returns {boolean}
@@ -351,7 +412,57 @@ declare class Eventified implements IEventEmitter {
      * @param {string | symbol} eventName - The event name that determines the log level
      * @param {unknown} data - The data to log
      */
-    private sendLog;
+    private sendToEventLogger;
+}
+
+/**
+ * Concrete implementation of the IHook interface.
+ * Provides a convenient class-based way to create hook entries.
+ */
+declare class Hook implements IHook {
+    id?: string;
+    event: string;
+    handler: HookFn;
+    /**
+     * Creates a new Hook instance
+     * @param {string} event - The event name for the hook
+     * @param {HookFn} handler - The handler function for the hook
+     * @param {string} [id] - Optional unique identifier for the hook
+     */
+    constructor(event: string, handler: HookFn, id?: string);
+}
+
+/**
+ * A WaterfallHook chains multiple hook functions sequentially,
+ * where each hook receives a context with the previous result,
+ * initial arguments, and accumulated results. After all hooks
+ * have executed, the final handler receives the transformed result.
+ * Implements IHook for compatibility with Hookified.onHook().
+ */
+declare class WaterfallHook implements IWaterfallHook {
+    id?: string;
+    event: string;
+    handler: HookFn;
+    hooks: WaterfallHookFn[];
+    private readonly _finalHandler;
+    /**
+     * Creates a new WaterfallHook instance
+     * @param {string} event - The event name for the hook
+     * @param {WaterfallHookFn} finalHandler - The final handler function that receives the transformed result
+     * @param {string} [id] - Optional unique identifier for the hook
+     */
+    constructor(event: string, finalHandler: WaterfallHookFn, id?: string);
+    /**
+     * Adds a hook function to the end of the waterfall chain
+     * @param {WaterfallHookFn} hook - The hook function to add
+     */
+    addHook(hook: WaterfallHookFn): void;
+    /**
+     * Removes a specific hook function from the waterfall chain
+     * @param {WaterfallHookFn} hook - The hook function to remove
+     * @returns {boolean} true if the hook was found and removed
+     */
+    removeHook(hook: WaterfallHookFn): boolean;
 }
 
 declare class Hookified extends Eventified {
@@ -360,24 +471,13 @@ declare class Hookified extends Eventified {
     private _enforceBeforeAfter;
     private _deprecatedHooks;
     private _allowDeprecated;
+    private _useHookClone;
     constructor(options?: HookifiedOptions);
     /**
      * Gets all hooks
-     * @returns {Map<string, Hook[]>}
-     */
-    get hooks(): Map<string, Hook[]>;
-    /**
-     * Gets whether an error should be thrown when a hook throws an error. Default is false and only emits an error event.
-     * @returns {boolean}
-     * @deprecated - this will be deprecated in version 2. Please use throwOnHookError.
-     */
-    get throwHookErrors(): boolean;
-    /**
-     * Sets whether an error should be thrown when a hook throws an error. Default is false and only emits an error event.
-     * @param {boolean} value
-     * @deprecated - this will be deprecated in version 2. Please use throwOnHookError.
+     * @returns {Map<string, IHook[]>}
      */
-    set throwHookErrors(value: boolean);
+    get hooks(): Map<string, IHook[]>;
     /**
      * Gets whether an error should be thrown when a hook throws an error. Default is false and only emits an error event.
      * @returns {boolean}
@@ -420,75 +520,72 @@ declare class Hookified extends Eventified {
      */
     set allowDeprecated(value: boolean);
     /**
-     * Validates hook event name if enforceBeforeAfter is enabled
-     * @param {string} event - The event name to validate
-     * @throws {Error} If enforceBeforeAfter is true and event doesn't start with 'before' or 'after'
-     */
-    private validateHookName;
-    /**
-     * Checks if a hook is deprecated and emits a warning if it is
-     * @param {string} event - The event name to check
-     * @returns {boolean} - Returns true if the hook should proceed, false if it should be blocked
+     * Gets whether hook objects are cloned before storing. Default is true.
+     * @returns {boolean}
      */
-    private checkDeprecatedHook;
+    get useHookClone(): boolean;
     /**
-     * Adds a handler function for a specific event
-     * @param {string} event
-     * @param {Hook} handler - this can be async or sync
-     * @returns {void}
+     * Sets whether hook objects are cloned before storing. Default is true.
+     * When false, the original IHook reference is stored directly.
+     * @param {boolean} value
      */
-    onHook(event: string, handler: Hook): void;
+    set useHookClone(value: boolean);
     /**
-     * Adds a handler function for a specific event
-     * @param {HookEntry} hookEntry
-     * @returns {void}
+     * Adds a handler function for a specific event.
+     * If you prefer the legacy `(event, handler)` signature, use {@link addHook} instead.
+     * To register multiple hooks at once, use {@link onHooks}.
+     * @param {IHook} hook - the hook containing event name and handler
+     * @param {OnHookOptions} [options] - optional per-call options (e.g., useHookClone override, position)
+     * @returns {IHook | undefined} the stored hook, or undefined if blocked by deprecation
      */
-    onHookEntry(hookEntry: HookEntry): void;
+    onHook(hook: IHook, options?: OnHookOptions): IHook | undefined;
     /**
      * Alias for onHook. This is provided for compatibility with other libraries that use the `addHook` method.
-     * @param {string} event
-     * @param {Hook} handler - this can be async or sync
+     * @param {string} event - the event name
+     * @param {HookFn} handler - the handler function
      * @returns {void}
      */
-    addHook(event: string, handler: Hook): void;
+    addHook(event: string, handler: HookFn): void;
     /**
-     * Adds a handler function for a specific event
-     * @param {Array<HookEntry>} hooks
+     * Adds handler functions for specific events
+     * @param {Array<IHook>} hooks
+     * @param {OnHookOptions} [options] - optional per-call options (e.g., useHookClone override, position)
      * @returns {void}
      */
-    onHooks(hooks: HookEntry[]): void;
+    onHooks(hooks: IHook[], options?: OnHookOptions): void;
     /**
-     * Adds a handler function for a specific event that runs before all other handlers
-     * @param {string} event
-     * @param {Hook} handler - this can be async or sync
-     * @returns {void}
+     * Adds a handler function for a specific event that runs before all other handlers.
+     * Equivalent to calling `onHook(hook, { position: "Top" })`.
+     * @param {IHook} hook - the hook containing event name and handler
+     * @param {PrependHookOptions} [options] - optional per-call options (e.g., useHookClone override)
+     * @returns {IHook | undefined} the stored hook, or undefined if blocked by deprecation
      */
-    prependHook(event: string, handler: Hook): void;
+    prependHook(hook: IHook, options?: PrependHookOptions): IHook | undefined;
     /**
-     * Adds a handler that only executes once for a specific event before all other handlers
-     * @param event
-     * @param handler
+     * Adds a handler that only executes once for a specific event before all other handlers.
+     * Equivalent to calling `onHook` with a self-removing wrapper and `{ position: "Top" }`.
+     * @param {IHook} hook - the hook containing event name and handler
+     * @param {PrependHookOptions} [options] - optional per-call options (e.g., useHookClone override)
+     * @returns {IHook | undefined} the stored hook, or undefined if blocked by deprecation
      */
-    prependOnceHook(event: string, handler: Hook): void;
+    prependOnceHook(hook: IHook, options?: PrependHookOptions): IHook | undefined;
     /**
      * Adds a handler that only executes once for a specific event
-     * @param event
-     * @param handler
+     * @param {IHook} hook - the hook containing event name and handler
      */
-    onceHook(event: string, handler: Hook): void;
+    onceHook(hook: IHook): void;
     /**
      * Removes a handler function for a specific event
-     * @param {string} event
-     * @param {Hook} handler
-     * @returns {void}
+     * @param {IHook} hook - the hook containing event name and handler to remove
+     * @returns {IHook | undefined} the removed hook, or undefined if not found
      */
-    removeHook(event: string, handler: Hook): void;
+    removeHook(hook: IHook): IHook | undefined;
     /**
-     * Removes all handlers for a specific event
-     * @param {Array<HookEntry>} hooks
-     * @returns {void}
+     * Removes multiple hook handlers
+     * @param {Array<IHook>} hooks
+     * @returns {IHook[]} the hooks that were successfully removed
      */
-    removeHooks(hooks: HookEntry[]): void;
+    removeHooks(hooks: IHook[]): IHook[];
     /**
      * Calls all handlers for a specific event
      * @param {string} event
@@ -530,14 +627,44 @@ declare class Hookified extends Eventified {
     /**
      * Gets all hooks for a specific event
      * @param {string} event
-     * @returns {Hook[]}
+     * @returns {IHook[]}
+     */
+    getHooks(event: string): IHook[] | undefined;
+    /**
+     * Gets a specific hook by id, searching across all events
+     * @param {string} id - the hook id
+     * @returns {IHook | undefined} the hook if found, or undefined
+     */
+    getHook(id: string): IHook | undefined;
+    /**
+     * Removes one or more hooks by id, searching across all events
+     * @param {string | string[]} id - the hook id or array of hook ids to remove
+     * @returns {IHook | IHook[] | undefined} the removed hook(s), or undefined/empty array if not found
      */
-    getHooks(event: string): Hook[] | undefined;
+    removeHookById(id: string | string[]): IHook | IHook[] | undefined;
     /**
      * Removes all hooks
      * @returns {void}
      */
     clearHooks(): void;
+    /**
+     * Removes all hooks for a specific event and returns the removed hooks.
+     * @param {string} event - The event name to remove hooks for.
+     * @returns {IHook[]} the hooks that were removed
+     */
+    removeEventHooks(event: string): IHook[];
+    /**
+     * Validates hook event name if enforceBeforeAfter is enabled
+     * @param {string} event - The event name to validate
+     * @throws {Error} If enforceBeforeAfter is true and event doesn't start with 'before' or 'after'
+     */
+    private validateHookName;
+    /**
+     * Checks if a hook is deprecated and emits a warning if it is
+     * @param {string} event - The event name to check
+     * @returns {boolean} - Returns true if the hook should proceed, false if it should be blocked
+     */
+    private checkDeprecatedHook;
 }
 
-export { type EventEmitterOptions, type EventListener, Eventified, type Hook, type HookEntry, Hookified, type HookifiedOptions, type IEventEmitter, type Logger };
+export { type EventEmitterOptions, type EventListener, Eventified, Hook, type HookFn, Hookified, type HookifiedOptions, type IEventEmitter, type IHook, type IWaterfallHook, type Logger, type OnHookOptions, type PrependHookOptions, WaterfallHook, type WaterfallHookContext, type WaterfallHookFn, type WaterfallHookResult };