hookified 2.1.1 → 3.0.0

package/README.md

@@ -12,7 +12,7 @@
 # Features
 - Simple replacement for EventEmitter
 - Async / Sync Middleware Hooks for Your Methods 
-- ESM / CJS with Types and Nodejs 20+
+- 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
@@ -20,6 +20,7 @@
 - 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
 - No package dependencies and only 250KB in size
 - Fast and Efficient with [Benchmarks](#benchmarks)
 - Maintained on a regular basis!
@@ -27,11 +28,13 @@
 # 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](#waterfallhook)
+  - [Waterfall Hook](#waterfall-hook)
+  - [Parallel Hook](#parallel-hook)
 - [API - Hooks](#api---hooks)
   - [.allowDeprecated](#allowdeprecated)
   - [.deprecatedHooks](#deprecatedhooks)
@@ -342,6 +345,114 @@ wh.removeHook(myHook); // returns true
 console.log(wh.hooks.length); // 0
 ```
 
+## 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()`.
+
+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<ParallelHookFn, ParallelHookResult>` | 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<TArgs, TResult>` 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<NotifyArgs, NotifyResult>('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:
@@ -1253,6 +1364,22 @@ This shows how on par `hookified` is to the native `EventEmitter` and popular `e
 
 _Note: the `EventEmitter` version is Nodejs versioning._
 
+# Migrating from v2 to v3
+
+v3 has no 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 — the library API is identical to v2.
+
 # Migrating from v1 to v2
 
 ## Quick Guide