hookified 2.1.1 → 2.2.0

package/README.md

@@ -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!
@@ -31,7 +32,8 @@
 - [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 +344,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: