@l-etabli/events 0.1.0

package/src/ports/EventBus.ts

@@ -0,0 +1,37 @@
+import type { DefaultContext, GenericEvent, SubscriptionId } from "../types.ts";
+
+/**
+ * Event bus for publishing events to subscribers.
+ * Handles delivery, failure tracking, and retry logic.
+ *
+ * @example
+ * ```typescript
+ * eventBus.subscribe({
+ *   topic: "OrderPlaced",
+ *   subscriptionId: "send-confirmation-email",
+ *   callBack: async (event) => {
+ *     await emailService.sendOrderConfirmation(event.payload);
+ *   },
+ * });
+ * ```
+ */
+export type EventBus<
+  Event extends GenericEvent<string, unknown, DefaultContext>,
+> = {
+  /**
+   * Publish an event to all subscribers of its topic.
+   * Updates event status and records publication results.
+   */
+  publish: (event: Event) => Promise<void>;
+  /**
+   * Register a subscriber for a specific topic.
+   * The subscriptionId must be unique per topic and is used for retry tracking.
+   */
+  subscribe: <
+    Event extends GenericEvent<string, unknown, DefaultContext>,
+  >(params: {
+    topic: Event["topic"];
+    subscriptionId: SubscriptionId;
+    callBack: (e: Event) => Promise<void>;
+  }) => void;
+};

package/src/ports/EventQueries.ts

@@ -0,0 +1,25 @@
+import type { DefaultContext, EventStatus, GenericEvent } from "../types.ts";
+
+/** Parameters for querying events. */
+type GetEventsParams = {
+  filters: {
+    /** Filter by event status (e.g., ["never-published", "failed-but-will-retry"]). */
+    statuses: EventStatus[];
+    /** Optional context filter for multi-tenant scenarios. */
+    context?: Partial<Record<string, string>>;
+  };
+  /** Maximum number of events to return. */
+  limit: number;
+};
+
+/**
+ * Query interface for reading events.
+ * Used by the event crawler to fetch events for processing.
+ * Implement this to query events from your database.
+ */
+export type EventQueries<
+  Event extends GenericEvent<string, unknown, DefaultContext>,
+> = {
+  /** Fetch events matching the given filters. */
+  getEvents: (params: GetEventsParams) => Promise<Event[]>;
+};

package/src/ports/EventRepository.ts

@@ -0,0 +1,49 @@
+import type { DefaultContext, GenericEvent } from "../types.ts";
+
+/**
+ * Repository interface for persisting events.
+ * Implement this to store events in your database (e.g., PostgreSQL, MongoDB).
+ * Events should be saved in the same transaction as your domain changes.
+ */
+export type EventRepository<
+  Event extends GenericEvent<string, unknown, DefaultContext>,
+> = {
+  /** Persist a single event (typically after publication status update). */
+  save: (event: Event) => Promise<void>;
+  /** Persist multiple new events in a batch. */
+  saveNewEventsBatch: (events: Event[]) => Promise<void>;
+  /** Mark events as "in-process" before publishing (prevents duplicate processing). */
+  markEventsAsInProcess: (events: Event[]) => Promise<void>;
+};
+
+/**
+ * Unit of work containing the event repository.
+ * Extend this with your own repositories for transactional consistency.
+ */
+export type EventsUnitOfWork<
+  Event extends GenericEvent<string, unknown, DefaultContext>,
+> = {
+  eventRepository: EventRepository<Event>;
+};
+
+/**
+ * Higher-order function that provides a unit of work for transactional operations.
+ * Your implementation should handle transaction begin/commit/rollback.
+ *
+ * @example
+ * ```typescript
+ * const withUow: WithEventsUow<MyEvent> = async (fn) => {
+ *   const tx = await db.beginTransaction();
+ *   try {
+ *     await fn({ eventRepository: createEventRepo(tx) });
+ *     await tx.commit();
+ *   } catch (e) {
+ *     await tx.rollback();
+ *     throw e;
+ *   }
+ * };
+ * ```
+ */
+export type WithEventsUow<
+  Event extends GenericEvent<string, unknown, DefaultContext>,
+> = (fn: (uow: EventsUnitOfWork<Event>) => Promise<void>) => Promise<void>;

package/src/types.ts

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