@vielzeug/herald 1.0.6 → 2.0.0

package/README.md

@@ -30,54 +30,25 @@ yarn add @vielzeug/herald
 ## Quick Start
 
 ```ts
-import { BusDisposedError, createBus, pipeEvents } from '@vielzeug/herald';
+import { createBus, pipeEvents } from '@vielzeug/herald';
 
-type AppEvents = {
-  'user:login': { userId: string; email: string };
+interface AppEvents {
+  'user:login': { email: string; userId: string };
   'user:logout': void;
-};
+}
 
 const bus = createBus<AppEvents>();
+const auditBus = createBus<AppEvents>();
+const stop = bus.on('user:login', ({ userId }) => console.log('Logged in:', userId));
+const stopPipe = pipeEvents(bus, auditBus, ['user:login', 'user:logout']);
 
-// Subscribe
-bus.on('user:login', ({ userId }) => {
-  console.log('Logged in:', userId);
-});
-
-// Emit
 bus.emit('user:login', { email: 'alice@example.com', userId: '42' });
 bus.emit('user:logout');
 
-// Await the next event
-const nextLogin = await bus.wait('user:login');
-
-// Race multiple events — result is a discriminated union
-const nextSessionEvent = await bus.waitAny(['user:login', 'user:logout'] as const);
-if (nextSessionEvent.event === 'user:login') {
-  console.log(nextSessionEvent.payload.userId);
-}
-
-// Stream all future emits as an async generator
-for await (const payload of bus.events('user:login', { signal: AbortSignal.timeout(5_000) })) {
-  console.log(payload.email);
-}
-
-// Forward selected events from one bus to another
-const auditBus = createBus<AppEvents>();
-const unpipe = pipeEvents(bus, auditBus, ['user:login', 'user:logout']);
-// unpipe() — stop forwarding; also stops automatically when either bus disposes
-
-// Disposal signal — fire external cleanup when the bus is torn down
-otherBus.on('count', handler, { signal: bus.disposalSignal });
-
-// Handle disposal in async code
-try {
-  await bus.wait('user:login', { signal: AbortSignal.timeout(1_000) });
-} catch (err) {
-  if (err instanceof BusDisposedError) {
-    console.log('Bus was disposed');
-  }
-}
+stopPipe();
+stop();
+bus.dispose();
+auditBus.dispose();
 ```
 
 ## Documentation
@@ -86,6 +57,7 @@ try {
 - [Usage Guide](https://vielzeug.dev/herald/usage)
 - [API Reference](https://vielzeug.dev/herald/api)
 - [Examples](https://vielzeug.dev/herald/examples)
+- [Migration Guide](https://vielzeug.dev/herald/migration)
 
 ## License
 

package/dist/bus.cjs

@@ -1,2 +1,2 @@
-const e=require("./_safe.cjs");require("./_dev.cjs");const t=require("./errors.cjs");var n=()=>{};function r(e,t){if(e.aborted)return e;if(t.aborted)return t;let n=new AbortController,r=()=>n.abort(e.reason),i=()=>n.abort(t.reason);return e.addEventListener(`abort`,r,{once:!0}),t.addEventListener(`abort`,i,{once:!0}),n.signal.addEventListener(`abort`,()=>{e.removeEventListener(`abort`,r),t.removeEventListener(`abort`,i)},{once:!0}),n.signal}function i(e,...t){return t.length===0?e:t.reduce(r,e)}function a(e,t){return Object.assign(e,{[Symbol.asyncDispose]:t})}function o(r){let o=new Map,s=new Set,c=new AbortController,l=r?.name,u=r?.maxListeners,d=r?.logger?.debug,f=d&&l?e=>d(`${e} (${l})`):d;r?.logger;let p=r?.logger?.warn,m=l?` (${l})`:``;function h(e){p&&p(e)}function g(e){return e?i(c.signal,e):c.signal}function _(t,n,i,a){let o=r?.onError?e=>r.onError({err:e,event:n,payload:i,timestamp:a}):void 0;return e.callSafely(t,o)}function v(e,t,r,{offLog:i,onLog:a,onRemove:o}){if(r.aborted)return n;let s=!1;function c(){s||(s=!0,e.delete(l),o?.(),r.removeEventListener(`abort`,c),f?.(`[herald:sub] ${i} — ${e.size} listener(s) remaining`))}let l=t(c);return e.add(l),r.addEventListener(`abort`,c,{once:!0}),f?.(`[herald:sub] ${a} — ${e.size} listener(s)`),u!==void 0&&e.size>u&&h(`${a} has ${e.size} listeners, exceeding maxListeners (${u}). Possible memory leak.${m}`),c}function y(e,t,n){let r=o.get(e);r||(r=new Set,o.set(e,r));let i=r;return v(i,e=>({fn:t,unsub:e}),n,{offLog:`off("${e}")`,onLog:`on("${e}")`,onRemove:()=>{i.size===0&&o.delete(e)}})}function b(e,t){return v(s,t=>({fn:e,unsub:t}),t,{offLog:`onAny off`,onLog:`onAny`})}function x(e,t,r){let i={unsub:n};return i.unsub=y(e,e=>{i.unsub(),t(e)},r),i.unsub}function S(e,t){let r={unsub:n};return r.unsub=b((t,n)=>{r.unsub(),e(t,n)},t),r.unsub}function C(e,t,n){let r=g(n?.signal);return n?.once?x(e,t,r):y(e,t,r)}function w(e,t,n){return x(e,t,g(n?.signal))}function T(e,t){let n=g(t?.signal);return t?.once?S(e,n):b(e,n)}function E(e,t){let n=g(t?.signal);return n.aborted?Promise.reject(n.reason):new Promise((t,r)=>{function i(){r(n.reason)}x(e,e=>{n.removeEventListener(`abort`,i),t(e)},n),n.addEventListener(`abort`,i,{once:!0})})}function D(e,n){let r=n?.maxBuffer??1/0;if(!(r>0))throw new t.HeraldConfigError(`maxBuffer must be a positive number`);let i=g(n?.signal);if(i.aborted)return a((async function*(){})(),async()=>{});let o=[],s,c=y(e,e=>{o.length>=r&&o.shift(),o.push(e),s?.()},i);async function*l(){try{for(;!i.aborted;){if(o.length){yield o.shift();continue}let{promise:e,resolve:t}=Promise.withResolvers(),n=()=>{t()};s=t,i.addEventListener(`abort`,n,{once:!0}),await e,i.removeEventListener(`abort`,n),s=void 0}}finally{c()}}let u=l();return a(u,async()=>{c(),await u.return(void 0)})}function O(e,t,n){r?._onDispatch?.(e,t);let i=0,a,c=o.get(e);if(c?.size)for(let r of[...c]){let o=_(()=>r.fn(t),e,t,n);o.threw&&!a&&(a={err:o.err}),i++}if(s.size)for(let r of[...s]){let o=_(()=>r.fn(e,t),e,t,n);o.threw&&!a&&(a={err:o.err}),i++}if(a)throw a.err;return i}function k(e,...t){if(c.signal.aborted)return 0;let n=t[0],i=Date.now();if(r?.validatePayload)try{r.validatePayload(e,n)}catch(t){if(r?.onError)return r.onError({err:t,event:e,payload:n,timestamp:i}),0;throw t}if(f){let t=o.get(e)?.size??0,n=s.size;f(`[herald:emit] emit("${e}") — ${t+n} listener(s) (${t} specific, ${n} wildcard)`)}let a=r?.middleware;if(a?.length){let t=0,r=0;function l(){let o=r++;o<a.length?a[o](e,n,l):o===a.length&&(t=O(e,n,i))}return l(),t}return O(e,n,i)}function A(e){if(e!==void 0)return o.get(e)?.size??0;let t=0;for(let e of o.values())t+=e.size;return t}function j(){return s.size}function M(){return[...o.keys()]}function N(e,n){if(e.length<2)throw new t.HeraldConfigError(`waitAny() requires at least 2 event keys`);let r=g(n?.signal);return r.aborted?Promise.reject(r.reason):new Promise((t,n)=>{let a=new AbortController,o=i(r,a.signal);function s(){a.abort(),n(r.reason)}r.addEventListener(`abort`,s,{once:!0});for(let n of e)x(n,e=>{r.removeEventListener(`abort`,s),a.abort(),t({event:n,payload:e})},o)})}function P(){c.signal.aborted||(f?.(`[herald:lifecycle] dispose()`),c.abort(new t.BusDisposedError(l)),o.clear(),s.clear())}return{get disposalSignal(){return c.signal},dispose:P,get disposed(){return c.signal.aborted},emit:k,eventNames:M,events:D,listenerCount:A,on:C,onAny:T,once:w,[Symbol.dispose]:P,wait:E,waitAny:N,wildcardCount:j}}exports.combineSignals=i,exports.createBus=o,exports.noop=n;
+require("./_dev.cjs");const e=require("./_safe.cjs"),t=require("./errors.cjs");var n=()=>{};function r(...e){let t=e.filter(e=>e!==void 0);if(t.length===1)return{dispose:n,signal:t[0]};let r=t.find(e=>e.aborted);if(r)return{dispose:n,signal:r};let i=new AbortController,a=new Map,o=!1;function s(){if(!o){o=!0;for(let[e,t]of a)e.removeEventListener(`abort`,t);a.clear()}}for(let e of t){let t=()=>{i.abort(e.reason),s()};a.set(e,t),e.addEventListener(`abort`,t,{once:!0})}return{dispose:s,signal:i.signal}}function i(e,...t){return r(e,...t).signal}function a(e,t){return Object.assign(e,{[Symbol.asyncDispose]:t})}function o(i){let o=new Map,s=new Set,c=new AbortController,l=i?.name,u=i?.maxListeners,d=i?.logger?.debug,f=d&&l?e=>d(`${e} (${l})`):d;i?.logger;let p=i?.logger?.warn,m=l?` (${l})`:``;function h(e){p&&p(e)}function g(e){return e?r(c.signal,e):{dispose:n,signal:c.signal}}function _(t,n,r,a){let o=i?.onError?e=>i.onError({err:e,event:n,payload:r,timestamp:a}):void 0;return e.callSafely(t,o)}function v(e,t,r,{offLog:i,onLog:a,onRemove:o}){if(r.aborted)return n;let s=!1;function c(){s||(s=!0,e.delete(l),o?.(),r.removeEventListener(`abort`,c),f?.(`[herald:sub] ${i} — ${e.size} listener(s) remaining`))}let l=t(c);return e.add(l),r.addEventListener(`abort`,c,{once:!0}),f?.(`[herald:sub] ${a} — ${e.size} listener(s)`),u!==void 0&&e.size>u&&h(`${a} has ${e.size} listeners, exceeding maxListeners (${u}). Possible memory leak.${m}`),c}function y(e,t,n,r){let i=o.get(e);i||(i=new Set,o.set(e,i));let a=i;return v(a,e=>({fn:t,unsub:e}),n,{offLog:`off("${e}")`,onLog:`on("${e}")`,onRemove:()=>{a.size===0&&o.delete(e),r?.()}})}function b(e,t,n){return v(s,t=>({fn:e,unsub:t}),t,{offLog:`onAny off`,onLog:`onAny`,onRemove:n})}function x(e,t,r,i){let a={unsub:n};return a.unsub=y(e,e=>{a.unsub(),t(e)},r,i),a.unsub}function S(e,t,r){let i={unsub:n};return i.unsub=b((t,n)=>{i.unsub(),e(t,n)},t,r),i.unsub}function C(e,t,n){let r=g(n?.signal);return n?.once?x(e,t,r.signal,r.dispose):y(e,t,r.signal,r.dispose)}function w(e,t,n){let r=g(n?.signal);return x(e,t,r.signal,r.dispose)}function T(e,t){let n=g(t?.signal);return t?.once?S(e,n.signal,n.dispose):b(e,n.signal,n.dispose)}function E(e,t){let n=g(t?.signal);return n.signal.aborted?Promise.reject(n.signal.reason):new Promise((t,r)=>{let i=()=>{n.dispose(),r(n.signal.reason)};x(e,e=>{n.signal.removeEventListener(`abort`,i),n.dispose(),t(e)},n.signal),n.signal.addEventListener(`abort`,i,{once:!0})})}function D(e,n){let r=n?.maxBuffer??1/0;if(!(r>0))throw new t.HeraldConfigError(`maxBuffer must be a positive number`);let i=g(n?.signal),o=i.signal;if(o.aborted)return a((async function*(){})(),async()=>{});let s=[],c,l=y(e,e=>{s.length>=r&&s.shift(),s.push(e),c?.()},o,i.dispose);async function*u(){try{for(;!o.aborted;){if(s.length){yield s.shift();continue}let{promise:e,resolve:t}=Promise.withResolvers(),n=()=>{t()};c=t,o.addEventListener(`abort`,n,{once:!0}),await e,o.removeEventListener(`abort`,n),c=void 0}}finally{l()}}let d=u();return a(d,async()=>{l(),await d.return(void 0)})}function O(e,t,n){i?._onDispatch?.(e,t);let r=0,a,c=o.get(e);if(c?.size)for(let i of[...c]){let o=_(()=>i.fn(t),e,t,n);o.threw&&!a&&(a={err:o.err}),r++}if(s.size)for(let i of[...s]){let o=_(()=>i.fn(e,t),e,t,n);o.threw&&!a&&(a={err:o.err}),r++}if(a)throw a.err;return r}function k(e,...t){if(c.signal.aborted)return 0;let n=t[0],r=Date.now();if(i?.validatePayload)try{i.validatePayload(e,n)}catch(t){if(i?.onError)return i.onError({err:t,event:e,payload:n,timestamp:r}),0;throw t}if(f){let t=o.get(e)?.size??0,n=s.size;f(`[herald:emit] emit("${e}") — ${t+n} listener(s) (${t} specific, ${n} wildcard)`)}let a=i?.middleware;if(!a?.length)return O(e,n,r);let l=a;function u(t){let i=l[t];if(!i)return O(e,n,r);let a=0,o=!1,s=!0;return i(e,n,()=>{!s||o||(o=!0,a=u(t+1))}),s=!1,a}return u(0)}function A(e){if(e!==void 0)return o.get(e)?.size??0;let t=0;for(let e of o.values())t+=e.size;return t}function j(){return s.size}function M(){return[...o.keys()]}function N(e,n){if(e.length<2)throw new t.HeraldConfigError(`waitAny() requires at least 2 event keys`);let i=g(n?.signal);return i.signal.aborted?Promise.reject(i.signal.reason):new Promise((t,n)=>{let a=new AbortController,o=r(i.signal,a.signal),s=[],c=!1;function l(){i.signal.removeEventListener(`abort`,u),a.abort(),o.dispose(),i.dispose();for(let e of s)e()}function u(){c||(c=!0,l(),n(i.signal.reason))}i.signal.addEventListener(`abort`,u,{once:!0});for(let n of e)s.push(x(n,e=>{c||(c=!0,l(),t({event:n,payload:e}))},o.signal))})}function P(){c.signal.aborted||(f?.(`[herald:lifecycle] dispose()`),c.abort(new t.BusDisposedError(l)),o.clear(),s.clear())}return{get disposalSignal(){return c.signal},dispose:P,get disposed(){return c.signal.aborted},emit:k,eventNames:M,events:D,listenerCount:A,on:C,onAny:T,once:w,[Symbol.dispose]:P,wait:E,waitAny:N,wildcardCount:j}}exports.combineSignals=i,exports.createBus=o,exports.createSignalScope=r,exports.noop=n;
 //# sourceMappingURL=bus.cjs.map

package/dist/bus.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"bus.cjs","names":[],"sources":["../src/bus.ts"],"sourcesContent":["import type {\n  Bus,\n  BusOptions,\n  EmissionErrorContext,\n  EventKey,\n  EventMap,\n  EventStream,\n  Listener,\n  SubscribeOptions,\n  Unsubscribe,\n  WaitAnyResult,\n} from './types';\n\nimport { warn as _internalWarn } from './_dev';\nimport { type SafeCallResult, callSafely } from './_safe';\nimport { BusDisposedError, HeraldConfigError } from './errors';\n\n// Module-scoped noop — shared across all bus instances to avoid per-bus allocation.\n// @internal — exported only for sibling internal modules; stripped from public declarations via stripInternal.\n/** @internal */\nexport const noop = () => {};\n\n/** @internal */\nfunction mergeTwo(a: AbortSignal, b: AbortSignal): AbortSignal {\n  if (a.aborted) return a;\n\n  if (b.aborted) return b;\n\n  const ctrl = new AbortController();\n  const onA = (): void => ctrl.abort(a.reason);\n  const onB = (): void => ctrl.abort(b.reason);\n\n  a.addEventListener('abort', onA, { once: true });\n  b.addEventListener('abort', onB, { once: true });\n  ctrl.signal.addEventListener(\n    'abort',\n    () => {\n      a.removeEventListener('abort', onA);\n      b.removeEventListener('abort', onB);\n    },\n    { once: true },\n  );\n\n  return ctrl.signal;\n}\n\n/**\n * Returns a signal that aborts as soon as any of the provided signals abort.\n * With a single argument, returns it directly (no allocation).\n * Registers and cleans up its own event listeners — no leaks when no signal fires.\n *\n * @example\n * const signal = combineSignals(timeoutSignal, bus.disposalSignal);\n * bus.on('event', handler, { signal });\n *\n * @example\n * // Three signals — no nesting required\n * const signal = combineSignals(userSignal, timeoutSignal, bus.disposalSignal);\n */\nexport function combineSignals(first: AbortSignal, ...rest: AbortSignal[]): AbortSignal {\n  if (rest.length === 0) return first;\n\n  return rest.reduce(mergeTwo, first);\n}\n\n// Each registration gets a unique Entry object, allowing the same listener function\n// to be registered multiple times independently (aligns with Node EventEmitter / mitt).\ntype Entry = { fn: Listener<unknown>; unsub: () => void };\ntype WildcardEntry = { fn: (event: string, payload: unknown) => void; unsub: () => void };\n\ntype RegisterEntryOpts = { offLog: string; onLog: string; onRemove?: () => void };\n\n// makeEventStream wraps an AsyncGenerator with AsyncDisposable.\nfunction makeEventStream<V>(gen: AsyncGenerator<V>, onDispose: () => Promise<void>): EventStream<V> {\n  return Object.assign(gen, {\n    [Symbol.asyncDispose]: onDispose,\n  }) as unknown as EventStream<V>;\n}\n\n/** @internal */\nexport type InternalBusOptions<T extends EventMap> = BusOptions<T> & {\n  /** @internal Called after middleware passes, before listeners run. Used by BehaviorBus. */\n  _onDispatch?: (event: EventKey<T>, payload: unknown) => void;\n};\n\nexport function createBus<T extends EventMap>(options?: InternalBusOptions<T>): Bus<T> {\n  // Per-event set of Entry objects. Set identity prevents accidental dedup of entries;\n  // the same fn can appear in multiple entries with independent lifetimes.\n  const listeners = new Map<string, Set<Entry>>();\n  const wildcards = new Set<WildcardEntry>();\n  const disposeController = new AbortController();\n  const busName = options?.name;\n  const maxListeners = options?.maxListeners;\n  const rawDebug = options?.logger?.debug;\n  const logDebug = rawDebug && busName ? (msg: string) => rawDebug(`${msg} (${busName})`) : rawDebug;\n  const hasLogger = options?.logger !== undefined;\n  const customLogWarn = options?.logger?.warn;\n  const busTag = busName ? ` (${busName})` : '';\n\n  function doWarn(msg: string): void {\n    if (customLogWarn) {\n      customLogWarn(msg);\n    } else if (!hasLogger) {\n      _internalWarn(msg);\n    }\n  }\n\n  function mergeSignal(signal?: AbortSignal): AbortSignal {\n    return signal ? combineSignals(disposeController.signal, signal) : disposeController.signal;\n  }\n\n  // callSafe is defined once per bus (not per emit) — avoids re-allocating on every emission.\n  // Captures options.onError via closure. Used in emit() for both specific and wildcard loops.\n  // Does not rethrow directly — see dispatch(), which continues the broadcast to every remaining\n  // listener (including wildcards) before rethrowing the first captured error, if any.\n  function callSafe(fn: () => void, event: EventKey<T>, payload: unknown, timestamp: number): SafeCallResult {\n    const onError = options?.onError\n      ? (err: unknown) => options.onError!({ err, event, payload, timestamp } as EmissionErrorContext<T>)\n      : undefined;\n\n    return callSafely(fn, onError);\n  }\n\n  // registerEntry opts object — self-documenting call sites.\n  function registerEntry<E extends { unsub: () => void }>(\n    container: Set<E>,\n    makeEntry: (unsub: () => void) => E,\n    signal: AbortSignal,\n    { offLog, onLog, onRemove }: RegisterEntryOpts,\n  ): () => void {\n    if (signal.aborted) return noop;\n\n    // Boolean guard makes unsub idempotent — a second call after re-registration would\n    // otherwise see an empty container and incorrectly delete the outer map entry.\n    let called = false;\n\n    function unsub() {\n      if (called) return;\n\n      called = true;\n      container.delete(entry);\n      onRemove?.();\n      signal.removeEventListener('abort', unsub);\n\n      logDebug?.(`[herald:sub] ${offLog} — ${container.size} listener(s) remaining`);\n    }\n\n    // Function declaration is hoisted so `entry` can reference `unsub` directly.\n    const entry = makeEntry(unsub);\n\n    container.add(entry);\n    signal.addEventListener('abort', unsub, { once: true });\n\n    logDebug?.(`[herald:sub] ${onLog} — ${container.size} listener(s)`);\n\n    if (maxListeners !== undefined && container.size > maxListeners) {\n      doWarn(\n        `${onLog} has ${container.size} listeners, exceeding maxListeners (${maxListeners}). Possible memory leak.${busTag}`,\n      );\n    }\n\n    return unsub;\n  }\n\n  function onWithSignal<K extends EventKey<T>>(event: K, listener: Listener<T[K]>, signal: AbortSignal): () => void {\n    let set = listeners.get(event);\n\n    if (!set) {\n      set = new Set();\n      listeners.set(event, set);\n    }\n\n    // Capture the set reference so unsub can safely delete from it even after\n    // the event key has been removed from the outer map.\n    const capturedSet = set;\n\n    return registerEntry(capturedSet, (unsub) => ({ fn: listener as Listener<unknown>, unsub }), signal, {\n      offLog: `off(\"${event}\")`,\n      onLog: `on(\"${event}\")`,\n      onRemove: () => {\n        if (capturedSet.size === 0) listeners.delete(event);\n      },\n    });\n  }\n\n  function onAnyWithSignal(listener: (event: EventKey<T>, payload: unknown) => void, signal: AbortSignal): () => void {\n    return registerEntry(\n      wildcards,\n      (unsub) => ({ fn: listener as (event: string, payload: unknown) => void, unsub }),\n      signal,\n      { offLog: 'onAny off', onLog: 'onAny' },\n    );\n  }\n\n  // Use a const ref object to hold the unsub handle — avoids the forward-reference that\n  // TypeScript cannot prove safe with `const unsub = f(() => unsub)`. The `ref` binding never\n  // changes (only its property is mutated), satisfying prefer-const. By the time the inner\n  // callback fires (only possible after onWithSignal returns), ref.unsub is the real handle.\n  function onceWithSignal<K extends EventKey<T>>(event: K, listener: Listener<T[K]>, signal: AbortSignal): () => void {\n    const ref = { unsub: noop as Unsubscribe };\n\n    ref.unsub = onWithSignal(\n      event,\n      (payload) => {\n        ref.unsub();\n        listener(payload);\n      },\n      signal,\n    );\n\n    return ref.unsub;\n  }\n\n  // onAny with once — fires the wildcard listener exactly once, then auto-removes.\n  function onAnyWithOnce(listener: (event: EventKey<T>, payload: unknown) => void, signal: AbortSignal): () => void {\n    const ref = { unsub: noop as Unsubscribe };\n\n    ref.unsub = onAnyWithSignal((event, payload) => {\n      ref.unsub();\n      listener(event, payload);\n    }, signal);\n\n    return ref.unsub;\n  }\n\n  function on<K extends EventKey<T>>(event: K, listener: Listener<T[K]>, opts?: SubscribeOptions): () => void {\n    const signal = mergeSignal(opts?.signal);\n\n    if (opts?.once) return onceWithSignal(event, listener, signal);\n\n    return onWithSignal(event, listener, signal);\n  }\n\n  // once() and onAny() take an options object — consistent with on(), extensible for future options.\n  function once<K extends EventKey<T>>(\n    event: K,\n    listener: Listener<T[K]>,\n    opts?: { signal?: AbortSignal },\n  ): () => void {\n    return onceWithSignal(event, listener, mergeSignal(opts?.signal));\n  }\n\n  function onAny(listener: (event: EventKey<T>, payload: unknown) => void, opts?: SubscribeOptions): () => void {\n    const signal = mergeSignal(opts?.signal);\n\n    if (opts?.once) return onAnyWithOnce(listener, signal);\n\n    return onAnyWithSignal(listener, signal);\n  }\n\n  function wait<K extends EventKey<T>>(event: K, opts?: { signal?: AbortSignal }): Promise<T[K]> {\n    const activeSignal = mergeSignal(opts?.signal);\n\n    if (activeSignal.aborted) return Promise.reject(activeSignal.reason);\n\n    return new Promise<T[K]>((resolve, reject) => {\n      function onAbort() {\n        reject(activeSignal.reason);\n      }\n\n      onceWithSignal(\n        event,\n        (payload) => {\n          activeSignal.removeEventListener('abort', onAbort);\n          resolve(payload);\n        },\n        activeSignal,\n      );\n\n      activeSignal.addEventListener('abort', onAbort, { once: true });\n    });\n  }\n\n  // events() subscribes eagerly — the listener is registered when events() is called, not when\n  // the first .next() runs. This ensures events emitted before iteration begins are buffered.\n  // maxBuffer is validated synchronously so callers get a RangeError at call time.\n  function events<K extends EventKey<T>>(\n    event: K,\n    opts?: { maxBuffer?: number; signal?: AbortSignal },\n  ): EventStream<T[K]> {\n    const maxBuffer = opts?.maxBuffer ?? Infinity;\n\n    if (!(maxBuffer > 0)) throw new HeraldConfigError('maxBuffer must be a positive number');\n\n    const activeSignal = mergeSignal(opts?.signal);\n\n    if (activeSignal.aborted) {\n      const empty = (async function* (): AsyncGenerator<T[K]> {})();\n\n      return makeEventStream(empty, async (): Promise<void> => {});\n    }\n\n    const queue: T[K][] = [];\n    let wake: (() => void) | undefined;\n\n    const unsub = onWithSignal(\n      event,\n      (payload) => {\n        if (queue.length >= maxBuffer) queue.shift();\n\n        queue.push(payload);\n        wake?.();\n      },\n      activeSignal,\n    );\n\n    async function* generate(): AsyncGenerator<T[K]> {\n      try {\n        while (!activeSignal.aborted) {\n          if (queue.length) {\n            yield queue.shift()!;\n            continue;\n          }\n\n          const { promise, resolve } = Promise.withResolvers<void>();\n          const abortHandler = (): void => {\n            resolve();\n          };\n\n          wake = resolve;\n          activeSignal.addEventListener('abort', abortHandler, { once: true });\n          await promise;\n          activeSignal.removeEventListener('abort', abortHandler);\n          wake = undefined;\n        }\n      } finally {\n        unsub();\n      }\n    }\n\n    const gen = generate();\n\n    // Symbol.asyncDispose calls unsub() directly because gen.return() only runs the finally\n    // block when the generator has been started (at least one next() call). The unsub guard\n    // (called = false in registerEntry) makes this idempotent.\n    return makeEventStream(gen, async (): Promise<void> => {\n      unsub();\n      await gen.return(undefined as unknown as T[K]);\n    });\n  }\n\n  // dispatch is defined at createBus() scope (once per bus, not per emit call) — consistent with\n  // callSafe. Receives event/payload/timestamp as arguments so it can be invoked from both the\n  // direct path and the middleware chain without capturing per-emit locals in a closure.\n  function dispatch(event: EventKey<T>, payload: unknown, timestamp: number): number {\n    options?._onDispatch?.(event, payload);\n\n    let count = 0;\n    // Only the first unforwarded error is kept — every listener still runs (see callSafe's\n    // doc comment) — then it's rethrown once the whole broadcast (specific + wildcard) is done.\n    let firstError: { err: unknown } | undefined;\n    const set = listeners.get(event);\n\n    if (set?.size) {\n      for (const entry of [...set]) {\n        const result = callSafe(() => entry.fn(payload), event, payload, timestamp);\n\n        if (result.threw && !firstError) firstError = { err: result.err };\n\n        count++;\n      }\n    }\n\n    if (wildcards.size) {\n      for (const entry of [...wildcards]) {\n        const result = callSafe(() => entry.fn(event, payload), event, payload, timestamp);\n\n        if (result.threw && !firstError) firstError = { err: result.err };\n\n        count++;\n      }\n    }\n\n    if (firstError) throw firstError.err;\n\n    return count;\n  }\n\n  // emit() returns the number of listeners invoked (specific + wildcard).\n  // Returns 0 if bus is disposed, middleware blocked dispatch, or validatePayload rejected.\n  // validatePayload runs first, then middleware, then listeners.\n  function emit<K extends EventKey<T>>(event: K, ...args: T[K] extends void ? [] : [payload: T[K]]): number {\n    if (disposeController.signal.aborted) return 0;\n\n    const payload = (args as unknown[])[0];\n    const timestamp = Date.now();\n\n    if (options?.validatePayload) {\n      try {\n        options.validatePayload(event, payload as T[K]);\n      } catch (err) {\n        if (options?.onError) {\n          options.onError({ err, event, payload, timestamp } as EmissionErrorContext<T>);\n\n          return 0;\n        }\n\n        throw err;\n      }\n    }\n\n    if (logDebug) {\n      const specific = listeners.get(event)?.size ?? 0;\n      const wild = wildcards.size;\n\n      logDebug(\n        `[herald:emit] emit(\"${event}\") — ${specific + wild} listener(s) (${specific} specific, ${wild} wildcard)`,\n      );\n    }\n\n    // Middleware pipeline — each middleware calls next() to proceed.\n    const middleware = options?.middleware;\n\n    if (middleware?.length) {\n      let dispatched = 0;\n      let i = 0;\n\n      // Guard prevents a misbehaving middleware from calling next() twice and\n      // triggering a double-dispatch to listeners. Note: a middleware calling next()\n      // more than twice can still invoke downstream middleware multiple times.\n      function next(): void {\n        const idx = i++;\n\n        if (idx < middleware!.length) middleware![idx](event, payload, next);\n        else if (idx === middleware!.length) dispatched = dispatch(event, payload, timestamp);\n      }\n\n      next();\n\n      return dispatched;\n    }\n\n    return dispatch(event, payload, timestamp);\n  }\n\n  // listenerCount counts specific-event listeners only.\n  // wildcardCount() is the separate accessor for onAny listeners.\n  function listenerCount(event?: EventKey<T>): number {\n    if (event !== undefined) return listeners.get(event)?.size ?? 0;\n\n    let total = 0;\n\n    for (const set of listeners.values()) total += set.size;\n\n    return total;\n  }\n\n  function wildcardCount(): number {\n    return wildcards.size;\n  }\n\n  function eventNames(): EventKey<T>[] {\n    return [...listeners.keys()] as EventKey<T>[];\n  }\n\n  function waitAny<K extends readonly [EventKey<T>, EventKey<T>, ...EventKey<T>[]]>(\n    eventList: K,\n    opts?: { signal?: AbortSignal },\n  ): Promise<WaitAnyResult<T, K>> {\n    if (eventList.length < 2) throw new HeraldConfigError('waitAny() requires at least 2 event keys');\n\n    const activeSignal = mergeSignal(opts?.signal);\n\n    if (activeSignal.aborted) return Promise.reject(activeSignal.reason);\n\n    return new Promise<WaitAnyResult<T, K>>((resolve, reject) => {\n      const raceController = new AbortController();\n      const raceSignal = combineSignals(activeSignal, raceController.signal);\n\n      function onAbort() {\n        raceController.abort();\n        reject(activeSignal.reason);\n      }\n\n      activeSignal.addEventListener('abort', onAbort, { once: true });\n\n      for (const event of eventList) {\n        onceWithSignal(\n          event as EventKey<T>,\n          (payload) => {\n            activeSignal.removeEventListener('abort', onAbort);\n            raceController.abort();\n            resolve({ event, payload } as WaitAnyResult<T, K>);\n          },\n          raceSignal,\n        );\n      }\n    });\n  }\n\n  function dispose(): void {\n    if (disposeController.signal.aborted) return;\n\n    logDebug?.('[herald:lifecycle] dispose()');\n\n    disposeController.abort(new BusDisposedError(busName));\n    // disposeController.abort() fires all unsub handlers synchronously, which\n    // removes every entry and deletes empty keys. By here both maps are already\n    // empty. clear() is a cheap defensive measure against any future code path\n    // that bypasses the signal (e.g. a direct listeners.set() before a guard).\n    listeners.clear();\n    wildcards.clear();\n  }\n\n  return {\n    get disposalSignal() {\n      return disposeController.signal;\n    },\n    dispose,\n    get disposed() {\n      return disposeController.signal.aborted;\n    },\n    emit,\n    eventNames,\n    events,\n    listenerCount,\n    on,\n    onAny,\n    once,\n    [Symbol.dispose]: dispose,\n    wait,\n    waitAny,\n    wildcardCount,\n  };\n}\n"],"mappings":"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"}
+{"version":3,"file":"bus.cjs","names":[],"sources":["../src/bus.ts"],"sourcesContent":["import type {\n  Bus,\n  BusOptions,\n  EmissionErrorContext,\n  EventKey,\n  EventMap,\n  EventStream,\n  Listener,\n  SubscribeOptions,\n  Unsubscribe,\n  WaitAnyResult,\n} from './types';\n\nimport { warn as _internalWarn } from './_dev';\nimport { type SafeCallResult, callSafely } from './_safe';\nimport { BusDisposedError, HeraldConfigError } from './errors';\n\n// Module-scoped noop — shared across all bus instances to avoid per-bus allocation.\n// @internal — exported only for sibling internal modules; stripped from public declarations via stripInternal.\n/** @internal */\nexport const noop = () => {};\n\n/** @internal */\nexport type SignalScope = { dispose(): void; signal: AbortSignal };\n\n/** @internal */\nexport function createSignalScope(...candidates: Array<AbortSignal | undefined>): SignalScope {\n  const signals = candidates.filter((signal): signal is AbortSignal => signal !== undefined);\n\n  if (signals.length === 1) return { dispose: noop, signal: signals[0]! };\n\n  const aborted = signals.find((signal) => signal.aborted);\n\n  if (aborted) return { dispose: noop, signal: aborted };\n\n  const controller = new AbortController();\n  const listeners = new Map<AbortSignal, () => void>();\n  let disposed = false;\n\n  function dispose(): void {\n    if (disposed) return;\n\n    disposed = true;\n    for (const [signal, listener] of listeners) signal.removeEventListener('abort', listener);\n    listeners.clear();\n  }\n\n  for (const signal of signals) {\n    const listener = () => {\n      controller.abort(signal.reason);\n      dispose();\n    };\n\n    listeners.set(signal, listener);\n    signal.addEventListener('abort', listener, { once: true });\n  }\n\n  return { dispose, signal: controller.signal };\n}\n\n/**\n * Returns a signal that aborts as soon as any provided signal aborts.\n * Input listeners remain active until one input aborts; use signal-owning APIs for early cleanup.\n */\nexport function combineSignals(first: AbortSignal, ...rest: AbortSignal[]): AbortSignal {\n  return createSignalScope(first, ...rest).signal;\n}\n\n// Each registration gets a unique Entry object, allowing the same listener function\n// to be registered multiple times independently (aligns with Node EventEmitter / mitt).\ntype Entry = { fn: Listener<unknown>; unsub: () => void };\ntype WildcardEntry = { fn: (event: string, payload: unknown) => void; unsub: () => void };\n\ntype RegisterEntryOpts = { offLog: string; onLog: string; onRemove?: () => void };\n\n// makeEventStream wraps an AsyncGenerator with AsyncDisposable.\nfunction makeEventStream<V>(gen: AsyncGenerator<V>, onDispose: () => Promise<void>): EventStream<V> {\n  return Object.assign(gen, {\n    [Symbol.asyncDispose]: onDispose,\n  }) as unknown as EventStream<V>;\n}\n\n/** @internal */\nexport type InternalBusOptions<T extends EventMap> = BusOptions<T> & {\n  /** @internal Called after middleware passes, before listeners run. Used by TestBus. */\n  _onDispatch?: (event: EventKey<T>, payload: unknown) => void;\n};\n\nexport function createBus<T extends EventMap = Record<string, unknown>>(options?: InternalBusOptions<T>): Bus<T> {\n  // Per-event set of Entry objects. Set identity prevents accidental dedup of entries;\n  // the same fn can appear in multiple entries with independent lifetimes.\n  const listeners = new Map<string, Set<Entry>>();\n  const wildcards = new Set<WildcardEntry>();\n  const disposeController = new AbortController();\n  const busName = options?.name;\n  const maxListeners = options?.maxListeners;\n  const rawDebug = options?.logger?.debug;\n  const logDebug = rawDebug && busName ? (msg: string) => rawDebug(`${msg} (${busName})`) : rawDebug;\n  const hasLogger = options?.logger !== undefined;\n  const customLogWarn = options?.logger?.warn;\n  const busTag = busName ? ` (${busName})` : '';\n\n  function doWarn(msg: string): void {\n    if (customLogWarn) {\n      customLogWarn(msg);\n    } else if (!hasLogger) {\n      _internalWarn(msg);\n    }\n  }\n\n  function createSubscriptionScope(signal?: AbortSignal): SignalScope {\n    return signal\n      ? createSignalScope(disposeController.signal, signal)\n      : { dispose: noop, signal: disposeController.signal };\n  }\n\n  // callSafe is defined once per bus (not per emit) — avoids re-allocating on every emission.\n  // Captures options.onError via closure. Used in emit() for both specific and wildcard loops.\n  // Does not rethrow directly — see dispatch(), which continues the broadcast to every remaining\n  // listener (including wildcards) before rethrowing the first captured error, if any.\n  function callSafe(fn: () => void, event: EventKey<T>, payload: unknown, timestamp: number): SafeCallResult {\n    const onError = options?.onError\n      ? (err: unknown) => options.onError!({ err, event, payload, timestamp } as EmissionErrorContext<T>)\n      : undefined;\n\n    return callSafely(fn, onError);\n  }\n\n  // registerEntry opts object — self-documenting call sites.\n  function registerEntry<E extends { unsub: () => void }>(\n    container: Set<E>,\n    makeEntry: (unsub: () => void) => E,\n    signal: AbortSignal,\n    { offLog, onLog, onRemove }: RegisterEntryOpts,\n  ): () => void {\n    if (signal.aborted) return noop;\n\n    // Boolean guard makes unsub idempotent — a second call after re-registration would\n    // otherwise see an empty container and incorrectly delete the outer map entry.\n    let called = false;\n\n    function unsub() {\n      if (called) return;\n\n      called = true;\n      container.delete(entry);\n      onRemove?.();\n      signal.removeEventListener('abort', unsub);\n\n      logDebug?.(`[herald:sub] ${offLog} — ${container.size} listener(s) remaining`);\n    }\n\n    // Function declaration is hoisted so `entry` can reference `unsub` directly.\n    const entry = makeEntry(unsub);\n\n    container.add(entry);\n    signal.addEventListener('abort', unsub, { once: true });\n\n    logDebug?.(`[herald:sub] ${onLog} — ${container.size} listener(s)`);\n\n    if (maxListeners !== undefined && container.size > maxListeners) {\n      doWarn(\n        `${onLog} has ${container.size} listeners, exceeding maxListeners (${maxListeners}). Possible memory leak.${busTag}`,\n      );\n    }\n\n    return unsub;\n  }\n\n  function onWithSignal<K extends EventKey<T>>(\n    event: K,\n    listener: Listener<T[K]>,\n    signal: AbortSignal,\n    onRemove?: () => void,\n  ): () => void {\n    let set = listeners.get(event);\n\n    if (!set) {\n      set = new Set();\n      listeners.set(event, set);\n    }\n\n    // Capture the set reference so unsub can safely delete from it even after\n    // the event key has been removed from the outer map.\n    const capturedSet = set;\n\n    return registerEntry(capturedSet, (unsub) => ({ fn: listener as Listener<unknown>, unsub }), signal, {\n      offLog: `off(\"${event}\")`,\n      onLog: `on(\"${event}\")`,\n      onRemove: () => {\n        if (capturedSet.size === 0) listeners.delete(event);\n\n        onRemove?.();\n      },\n    });\n  }\n\n  function onAnyWithSignal(\n    listener: (event: EventKey<T>, payload: unknown) => void,\n    signal: AbortSignal,\n    onRemove?: () => void,\n  ): () => void {\n    return registerEntry(\n      wildcards,\n      (unsub) => ({ fn: listener as (event: string, payload: unknown) => void, unsub }),\n      signal,\n      { offLog: 'onAny off', onLog: 'onAny', onRemove },\n    );\n  }\n\n  // Use a const ref object to hold the unsub handle — avoids the forward-reference that\n  // TypeScript cannot prove safe with `const unsub = f(() => unsub)`. The `ref` binding never\n  // changes (only its property is mutated), satisfying prefer-const. By the time the inner\n  // callback fires (only possible after onWithSignal returns), ref.unsub is the real handle.\n  function onceWithSignal<K extends EventKey<T>>(\n    event: K,\n    listener: Listener<T[K]>,\n    signal: AbortSignal,\n    onRemove?: () => void,\n  ): () => void {\n    const ref = { unsub: noop as Unsubscribe };\n\n    ref.unsub = onWithSignal(\n      event,\n      (payload) => {\n        ref.unsub();\n        listener(payload);\n      },\n      signal,\n      onRemove,\n    );\n\n    return ref.unsub;\n  }\n\n  // onAny with once — fires the wildcard listener exactly once, then auto-removes.\n  function onAnyWithOnce(\n    listener: (event: EventKey<T>, payload: unknown) => void,\n    signal: AbortSignal,\n    onRemove?: () => void,\n  ): () => void {\n    const ref = { unsub: noop as Unsubscribe };\n\n    ref.unsub = onAnyWithSignal(\n      (event, payload) => {\n        ref.unsub();\n        listener(event, payload);\n      },\n      signal,\n      onRemove,\n    );\n\n    return ref.unsub;\n  }\n\n  function on<K extends EventKey<T>>(event: K, listener: Listener<T[K]>, opts?: SubscribeOptions): () => void {\n    const scope = createSubscriptionScope(opts?.signal);\n\n    if (opts?.once) return onceWithSignal(event, listener, scope.signal, scope.dispose);\n\n    return onWithSignal(event, listener, scope.signal, scope.dispose);\n  }\n\n  function once<K extends EventKey<T>>(\n    event: K,\n    listener: Listener<T[K]>,\n    opts?: { signal?: AbortSignal },\n  ): () => void {\n    const scope = createSubscriptionScope(opts?.signal);\n\n    return onceWithSignal(event, listener, scope.signal, scope.dispose);\n  }\n\n  function onAny(listener: (event: EventKey<T>, payload: unknown) => void, opts?: SubscribeOptions): () => void {\n    const scope = createSubscriptionScope(opts?.signal);\n\n    if (opts?.once) return onAnyWithOnce(listener, scope.signal, scope.dispose);\n\n    return onAnyWithSignal(listener, scope.signal, scope.dispose);\n  }\n\n  function wait<K extends EventKey<T>>(event: K, opts?: { signal?: AbortSignal }): Promise<T[K]> {\n    const scope = createSubscriptionScope(opts?.signal);\n\n    if (scope.signal.aborted) return Promise.reject(scope.signal.reason);\n\n    return new Promise<T[K]>((resolve, reject) => {\n      const onAbort = () => {\n        scope.dispose();\n        reject(scope.signal.reason);\n      };\n\n      onceWithSignal(\n        event,\n        (payload) => {\n          scope.signal.removeEventListener('abort', onAbort);\n          scope.dispose();\n          resolve(payload);\n        },\n        scope.signal,\n      );\n\n      scope.signal.addEventListener('abort', onAbort, { once: true });\n    });\n  }\n\n  // events() subscribes eagerly — the listener is registered when events() is called, not when\n  // the first .next() runs. This ensures events emitted before iteration begins are buffered.\n  // maxBuffer is validated synchronously so callers get a RangeError at call time.\n  function events<K extends EventKey<T>>(\n    event: K,\n    opts?: { maxBuffer?: number; signal?: AbortSignal },\n  ): EventStream<T[K]> {\n    const maxBuffer = opts?.maxBuffer ?? Infinity;\n\n    if (!(maxBuffer > 0)) throw new HeraldConfigError('maxBuffer must be a positive number');\n\n    const scope = createSubscriptionScope(opts?.signal);\n    const activeSignal = scope.signal;\n\n    if (activeSignal.aborted) {\n      const empty = (async function* (): AsyncGenerator<T[K]> {})();\n\n      return makeEventStream(empty, async (): Promise<void> => {});\n    }\n\n    const queue: T[K][] = [];\n    let wake: (() => void) | undefined;\n\n    const unsub = onWithSignal(\n      event,\n      (payload) => {\n        if (queue.length >= maxBuffer) queue.shift();\n\n        queue.push(payload);\n        wake?.();\n      },\n      activeSignal,\n      scope.dispose,\n    );\n\n    async function* generate(): AsyncGenerator<T[K]> {\n      try {\n        while (!activeSignal.aborted) {\n          if (queue.length) {\n            yield queue.shift()!;\n            continue;\n          }\n\n          const { promise, resolve } = Promise.withResolvers<void>();\n          const abortHandler = (): void => {\n            resolve();\n          };\n\n          wake = resolve;\n          activeSignal.addEventListener('abort', abortHandler, { once: true });\n          await promise;\n          activeSignal.removeEventListener('abort', abortHandler);\n          wake = undefined;\n        }\n      } finally {\n        unsub();\n      }\n    }\n\n    const gen = generate();\n\n    // Symbol.asyncDispose calls unsub() directly because gen.return() only runs the finally\n    // block when the generator has been started (at least one next() call). The unsub guard\n    // (called = false in registerEntry) makes this idempotent.\n    return makeEventStream(gen, async (): Promise<void> => {\n      unsub();\n      await gen.return(undefined as unknown as T[K]);\n    });\n  }\n\n  // dispatch is defined at createBus() scope (once per bus, not per emit call) — consistent with\n  // callSafe. Receives event/payload/timestamp as arguments so it can be invoked from both the\n  // direct path and the middleware chain without capturing per-emit locals in a closure.\n  function dispatch(event: EventKey<T>, payload: unknown, timestamp: number): number {\n    options?._onDispatch?.(event, payload);\n\n    let count = 0;\n    // Only the first unforwarded error is kept — every listener still runs (see callSafe's\n    // doc comment) — then it's rethrown once the whole broadcast (specific + wildcard) is done.\n    let firstError: { err: unknown } | undefined;\n    const set = listeners.get(event);\n\n    if (set?.size) {\n      for (const entry of [...set]) {\n        const result = callSafe(() => entry.fn(payload), event, payload, timestamp);\n\n        if (result.threw && !firstError) firstError = { err: result.err };\n\n        count++;\n      }\n    }\n\n    if (wildcards.size) {\n      for (const entry of [...wildcards]) {\n        const result = callSafe(() => entry.fn(event, payload), event, payload, timestamp);\n\n        if (result.threw && !firstError) firstError = { err: result.err };\n\n        count++;\n      }\n    }\n\n    if (firstError) throw firstError.err;\n\n    return count;\n  }\n\n  // emit() returns the number of listeners invoked (specific + wildcard).\n  // Returns 0 if bus is disposed, middleware blocked dispatch, or validatePayload rejected.\n  // validatePayload runs first, then middleware, then listeners.\n  function emit<K extends EventKey<T>>(event: K, ...args: T[K] extends void ? [] : [payload: T[K]]): number {\n    if (disposeController.signal.aborted) return 0;\n\n    const payload = (args as unknown[])[0];\n    const timestamp = Date.now();\n\n    if (options?.validatePayload) {\n      try {\n        options.validatePayload(event, payload as T[K]);\n      } catch (err) {\n        if (options?.onError) {\n          options.onError({ err, event, payload, timestamp } as EmissionErrorContext<T>);\n\n          return 0;\n        }\n\n        throw err;\n      }\n    }\n\n    if (logDebug) {\n      const specific = listeners.get(event)?.size ?? 0;\n      const wild = wildcards.size;\n\n      logDebug(\n        `[herald:emit] emit(\"${event}\") — ${specific + wild} listener(s) (${specific} specific, ${wild} wildcard)`,\n      );\n    }\n\n    const middleware = options?.middleware;\n\n    if (!middleware?.length) return dispatch(event, payload, timestamp);\n\n    const middlewareList = middleware;\n\n    function run(index: number): number {\n      const current = middlewareList[index];\n\n      if (!current) return dispatch(event, payload, timestamp);\n\n      let result = 0;\n      let continued = false;\n      let synchronous = true;\n\n      current(event, payload, () => {\n        if (!synchronous || continued) return;\n\n        continued = true;\n        result = run(index + 1);\n      });\n\n      synchronous = false;\n\n      return result;\n    }\n\n    return run(0);\n  }\n\n  // listenerCount counts specific-event listeners only.\n  // wildcardCount() is the separate accessor for onAny listeners.\n  function listenerCount(event?: EventKey<T>): number {\n    if (event !== undefined) return listeners.get(event)?.size ?? 0;\n\n    let total = 0;\n\n    for (const set of listeners.values()) total += set.size;\n\n    return total;\n  }\n\n  function wildcardCount(): number {\n    return wildcards.size;\n  }\n\n  function eventNames(): EventKey<T>[] {\n    return [...listeners.keys()] as EventKey<T>[];\n  }\n\n  function waitAny<K extends readonly [EventKey<T>, EventKey<T>, ...EventKey<T>[]]>(\n    eventList: K,\n    opts?: { signal?: AbortSignal },\n  ): Promise<WaitAnyResult<T, K>> {\n    if (eventList.length < 2) throw new HeraldConfigError('waitAny() requires at least 2 event keys');\n\n    const activeScope = createSubscriptionScope(opts?.signal);\n\n    if (activeScope.signal.aborted) return Promise.reject(activeScope.signal.reason);\n\n    return new Promise<WaitAnyResult<T, K>>((resolve, reject) => {\n      const raceController = new AbortController();\n      const raceScope = createSignalScope(activeScope.signal, raceController.signal);\n      const unsubs: Unsubscribe[] = [];\n      let settled = false;\n\n      function cleanup(): void {\n        activeScope.signal.removeEventListener('abort', onAbort);\n        raceController.abort();\n        raceScope.dispose();\n        activeScope.dispose();\n        for (const unsub of unsubs) unsub();\n      }\n\n      function onAbort(): void {\n        if (settled) return;\n\n        settled = true;\n        cleanup();\n        reject(activeScope.signal.reason);\n      }\n\n      activeScope.signal.addEventListener('abort', onAbort, { once: true });\n\n      for (const event of eventList) {\n        unsubs.push(\n          onceWithSignal(\n            event as EventKey<T>,\n            (payload) => {\n              if (settled) return;\n\n              settled = true;\n              cleanup();\n              resolve({ event, payload } as WaitAnyResult<T, K>);\n            },\n            raceScope.signal,\n          ),\n        );\n      }\n    });\n  }\n\n  function dispose(): void {\n    if (disposeController.signal.aborted) return;\n\n    logDebug?.('[herald:lifecycle] dispose()');\n\n    disposeController.abort(new BusDisposedError(busName));\n    // disposeController.abort() fires all unsub handlers synchronously, which\n    // removes every entry and deletes empty keys. By here both maps are already\n    // empty. clear() is a cheap defensive measure against any future code path\n    // that bypasses the signal (e.g. a direct listeners.set() before a guard).\n    listeners.clear();\n    wildcards.clear();\n  }\n\n  return {\n    get disposalSignal() {\n      return disposeController.signal;\n    },\n    dispose,\n    get disposed() {\n      return disposeController.signal.aborted;\n    },\n    emit,\n    eventNames,\n    events,\n    listenerCount,\n    on,\n    onAny,\n    once,\n    [Symbol.dispose]: dispose,\n    wait,\n    waitAny,\n    wildcardCount,\n  };\n}\n"],"mappings":"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"}

package/dist/bus.d.ts

@@ -1,17 +1,8 @@
 import type { Bus, EventMap } from './types';
 /**
- * Returns a signal that aborts as soon as any of the provided signals abort.
- * With a single argument, returns it directly (no allocation).
- * Registers and cleans up its own event listeners — no leaks when no signal fires.
- *
- * @example
- * const signal = combineSignals(timeoutSignal, bus.disposalSignal);
- * bus.on('event', handler, { signal });
- *
- * @example
- * // Three signals — no nesting required
- * const signal = combineSignals(userSignal, timeoutSignal, bus.disposalSignal);
+ * Returns a signal that aborts as soon as any provided signal aborts.
+ * Input listeners remain active until one input aborts; use signal-owning APIs for early cleanup.
  */
 export declare function combineSignals(first: AbortSignal, ...rest: AbortSignal[]): AbortSignal;
-export declare function createBus<T extends EventMap>(options?: InternalBusOptions<T>): Bus<T>;
+export declare function createBus<T extends EventMap = Record<string, unknown>>(options?: InternalBusOptions<T>): Bus<T>;
 //# sourceMappingURL=bus.d.ts.map

package/dist/bus.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bus.d.ts","sourceRoot":"","sources":["../src/bus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,GAAG,EAIH,QAAQ,EAMT,MAAM,SAAS,CAAC;AAmCjB;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,IAAI,EAAE,WAAW,EAAE,GAAG,WAAW,CAItF;AAsBD,wBAAgB,SAAS,CAAC,CAAC,SAAS,QAAQ,EAAE,OAAO,CAAC,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAubrF"}
+{"version":3,"file":"bus.d.ts","sourceRoot":"","sources":["../src/bus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,GAAG,EAIH,QAAQ,EAMT,MAAM,SAAS,CAAC;AAiDjB;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,IAAI,EAAE,WAAW,EAAE,GAAG,WAAW,CAEtF;AAsBD,wBAAgB,SAAS,CAAC,CAAC,SAAS,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CA6e/G"}

package/dist/bus.js

@@ -1,38 +1,63 @@
-import { callSafely as e } from "./_safe.js";
 import "./_dev.js";
+import { callSafely as e } from "./_safe.js";
 import { BusDisposedError as t, HeraldConfigError as n } from "./errors.js";
 //#region src/bus.ts
 var r = () => {};
-function i(e, t) {
-	if (e.aborted) return e;
-	if (t.aborted) return t;
-	let n = new AbortController(), r = () => n.abort(e.reason), i = () => n.abort(t.reason);
-	return e.addEventListener("abort", r, { once: !0 }), t.addEventListener("abort", i, { once: !0 }), n.signal.addEventListener("abort", () => {
-		e.removeEventListener("abort", r), t.removeEventListener("abort", i);
-	}, { once: !0 }), n.signal;
+function i(...e) {
+	let t = e.filter((e) => e !== void 0);
+	if (t.length === 1) return {
+		dispose: r,
+		signal: t[0]
+	};
+	let n = t.find((e) => e.aborted);
+	if (n) return {
+		dispose: r,
+		signal: n
+	};
+	let i = new AbortController(), a = /* @__PURE__ */ new Map(), o = !1;
+	function s() {
+		if (!o) {
+			o = !0;
+			for (let [e, t] of a) e.removeEventListener("abort", t);
+			a.clear();
+		}
+	}
+	for (let e of t) {
+		let t = () => {
+			i.abort(e.reason), s();
+		};
+		a.set(e, t), e.addEventListener("abort", t, { once: !0 });
+	}
+	return {
+		dispose: s,
+		signal: i.signal
+	};
 }
 function a(e, ...t) {
-	return t.length === 0 ? e : t.reduce(i, e);
+	return i(e, ...t).signal;
 }
 function o(e, t) {
 	return Object.assign(e, { [Symbol.asyncDispose]: t });
 }
-function s(i) {
-	let s = /* @__PURE__ */ new Map(), c = /* @__PURE__ */ new Set(), l = new AbortController(), u = i?.name, d = i?.maxListeners, f = i?.logger?.debug, p = f && u ? (e) => f(`${e} (${u})`) : f;
-	i?.logger;
-	let m = i?.logger?.warn, h = u ? ` (${u})` : "";
+function s(a) {
+	let s = /* @__PURE__ */ new Map(), c = /* @__PURE__ */ new Set(), l = new AbortController(), u = a?.name, d = a?.maxListeners, f = a?.logger?.debug, p = f && u ? (e) => f(`${e} (${u})`) : f;
+	a?.logger;
+	let m = a?.logger?.warn, h = u ? ` (${u})` : "";
 	function g(e) {
 		m && m(e);
 	}
 	function _(e) {
-		return e ? a(l.signal, e) : l.signal;
+		return e ? i(l.signal, e) : {
+			dispose: r,
+			signal: l.signal
+		};
 	}
-	function v(t, n, r, a) {
-		let o = i?.onError ? (e) => i.onError({
+	function v(t, n, r, i) {
+		let o = a?.onError ? (e) => a.onError({
 			err: e,
 			event: n,
 			payload: r,
-			timestamp: a
+			timestamp: i
 		}) : void 0;
 		return e(t, o);
 	}
@@ -45,114 +70,116 @@ function s(i) {
 		let l = t(c);
 		return e.add(l), n.addEventListener("abort", c, { once: !0 }), p?.(`[herald:sub] ${a} — ${e.size} listener(s)`), d !== void 0 && e.size > d && g(`${a} has ${e.size} listeners, exceeding maxListeners (${d}). Possible memory leak.${h}`), c;
 	}
-	function b(e, t, n) {
-		let r = s.get(e);
-		r || (r = /* @__PURE__ */ new Set(), s.set(e, r));
-		let i = r;
-		return y(i, (e) => ({
+	function b(e, t, n, r) {
+		let i = s.get(e);
+		i || (i = /* @__PURE__ */ new Set(), s.set(e, i));
+		let a = i;
+		return y(a, (e) => ({
 			fn: t,
 			unsub: e
 		}), n, {
 			offLog: `off("${e}")`,
 			onLog: `on("${e}")`,
 			onRemove: () => {
-				i.size === 0 && s.delete(e);
+				a.size === 0 && s.delete(e), r?.();
 			}
 		});
 	}
-	function x(e, t) {
+	function x(e, t, n) {
 		return y(c, (t) => ({
 			fn: e,
 			unsub: t
 		}), t, {
 			offLog: "onAny off",
-			onLog: "onAny"
+			onLog: "onAny",
+			onRemove: n
 		});
 	}
-	function S(e, t, n) {
-		let i = { unsub: r };
-		return i.unsub = b(e, (e) => {
-			i.unsub(), t(e);
-		}, n), i.unsub;
+	function S(e, t, n, i) {
+		let a = { unsub: r };
+		return a.unsub = b(e, (e) => {
+			a.unsub(), t(e);
+		}, n, i), a.unsub;
 	}
-	function C(e, t) {
-		let n = { unsub: r };
-		return n.unsub = x((t, r) => {
-			n.unsub(), e(t, r);
-		}, t), n.unsub;
+	function C(e, t, n) {
+		let i = { unsub: r };
+		return i.unsub = x((t, n) => {
+			i.unsub(), e(t, n);
+		}, t, n), i.unsub;
 	}
 	function w(e, t, n) {
 		let r = _(n?.signal);
-		return n?.once ? S(e, t, r) : b(e, t, r);
+		return n?.once ? S(e, t, r.signal, r.dispose) : b(e, t, r.signal, r.dispose);
 	}
 	function T(e, t, n) {
-		return S(e, t, _(n?.signal));
+		let r = _(n?.signal);
+		return S(e, t, r.signal, r.dispose);
 	}
 	function E(e, t) {
 		let n = _(t?.signal);
-		return t?.once ? C(e, n) : x(e, n);
+		return t?.once ? C(e, n.signal, n.dispose) : x(e, n.signal, n.dispose);
 	}
 	function D(e, t) {
 		let n = _(t?.signal);
-		return n.aborted ? Promise.reject(n.reason) : new Promise((t, r) => {
-			function i() {
-				r(n.reason);
-			}
+		return n.signal.aborted ? Promise.reject(n.signal.reason) : new Promise((t, r) => {
+			let i = () => {
+				n.dispose(), r(n.signal.reason);
+			};
 			S(e, (e) => {
-				n.removeEventListener("abort", i), t(e);
-			}, n), n.addEventListener("abort", i, { once: !0 });
+				n.signal.removeEventListener("abort", i), n.dispose(), t(e);
+			}, n.signal), n.signal.addEventListener("abort", i, { once: !0 });
 		});
 	}
 	function O(e, t) {
 		let r = t?.maxBuffer ?? Infinity;
 		if (!(r > 0)) throw new n("maxBuffer must be a positive number");
-		let i = _(t?.signal);
-		if (i.aborted) return o((async function* () {})(), async () => {});
-		let a = [], s, c = b(e, (e) => {
-			a.length >= r && a.shift(), a.push(e), s?.();
-		}, i);
-		async function* l() {
+		let i = _(t?.signal), a = i.signal;
+		if (a.aborted) return o((async function* () {})(), async () => {});
+		let s = [], c, l = b(e, (e) => {
+			s.length >= r && s.shift(), s.push(e), c?.();
+		}, a, i.dispose);
+		async function* u() {
 			try {
-				for (; !i.aborted;) {
-					if (a.length) {
-						yield a.shift();
+				for (; !a.aborted;) {
+					if (s.length) {
+						yield s.shift();
 						continue;
 					}
 					let { promise: e, resolve: t } = Promise.withResolvers(), n = () => {
 						t();
 					};
-					s = t, i.addEventListener("abort", n, { once: !0 }), await e, i.removeEventListener("abort", n), s = void 0;
+					c = t, a.addEventListener("abort", n, { once: !0 }), await e, a.removeEventListener("abort", n), c = void 0;
 				}
 			} finally {
-				c();
+				l();
 			}
 		}
-		let u = l();
-		return o(u, async () => {
-			c(), await u.return(void 0);
+		let d = u();
+		return o(d, async () => {
+			l(), await d.return(void 0);
 		});
 	}
 	function k(e, t, n) {
-		i?._onDispatch?.(e, t);
-		let r = 0, a, o = s.get(e);
-		if (o?.size) for (let i of [...o]) {
-			let o = v(() => i.fn(t), e, t, n);
-			o.threw && !a && (a = { err: o.err }), r++;
+		a?._onDispatch?.(e, t);
+		let r = 0, i, o = s.get(e);
+		if (o?.size) for (let a of [...o]) {
+			let o = v(() => a.fn(t), e, t, n);
+			o.threw && !i && (i = { err: o.err }), r++;
 		}
-		if (c.size) for (let i of [...c]) {
-			let o = v(() => i.fn(e, t), e, t, n);
-			o.threw && !a && (a = { err: o.err }), r++;
+		if (c.size) for (let a of [...c]) {
+			let o = v(() => a.fn(e, t), e, t, n);
+			o.threw && !i && (i = { err: o.err }), r++;
 		}
-		if (a) throw a.err;
+		if (i) throw i.err;
 		return r;
 	}
 	function A(e, ...t) {
 		if (l.signal.aborted) return 0;
 		let n = t[0], r = Date.now();
-		if (i?.validatePayload) try {
-			i.validatePayload(e, n);
+		if (a?.validatePayload) try {
+			a.validatePayload(e, n);
 		} catch (t) {
-			if (i?.onError) return i.onError({
+			if (a?.onError) return a.onError({
 				err: t,
 				event: e,
 				payload: n,
@@ -164,16 +191,18 @@ function s(i) {
 			let t = s.get(e)?.size ?? 0, n = c.size;
 			p(`[herald:emit] emit("${e}") — ${t + n} listener(s) (${t} specific, ${n} wildcard)`);
 		}
-		let a = i?.middleware;
-		if (a?.length) {
-			let t = 0, i = 0;
-			function o() {
-				let s = i++;
-				s < a.length ? a[s](e, n, o) : s === a.length && (t = k(e, n, r));
-			}
-			return o(), t;
+		let i = a?.middleware;
+		if (!i?.length) return k(e, n, r);
+		let o = i;
+		function u(t) {
+			let i = o[t];
+			if (!i) return k(e, n, r);
+			let a = 0, s = !1, c = !0;
+			return i(e, n, () => {
+				!c || s || (s = !0, a = u(t + 1));
+			}), c = !1, a;
 		}
-		return k(e, n, r);
+		return u(0);
 	}
 	function j(e) {
 		if (e !== void 0) return s.get(e)?.size ?? 0;
@@ -190,18 +219,22 @@ function s(i) {
 	function P(e, t) {
 		if (e.length < 2) throw new n("waitAny() requires at least 2 event keys");
 		let r = _(t?.signal);
-		return r.aborted ? Promise.reject(r.reason) : new Promise((t, n) => {
-			let i = new AbortController(), o = a(r, i.signal);
-			function s() {
-				i.abort(), n(r.reason);
+		return r.signal.aborted ? Promise.reject(r.signal.reason) : new Promise((t, n) => {
+			let a = new AbortController(), o = i(r.signal, a.signal), s = [], c = !1;
+			function l() {
+				r.signal.removeEventListener("abort", u), a.abort(), o.dispose(), r.dispose();
+				for (let e of s) e();
+			}
+			function u() {
+				c || (c = !0, l(), n(r.signal.reason));
 			}
-			r.addEventListener("abort", s, { once: !0 });
-			for (let n of e) S(n, (e) => {
-				r.removeEventListener("abort", s), i.abort(), t({
+			r.signal.addEventListener("abort", u, { once: !0 });
+			for (let n of e) s.push(S(n, (e) => {
+				c || (c = !0, l(), t({
 					event: n,
 					payload: e
-				});
-			}, o);
+				}));
+			}, o.signal));
 		});
 	}
 	function F() {
@@ -229,6 +262,6 @@ function s(i) {
 	};
 }
 //#endregion
-export { a as combineSignals, s as createBus, r as noop };
+export { a as combineSignals, s as createBus, i as createSignalScope, r as noop };
 
 //# sourceMappingURL=bus.js.map