@l-etabli/events 0.4.2 → 0.5.0

package/dist/adapters/in-memory/InMemoryEventBus.cjs

@@ -22,6 +22,7 @@ __export(InMemoryEventBus_exports, {
 });
 module.exports = __toCommonJS(InMemoryEventBus_exports);
 var import_createNewEvent = require("../../createNewEvent.ts");
+var import_subscriptions = require("../../subscriptions.ts");
 const createInMemoryEventBus = (withUow, options = {}) => {
   const maxRetries = options.maxRetries ?? 3;
   const createNewEvent = (0, import_createNewEvent.makeCreateNewEvent)({
@@ -48,7 +49,7 @@ const createInMemoryEventBus = (withUow, options = {}) => {
     const lastPublication = event.publications.reduce(
       (latest, current) => current.publishedAt > latest.publishedAt ? current : latest
     );
-    const failedSubscriptionIds = lastPublication.failures.map(
+    const failedSubscriptionIds = (lastPublication.failures ?? []).map(
       (failure) => failure.subscriptionId
     );
     return allSubscriptionIds.filter(
@@ -63,8 +64,7 @@ const createInMemoryEventBus = (withUow, options = {}) => {
       if (!callbacksBySubscriptionSlug) {
         event.publications.push({
           publishedAt,
-          publishedSubscribers: [],
-          failures: []
+          publishedSubscribers: []
         });
         event.status = "published";
         await withUow(async (uow) => {
@@ -95,7 +95,7 @@ const createInMemoryEventBus = (withUow, options = {}) => {
           publishedSubscribers: subscriptionIdsToPublish.map(
             (id) => id
           ),
-          failures
+          ...failures.length > 0 && { failures }
         }
       ];
       if (failures.length === 0) {
@@ -119,7 +119,20 @@ const createInMemoryEventBus = (withUow, options = {}) => {
       }
     }
   };
-  return { eventBus, createNewEvent };
+  const defineSubscriptions = (subscriptions2) => subscriptions2;
+  const subscribeAll = (subscriptions2) => {
+    (0, import_subscriptions.subscribeByTopic)(eventBus, subscriptions2);
+  };
+  const subscribeGlobal = (subscriptions2, config) => {
+    (0, import_subscriptions.subscribeGlobalToTopics)(eventBus, subscriptions2, config);
+  };
+  return {
+    eventBus,
+    createNewEvent,
+    defineSubscriptions,
+    subscribeAll,
+    subscribeGlobal
+  };
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/adapters/in-memory/InMemoryEventBus.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/adapters/in-memory/InMemoryEventBus.ts"],"sourcesContent":["import { makeCreateNewEvent } from \"../../createNewEvent.ts\";\nimport type { EventBus } from \"../../ports/EventBus.ts\";\nimport type { WithEventsUow } from \"../../ports/EventRepository.ts\";\nimport type {\n  DefaultContext,\n  EventId,\n  EventPublication,\n  GenericEvent,\n  SubscriptionId,\n} from \"../../types.ts\";\n\ntype SubscriptionsForTopic = Record<\n  string,\n  (event: GenericEvent<string, unknown, DefaultContext>) => Promise<void>\n>;\n\ntype CreateInMemoryEventBusOptions = {\n  maxRetries?: number;\n  getNow?: () => Date;\n  generateId?: () => EventId;\n};\n\nexport const createInMemoryEventBus = <\n  Event extends GenericEvent<string, unknown, DefaultContext>,\n>(\n  withUow: WithEventsUow<Event>,\n  options: CreateInMemoryEventBusOptions = {},\n) => {\n  const maxRetries = options.maxRetries ?? 3;\n  const createNewEvent = makeCreateNewEvent<Event>({\n    getNow: options.getNow,\n    generateId: options.generateId,\n  });\n  const subscriptions: Partial<Record<string, SubscriptionsForTopic>> = {};\n\n  const executeCallback = async (\n    event: Event,\n    subscriptionId: string,\n    callback: (\n      event: GenericEvent<string, unknown, DefaultContext>,\n    ) => Promise<void>,\n  ): Promise<\n    { subscriptionId: string; errorMessage: string; stack?: string } | undefined\n  > => {\n    try {\n      await callback(event);\n    } catch (error) {\n      return {\n        subscriptionId,\n        errorMessage: error instanceof Error ? error.message : String(error),\n        stack: error instanceof Error ? error.stack : undefined,\n      };\n    }\n  };\n\n  const getSubscriptionIdsToPublish = (\n    event: Event,\n    callbacksBySubscriptionId: SubscriptionsForTopic,\n  ): string[] => {\n    const allSubscriptionIds = Object.keys(callbacksBySubscriptionId);\n\n    if (event.publications.length === 0 || event.status === \"to-republish\") {\n      return allSubscriptionIds;\n    }\n\n    const lastPublication = event.publications.reduce((latest, current) =>\n      current.publishedAt > latest.publishedAt ? current : latest,\n    );\n    const failedSubscriptionIds = lastPublication.failures.map(\n      (failure) => failure.subscriptionId,\n    );\n\n    return allSubscriptionIds.filter((id) =>\n      failedSubscriptionIds.includes(id),\n    );\n  };\n\n  const eventBus: EventBus<Event> = {\n    publish: async (event) => {\n      const publishedAt = new Date();\n      const topic = event.topic;\n\n      const callbacksBySubscriptionSlug = subscriptions[topic];\n\n      if (!callbacksBySubscriptionSlug) {\n        event.publications.push({\n          publishedAt,\n          publishedSubscribers: [],\n          failures: [],\n        });\n        event.status = \"published\";\n        await withUow(async (uow) => {\n          await uow.eventRepository.save(event);\n        });\n        return;\n      }\n\n      const subscriptionIdsToPublish = getSubscriptionIdsToPublish(\n        event,\n        callbacksBySubscriptionSlug,\n      );\n\n      const failuresOrUndefined = await Promise.all(\n        subscriptionIdsToPublish.map((subscriptionId) =>\n          executeCallback(\n            event,\n            subscriptionId,\n            callbacksBySubscriptionSlug[subscriptionId],\n          ),\n        ),\n      );\n\n      const failures = failuresOrUndefined.filter(\n        (\n          f,\n        ): f is {\n          subscriptionId: string;\n          errorMessage: string;\n          stack?: string;\n        } => f !== undefined,\n      );\n\n      const publications: EventPublication[] = [\n        ...event.publications,\n        {\n          publishedAt,\n          publishedSubscribers: subscriptionIdsToPublish.map(\n            (id) => id as SubscriptionId,\n          ),\n          failures,\n        },\n      ];\n\n      if (failures.length === 0) {\n        event.status = \"published\";\n      } else {\n        const wasMaxNumberOfErrorsReached = publications.length >= maxRetries;\n        event.status = wasMaxNumberOfErrorsReached\n          ? \"quarantined\"\n          : \"failed-but-will-retry\";\n      }\n\n      event.publications = publications;\n\n      await withUow(async (uow) => {\n        await uow.eventRepository.save(event);\n      });\n    },\n\n    subscribe: ({ topic, subscriptionId, callBack }) => {\n      if (!subscriptions[topic]) {\n        subscriptions[topic] = {};\n      }\n\n      const subscriptionsForTopic = subscriptions[topic];\n      if (subscriptionsForTopic) {\n        subscriptionsForTopic[subscriptionId] = callBack as (\n          event: GenericEvent<string, unknown, DefaultContext>,\n        ) => Promise<void>;\n      }\n    },\n  };\n\n  return { eventBus, createNewEvent };\n};\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../../src/adapters/in-memory/InMemoryEventBus.ts"],"sourcesContent":["import { makeCreateNewEvent } from \"../../createNewEvent.ts\";\nimport type { EventBus } from \"../../ports/EventBus.ts\";\nimport type { WithEventsUow } from \"../../ports/EventRepository.ts\";\nimport {\n  type GlobalSubscriberConfig,\n  subscribeByTopic,\n  subscribeGlobalToTopics,\n  type TopicSubscriptions,\n} from \"../../subscriptions.ts\";\nimport type {\n  DefaultContext,\n  EventId,\n  EventPublication,\n  GenericEvent,\n  SubscriptionId,\n} from \"../../types.ts\";\n\ntype SubscriptionsForTopic = Record<\n  string,\n  (event: GenericEvent<string, unknown, DefaultContext>) => Promise<void>\n>;\n\ntype CreateInMemoryEventBusOptions = {\n  maxRetries?: number;\n  getNow?: () => Date;\n  generateId?: () => EventId;\n};\n\nexport const createInMemoryEventBus = <\n  Event extends GenericEvent<string, unknown, DefaultContext>,\n>(\n  withUow: WithEventsUow<Event>,\n  options: CreateInMemoryEventBusOptions = {},\n) => {\n  const maxRetries = options.maxRetries ?? 3;\n  const createNewEvent = makeCreateNewEvent<Event>({\n    getNow: options.getNow,\n    generateId: options.generateId,\n  });\n  const subscriptions: Partial<Record<string, SubscriptionsForTopic>> = {};\n\n  const executeCallback = async (\n    event: Event,\n    subscriptionId: string,\n    callback: (\n      event: GenericEvent<string, unknown, DefaultContext>,\n    ) => Promise<void>,\n  ): Promise<\n    { subscriptionId: string; errorMessage: string; stack?: string } | undefined\n  > => {\n    try {\n      await callback(event);\n    } catch (error) {\n      return {\n        subscriptionId,\n        errorMessage: error instanceof Error ? error.message : String(error),\n        stack: error instanceof Error ? error.stack : undefined,\n      };\n    }\n  };\n\n  const getSubscriptionIdsToPublish = (\n    event: Event,\n    callbacksBySubscriptionId: SubscriptionsForTopic,\n  ): string[] => {\n    const allSubscriptionIds = Object.keys(callbacksBySubscriptionId);\n\n    if (event.publications.length === 0 || event.status === \"to-republish\") {\n      return allSubscriptionIds;\n    }\n\n    const lastPublication = event.publications.reduce((latest, current) =>\n      current.publishedAt > latest.publishedAt ? current : latest,\n    );\n    const failedSubscriptionIds = (lastPublication.failures ?? []).map(\n      (failure) => failure.subscriptionId,\n    );\n\n    return allSubscriptionIds.filter((id) =>\n      failedSubscriptionIds.includes(id),\n    );\n  };\n\n  const eventBus: EventBus<Event> = {\n    publish: async (event) => {\n      const publishedAt = new Date();\n      const topic = event.topic;\n\n      const callbacksBySubscriptionSlug = subscriptions[topic];\n\n      if (!callbacksBySubscriptionSlug) {\n        event.publications.push({\n          publishedAt,\n          publishedSubscribers: [],\n        });\n        event.status = \"published\";\n        await withUow(async (uow) => {\n          await uow.eventRepository.save(event);\n        });\n        return;\n      }\n\n      const subscriptionIdsToPublish = getSubscriptionIdsToPublish(\n        event,\n        callbacksBySubscriptionSlug,\n      );\n\n      const failuresOrUndefined = await Promise.all(\n        subscriptionIdsToPublish.map((subscriptionId) =>\n          executeCallback(\n            event,\n            subscriptionId,\n            callbacksBySubscriptionSlug[subscriptionId],\n          ),\n        ),\n      );\n\n      const failures = failuresOrUndefined.filter(\n        (\n          f,\n        ): f is {\n          subscriptionId: string;\n          errorMessage: string;\n          stack?: string;\n        } => f !== undefined,\n      );\n\n      const publications: EventPublication[] = [\n        ...event.publications,\n        {\n          publishedAt,\n          publishedSubscribers: subscriptionIdsToPublish.map(\n            (id) => id as SubscriptionId,\n          ),\n          ...(failures.length > 0 && { failures }),\n        },\n      ];\n\n      if (failures.length === 0) {\n        event.status = \"published\";\n      } else {\n        const wasMaxNumberOfErrorsReached = publications.length >= maxRetries;\n        event.status = wasMaxNumberOfErrorsReached\n          ? \"quarantined\"\n          : \"failed-but-will-retry\";\n      }\n\n      event.publications = publications;\n\n      await withUow(async (uow) => {\n        await uow.eventRepository.save(event);\n      });\n    },\n\n    subscribe: ({ topic, subscriptionId, callBack }) => {\n      if (!subscriptions[topic]) {\n        subscriptions[topic] = {};\n      }\n\n      const subscriptionsForTopic = subscriptions[topic];\n      if (subscriptionsForTopic) {\n        subscriptionsForTopic[subscriptionId] = callBack as (\n          event: GenericEvent<string, unknown, DefaultContext>,\n        ) => Promise<void>;\n      }\n    },\n  };\n\n  /**\n   * Identity function for type inference when defining subscription maps.\n   * Ensures all topics are covered and handlers have correct payload types.\n   *\n   * @example\n   * ```typescript\n   * const subscriptions = defineSubscriptions({\n   *   OrderCreated: [{ subscriptionId: \"notify\", handler: async (e) => {...} }],\n   *   OrderShipped: [], // Required even if empty\n   * });\n   * ```\n   */\n  const defineSubscriptions = (\n    subscriptions: TopicSubscriptions<Event>,\n  ): TopicSubscriptions<Event> => subscriptions;\n\n  /**\n   * Subscribe all handlers from a topic subscription map to this event bus.\n   *\n   * @example\n   * ```typescript\n   * const subscriptions = defineSubscriptions({...});\n   * subscribeAll(subscriptions);\n   * ```\n   */\n  const subscribeAll = (subscriptions: TopicSubscriptions<Event>): void => {\n    subscribeByTopic(eventBus, subscriptions);\n  };\n\n  /**\n   * Subscribe a global handler to multiple topics with optional filtering.\n   *\n   * @example\n   * ```typescript\n   * subscribeGlobal(subscriptions, {\n   *   subscriptionId: \"audit-log\",\n   *   handler: async (event) => auditLog.record(event),\n   *   filter: { exclude: [\"NotificationAdded\"] },\n   * });\n   * ```\n   */\n  const subscribeGlobal = (\n    subscriptions: TopicSubscriptions<Event>,\n    config: GlobalSubscriberConfig<Event>,\n  ): void => {\n    subscribeGlobalToTopics(eventBus, subscriptions, config);\n  };\n\n  return {\n    eventBus,\n    createNewEvent,\n    defineSubscriptions,\n    subscribeAll,\n    subscribeGlobal,\n  };\n};\n"],"mappings":"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","names":["subscriptions"]}

package/dist/adapters/in-memory/InMemoryEventBus.d.cts

@@ -1,6 +1,7 @@
 import { CreateNewEvent } from '../../createNewEvent.cjs';
 import { EventBus } from '../../ports/EventBus.cjs';
 import { WithEventsUow } from '../../ports/EventRepository.cjs';
+import { TopicSubscriptions, GlobalSubscriberConfig } from '../../subscriptions.cjs';
 import { GenericEvent, DefaultContext, EventId } from '../../types.cjs';
 
 type CreateInMemoryEventBusOptions = {
@@ -11,6 +12,9 @@ type CreateInMemoryEventBusOptions = {
 declare const createInMemoryEventBus: <Event extends GenericEvent<string, unknown, DefaultContext>>(withUow: WithEventsUow<Event>, options?: CreateInMemoryEventBusOptions) => {
     eventBus: EventBus<Event>;
     createNewEvent: CreateNewEvent<Event>;
+    defineSubscriptions: (subscriptions: TopicSubscriptions<Event>) => TopicSubscriptions<Event>;
+    subscribeAll: (subscriptions: TopicSubscriptions<Event>) => void;
+    subscribeGlobal: (subscriptions: TopicSubscriptions<Event>, config: GlobalSubscriberConfig<Event>) => void;
 };
 
 export { createInMemoryEventBus };

package/dist/adapters/in-memory/InMemoryEventBus.d.ts

@@ -1,6 +1,7 @@
 import { CreateNewEvent } from '../../createNewEvent.js';
 import { EventBus } from '../../ports/EventBus.js';
 import { WithEventsUow } from '../../ports/EventRepository.js';
+import { TopicSubscriptions, GlobalSubscriberConfig } from '../../subscriptions.js';
 import { GenericEvent, DefaultContext, EventId } from '../../types.js';
 
 type CreateInMemoryEventBusOptions = {
@@ -11,6 +12,9 @@ type CreateInMemoryEventBusOptions = {
 declare const createInMemoryEventBus: <Event extends GenericEvent<string, unknown, DefaultContext>>(withUow: WithEventsUow<Event>, options?: CreateInMemoryEventBusOptions) => {
     eventBus: EventBus<Event>;
     createNewEvent: CreateNewEvent<Event>;
+    defineSubscriptions: (subscriptions: TopicSubscriptions<Event>) => TopicSubscriptions<Event>;
+    subscribeAll: (subscriptions: TopicSubscriptions<Event>) => void;
+    subscribeGlobal: (subscriptions: TopicSubscriptions<Event>, config: GlobalSubscriberConfig<Event>) => void;
 };
 
 export { createInMemoryEventBus };

package/dist/adapters/in-memory/InMemoryEventBus.mjs

@@ -1,4 +1,8 @@
 import { makeCreateNewEvent } from "../../createNewEvent.mjs";
+import {
+  subscribeByTopic,
+  subscribeGlobalToTopics
+} from "../../subscriptions.mjs";
 const createInMemoryEventBus = (withUow, options = {}) => {
   const maxRetries = options.maxRetries ?? 3;
   const createNewEvent = makeCreateNewEvent({
@@ -25,7 +29,7 @@ const createInMemoryEventBus = (withUow, options = {}) => {
     const lastPublication = event.publications.reduce(
       (latest, current) => current.publishedAt > latest.publishedAt ? current : latest
     );
-    const failedSubscriptionIds = lastPublication.failures.map(
+    const failedSubscriptionIds = (lastPublication.failures ?? []).map(
       (failure) => failure.subscriptionId
     );
     return allSubscriptionIds.filter(
@@ -40,8 +44,7 @@ const createInMemoryEventBus = (withUow, options = {}) => {
       if (!callbacksBySubscriptionSlug) {
         event.publications.push({
           publishedAt,
-          publishedSubscribers: [],
-          failures: []
+          publishedSubscribers: []
         });
         event.status = "published";
         await withUow(async (uow) => {
@@ -72,7 +75,7 @@ const createInMemoryEventBus = (withUow, options = {}) => {
           publishedSubscribers: subscriptionIdsToPublish.map(
             (id) => id
           ),
-          failures
+          ...failures.length > 0 && { failures }
         }
       ];
       if (failures.length === 0) {
@@ -96,7 +99,20 @@ const createInMemoryEventBus = (withUow, options = {}) => {
       }
     }
   };
-  return { eventBus, createNewEvent };
+  const defineSubscriptions = (subscriptions2) => subscriptions2;
+  const subscribeAll = (subscriptions2) => {
+    subscribeByTopic(eventBus, subscriptions2);
+  };
+  const subscribeGlobal = (subscriptions2, config) => {
+    subscribeGlobalToTopics(eventBus, subscriptions2, config);
+  };
+  return {
+    eventBus,
+    createNewEvent,
+    defineSubscriptions,
+    subscribeAll,
+    subscribeGlobal
+  };
 };
 export {
   createInMemoryEventBus

package/dist/adapters/in-memory/InMemoryEventBus.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/adapters/in-memory/InMemoryEventBus.ts"],"sourcesContent":["import { makeCreateNewEvent } from '../../createNewEvent.mjs';\nimport type { EventBus } from '../../ports/EventBus.mjs';\nimport type { WithEventsUow } from '../../ports/EventRepository.mjs';\nimport type {\n  DefaultContext,\n  EventId,\n  EventPublication,\n  GenericEvent,\n  SubscriptionId,\n} from '../../types.mjs';\n\ntype SubscriptionsForTopic = Record<\n  string,\n  (event: GenericEvent<string, unknown, DefaultContext>) => Promise<void>\n>;\n\ntype CreateInMemoryEventBusOptions = {\n  maxRetries?: number;\n  getNow?: () => Date;\n  generateId?: () => EventId;\n};\n\nexport const createInMemoryEventBus = <\n  Event extends GenericEvent<string, unknown, DefaultContext>,\n>(\n  withUow: WithEventsUow<Event>,\n  options: CreateInMemoryEventBusOptions = {},\n) => {\n  const maxRetries = options.maxRetries ?? 3;\n  const createNewEvent = makeCreateNewEvent<Event>({\n    getNow: options.getNow,\n    generateId: options.generateId,\n  });\n  const subscriptions: Partial<Record<string, SubscriptionsForTopic>> = {};\n\n  const executeCallback = async (\n    event: Event,\n    subscriptionId: string,\n    callback: (\n      event: GenericEvent<string, unknown, DefaultContext>,\n    ) => Promise<void>,\n  ): Promise<\n    { subscriptionId: string; errorMessage: string; stack?: string } | undefined\n  > => {\n    try {\n      await callback(event);\n    } catch (error) {\n      return {\n        subscriptionId,\n        errorMessage: error instanceof Error ? error.message : String(error),\n        stack: error instanceof Error ? error.stack : undefined,\n      };\n    }\n  };\n\n  const getSubscriptionIdsToPublish = (\n    event: Event,\n    callbacksBySubscriptionId: SubscriptionsForTopic,\n  ): string[] => {\n    const allSubscriptionIds = Object.keys(callbacksBySubscriptionId);\n\n    if (event.publications.length === 0 || event.status === \"to-republish\") {\n      return allSubscriptionIds;\n    }\n\n    const lastPublication = event.publications.reduce((latest, current) =>\n      current.publishedAt > latest.publishedAt ? current : latest,\n    );\n    const failedSubscriptionIds = lastPublication.failures.map(\n      (failure) => failure.subscriptionId,\n    );\n\n    return allSubscriptionIds.filter((id) =>\n      failedSubscriptionIds.includes(id),\n    );\n  };\n\n  const eventBus: EventBus<Event> = {\n    publish: async (event) => {\n      const publishedAt = new Date();\n      const topic = event.topic;\n\n      const callbacksBySubscriptionSlug = subscriptions[topic];\n\n      if (!callbacksBySubscriptionSlug) {\n        event.publications.push({\n          publishedAt,\n          publishedSubscribers: [],\n          failures: [],\n        });\n        event.status = \"published\";\n        await withUow(async (uow) => {\n          await uow.eventRepository.save(event);\n        });\n        return;\n      }\n\n      const subscriptionIdsToPublish = getSubscriptionIdsToPublish(\n        event,\n        callbacksBySubscriptionSlug,\n      );\n\n      const failuresOrUndefined = await Promise.all(\n        subscriptionIdsToPublish.map((subscriptionId) =>\n          executeCallback(\n            event,\n            subscriptionId,\n            callbacksBySubscriptionSlug[subscriptionId],\n          ),\n        ),\n      );\n\n      const failures = failuresOrUndefined.filter(\n        (\n          f,\n        ): f is {\n          subscriptionId: string;\n          errorMessage: string;\n          stack?: string;\n        } => f !== undefined,\n      );\n\n      const publications: EventPublication[] = [\n        ...event.publications,\n        {\n          publishedAt,\n          publishedSubscribers: subscriptionIdsToPublish.map(\n            (id) => id as SubscriptionId,\n          ),\n          failures,\n        },\n      ];\n\n      if (failures.length === 0) {\n        event.status = \"published\";\n      } else {\n        const wasMaxNumberOfErrorsReached = publications.length >= maxRetries;\n        event.status = wasMaxNumberOfErrorsReached\n          ? \"quarantined\"\n          : \"failed-but-will-retry\";\n      }\n\n      event.publications = publications;\n\n      await withUow(async (uow) => {\n        await uow.eventRepository.save(event);\n      });\n    },\n\n    subscribe: ({ topic, subscriptionId, callBack }) => {\n      if (!subscriptions[topic]) {\n        subscriptions[topic] = {};\n      }\n\n      const subscriptionsForTopic = subscriptions[topic];\n      if (subscriptionsForTopic) {\n        subscriptionsForTopic[subscriptionId] = callBack as (\n          event: GenericEvent<string, unknown, DefaultContext>,\n        ) => Promise<void>;\n      }\n    },\n  };\n\n  return { eventBus, createNewEvent };\n};\n"],"mappings":"AAAA,SAAS,0BAA0B;AAsB5B,MAAM,yBAAyB,CAGpC,SACA,UAAyC,CAAC,MACvC;AACH,QAAM,aAAa,QAAQ,cAAc;AACzC,QAAM,iBAAiB,mBAA0B;AAAA,IAC/C,QAAQ,QAAQ;AAAA,IAChB,YAAY,QAAQ;AAAA,EACtB,CAAC;AACD,QAAM,gBAAgE,CAAC;AAEvE,QAAM,kBAAkB,OACtB,OACA,gBACA,aAKG;AACH,QAAI;AACF,YAAM,SAAS,KAAK;AAAA,IACtB,SAAS,OAAO;AACd,aAAO;AAAA,QACL;AAAA,QACA,cAAc,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;AAAA,QACnE,OAAO,iBAAiB,QAAQ,MAAM,QAAQ;AAAA,MAChD;AAAA,IACF;AAAA,EACF;AAEA,QAAM,8BAA8B,CAClC,OACA,8BACa;AACb,UAAM,qBAAqB,OAAO,KAAK,yBAAyB;AAEhE,QAAI,MAAM,aAAa,WAAW,KAAK,MAAM,WAAW,gBAAgB;AACtE,aAAO;AAAA,IACT;AAEA,UAAM,kBAAkB,MAAM,aAAa;AAAA,MAAO,CAAC,QAAQ,YACzD,QAAQ,cAAc,OAAO,cAAc,UAAU;AAAA,IACvD;AACA,UAAM,wBAAwB,gBAAgB,SAAS;AAAA,MACrD,CAAC,YAAY,QAAQ;AAAA,IACvB;AAEA,WAAO,mBAAmB;AAAA,MAAO,CAAC,OAChC,sBAAsB,SAAS,EAAE;AAAA,IACnC;AAAA,EACF;AAEA,QAAM,WAA4B;AAAA,IAChC,SAAS,OAAO,UAAU;AACxB,YAAM,cAAc,oBAAI,KAAK;AAC7B,YAAM,QAAQ,MAAM;AAEpB,YAAM,8BAA8B,cAAc,KAAK;AAEvD,UAAI,CAAC,6BAA6B;AAChC,cAAM,aAAa,KAAK;AAAA,UACtB;AAAA,UACA,sBAAsB,CAAC;AAAA,UACvB,UAAU,CAAC;AAAA,QACb,CAAC;AACD,cAAM,SAAS;AACf,cAAM,QAAQ,OAAO,QAAQ;AAC3B,gBAAM,IAAI,gBAAgB,KAAK,KAAK;AAAA,QACtC,CAAC;AACD;AAAA,MACF;AAEA,YAAM,2BAA2B;AAAA,QAC/B;AAAA,QACA;AAAA,MACF;AAEA,YAAM,sBAAsB,MAAM,QAAQ;AAAA,QACxC,yBAAyB;AAAA,UAAI,CAAC,mBAC5B;AAAA,YACE;AAAA,YACA;AAAA,YACA,4BAA4B,cAAc;AAAA,UAC5C;AAAA,QACF;AAAA,MACF;AAEA,YAAM,WAAW,oBAAoB;AAAA,QACnC,CACE,MAKG,MAAM;AAAA,MACb;AAEA,YAAM,eAAmC;AAAA,QACvC,GAAG,MAAM;AAAA,QACT;AAAA,UACE;AAAA,UACA,sBAAsB,yBAAyB;AAAA,YAC7C,CAAC,OAAO;AAAA,UACV;AAAA,UACA;AAAA,QACF;AAAA,MACF;AAEA,UAAI,SAAS,WAAW,GAAG;AACzB,cAAM,SAAS;AAAA,MACjB,OAAO;AACL,cAAM,8BAA8B,aAAa,UAAU;AAC3D,cAAM,SAAS,8BACX,gBACA;AAAA,MACN;AAEA,YAAM,eAAe;AAErB,YAAM,QAAQ,OAAO,QAAQ;AAC3B,cAAM,IAAI,gBAAgB,KAAK,KAAK;AAAA,MACtC,CAAC;AAAA,IACH;AAAA,IAEA,WAAW,CAAC,EAAE,OAAO,gBAAgB,SAAS,MAAM;AAClD,UAAI,CAAC,cAAc,KAAK,GAAG;AACzB,sBAAc,KAAK,IAAI,CAAC;AAAA,MAC1B;AAEA,YAAM,wBAAwB,cAAc,KAAK;AACjD,UAAI,uBAAuB;AACzB,8BAAsB,cAAc,IAAI;AAAA,MAG1C;AAAA,IACF;AAAA,EACF;AAEA,SAAO,EAAE,UAAU,eAAe;AACpC;","names":[]}
+{"version":3,"sources":["../../../src/adapters/in-memory/InMemoryEventBus.ts"],"sourcesContent":["import { makeCreateNewEvent } from '../../createNewEvent.mjs';\nimport type { EventBus } from '../../ports/EventBus.mjs';\nimport type { WithEventsUow } from '../../ports/EventRepository.mjs';\nimport {\n  type GlobalSubscriberConfig,\n  subscribeByTopic,\n  subscribeGlobalToTopics,\n  type TopicSubscriptions,\n} from '../../subscriptions.mjs';\nimport type {\n  DefaultContext,\n  EventId,\n  EventPublication,\n  GenericEvent,\n  SubscriptionId,\n} from '../../types.mjs';\n\ntype SubscriptionsForTopic = Record<\n  string,\n  (event: GenericEvent<string, unknown, DefaultContext>) => Promise<void>\n>;\n\ntype CreateInMemoryEventBusOptions = {\n  maxRetries?: number;\n  getNow?: () => Date;\n  generateId?: () => EventId;\n};\n\nexport const createInMemoryEventBus = <\n  Event extends GenericEvent<string, unknown, DefaultContext>,\n>(\n  withUow: WithEventsUow<Event>,\n  options: CreateInMemoryEventBusOptions = {},\n) => {\n  const maxRetries = options.maxRetries ?? 3;\n  const createNewEvent = makeCreateNewEvent<Event>({\n    getNow: options.getNow,\n    generateId: options.generateId,\n  });\n  const subscriptions: Partial<Record<string, SubscriptionsForTopic>> = {};\n\n  const executeCallback = async (\n    event: Event,\n    subscriptionId: string,\n    callback: (\n      event: GenericEvent<string, unknown, DefaultContext>,\n    ) => Promise<void>,\n  ): Promise<\n    { subscriptionId: string; errorMessage: string; stack?: string } | undefined\n  > => {\n    try {\n      await callback(event);\n    } catch (error) {\n      return {\n        subscriptionId,\n        errorMessage: error instanceof Error ? error.message : String(error),\n        stack: error instanceof Error ? error.stack : undefined,\n      };\n    }\n  };\n\n  const getSubscriptionIdsToPublish = (\n    event: Event,\n    callbacksBySubscriptionId: SubscriptionsForTopic,\n  ): string[] => {\n    const allSubscriptionIds = Object.keys(callbacksBySubscriptionId);\n\n    if (event.publications.length === 0 || event.status === \"to-republish\") {\n      return allSubscriptionIds;\n    }\n\n    const lastPublication = event.publications.reduce((latest, current) =>\n      current.publishedAt > latest.publishedAt ? current : latest,\n    );\n    const failedSubscriptionIds = (lastPublication.failures ?? []).map(\n      (failure) => failure.subscriptionId,\n    );\n\n    return allSubscriptionIds.filter((id) =>\n      failedSubscriptionIds.includes(id),\n    );\n  };\n\n  const eventBus: EventBus<Event> = {\n    publish: async (event) => {\n      const publishedAt = new Date();\n      const topic = event.topic;\n\n      const callbacksBySubscriptionSlug = subscriptions[topic];\n\n      if (!callbacksBySubscriptionSlug) {\n        event.publications.push({\n          publishedAt,\n          publishedSubscribers: [],\n        });\n        event.status = \"published\";\n        await withUow(async (uow) => {\n          await uow.eventRepository.save(event);\n        });\n        return;\n      }\n\n      const subscriptionIdsToPublish = getSubscriptionIdsToPublish(\n        event,\n        callbacksBySubscriptionSlug,\n      );\n\n      const failuresOrUndefined = await Promise.all(\n        subscriptionIdsToPublish.map((subscriptionId) =>\n          executeCallback(\n            event,\n            subscriptionId,\n            callbacksBySubscriptionSlug[subscriptionId],\n          ),\n        ),\n      );\n\n      const failures = failuresOrUndefined.filter(\n        (\n          f,\n        ): f is {\n          subscriptionId: string;\n          errorMessage: string;\n          stack?: string;\n        } => f !== undefined,\n      );\n\n      const publications: EventPublication[] = [\n        ...event.publications,\n        {\n          publishedAt,\n          publishedSubscribers: subscriptionIdsToPublish.map(\n            (id) => id as SubscriptionId,\n          ),\n          ...(failures.length > 0 && { failures }),\n        },\n      ];\n\n      if (failures.length === 0) {\n        event.status = \"published\";\n      } else {\n        const wasMaxNumberOfErrorsReached = publications.length >= maxRetries;\n        event.status = wasMaxNumberOfErrorsReached\n          ? \"quarantined\"\n          : \"failed-but-will-retry\";\n      }\n\n      event.publications = publications;\n\n      await withUow(async (uow) => {\n        await uow.eventRepository.save(event);\n      });\n    },\n\n    subscribe: ({ topic, subscriptionId, callBack }) => {\n      if (!subscriptions[topic]) {\n        subscriptions[topic] = {};\n      }\n\n      const subscriptionsForTopic = subscriptions[topic];\n      if (subscriptionsForTopic) {\n        subscriptionsForTopic[subscriptionId] = callBack as (\n          event: GenericEvent<string, unknown, DefaultContext>,\n        ) => Promise<void>;\n      }\n    },\n  };\n\n  /**\n   * Identity function for type inference when defining subscription maps.\n   * Ensures all topics are covered and handlers have correct payload types.\n   *\n   * @example\n   * ```typescript\n   * const subscriptions = defineSubscriptions({\n   *   OrderCreated: [{ subscriptionId: \"notify\", handler: async (e) => {...} }],\n   *   OrderShipped: [], // Required even if empty\n   * });\n   * ```\n   */\n  const defineSubscriptions = (\n    subscriptions: TopicSubscriptions<Event>,\n  ): TopicSubscriptions<Event> => subscriptions;\n\n  /**\n   * Subscribe all handlers from a topic subscription map to this event bus.\n   *\n   * @example\n   * ```typescript\n   * const subscriptions = defineSubscriptions({...});\n   * subscribeAll(subscriptions);\n   * ```\n   */\n  const subscribeAll = (subscriptions: TopicSubscriptions<Event>): void => {\n    subscribeByTopic(eventBus, subscriptions);\n  };\n\n  /**\n   * Subscribe a global handler to multiple topics with optional filtering.\n   *\n   * @example\n   * ```typescript\n   * subscribeGlobal(subscriptions, {\n   *   subscriptionId: \"audit-log\",\n   *   handler: async (event) => auditLog.record(event),\n   *   filter: { exclude: [\"NotificationAdded\"] },\n   * });\n   * ```\n   */\n  const subscribeGlobal = (\n    subscriptions: TopicSubscriptions<Event>,\n    config: GlobalSubscriberConfig<Event>,\n  ): void => {\n    subscribeGlobalToTopics(eventBus, subscriptions, config);\n  };\n\n  return {\n    eventBus,\n    createNewEvent,\n    defineSubscriptions,\n    subscribeAll,\n    subscribeGlobal,\n  };\n};\n"],"mappings":"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","names":["subscriptions"]}

package/dist/adapters/in-memory/index.d.cts

@@ -7,6 +7,7 @@ export { createInMemoryEventBus } from './InMemoryEventBus.cjs';
 export { createInMemoryEventQueries } from './InMemoryEventQueries.cjs';
 import '../../createNewEvent.cjs';
 import '../../ports/EventBus.cjs';
+import '../../subscriptions.cjs';
 
 declare const createInMemoryEventRepositoryAndQueries: <Event extends GenericEvent<string, unknown, DefaultContext>>() => {
     eventRepository: EventRepository<Event>;

package/dist/adapters/in-memory/index.d.ts

@@ -7,6 +7,7 @@ export { createInMemoryEventBus } from './InMemoryEventBus.js';
 export { createInMemoryEventQueries } from './InMemoryEventQueries.js';
 import '../../createNewEvent.js';
 import '../../ports/EventBus.js';
+import '../../subscriptions.js';
 
 declare const createInMemoryEventRepositoryAndQueries: <Event extends GenericEvent<string, unknown, DefaultContext>>() => {
     eventRepository: EventRepository<Event>;

package/dist/index.cjs

@@ -18,10 +18,12 @@ module.exports = __toCommonJS(index_exports);
 __reExport(index_exports, require("./adapters/in-memory/index.ts"), module.exports);
 __reExport(index_exports, require("./createEventCrawler.ts"), module.exports);
 __reExport(index_exports, require("./createNewEvent.ts"), module.exports);
+__reExport(index_exports, require("./subscriptions.ts"), module.exports);
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ...require("./adapters/in-memory/index.ts"),
   ...require("./createEventCrawler.ts"),
-  ...require("./createNewEvent.ts")
+  ...require("./createNewEvent.ts"),
+  ...require("./subscriptions.ts")
 });
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from \"./adapters/in-memory/index.ts\";\nexport * from \"./createEventCrawler.ts\";\nexport * from \"./createNewEvent.ts\";\nexport type * from \"./ports/EventBus.ts\";\nexport type * from \"./ports/EventQueries.ts\";\nexport type * from \"./ports/EventRepository.ts\";\nexport type * from \"./types.ts\";\n"],"mappings":";;;;;;;;;;;;;;;AAAA;AAAA;AAAA,0BAAc,0CAAd;AACA,0BAAc,oCADd;AAEA,0BAAc,gCAFd;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from \"./adapters/in-memory/index.ts\";\nexport * from \"./createEventCrawler.ts\";\nexport * from \"./createNewEvent.ts\";\nexport type * from \"./ports/EventBus.ts\";\nexport type * from \"./ports/EventQueries.ts\";\nexport type * from \"./ports/EventRepository.ts\";\nexport * from \"./subscriptions.ts\";\nexport type * from \"./types.ts\";\n"],"mappings":";;;;;;;;;;;;;;;AAAA;AAAA;AAAA,0BAAc,0CAAd;AACA,0BAAc,oCADd;AAEA,0BAAc,gCAFd;AAMA,0BAAc,+BANd;","names":[]}

package/dist/index.d.cts

@@ -4,6 +4,7 @@ export { CreateNewEvent, makeCreateNewEvent } from './createNewEvent.cjs';
 export { EventBus } from './ports/EventBus.cjs';
 export { EventQueries } from './ports/EventQueries.cjs';
 export { EventRepository, EventsUnitOfWork, WithEventsUow, WithEventsUowOptions } from './ports/EventRepository.cjs';
+export { GlobalSubscriberConfig, NarrowEvent, TopicFilter, TopicSubscriber, TopicSubscriptions, subscribeByTopic, subscribeGlobalToTopics } from './subscriptions.cjs';
 export { DefaultContext, EventFailure, EventId, EventPublication, EventStatus, Flavor, GenericEvent, SubscriptionId, UserId } from './types.cjs';
 export { createInMemoryEventBus } from './adapters/in-memory/InMemoryEventBus.cjs';
 export { createInMemoryEventQueries } from './adapters/in-memory/InMemoryEventQueries.cjs';

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export { CreateNewEvent, makeCreateNewEvent } from './createNewEvent.js';
 export { EventBus } from './ports/EventBus.js';
 export { EventQueries } from './ports/EventQueries.js';
 export { EventRepository, EventsUnitOfWork, WithEventsUow, WithEventsUowOptions } from './ports/EventRepository.js';
+export { GlobalSubscriberConfig, NarrowEvent, TopicFilter, TopicSubscriber, TopicSubscriptions, subscribeByTopic, subscribeGlobalToTopics } from './subscriptions.js';
 export { DefaultContext, EventFailure, EventId, EventPublication, EventStatus, Flavor, GenericEvent, SubscriptionId, UserId } from './types.js';
 export { createInMemoryEventBus } from './adapters/in-memory/InMemoryEventBus.js';
 export { createInMemoryEventQueries } from './adapters/in-memory/InMemoryEventQueries.js';

package/dist/index.mjs

@@ -1,4 +1,5 @@
 export * from "./adapters/in-memory/index.mjs";
 export * from "./createEventCrawler.mjs";
 export * from "./createNewEvent.mjs";
+export * from "./subscriptions.mjs";
 //# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from './adapters/in-memory/index.mjs';\nexport * from './createEventCrawler.mjs';\nexport * from './createNewEvent.mjs';\nexport type * from './ports/EventBus.mjs';\nexport type * from './ports/EventQueries.mjs';\nexport type * from './ports/EventRepository.mjs';\nexport type * from './types.mjs';\n"],"mappings":"AAAA,cAAc;AACd,cAAc;AACd,cAAc;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from './adapters/in-memory/index.mjs';\nexport * from './createEventCrawler.mjs';\nexport * from './createNewEvent.mjs';\nexport type * from './ports/EventBus.mjs';\nexport type * from './ports/EventQueries.mjs';\nexport type * from './ports/EventRepository.mjs';\nexport * from './subscriptions.mjs';\nexport type * from './types.mjs';\n"],"mappings":"AAAA,cAAc;AACd,cAAc;AACd,cAAc;AAId,cAAc;","names":[]}

package/dist/subscriptions.cjs

@@ -0,0 +1,61 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var subscriptions_exports = {};
+__export(subscriptions_exports, {
+  subscribeByTopic: () => subscribeByTopic,
+  subscribeGlobalToTopics: () => subscribeGlobalToTopics
+});
+module.exports = __toCommonJS(subscriptions_exports);
+function subscribeByTopic(eventBus, subscriptions) {
+  for (const topic of Object.keys(subscriptions)) {
+    const handlers = subscriptions[topic];
+    for (const { subscriptionId, handler } of handlers) {
+      eventBus.subscribe({
+        topic,
+        subscriptionId,
+        callBack: handler
+      });
+    }
+  }
+}
+function subscribeGlobalToTopics(eventBus, subscriptions, config) {
+  const allTopics = Object.keys(subscriptions);
+  let topicsToSubscribe;
+  const filter = config.filter;
+  if (!filter) {
+    topicsToSubscribe = allTopics;
+  } else if ("include" in filter) {
+    topicsToSubscribe = filter.include;
+  } else {
+    topicsToSubscribe = allTopics.filter((t) => !filter.exclude.includes(t));
+  }
+  for (const topic of topicsToSubscribe) {
+    eventBus.subscribe({
+      topic,
+      subscriptionId: config.subscriptionId,
+      callBack: config.handler
+    });
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  subscribeByTopic,
+  subscribeGlobalToTopics
+});
+//# sourceMappingURL=subscriptions.cjs.map

package/dist/subscriptions.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/subscriptions.ts"],"sourcesContent":["import type { EventBus } from \"./ports/EventBus.ts\";\nimport type { DefaultContext, GenericEvent, SubscriptionId } from \"./types.ts\";\n\n/**\n * Extracts a specific event type from a union of events by topic.\n *\n * @example\n * ```typescript\n * type MyEvents =\n *   | GenericEvent<\"OrderCreated\", { orderId: string }>\n *   | GenericEvent<\"OrderShipped\", { trackingNumber: string }>;\n *\n * type OrderCreatedEvent = NarrowEvent<MyEvents, \"OrderCreated\">;\n * // Result: GenericEvent<\"OrderCreated\", { orderId: string }>\n * ```\n */\nexport type NarrowEvent<\n  AllEvents extends GenericEvent<string, unknown, DefaultContext>,\n  Topic extends AllEvents[\"topic\"],\n> = Extract<AllEvents, { topic: Topic }>;\n\n/**\n * A subscriber for a specific event topic.\n * The handler receives the full event (not just payload) for access to metadata.\n */\nexport type TopicSubscriber<\n  E extends GenericEvent<string, unknown, DefaultContext>,\n> = {\n  /** Unique identifier for retry tracking. */\n  subscriptionId: SubscriptionId;\n  /** Async handler receiving the full event with metadata (id, occurredAt, etc). */\n  handler: (event: E) => Promise<void>;\n};\n\n/**\n * Complete subscription map requiring ALL event topics.\n * Forces explicit decision about each topic, documenting intent.\n *\n * @example\n * ```typescript\n * const subscriptions: TopicSubscriptions<MyEvents> = {\n *   OrderCreated: [{ subscriptionId: \"notify\", handler: async (e) => {...} }],\n *   OrderShipped: [], // Required even if empty\n * };\n * ```\n */\nexport type TopicSubscriptions<\n  AllEvents extends GenericEvent<string, unknown, DefaultContext>,\n> = {\n  [K in AllEvents[\"topic\"]]: Array<TopicSubscriber<NarrowEvent<AllEvents, K>>>;\n};\n\n/**\n * Filter for global handlers. Use `include` OR `exclude` (mutually exclusive).\n *\n * @example\n * ```typescript\n * { include: [\"OrderCreated\", \"OrderShipped\"] } // Only these topics\n * { exclude: [\"NotificationAdded\"] } // All except these\n * ```\n */\nexport type TopicFilter<Topic extends string> =\n  | { include: Topic[] }\n  | { exclude: Topic[] };\n\n/**\n * Configuration for a global handler that listens to multiple topics.\n */\nexport type GlobalSubscriberConfig<\n  AllEvents extends GenericEvent<string, unknown, DefaultContext>,\n> = {\n  /** Unique identifier for retry tracking. */\n  subscriptionId: SubscriptionId;\n  /** Async handler receiving any event matching the filter. */\n  handler: (event: AllEvents) => Promise<void>;\n  /** Optional topic filter. Without filter, receives all topics. */\n  filter?: TopicFilter<AllEvents[\"topic\"]>;\n};\n\n/**\n * Subscribe all handlers from a topic subscription map to an event bus.\n * Standalone function for use with any EventBus implementation.\n *\n * @example\n * ```typescript\n * const subscriptions: TopicSubscriptions<MyEvents> = {\n *   OrderCreated: [{ subscriptionId: \"notify\", handler: sendNotification }],\n *   OrderShipped: [{ subscriptionId: \"track\", handler: updateTracking }],\n * };\n * subscribeByTopic(eventBus, subscriptions);\n * ```\n */\nexport function subscribeByTopic<\n  AllEvents extends GenericEvent<string, unknown, DefaultContext>,\n>(\n  eventBus: EventBus<AllEvents>,\n  subscriptions: TopicSubscriptions<AllEvents>,\n): void {\n  for (const topic of Object.keys(subscriptions) as AllEvents[\"topic\"][]) {\n    const handlers = subscriptions[topic];\n    for (const { subscriptionId, handler } of handlers) {\n      eventBus.subscribe({\n        topic,\n        subscriptionId,\n        callBack: handler,\n      });\n    }\n  }\n}\n\n/**\n * Subscribe a global handler to multiple topics with optional filtering.\n * Standalone function for use with any EventBus implementation.\n *\n * @example\n * ```typescript\n * // Audit log for all events except noisy ones\n * subscribeGlobalToTopics(eventBus, subscriptions, {\n *   subscriptionId: \"audit-log\",\n *   handler: async (event) => auditLog.record(event),\n *   filter: { exclude: [\"NotificationAdded\"] },\n * });\n *\n * // Analytics for specific topics only\n * subscribeGlobalToTopics(eventBus, subscriptions, {\n *   subscriptionId: \"order-analytics\",\n *   handler: async (event) => analytics.track(event),\n *   filter: { include: [\"OrderCreated\", \"OrderShipped\"] },\n * });\n * ```\n */\nexport function subscribeGlobalToTopics<\n  AllEvents extends GenericEvent<string, unknown, DefaultContext>,\n>(\n  eventBus: EventBus<AllEvents>,\n  subscriptions: TopicSubscriptions<AllEvents>,\n  config: GlobalSubscriberConfig<AllEvents>,\n): void {\n  const allTopics = Object.keys(subscriptions) as AllEvents[\"topic\"][];\n\n  let topicsToSubscribe: AllEvents[\"topic\"][];\n\n  const filter = config.filter;\n  if (!filter) {\n    topicsToSubscribe = allTopics;\n  } else if (\"include\" in filter) {\n    topicsToSubscribe = filter.include;\n  } else {\n    topicsToSubscribe = allTopics.filter((t) => !filter.exclude.includes(t));\n  }\n\n  for (const topic of topicsToSubscribe) {\n    eventBus.subscribe({\n      topic,\n      subscriptionId: config.subscriptionId,\n      callBack: config.handler,\n    });\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA4FO,SAAS,iBAGd,UACA,eACM;AACN,aAAW,SAAS,OAAO,KAAK,aAAa,GAA2B;AACtE,UAAM,WAAW,cAAc,KAAK;AACpC,eAAW,EAAE,gBAAgB,QAAQ,KAAK,UAAU;AAClD,eAAS,UAAU;AAAA,QACjB;AAAA,QACA;AAAA,QACA,UAAU;AAAA,MACZ,CAAC;AAAA,IACH;AAAA,EACF;AACF;AAuBO,SAAS,wBAGd,UACA,eACA,QACM;AACN,QAAM,YAAY,OAAO,KAAK,aAAa;AAE3C,MAAI;AAEJ,QAAM,SAAS,OAAO;AACtB,MAAI,CAAC,QAAQ;AACX,wBAAoB;AAAA,EACtB,WAAW,aAAa,QAAQ;AAC9B,wBAAoB,OAAO;AAAA,EAC7B,OAAO;AACL,wBAAoB,UAAU,OAAO,CAAC,MAAM,CAAC,OAAO,QAAQ,SAAS,CAAC,CAAC;AAAA,EACzE;AAEA,aAAW,SAAS,mBAAmB;AACrC,aAAS,UAAU;AAAA,MACjB;AAAA,MACA,gBAAgB,OAAO;AAAA,MACvB,UAAU,OAAO;AAAA,IACnB,CAAC;AAAA,EACH;AACF;","names":[]}

package/dist/subscriptions.d.cts

@@ -0,0 +1,107 @@
+import { EventBus } from './ports/EventBus.cjs';
+import { GenericEvent, DefaultContext, SubscriptionId } from './types.cjs';
+
+/**
+ * Extracts a specific event type from a union of events by topic.
+ *
+ * @example
+ * ```typescript
+ * type MyEvents =
+ *   | GenericEvent<"OrderCreated", { orderId: string }>
+ *   | GenericEvent<"OrderShipped", { trackingNumber: string }>;
+ *
+ * type OrderCreatedEvent = NarrowEvent<MyEvents, "OrderCreated">;
+ * // Result: GenericEvent<"OrderCreated", { orderId: string }>
+ * ```
+ */
+type NarrowEvent<AllEvents extends GenericEvent<string, unknown, DefaultContext>, Topic extends AllEvents["topic"]> = Extract<AllEvents, {
+    topic: Topic;
+}>;
+/**
+ * A subscriber for a specific event topic.
+ * The handler receives the full event (not just payload) for access to metadata.
+ */
+type TopicSubscriber<E extends GenericEvent<string, unknown, DefaultContext>> = {
+    /** Unique identifier for retry tracking. */
+    subscriptionId: SubscriptionId;
+    /** Async handler receiving the full event with metadata (id, occurredAt, etc). */
+    handler: (event: E) => Promise<void>;
+};
+/**
+ * Complete subscription map requiring ALL event topics.
+ * Forces explicit decision about each topic, documenting intent.
+ *
+ * @example
+ * ```typescript
+ * const subscriptions: TopicSubscriptions<MyEvents> = {
+ *   OrderCreated: [{ subscriptionId: "notify", handler: async (e) => {...} }],
+ *   OrderShipped: [], // Required even if empty
+ * };
+ * ```
+ */
+type TopicSubscriptions<AllEvents extends GenericEvent<string, unknown, DefaultContext>> = {
+    [K in AllEvents["topic"]]: Array<TopicSubscriber<NarrowEvent<AllEvents, K>>>;
+};
+/**
+ * Filter for global handlers. Use `include` OR `exclude` (mutually exclusive).
+ *
+ * @example
+ * ```typescript
+ * { include: ["OrderCreated", "OrderShipped"] } // Only these topics
+ * { exclude: ["NotificationAdded"] } // All except these
+ * ```
+ */
+type TopicFilter<Topic extends string> = {
+    include: Topic[];
+} | {
+    exclude: Topic[];
+};
+/**
+ * Configuration for a global handler that listens to multiple topics.
+ */
+type GlobalSubscriberConfig<AllEvents extends GenericEvent<string, unknown, DefaultContext>> = {
+    /** Unique identifier for retry tracking. */
+    subscriptionId: SubscriptionId;
+    /** Async handler receiving any event matching the filter. */
+    handler: (event: AllEvents) => Promise<void>;
+    /** Optional topic filter. Without filter, receives all topics. */
+    filter?: TopicFilter<AllEvents["topic"]>;
+};
+/**
+ * Subscribe all handlers from a topic subscription map to an event bus.
+ * Standalone function for use with any EventBus implementation.
+ *
+ * @example
+ * ```typescript
+ * const subscriptions: TopicSubscriptions<MyEvents> = {
+ *   OrderCreated: [{ subscriptionId: "notify", handler: sendNotification }],
+ *   OrderShipped: [{ subscriptionId: "track", handler: updateTracking }],
+ * };
+ * subscribeByTopic(eventBus, subscriptions);
+ * ```
+ */
+declare function subscribeByTopic<AllEvents extends GenericEvent<string, unknown, DefaultContext>>(eventBus: EventBus<AllEvents>, subscriptions: TopicSubscriptions<AllEvents>): void;
+/**
+ * Subscribe a global handler to multiple topics with optional filtering.
+ * Standalone function for use with any EventBus implementation.
+ *
+ * @example
+ * ```typescript
+ * // Audit log for all events except noisy ones
+ * subscribeGlobalToTopics(eventBus, subscriptions, {
+ *   subscriptionId: "audit-log",
+ *   handler: async (event) => auditLog.record(event),
+ *   filter: { exclude: ["NotificationAdded"] },
+ * });
+ *
+ * // Analytics for specific topics only
+ * subscribeGlobalToTopics(eventBus, subscriptions, {
+ *   subscriptionId: "order-analytics",
+ *   handler: async (event) => analytics.track(event),
+ *   filter: { include: ["OrderCreated", "OrderShipped"] },
+ * });
+ * ```
+ */
+declare function subscribeGlobalToTopics<AllEvents extends GenericEvent<string, unknown, DefaultContext>>(eventBus: EventBus<AllEvents>, subscriptions: TopicSubscriptions<AllEvents>, config: GlobalSubscriberConfig<AllEvents>): void;
+
+export { type GlobalSubscriberConfig, type NarrowEvent, type TopicFilter, type TopicSubscriber, type TopicSubscriptions, subscribeByTopic, subscribeGlobalToTopics };

package/dist/subscriptions.d.ts

@@ -0,0 +1,107 @@
+import { EventBus } from './ports/EventBus.js';
+import { GenericEvent, DefaultContext, SubscriptionId } from './types.js';
+
+/**
+ * Extracts a specific event type from a union of events by topic.
+ *
+ * @example
+ * ```typescript
+ * type MyEvents =
+ *   | GenericEvent<"OrderCreated", { orderId: string }>
+ *   | GenericEvent<"OrderShipped", { trackingNumber: string }>;
+ *
+ * type OrderCreatedEvent = NarrowEvent<MyEvents, "OrderCreated">;
+ * // Result: GenericEvent<"OrderCreated", { orderId: string }>
+ * ```
+ */
+type NarrowEvent<AllEvents extends GenericEvent<string, unknown, DefaultContext>, Topic extends AllEvents["topic"]> = Extract<AllEvents, {
+    topic: Topic;
+}>;
+/**
+ * A subscriber for a specific event topic.
+ * The handler receives the full event (not just payload) for access to metadata.
+ */
+type TopicSubscriber<E extends GenericEvent<string, unknown, DefaultContext>> = {
+    /** Unique identifier for retry tracking. */
+    subscriptionId: SubscriptionId;
+    /** Async handler receiving the full event with metadata (id, occurredAt, etc). */
+    handler: (event: E) => Promise<void>;
+};
+/**
+ * Complete subscription map requiring ALL event topics.
+ * Forces explicit decision about each topic, documenting intent.
+ *
+ * @example
+ * ```typescript
+ * const subscriptions: TopicSubscriptions<MyEvents> = {
+ *   OrderCreated: [{ subscriptionId: "notify", handler: async (e) => {...} }],
+ *   OrderShipped: [], // Required even if empty
+ * };
+ * ```
+ */
+type TopicSubscriptions<AllEvents extends GenericEvent<string, unknown, DefaultContext>> = {
+    [K in AllEvents["topic"]]: Array<TopicSubscriber<NarrowEvent<AllEvents, K>>>;
+};
+/**
+ * Filter for global handlers. Use `include` OR `exclude` (mutually exclusive).
+ *
+ * @example
+ * ```typescript
+ * { include: ["OrderCreated", "OrderShipped"] } // Only these topics
+ * { exclude: ["NotificationAdded"] } // All except these
+ * ```
+ */
+type TopicFilter<Topic extends string> = {
+    include: Topic[];
+} | {
+    exclude: Topic[];
+};
+/**
+ * Configuration for a global handler that listens to multiple topics.
+ */
+type GlobalSubscriberConfig<AllEvents extends GenericEvent<string, unknown, DefaultContext>> = {
+    /** Unique identifier for retry tracking. */
+    subscriptionId: SubscriptionId;
+    /** Async handler receiving any event matching the filter. */
+    handler: (event: AllEvents) => Promise<void>;
+    /** Optional topic filter. Without filter, receives all topics. */
+    filter?: TopicFilter<AllEvents["topic"]>;
+};
+/**
+ * Subscribe all handlers from a topic subscription map to an event bus.
+ * Standalone function for use with any EventBus implementation.
+ *
+ * @example
+ * ```typescript
+ * const subscriptions: TopicSubscriptions<MyEvents> = {
+ *   OrderCreated: [{ subscriptionId: "notify", handler: sendNotification }],
+ *   OrderShipped: [{ subscriptionId: "track", handler: updateTracking }],
+ * };
+ * subscribeByTopic(eventBus, subscriptions);
+ * ```
+ */
+declare function subscribeByTopic<AllEvents extends GenericEvent<string, unknown, DefaultContext>>(eventBus: EventBus<AllEvents>, subscriptions: TopicSubscriptions<AllEvents>): void;
+/**
+ * Subscribe a global handler to multiple topics with optional filtering.
+ * Standalone function for use with any EventBus implementation.
+ *
+ * @example
+ * ```typescript
+ * // Audit log for all events except noisy ones
+ * subscribeGlobalToTopics(eventBus, subscriptions, {
+ *   subscriptionId: "audit-log",
+ *   handler: async (event) => auditLog.record(event),
+ *   filter: { exclude: ["NotificationAdded"] },
+ * });
+ *
+ * // Analytics for specific topics only
+ * subscribeGlobalToTopics(eventBus, subscriptions, {
+ *   subscriptionId: "order-analytics",
+ *   handler: async (event) => analytics.track(event),
+ *   filter: { include: ["OrderCreated", "OrderShipped"] },
+ * });
+ * ```
+ */
+declare function subscribeGlobalToTopics<AllEvents extends GenericEvent<string, unknown, DefaultContext>>(eventBus: EventBus<AllEvents>, subscriptions: TopicSubscriptions<AllEvents>, config: GlobalSubscriberConfig<AllEvents>): void;
+
+export { type GlobalSubscriberConfig, type NarrowEvent, type TopicFilter, type TopicSubscriber, type TopicSubscriptions, subscribeByTopic, subscribeGlobalToTopics };

package/dist/subscriptions.mjs

@@ -0,0 +1,36 @@
+function subscribeByTopic(eventBus, subscriptions) {
+  for (const topic of Object.keys(subscriptions)) {
+    const handlers = subscriptions[topic];
+    for (const { subscriptionId, handler } of handlers) {
+      eventBus.subscribe({
+        topic,
+        subscriptionId,
+        callBack: handler
+      });
+    }
+  }
+}
+function subscribeGlobalToTopics(eventBus, subscriptions, config) {
+  const allTopics = Object.keys(subscriptions);
+  let topicsToSubscribe;
+  const filter = config.filter;
+  if (!filter) {
+    topicsToSubscribe = allTopics;
+  } else if ("include" in filter) {
+    topicsToSubscribe = filter.include;
+  } else {
+    topicsToSubscribe = allTopics.filter((t) => !filter.exclude.includes(t));
+  }
+  for (const topic of topicsToSubscribe) {
+    eventBus.subscribe({
+      topic,
+      subscriptionId: config.subscriptionId,
+      callBack: config.handler
+    });
+  }
+}
+export {
+  subscribeByTopic,
+  subscribeGlobalToTopics
+};
+//# sourceMappingURL=subscriptions.mjs.map

package/dist/subscriptions.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/subscriptions.ts"],"sourcesContent":["import type { EventBus } from './ports/EventBus.mjs';\nimport type { DefaultContext, GenericEvent, SubscriptionId } from './types.mjs';\n\n/**\n * Extracts a specific event type from a union of events by topic.\n *\n * @example\n * ```typescript\n * type MyEvents =\n *   | GenericEvent<\"OrderCreated\", { orderId: string }>\n *   | GenericEvent<\"OrderShipped\", { trackingNumber: string }>;\n *\n * type OrderCreatedEvent = NarrowEvent<MyEvents, \"OrderCreated\">;\n * // Result: GenericEvent<\"OrderCreated\", { orderId: string }>\n * ```\n */\nexport type NarrowEvent<\n  AllEvents extends GenericEvent<string, unknown, DefaultContext>,\n  Topic extends AllEvents[\"topic\"],\n> = Extract<AllEvents, { topic: Topic }>;\n\n/**\n * A subscriber for a specific event topic.\n * The handler receives the full event (not just payload) for access to metadata.\n */\nexport type TopicSubscriber<\n  E extends GenericEvent<string, unknown, DefaultContext>,\n> = {\n  /** Unique identifier for retry tracking. */\n  subscriptionId: SubscriptionId;\n  /** Async handler receiving the full event with metadata (id, occurredAt, etc). */\n  handler: (event: E) => Promise<void>;\n};\n\n/**\n * Complete subscription map requiring ALL event topics.\n * Forces explicit decision about each topic, documenting intent.\n *\n * @example\n * ```typescript\n * const subscriptions: TopicSubscriptions<MyEvents> = {\n *   OrderCreated: [{ subscriptionId: \"notify\", handler: async (e) => {...} }],\n *   OrderShipped: [], // Required even if empty\n * };\n * ```\n */\nexport type TopicSubscriptions<\n  AllEvents extends GenericEvent<string, unknown, DefaultContext>,\n> = {\n  [K in AllEvents[\"topic\"]]: Array<TopicSubscriber<NarrowEvent<AllEvents, K>>>;\n};\n\n/**\n * Filter for global handlers. Use `include` OR `exclude` (mutually exclusive).\n *\n * @example\n * ```typescript\n * { include: [\"OrderCreated\", \"OrderShipped\"] } // Only these topics\n * { exclude: [\"NotificationAdded\"] } // All except these\n * ```\n */\nexport type TopicFilter<Topic extends string> =\n  | { include: Topic[] }\n  | { exclude: Topic[] };\n\n/**\n * Configuration for a global handler that listens to multiple topics.\n */\nexport type GlobalSubscriberConfig<\n  AllEvents extends GenericEvent<string, unknown, DefaultContext>,\n> = {\n  /** Unique identifier for retry tracking. */\n  subscriptionId: SubscriptionId;\n  /** Async handler receiving any event matching the filter. */\n  handler: (event: AllEvents) => Promise<void>;\n  /** Optional topic filter. Without filter, receives all topics. */\n  filter?: TopicFilter<AllEvents[\"topic\"]>;\n};\n\n/**\n * Subscribe all handlers from a topic subscription map to an event bus.\n * Standalone function for use with any EventBus implementation.\n *\n * @example\n * ```typescript\n * const subscriptions: TopicSubscriptions<MyEvents> = {\n *   OrderCreated: [{ subscriptionId: \"notify\", handler: sendNotification }],\n *   OrderShipped: [{ subscriptionId: \"track\", handler: updateTracking }],\n * };\n * subscribeByTopic(eventBus, subscriptions);\n * ```\n */\nexport function subscribeByTopic<\n  AllEvents extends GenericEvent<string, unknown, DefaultContext>,\n>(\n  eventBus: EventBus<AllEvents>,\n  subscriptions: TopicSubscriptions<AllEvents>,\n): void {\n  for (const topic of Object.keys(subscriptions) as AllEvents[\"topic\"][]) {\n    const handlers = subscriptions[topic];\n    for (const { subscriptionId, handler } of handlers) {\n      eventBus.subscribe({\n        topic,\n        subscriptionId,\n        callBack: handler,\n      });\n    }\n  }\n}\n\n/**\n * Subscribe a global handler to multiple topics with optional filtering.\n * Standalone function for use with any EventBus implementation.\n *\n * @example\n * ```typescript\n * // Audit log for all events except noisy ones\n * subscribeGlobalToTopics(eventBus, subscriptions, {\n *   subscriptionId: \"audit-log\",\n *   handler: async (event) => auditLog.record(event),\n *   filter: { exclude: [\"NotificationAdded\"] },\n * });\n *\n * // Analytics for specific topics only\n * subscribeGlobalToTopics(eventBus, subscriptions, {\n *   subscriptionId: \"order-analytics\",\n *   handler: async (event) => analytics.track(event),\n *   filter: { include: [\"OrderCreated\", \"OrderShipped\"] },\n * });\n * ```\n */\nexport function subscribeGlobalToTopics<\n  AllEvents extends GenericEvent<string, unknown, DefaultContext>,\n>(\n  eventBus: EventBus<AllEvents>,\n  subscriptions: TopicSubscriptions<AllEvents>,\n  config: GlobalSubscriberConfig<AllEvents>,\n): void {\n  const allTopics = Object.keys(subscriptions) as AllEvents[\"topic\"][];\n\n  let topicsToSubscribe: AllEvents[\"topic\"][];\n\n  const filter = config.filter;\n  if (!filter) {\n    topicsToSubscribe = allTopics;\n  } else if (\"include\" in filter) {\n    topicsToSubscribe = filter.include;\n  } else {\n    topicsToSubscribe = allTopics.filter((t) => !filter.exclude.includes(t));\n  }\n\n  for (const topic of topicsToSubscribe) {\n    eventBus.subscribe({\n      topic,\n      subscriptionId: config.subscriptionId,\n      callBack: config.handler,\n    });\n  }\n}\n"],"mappings":"AA4FO,SAAS,iBAGd,UACA,eACM;AACN,aAAW,SAAS,OAAO,KAAK,aAAa,GAA2B;AACtE,UAAM,WAAW,cAAc,KAAK;AACpC,eAAW,EAAE,gBAAgB,QAAQ,KAAK,UAAU;AAClD,eAAS,UAAU;AAAA,QACjB;AAAA,QACA;AAAA,QACA,UAAU;AAAA,MACZ,CAAC;AAAA,IACH;AAAA,EACF;AACF;AAuBO,SAAS,wBAGd,UACA,eACA,QACM;AACN,QAAM,YAAY,OAAO,KAAK,aAAa;AAE3C,MAAI;AAEJ,QAAM,SAAS,OAAO;AACtB,MAAI,CAAC,QAAQ;AACX,wBAAoB;AAAA,EACtB,WAAW,aAAa,QAAQ;AAC9B,wBAAoB,OAAO;AAAA,EAC7B,OAAO;AACL,wBAAoB,UAAU,OAAO,CAAC,MAAM,CAAC,OAAO,QAAQ,SAAS,CAAC,CAAC;AAAA,EACzE;AAEA,aAAW,SAAS,mBAAmB;AACrC,aAAS,UAAU;AAAA,MACjB;AAAA,MACA,gBAAgB,OAAO;AAAA,MACvB,UAAU,OAAO;AAAA,IACnB,CAAC;AAAA,EACH;AACF;","names":[]}

package/dist/types.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/types.ts"],"sourcesContent":["/**\n * Branded type helper for nominal typing.\n * Adds a phantom type property to distinguish between structurally identical types.\n */\nexport type Flavor<T, FlavorT> = T & {\n  _type?: FlavorT;\n};\n\n/** Unique identifier for an event subscription. */\nexport type SubscriptionId = Flavor<string, \"SubscriptionId\">;\n\n/** Unique identifier for a user who triggered an event. */\nexport type UserId = Flavor<string, \"UserId\">;\n\n/** Unique identifier for an event. */\nexport type EventId = Flavor<string, \"EventId\">;\n\n/**\n * Records a subscription failure during event publication.\n * Contains the subscription that failed and error details for debugging.\n */\nexport type EventFailure = {\n  subscriptionId: SubscriptionId;\n  errorMessage: string;\n  /** Stack trace captured when the subscription callback threw. */\n  stack?: string;\n};\n\n/**\n * Records a single publication attempt for an event.\n * Tracks which subscribers were notified and any failures that occurred.\n */\nexport type EventPublication = {\n  publishedAt: Date;\n  /** All subscription IDs that were attempted in this publication. */\n  publishedSubscribers: SubscriptionId[];\n  /** Subscriptions that failed during this publication attempt. */\n  failures: EventFailure[];\n};\n\n/**\n * Event lifecycle status.\n * - `never-published`: New event, not yet processed by crawler\n * - `in-process`: Currently being published by crawler\n * - `published`: Successfully delivered to all subscribers\n * - `failed-but-will-retry`: Some subscribers failed, will retry\n * - `quarantined`: Exceeded max retries, requires manual intervention\n * - `to-republish`: Force republish to all subscribers (manual trigger)\n */\nexport type EventStatus =\n  | \"never-published\"\n  | \"to-republish\"\n  | \"in-process\"\n  | \"published\"\n  | \"failed-but-will-retry\"\n  | \"quarantined\";\n\n/** Context type constraint - must be a string record or undefined. */\nexport type DefaultContext = Record<string, string> | undefined;\n\n/**\n * Generic event type for the outbox pattern.\n * Events are persisted in the same transaction as domain changes,\n * then asynchronously published to subscribers.\n *\n * @typeParam T - Event topic/type string literal\n * @typeParam P - Event payload type\n * @typeParam C - Optional context for filtering (e.g., tenant ID)\n *\n * @example\n * ```typescript\n * type MyEvents =\n *   | GenericEvent<\"UserCreated\", { userId: string; email: string }>\n *   | GenericEvent<\"OrderPlaced\", { orderId: string }, { tenantId: string }>;\n * ```\n */\nexport type GenericEvent<\n  T extends string,\n  P,\n  C extends DefaultContext = undefined,\n> = {\n  /** Unique event identifier. */\n  id: EventId;\n  /** When the event occurred in the domain. */\n  occurredAt: Date;\n  /** Event type/topic for routing to subscribers. */\n  topic: T;\n  /** Event-specific data. */\n  payload: P;\n  /** Current lifecycle status. */\n  status: EventStatus;\n  /** History of publication attempts. */\n  publications: EventPublication[];\n  /** User who triggered the action that created this event. */\n  triggeredByUserId: UserId;\n  /** Optional priority for processing order (not yet implemented in crawler). */\n  priority?: number;\n  /** Optional context for filtering events (e.g., by tenant). */\n  context?: C;\n};\n"],"mappings":";;;;;;;;;;;;;;AAAA;AAAA;","names":[]}
+{"version":3,"sources":["../src/types.ts"],"sourcesContent":["/**\n * Branded type helper for nominal typing.\n * Adds a phantom type property to distinguish between structurally identical types.\n */\nexport type Flavor<T, FlavorT> = T & {\n  _type?: FlavorT;\n};\n\n/** Unique identifier for an event subscription. */\nexport type SubscriptionId = Flavor<string, \"SubscriptionId\">;\n\n/** Unique identifier for a user who triggered an event. */\nexport type UserId = Flavor<string, \"UserId\">;\n\n/** Unique identifier for an event. */\nexport type EventId = Flavor<string, \"EventId\">;\n\n/**\n * Records a subscription failure during event publication.\n * Contains the subscription that failed and error details for debugging.\n */\nexport type EventFailure = {\n  subscriptionId: SubscriptionId;\n  errorMessage: string;\n  /** Stack trace captured when the subscription callback threw. */\n  stack?: string;\n};\n\n/**\n * Records a single publication attempt for an event.\n * Tracks which subscribers were notified and any failures that occurred.\n */\nexport type EventPublication = {\n  publishedAt: Date;\n  /** All subscription IDs that were attempted in this publication. */\n  publishedSubscribers: SubscriptionId[];\n  /** Subscriptions that failed during this publication attempt. */\n  failures?: EventFailure[];\n};\n\n/**\n * Event lifecycle status.\n * - `never-published`: New event, not yet processed by crawler\n * - `in-process`: Currently being published by crawler\n * - `published`: Successfully delivered to all subscribers\n * - `failed-but-will-retry`: Some subscribers failed, will retry\n * - `quarantined`: Exceeded max retries, requires manual intervention\n * - `to-republish`: Force republish to all subscribers (manual trigger)\n */\nexport type EventStatus =\n  | \"never-published\"\n  | \"to-republish\"\n  | \"in-process\"\n  | \"published\"\n  | \"failed-but-will-retry\"\n  | \"quarantined\";\n\n/** Context type constraint - must be a string record or undefined. */\nexport type DefaultContext = Record<string, string> | undefined;\n\n/**\n * Generic event type for the outbox pattern.\n * Events are persisted in the same transaction as domain changes,\n * then asynchronously published to subscribers.\n *\n * @typeParam T - Event topic/type string literal\n * @typeParam P - Event payload type\n * @typeParam C - Optional context for filtering (e.g., tenant ID)\n *\n * @example\n * ```typescript\n * type MyEvents =\n *   | GenericEvent<\"UserCreated\", { userId: string; email: string }>\n *   | GenericEvent<\"OrderPlaced\", { orderId: string }, { tenantId: string }>;\n * ```\n */\nexport type GenericEvent<\n  T extends string,\n  P,\n  C extends DefaultContext = undefined,\n> = {\n  /** Unique event identifier. */\n  id: EventId;\n  /** When the event occurred in the domain. */\n  occurredAt: Date;\n  /** Event type/topic for routing to subscribers. */\n  topic: T;\n  /** Event-specific data. */\n  payload: P;\n  /** Current lifecycle status. */\n  status: EventStatus;\n  /** History of publication attempts. */\n  publications: EventPublication[];\n  /** User who triggered the action that created this event. */\n  triggeredByUserId: UserId;\n  /** Optional priority for processing order (not yet implemented in crawler). */\n  priority?: number;\n  /** Optional context for filtering events (e.g., by tenant). */\n  context?: C;\n};\n"],"mappings":";;;;;;;;;;;;;;AAAA;AAAA;","names":[]}

package/dist/types.d.cts

@@ -30,7 +30,7 @@ type EventPublication = {
     /** All subscription IDs that were attempted in this publication. */
     publishedSubscribers: SubscriptionId[];
     /** Subscriptions that failed during this publication attempt. */
-    failures: EventFailure[];
+    failures?: EventFailure[];
 };
 /**
  * Event lifecycle status.

package/dist/types.d.ts

@@ -30,7 +30,7 @@ type EventPublication = {
     /** All subscription IDs that were attempted in this publication. */
     publishedSubscribers: SubscriptionId[];
     /** Subscriptions that failed during this publication attempt. */
-    failures: EventFailure[];
+    failures?: EventFailure[];
 };
 /**
  * Event lifecycle status.

package/package.json

@@ -3,7 +3,7 @@
   "description": "The purpose of this repository is to make it easy to setup event driven architecture using outbox pattern",
   "module": "src/index.ts",
   "type": "module",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "main": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
   "files": [

package/src/adapters/in-memory/InMemoryEventBus.ts

@@ -1,6 +1,12 @@
 import { makeCreateNewEvent } from "../../createNewEvent.ts";
 import type { EventBus } from "../../ports/EventBus.ts";
 import type { WithEventsUow } from "../../ports/EventRepository.ts";
+import {
+  type GlobalSubscriberConfig,
+  subscribeByTopic,
+  subscribeGlobalToTopics,
+  type TopicSubscriptions,
+} from "../../subscriptions.ts";
 import type {
   DefaultContext,
   EventId,
@@ -66,7 +72,7 @@ export const createInMemoryEventBus = <
     const lastPublication = event.publications.reduce((latest, current) =>
       current.publishedAt > latest.publishedAt ? current : latest,
     );
-    const failedSubscriptionIds = lastPublication.failures.map(
+    const failedSubscriptionIds = (lastPublication.failures ?? []).map(
       (failure) => failure.subscriptionId,
     );
 
@@ -86,7 +92,6 @@ export const createInMemoryEventBus = <
         event.publications.push({
           publishedAt,
           publishedSubscribers: [],
-          failures: [],
         });
         event.status = "published";
         await withUow(async (uow) => {
@@ -127,7 +132,7 @@ export const createInMemoryEventBus = <
           publishedSubscribers: subscriptionIdsToPublish.map(
             (id) => id as SubscriptionId,
           ),
-          failures,
+          ...(failures.length > 0 && { failures }),
         },
       ];
 
@@ -161,5 +166,59 @@ export const createInMemoryEventBus = <
     },
   };
 
-  return { eventBus, createNewEvent };
+  /**
+   * Identity function for type inference when defining subscription maps.
+   * Ensures all topics are covered and handlers have correct payload types.
+   *
+   * @example
+   * ```typescript
+   * const subscriptions = defineSubscriptions({
+   *   OrderCreated: [{ subscriptionId: "notify", handler: async (e) => {...} }],
+   *   OrderShipped: [], // Required even if empty
+   * });
+   * ```
+   */
+  const defineSubscriptions = (
+    subscriptions: TopicSubscriptions<Event>,
+  ): TopicSubscriptions<Event> => subscriptions;
+
+  /**
+   * Subscribe all handlers from a topic subscription map to this event bus.
+   *
+   * @example
+   * ```typescript
+   * const subscriptions = defineSubscriptions({...});
+   * subscribeAll(subscriptions);
+   * ```
+   */
+  const subscribeAll = (subscriptions: TopicSubscriptions<Event>): void => {
+    subscribeByTopic(eventBus, subscriptions);
+  };
+
+  /**
+   * Subscribe a global handler to multiple topics with optional filtering.
+   *
+   * @example
+   * ```typescript
+   * subscribeGlobal(subscriptions, {
+   *   subscriptionId: "audit-log",
+   *   handler: async (event) => auditLog.record(event),
+   *   filter: { exclude: ["NotificationAdded"] },
+   * });
+   * ```
+   */
+  const subscribeGlobal = (
+    subscriptions: TopicSubscriptions<Event>,
+    config: GlobalSubscriberConfig<Event>,
+  ): void => {
+    subscribeGlobalToTopics(eventBus, subscriptions, config);
+  };
+
+  return {
+    eventBus,
+    createNewEvent,
+    defineSubscriptions,
+    subscribeAll,
+    subscribeGlobal,
+  };
 };

package/src/index.ts

@@ -4,4 +4,5 @@ export * from "./createNewEvent.ts";
 export type * from "./ports/EventBus.ts";
 export type * from "./ports/EventQueries.ts";
 export type * from "./ports/EventRepository.ts";
+export * from "./subscriptions.ts";
 export type * from "./types.ts";

package/src/subscriptions.ts

@@ -0,0 +1,159 @@
+import type { EventBus } from "./ports/EventBus.ts";
+import type { DefaultContext, GenericEvent, SubscriptionId } from "./types.ts";
+
+/**
+ * Extracts a specific event type from a union of events by topic.
+ *
+ * @example
+ * ```typescript
+ * type MyEvents =
+ *   | GenericEvent<"OrderCreated", { orderId: string }>
+ *   | GenericEvent<"OrderShipped", { trackingNumber: string }>;
+ *
+ * type OrderCreatedEvent = NarrowEvent<MyEvents, "OrderCreated">;
+ * // Result: GenericEvent<"OrderCreated", { orderId: string }>
+ * ```
+ */
+export type NarrowEvent<
+  AllEvents extends GenericEvent<string, unknown, DefaultContext>,
+  Topic extends AllEvents["topic"],
+> = Extract<AllEvents, { topic: Topic }>;
+
+/**
+ * A subscriber for a specific event topic.
+ * The handler receives the full event (not just payload) for access to metadata.
+ */
+export type TopicSubscriber<
+  E extends GenericEvent<string, unknown, DefaultContext>,
+> = {
+  /** Unique identifier for retry tracking. */
+  subscriptionId: SubscriptionId;
+  /** Async handler receiving the full event with metadata (id, occurredAt, etc). */
+  handler: (event: E) => Promise<void>;
+};
+
+/**
+ * Complete subscription map requiring ALL event topics.
+ * Forces explicit decision about each topic, documenting intent.
+ *
+ * @example
+ * ```typescript
+ * const subscriptions: TopicSubscriptions<MyEvents> = {
+ *   OrderCreated: [{ subscriptionId: "notify", handler: async (e) => {...} }],
+ *   OrderShipped: [], // Required even if empty
+ * };
+ * ```
+ */
+export type TopicSubscriptions<
+  AllEvents extends GenericEvent<string, unknown, DefaultContext>,
+> = {
+  [K in AllEvents["topic"]]: Array<TopicSubscriber<NarrowEvent<AllEvents, K>>>;
+};
+
+/**
+ * Filter for global handlers. Use `include` OR `exclude` (mutually exclusive).
+ *
+ * @example
+ * ```typescript
+ * { include: ["OrderCreated", "OrderShipped"] } // Only these topics
+ * { exclude: ["NotificationAdded"] } // All except these
+ * ```
+ */
+export type TopicFilter<Topic extends string> =
+  | { include: Topic[] }
+  | { exclude: Topic[] };
+
+/**
+ * Configuration for a global handler that listens to multiple topics.
+ */
+export type GlobalSubscriberConfig<
+  AllEvents extends GenericEvent<string, unknown, DefaultContext>,
+> = {
+  /** Unique identifier for retry tracking. */
+  subscriptionId: SubscriptionId;
+  /** Async handler receiving any event matching the filter. */
+  handler: (event: AllEvents) => Promise<void>;
+  /** Optional topic filter. Without filter, receives all topics. */
+  filter?: TopicFilter<AllEvents["topic"]>;
+};
+
+/**
+ * Subscribe all handlers from a topic subscription map to an event bus.
+ * Standalone function for use with any EventBus implementation.
+ *
+ * @example
+ * ```typescript
+ * const subscriptions: TopicSubscriptions<MyEvents> = {
+ *   OrderCreated: [{ subscriptionId: "notify", handler: sendNotification }],
+ *   OrderShipped: [{ subscriptionId: "track", handler: updateTracking }],
+ * };
+ * subscribeByTopic(eventBus, subscriptions);
+ * ```
+ */
+export function subscribeByTopic<
+  AllEvents extends GenericEvent<string, unknown, DefaultContext>,
+>(
+  eventBus: EventBus<AllEvents>,
+  subscriptions: TopicSubscriptions<AllEvents>,
+): void {
+  for (const topic of Object.keys(subscriptions) as AllEvents["topic"][]) {
+    const handlers = subscriptions[topic];
+    for (const { subscriptionId, handler } of handlers) {
+      eventBus.subscribe({
+        topic,
+        subscriptionId,
+        callBack: handler,
+      });
+    }
+  }
+}
+
+/**
+ * Subscribe a global handler to multiple topics with optional filtering.
+ * Standalone function for use with any EventBus implementation.
+ *
+ * @example
+ * ```typescript
+ * // Audit log for all events except noisy ones
+ * subscribeGlobalToTopics(eventBus, subscriptions, {
+ *   subscriptionId: "audit-log",
+ *   handler: async (event) => auditLog.record(event),
+ *   filter: { exclude: ["NotificationAdded"] },
+ * });
+ *
+ * // Analytics for specific topics only
+ * subscribeGlobalToTopics(eventBus, subscriptions, {
+ *   subscriptionId: "order-analytics",
+ *   handler: async (event) => analytics.track(event),
+ *   filter: { include: ["OrderCreated", "OrderShipped"] },
+ * });
+ * ```
+ */
+export function subscribeGlobalToTopics<
+  AllEvents extends GenericEvent<string, unknown, DefaultContext>,
+>(
+  eventBus: EventBus<AllEvents>,
+  subscriptions: TopicSubscriptions<AllEvents>,
+  config: GlobalSubscriberConfig<AllEvents>,
+): void {
+  const allTopics = Object.keys(subscriptions) as AllEvents["topic"][];
+
+  let topicsToSubscribe: AllEvents["topic"][];
+
+  const filter = config.filter;
+  if (!filter) {
+    topicsToSubscribe = allTopics;
+  } else if ("include" in filter) {
+    topicsToSubscribe = filter.include;
+  } else {
+    topicsToSubscribe = allTopics.filter((t) => !filter.exclude.includes(t));
+  }
+
+  for (const topic of topicsToSubscribe) {
+    eventBus.subscribe({
+      topic,
+      subscriptionId: config.subscriptionId,
+      callBack: config.handler,
+    });
+  }
+}

package/src/types.ts

@@ -35,7 +35,7 @@ export type EventPublication = {
   /** All subscription IDs that were attempted in this publication. */
   publishedSubscribers: SubscriptionId[];
   /** Subscriptions that failed during this publication attempt. */
-  failures: EventFailure[];
+  failures?: EventFailure[];
 };
 
 /**