@open-mercato/events 0.6.7 → 0.6.8-develop.6875.1.871a4afc94

package/dist/bus.js

@@ -115,6 +115,9 @@ function createEventBus(opts) {
           );
         } catch (error) {
           logger.error("Handler error", { event, pattern, err: error });
+          if (options?.rethrowHandlerErrors) {
+            throw error;
+          }
         }
       }
     }

package/dist/bus.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/bus.ts"],
-  "sourcesContent": ["import { createQueue } from '@open-mercato/queue'\nimport type { Queue } from '@open-mercato/queue'\nimport { parseBooleanWithDefault } from '@open-mercato/shared/lib/boolean'\nimport { createLogger } from '@open-mercato/shared/lib/logger'\nimport { isSingleDeliveryRequested } from './single-delivery'\nimport { matchEventPattern } from '@open-mercato/shared/lib/events/patterns'\nimport { getRedisUrlOrThrow } from '@open-mercato/shared/lib/redis/connection'\nimport { isBroadcastEvent } from '@open-mercato/shared/modules/events'\nimport {\n  inferModuleIdFromResourceId,\n  withModuleResourceUsage,\n} from '@open-mercato/shared/lib/modules/resource-usage'\nexport { registerCrossProcessEventListener } from './bridge'\nimport { publishCrossProcessEvent } from './bridge'\nimport type {\n  EventBus,\n  CreateBusOptions,\n  SubscriberHandler,\n  SubscriberDescriptor,\n  EventPayload,\n  EmitOptions,\n} from './types'\n\n/** Queue name for persistent events */\nconst EVENTS_QUEUE_NAME = 'events'\n\nconst logger = createLogger('events')\n\ntype RegisteredSubscriber = {\n  id?: string\n  moduleId?: string\n  event: string\n  handler: SubscriberHandler\n  persistent?: boolean\n}\n\n/**\n * When enabled, a persistent emit delivers each subscriber on exactly one path:\n * persistent-marked subscribers are skipped inline (the events worker dispatches\n * them via pattern match, so wildcard persistent subscribers are reached), while\n * ephemeral subscribers keep running inline. Defaults ON; the server bootstrap\n * reconciles the env against worker availability (and may rewrite it to `false`\n * for a worker-less process). Both the bus and the events worker read the same\n * (possibly reconciled) env var, so they always agree within a process.\n */\nfunction isSingleDeliveryEnabled(): boolean {\n  return isSingleDeliveryRequested()\n}\n\ntype GlobalEventTap = (event: string, payload: EventPayload, options?: EmitOptions) => void | Promise<void>\nconst GLOBAL_EVENT_TAPS_KEY = '__openMercatoEventBusGlobalTaps__'\n\nfunction hasTenantScope(payload: EventPayload): boolean {\n  return typeof (payload as Record<string, unknown>)?.tenantId === 'string'\n    && String((payload as Record<string, unknown>).tenantId).trim().length > 0\n}\n\nfunction getGlobalEventTaps(): Set<GlobalEventTap> {\n  const existing = (globalThis as Record<string, unknown>)[GLOBAL_EVENT_TAPS_KEY]\n  if (existing instanceof Set) {\n    return existing as Set<GlobalEventTap>\n  }\n  const created = new Set<GlobalEventTap>()\n  ;(globalThis as Record<string, unknown>)[GLOBAL_EVENT_TAPS_KEY] = created\n  return created\n}\n\nexport function registerGlobalEventTap(handler: GlobalEventTap): () => void {\n  const taps = getGlobalEventTaps()\n  taps.add(handler)\n  return () => {\n    taps.delete(handler)\n  }\n}\n\n/** Job data structure for queued events */\ntype EventJobData = {\n  event: string\n  payload: EventPayload\n  options?: EmitOptions\n}\n\n// Process-wide cache of the async (BullMQ) persistent-events producer queue.\n// Each authenticated request builds a fresh DI container and event bus, so a\n// per-bus producer queue opened a new ioredis connection per write request that\n// was never closed \u2014 leaking one Redis connection per request until maxclients\n// exhaustion. Memoizing the producer on `globalThis` (keyed by Redis URL, so a\n// reconfigured URL still gets its own queue) keeps it at one connection per\n// process, mirroring the `GLOBAL_EVENT_TAPS_KEY` and `getCachedRateLimiterService`\n// patterns. The local (file-based) strategy holds no pooled connection and its\n// base dir is cwd-relative, so it stays per-bus.\nconst EVENTS_PRODUCER_QUEUE_KEY = '__openMercatoEventsProducerQueues__'\nconst EVENTS_PRODUCER_SHUTDOWN_KEY = '__openMercatoEventsProducerShutdown__'\n\nfunction isSharedProducerEnabled(): boolean {\n  return parseBooleanWithDefault(process.env.OM_EVENTS_SHARED_PRODUCER, true)\n}\n\nfunction getProducerQueueRegistry(): Map<string, Queue<EventJobData>> {\n  const existing = (globalThis as Record<string, unknown>)[EVENTS_PRODUCER_QUEUE_KEY]\n  if (existing instanceof Map) {\n    return existing as Map<string, Queue<EventJobData>>\n  }\n  const created = new Map<string, Queue<EventJobData>>()\n  ;(globalThis as Record<string, unknown>)[EVENTS_PRODUCER_QUEUE_KEY] = created\n  return created\n}\n\nfunction registerProducerShutdownHook(): void {\n  if ((globalThis as Record<string, unknown>)[EVENTS_PRODUCER_SHUTDOWN_KEY]) return\n  const shutdown = () => {\n    const registry = getProducerQueueRegistry()\n    for (const sharedQueue of registry.values()) {\n      Promise.resolve(sharedQueue.close()).catch(() => {})\n    }\n    registry.clear()\n  }\n  process.once('SIGTERM', shutdown)\n  process.once('SIGINT', shutdown)\n  ;(globalThis as Record<string, unknown>)[EVENTS_PRODUCER_SHUTDOWN_KEY] = true\n}\n\n/**\n * Creates an event bus instance.\n *\n * The event bus provides:\n * - In-memory event delivery to registered handlers\n * - Optional persistence via the queue package when `persistent: true`\n *\n * @param opts - Configuration options\n * @returns An EventBus instance\n *\n * @example\n * ```typescript\n * const bus = createEventBus({\n *   resolve: container.resolve.bind(container),\n *   queueStrategy: 'local', // or 'async' for BullMQ\n * })\n *\n * // Register a handler\n * bus.on('user.created', async (payload, ctx) => {\n *   const userService = ctx.resolve('userService')\n *   await userService.sendWelcomeEmail(payload.userId)\n * })\n *\n * // Emit an event (immediate delivery)\n * await bus.emit('user.created', { userId: '123' })\n *\n * // Emit with persistence (for async worker processing)\n * await bus.emit('order.placed', { orderId: '456' }, { persistent: true })\n * ```\n */\nexport function createEventBus(opts: CreateBusOptions): EventBus {\n  // In-memory listeners for immediate event delivery\n  const listeners = new Map<string, Set<RegisteredSubscriber>>()\n  // Subscribers registered as persistent (worker-dispatched). Used by the\n  // single-delivery path to skip them inline on a persistent emit.\n  const persistentSubscribers = new Set<RegisteredSubscriber>()\n\n  // Determine queue strategy from options or environment\n  const queueStrategy = opts.queueStrategy ??\n    (process.env.QUEUE_STRATEGY === 'async' ? 'async' : 'local')\n\n  // Lazy-initialized queue for persistent events\n  let queue: Queue<EventJobData> | null = null\n\n  /**\n   * Gets or creates the queue instance for persistent events.\n   *\n   * The async (BullMQ) producer is memoized process-wide so the per-request\n   * event bus reuses one Redis connection instead of leaking one per write\n   * request. The local strategy stays per-bus (no pooled connection, cwd-relative\n   * base dir). Set `OM_EVENTS_SHARED_PRODUCER=0` to fall back to per-bus producers.\n   */\n  function getQueue(): Queue<EventJobData> {\n    if (queueStrategy !== 'async' || !isSharedProducerEnabled()) {\n      if (!queue) {\n        queue = queueStrategy === 'async'\n          ? createQueue<EventJobData>(EVENTS_QUEUE_NAME, 'async', {\n              connection: { url: getRedisUrlOrThrow('QUEUE') },\n            })\n          : createQueue<EventJobData>(EVENTS_QUEUE_NAME, 'local')\n      }\n      return queue\n    }\n\n    const redisUrl = getRedisUrlOrThrow('QUEUE')\n    const registry = getProducerQueueRegistry()\n    const cacheKey = `async:${redisUrl}`\n    let shared = registry.get(cacheKey)\n    if (!shared) {\n      shared = createQueue<EventJobData>(EVENTS_QUEUE_NAME, 'async', {\n        connection: { url: redisUrl },\n      })\n      registry.set(cacheKey, shared)\n      registerProducerShutdownHook()\n    }\n    return shared\n  }\n\n  /**\n   * Delivers an event to all registered in-memory handlers.\n   * Supports wildcard pattern matching for event patterns.\n   */\n  async function deliver(\n    event: string,\n    payload: EventPayload,\n    options?: EmitOptions,\n    skipPersistent = false,\n  ): Promise<void> {\n    // Check all registered patterns (including wildcards)\n    for (const [pattern, handlers] of listeners) {\n      if (!matchEventPattern(event, pattern)) continue\n      if (!handlers || handlers.size === 0) continue\n\n      for (const subscriber of handlers) {\n        // Single-delivery: persistent subscribers are dispatched by the worker,\n        // so skip them inline to avoid double execution.\n        if (skipPersistent && persistentSubscribers.has(subscriber)) continue\n        try {\n          // Pass eventName in context for wildcard handlers\n          const moduleId = subscriber.moduleId ?? inferModuleIdFromResourceId(subscriber.id)\n          await withModuleResourceUsage(\n            {\n              moduleId,\n              surface: 'subscriber',\n              operation: `${event} -> ${subscriber.id ?? subscriber.event}`,\n              resourceId: subscriber.id ?? subscriber.event,\n            },\n            () => subscriber.handler(payload, {\n              resolve: opts.resolve,\n              eventName: event,\n              tenantId: options?.tenantId ?? null,\n              organizationId: options?.organizationId ?? null,\n            }),\n          )\n        } catch (error) {\n          logger.error('Handler error', { event, pattern, err: error })\n        }\n      }\n    }\n  }\n\n  /**\n   * Registers a handler for an event. Pass `moduleId` whenever the subscribing\n   * module is known (e.g. a module reacting to another module's event) so\n   * resource-usage telemetry attributes the handler correctly instead of\n   * guessing a module id from the event name.\n   */\n  function on(\n    event: string,\n    handler: SubscriberHandler,\n    options?: { persistent?: boolean; moduleId?: string; id?: string },\n  ): void {\n    if (!listeners.has(event)) {\n      listeners.set(event, new Set())\n    }\n    const subscriber: RegisteredSubscriber = {\n      id: options?.id,\n      moduleId: options?.moduleId,\n      event,\n      handler,\n      persistent: options?.persistent,\n    }\n    listeners.get(event)!.add(subscriber)\n    if (options?.persistent) {\n      persistentSubscribers.add(subscriber)\n    }\n  }\n\n  /**\n   * Registers multiple module subscribers at once.\n   */\n  function registerModuleSubscribers(subs: SubscriberDescriptor[]): void {\n    for (const sub of subs) {\n      on(sub.event, sub.handler, { persistent: sub.persistent, moduleId: sub.moduleId, id: sub.id })\n    }\n  }\n\n  /**\n   * Emits an event to all registered handlers.\n   *\n   * If `persistent: true`, also enqueues the event for async processing.\n   */\n  async function emit(\n    event: string,\n    payload: EventPayload,\n    options?: EmitOptions\n  ): Promise<void> {\n    const taps = getGlobalEventTaps()\n    for (const tap of taps) {\n      try {\n        await Promise.resolve(tap(event, payload, options))\n      } catch (error) {\n        logger.error('Global tap error', { event, err: error })\n      }\n    }\n\n    // Deliver to in-memory handlers first. Under single-delivery, persistent\n    // subscribers are skipped inline on a persistent emit because the events\n    // worker will dispatch them from the queue.\n    //\n    // `deliverInline: false` on a persistent emit is enqueue-only: skip inline\n    // delivery entirely so a heavy persistent job runs solely in the events\n    // worker, off the caller's request path (the queued enqueue below still\n    // happens). Without this, a persistent emit dual-dispatches by default and\n    // runs the subscriber inline in the caller's request too.\n    const enqueueOnly = Boolean(options?.persistent) && options?.deliverInline === false\n    if (!enqueueOnly) {\n      const skipPersistentInline = Boolean(options?.persistent) && isSingleDeliveryEnabled()\n      await deliver(event, payload, options, skipPersistentInline)\n    }\n\n    if (isBroadcastEvent(event) && hasTenantScope(payload)) {\n      try {\n        await publishCrossProcessEvent(event, payload, options)\n      } catch (error) {\n        logger.error('Cross-process publish error', { event, err: error })\n      }\n    }\n\n    // If persistent, also enqueue for async processing\n    if (options?.persistent) {\n      const q = getQueue()\n      await q.enqueue({ event, payload, options })\n    }\n  }\n\n  /**\n   * Clears all events from the persistent queue.\n   */\n  async function clearQueue(): Promise<{ removed: number }> {\n    const q = getQueue()\n    return q.clear()\n  }\n\n  // Backward compatibility alias\n  const emitEvent = emit\n\n  return {\n    emit,\n    emitEvent, // Alias for backward compatibility\n    on,\n    registerModuleSubscribers,\n    clearQueue,\n  }\n}\n"],
-  "mappings": "AAAA,SAAS,mBAAmB;AAE5B,SAAS,+BAA+B;AACxC,SAAS,oBAAoB;AAC7B,SAAS,iCAAiC;AAC1C,SAAS,yBAAyB;AAClC,SAAS,0BAA0B;AACnC,SAAS,wBAAwB;AACjC;AAAA,EACE;AAAA,EACA;AAAA,OACK;AACP,SAAS,yCAAyC;AAClD,SAAS,gCAAgC;AAWzC,MAAM,oBAAoB;AAE1B,MAAM,SAAS,aAAa,QAAQ;AAmBpC,SAAS,0BAAmC;AAC1C,SAAO,0BAA0B;AACnC;AAGA,MAAM,wBAAwB;AAE9B,SAAS,eAAe,SAAgC;AACtD,SAAO,OAAQ,SAAqC,aAAa,YAC5D,OAAQ,QAAoC,QAAQ,EAAE,KAAK,EAAE,SAAS;AAC7E;AAEA,SAAS,qBAA0C;AACjD,QAAM,WAAY,WAAuC,qBAAqB;AAC9E,MAAI,oBAAoB,KAAK;AAC3B,WAAO;AAAA,EACT;AACA,QAAM,UAAU,oBAAI,IAAoB;AACvC,EAAC,WAAuC,qBAAqB,IAAI;AAClE,SAAO;AACT;AAEO,SAAS,uBAAuB,SAAqC;AAC1E,QAAM,OAAO,mBAAmB;AAChC,OAAK,IAAI,OAAO;AAChB,SAAO,MAAM;AACX,SAAK,OAAO,OAAO;AAAA,EACrB;AACF;AAkBA,MAAM,4BAA4B;AAClC,MAAM,+BAA+B;AAErC,SAAS,0BAAmC;AAC1C,SAAO,wBAAwB,QAAQ,IAAI,2BAA2B,IAAI;AAC5E;AAEA,SAAS,2BAA6D;AACpE,QAAM,WAAY,WAAuC,yBAAyB;AAClF,MAAI,oBAAoB,KAAK;AAC3B,WAAO;AAAA,EACT;AACA,QAAM,UAAU,oBAAI,IAAiC;AACpD,EAAC,WAAuC,yBAAyB,IAAI;AACtE,SAAO;AACT;AAEA,SAAS,+BAAqC;AAC5C,MAAK,WAAuC,4BAA4B,EAAG;AAC3E,QAAM,WAAW,MAAM;AACrB,UAAM,WAAW,yBAAyB;AAC1C,eAAW,eAAe,SAAS,OAAO,GAAG;AAC3C,cAAQ,QAAQ,YAAY,MAAM,CAAC,EAAE,MAAM,MAAM;AAAA,MAAC,CAAC;AAAA,IACrD;AACA,aAAS,MAAM;AAAA,EACjB;AACA,UAAQ,KAAK,WAAW,QAAQ;AAChC,UAAQ,KAAK,UAAU,QAAQ;AAC9B,EAAC,WAAuC,4BAA4B,IAAI;AAC3E;AAgCO,SAAS,eAAe,MAAkC;AAE/D,QAAM,YAAY,oBAAI,IAAuC;AAG7D,QAAM,wBAAwB,oBAAI,IAA0B;AAG5D,QAAM,gBAAgB,KAAK,kBACxB,QAAQ,IAAI,mBAAmB,UAAU,UAAU;AAGtD,MAAI,QAAoC;AAUxC,WAAS,WAAgC;AACvC,QAAI,kBAAkB,WAAW,CAAC,wBAAwB,GAAG;AAC3D,UAAI,CAAC,OAAO;AACV,gBAAQ,kBAAkB,UACtB,YAA0B,mBAAmB,SAAS;AAAA,UACpD,YAAY,EAAE,KAAK,mBAAmB,OAAO,EAAE;AAAA,QACjD,CAAC,IACD,YAA0B,mBAAmB,OAAO;AAAA,MAC1D;AACA,aAAO;AAAA,IACT;AAEA,UAAM,WAAW,mBAAmB,OAAO;AAC3C,UAAM,WAAW,yBAAyB;AAC1C,UAAM,WAAW,SAAS,QAAQ;AAClC,QAAI,SAAS,SAAS,IAAI,QAAQ;AAClC,QAAI,CAAC,QAAQ;AACX,eAAS,YAA0B,mBAAmB,SAAS;AAAA,QAC7D,YAAY,EAAE,KAAK,SAAS;AAAA,MAC9B,CAAC;AACD,eAAS,IAAI,UAAU,MAAM;AAC7B,mCAA6B;AAAA,IAC/B;AACA,WAAO;AAAA,EACT;AAMA,iBAAe,QACb,OACA,SACA,SACA,iBAAiB,OACF;AAEf,eAAW,CAAC,SAAS,QAAQ,KAAK,WAAW;AAC3C,UAAI,CAAC,kBAAkB,OAAO,OAAO,EAAG;AACxC,UAAI,CAAC,YAAY,SAAS,SAAS,EAAG;AAEtC,iBAAW,cAAc,UAAU;AAGjC,YAAI,kBAAkB,sBAAsB,IAAI,UAAU,EAAG;AAC7D,YAAI;AAEF,gBAAM,WAAW,WAAW,YAAY,4BAA4B,WAAW,EAAE;AACjF,gBAAM;AAAA,YACJ;AAAA,cACE;AAAA,cACA,SAAS;AAAA,cACT,WAAW,GAAG,KAAK,OAAO,WAAW,MAAM,WAAW,KAAK;AAAA,cAC3D,YAAY,WAAW,MAAM,WAAW;AAAA,YAC1C;AAAA,YACA,MAAM,WAAW,QAAQ,SAAS;AAAA,cAChC,SAAS,KAAK;AAAA,cACd,WAAW;AAAA,cACX,UAAU,SAAS,YAAY;AAAA,cAC/B,gBAAgB,SAAS,kBAAkB;AAAA,YAC7C,CAAC;AAAA,UACH;AAAA,QACF,SAAS,OAAO;AACd,iBAAO,MAAM,iBAAiB,EAAE,OAAO,SAAS,KAAK,MAAM,CAAC;AAAA,QAC9D;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAQA,WAAS,GACP,OACA,SACA,SACM;AACN,QAAI,CAAC,UAAU,IAAI,KAAK,GAAG;AACzB,gBAAU,IAAI,OAAO,oBAAI,IAAI,CAAC;AAAA,IAChC;AACA,UAAM,aAAmC;AAAA,MACvC,IAAI,SAAS;AAAA,MACb,UAAU,SAAS;AAAA,MACnB;AAAA,MACA;AAAA,MACA,YAAY,SAAS;AAAA,IACvB;AACA,cAAU,IAAI,KAAK,EAAG,IAAI,UAAU;AACpC,QAAI,SAAS,YAAY;AACvB,4BAAsB,IAAI,UAAU;AAAA,IACtC;AAAA,EACF;AAKA,WAAS,0BAA0B,MAAoC;AACrE,eAAW,OAAO,MAAM;AACtB,SAAG,IAAI,OAAO,IAAI,SAAS,EAAE,YAAY,IAAI,YAAY,UAAU,IAAI,UAAU,IAAI,IAAI,GAAG,CAAC;AAAA,IAC/F;AAAA,EACF;AAOA,iBAAe,KACb,OACA,SACA,SACe;AACf,UAAM,OAAO,mBAAmB;AAChC,eAAW,OAAO,MAAM;AACtB,UAAI;AACF,cAAM,QAAQ,QAAQ,IAAI,OAAO,SAAS,OAAO,CAAC;AAAA,MACpD,SAAS,OAAO;AACd,eAAO,MAAM,oBAAoB,EAAE,OAAO,KAAK,MAAM,CAAC;AAAA,MACxD;AAAA,IACF;AAWA,UAAM,cAAc,QAAQ,SAAS,UAAU,KAAK,SAAS,kBAAkB;AAC/E,QAAI,CAAC,aAAa;AAChB,YAAM,uBAAuB,QAAQ,SAAS,UAAU,KAAK,wBAAwB;AACrF,YAAM,QAAQ,OAAO,SAAS,SAAS,oBAAoB;AAAA,IAC7D;AAEA,QAAI,iBAAiB,KAAK,KAAK,eAAe,OAAO,GAAG;AACtD,UAAI;AACF,cAAM,yBAAyB,OAAO,SAAS,OAAO;AAAA,MACxD,SAAS,OAAO;AACd,eAAO,MAAM,+BAA+B,EAAE,OAAO,KAAK,MAAM,CAAC;AAAA,MACnE;AAAA,IACF;AAGA,QAAI,SAAS,YAAY;AACvB,YAAM,IAAI,SAAS;AACnB,YAAM,EAAE,QAAQ,EAAE,OAAO,SAAS,QAAQ,CAAC;AAAA,IAC7C;AAAA,EACF;AAKA,iBAAe,aAA2C;AACxD,UAAM,IAAI,SAAS;AACnB,WAAO,EAAE,MAAM;AAAA,EACjB;AAGA,QAAM,YAAY;AAElB,SAAO;AAAA,IACL;AAAA,IACA;AAAA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;",
+  "sourcesContent": ["import { createQueue } from '@open-mercato/queue'\nimport type { Queue } from '@open-mercato/queue'\nimport { parseBooleanWithDefault } from '@open-mercato/shared/lib/boolean'\nimport { createLogger } from '@open-mercato/shared/lib/logger'\nimport { isSingleDeliveryRequested } from './single-delivery'\nimport { matchEventPattern } from '@open-mercato/shared/lib/events/patterns'\nimport { getRedisUrlOrThrow } from '@open-mercato/shared/lib/redis/connection'\nimport { isBroadcastEvent } from '@open-mercato/shared/modules/events'\nimport {\n  inferModuleIdFromResourceId,\n  withModuleResourceUsage,\n} from '@open-mercato/shared/lib/modules/resource-usage'\nexport { registerCrossProcessEventListener } from './bridge'\nimport { publishCrossProcessEvent } from './bridge'\nimport type {\n  EventBus,\n  CreateBusOptions,\n  SubscriberHandler,\n  SubscriberDescriptor,\n  EventPayload,\n  EmitOptions,\n} from './types'\n\n/** Queue name for persistent events */\nconst EVENTS_QUEUE_NAME = 'events'\n\nconst logger = createLogger('events')\n\ntype RegisteredSubscriber = {\n  id?: string\n  moduleId?: string\n  event: string\n  handler: SubscriberHandler\n  persistent?: boolean\n}\n\n/**\n * When enabled, a persistent emit delivers each subscriber on exactly one path:\n * persistent-marked subscribers are skipped inline (the events worker dispatches\n * them via pattern match, so wildcard persistent subscribers are reached), while\n * ephemeral subscribers keep running inline. Defaults ON; the server bootstrap\n * reconciles the env against worker availability (and may rewrite it to `false`\n * for a worker-less process). Both the bus and the events worker read the same\n * (possibly reconciled) env var, so they always agree within a process.\n */\nfunction isSingleDeliveryEnabled(): boolean {\n  return isSingleDeliveryRequested()\n}\n\ntype GlobalEventTap = (event: string, payload: EventPayload, options?: EmitOptions) => void | Promise<void>\nconst GLOBAL_EVENT_TAPS_KEY = '__openMercatoEventBusGlobalTaps__'\n\nfunction hasTenantScope(payload: EventPayload): boolean {\n  return typeof (payload as Record<string, unknown>)?.tenantId === 'string'\n    && String((payload as Record<string, unknown>).tenantId).trim().length > 0\n}\n\nfunction getGlobalEventTaps(): Set<GlobalEventTap> {\n  const existing = (globalThis as Record<string, unknown>)[GLOBAL_EVENT_TAPS_KEY]\n  if (existing instanceof Set) {\n    return existing as Set<GlobalEventTap>\n  }\n  const created = new Set<GlobalEventTap>()\n  ;(globalThis as Record<string, unknown>)[GLOBAL_EVENT_TAPS_KEY] = created\n  return created\n}\n\nexport function registerGlobalEventTap(handler: GlobalEventTap): () => void {\n  const taps = getGlobalEventTaps()\n  taps.add(handler)\n  return () => {\n    taps.delete(handler)\n  }\n}\n\n/** Job data structure for queued events */\ntype EventJobData = {\n  event: string\n  payload: EventPayload\n  options?: EmitOptions\n}\n\n// Process-wide cache of the async (BullMQ) persistent-events producer queue.\n// Each authenticated request builds a fresh DI container and event bus, so a\n// per-bus producer queue opened a new ioredis connection per write request that\n// was never closed \u2014 leaking one Redis connection per request until maxclients\n// exhaustion. Memoizing the producer on `globalThis` (keyed by Redis URL, so a\n// reconfigured URL still gets its own queue) keeps it at one connection per\n// process, mirroring the `GLOBAL_EVENT_TAPS_KEY` and `getCachedRateLimiterService`\n// patterns. The local (file-based) strategy holds no pooled connection and its\n// base dir is cwd-relative, so it stays per-bus.\nconst EVENTS_PRODUCER_QUEUE_KEY = '__openMercatoEventsProducerQueues__'\nconst EVENTS_PRODUCER_SHUTDOWN_KEY = '__openMercatoEventsProducerShutdown__'\n\nfunction isSharedProducerEnabled(): boolean {\n  return parseBooleanWithDefault(process.env.OM_EVENTS_SHARED_PRODUCER, true)\n}\n\nfunction getProducerQueueRegistry(): Map<string, Queue<EventJobData>> {\n  const existing = (globalThis as Record<string, unknown>)[EVENTS_PRODUCER_QUEUE_KEY]\n  if (existing instanceof Map) {\n    return existing as Map<string, Queue<EventJobData>>\n  }\n  const created = new Map<string, Queue<EventJobData>>()\n  ;(globalThis as Record<string, unknown>)[EVENTS_PRODUCER_QUEUE_KEY] = created\n  return created\n}\n\nfunction registerProducerShutdownHook(): void {\n  if ((globalThis as Record<string, unknown>)[EVENTS_PRODUCER_SHUTDOWN_KEY]) return\n  const shutdown = () => {\n    const registry = getProducerQueueRegistry()\n    for (const sharedQueue of registry.values()) {\n      Promise.resolve(sharedQueue.close()).catch(() => {})\n    }\n    registry.clear()\n  }\n  process.once('SIGTERM', shutdown)\n  process.once('SIGINT', shutdown)\n  ;(globalThis as Record<string, unknown>)[EVENTS_PRODUCER_SHUTDOWN_KEY] = true\n}\n\n/**\n * Creates an event bus instance.\n *\n * The event bus provides:\n * - In-memory event delivery to registered handlers\n * - Optional persistence via the queue package when `persistent: true`\n *\n * @param opts - Configuration options\n * @returns An EventBus instance\n *\n * @example\n * ```typescript\n * const bus = createEventBus({\n *   resolve: container.resolve.bind(container),\n *   queueStrategy: 'local', // or 'async' for BullMQ\n * })\n *\n * // Register a handler\n * bus.on('user.created', async (payload, ctx) => {\n *   const userService = ctx.resolve('userService')\n *   await userService.sendWelcomeEmail(payload.userId)\n * })\n *\n * // Emit an event (immediate delivery)\n * await bus.emit('user.created', { userId: '123' })\n *\n * // Emit with persistence (for async worker processing)\n * await bus.emit('order.placed', { orderId: '456' }, { persistent: true })\n * ```\n */\nexport function createEventBus(opts: CreateBusOptions): EventBus {\n  // In-memory listeners for immediate event delivery\n  const listeners = new Map<string, Set<RegisteredSubscriber>>()\n  // Subscribers registered as persistent (worker-dispatched). Used by the\n  // single-delivery path to skip them inline on a persistent emit.\n  const persistentSubscribers = new Set<RegisteredSubscriber>()\n\n  // Determine queue strategy from options or environment\n  const queueStrategy = opts.queueStrategy ??\n    (process.env.QUEUE_STRATEGY === 'async' ? 'async' : 'local')\n\n  // Lazy-initialized queue for persistent events\n  let queue: Queue<EventJobData> | null = null\n\n  /**\n   * Gets or creates the queue instance for persistent events.\n   *\n   * The async (BullMQ) producer is memoized process-wide so the per-request\n   * event bus reuses one Redis connection instead of leaking one per write\n   * request. The local strategy stays per-bus (no pooled connection, cwd-relative\n   * base dir). Set `OM_EVENTS_SHARED_PRODUCER=0` to fall back to per-bus producers.\n   */\n  function getQueue(): Queue<EventJobData> {\n    if (queueStrategy !== 'async' || !isSharedProducerEnabled()) {\n      if (!queue) {\n        queue = queueStrategy === 'async'\n          ? createQueue<EventJobData>(EVENTS_QUEUE_NAME, 'async', {\n              connection: { url: getRedisUrlOrThrow('QUEUE') },\n            })\n          : createQueue<EventJobData>(EVENTS_QUEUE_NAME, 'local')\n      }\n      return queue\n    }\n\n    const redisUrl = getRedisUrlOrThrow('QUEUE')\n    const registry = getProducerQueueRegistry()\n    const cacheKey = `async:${redisUrl}`\n    let shared = registry.get(cacheKey)\n    if (!shared) {\n      shared = createQueue<EventJobData>(EVENTS_QUEUE_NAME, 'async', {\n        connection: { url: redisUrl },\n      })\n      registry.set(cacheKey, shared)\n      registerProducerShutdownHook()\n    }\n    return shared\n  }\n\n  /**\n   * Delivers an event to all registered in-memory handlers.\n   * Supports wildcard pattern matching for event patterns.\n   */\n  async function deliver(\n    event: string,\n    payload: EventPayload,\n    options?: EmitOptions,\n    skipPersistent = false,\n  ): Promise<void> {\n    // Check all registered patterns (including wildcards)\n    for (const [pattern, handlers] of listeners) {\n      if (!matchEventPattern(event, pattern)) continue\n      if (!handlers || handlers.size === 0) continue\n\n      for (const subscriber of handlers) {\n        // Single-delivery: persistent subscribers are dispatched by the worker,\n        // so skip them inline to avoid double execution.\n        if (skipPersistent && persistentSubscribers.has(subscriber)) continue\n        try {\n          // Pass eventName in context for wildcard handlers\n          const moduleId = subscriber.moduleId ?? inferModuleIdFromResourceId(subscriber.id)\n          await withModuleResourceUsage(\n            {\n              moduleId,\n              surface: 'subscriber',\n              operation: `${event} -> ${subscriber.id ?? subscriber.event}`,\n              resourceId: subscriber.id ?? subscriber.event,\n            },\n            () => subscriber.handler(payload, {\n              resolve: opts.resolve,\n              eventName: event,\n              tenantId: options?.tenantId ?? null,\n              organizationId: options?.organizationId ?? null,\n            }),\n          )\n        } catch (error) {\n          logger.error('Handler error', { event, pattern, err: error })\n          if (options?.rethrowHandlerErrors) {\n            throw error\n          }\n        }\n      }\n    }\n  }\n\n  /**\n   * Registers a handler for an event. Pass `moduleId` whenever the subscribing\n   * module is known (e.g. a module reacting to another module's event) so\n   * resource-usage telemetry attributes the handler correctly instead of\n   * guessing a module id from the event name.\n   */\n  function on(\n    event: string,\n    handler: SubscriberHandler,\n    options?: { persistent?: boolean; moduleId?: string; id?: string },\n  ): void {\n    if (!listeners.has(event)) {\n      listeners.set(event, new Set())\n    }\n    const subscriber: RegisteredSubscriber = {\n      id: options?.id,\n      moduleId: options?.moduleId,\n      event,\n      handler,\n      persistent: options?.persistent,\n    }\n    listeners.get(event)!.add(subscriber)\n    if (options?.persistent) {\n      persistentSubscribers.add(subscriber)\n    }\n  }\n\n  /**\n   * Registers multiple module subscribers at once.\n   */\n  function registerModuleSubscribers(subs: SubscriberDescriptor[]): void {\n    for (const sub of subs) {\n      on(sub.event, sub.handler, { persistent: sub.persistent, moduleId: sub.moduleId, id: sub.id })\n    }\n  }\n\n  /**\n   * Emits an event to all registered handlers.\n   *\n   * If `persistent: true`, also enqueues the event for async processing.\n   */\n  async function emit(\n    event: string,\n    payload: EventPayload,\n    options?: EmitOptions\n  ): Promise<void> {\n    const taps = getGlobalEventTaps()\n    for (const tap of taps) {\n      try {\n        await Promise.resolve(tap(event, payload, options))\n      } catch (error) {\n        logger.error('Global tap error', { event, err: error })\n      }\n    }\n\n    // Deliver to in-memory handlers first. Under single-delivery, persistent\n    // subscribers are skipped inline on a persistent emit because the events\n    // worker will dispatch them from the queue.\n    //\n    // `deliverInline: false` on a persistent emit is enqueue-only: skip inline\n    // delivery entirely so a heavy persistent job runs solely in the events\n    // worker, off the caller's request path (the queued enqueue below still\n    // happens). Without this, a persistent emit dual-dispatches by default and\n    // runs the subscriber inline in the caller's request too.\n    const enqueueOnly = Boolean(options?.persistent) && options?.deliverInline === false\n    if (!enqueueOnly) {\n      const skipPersistentInline = Boolean(options?.persistent) && isSingleDeliveryEnabled()\n      await deliver(event, payload, options, skipPersistentInline)\n    }\n\n    if (isBroadcastEvent(event) && hasTenantScope(payload)) {\n      try {\n        await publishCrossProcessEvent(event, payload, options)\n      } catch (error) {\n        logger.error('Cross-process publish error', { event, err: error })\n      }\n    }\n\n    // If persistent, also enqueue for async processing\n    if (options?.persistent) {\n      const q = getQueue()\n      await q.enqueue({ event, payload, options })\n    }\n  }\n\n  /**\n   * Clears all events from the persistent queue.\n   */\n  async function clearQueue(): Promise<{ removed: number }> {\n    const q = getQueue()\n    return q.clear()\n  }\n\n  // Backward compatibility alias\n  const emitEvent = emit\n\n  return {\n    emit,\n    emitEvent, // Alias for backward compatibility\n    on,\n    registerModuleSubscribers,\n    clearQueue,\n  }\n}\n"],
+  "mappings": "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",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/events",
-  "version": "0.6.7",
+  "version": "0.6.8-develop.6875.1.871a4afc94",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -33,14 +33,14 @@
     }
   },
   "dependencies": {
-    "@open-mercato/queue": "0.6.7",
-    "@open-mercato/shared": "0.6.7",
+    "@open-mercato/queue": "0.6.8-develop.6875.1.871a4afc94",
+    "@open-mercato/shared": "0.6.8-develop.6875.1.871a4afc94",
     "pg": "8.22.0"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",
     "jest": "^30.4.2",
-    "ts-jest": "^29.4.11",
+    "ts-jest": "^29.4.12",
     "typescript": "7.0.2"
   },
   "publishConfig": {
@@ -50,5 +50,6 @@
     "type": "git",
     "url": "https://github.com/open-mercato/open-mercato",
     "directory": "packages/events"
-  }
+  },
+  "stableVersion": "0.6.7"
 }

package/src/__tests__/handler-errors.test.ts

@@ -0,0 +1,39 @@
+jest.mock('@open-mercato/queue', () => ({
+  createQueue: jest.fn(() => ({
+    enqueue: jest.fn(),
+    clear: jest.fn(),
+    close: jest.fn(),
+  })),
+}))
+
+const { createEventBus } = require('../bus')
+
+describe('event handler error propagation', () => {
+  const originalConsoleError = console.error
+
+  beforeEach(() => {
+    console.error = jest.fn()
+  })
+
+  afterEach(() => {
+    console.error = originalConsoleError
+  })
+
+  it('keeps handler failures non-blocking by default', async () => {
+    const bus = createEventBus({ resolve: () => undefined })
+    bus.on('demo.failed', async () => {
+      throw new Error('boom')
+    })
+
+    await expect(bus.emit('demo.failed', {})).resolves.toBeUndefined()
+  })
+
+  it('rejects the emit when rethrowHandlerErrors is enabled', async () => {
+    const bus = createEventBus({ resolve: () => undefined })
+    bus.on('demo.failed', async () => {
+      throw new Error('boom')
+    })
+
+    await expect(bus.emit('demo.failed', {}, { rethrowHandlerErrors: true })).rejects.toThrow('boom')
+  })
+})

package/src/bus.ts

@@ -236,6 +236,9 @@ export function createEventBus(opts: CreateBusOptions): EventBus {
           )
         } catch (error) {
           logger.error('Handler error', { event, pattern, err: error })
+          if (options?.rethrowHandlerErrors) {
+            throw error
+          }
         }
       }
     }

package/src/types.ts

@@ -80,6 +80,8 @@ export type EmitOptions = {
   tenantId?: string | null
   /** Trusted organization scope for subscribers that must not rely on payload scope */
   organizationId?: string | null
+  /** Opt-in path for callers that need inline subscriber failures to reject the emit. */
+  rethrowHandlerErrors?: boolean
 }
 
 /** Options for creating an event bus */