hookified 1.15.0 → 2.0.0

package/dist/browser/index.global.js

@@ -9,13 +9,13 @@
     constructor(options) {
       __publicField(this, "_eventListeners");
       __publicField(this, "_maxListeners");
-      __publicField(this, "_logger");
+      __publicField(this, "_eventLogger");
       __publicField(this, "_throwOnEmitError", false);
-      __publicField(this, "_throwOnEmptyListeners", false);
+      __publicField(this, "_throwOnEmptyListeners", true);
       __publicField(this, "_errorEvent", "error");
       this._eventListeners = /* @__PURE__ */ new Map();
-      this._maxListeners = 100;
-      this._logger = options?.logger;
+      this._maxListeners = 0;
+      this._eventLogger = options?.eventLogger;
       if (options?.throwOnEmitError !== void 0) {
         this._throwOnEmitError = options.throwOnEmitError;
       }
@@ -24,18 +24,18 @@
       }
     }
     /**
-     * Gets the logger
+     * Gets the event logger
      * @returns {Logger}
      */
-    get logger() {
-      return this._logger;
+    get eventLogger() {
+      return this._eventLogger;
     }
     /**
-     * Sets the logger
-     * @param {Logger} logger
+     * Sets the event logger
+     * @param {Logger} eventLogger
      */
-    set logger(logger) {
-      this._logger = logger;
+    set eventLogger(eventLogger) {
+      this._eventLogger = eventLogger;
     }
     /**
      * Gets whether an error should be thrown when an emit throws an error. Default is false and only emits an error event.
@@ -164,7 +164,7 @@
       }
       const listeners = this._eventListeners.get(event);
       if (listeners) {
-        if (listeners.length >= this._maxListeners) {
+        if (this._maxListeners > 0 && listeners.length >= this._maxListeners) {
           console.warn(
             `MaxListenersExceededWarning: Possible event memory leak detected. ${listeners.length + 1} ${event} listeners added. Use setMaxListeners() to increase limit.`
           );
@@ -215,6 +215,7 @@
           result = true;
         }
       }
+      this.sendToEventLogger(event, arguments_);
       if (event === this._errorEvent) {
         const error = arguments_[0] instanceof Error ? arguments_[0] : new Error(`${arguments_[0]}`);
         if (this._throwOnEmitError && !result) {
@@ -225,7 +226,6 @@
           }
         }
       }
-      this.sendLog(event, arguments_);
       return result;
     }
     /**
@@ -255,12 +255,7 @@
      * @returns {void}
      */
     setMaxListeners(n) {
-      this._maxListeners = n;
-      for (const listeners of this._eventListeners.values()) {
-        if (listeners.length > n) {
-          listeners.splice(n);
-        }
-      }
+      this._maxListeners = n < 0 ? 0 : n;
     }
     /**
      * Gets all listeners
@@ -278,8 +273,8 @@
      * @param {string | symbol} eventName - The event name that determines the log level
      * @param {unknown} data - The data to log
      */
-    sendLog(eventName, data) {
-      if (!this._logger) {
+    sendToEventLogger(eventName, data) {
+      if (!this._eventLogger) {
         return;
       }
       let message;
@@ -296,38 +291,106 @@
       }
       switch (eventName) {
         case "error": {
-          this._logger.error?.(message, { event: eventName, data });
+          this._eventLogger.error?.(message, { event: eventName, data });
           break;
         }
         case "warn": {
-          this._logger.warn?.(message, { event: eventName, data });
+          this._eventLogger.warn?.(message, { event: eventName, data });
           break;
         }
         case "trace": {
-          this._logger.trace?.(message, { event: eventName, data });
+          this._eventLogger.trace?.(message, { event: eventName, data });
           break;
         }
         case "debug": {
-          this._logger.debug?.(message, { event: eventName, data });
+          this._eventLogger.debug?.(message, { event: eventName, data });
           break;
         }
         case "fatal": {
-          this._logger.fatal?.(message, { event: eventName, data });
+          this._eventLogger.fatal?.(message, { event: eventName, data });
           break;
         }
         default: {
-          this._logger.info?.(message, { event: eventName, data });
+          this._eventLogger.info?.(message, { event: eventName, data });
           break;
         }
       }
     }
   };
 
+  // src/hooks/hook.ts
+  var Hook = class {
+    /**
+     * 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, handler, id) {
+      __publicField(this, "id");
+      __publicField(this, "event");
+      __publicField(this, "handler");
+      this.id = id;
+      this.event = event;
+      this.handler = handler;
+    }
+  };
+
+  // src/hooks/waterfall-hook.ts
+  var WaterfallHook = class {
+    /**
+     * 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, finalHandler, id) {
+      __publicField(this, "id");
+      __publicField(this, "event");
+      __publicField(this, "handler");
+      __publicField(this, "hooks");
+      __publicField(this, "_finalHandler");
+      this.id = id;
+      this.event = event;
+      this.hooks = [];
+      this._finalHandler = finalHandler;
+      this.handler = async (...arguments_) => {
+        const initialArgs = arguments_.length === 1 ? arguments_[0] : arguments_;
+        const results = [];
+        for (const hook of this.hooks) {
+          const result = await hook({ initialArgs, results: [...results] });
+          results.push({ hook, result });
+        }
+        await this._finalHandler({ initialArgs, results: [...results] });
+      };
+    }
+    /**
+     * Adds a hook function to the end of the waterfall chain
+     * @param {WaterfallHookFn} hook - The hook function to add
+     */
+    addHook(hook) {
+      this.hooks.push(hook);
+    }
+    /**
+     * 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) {
+      const index = this.hooks.indexOf(hook);
+      if (index !== -1) {
+        this.hooks.splice(index, 1);
+        return true;
+      }
+      return false;
+    }
+  };
+
   // src/index.ts
   var Hookified = class extends Eventified {
     constructor(options) {
       super({
-        logger: options?.logger,
+        eventLogger: options?.eventLogger,
         throwOnEmitError: options?.throwOnEmitError,
         throwOnEmptyListeners: options?.throwOnEmptyListeners
       });
@@ -336,12 +399,11 @@
       __publicField(this, "_enforceBeforeAfter", false);
       __publicField(this, "_deprecatedHooks");
       __publicField(this, "_allowDeprecated", true);
+      __publicField(this, "_useHookClone", true);
       this._hooks = /* @__PURE__ */ new Map();
       this._deprecatedHooks = options?.deprecatedHooks ? new Map(options.deprecatedHooks) : /* @__PURE__ */ new Map();
       if (options?.throwOnHookError !== void 0) {
         this._throwOnHookError = options.throwOnHookError;
-      } else if (options?.throwHookErrors !== void 0) {
-        this._throwOnHookError = options.throwHookErrors;
       }
       if (options?.enforceBeforeAfter !== void 0) {
         this._enforceBeforeAfter = options.enforceBeforeAfter;
@@ -349,30 +411,17 @@
       if (options?.allowDeprecated !== void 0) {
         this._allowDeprecated = options.allowDeprecated;
       }
+      if (options?.useHookClone !== void 0) {
+        this._useHookClone = options.useHookClone;
+      }
     }
     /**
      * Gets all hooks
-     * @returns {Map<string, Hook[]>}
+     * @returns {Map<string, IHook[]>}
      */
     get hooks() {
       return this._hooks;
     }
-    /**
-     * 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() {
-      return this._throwOnHookError;
-    }
-    /**
-     * 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.
-     */
-    set throwHookErrors(value) {
-      this._throwOnHookError = value;
-    }
     /**
      * Gets whether an error should be thrown when a hook throws an error. Default is false and only emits an error event.
      * @returns {boolean}
@@ -431,157 +480,153 @@
       this._allowDeprecated = value;
     }
     /**
-     * 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'
-     */
-    validateHookName(event) {
-      if (this._enforceBeforeAfter) {
-        const eventValue = event.trim().toLocaleLowerCase();
-        if (!eventValue.startsWith("before") && !eventValue.startsWith("after")) {
-          throw new Error(
-            `Hook event "${event}" must start with "before" or "after" when enforceBeforeAfter is enabled`
-          );
-        }
-      }
-    }
-    /**
-     * 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}
      */
-    checkDeprecatedHook(event) {
-      if (this._deprecatedHooks.has(event)) {
-        const message = this._deprecatedHooks.get(event);
-        const warningMessage = `Hook "${event}" is deprecated${message ? `: ${message}` : ""}`;
-        this.emit("warn", { hook: event, message: warningMessage });
-        return this._allowDeprecated;
-      }
-      return true;
+    get useHookClone() {
+      return this._useHookClone;
     }
     /**
-     * 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, handler) {
-      this.onHookEntry({ event, handler });
+    set useHookClone(value) {
+      this._useHookClone = value;
     }
     /**
-     * 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) {
-      this.validateHookName(hookEntry.event);
-      if (!this.checkDeprecatedHook(hookEntry.event)) {
-        return;
+    onHook(hook, options) {
+      this.validateHookName(hook.event);
+      if (!this.checkDeprecatedHook(hook.event)) {
+        return void 0;
       }
-      const eventHandlers = this._hooks.get(hookEntry.event);
+      const shouldClone = options?.useHookClone ?? this._useHookClone;
+      const entry = shouldClone ? { id: hook.id, event: hook.event, handler: hook.handler } : hook;
+      entry.id = entry.id ?? crypto.randomUUID();
+      const eventHandlers = this._hooks.get(hook.event);
       if (eventHandlers) {
-        eventHandlers.push(hookEntry.handler);
+        const existingIndex = eventHandlers.findIndex((h) => h.id === entry.id);
+        if (existingIndex !== -1) {
+          eventHandlers[existingIndex] = entry;
+        } else {
+          const position = options?.position ?? "Bottom";
+          if (position === "Top") {
+            eventHandlers.unshift(entry);
+          } else if (position === "Bottom") {
+            eventHandlers.push(entry);
+          } else {
+            const index = Math.max(0, Math.min(position, eventHandlers.length));
+            eventHandlers.splice(index, 0, entry);
+          }
+        }
       } else {
-        this._hooks.set(hookEntry.event, [hookEntry.handler]);
+        this._hooks.set(hook.event, [entry]);
       }
+      return entry;
     }
     /**
      * 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, handler) {
-      this.onHookEntry({ event, handler });
+      this.onHook({ event, handler });
     }
     /**
-     * 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) {
+    onHooks(hooks, options) {
       for (const hook of hooks) {
-        this.onHook(hook.event, hook.handler);
+        this.onHook(hook, options);
       }
     }
     /**
-     * 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, handler) {
-      this.validateHookName(event);
-      if (!this.checkDeprecatedHook(event)) {
-        return;
-      }
-      const eventHandlers = this._hooks.get(event);
-      if (eventHandlers) {
-        eventHandlers.unshift(handler);
-      } else {
-        this._hooks.set(event, [handler]);
-      }
+    prependHook(hook, options) {
+      return this.onHook(hook, { ...options, position: "Top" });
     }
     /**
-     * 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, handler) {
-      this.validateHookName(event);
-      if (!this.checkDeprecatedHook(event)) {
-        return;
-      }
-      const hook = async (...arguments_) => {
-        this.removeHook(event, hook);
-        return handler(...arguments_);
+    prependOnceHook(hook, options) {
+      const wrappedHandler = async (...arguments_) => {
+        this.removeHook({ event: hook.event, handler: wrappedHandler });
+        return hook.handler(...arguments_);
       };
-      this.prependHook(event, hook);
+      return this.onHook(
+        { id: hook.id, event: hook.event, handler: wrappedHandler },
+        { ...options, position: "Top" }
+      );
     }
     /**
      * 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, handler) {
-      this.validateHookName(event);
-      if (!this.checkDeprecatedHook(event)) {
+    onceHook(hook) {
+      this.validateHookName(hook.event);
+      if (!this.checkDeprecatedHook(hook.event)) {
         return;
       }
-      const hook = async (...arguments_) => {
-        this.removeHook(event, hook);
-        return handler(...arguments_);
+      const wrappedHandler = async (...arguments_) => {
+        this.removeHook({ event: hook.event, handler: wrappedHandler });
+        return hook.handler(...arguments_);
       };
-      this.onHook(event, hook);
+      this.onHook({ id: hook.id, event: hook.event, handler: wrappedHandler });
     }
     /**
      * 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, handler) {
-      this.validateHookName(event);
-      if (!this.checkDeprecatedHook(event)) {
-        return;
-      }
-      const eventHandlers = this._hooks.get(event);
+    removeHook(hook) {
+      this.validateHookName(hook.event);
+      const eventHandlers = this._hooks.get(hook.event);
       if (eventHandlers) {
-        const index = eventHandlers.indexOf(handler);
+        const index = eventHandlers.findIndex((h) => h.handler === hook.handler);
         if (index !== -1) {
           eventHandlers.splice(index, 1);
+          if (eventHandlers.length === 0) {
+            this._hooks.delete(hook.event);
+          }
+          return { event: hook.event, handler: hook.handler };
         }
       }
+      return void 0;
     }
     /**
-     * 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) {
+      const removed = [];
       for (const hook of hooks) {
-        this.removeHook(hook.event, hook.handler);
+        const result = this.removeHook(hook);
+        if (result) {
+          removed.push(result);
+        }
       }
+      return removed;
     }
     /**
      * Calls all handlers for a specific event
@@ -596,9 +641,9 @@
       }
       const eventHandlers = this._hooks.get(event);
       if (eventHandlers) {
-        for (const handler of eventHandlers) {
+        for (const hook of [...eventHandlers]) {
           try {
-            await handler(...arguments_);
+            await hook.handler(...arguments_);
           } catch (error) {
             const message = `${event}: ${error.message}`;
             this.emit("error", new Error(message));
@@ -626,12 +671,12 @@
       }
       const eventHandlers = this._hooks.get(event);
       if (eventHandlers) {
-        for (const handler of eventHandlers) {
-          if (handler.constructor.name === "AsyncFunction") {
+        for (const hook of [...eventHandlers]) {
+          if (hook.handler.constructor.name === "AsyncFunction") {
             continue;
           }
           try {
-            handler(...arguments_);
+            hook.handler(...arguments_);
           } catch (error) {
             const message = `${event}: ${error.message}`;
             this.emit("error", new Error(message));
@@ -671,15 +716,54 @@
     /**
      * Gets all hooks for a specific event
      * @param {string} event
-     * @returns {Hook[]}
+     * @returns {IHook[]}
      */
     getHooks(event) {
       this.validateHookName(event);
-      if (!this.checkDeprecatedHook(event)) {
-        return void 0;
-      }
       return this._hooks.get(event);
     }
+    /**
+     * 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) {
+      for (const eventHandlers of this._hooks.values()) {
+        const found = eventHandlers.find((h) => h.id === id);
+        if (found) {
+          return found;
+        }
+      }
+      return void 0;
+    }
+    /**
+     * 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
+     */
+    removeHookById(id) {
+      if (Array.isArray(id)) {
+        const removed = [];
+        for (const singleId of id) {
+          const result = this.removeHookById(singleId);
+          if (result && !Array.isArray(result)) {
+            removed.push(result);
+          }
+        }
+        return removed;
+      }
+      for (const [event, eventHandlers] of this._hooks.entries()) {
+        const index = eventHandlers.findIndex((h) => h.id === id);
+        if (index !== -1) {
+          const [removed] = eventHandlers.splice(index, 1);
+          if (eventHandlers.length === 0) {
+            this._hooks.delete(event);
+          }
+          return removed;
+        }
+      }
+      return void 0;
+    }
     /**
      * Removes all hooks
      * @returns {void}
@@ -687,6 +771,50 @@
     clearHooks() {
       this._hooks.clear();
     }
+    /**
+     * 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) {
+      this.validateHookName(event);
+      const eventHandlers = this._hooks.get(event);
+      if (eventHandlers) {
+        const removed = [...eventHandlers];
+        this._hooks.delete(event);
+        return removed;
+      }
+      return [];
+    }
+    /**
+     * 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'
+     */
+    validateHookName(event) {
+      if (this._enforceBeforeAfter) {
+        const eventValue = event.trim().toLocaleLowerCase();
+        if (!eventValue.startsWith("before") && !eventValue.startsWith("after")) {
+          throw new Error(
+            `Hook event "${event}" must start with "before" or "after" when enforceBeforeAfter is enabled`
+          );
+        }
+      }
+    }
+    /**
+     * 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
+     */
+    checkDeprecatedHook(event) {
+      if (this._deprecatedHooks.has(event)) {
+        const message = this._deprecatedHooks.get(event);
+        const warningMessage = `Hook "${event}" is deprecated${message ? `: ${message}` : ""}`;
+        this.emit("warn", { hook: event, message: warningMessage });
+        return this._allowDeprecated;
+      }
+      return true;
+    }
   };
 })();
 /* v8 ignore next -- @preserve */