@nwire/hooks 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Gefter / 200apps Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,98 @@
+# @nwire/hooks
+
+> Universal dispatch primitive. One `hook()` accepts both `.use()` (sequential chain) and `.on()` (parallel listener) attachments.
+
+## What it is
+
+Every middleware, lifecycle phase, event subscription, and plugin attachment in Nwire is built from one primitive: a named hook that runs a koa-compose chain first, then a parallel listener fan-out via `Promise.allSettled`. Built on [emittery](https://github.com/sindresorhus/emittery) (~3KB) plus a ~30 LOC composer. No other Nwire package required.
+
+## Install
+
+```bash
+pnpm add @nwire/hooks
+```
+
+## Standalone use
+
+For developers building a framework, a lifecycle host, or any system that needs both wrappers (tracing, auth, retry) AND observers (analytics, metrics) on the same signal.
+
+```ts
+import { hook } from "@nwire/hooks";
+
+interface RequestCtx {
+  url: string;
+  startTime?: number;
+  duration?: number;
+  error?: unknown;
+}
+
+const request = hook<RequestCtx>("http.request");
+
+// MIDDLEWARE — sequential, can wrap, can short-circuit
+request.use(async (ctx, next) => {
+  ctx.startTime = Date.now();
+  await next();
+  ctx.duration = Date.now() - ctx.startTime;
+});
+
+// LISTENER — parallel observer, fires after the chain
+request.on(async (ctx) => {
+  await analytics.track(ctx);
+});
+
+await request.run({ url: "/hello" });
+// 1. .use() chain in insertion order (each can next() or short-circuit)
+// 2. .on() listeners in parallel via Promise.allSettled
+// 3. If chain throws, ctx.error is set BEFORE listeners fire
+```
+
+## Within nwire-app
+
+For developers using this package as part of the Nwire stack. You usually never call `hook()` yourself — `@nwire/app` lifecycle, `@nwire/forge` events, and every plugin's middleware all build on it. Touch this package when authoring a plugin that needs custom hooks.
+
+```ts
+import { createHooks, hook } from "@nwire/hooks";
+
+const lifecycle = createHooks({
+  boot: hook<EndpointCtx>("endpoint.boot"),
+  ready: hook<EndpointCtx>("endpoint.ready"),
+  shutdown: hook<EndpointCtx>("endpoint.shutdown"),
+});
+
+// Apply a plugin object — same hook can take chains AND listeners:
+lifecycle.use({
+  boot: async (ctx, next) => {
+    logger.info("booting…");
+    await next();
+  },
+  shutdown: { on: (ctx) => logger.info("shut down", ctx) },
+});
+```
+
+## The contract — the matrix
+
+| Question                                         | Behavior                                    |
+| ------------------------------------------------ | ------------------------------------------- |
+| `.on()` runs if chain short-circuits (no throw)? | Yes — listeners observe outcome             |
+| `.on()` runs if chain throws?                    | Yes — `ctx.error` is set first              |
+| Can listeners mutate ctx?                        | No — `.on()` types ctx as `Readonly<Ctx>`   |
+| Listeners awaited by `.run()`?                   | Yes — parallel, `Promise.allSettled`        |
+| Listener throws → fails chain?                   | No — collected, routed to `onListenerError` |
+| Listener ordering                                | Unordered (parallel)                        |
+| Chain ordering                                   | Insertion order (koa-compose)               |
+
+Escape hatch: `hook(name, { strictListeners: true })` re-throws the first listener error instead of routing it through `onListenerError`.
+
+## API
+
+- `hook<Ctx>(name, options?)` — create one hook.
+- `Hook<Ctx>.use(fn)` / `.on(fn)` / `.off(fn)` / `.run(ctx)`.
+- `createHooks(record)` — typed bundle with `.hooks` + `.use(plugin)`.
+- `compose(fns)` / `pipe(...fns)` / `withTimeout(ms, fn)` / `withRetry(opts, fn)` — composition helpers.
+
+## See also
+
+- [Architecture sketch §06 — Hooks, the universal dispatch primitive](../../architecture-sketch.html#hooks)
+- [Architecture sketch §07 — Hook contract matrix](../../architecture-sketch.html#hook-contract)
+- Built on [`emittery`](https://github.com/sindresorhus/emittery)
+- Sibling packages: [@nwire/endpoint](../nwire-endpoint), [@nwire/container](../nwire-container), [@nwire/app](../nwire-app)

package/dist/compose.d.ts

@@ -0,0 +1,16 @@
+/**
+ * koa-compose-shaped chain composer. ~30 LOC.
+ *
+ * Insertion order. Each fn wraps the next; first registered runs outermost.
+ * A fn that returns without calling `next()` short-circuits the rest of the
+ * chain — that's the outcome listeners observe.
+ *
+ * See architecture-sketch.html §07 (Chain ordering = insertion order).
+ */
+import type { ChainFn } from "./types.js";
+/**
+ * Compose an ordered list of chain functions into a single chain function.
+ * Throws if a middleware calls `next()` more than once (koa convention).
+ */
+export declare function compose<Ctx>(fns: ReadonlyArray<ChainFn<Ctx>>): ChainFn<Ctx>;
+//# sourceMappingURL=compose.d.ts.map

package/dist/compose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose.d.ts","sourceRoot":"","sources":["../src/compose.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC;;;GAGG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,aAAa,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAgB3E"}

package/dist/compose.js

@@ -0,0 +1,30 @@
+/**
+ * koa-compose-shaped chain composer. ~30 LOC.
+ *
+ * Insertion order. Each fn wraps the next; first registered runs outermost.
+ * A fn that returns without calling `next()` short-circuits the rest of the
+ * chain — that's the outcome listeners observe.
+ *
+ * See architecture-sketch.html §07 (Chain ordering = insertion order).
+ */
+/**
+ * Compose an ordered list of chain functions into a single chain function.
+ * Throws if a middleware calls `next()` more than once (koa convention).
+ */
+export function compose(fns) {
+    return function composed(ctx, finalNext) {
+        let lastIndex = -1;
+        const dispatch = async (i) => {
+            if (i <= lastIndex) {
+                throw new Error("next() called multiple times in @nwire/hooks chain");
+            }
+            lastIndex = i;
+            const fn = i === fns.length ? finalNext : fns[i];
+            if (!fn)
+                return;
+            await fn(ctx, () => dispatch(i + 1));
+        };
+        return dispatch(0);
+    };
+}
+//# sourceMappingURL=compose.js.map

package/dist/compose.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose.js","sourceRoot":"","sources":["../src/compose.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;;GAGG;AACH,MAAM,UAAU,OAAO,CAAM,GAAgC;IAC3D,OAAO,SAAS,QAAQ,CAAC,GAAG,EAAE,SAAS;QACrC,IAAI,SAAS,GAAG,CAAC,CAAC,CAAC;QAEnB,MAAM,QAAQ,GAAG,KAAK,EAAE,CAAS,EAAiB,EAAE;YAClD,IAAI,CAAC,IAAI,SAAS,EAAE,CAAC;gBACnB,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;YACxE,CAAC;YACD,SAAS,GAAG,CAAC,CAAC;YACd,MAAM,EAAE,GAAG,CAAC,KAAK,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YACjD,IAAI,CAAC,EAAE;gBAAE,OAAO;YAChB,MAAM,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACvC,CAAC,CAAC;QAEF,OAAO,QAAQ,CAAC,CAAC,CAAC,CAAC;IACrB,CAAC,CAAC;AACJ,CAAC"}

package/dist/create-hooks.d.ts

@@ -0,0 +1,56 @@
+/**
+ * `createHooks()` — typed host for a group of named hooks.
+ *
+ * Exposes the original `.hooks` record (so consumers can spread it into
+ * extended hosts: `createHooks({ ...lifecycle.hooks, request: hook(...) })`),
+ * and a plain-object `.use(plugin)` DX with full autocomplete on hook names.
+ *
+ * See architecture-sketch.html §06 ("Each consumer wires its own hooks").
+ */
+import type { Hook } from "./hook.js";
+import type { ChainFn, ListenerFn } from "./types.js";
+/** Map of hook name → `Hook<Ctx>` for that hook. */
+export type HookMap = Record<string, Hook<any>>;
+/** Recover the Ctx parameter of a Hook. */
+type CtxOf<H> = H extends Hook<infer C> ? C : never;
+/**
+ * Per-hook plugin entry shape. Two convenience overloads:
+ *   - a single chain fn, OR a list of chain fns (registered in order)
+ *   - a tagged listener entry: `{ on: fn }` or `{ on: [fn1, fn2] }`
+ *
+ * Listeners and chains can coexist:
+ *   { request: [chain1, chain2, { on: listener }] }
+ */
+export type PluginEntry<Ctx> = ChainFn<Ctx> | {
+    on: ListenerFn<Ctx> | ReadonlyArray<ListenerFn<Ctx>>;
+} | ReadonlyArray<ChainFn<Ctx> | {
+    on: ListenerFn<Ctx> | ReadonlyArray<ListenerFn<Ctx>>;
+}>;
+/** A plugin object keyed by hook name. All entries optional. */
+export type Plugin<T extends HookMap> = {
+    [K in keyof T]?: PluginEntry<CtxOf<T[K]>>;
+};
+/** The typed host returned by {@link createHooks}. */
+export interface Host<T extends HookMap> {
+    /** The underlying hook record. Spread to compose hosts. */
+    readonly hooks: T;
+    /** Apply a plugin object across multiple hooks at once. */
+    use(plugin: Plugin<T>): this;
+}
+/**
+ * Build a typed host over a record of hooks. Hook names are inferred from
+ * the keys; ctx types are inferred per-hook.
+ *
+ * @example
+ *   const lifecycle = createHooks({
+ *     boot:     hook<EndpointCtx>("endpoint.boot"),
+ *     shutdown: hook<EndpointCtx>("endpoint.shutdown"),
+ *   });
+ *   lifecycle.use({
+ *     boot: async (ctx, next) => { console.log("booting…"); await next(); },
+ *     shutdown: { on: (ctx) => console.log("shut down") },
+ *   });
+ */
+export declare function createHooks<T extends HookMap>(hooks: T): Host<T>;
+export {};
+//# sourceMappingURL=create-hooks.d.ts.map

package/dist/create-hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-hooks.d.ts","sourceRoot":"","sources":["../src/create-hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AACnC,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAEnD,oDAAoD;AACpD,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAEhD,2CAA2C;AAC3C,KAAK,KAAK,CAAC,CAAC,IAAI,CAAC,SAAS,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAEpD;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,CAAC,GAAG,IACvB,OAAO,CAAC,GAAG,CAAC,GACZ;IAAE,EAAE,EAAE,UAAU,CAAC,GAAG,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAA;CAAE,GACxD,aAAa,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG;IAAE,EAAE,EAAE,UAAU,CAAC,GAAG,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAA;CAAE,CAAC,CAAC;AAE3F,gEAAgE;AAChE,MAAM,MAAM,MAAM,CAAC,CAAC,SAAS,OAAO,IAAI;KACrC,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAC1C,CAAC;AAEF,sDAAsD;AACtD,MAAM,WAAW,IAAI,CAAC,CAAC,SAAS,OAAO;IACrC,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,2DAA2D;IAC3D,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;CAC9B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,OAAO,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAehE"}

package/dist/create-hooks.js

@@ -0,0 +1,63 @@
+/**
+ * `createHooks()` — typed host for a group of named hooks.
+ *
+ * Exposes the original `.hooks` record (so consumers can spread it into
+ * extended hosts: `createHooks({ ...lifecycle.hooks, request: hook(...) })`),
+ * and a plain-object `.use(plugin)` DX with full autocomplete on hook names.
+ *
+ * See architecture-sketch.html §06 ("Each consumer wires its own hooks").
+ */
+/**
+ * Build a typed host over a record of hooks. Hook names are inferred from
+ * the keys; ctx types are inferred per-hook.
+ *
+ * @example
+ *   const lifecycle = createHooks({
+ *     boot:     hook<EndpointCtx>("endpoint.boot"),
+ *     shutdown: hook<EndpointCtx>("endpoint.shutdown"),
+ *   });
+ *   lifecycle.use({
+ *     boot: async (ctx, next) => { console.log("booting…"); await next(); },
+ *     shutdown: { on: (ctx) => console.log("shut down") },
+ *   });
+ */
+export function createHooks(hooks) {
+    const host = {
+        hooks,
+        use(plugin) {
+            for (const key of Object.keys(plugin)) {
+                const entry = plugin[key];
+                if (entry === undefined)
+                    continue;
+                const target = hooks[key];
+                if (!target)
+                    continue;
+                applyEntry(target, entry);
+            }
+            return host;
+        },
+    };
+    return host;
+}
+function applyEntry(target, entry) {
+    if (Array.isArray(entry)) {
+        for (const sub of entry)
+            applyEntry(target, sub);
+        return;
+    }
+    if (typeof entry === "function") {
+        target.use(entry);
+        return;
+    }
+    if (entry && typeof entry === "object" && "on" in entry) {
+        const onFn = entry.on;
+        if (Array.isArray(onFn)) {
+            for (const fn of onFn)
+                target.on(fn);
+        }
+        else if (typeof onFn === "function") {
+            target.on(onFn);
+        }
+    }
+}
+//# sourceMappingURL=create-hooks.js.map

package/dist/create-hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-hooks.js","sourceRoot":"","sources":["../src/create-hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAqCH;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,WAAW,CAAoB,KAAQ;IACrD,MAAM,IAAI,GAAY;QACpB,KAAK;QACL,GAAG,CAAC,MAAM;YACR,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAmB,EAAE,CAAC;gBACxD,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;gBAC1B,IAAI,KAAK,KAAK,SAAS;oBAAE,SAAS;gBAClC,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;gBAC1B,IAAI,CAAC,MAAM;oBAAE,SAAS;gBACtB,UAAU,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;YAC5B,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;KACF,CAAC;IACF,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,UAAU,CAAM,MAAiB,EAAE,KAAuB;IACjE,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,KAAK,MAAM,GAAG,IAAI,KAAK;YAAE,UAAU,CAAC,MAAM,EAAE,GAAuB,CAAC,CAAC;QACrE,OAAO;IACT,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,UAAU,EAAE,CAAC;QAChC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAClB,OAAO;IACT,CAAC;IACD,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,IAAI,IAAI,KAAK,EAAE,CAAC;QACxD,MAAM,IAAI,GAAG,KAAK,CAAC,EAAE,CAAC;QACtB,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YACxB,KAAK,MAAM,EAAE,IAAI,IAAI;gBAAE,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QACvC,CAAC;aAAM,IAAI,OAAO,IAAI,KAAK,UAAU,EAAE,CAAC;YACtC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/hook.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The core `hook()` factory and Hook class.
+ *
+ * One hook accepts BOTH `.use()` (chain) and `.on()` (parallel listener)
+ * attachments. `.run()` fires the chain first (sequential, can short-circuit),
+ * then fires listeners in parallel via Promise.allSettled.
+ *
+ * Behavior matrix is locked by architecture-sketch.html §07.
+ */
+import type { ChainFn, HookOptions, ListenerFn } from "./types.js";
+/** The public Hook surface. See architecture-sketch.html §06. */
+export interface Hook<Ctx> {
+    /** Hook name. Stable for logging + telemetry. */
+    readonly name: string;
+    /** Attach a chain middleware (sequential, can short-circuit). */
+    use(fn: ChainFn<Ctx>): this;
+    /** Attach a listener (parallel, observes final ctx, cannot mutate). */
+    on(fn: ListenerFn<Ctx>): this;
+    /** Detach a previously attached `.use()` or `.on()` fn. No-op if unknown. */
+    off(fn: ChainFn<Ctx> | ListenerFn<Ctx>): this;
+    /** Run the chain, then fire listeners. Returns the (possibly mutated) ctx. */
+    run(ctx: Ctx): Promise<Ctx>;
+}
+/**
+ * Create a new hook.
+ *
+ * @example
+ *   const request = hook<RequestCtx>("http.request");
+ *   request.use(async (ctx, next) => { ctx.start = Date.now(); await next(); });
+ *   request.on(async (ctx) => { await analytics.track(ctx); });
+ *   await request.run(ctx);
+ */
+export declare function hook<Ctx>(name: string, options?: HookOptions<Ctx>): Hook<Ctx>;
+//# sourceMappingURL=hook.d.ts.map

package/dist/hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook.d.ts","sourceRoot":"","sources":["../src/hook.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAWhE,iEAAiE;AACjE,MAAM,WAAW,IAAI,CAAC,GAAG;IACvB,iDAAiD;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,iEAAiE;IACjE,GAAG,CAAC,EAAE,EAAE,OAAO,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;IAE5B,uEAAuE;IACvE,EAAE,CAAC,EAAE,EAAE,UAAU,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;IAE9B,6EAA6E;IAC7E,GAAG,CAAC,EAAE,EAAE,OAAO,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;IAE9C,8EAA8E;IAC9E,GAAG,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;CAC7B;AAED;;;;;;;;GAQG;AACH,wBAAgB,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,WAAW,CAAC,GAAG,CAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAEjF"}

package/dist/hook.js

@@ -0,0 +1,148 @@
+/**
+ * The core `hook()` factory and Hook class.
+ *
+ * One hook accepts BOTH `.use()` (chain) and `.on()` (parallel listener)
+ * attachments. `.run()` fires the chain first (sequential, can short-circuit),
+ * then fires listeners in parallel via Promise.allSettled.
+ *
+ * Behavior matrix is locked by architecture-sketch.html §07.
+ */
+import Emittery from "emittery";
+import { compose } from "./compose.js";
+/**
+ * Internal emittery event name. We piggy-back on emittery for typed
+ * subscription bookkeeping (and as the documented foundation of @nwire/hooks),
+ * but we iterate listeners ourselves via a parallel Set so we can apply the
+ * contract-mandated `Promise.allSettled` semantics — emittery's `.emit()`
+ * uses Promise.all which fails fast on the first rejection.
+ */
+const RUN_EVENT = "__nwire_hooks_run__";
+/**
+ * Create a new hook.
+ *
+ * @example
+ *   const request = hook<RequestCtx>("http.request");
+ *   request.use(async (ctx, next) => { ctx.start = Date.now(); await next(); });
+ *   request.on(async (ctx) => { await analytics.track(ctx); });
+ *   await request.run(ctx);
+ */
+export function hook(name, options = {}) {
+    return new HookImpl(name, options);
+}
+class HookImpl {
+    name;
+    chain = [];
+    /** Iteration store — we run these in parallel via Promise.allSettled. */
+    listeners = new Set();
+    /** Bookkeeping mirror — emittery is the documented foundation. */
+    emitter = new Emittery();
+    /** Map user fn → emittery-shaped adapter, for `.off()`. */
+    adapters = new WeakMap();
+    strictListeners;
+    onListenerError;
+    constructor(name, options) {
+        this.name = name;
+        this.strictListeners = options.strictListeners === true;
+        this.onListenerError =
+            options.onListenerError ??
+                ((err, _ctx, hookName) => {
+                    // Conservative default — log + continue. Hosts (createHooks)
+                    // override this to route through their `lifecycle.error` hook.
+                    // eslint-disable-next-line no-console
+                    console.error(`[@nwire/hooks] listener error in "${hookName}":`, err);
+                });
+    }
+    use(fn) {
+        this.chain.push(fn);
+        return this;
+    }
+    on(fn) {
+        if (this.listeners.has(fn))
+            return this;
+        this.listeners.add(fn);
+        const adapter = async (ctx) => {
+            await fn(ctx);
+        };
+        this.adapters.set(fn, adapter);
+        this.emitter.on(RUN_EVENT, adapter);
+        return this;
+    }
+    off(fn) {
+        // Try chain first.
+        const chainIdx = this.chain.indexOf(fn);
+        if (chainIdx >= 0) {
+            this.chain.splice(chainIdx, 1);
+            return this;
+        }
+        // Otherwise treat as listener.
+        const listenerFn = fn;
+        if (this.listeners.delete(listenerFn)) {
+            const adapter = this.adapters.get(listenerFn);
+            if (adapter) {
+                this.emitter.off(RUN_EVENT, adapter);
+                this.adapters.delete(listenerFn);
+            }
+        }
+        return this;
+    }
+    async run(ctx) {
+        // 1. Run the chain. If it throws, capture before listeners fire so they
+        //    can observe the failure mode via ctx.error.
+        const composed = compose(this.chain);
+        let chainError = undefined;
+        try {
+            await composed(ctx, async () => {
+                // Tail — nothing to do. The chain itself decides whether to call
+                // next() or short-circuit.
+            });
+        }
+        catch (err) {
+            chainError = err;
+            // Stash on ctx so listeners can observe failure mode. Mutating even
+            // when `Ctx` doesn't declare an `error` field is the documented
+            // contract (§07 row 2 + row 11).
+            ctx.error = err;
+        }
+        // 2. Fire listeners in parallel via Promise.allSettled — contract row 4.
+        if (this.listeners.size > 0) {
+            const snapshot = Array.from(this.listeners);
+            const results = await Promise.allSettled(snapshot.map(async (listener) => listener(ctx)));
+            const failures = results.filter((r) => r.status === "rejected");
+            if (failures.length > 0) {
+                if (this.strictListeners) {
+                    // Strict mode: opt-in escape hatch (§07 closing note). Surface
+                    // the first failure; attach the rest via `cause` for debug.
+                    const primary = failures[0].reason;
+                    if (failures.length > 1 &&
+                        primary instanceof Error &&
+                        primary.cause === undefined) {
+                        Object.defineProperty(primary, "cause", {
+                            value: failures.slice(1).map((f) => f.reason),
+                            configurable: true,
+                            writable: true,
+                        });
+                    }
+                    throw primary;
+                }
+                // Default mode: report each, never fail the run.
+                for (const failure of failures) {
+                    try {
+                        this.onListenerError(failure.reason, ctx, this.name);
+                    }
+                    catch {
+                        // Reporter itself blew up — swallow. Listener-error reporting
+                        // must never crash the hook.
+                    }
+                }
+            }
+        }
+        // 3. Propagate chain failure to the caller of `.run()`. Listeners have
+        //    already observed it via ctx.error; this is the actionable signal
+        //    for whatever called the hook.
+        if (chainError !== undefined) {
+            throw chainError;
+        }
+        return ctx;
+    }
+}
+//# sourceMappingURL=hook.js.map

package/dist/hook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook.js","sourceRoot":"","sources":["../src/hook.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @nwire/hooks — the universal dispatch primitive
+ *
+ * One `hook()` accepts BOTH `.use()` (chain) and `.on()` (parallel listener)
+ * attachments. Chain runs first (sequential, can short-circuit), then listeners
+ * fire in parallel via Promise.allSettled. See architecture-sketch.html §06–§07.
+ */
+export { hook, type Hook } from "./hook.js";
+export { createHooks, type Host, type HookMap, type Plugin, type PluginEntry } from "./create-hooks.js";
+export { compose } from "./compose.js";
+export { pipe, withTimeout, withRetry } from "./pipe.js";
+export type { ChainFn, HookOptions, ListenerFn, RetryOpts } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,IAAI,EAAE,KAAK,IAAI,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,KAAK,IAAI,EAAE,KAAK,OAAO,EAAE,KAAK,MAAM,EAAE,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AACrG,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACtD,YAAY,EAAE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,12 @@
+/**
+ * @nwire/hooks — the universal dispatch primitive
+ *
+ * One `hook()` accepts BOTH `.use()` (chain) and `.on()` (parallel listener)
+ * attachments. Chain runs first (sequential, can short-circuit), then listeners
+ * fire in parallel via Promise.allSettled. See architecture-sketch.html §06–§07.
+ */
+export { hook } from "./hook.js";
+export { createHooks } from "./create-hooks.js";
+export { compose } from "./compose.js";
+export { pipe, withTimeout, withRetry } from "./pipe.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,IAAI,EAAa,MAAM,QAAQ,CAAC;AACzC,OAAO,EAAE,WAAW,EAA0D,MAAM,gBAAgB,CAAC;AACrG,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC"}

package/dist/pipe.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Composition helpers for chain functions.
+ *
+ * `pipe(...fns)`         — compose multiple chain fns into one, koa-compose style.
+ * `withTimeout(ms, fn)`  — wrap a chain fn so it rejects if it takes too long.
+ * `withRetry(opts, fn)`  — wrap a chain fn so failures retry per the policy.
+ *
+ * These return `ChainFn<Ctx>` so they slot into `.use()` directly.
+ *
+ * See architecture-sketch.html §06.
+ */
+import type { ChainFn, RetryOpts } from "./types.js";
+/** Compose multiple chain fns into one. Insertion order. */
+export declare function pipe<Ctx>(...fns: ChainFn<Ctx>[]): ChainFn<Ctx>;
+/**
+ * Wrap a chain fn so it rejects with `Error("hook timeout: <ms>ms")` if it
+ * doesn't resolve in time. The downstream fn keeps running — there is no
+ * cancellation in JS — but the chain moves on.
+ */
+export declare function withTimeout<Ctx>(ms: number, fn: ChainFn<Ctx>): ChainFn<Ctx>;
+/**
+ * Wrap a chain fn so it retries on rejection per the policy. `next()` may
+ * be invoked more than once across retries — that's intentional; users
+ * who want next-only-once semantics should keep `next()` outside the
+ * retried fn (compose around it).
+ */
+export declare function withRetry<Ctx>(opts: RetryOpts, fn: ChainFn<Ctx>): ChainFn<Ctx>;
+//# sourceMappingURL=pipe.d.ts.map

package/dist/pipe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipe.d.ts","sourceRoot":"","sources":["../src/pipe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAElD,4DAA4D;AAC5D,wBAAgB,IAAI,CAAC,GAAG,EAAE,GAAG,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,CAE9D;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAiB3E;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,OAAO,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CA0B9E"}

package/dist/pipe.js

@@ -0,0 +1,75 @@
+/**
+ * Composition helpers for chain functions.
+ *
+ * `pipe(...fns)`         — compose multiple chain fns into one, koa-compose style.
+ * `withTimeout(ms, fn)`  — wrap a chain fn so it rejects if it takes too long.
+ * `withRetry(opts, fn)`  — wrap a chain fn so failures retry per the policy.
+ *
+ * These return `ChainFn<Ctx>` so they slot into `.use()` directly.
+ *
+ * See architecture-sketch.html §06.
+ */
+import { compose } from "./compose.js";
+/** Compose multiple chain fns into one. Insertion order. */
+export function pipe(...fns) {
+    return compose(fns);
+}
+/**
+ * Wrap a chain fn so it rejects with `Error("hook timeout: <ms>ms")` if it
+ * doesn't resolve in time. The downstream fn keeps running — there is no
+ * cancellation in JS — but the chain moves on.
+ */
+export function withTimeout(ms, fn) {
+    if (!Number.isFinite(ms) || ms < 0) {
+        throw new RangeError(`withTimeout: ms must be a non-negative finite number, got ${ms}`);
+    }
+    return async function timed(ctx, next) {
+        let timer;
+        try {
+            await Promise.race([
+                Promise.resolve(fn(ctx, next)),
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new Error(`hook timeout: ${ms}ms`)), ms);
+                }),
+            ]);
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+    };
+}
+/**
+ * Wrap a chain fn so it retries on rejection per the policy. `next()` may
+ * be invoked more than once across retries — that's intentional; users
+ * who want next-only-once semantics should keep `next()` outside the
+ * retried fn (compose around it).
+ */
+export function withRetry(opts, fn) {
+    if (!Number.isInteger(opts.attempts) || opts.attempts < 1) {
+        throw new RangeError(`withRetry: attempts must be a positive integer, got ${opts.attempts}`);
+    }
+    const delayMs = opts.delayMs ?? 0;
+    const shouldRetry = opts.shouldRetry ?? (() => true);
+    return async function retried(ctx, next) {
+        let lastErr;
+        for (let attempt = 1; attempt <= opts.attempts; attempt++) {
+            try {
+                await fn(ctx, next);
+                return;
+            }
+            catch (err) {
+                lastErr = err;
+                if (attempt >= opts.attempts || !shouldRetry(err, attempt)) {
+                    throw err;
+                }
+                if (delayMs > 0) {
+                    await new Promise((resolve) => setTimeout(resolve, delayMs));
+                }
+            }
+        }
+        // Unreachable — we either returned or threw above.
+        throw lastErr;
+    };
+}
+//# sourceMappingURL=pipe.js.map

package/dist/pipe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipe.js","sourceRoot":"","sources":["../src/pipe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpC,4DAA4D;AAC5D,MAAM,UAAU,IAAI,CAAM,GAAG,GAAmB;IAC9C,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC;AACtB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAM,EAAU,EAAE,EAAgB;IAC3D,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,UAAU,CAAC,6DAA6D,EAAE,EAAE,CAAC,CAAC;IAC1F,CAAC;IACD,OAAO,KAAK,UAAU,KAAK,CAAC,GAAG,EAAE,IAAI;QACnC,IAAI,KAAgD,CAAC;QACrD,IAAI,CAAC;YACH,MAAM,OAAO,CAAC,IAAI,CAAC;gBACjB,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;gBAC9B,IAAI,OAAO,CAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE;oBAC/B,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,iBAAiB,EAAE,IAAI,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBAC3E,CAAC,CAAC;aACH,CAAC,CAAC;QACL,CAAC;gBAAS,CAAC;YACT,IAAI,KAAK,KAAK,SAAS;gBAAE,YAAY,CAAC,KAAK,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAM,IAAe,EAAE,EAAgB;IAC9D,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,GAAG,CAAC,EAAE,CAAC;QAC1D,MAAM,IAAI,UAAU,CAAC,uDAAuD,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC/F,CAAC;IACD,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC;IAClC,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;IAErD,OAAO,KAAK,UAAU,OAAO,CAAC,GAAG,EAAE,IAAI;QACrC,IAAI,OAAgB,CAAC;QACrB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,IAAI,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,CAAC;YAC1D,IAAI,CAAC;gBACH,MAAM,EAAE,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;gBACpB,OAAO;YACT,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO,GAAG,GAAG,CAAC;gBACd,IAAI,OAAO,IAAI,IAAI,CAAC,QAAQ,IAAI,CAAC,WAAW,CAAC,GAAG,EAAE,OAAO,CAAC,EAAE,CAAC;oBAC3D,MAAM,GAAG,CAAC;gBACZ,CAAC;gBACD,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;oBAChB,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;gBAC/D,CAAC;YACH,CAAC;QACH,CAAC;QACD,mDAAmD;QACnD,MAAM,OAAO,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Public types for `@nwire/hooks`. See architecture-sketch.html §06–§07.
+ */
+/** A single link in a chain — koa-compose-shaped middleware. */
+export type ChainFn<Ctx> = (ctx: Ctx, next: () => Promise<void>) => Promise<void> | void;
+/** A listener — observes the final ctx state, never mutates it. */
+export type ListenerFn<Ctx> = (ctx: Readonly<Ctx>) => Promise<void> | void;
+/** Options for {@link createHook}/{@link hook}. */
+export interface HookOptions<Ctx> {
+    /**
+     * If true, listener errors are re-thrown by `.run()` instead of being
+     * collected and surfaced via `onListenerError`. Default: false (conservative).
+     */
+    strictListeners?: boolean;
+    /**
+     * Called once per listener error. Defaults to `console.error`. A host
+     * (e.g. `createHooks(...)`) wires its `lifecycle.error` hook here.
+     */
+    onListenerError?: (err: unknown, ctx: Readonly<Ctx>, hookName: string) => void;
+}
+/** Retry policy for {@link withRetry}. */
+export interface RetryOpts {
+    /** Total attempts (including the first). Must be >= 1. */
+    attempts: number;
+    /** Optional delay between attempts in ms (constant). Default: 0. */
+    delayMs?: number;
+    /** Optional predicate — return false to stop retrying a given error. */
+    shouldRetry?: (err: unknown, attempt: number) => boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,gEAAgE;AAChE,MAAM,MAAM,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAEzF,mEAAmE;AACnE,MAAM,MAAM,UAAU,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,GAAG,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAE3E,mDAAmD;AACnD,MAAM,WAAW,WAAW,CAAC,GAAG;IAC9B;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;OAGG;IACH,eAAe,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;CAChF;AAED,0CAA0C;AAC1C,MAAM,WAAW,SAAS;IACxB,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;CAC1D"}

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * Public types for `@nwire/hooks`. See architecture-sketch.html §06–§07.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@nwire/hooks",
+  "version": "0.7.0",
+  "description": "Nwire — the universal dispatch primitive. One hook() accepts both .use() (sequential koa-compose chain) and .on() (parallel listener) attachments. Built on emittery + a ~30 LOC composer. Standalone, in-process only, ~100 LOC of surface.",
+  "keywords": [
+    "dispatch",
+    "events",
+    "hooks",
+    "koa-compose",
+    "lifecycle",
+    "middleware",
+    "nwire"
+  ],
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "emittery": "1.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.9",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsc && node ../../scripts/fix-dist-extensions.mjs dist",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}