hookified 1.15.1 → 2.0.1

package/dist/node/index.js

@@ -1,15 +1,15 @@
 // src/eventified.ts
+var ERROR_EVENT = "error";
 var Eventified = class {
   _eventListeners;
   _maxListeners;
-  _logger;
+  _eventLogger;
   _throwOnEmitError = false;
-  _throwOnEmptyListeners = false;
-  _errorEvent = "error";
+  _throwOnEmptyListeners = true;
   constructor(options) {
     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;
     }
@@ -18,18 +18,18 @@ var Eventified = class {
     }
   }
   /**
-   * 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.
@@ -80,10 +80,17 @@ var Eventified = class {
    */
   listenerCount(eventName) {
     if (eventName === void 0) {
-      return this.getAllListeners().length;
+      let count = 0;
+      for (const entry2 of this._eventListeners.values()) {
+        count += typeof entry2 === "function" ? 1 : entry2.length;
+      }
+      return count;
+    }
+    const entry = this._eventListeners.get(eventName);
+    if (entry === void 0) {
+      return 0;
     }
-    const listeners = this._eventListeners.get(eventName);
-    return listeners ? listeners.length : 0;
+    return typeof entry === "function" ? 1 : entry.length;
   }
   /**
    * Gets an array of event names
@@ -101,7 +108,11 @@ var Eventified = class {
     if (event === void 0) {
       return this.getAllListeners();
     }
-    return this._eventListeners.get(event) ?? [];
+    const entry = this._eventListeners.get(event);
+    if (entry === void 0) {
+      return [];
+    }
+    return typeof entry === "function" ? [entry] : entry;
   }
   /**
    * Prepends a listener to the beginning of the listeners array for the specified event
@@ -110,9 +121,14 @@ var Eventified = class {
    * @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);
+    const existing = this._eventListeners.get(eventName);
+    if (existing === void 0) {
+      this._eventListeners.set(eventName, listener);
+    } else if (typeof existing === "function") {
+      this._eventListeners.set(eventName, [listener, existing]);
+    } else {
+      existing.unshift(listener);
+    }
     return this;
   }
   /**
@@ -153,17 +169,26 @@ var Eventified = class {
    * @returns {IEventEmitter} returns the instance of the class for chaining
    */
   on(event, listener) {
-    if (!this._eventListeners.has(event)) {
-      this._eventListeners.set(event, []);
-    }
-    const listeners = this._eventListeners.get(event);
-    if (listeners) {
-      if (listeners.length >= this._maxListeners) {
+    const existing = this._eventListeners.get(event);
+    if (existing === void 0) {
+      this._eventListeners.set(event, listener);
+      return this;
+    }
+    if (typeof existing === "function") {
+      const arr = [existing, listener];
+      this._eventListeners.set(event, arr);
+      if (this._maxListeners > 0 && arr.length > this._maxListeners) {
         console.warn(
-          `MaxListenersExceededWarning: Possible event memory leak detected. ${listeners.length + 1} ${event} listeners added. Use setMaxListeners() to increase limit.`
+          `MaxListenersExceededWarning: Possible event memory leak detected. ${arr.length} ${event} listeners added. Use setMaxListeners() to increase limit.`
+        );
+      }
+    } else {
+      existing.push(listener);
+      if (this._maxListeners > 0 && existing.length > this._maxListeners) {
+        console.warn(
+          `MaxListenersExceededWarning: Possible event memory leak detected. ${existing.length} ${event} listeners added. Use setMaxListeners() to increase limit.`
         );
       }
-      listeners.push(listener);
     }
     return this;
   }
@@ -184,13 +209,25 @@ var Eventified = class {
    * @returns {IEventEmitter} returns the instance of the class for chaining
    */
   off(event, listener) {
-    const listeners = this._eventListeners.get(event) ?? [];
-    const index = listeners.indexOf(listener);
-    if (index !== -1) {
-      listeners.splice(index, 1);
+    const entry = this._eventListeners.get(event);
+    if (entry === void 0) {
+      return this;
     }
-    if (listeners.length === 0) {
-      this._eventListeners.delete(event);
+    if (typeof entry === "function") {
+      if (entry === listener) {
+        this._eventListeners.delete(event);
+      }
+      return this;
+    }
+    const index = entry.indexOf(listener);
+    if (index !== -1) {
+      if (entry.length === 2) {
+        this._eventListeners.set(event, entry[1 - index]);
+      } else if (entry.length === 1) {
+        this._eventListeners.delete(event);
+      } else {
+        entry.splice(index, 1);
+      }
     }
     return this;
   }
@@ -202,24 +239,40 @@ var Eventified = class {
    */
   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;
+    const entry = this._eventListeners.get(event);
+    const argumentLength = arguments_.length;
+    if (entry !== void 0) {
+      if (typeof entry === "function") {
+        if (argumentLength === 1) {
+          entry(arguments_[0]);
+        } else if (argumentLength === 2) {
+          entry(arguments_[0], arguments_[1]);
+        } else {
+          entry(...arguments_);
+        }
+      } else {
+        const snapshot = [...entry];
+        for (let i = 0; i < snapshot.length; i++) {
+          if (argumentLength === 1) {
+            snapshot[i](arguments_[0]);
+          } else if (argumentLength === 2) {
+            snapshot[i](arguments_[0], arguments_[1]);
+          } else {
+            snapshot[i](...arguments_);
+          }
+        }
       }
+      result = true;
+    }
+    if (this._eventLogger) {
+      this.sendToEventLogger(event, arguments_);
     }
-    if (event === this._errorEvent) {
+    if (event === ERROR_EVENT && !result) {
       const error = arguments_[0] instanceof Error ? arguments_[0] : new Error(`${arguments_[0]}`);
-      if (this._throwOnEmitError && !result) {
+      if (this._throwOnEmitError || this._throwOnEmptyListeners) {
         throw error;
-      } else {
-        if (this.listeners(this._errorEvent).length === 0 && this._throwOnEmptyListeners === true) {
-          throw error;
-        }
       }
     }
-    this.sendLog(event, arguments_);
     return result;
   }
   /**
@@ -228,7 +281,11 @@ var Eventified = class {
    * @returns {EventListener[]} An array of listeners
    */
   listeners(event) {
-    return this._eventListeners.get(event) ?? [];
+    const entry = this._eventListeners.get(event);
+    if (entry === void 0) {
+      return [];
+    }
+    return typeof entry === "function" ? [entry] : entry;
   }
   /**
    * Removes all listeners for a specific event. If no event is provided, it removes all listeners
@@ -249,21 +306,22 @@ var Eventified = class {
    * @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
    * @returns {EventListener[]} An array of listeners
    */
   getAllListeners() {
-    let result = [];
-    for (const listeners of this._eventListeners.values()) {
-      result = [...result, ...listeners];
+    const result = [];
+    for (const entry of this._eventListeners.values()) {
+      if (typeof entry === "function") {
+        result.push(entry);
+      } else {
+        for (let i = 0; i < entry.length; i++) {
+          result.push(entry[i]);
+        }
+      }
     }
     return result;
   }
@@ -272,8 +330,8 @@ var Eventified = class {
    * @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;
@@ -290,33 +348,101 @@ var Eventified = class {
     }
     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 {
+  id;
+  event;
+  handler;
+  /**
+   * 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) {
+    this.id = id;
+    this.event = event;
+    this.handler = handler;
+  }
+};
+
+// src/hooks/waterfall-hook.ts
+var WaterfallHook = class {
+  id;
+  event;
+  handler;
+  hooks;
+  _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, finalHandler, id) {
+    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 {
   _hooks;
@@ -324,9 +450,10 @@ var Hookified = class extends Eventified {
   _enforceBeforeAfter = false;
   _deprecatedHooks;
   _allowDeprecated = true;
+  _useHookClone = true;
   constructor(options) {
     super({
-      logger: options?.logger,
+      eventLogger: options?.eventLogger,
       throwOnEmitError: options?.throwOnEmitError,
       throwOnEmptyListeners: options?.throwOnEmptyListeners
     });
@@ -334,8 +461,6 @@ var Hookified = class extends Eventified {
     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;
@@ -343,30 +468,17 @@ var Hookified = class extends Eventified {
     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}
@@ -425,157 +537,153 @@ var Hookified = class extends Eventified {
     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
@@ -590,9 +698,9 @@ var Hookified = class extends Eventified {
     }
     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));
@@ -620,12 +728,12 @@ var Hookified = class extends Eventified {
     }
     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));
@@ -665,15 +773,54 @@ var Hookified = class extends Eventified {
   /**
    * 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}
@@ -681,9 +828,57 @@ var Hookified = class extends Eventified {
   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;
+  }
 };
 export {
   Eventified,
-  Hookified
+  Hook,
+  Hookified,
+  WaterfallHook
 };
+/* v8 ignore start -- @preserve: single-element arrays are stored as functions */
+/* v8 ignore next 3 -- @preserve: guarded by caller */
 /* v8 ignore next -- @preserve */