![Hookified](site/logo.svg) # Event Emitting and Middleware Hooks [![tests](https://github.com/jaredwray/hookified/actions/workflows/tests.yaml/badge.svg)](https://github.com/jaredwray/hookified/actions/workflows/tests.yaml) [![GitHub license](https://img.shields.io/github/license/jaredwray/hookified)](https://github.com/jaredwray/hookified/blob/master/LICENSE) [![codecov](https://codecov.io/gh/jaredwray/hookified/branch/main/graph/badge.svg?token=nKkVklTFdA)](https://codecov.io/gh/jaredwray/hookified) [![npm](https://img.shields.io/npm/dm/hookified)](https://npmjs.com/package/hookified) [![jsDelivr](https://data.jsdelivr.com/v1/package/npm/hookified/badge)](https://www.jsdelivr.com/package/npm/hookified) [![npm](https://img.shields.io/npm/v/hookified)](https://npmjs.com/package/hookified) [![Drydock review](https://img.shields.io/endpoint?url=https%3A%2F%2Fdrydock.org%2Fpublic%2Fbadge%2Fnpm%2Fhookified)](https://drydock.org/diff/hookified) # Features - Simple replacement for EventEmitter - Async / Sync Middleware Hooks for Your Methods - ESM / CJS with Types - Browser Support and Delivered via CDN - Ability to throw errors in hooks - Ability to pass in a logger (such as Pino) for errors - Enforce consistent hook naming conventions with `enforceBeforeAfter` - Deprecation warnings for hooks with `deprecatedHooks` - Control deprecated hook execution with `allowDeprecated` - WaterfallHook for sequential data transformation pipelines - ParallelHook for concurrent fan-out execution with collected results - Tag hooks and look them up across events with `getHooksByTag` and `getTaggedHooks` - Optional hook stats, off by default unless you set `enableStats` or `stats.enabled` - No package dependencies and only 250KB in size - Fast and Efficient with [Benchmarks](#benchmarks) - Maintained on a regular basis! # Table of Contents - [Installation](#installation) - [Usage](#usage) - [Migrating from v2 to v3](#migrating-from-v2-to-v3) - [Migrating from v1 to v2](#migrating-from-v1-to-v2) - [Using it in the Browser](#using-it-in-the-browser) - [Hooks](#hooks) - [Standard Hook](#standard-hook) - [Waterfall Hook](#waterfall-hook) - [Parallel Hook](#parallel-hook) - [API - Hooks](#api---hooks) - [.allowDeprecated](#allowdeprecated) - [.deprecatedHooks](#deprecatedhooks) - [.enforceBeforeAfter](#enforcebeforeafter) - [.eventLogger](#eventlogger) - [.hooks](#hooks-1) - [.throwOnHookError](#throwOnHookError) - [.stats](#stats) - [.stats.resetStats()](#statsresetstats) - [.stats.topCalls()](#statstopcalls) - [.stats.longestCalls()](#statslongestcalls) - [.useHookClone](#usehookclone) - [.addHook(event, handler)](#addhookevent-handler) - [.afterHook(eventName, ...args)](#afterhookeventname-args) - [.beforeHook(eventName, ...args)](#beforehookeventname-args) - [.callHook(eventName, ...args)](#callhookeventname-args) - [.clearHooks()](#clearhooks) - [.getHook(id)](#gethookid) - [.getHooks(eventName)](#gethookseventname) - [.getHooksByTag(tag)](#gethooksbytagtag) - [.getTaggedHooks()](#gettaggedhooks) - [.hook(eventName, ...args)](#hookeventname-args) - [.hookSync(eventName, ...args)](#hooksync-eventname-args) - [.onHook(hook, options?)](#onhookhook-options) - [.onHooks(Array, options?)](#onhooksarray-options) - [.onceHook(hook)](#oncehookhook) - [.prependHook(hook, options?)](#prependhookhook-options) - [.prependOnceHook(hook, options?)](#prependoncehookhook-options) - [.removeEventHooks(eventName)](#removeeventhookseventname) - [.removeHook(hook)](#removehookhook) - [.removeHookById(id)](#removehookbyidid) - [.removeHooks(Array)](#removehooksarray) - [API - Events](#api---events) - [.throwOnEmitError](#throwonemitterror) - [.throwOnEmptyListeners](#throwonemptylisteners) - [.on(eventName, handler)](#oneventname-handler) - [.off(eventName, handler)](#offeventname-handler) - [.emit(eventName, ...args)](#emiteventname-args) - [.listeners(eventName)](#listenerseventname) - [.removeAllListeners(eventName)](#removealllistenerseventname) - [.setMaxListeners(maxListeners: number)](#setmaxlistenersmaxlisteners-number) - [.once(eventName, handler)](#oneventname-handler-1) - [.prependListener(eventName, handler)](#prependlistenereventname-handler) - [.prependOnceListener(eventName, handler)](#prependoncelistenereventname-handler) - [.eventNames()](#eventnames) - [.listenerCount(eventName?)](#listenercounteventname) - [.rawListeners(eventName?)](#rawlistenerseventname) - [Logging](#logging) - [Hook Stats](#hook-stats) - [Benchmarks](#benchmarks) - [How to Contribute](#how-to-contribute) - [License and Copyright](#license-and-copyright) # Installation ```bash npm install hookified --save ``` # Usage This was built because we constantly wanted hooks and events extended on libraires we are building such as [Keyv](https://keyv.org) and [Cacheable](https://cacheable.org). This is a simple way to add hooks and events to your classes. ```javascript import { Hookified } from 'hookified'; class MyClass extends Hookified { constructor() { super(); } async myMethodEmittingEvent() { this.emit('message', 'Hello World'); } //with hooks you can pass data in and if they are subscribed via onHook they can modify the data async myMethodWithHooks(): Promise { let data = { some: 'data' }; // do something await this.hook('before:myMethod2', data); return data; } } ``` You can even pass in multiple arguments to the hooks: ```javascript import { Hookified } from 'hookified'; class MyClass extends Hookified { constructor() { super(); } async myMethodWithHooks(): Promise { let data = { some: 'data' }; let data2 = { some: 'data2' }; // do something await this.hook('before:myMethod2', data, data2); return data; } } ``` # Using it in the Browser ```html ``` if you are not using ESM modules, you can use the following: ```html ``` # Hooks ## Standard Hook The `Hook` class provides a convenient way to create hook entries. It implements the `IHook` interface. The `IHook` interface has the following properties: | Property | Type | Required | Description | |----------|------|----------|-------------| | `id` | `string` | No | Unique identifier for the hook. Auto-generated via `crypto.randomUUID()` if not provided. | | `event` | `string` | Yes | The event name for the hook. | | `handler` | `HookFn` | Yes | The handler function for the hook. | | `tags` | `string[]` | No | Tags for grouping and looking up hooks across events. | When a hook is registered, it is assigned an `id` (auto-generated if not provided). The `id` can be used to look up or remove hooks via `getHook` and `removeHookById`. If you register a hook with the same `id` on the same event, it will replace the existing hook in-place (preserving its position). Hooks can also carry `tags`, an optional array of strings used to group and look them up across events. When a hook is registered, tags are validated, copied, and de-duplicated while keeping the first-seen order. Matching is exact and case-sensitive: `"audit"`, `"Audit"`, and `" audit"` are three different tags. An empty string, a non-string, or a non-array throws a `TypeError` and the hook is not registered. Changing the array you passed in after registering has no effect, because the stored tags are a copy. Tags are not trimmed or lowercased. With `useHookClone: false`, the `tags` property on your hook object is replaced with that normalized copy, the same way `id` is assigned onto it. **Using the `Hook` class:** ```javascript import { Hook, Hookified } from 'hookified'; class MyClass extends Hookified { constructor() { super(); } } const myClass = new MyClass(); // Without id (auto-generated) const hook = new Hook('before:save', async (data) => { data.validated = true; }); // With id const hook2 = new Hook('after:save', async (data) => { console.log('saved'); }, 'my-after-save-hook'); // With id and tags const hook3 = new Hook('before:save', async (data) => { data.audited = true; }, 'audit-hook', ['audit']); // Register with onHook myClass.onHook(hook); // Or register multiple hooks with onHooks const hooks = [ new Hook('before:save', async (data) => { data.validated = true; }), new Hook('after:save', async (data) => { console.log('saved'); }), ]; myClass.onHooks(hooks); // Remove hooks myClass.removeHooks(hooks); ``` **Using plain TypeScript with the `IHook` interface:** ```typescript import { Hookified, type IHook } from 'hookified'; class MyClass extends Hookified { constructor() { super(); } } const myClass = new MyClass(); const hook: IHook = { id: 'my-validation-hook', // optional — auto-generated if omitted event: 'before:save', tags: ['validation', 'audit'], handler: async (data) => { data.validated = true; }, }; const stored = myClass.onHook(hook); console.log(stored?.id); // 'my-validation-hook' console.log(myClass.getHooksByTag('audit').map((entry) => entry.id)); // ['my-validation-hook'] // Later, remove by id myClass.removeHookById('my-validation-hook'); ``` ## Waterfall Hook The `WaterfallHook` class chains multiple hook functions sequentially in a waterfall pipeline. Each hook receives a context containing the original arguments and the accumulated results from all previous hooks. It implements the `IHook` interface, so it integrates directly with `Hookified.onHook()`. The constructor is `new WaterfallHook(event, finalHandler, id?, tags?)`. `id` and `tags` behave as they do on `IHook`. The `WaterfallHookContext` has the following properties: | Property | Type | Description | |----------|------|-------------| | `initialArgs` | `any` | The original arguments passed to the waterfall execution. | | `results` | `WaterfallHookResult[]` | Array of `{ hook, result }` entries from previous hooks. Empty for the first hook. | **Basic usage:** ```javascript import { WaterfallHook } from 'hookified'; const wh = new WaterfallHook('process', ({ results, initialArgs }) => { // Final handler receives all accumulated results const lastResult = results[results.length - 1].result; console.log('Final:', lastResult); }); // Add transformation hooks to the pipeline wh.addHook(({ initialArgs }) => { return initialArgs + 1; // 5 -> 6 }); wh.addHook(({ results }) => { return results[results.length - 1].result * 2; // 6 -> 12 }); // Execute the waterfall by calling handler directly await wh.handler(5); // Final: 12 ``` **Integrating with Hookified via `onHook()`:** ```javascript import { Hookified, WaterfallHook } from 'hookified'; class MyClass extends Hookified { constructor() { super(); } } const myClass = new MyClass(); const wh = new WaterfallHook('save', ({ results }) => { const data = results[results.length - 1].result; console.log('Saved:', data); }); wh.addHook(({ initialArgs }) => { return { ...initialArgs, validated: true }; }); wh.addHook(({ results }) => { return { ...results[results.length - 1].result, timestamp: Date.now() }; }); // Register with Hookified — works because WaterfallHook implements IHook myClass.onHook(wh); // When hook() fires, the full waterfall pipeline executes await myClass.hook('save', { name: 'test' }); // Saved: { name: 'test', validated: true, timestamp: ... } ``` **Managing hooks:** ```javascript const wh = new WaterfallHook('process', ({ results }) => results); const myHook = ({ initialArgs }) => initialArgs + 1; wh.addHook(myHook); // Remove a hook by reference wh.removeHook(myHook); // returns true // Access the hooks array console.log(wh.hooks.length); // 0 ``` A run uses the hooks that were in the chain at the start of the run. If you call `addHook()` or `removeHook()` during a run, the change applies to the next run. ## Parallel Hook The `ParallelHook` class fans a single invocation out to many registered hook functions concurrently via `Promise.allSettled`, then calls a final handler with the aggregated outcomes — including failures. Unlike `WaterfallHook`, hooks do not see each other's results: every hook receives the same `initialArgs` and runs in parallel. It implements the `IHook` interface, so it integrates directly with `Hookified.onHook()`, and the final handler still fires whether the hook is invoked directly or through `Hookified.hook()`. The constructor is `new ParallelHook(event, finalHandler, id?, tags?)`. `id` and `tags` behave as they do on `IHook`. Per-hook functions receive a `ParallelHookContext`: | Property | Type | Description | |----------|------|-------------| | `initialArgs` | `any` | The original arguments passed to `handler()`. Single argument stays as-is; multiple arguments become an array. | The final handler receives a `ParallelHookFinalContext`: | Property | Type | Description | |----------|------|-------------| | `initialArgs` | `any` | Same value passed to every hook. | | `results` | `Map` | One entry per registered hook, keyed by the hook function reference for direct lookup. Iteration order matches registration order. | Each `ParallelHookResult` value is a discriminated union — failures are reported, not thrown: | Field | Type | Description | |-------|------|-------------| | `status` | `"fulfilled" \| "rejected"` | Discriminator. | | `result` | `TResult` | Present when `status === "fulfilled"`. The value the hook returned. Defaults to `any`; tighten via the `ParallelHook` generic. | | `reason` | `unknown` | Present when `status === "rejected"`. The error or value the hook threw. Stays `unknown` regardless of the result generic, since errors in JS aren't typed. | **Basic usage with `Hookified`:** ```javascript import { Hookified, ParallelHook } from 'hookified'; class MyClass extends Hookified { constructor() { super(); } } const myClass = new MyClass(); const sendEmailHook = async ({ initialArgs }) => sendEmail(initialArgs); const sendSlackHook = async ({ initialArgs }) => sendSlack(initialArgs); const sendWebhookHook = async ({ initialArgs }) => sendWebhook(initialArgs); const ph = new ParallelHook('notify', ({ results }) => { // Look up a specific hook's outcome by reference const emailOutcome = results.get(sendEmailHook); if (emailOutcome?.status === 'rejected') { console.error('email failed:', emailOutcome.reason); } // Or iterate every result in registration order for (const [hook, r] of results) { if (r.status === 'fulfilled') { console.log('ok:', r.result); } else { console.error('failed:', r.reason); } } }); ph.addHook(sendEmailHook); ph.addHook(sendSlackHook); ph.addHook(sendWebhookHook); // Register with Hookified — works because ParallelHook implements IHook myClass.onHook(ph); // All three notification hooks fire concurrently, then the final handler runs await myClass.hook('notify', { user: 'alice', message: 'hi' }); ``` **Tightening the result type:** When every hook returns the same shape, pass generics so `result` is fully typed instead of `any`: ```typescript import { ParallelHook } from 'hookified'; type NotifyArgs = { user: string; message: string }; type NotifyResult = { channel: string; messageId: string }; const ph = new ParallelHook('notify', ({ results }) => { for (const [, r] of results) { if (r.status === 'fulfilled') { console.log(`${r.result.channel}: ${r.result.messageId}`); } else { console.error(r.reason); // still `unknown` — errors aren't typed } } }); ph.addHook(async ({ initialArgs }) => ({ channel: 'email', messageId: '1' })); ``` **Managing hooks:** ```javascript const ph = new ParallelHook('process', ({ results }) => { console.log(results.size); // number of hooks that ran }); const myHook = ({ initialArgs }) => initialArgs + 1; ph.addHook(myHook); // Remove a hook by reference ph.removeHook(myHook); // returns true // Access the hooks array console.log(ph.hooks.length); // 0 ``` # API - Hooks > All examples below assume the following setup unless otherwise noted: > ```javascript > import { Hookified } from 'hookified'; > class MyClass extends Hookified { > constructor(options) { super(options); } > } > const myClass = new MyClass(); > ``` ## .allowDeprecated Controls whether deprecated hooks are allowed to be registered and executed. Default is true. When set to false, deprecated hooks will still emit warnings but will be prevented from registration and execution. ```javascript import { Hookified } from 'hookified'; const deprecatedHooks = new Map([ ['oldHook', 'Use newHook instead'] ]); class MyClass extends Hookified { constructor() { super({ deprecatedHooks, allowDeprecated: false }); } } const myClass = new MyClass(); console.log(myClass.allowDeprecated); // false // Listen for deprecation warnings (still emitted even when blocked) myClass.on('warn', (event) => { console.log(`Warning: ${event.message}`); }); // Try to register a deprecated hook - will emit warning but not register myClass.onHook({ event: 'oldHook', handler: () => { console.log('This will never execute'); }}); // Output: Warning: Hook "oldHook" is deprecated: Use newHook instead // Verify hook was not registered console.log(myClass.getHooks('oldHook')); // undefined // Try to execute a deprecated hook - will emit warning but not execute await myClass.hook('oldHook'); // Output: Warning: Hook "oldHook" is deprecated: Use newHook instead // (but no handlers execute) // Non-deprecated hooks work normally myClass.onHook({ event: 'validHook', handler: () => { console.log('This works fine'); }}); console.log(myClass.getHooks('validHook')); // [handler function] // You can dynamically change the setting myClass.allowDeprecated = true; // Now deprecated hooks can be registered and executed myClass.onHook({ event: 'oldHook', handler: () => { console.log('Now this works'); }}); console.log(myClass.getHooks('oldHook')); // [handler function] ``` **Behavior when `allowDeprecated` is false:** - **Registration**: All hook registration methods (`onHook`, `addHook`, `prependHook`, etc.) will emit warnings but skip registration - **Execution**: Hook execution methods (`hook`, `callHook`) will emit warnings but skip execution - **Removal/Reading**: `removeHook`, `removeHooks`, and `getHooks` always work regardless of deprecation status - **Warnings**: Deprecation warnings are always emitted regardless of `allowDeprecated` setting **Use cases:** - **Development**: Keep `allowDeprecated: true` to maintain functionality while seeing warnings - **Testing**: Set `allowDeprecated: false` to ensure no deprecated hooks are accidentally used - **Migration**: Gradually disable deprecated hooks during API transitions - **Production**: Disable deprecated hooks to prevent legacy code execution ## .deprecatedHooks A Map of deprecated hook names to deprecation messages. When a deprecated hook is used, a warning will be emitted via the 'warn' event and logged to the logger (if available). Default is an empty Map. ```javascript import { Hookified } from 'hookified'; // Define deprecated hooks with custom messages const deprecatedHooks = new Map([ ['oldHook', 'Use newHook instead'], ['legacyMethod', 'This hook will be removed in v2.0'], ['deprecatedFeature', ''] // Empty message - will just say "deprecated" ]); class MyClass extends Hookified { constructor() { super({ deprecatedHooks }); } } const myClass = new MyClass(); console.log(myClass.deprecatedHooks); // Map with deprecated hooks // Listen for deprecation warnings myClass.on('warn', (event) => { console.log(`Deprecation warning: ${event.message}`); // event.hook contains the hook name // event.message contains the full warning message }); // Using a deprecated hook will emit warnings myClass.onHook({ event: 'oldHook', handler: () => { console.log('This hook is deprecated'); }}); // Output: Hook "oldHook" is deprecated: Use newHook instead // Using a deprecated hook with empty message myClass.onHook({ event: 'deprecatedFeature', handler: () => { console.log('This hook is deprecated'); }}); // Output: Hook "deprecatedFeature" is deprecated // You can also set deprecated hooks dynamically myClass.deprecatedHooks.set('anotherOldHook', 'Please migrate to the new API'); // Works with logger if provided import pino from 'pino'; const logger = pino(); const myClassWithLogger = new Hookified({ deprecatedHooks, eventLogger: logger }); // Deprecation warnings will be logged to logger.warn ``` The deprecation warning system applies to the following hook-related methods: - Registration: `onHook()`, `addHook()`, `onHooks()`, `prependHook()`, `onceHook()`, `prependOnceHook()` - Execution: `hook()`, `callHook()` Note: `getHooks()`, `removeHook()`, and `removeHooks()` do not check for deprecated hooks and always operate normally. Deprecation warnings are emitted in two ways: 1. **Event**: A 'warn' event is emitted with `{ hook: string, message: string }` 2. **Logger**: Logged to `eventLogger.warn()` if an `eventLogger` is configured and has a `warn` method ## .enforceBeforeAfter If set to true, enforces that all hook names must start with 'before' or 'after'. This is useful for maintaining consistent hook naming conventions in your application. Default is false. ```javascript import { Hookified } from 'hookified'; class MyClass extends Hookified { constructor() { super({ enforceBeforeAfter: true }); } } const myClass = new MyClass(); console.log(myClass.enforceBeforeAfter); // true // These will work fine myClass.onHook({ event: 'beforeSave', handler: async () => { console.log('Before save hook'); }}); myClass.onHook({ event: 'afterSave', handler: async () => { console.log('After save hook'); }}); myClass.onHook({ event: 'before:validation', handler: async () => { console.log('Before validation hook'); }}); // This will throw an error try { myClass.onHook({ event: 'customEvent', handler: async () => { console.log('This will not work'); }}); } catch (error) { console.log(error.message); // Hook event "customEvent" must start with "before" or "after" when enforceBeforeAfter is enabled } // You can also change it dynamically myClass.enforceBeforeAfter = false; myClass.onHook({ event: 'customEvent', handler: async () => { console.log('This will work now'); }}); ``` The validation applies to all hook-related methods: - `onHook()`, `addHook()`, `onHooks()` - `prependHook()`, `onceHook()`, `prependOnceHook()` - `hook()`, `callHook()` - `getHooks()`, `removeHook()`, `removeHooks()` Note: The `beforeHook()` and `afterHook()` helper methods automatically generate proper hook names and work regardless of the `enforceBeforeAfter` setting. ## .eventLogger If set, errors thrown in hooks will be logged to the logger. If not set, errors will be only emitted. ```javascript import pino from 'pino'; const myClass = new MyClass({ eventLogger: pino() }); myClass.onHook({ event: 'before:myMethod2', handler: async () => { throw new Error('error'); }}); // when you call before:myMethod2 it will log the error to the logger await myClass.hook('before:myMethod2'); ``` ## .hooks Get all hooks. Returns a `Map` where each key is an event name and the value is an array of `IHook` objects. ```javascript myClass.onHook({ event: 'before:myMethod2', handler: async (data) => { data.some = 'new data'; }}); console.log(myClass.hooks); // Map { 'before:myMethod2' => [{ event: 'before:myMethod2', handler: [Function] }] } ``` ## .throwOnHookError If set to true, errors thrown in hooks will be thrown. If set to false, errors will be only emitted. ```javascript const myClass = new MyClass({ throwOnHookError: true }); console.log(myClass.throwOnHookError); // true try { myClass.onHook({ event: 'error-event', handler: async () => { throw new Error('error'); }}); await myClass.hook('error-event'); } catch (error) { console.log(error.message); // error } myClass.throwOnHookError = false; console.log(myClass.throwOnHookError); // false ``` ## .stats This getter returns the `HookStats` collector for this instance. Stats collection is off by default. To start collection, pass `enableStats: true` to the constructor, or set `stats.enabled = true`. Set `stats.enabled = false` to pause collection and keep the current data. Set `stats.enabled = true` again to resume the same collector. The collector exposes these properties: - `.enabled` (`boolean`): Reads or sets the collection state. - `.calls` (`number`): Total dispatches across all tracked events and overflow. - `.errors` (`number`): Total hook errors, plus late rejections from `.hookSync()`. - `.skipped` (`number`): Total async handlers that `.hookSync()` skips. - `.blocked` (`number`): Total dispatches that deprecation rules block. - `.pending` (`number`): Count of active dispatches that do not have a duration sample yet. - `.duration` (`HookDurationStats`): Duration stats (`count`, `sum`, `min`, `max`, `last`, `mean`) for all dispatches in milliseconds. - `.events` (`HookEventStats[]`): Per-event stats in insertion order, with live per-hook rows in execution order. - `.overflow` (`HookStatsTotals | undefined`): Totals for events after the first 1000 distinct names, or `undefined` before that cap. - `.registration` (`HookRegistrationStats`): Counts for `registered`, `replaced`, `removed`, and `removeMisses`. - `.toJSON()` (`HookStatsJSON`): Returns a plain JSON snapshot. `JSON.stringify(myClass.stats)` uses this method. ```javascript const myClass = new MyClass({ enableStats: true }); myClass.onHook({ id: 'validate', event: 'before:save', handler: async (data) => { data.validated = true; }, }); await myClass.hook('before:save', {}); console.log(myClass.stats.calls); // 1 console.log(myClass.stats.errors); // 0 console.log(myClass.stats.duration); // { count: 1, sum: ..., min: ..., max: ..., last: ..., mean: ... } console.log(myClass.stats.registration); // { registered: 1, replaced: 0, removed: 0, removeMisses: 0 } // Pause collection and keep current data myClass.stats.enabled = false; await myClass.hook('before:save', {}); console.log(myClass.stats.calls); // 1 // Resume collection on the same collector myClass.stats.enabled = true; await myClass.hook('before:save', {}); console.log(myClass.stats.calls); // 2 ``` ### .stats.resetStats() This method clears all event, handler, duration, overflow, and registration stats. It leaves `stats.enabled` unchanged. ```javascript myClass.stats.resetStats(); console.log(myClass.stats.calls); // 0 console.log(myClass.stats.events); // [] ``` ### .stats.topCalls() This method returns up to 20 live hooks. The list sorts by `calls` from high to low, then by `event` and `id` from A to Z. A hook without an `id` sorts before a hook with an `id`. ```javascript const busiest = myClass.stats.topCalls(); console.log(busiest); // [{ event: 'before:save', id: 'validate', calls: 2, errors: 0, skipped: 0, duration: ... }] ``` ### .stats.longestCalls() This method returns up to 20 live hooks. The list sorts by `duration.max` from high to low, then by `event` and `id` from A to Z. This method excludes hooks with `duration.count === 0`. ```javascript const slowest = myClass.stats.longestCalls(); console.log(slowest); // [{ event: 'before:save', id: 'validate', calls: 2, errors: 0, skipped: 0, duration: ... }] ``` ## .useHookClone Controls whether hook objects are cloned before storing internally. Default is `true`. When `true`, a shallow copy of the `IHook` object is stored, preventing external mutation from affecting registered hooks. When `false`, the original reference is stored directly. ```javascript const myClass = new MyClass({ useHookClone: false }); const hook = { event: 'before:save', handler: async (data) => {} }; myClass.onHook(hook); // With useHookClone: false, the stored hook is the same reference const storedHooks = myClass.getHooks('before:save'); console.log(storedHooks[0] === hook); // true // You can dynamically change the setting myClass.useHookClone = true; ``` ## .addHook(event, handler) This is an alias for `.onHook()` that takes an event name and handler function directly. ```javascript myClass.addHook('before:myMethod2', async (data) => { data.some = 'new data'; }); ``` ## .afterHook(eventName, ...args) This is a helper function that will prepend a hook name with `after:`. ```javascript // Inside your class method — the event name will be `after:myMethod2` await this.afterHook('myMethod2', data); ``` ## .beforeHook(eventName, ...args) This is a helper function that will prepend a hook name with `before:`. ```javascript // Inside your class method — the event name will be `before:myMethod2` await this.beforeHook('myMethod2', data); ``` ## .callHook(eventName, ...args) This is an alias for `.hook(eventName, ...args)` for backwards compatibility. ## .clearHooks() Clear all hooks across all events. ```javascript myClass.onHook({ event: 'before:myMethod2', handler: async (data) => { data.some = 'new data'; }}); myClass.clearHooks(); ``` ## .getHook(id) Get a specific hook by `id`, searching across all events. Returns the `IHook` if found, or `undefined`. ```javascript const myClass = new MyClass(); myClass.onHook({ id: 'my-hook', event: 'before:save', handler: async (data) => { data.validated = true; }, }); const hook = myClass.getHook('my-hook'); console.log(hook?.id); // 'my-hook' console.log(hook?.event); // 'before:save' console.log(hook?.handler); // [Function] ``` ## .getHooks(eventName) Get all hooks for an event. Returns an `IHook[]` array, or `undefined` if no hooks are registered for the event. ```javascript myClass.onHook({ event: 'before:myMethod2', handler: async (data) => { data.some = 'new data'; }}); console.log(myClass.getHooks('before:myMethod2')); // [{ event: 'before:myMethod2', handler: [Function] }] ``` ## .getHooksByTag(tag) Get every hook that has a tag, searching across all events. Pass one tag or an array of tags. An array matches hooks that have any of those tags, and each hook is returned once even if it matches more than one. Results follow storage order: events in insertion order, then hooks in execution order within each event. The query order does not change the result order. Matching is exact and case-sensitive. Returns a new `IHook[]` array, or `[]` when nothing matches. ```javascript myClass.onHook({ id: 'validate', event: 'before:save', tags: ['validation', 'audit'], handler: async (data) => { data.validated = true; }, }); myClass.onHook({ id: 'log', event: 'after:save', tags: ['audit'], handler: async () => {}, }); myClass.onHook({ id: 'notify', event: 'after:save', handler: async () => {}, }); console.log(myClass.getHooksByTag('audit').map((hook) => hook.id)); // ['validate', 'log'] console.log(myClass.getHooksByTag(['validation', 'audit']).map((hook) => hook.id)); // ['validate', 'log'] console.log(myClass.getHooksByTag('missing')); // [] ``` ## .getTaggedHooks() Get a `Map` of every tag to the hooks that have that tag. A hook with several tags appears under each of them. Hooks without tags are left out. Keys are in order of first appearance, and each array is in storage order. Every call returns a new `Map`. ```javascript const tagged = myClass.getTaggedHooks(); console.log([...tagged.keys()]); // ['validation', 'audit'] console.log(tagged.get('audit').map((hook) => hook.id)); // ['validate', 'log'] ``` ## .hook(eventName, ...args) Run a hook event. ```javascript // Inside your class method await this.hook('before:myMethod2', data); ``` You can pass multiple arguments to the hook: ```javascript // Inside your class method await this.hook('before:myMethod2', data, data2); // The handler receives all arguments myClass.onHook({ event: 'before:myMethod2', handler: async (data, data2) => { data.some = 'new data'; data2.some = 'new data2'; }}); ``` ## .hookSync(eventName, ...args) Run a hook event synchronously. Async handlers (functions declared with `async` keyword) are silently skipped and only synchronous handlers are executed. > **Note:** The `.hook()` method is preferred as it executes both sync and async functions. Use `.hookSync()` only when you specifically need synchronous execution. ```javascript // This sync handler will execute myClass.onHook({ event: 'before:myMethod', handler: (data) => { data.some = 'modified'; }}); // This async handler will be silently skipped myClass.onHook({ event: 'before:myMethod', handler: async (data) => { data.some = 'will not run'; }}); // Inside your class method this.hookSync('before:myMethod', data); // Only sync handler runs ``` A handler that is not declared with the `async` keyword can return a promise. `.hookSync()` does not wait for that promise. If the promise rejects, `.hookSync()` emits the `error` event with the hook name and the message of the rejection. The `throwOnHookError` option does not apply to that rejection, because `.hookSync()` returned before the rejection. Add an `error` listener or set an `eventLogger` to get the error. If there is no `error` listener and no `eventLogger`, Hookified does not report the rejection. ## .onHook(hook, options?) / .onHook(event, handler) Subscribe to a hook event. Supports two calling styles: - **Object form**: `onHook(hook, options?)` — takes an `IHook` object and an optional `OnHookOptions` object. - **Shorthand form**: `onHook(event, handler)` — takes an event name string and a handler function (v1-compatible). Returns the stored `IHook` (with `id` assigned), or `undefined` if the hook was blocked by deprecation. The returned reference is the exact object stored internally, which is useful for later removal with `.removeHook()` or `.removeHookById()`. To register multiple hooks at once, use `.onHooks()`. If the hook has an `id`, it will be used as-is. If not, a UUID is auto-generated via `crypto.randomUUID()`. If a hook with the same `id` already exists on the same event, it will be **replaced in-place** (preserving its position in the array). If the hook includes `tags`, they are validated, copied, and de-duplicated before the hook is stored. Invalid tags throw a `TypeError` and nothing is registered. Replacing a hook by `id` replaces its tags rather than merging them; registering the same `id` again without tags clears them. **Options (`OnHookOptions`)**: - `useHookClone` (boolean, optional) — Per-call override for the instance-level `useHookClone` setting. When `true`, the hook object is cloned before storing. When `false`, the original reference is stored directly. When omitted, falls back to the instance-level setting. - `position` (`"Top"` | `"Bottom"` | `number`, optional) — Controls where the hook is inserted in the handlers array. `"Top"` inserts at the beginning, `"Bottom"` appends to the end (default). A number inserts at that index, clamped to the array bounds. ```javascript // Single hook — returns the stored IHook with id const stored = myClass.onHook({ event: 'before:myMethod2', handler: async (data) => { data.some = 'new data'; }, }); console.log(stored.id); // auto-generated UUID // With a custom id const stored2 = myClass.onHook({ id: 'my-validation', event: 'before:save', handler: async (data) => { data.validated = true; }, }); // With tags — duplicates are removed, order of first occurrence is kept myClass.onHook({ id: 'audit-save', event: 'before:save', tags: ['audit', 'audit', 'validation'], handler: async (data) => { data.audited = true; }, }); // stored tags are ['audit', 'validation'] // Replace hook by registering with the same id myClass.onHook({ id: 'my-validation', event: 'before:save', handler: async (data) => { data.validated = true; data.extra = true; }, }); // Only one hook with id 'my-validation' exists, at the same position // Remove by id myClass.removeHookById('my-validation'); // Use the returned reference to remove the hook later myClass.removeHook(stored); // Override useHookClone per-call — store original reference even though instance default is true const hook = { event: 'before:save', handler: async (data) => {} }; myClass.onHook(hook, { useHookClone: false }); console.log(myClass.getHooks('before:save')[0] === hook); // true // Insert at the top of the handlers array myClass.onHook({ event: 'before:save', handler: async (data) => {} }, { position: 'Top' }); // Insert at a specific index myClass.onHook({ event: 'before:save', handler: async (data) => {} }, { position: 1 }); // Shorthand form — pass event name and handler directly (v1-compatible) myClass.onHook('before:save', async (data) => { data.validated = true; }); ``` ## .onHooks(Array, options?) Subscribe to multiple hook events at once. Takes an array of `IHook` objects and an optional `OnHookOptions` object that is applied to each hook. ```javascript const hooks = [ { event: 'before:myMethodWithHooks', handler: async (data) => { data.some = 'new data1'; }, }, { event: 'after:myMethodWithHooks', handler: async (data) => { data.some = 'new data2'; }, }, ]; myClass.onHooks(hooks); // With options — insert all hooks at the top myClass.onHooks(hooks, { position: 'Top' }); // With options — skip cloning for all hooks in this batch myClass.onHooks(hooks, { useHookClone: false }); ``` ## .onceHook(hook) Subscribe to a hook event once. Takes an `IHook` object with `event` and `handler` properties. After the handler is called once, it is automatically removed. ```javascript myClass.onceHook({ event: 'before:myMethod2', handler: async (data) => { data.some = 'new data'; }}); await myClass.hook('before:myMethod2', data); // handler runs once then is removed console.log(myClass.hooks.size); // 0 ``` ## .prependHook(hook, options?) Subscribe to a hook event before all other hooks. Takes an `IHook` object with `event` and `handler` properties. Returns the stored `IHook` (with generated `id`), or `undefined` if blocked by deprecation. Equivalent to calling `onHook(hook, { position: "Top" })`. An optional `PrependHookOptions` object can be passed with: - `useHookClone` (boolean) — per-call override for hook cloning behavior ```javascript myClass.onHook({ event: 'before:myMethod2', handler: async (data) => { data.some = 'new data'; }}); myClass.prependHook({ event: 'before:myMethod2', handler: async (data) => { data.some = 'will run before new data'; }}); ``` ## .prependOnceHook(hook, options?) Subscribe to a hook event before all other hooks. Takes an `IHook` object with `event` and `handler` properties. After the handler is called once, it is automatically removed. Returns the stored `IHook` (with generated `id`), or `undefined` if blocked by deprecation. An optional `PrependHookOptions` object can be passed with: - `useHookClone` (boolean) — per-call override for hook cloning behavior ```javascript myClass.onHook({ event: 'before:myMethod2', handler: async (data) => { data.some = 'new data'; }}); myClass.prependOnceHook({ event: 'before:myMethod2', handler: async (data) => { data.some = 'will run before new data'; }}); ``` ## .removeEventHooks(eventName) Removes all hooks for a specific event and returns the removed hooks as an `IHook[]` array. Returns an empty array if no hooks are registered for the event. ```javascript myClass.onHook({ event: 'before:myMethod2', handler: async (data) => { data.some = 'new data'; }}); myClass.onHook({ event: 'before:myMethod2', handler: async (data) => { data.some = 'more data'; }}); // Remove all hooks for a specific event const removed = myClass.removeEventHooks('before:myMethod2'); console.log(removed.length); // 2 ``` ## .removeHook(hook) Unsubscribe a handler from a hook event. Takes an `IHook` object with `event` and `handler` properties. Returns the removed hook as an `IHook` object, or `undefined` if the handler was not found. ```javascript const handler = async (data) => { data.some = 'new data'; }; myClass.onHook({ event: 'before:myMethod2', handler }); const removed = myClass.removeHook({ event: 'before:myMethod2', handler }); console.log(removed); // { event: 'before:myMethod2', handler: [Function] } ``` ## .removeHookById(id) Remove one or more hooks by `id`, searching across all events. Accepts a single `string` or an array of `string` ids. - **Single id**: Returns the removed `IHook`, or `undefined` if not found. - **Array of ids**: Returns an `IHook[]` array of the hooks that were successfully removed. When the last hook for an event is removed, the event key is cleaned up. ```javascript const myClass = new MyClass(); myClass.onHook({ id: 'hook-a', event: 'before:save', handler: async () => {} }); myClass.onHook({ id: 'hook-b', event: 'after:save', handler: async () => {} }); myClass.onHook({ id: 'hook-c', event: 'before:save', handler: async () => {} }); // Remove a single hook by id const removed = myClass.removeHookById('hook-a'); console.log(removed?.id); // 'hook-a' // Remove multiple hooks by ids const removedMany = myClass.removeHookById(['hook-b', 'hook-c']); console.log(removedMany.length); // 2 ``` ## .removeHooks(Array) Unsubscribe from multiple hooks. Returns an array of the hooks that were successfully removed. ```javascript const hooks = [ { event: 'before:save', handler: async (data) => { data.some = 'new data1'; } }, { event: 'after:save', handler: async (data) => { data.some = 'new data2'; } }, ]; myClass.onHooks(hooks); const removed = myClass.removeHooks(hooks); console.log(removed.length); // 2 ``` # API - Events > All examples below assume the following setup unless otherwise noted: > ```javascript > import { Hookified } from 'hookified'; > class MyClass extends Hookified { > constructor(options) { super(options); } > } > const myClass = new MyClass(); > ``` ## .throwOnEmitError If set to true, errors emitted as `error` will always be thrown, even if there are listeners. If set to false (default), errors will only be emitted to listeners. ```javascript const myClass = new MyClass({ throwOnEmitError: true }); myClass.on('error', (err) => { console.log('listener received:', err.message); }); try { myClass.emit('error', new Error('This will throw despite having a listener')); } catch (error) { console.log(error.message); // This will throw despite having a listener } ``` ## .throwOnEmptyListeners If set to true, errors will be thrown when emitting an `error` event with no listeners. This follows the standard Node.js EventEmitter behavior. Default is `true`. ```javascript const myClass = new MyClass({ throwOnEmptyListeners: true }); console.log(myClass.throwOnEmptyListeners); // true (default) // This will throw because there are no error listeners try { myClass.emit('error', new Error('Something went wrong')); } catch (error) { console.log(error.message); // Something went wrong } // Add an error listener - now it won't throw myClass.on('error', (error) => { console.log('Error caught:', error.message); }); myClass.emit('error', new Error('This will be caught')); // No throw, listener handles it // You can also change it dynamically myClass.throwOnEmptyListeners = false; console.log(myClass.throwOnEmptyListeners); // false ``` **Difference between `throwOnEmitError` and `throwOnEmptyListeners`:** - `throwOnEmitError`: Throws when emitting 'error' event every time. - `throwOnEmptyListeners`: Throws only when there are NO error listeners registered When both are set to `true`, `throwOnEmitError` takes precedence. ## .on(eventName, handler) Subscribe to an event. ```javascript myClass.on('message', (message) => { console.log(message); }); ``` ## .off(eventName, handler) Unsubscribe from an event. ```javascript const handler = (message) => { console.log(message); }; myClass.on('message', handler); myClass.off('message', handler); ``` ## .emit(eventName, ...args) Emit an event. ```javascript myClass.emit('message', 'Hello World'); ``` ## .listeners(eventName) Get all listeners for an event. ```javascript myClass.on('message', (message) => { console.log(message); }); console.log(myClass.listeners('message')); ``` ## .removeAllListeners(eventName) Remove all listeners for an event. ```javascript myClass.on('message', (message) => { console.log(message); }); myClass.removeAllListeners('message'); ``` ## .setMaxListeners(maxListeners: number) Set the maximum number of listeners for a single event. Default is `0` (unlimited). Negative values are treated as `0`. Setting to `0` disables the limit and the warning. When the limit is exceeded, a `MaxListenersExceededWarning` is emitted via `console.warn` but the listener is still added. This matches standard Node.js EventEmitter behavior. ```javascript myClass.setMaxListeners(1); myClass.on('message', (message) => { console.log(message); }); myClass.on('message', (message) => { console.log(message); }); // warning emitted but listener is still added console.log(myClass.listenerCount('message')); // 2 ``` ## .once(eventName, handler) Subscribe to an event once. ```javascript myClass.once('message', (message) => { console.log(message); }); myClass.emit('message', 'Hello World'); // handler runs myClass.emit('message', 'Hello World'); // handler does not run ``` ## .prependListener(eventName, handler) Prepend a listener to an event. This will be called before any other listeners. ```javascript myClass.prependListener('message', (message) => { console.log(message); }); ``` ## .prependOnceListener(eventName, handler) Prepend a listener to an event once. This will be called before any other listeners. ```javascript myClass.prependOnceListener('message', (message) => { console.log(message); }); myClass.emit('message', 'Hello World'); ``` ## .eventNames() Get all event names. ```javascript myClass.on('message', (message) => { console.log(message); }); console.log(myClass.eventNames()); // ['message'] ``` ## .listenerCount(eventName?) Get the count of listeners for an event or all events if eventName not provided. ```javascript myClass.on('message', (message) => { console.log(message); }); console.log(myClass.listenerCount('message')); // 1 ``` ## .rawListeners(eventName?) Get all listeners for an event or all events if eventName not provided. ```javascript myClass.on('message', (message) => { console.log(message); }); console.log(myClass.rawListeners('message')); ``` # Logging Hookified integrates logging directly into the event system. When an `eventLogger` is configured, all emitted events are automatically logged to the appropriate log level based on the event name. ## How It Works When you emit an event, Hookified automatically sends the event data to the configured `eventLogger` using the appropriate log method: | Event Name | Logger Method | |------------|---------------| | `error` | `eventLogger.error()` | | `warn` | `eventLogger.warn()` | | `debug` | `eventLogger.debug()` | | `trace` | `eventLogger.trace()` | | `fatal` | `eventLogger.fatal()` | | Any other | `eventLogger.info()` | The logger receives two arguments: 1. **message**: A string extracted from the event data (error messages, object messages, or JSON stringified data) 2. **context**: An object containing `{ event: eventName, data: originalData }` Some loggers use the message as a format string, and some loggers write the message as text lines. Hookified changes the message so that event data cannot change the structure of a log record: - A percent sign that starts a format specifier, for example `%s` or `%o`, becomes `%%`. A logger that formats the message shows `%`. A logger that does not format the message shows `%%`. - A control character or a line separator becomes an escape sequence, for example `\n` or `\u001b`. The `data` property of the context has the event data with no change. ## Setting Up a Logger Any logger that implements the `Logger` interface is compatible. This includes popular loggers like [Pino](https://github.com/pinojs/pino), [Winston](https://github.com/winstonjs/winston), [Bunyan](https://github.com/trentm/node-bunyan), and others. ```typescript type Logger = { trace: (message: string, ...args: unknown[]) => void; debug: (message: string, ...args: unknown[]) => void; info: (message: string, ...args: unknown[]) => void; warn: (message: string, ...args: unknown[]) => void; error: (message: string, ...args: unknown[]) => void; fatal: (message: string, ...args: unknown[]) => void; }; ``` ## Usage Example with Pino ```javascript import { Hookified } from 'hookified'; import pino from 'pino'; const logger = pino(); class MyService extends Hookified { constructor() { super({ eventLogger: logger }); } async processData(data) { // This will log to logger.info with the data this.emit('info', { action: 'processing', data }); try { // ... process data this.emit('debug', { action: 'completed', result: 'success' }); } catch (err) { // This will log to logger.error with the error message this.emit('error', err); } } } const service = new MyService(); // All events are automatically logged service.emit('info', 'Service started'); // -> logger.info() service.emit('warn', { message: 'Low memory' }); // -> logger.warn() service.emit('error', new Error('Failed')); // -> logger.error() service.emit('custom-event', { foo: 'bar' }); // -> logger.info() (default) ``` You can also set or change the eventLogger after instantiation: ```javascript const service = new MyService(); service.eventLogger = pino({ level: 'debug' }); // Or remove the eventLogger service.eventLogger = undefined; ``` # Hook Stats Hookified includes an optional `HookStats` collector on `.stats`. Collection is off by default and adds no clock reads or allocations when off. To collect stats, pass `enableStats: true` to the constructor, or set `stats.enabled = true`. ## What Hookified Collects When `stats.enabled` is `true`, Hookified collects these metrics: - **Dispatches**: Each call to `.hook()` or `.hookSync()` with at least one handler increments `calls` on the event. Each handler that starts increments its own `calls`. Empty dispatches record nothing. - **Errors**: Thrown handler errors and late promise rejections from `.hookSync()` increment `errors` on the handler and event. - **Skipped handlers**: Async functions that `.hookSync()` skips increment `skipped`. They do not read the clock or increment handler `calls`. A dispatch whose handlers are all skipped still records one event duration sample of `0`. - **Blocked dispatches**: Calls to `.hook()` or `.hookSync()` that `allowDeprecated: false` blocks increment `blocked` on the event. Blocked registrations record nothing. - **`pending` dispatches**: Active calls in `.hook()` show `pending` as `calls - duration.count` on the handler, event, and totals until they finish. - **Durations**: Each handler runs with two `performance.now()` reads. Each dispatch records one event duration sample equal to the sum of its handler durations. - **Registration**: `stats.registration` counts `registered` inserts, `replaced` same-id updates, `removed` hooks (plus `.onceHook()` self-removal), and `removeMisses` on single-hook removals. ## Example ```javascript import { Hookified } from 'hookified'; class MyService extends Hookified { constructor() { super({ enableStats: true }); } } const service = new MyService(); service.onHook({ id: 'validate', event: 'before:save', handler: async (data) => { data.valid = true; }, }); await service.hook('before:save', { id: 1 }); console.log(service.stats.calls); // 1 console.log(service.stats.duration.mean); // duration in ms console.log(service.stats.events[0].hooks[0]); // { id: 'validate', calls: 1, errors: 0, skipped: 0, pending: 0, duration: ... } console.log(service.stats.topCalls()); // top 20 live hooks by calls console.log(service.stats.longestCalls()); // top 20 live hooks by duration.max console.log(JSON.stringify(service.stats)); // plain JSON snapshot from toJSON() ``` ## Units and Precision All durations use float milliseconds from `performance.now()`. The collector keeps the unrounded sum internally. On read, the collector rounds `sum`, `min`, `max`, `last`, and `mean` to 3 decimal places. It calculates `mean` from the unrounded sum divided by `count`, then rounds the result. When `count` is `0`, every duration field is `0`. ## Top 20 Leaderboards `stats.topCalls()` and `stats.longestCalls()` read live hook rows at call time and return at most 20 items. `topCalls()` sorts by `calls` from high to low. `longestCalls()` sorts by `duration.max` from high to low and excludes hooks with `duration.count === 0`. Both methods break ties by `event` and then by `id` from A to Z, with hooks without an `id` first. When you remove a hook, it leaves both lists, while event totals stay. ## 1000-Event Cap Hookified tracks up to 1000 distinct event names individually while stats are on. A name keeps its slot until `resetStats()`, including after you remove its hooks. Events after the 1000th fold into `stats.overflow`, which stays `undefined` before the 1001st distinct event name. Overflow totals count toward the top-level totals on `stats`, and `registration.registered` still increments. Overflow hooks have no per-hook rows, so they do not appear in `events`, `topCalls()`, or `longestCalls()`. ## Scope Notes - **Events with `.emit()`**: Hookified does not collect stats for `Eventified.emit()`. - **`WaterfallHook` and `ParallelHook`**: Each `WaterfallHook` or `ParallelHook` that you register through `.onHook()` counts as one handler row. A step that throws inside `WaterfallHook` counts as one hook error. A step that rejects inside `ParallelHook` settles internally and counts as zero hook errors. - **Subclasses**: `.stats` is a getter. Hookified stores the collector on `_stats`. A subclass that assigns its own `_stats` after `super()` keeps that value. Hook recording runs only when `_stats` is a `HookStats` instance. # Benchmarks We are doing very simple benchmarking to see how this compares to other libraries using `tinybench`. This is not a full benchmark but just a simple way to see how it performs. ## Hooks | name | summary | ops/sec | time/op | margin | samples | |----------------------|:---------:|----------:|----------:|:--------:|----------:| | Hookified (v2.0.1) | 🥇 | 5M | 221ns | ±0.01% | 5M | | Hookable (v6.0.1) | -59% | 2M | 569ns | ±0.01% | 2M | ## Emits This shows how on par `hookified` is to the native `EventEmitter` and popular `eventemitter3`. These are simple emitting benchmarks to see how it performs. Our goal is to be as close or better than the other libraries including native (EventEmitter). | name | summary | ops/sec | time/op | margin | samples | |---------------------------|:---------:|----------:|----------:|:--------:|----------:| | Hookified (v2.1.0) | 🥇 | 17M | 73ns | ±0.02% | 14M | | EventEmitter3 (v5.0.4) | -2.2% | 17M | 70ns | ±0.02% | 14M | | EventEmitter (v24.14.0) | -4.5% | 16M | 70ns | ±0.02% | 14M | | Emittery (v2.0.0) | -92% | 1M | 792ns | ±0.01% | 1M | _Note: the `EventEmitter` version is Nodejs versioning._ # Migrating from v2 to v3 v3 has no breaking API changes. The only breaking change is the minimum Node.js version requirement. ## Breaking Changes | Change | Summary | |---|---| | Node.js version | Minimum required version is now `>=22.18.0` (previously no `engines` constraint) | ### Node.js >=22.18.0 required The `engines` field in `package.json` now requires Node.js 22.18.0 or later. Node.js 20 reached end-of-life in April 2026. **Migration:** Upgrade to Node.js 22 LTS or Node.js 24+. No code changes are required — all v2 code works unchanged on v3. ## New Features ### Hook tags Hook tags are additive. `IHook.tags` is optional, existing constructors still work, existing `IHook` implementations stay valid, untagged hooks are unchanged, and `removeHook` still returns `{ event, handler }`. If you previously attached your own `tags` property to hook objects, it must now be a `string[]` of non-empty strings (or omitted); `null` or other values throw a `TypeError` on registration. ```javascript myClass.onHook({ id: 'validate', event: 'before:save', tags: ['validation', 'audit'], handler: async (data) => { data.validated = true; }, }); myClass.getHooksByTag('audit'); // hooks tagged "audit", across events myClass.getHooksByTag(['validation', 'audit']); // hooks with any of these tags myClass.getTaggedHooks(); // Map { 'validation' => [...], 'audit' => [...] } ``` # Migrating from v1 to v2 ## Quick Guide v2 overhauls hook storage to use `IHook` objects instead of raw functions. This enables hook IDs, ordering via position, cloning control, and new hook types like `WaterfallHook`. `onHook` now supports both the v1 positional `(event, handler)` form and the new `IHook` object form, so this is **not a breaking change**: ```typescript // v1 style — still works hookified.onHook('before:save', async (data) => {}); // v2 style — IHook object with options support hookified.onHook({ event: 'before:save', handler: async (data) => {} }); // addHook also works as an alias for the positional form hookified.addHook('before:save', async (data) => {}); ``` **Other common changes:** | v1 | v2 | |---|---| | `throwHookErrors` | `throwOnHookError` | | `logger` | `eventLogger` | | `onHookEntry(hook)` | `onHook(hook)` | | `HookEntry` type | `IHook` interface | | `Hook` type (fn) | `HookFn` type | | `getHooks()` returns `HookFn[]` | `getHooks()` returns `IHook[]` | | `removeHook(event, handler)` | `removeHook({ event, handler })` | See below for full details on each change. **[Breaking Changes](#breaking-changes)** - [`throwHookErrors` removed — use `throwOnHookError` instead](#throwhookerrors-removed--use-throwonhookerror-instead) - [`throwOnEmptyListeners` now defaults to `true`](#throwonemptylisteners-now-defaults-to-true) - [`logger` renamed to `eventLogger`](#logger-renamed-to-eventlogger) - [`maxListeners` default changed from `100` to `0` (unlimited) and no longer truncates](#maxlisteners-default-changed-from-100-to-0-unlimited-and-no-longer-truncates) - [`onHookEntry` removed — use `onHook` instead](#onhookentry-removed--use-onhook-instead) - [`onHook` signature updated (not breaking)](#onhook-signature-updated) - [`HookEntry` type and `Hook` type removed](#hookentry-type-and-hook-type-removed) - [`removeHook` and `removeHooks` now return removed hooks](#removehook-and-removehooks-now-return-removed-hooks) - [`removeHook`, `removeHooks`, and `getHooks` no longer check for deprecated hooks](#removehook-removehooks-and-gethooks-no-longer-check-for-deprecated-hooks) - [Internal hook storage now uses `IHook` objects](#internal-hook-storage-now-uses-ihook-objects) - [`onceHook`, `prependHook`, `prependOnceHook`, and `removeHook` now take `IHook`](#oncehook-prependhook-prependoncehook-and-removehook-now-take-ihook) - [`onHook` now returns the stored hook](#onhook-now-returns-the-stored-hook) **[New Features](#new-features)** - [standard `Hook` class now available](#standard-hook) - [`WaterfallHook` class for sequential data transformation pipelines](#waterfallhook-class) - [`useHookClone` option](#usehookclone-option) - [`onHook` now accepts `OnHookOptions`](#onhook-now-accepts-onhookoptions) - [`IHook` now has an `id` property](#ihook-now-has-an-id-property) - [`removeEventHooks` method](#removeeventhooks-method) ## Breaking Changes | Change | Summary | |---|---| | `throwHookErrors` | Renamed to `throwOnHookError` | | `throwOnEmptyListeners` | Default changed from `false` to `true` | | `logger` | Renamed to `eventLogger` | | `maxListeners` | Default changed from `100` to `0` (unlimited), no longer truncates | | `onHookEntry` | Removed — use `onHook` instead | | `onHook` signature | Now takes `IHook` object **or** `(event, handler)` — both supported (not breaking) | | `HookEntry` / `Hook` types | Replaced with `IHook` / `HookFn` | | `removeHook` / `removeHooks` | Now return removed hooks; no longer check deprecated status | | Internal hook storage | Uses `IHook` objects instead of raw functions | | `onceHook`, `prependHook`, etc. | Now take `IHook` instead of `(event, handler)` | | `onHook` return | Now returns stored `IHook` (was `void`) | ### `throwHookErrors` removed — use `throwOnHookError` instead The deprecated `throwHookErrors` option and property has been removed. Use `throwOnHookError` instead. **Before (v1):** ```javascript super({ throwHookErrors: true }); myClass.throwHookErrors = false; ``` **After (v2):** ```javascript super({ throwOnHookError: true }); myClass.throwOnHookError = false; ``` ### `throwOnEmptyListeners` now defaults to `true` The `throwOnEmptyListeners` option now defaults to `true`, matching standard Node.js EventEmitter behavior. Previously it defaulted to `false`. If you emit an `error` event with no listeners registered, an error will now be thrown by default. **Before (v1):** ```javascript const myClass = new MyClass(); // throwOnEmptyListeners defaults to false myClass.emit('error', new Error('No throw')); // silently ignored ``` **After (v2):** ```javascript const myClass = new MyClass(); // throwOnEmptyListeners defaults to true myClass.emit('error', new Error('This will throw')); // throws! // To restore v1 behavior: const myClass2 = new MyClass({ throwOnEmptyListeners: false }); ``` ### `logger` renamed to `eventLogger` The `logger` option and property has been renamed to `eventLogger` to avoid conflicts with other logger properties in your classes. **Before (v1):** ```javascript super({ logger }); myClass.logger = pino({ level: 'debug' }); ``` **After (v2):** ```javascript super({ eventLogger: logger }); myClass.eventLogger = pino({ level: 'debug' }); ``` ### `maxListeners` default changed from `100` to `0` (unlimited) and no longer truncates The default maximum number of listeners has changed from `100` to `0` (unlimited). The `MaxListenersExceededWarning` will no longer be emitted unless you explicitly set a limit via `setMaxListeners()`. Additionally, `setMaxListeners()` no longer truncates existing listeners — it only sets the warning threshold, matching standard Node.js EventEmitter behavior. **Before (v1):** ```javascript const myClass = new MyClass(); // maxListeners defaults to 100 // Warning emitted after adding 100+ listeners to the same event // setMaxListeners() would truncate existing listeners exceeding the limit ``` **After (v2):** ```javascript const myClass = new MyClass(); // maxListeners defaults to 0 (unlimited) // No warning — unlimited listeners allowed // setMaxListeners() only sets warning threshold, never removes listeners // To restore v1 warning behavior: myClass.setMaxListeners(100); ``` ### `onHookEntry` removed — use `onHook` instead The `onHookEntry` method has been removed. Use `onHook` which now accepts an `IHook` object (or array of `IHook`) directly. **Before (v1):** ```typescript hookified.onHookEntry({ event: 'before:save', handler: async (data) => {} }); ``` **After (v2):** ```typescript hookified.onHook({ event: 'before:save', handler: async (data) => {} }); ``` ### `onHook` signature updated `onHook` now supports both the v1 positional `(event, handler)` form and the new `IHook` object form. **This is not a breaking change** — existing v1 code continues to work. The `IHook` object form is recommended for new code as it supports hook IDs, positioning, and cloning options. You can also use `addHook(event, handler)` as an alias or `onHooks()` for bulk registration. ```typescript // v1 style — still works hookified.onHook('before:save', async (data) => {}); // v2 style — IHook object with full options support hookified.onHook({ event: 'before:save', handler: async (data) => {} }); // For multiple hooks, use onHooks hookified.onHooks([ { event: 'before:save', handler: async (dat