@l-etabli/events 0.3.0 → 0.4.0

package/README.md

@@ -1,16 +1,267 @@
-# l-etabli/events
+# @l-etabli/events
 
-${project_description}
+Event-driven architecture library implementing the **outbox pattern** for TypeScript.
 
+Events are persisted in the same transaction as your domain changes, then reliably published asynchronously. No lost events, even on failures.
 
-This project is a template for creating typscript libraries.
+## Installation
 
-It uses :
+```bash
+pnpm add @l-etabli/events
+```
 
-- Typescript for type checking
-- Bun for running tests
-- Bun as a package manager
-- Biome as a formatter
-- Biome as a linter
-- Lefthook for pre-commit hooks
-- GitHub Actions for CI, which will run typecheck, format, lint, test and than deploy the package to npm
+For Kysely adapter (PostgreSQL):
+
+```bash
+pnpm add @l-etabli/events kysely pg
+```
+
+## Quick Start
+
+### 1. Define Your Events
+
+```typescript
+import { GenericEvent } from "@l-etabli/events";
+
+type MyEvents =
+  | GenericEvent<"UserCreated", { userId: string; email: string }>
+  | GenericEvent<"OrderPlaced", { orderId: string; amount: number }>;
+```
+
+### 2. Setup Event Infrastructure
+
+```typescript
+import {
+  createInMemoryEventBus,
+  createInMemoryEventRepositoryAndQueries,
+  createEventCrawler,
+} from "@l-etabli/events";
+
+const { eventQueries, withUow } = createInMemoryEventRepositoryAndQueries<MyEvents>();
+const { eventBus, createNewEvent } = createInMemoryEventBus<MyEvents>(withUow);
+
+const crawler = createEventCrawler({
+  withUow,
+  eventQueries,
+  eventBus,
+});
+```
+
+### 3. Subscribe to Events
+
+```typescript
+eventBus.subscribe({
+  topic: "OrderPlaced",
+  subscriptionId: "send-confirmation-email",
+  callBack: async (event) => {
+    await emailService.sendOrderConfirmation(event.payload.orderId);
+  },
+});
+```
+
+### 4. Emit Events (in a use case)
+
+```typescript
+await withUow(async (uow) => {
+  // Save your domain entity
+  await orderRepository.save(order);
+
+  // Emit event in the same transaction
+  await uow.eventRepository.saveNewEventsBatch([
+    createNewEvent({
+      topic: "OrderPlaced",
+      payload: { orderId: order.id, amount: order.total },
+      triggeredByUserId: currentUserId,
+    }),
+  ]);
+});
+```
+
+### 5. Process Events
+
+**Traditional server** - start background polling:
+
+```typescript
+crawler.start();
+```
+
+**Serverless** - trigger on-demand after commit:
+
+```typescript
+await withUow(
+  async (uow) => {
+    await uow.eventRepository.saveNewEventsBatch([event]);
+  },
+  {
+    afterCommit: async () => {
+      await crawler.triggerProcessing();
+    },
+  }
+);
+
+### Returning Values from Transactions
+
+The `withUow` function supports returning values from your transaction callback:
+
+```typescript
+const result = await withUow(async (uow) => {
+  const order = await orderRepository.save(newOrder);
+
+  await uow.eventRepository.saveNewEventsBatch([
+    createNewEvent({
+      topic: "OrderPlaced",
+      payload: { orderId: order.id, amount: order.total },
+      triggeredByUserId: currentUserId,
+    }),
+  ]);
+
+  return { orderId: order.id, createdAt: order.createdAt };
+});
+
+console.log(result.orderId); // Access the returned value
+```
+
+## Event Lifecycle
+
+```
+never-published → in-process → published
+                           ↘ failed-but-will-retry → published
+                                                  ↘ quarantined (after maxRetries)
+```
+
+- `never-published` - New event, not yet processed
+- `in-process` - Currently being published
+- `published` - Successfully delivered to all subscribers
+- `failed-but-will-retry` - Some subscribers failed, will retry
+- `quarantined` - Exceeded max retries, requires manual intervention
+- `to-republish` - Force republish to all subscribers
+
+## API Reference
+
+### Types
+
+```typescript
+// Define events with topic, payload, and optional context
+type GenericEvent<Topic, Payload, Context?> = {
+  id: EventId;
+  topic: Topic;
+  payload: Payload;
+  status: EventStatus;
+  occurredAt: Date;
+  triggeredByUserId: UserId;
+  publications: EventPublication[];
+  context?: Context;
+  priority?: number;
+};
+```
+
+### `makeCreateNewEvent<Events>(options?)`
+
+Creates a type-safe event factory. Payload is validated against topic at compile time.
+
+```typescript
+const createEvent = makeCreateNewEvent<MyEvents>({
+  getNow: () => new Date(),      // optional, for testing
+  generateId: () => crypto.randomUUID(), // optional, for testing
+});
+
+// Type-safe: payload must match topic
+createEvent({ topic: "UserCreated", payload: { userId: "1", email: "a@b.com" }, triggeredByUserId: "u1" });
+```
+
+### `createInMemoryEventBus<Events>(withUow, options?)`
+
+Creates an in-memory event bus with a typed `createNewEvent` function.
+
+```typescript
+const { eventBus, createNewEvent } = createInMemoryEventBus<MyEvents>(withUow, {
+  maxRetries: 3, // default
+});
+```
+
+### `createEventCrawler(config)`
+
+Creates a background processor for publishing events.
+
+```typescript
+const crawler = createEventCrawler({
+  withUow,
+  eventQueries,
+  eventBus,
+  options: {
+    batchSize: 100,              // events per batch (default: 100)
+    maxParallelProcessing: 1,    // parallel publishes (default: 1)
+    newEventsIntervalMs: 10000,  // polling interval (default: 10s)
+    failedEventsIntervalMs: 60000, // retry interval (default: 60s)
+  },
+});
+
+crawler.start();              // Start background polling
+crawler.processNewEvents();   // Manual: process new events
+crawler.retryFailedEvents();  // Manual: retry failed events
+crawler.triggerProcessing();  // Manual: process new + retry failed
+```
+
+## Database Setup (Kysely/PostgreSQL)
+
+### Migration
+
+```typescript
+import type { Kysely } from "kysely";
+
+export async function up(db: Kysely<unknown>): Promise<void> {
+  await db.schema
+    .createTable("events")
+    .addColumn("id", "text", (col) => col.primaryKey())
+    .addColumn("topic", "text", (col) => col.notNull())
+    .addColumn("payload", "jsonb", (col) => col.notNull())
+    .addColumn("context", "jsonb")
+    .addColumn("status", "text", (col) => col.notNull())
+    .addColumn("triggeredByUserId", "text", (col) => col.notNull())
+    .addColumn("occurredAt", "timestamptz", (col) => col.notNull())
+    .addColumn("publications", "jsonb", (col) => col.notNull().defaultTo("[]"))
+    .addColumn("priority", "integer")
+    .execute();
+
+  await db.schema
+    .createIndex("events_status_idx")
+    .on("events")
+    .column("status")
+    .execute();
+
+  await db.schema
+    .createIndex("events_topic_idx")
+    .on("events")
+    .column("topic")
+    .execute();
+}
+
+export async function down(db: Kysely<unknown>): Promise<void> {
+  await db.schema.dropTable("events").execute();
+}
+```
+
+### Usage with Kysely
+
+```typescript
+import { createInMemoryEventBus, createEventCrawler } from "@l-etabli/events";
+import {
+  KyselyEventRepository,
+  KyselyEventQueries,
+  createKyselyMigration,
+} from "@l-etabli/events/kysely";
+
+// See examples/kysely/ for complete implementation
+```
+
+## Examples
+
+See the [`examples/`](./examples/) directory for complete implementations:
+
+- **[kysely-adapter.ts](./examples/kysely/kysely-adapter.ts)** - Kysely adapter with transaction support
+- **[serverless-usage.ts](./examples/kysely/serverless-usage.ts)** - AWS Lambda / serverless deployment
+- **[cascading-events.ts](./examples/kysely/cascading-events.ts)** - Transactional event chains
+
+## License
+
+MIT

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

@@ -56,8 +56,9 @@ const createInMemoryEventRepository = () => {
 };
 const createInMemoryWithUow = (eventRepository) => {
   const withUow = async (fn, options) => {
-    await fn({ eventRepository });
+    const result = await fn({ eventRepository });
     await options?.afterCommit?.();
+    return result;
   };
   return { withUow };
 };

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

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/adapters/in-memory/InMemoryEventRepository.ts"],"sourcesContent":["import type {\n  EventRepository,\n  WithEventsUow,\n} from \"../../ports/EventRepository.ts\";\nimport type { DefaultContext, GenericEvent } from \"../../types.ts\";\n\nexport type InMemoryEventRepositoryHelpers<\n  Event extends GenericEvent<string, unknown, DefaultContext>,\n> = { getAllEvents: () => Event[]; setEvents: (events: Event[]) => void };\n\nexport const createInMemoryEventRepository = <\n  Event extends GenericEvent<string, unknown, DefaultContext>,\n>(): {\n  eventRepository: EventRepository<Event>;\n  helpers: InMemoryEventRepositoryHelpers<Event>;\n} => {\n  const eventById: Record<string, Event> = {};\n\n  const eventRepository: EventRepository<Event> = {\n    save: async (event) => {\n      eventById[event.id] = event;\n    },\n    saveNewEventsBatch: async (events) => {\n      events.forEach((event) => {\n        eventById[event.id] = event;\n      });\n    },\n    markEventsAsInProcess: async (events) => {\n      events.forEach((event) => {\n        eventById[event.id] = { ...event, status: \"in-process\" };\n      });\n    },\n  };\n\n  return {\n    eventRepository,\n    helpers: {\n      getAllEvents: () => Object.values(eventById),\n      setEvents: (events) => {\n        Object.keys(eventById).forEach((key) => {\n          delete eventById[key];\n        });\n\n        events.forEach((event) => {\n          eventById[event.id] = event;\n        });\n      },\n    },\n  };\n};\n\nexport const createInMemoryWithUow = <\n  Event extends GenericEvent<string, unknown, DefaultContext>,\n>(\n  eventRepository: EventRepository<Event>,\n): { withUow: WithEventsUow<Event> } => {\n  // In-memory adapter awaits afterCommit for predictable test behavior\n  const withUow: WithEventsUow<Event> = async (fn, options) => {\n    await fn({ eventRepository });\n    await options?.afterCommit?.();\n  };\n  return { withUow };\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAUO,MAAM,gCAAgC,MAKxC;AACH,QAAM,YAAmC,CAAC;AAE1C,QAAM,kBAA0C;AAAA,IAC9C,MAAM,OAAO,UAAU;AACrB,gBAAU,MAAM,EAAE,IAAI;AAAA,IACxB;AAAA,IACA,oBAAoB,OAAO,WAAW;AACpC,aAAO,QAAQ,CAAC,UAAU;AACxB,kBAAU,MAAM,EAAE,IAAI;AAAA,MACxB,CAAC;AAAA,IACH;AAAA,IACA,uBAAuB,OAAO,WAAW;AACvC,aAAO,QAAQ,CAAC,UAAU;AACxB,kBAAU,MAAM,EAAE,IAAI,EAAE,GAAG,OAAO,QAAQ,aAAa;AAAA,MACzD,CAAC;AAAA,IACH;AAAA,EACF;AAEA,SAAO;AAAA,IACL;AAAA,IACA,SAAS;AAAA,MACP,cAAc,MAAM,OAAO,OAAO,SAAS;AAAA,MAC3C,WAAW,CAAC,WAAW;AACrB,eAAO,KAAK,SAAS,EAAE,QAAQ,CAAC,QAAQ;AACtC,iBAAO,UAAU,GAAG;AAAA,QACtB,CAAC;AAED,eAAO,QAAQ,CAAC,UAAU;AACxB,oBAAU,MAAM,EAAE,IAAI;AAAA,QACxB,CAAC;AAAA,MACH;AAAA,IACF;AAAA,EACF;AACF;AAEO,MAAM,wBAAwB,CAGnC,oBACsC;AAEtC,QAAM,UAAgC,OAAO,IAAI,YAAY;AAC3D,UAAM,GAAG,EAAE,gBAAgB,CAAC;AAC5B,UAAM,SAAS,cAAc;AAAA,EAC/B;AACA,SAAO,EAAE,QAAQ;AACnB;","names":[]}
+{"version":3,"sources":["../../../src/adapters/in-memory/InMemoryEventRepository.ts"],"sourcesContent":["import type {\n  EventRepository,\n  WithEventsUow,\n} from \"../../ports/EventRepository.ts\";\nimport type { DefaultContext, GenericEvent } from \"../../types.ts\";\n\nexport type InMemoryEventRepositoryHelpers<\n  Event extends GenericEvent<string, unknown, DefaultContext>,\n> = { getAllEvents: () => Event[]; setEvents: (events: Event[]) => void };\n\nexport const createInMemoryEventRepository = <\n  Event extends GenericEvent<string, unknown, DefaultContext>,\n>(): {\n  eventRepository: EventRepository<Event>;\n  helpers: InMemoryEventRepositoryHelpers<Event>;\n} => {\n  const eventById: Record<string, Event> = {};\n\n  const eventRepository: EventRepository<Event> = {\n    save: async (event) => {\n      eventById[event.id] = event;\n    },\n    saveNewEventsBatch: async (events) => {\n      events.forEach((event) => {\n        eventById[event.id] = event;\n      });\n    },\n    markEventsAsInProcess: async (events) => {\n      events.forEach((event) => {\n        eventById[event.id] = { ...event, status: \"in-process\" };\n      });\n    },\n  };\n\n  return {\n    eventRepository,\n    helpers: {\n      getAllEvents: () => Object.values(eventById),\n      setEvents: (events) => {\n        Object.keys(eventById).forEach((key) => {\n          delete eventById[key];\n        });\n\n        events.forEach((event) => {\n          eventById[event.id] = event;\n        });\n      },\n    },\n  };\n};\n\nexport const createInMemoryWithUow = <\n  Event extends GenericEvent<string, unknown, DefaultContext>,\n>(\n  eventRepository: EventRepository<Event>,\n): { withUow: WithEventsUow<Event> } => {\n  // In-memory adapter awaits afterCommit for predictable test behavior\n  const withUow: WithEventsUow<Event> = async (fn, options) => {\n    const result = await fn({ eventRepository });\n    await options?.afterCommit?.();\n    return result;\n  };\n  return { withUow };\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAUO,MAAM,gCAAgC,MAKxC;AACH,QAAM,YAAmC,CAAC;AAE1C,QAAM,kBAA0C;AAAA,IAC9C,MAAM,OAAO,UAAU;AACrB,gBAAU,MAAM,EAAE,IAAI;AAAA,IACxB;AAAA,IACA,oBAAoB,OAAO,WAAW;AACpC,aAAO,QAAQ,CAAC,UAAU;AACxB,kBAAU,MAAM,EAAE,IAAI;AAAA,MACxB,CAAC;AAAA,IACH;AAAA,IACA,uBAAuB,OAAO,WAAW;AACvC,aAAO,QAAQ,CAAC,UAAU;AACxB,kBAAU,MAAM,EAAE,IAAI,EAAE,GAAG,OAAO,QAAQ,aAAa;AAAA,MACzD,CAAC;AAAA,IACH;AAAA,EACF;AAEA,SAAO;AAAA,IACL;AAAA,IACA,SAAS;AAAA,MACP,cAAc,MAAM,OAAO,OAAO,SAAS;AAAA,MAC3C,WAAW,CAAC,WAAW;AACrB,eAAO,KAAK,SAAS,EAAE,QAAQ,CAAC,QAAQ;AACtC,iBAAO,UAAU,GAAG;AAAA,QACtB,CAAC;AAED,eAAO,QAAQ,CAAC,UAAU;AACxB,oBAAU,MAAM,EAAE,IAAI;AAAA,QACxB,CAAC;AAAA,MACH;AAAA,IACF;AAAA,EACF;AACF;AAEO,MAAM,wBAAwB,CAGnC,oBACsC;AAEtC,QAAM,UAAgC,OAAO,IAAI,YAAY;AAC3D,UAAM,SAAS,MAAM,GAAG,EAAE,gBAAgB,CAAC;AAC3C,UAAM,SAAS,cAAc;AAC7B,WAAO;AAAA,EACT;AACA,SAAO,EAAE,QAAQ;AACnB;","names":[]}

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

@@ -32,8 +32,9 @@ const createInMemoryEventRepository = () => {
 };
 const createInMemoryWithUow = (eventRepository) => {
   const withUow = async (fn, options) => {
-    await fn({ eventRepository });
+    const result = await fn({ eventRepository });
     await options?.afterCommit?.();
+    return result;
   };
   return { withUow };
 };

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

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/adapters/in-memory/InMemoryEventRepository.ts"],"sourcesContent":["import type {\n  EventRepository,\n  WithEventsUow,\n} from '../../ports/EventRepository.ts.mjs';\nimport type { DefaultContext, GenericEvent } from '../../types.ts.mjs';\n\nexport type InMemoryEventRepositoryHelpers<\n  Event extends GenericEvent<string, unknown, DefaultContext>,\n> = { getAllEvents: () => Event[]; setEvents: (events: Event[]) => void };\n\nexport const createInMemoryEventRepository = <\n  Event extends GenericEvent<string, unknown, DefaultContext>,\n>(): {\n  eventRepository: EventRepository<Event>;\n  helpers: InMemoryEventRepositoryHelpers<Event>;\n} => {\n  const eventById: Record<string, Event> = {};\n\n  const eventRepository: EventRepository<Event> = {\n    save: async (event) => {\n      eventById[event.id] = event;\n    },\n    saveNewEventsBatch: async (events) => {\n      events.forEach((event) => {\n        eventById[event.id] = event;\n      });\n    },\n    markEventsAsInProcess: async (events) => {\n      events.forEach((event) => {\n        eventById[event.id] = { ...event, status: \"in-process\" };\n      });\n    },\n  };\n\n  return {\n    eventRepository,\n    helpers: {\n      getAllEvents: () => Object.values(eventById),\n      setEvents: (events) => {\n        Object.keys(eventById).forEach((key) => {\n          delete eventById[key];\n        });\n\n        events.forEach((event) => {\n          eventById[event.id] = event;\n        });\n      },\n    },\n  };\n};\n\nexport const createInMemoryWithUow = <\n  Event extends GenericEvent<string, unknown, DefaultContext>,\n>(\n  eventRepository: EventRepository<Event>,\n): { withUow: WithEventsUow<Event> } => {\n  // In-memory adapter awaits afterCommit for predictable test behavior\n  const withUow: WithEventsUow<Event> = async (fn, options) => {\n    await fn({ eventRepository });\n    await options?.afterCommit?.();\n  };\n  return { withUow };\n};\n"],"mappings":"AAUO,MAAM,gCAAgC,MAKxC;AACH,QAAM,YAAmC,CAAC;AAE1C,QAAM,kBAA0C;AAAA,IAC9C,MAAM,OAAO,UAAU;AACrB,gBAAU,MAAM,EAAE,IAAI;AAAA,IACxB;AAAA,IACA,oBAAoB,OAAO,WAAW;AACpC,aAAO,QAAQ,CAAC,UAAU;AACxB,kBAAU,MAAM,EAAE,IAAI;AAAA,MACxB,CAAC;AAAA,IACH;AAAA,IACA,uBAAuB,OAAO,WAAW;AACvC,aAAO,QAAQ,CAAC,UAAU;AACxB,kBAAU,MAAM,EAAE,IAAI,EAAE,GAAG,OAAO,QAAQ,aAAa;AAAA,MACzD,CAAC;AAAA,IACH;AAAA,EACF;AAEA,SAAO;AAAA,IACL;AAAA,IACA,SAAS;AAAA,MACP,cAAc,MAAM,OAAO,OAAO,SAAS;AAAA,MAC3C,WAAW,CAAC,WAAW;AACrB,eAAO,KAAK,SAAS,EAAE,QAAQ,CAAC,QAAQ;AACtC,iBAAO,UAAU,GAAG;AAAA,QACtB,CAAC;AAED,eAAO,QAAQ,CAAC,UAAU;AACxB,oBAAU,MAAM,EAAE,IAAI;AAAA,QACxB,CAAC;AAAA,MACH;AAAA,IACF;AAAA,EACF;AACF;AAEO,MAAM,wBAAwB,CAGnC,oBACsC;AAEtC,QAAM,UAAgC,OAAO,IAAI,YAAY;AAC3D,UAAM,GAAG,EAAE,gBAAgB,CAAC;AAC5B,UAAM,SAAS,cAAc;AAAA,EAC/B;AACA,SAAO,EAAE,QAAQ;AACnB;","names":[]}
+{"version":3,"sources":["../../../src/adapters/in-memory/InMemoryEventRepository.ts"],"sourcesContent":["import type {\n  EventRepository,\n  WithEventsUow,\n} from '../../ports/EventRepository.ts.mjs';\nimport type { DefaultContext, GenericEvent } from '../../types.ts.mjs';\n\nexport type InMemoryEventRepositoryHelpers<\n  Event extends GenericEvent<string, unknown, DefaultContext>,\n> = { getAllEvents: () => Event[]; setEvents: (events: Event[]) => void };\n\nexport const createInMemoryEventRepository = <\n  Event extends GenericEvent<string, unknown, DefaultContext>,\n>(): {\n  eventRepository: EventRepository<Event>;\n  helpers: InMemoryEventRepositoryHelpers<Event>;\n} => {\n  const eventById: Record<string, Event> = {};\n\n  const eventRepository: EventRepository<Event> = {\n    save: async (event) => {\n      eventById[event.id] = event;\n    },\n    saveNewEventsBatch: async (events) => {\n      events.forEach((event) => {\n        eventById[event.id] = event;\n      });\n    },\n    markEventsAsInProcess: async (events) => {\n      events.forEach((event) => {\n        eventById[event.id] = { ...event, status: \"in-process\" };\n      });\n    },\n  };\n\n  return {\n    eventRepository,\n    helpers: {\n      getAllEvents: () => Object.values(eventById),\n      setEvents: (events) => {\n        Object.keys(eventById).forEach((key) => {\n          delete eventById[key];\n        });\n\n        events.forEach((event) => {\n          eventById[event.id] = event;\n        });\n      },\n    },\n  };\n};\n\nexport const createInMemoryWithUow = <\n  Event extends GenericEvent<string, unknown, DefaultContext>,\n>(\n  eventRepository: EventRepository<Event>,\n): { withUow: WithEventsUow<Event> } => {\n  // In-memory adapter awaits afterCommit for predictable test behavior\n  const withUow: WithEventsUow<Event> = async (fn, options) => {\n    const result = await fn({ eventRepository });\n    await options?.afterCommit?.();\n    return result;\n  };\n  return { withUow };\n};\n"],"mappings":"AAUO,MAAM,gCAAgC,MAKxC;AACH,QAAM,YAAmC,CAAC;AAE1C,QAAM,kBAA0C;AAAA,IAC9C,MAAM,OAAO,UAAU;AACrB,gBAAU,MAAM,EAAE,IAAI;AAAA,IACxB;AAAA,IACA,oBAAoB,OAAO,WAAW;AACpC,aAAO,QAAQ,CAAC,UAAU;AACxB,kBAAU,MAAM,EAAE,IAAI;AAAA,MACxB,CAAC;AAAA,IACH;AAAA,IACA,uBAAuB,OAAO,WAAW;AACvC,aAAO,QAAQ,CAAC,UAAU;AACxB,kBAAU,MAAM,EAAE,IAAI,EAAE,GAAG,OAAO,QAAQ,aAAa;AAAA,MACzD,CAAC;AAAA,IACH;AAAA,EACF;AAEA,SAAO;AAAA,IACL;AAAA,IACA,SAAS;AAAA,MACP,cAAc,MAAM,OAAO,OAAO,SAAS;AAAA,MAC3C,WAAW,CAAC,WAAW;AACrB,eAAO,KAAK,SAAS,EAAE,QAAQ,CAAC,QAAQ;AACtC,iBAAO,UAAU,GAAG;AAAA,QACtB,CAAC;AAED,eAAO,QAAQ,CAAC,UAAU;AACxB,oBAAU,MAAM,EAAE,IAAI;AAAA,QACxB,CAAC;AAAA,MACH;AAAA,IACF;AAAA,EACF;AACF;AAEO,MAAM,wBAAwB,CAGnC,oBACsC;AAEtC,QAAM,UAAgC,OAAO,IAAI,YAAY;AAC3D,UAAM,SAAS,MAAM,GAAG,EAAE,gBAAgB,CAAC;AAC3C,UAAM,SAAS,cAAc;AAC7B,WAAO;AAAA,EACT;AACA,SAAO,EAAE,QAAQ;AACnB;","names":[]}

package/dist/ports/EventRepository.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/ports/EventRepository.ts"],"sourcesContent":["import type { DefaultContext, GenericEvent } from \"../types.ts\";\n\n/**\n * Repository interface for persisting events.\n * Implement this to store events in your database (e.g., PostgreSQL, MongoDB).\n * Events should be saved in the same transaction as your domain changes.\n */\nexport type EventRepository<\n  Event extends GenericEvent<string, unknown, DefaultContext>,\n> = {\n  /** Persist a single event (typically after publication status update). */\n  save: (event: Event) => Promise<void>;\n  /** Persist multiple new events in a batch. */\n  saveNewEventsBatch: (events: Event[]) => Promise<void>;\n  /** Mark events as \"in-process\" before publishing (prevents duplicate processing). */\n  markEventsAsInProcess: (events: Event[]) => Promise<void>;\n};\n\n/**\n * Unit of work containing the event repository.\n * Extend this with your own repositories for transactional consistency.\n */\nexport type EventsUnitOfWork<\n  Event extends GenericEvent<string, unknown, DefaultContext>,\n> = {\n  eventRepository: EventRepository<Event>;\n};\n\n/**\n * Options for unit of work execution.\n */\nexport type WithEventsUowOptions = {\n  /**\n   * Callback executed after successful transaction commit.\n   * Useful for triggering event processing in serverless environments.\n   *\n   * The callback should return a Promise. Whether it's awaited depends on\n   * the withUow implementation:\n   * - Serverless (Lambda): await to ensure completion before runtime freezes\n   * - Long-running servers: fire-and-forget for faster response times\n   *\n   * @example\n   * ```typescript\n   * await withUow(async (uow) => {\n   *   await uow.eventRepository.save(event);\n   * }, {\n   *   afterCommit: async () => {\n   *     await eventCrawler.triggerProcessing();\n   *   }\n   * });\n   * ```\n   */\n  afterCommit?: () => Promise<void>;\n};\n\n/**\n * Higher-order function that provides a unit of work for transactional operations.\n * Your implementation should handle transaction begin/commit/rollback.\n *\n * @example\n * ```typescript\n * const withUow: WithEventsUow<MyEvent> = async (fn, options) => {\n *   const tx = await db.beginTransaction();\n *   try {\n *     await fn({ eventRepository: createEventRepo(tx) });\n *     await tx.commit();\n *     options?.afterCommit?.();\n *   } catch (e) {\n *     await tx.rollback();\n *     throw e;\n *   }\n * };\n * ```\n */\nexport type WithEventsUow<\n  Event extends GenericEvent<string, unknown, DefaultContext>,\n> = (\n  fn: (uow: EventsUnitOfWork<Event>) => Promise<void>,\n  options?: WithEventsUowOptions,\n) => Promise<void>;\n"],"mappings":";;;;;;;;;;;;;;AAAA;AAAA;","names":[]}
+{"version":3,"sources":["../../src/ports/EventRepository.ts"],"sourcesContent":["import type { DefaultContext, GenericEvent } from \"../types.ts\";\n\n/**\n * Repository interface for persisting events.\n * Implement this to store events in your database (e.g., PostgreSQL, MongoDB).\n * Events should be saved in the same transaction as your domain changes.\n */\nexport type EventRepository<\n  Event extends GenericEvent<string, unknown, DefaultContext>,\n> = {\n  /** Persist a single event (typically after publication status update). */\n  save: (event: Event) => Promise<void>;\n  /** Persist multiple new events in a batch. */\n  saveNewEventsBatch: (events: Event[]) => Promise<void>;\n  /** Mark events as \"in-process\" before publishing (prevents duplicate processing). */\n  markEventsAsInProcess: (events: Event[]) => Promise<void>;\n};\n\n/**\n * Unit of work containing the event repository.\n * Extend this with your own repositories for transactional consistency.\n */\nexport type EventsUnitOfWork<\n  Event extends GenericEvent<string, unknown, DefaultContext>,\n> = {\n  eventRepository: EventRepository<Event>;\n};\n\n/**\n * Options for unit of work execution.\n */\nexport type WithEventsUowOptions = {\n  /**\n   * Callback executed after successful transaction commit.\n   * Useful for triggering event processing in serverless environments.\n   *\n   * The callback should return a Promise. Whether it's awaited depends on\n   * the withUow implementation:\n   * - Serverless (Lambda): await to ensure completion before runtime freezes\n   * - Long-running servers: fire-and-forget for faster response times\n   *\n   * @example\n   * ```typescript\n   * await withUow(async (uow) => {\n   *   await uow.eventRepository.save(event);\n   * }, {\n   *   afterCommit: async () => {\n   *     await eventCrawler.triggerProcessing();\n   *   }\n   * });\n   * ```\n   */\n  afterCommit?: () => Promise<void>;\n};\n\n/**\n * Higher-order function that provides a unit of work for transactional operations.\n * Your implementation should handle transaction begin/commit/rollback.\n *\n * @example\n * ```typescript\n * const withUow: WithEventsUow<MyEvent> = async (fn, options) => {\n *   const tx = await db.beginTransaction();\n *   try {\n *     const result = await fn({ eventRepository: createEventRepo(tx) });\n *     await tx.commit();\n *     await options?.afterCommit?.();\n *     return result;\n *   } catch (e) {\n *     await tx.rollback();\n *     throw e;\n *   }\n * };\n * ```\n */\nexport type WithEventsUow<\n  Event extends GenericEvent<string, unknown, DefaultContext>,\n> = <T>(\n  fn: (uow: EventsUnitOfWork<Event>) => Promise<T>,\n  options?: WithEventsUowOptions,\n) => Promise<T>;\n"],"mappings":";;;;;;;;;;;;;;AAAA;AAAA;","names":[]}

package/dist/ports/EventRepository.d.cts

@@ -55,9 +55,10 @@ type WithEventsUowOptions = {
  * const withUow: WithEventsUow<MyEvent> = async (fn, options) => {
  *   const tx = await db.beginTransaction();
  *   try {
- *     await fn({ eventRepository: createEventRepo(tx) });
+ *     const result = await fn({ eventRepository: createEventRepo(tx) });
  *     await tx.commit();
- *     options?.afterCommit?.();
+ *     await options?.afterCommit?.();
+ *     return result;
  *   } catch (e) {
  *     await tx.rollback();
  *     throw e;
@@ -65,6 +66,6 @@ type WithEventsUowOptions = {
  * };
  * ```
  */
-type WithEventsUow<Event extends GenericEvent<string, unknown, DefaultContext>> = (fn: (uow: EventsUnitOfWork<Event>) => Promise<void>, options?: WithEventsUowOptions) => Promise<void>;
+type WithEventsUow<Event extends GenericEvent<string, unknown, DefaultContext>> = <T>(fn: (uow: EventsUnitOfWork<Event>) => Promise<T>, options?: WithEventsUowOptions) => Promise<T>;
 
 export type { EventRepository, EventsUnitOfWork, WithEventsUow, WithEventsUowOptions };

package/dist/ports/EventRepository.d.ts

@@ -55,9 +55,10 @@ type WithEventsUowOptions = {
  * const withUow: WithEventsUow<MyEvent> = async (fn, options) => {
  *   const tx = await db.beginTransaction();
  *   try {
- *     await fn({ eventRepository: createEventRepo(tx) });
+ *     const result = await fn({ eventRepository: createEventRepo(tx) });
  *     await tx.commit();
- *     options?.afterCommit?.();
+ *     await options?.afterCommit?.();
+ *     return result;
  *   } catch (e) {
  *     await tx.rollback();
  *     throw e;
@@ -65,6 +66,6 @@ type WithEventsUowOptions = {
  * };
  * ```
  */
-type WithEventsUow<Event extends GenericEvent<string, unknown, DefaultContext>> = (fn: (uow: EventsUnitOfWork<Event>) => Promise<void>, options?: WithEventsUowOptions) => Promise<void>;
+type WithEventsUow<Event extends GenericEvent<string, unknown, DefaultContext>> = <T>(fn: (uow: EventsUnitOfWork<Event>) => Promise<T>, options?: WithEventsUowOptions) => Promise<T>;
 
 export type { EventRepository, EventsUnitOfWork, WithEventsUow, WithEventsUowOptions };

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.3.0",
+  "version": "0.4.0",
   "main": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
   "files": [

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

@@ -56,8 +56,9 @@ export const createInMemoryWithUow = <
 ): { withUow: WithEventsUow<Event> } => {
   // In-memory adapter awaits afterCommit for predictable test behavior
   const withUow: WithEventsUow<Event> = async (fn, options) => {
-    await fn({ eventRepository });
+    const result = await fn({ eventRepository });
     await options?.afterCommit?.();
+    return result;
   };
   return { withUow };
 };

package/src/ports/EventRepository.ts

@@ -62,9 +62,10 @@ export type WithEventsUowOptions = {
  * const withUow: WithEventsUow<MyEvent> = async (fn, options) => {
  *   const tx = await db.beginTransaction();
  *   try {
- *     await fn({ eventRepository: createEventRepo(tx) });
+ *     const result = await fn({ eventRepository: createEventRepo(tx) });
  *     await tx.commit();
- *     options?.afterCommit?.();
+ *     await options?.afterCommit?.();
+ *     return result;
  *   } catch (e) {
  *     await tx.rollback();
  *     throw e;
@@ -74,7 +75,7 @@ export type WithEventsUowOptions = {
  */
 export type WithEventsUow<
   Event extends GenericEvent<string, unknown, DefaultContext>,
-> = (
-  fn: (uow: EventsUnitOfWork<Event>) => Promise<void>,
+> = <T>(
+  fn: (uow: EventsUnitOfWork<Event>) => Promise<T>,
   options?: WithEventsUowOptions,
-) => Promise<void>;
+) => Promise<T>;