@l-etabli/events 0.1.0

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

@@ -0,0 +1,165 @@
+import { makeCreateNewEvent } from "../../createNewEvent.ts";
+import type { EventBus } from "../../ports/EventBus.ts";
+import type { WithEventsUow } from "../../ports/EventRepository.ts";
+import type {
+  DefaultContext,
+  EventId,
+  EventPublication,
+  GenericEvent,
+  SubscriptionId,
+} from "../../types.ts";
+
+type SubscriptionsForTopic = Record<
+  string,
+  (event: GenericEvent<string, unknown, DefaultContext>) => Promise<void>
+>;
+
+type CreateInMemoryEventBusOptions = {
+  maxRetries?: number;
+  getNow?: () => Date;
+  generateId?: () => EventId;
+};
+
+export const createInMemoryEventBus = <
+  Event extends GenericEvent<string, unknown, DefaultContext>,
+>(
+  withUow: WithEventsUow<Event>,
+  options: CreateInMemoryEventBusOptions = {},
+) => {
+  const maxRetries = options.maxRetries ?? 3;
+  const createNewEvent = makeCreateNewEvent<Event>({
+    getNow: options.getNow,
+    generateId: options.generateId,
+  });
+  const subscriptions: Partial<Record<string, SubscriptionsForTopic>> = {};
+
+  const executeCallback = async (
+    event: Event,
+    subscriptionId: string,
+    callback: (
+      event: GenericEvent<string, unknown, DefaultContext>,
+    ) => Promise<void>,
+  ): Promise<
+    { subscriptionId: string; errorMessage: string; stack?: string } | undefined
+  > => {
+    try {
+      await callback(event);
+    } catch (error) {
+      return {
+        subscriptionId,
+        errorMessage: error instanceof Error ? error.message : String(error),
+        stack: error instanceof Error ? error.stack : undefined,
+      };
+    }
+  };
+
+  const getSubscriptionIdsToPublish = (
+    event: Event,
+    callbacksBySubscriptionId: SubscriptionsForTopic,
+  ): string[] => {
+    const allSubscriptionIds = Object.keys(callbacksBySubscriptionId);
+
+    if (event.publications.length === 0 || event.status === "to-republish") {
+      return allSubscriptionIds;
+    }
+
+    const lastPublication = event.publications.reduce((latest, current) =>
+      current.publishedAt > latest.publishedAt ? current : latest,
+    );
+    const failedSubscriptionIds = lastPublication.failures.map(
+      (failure) => failure.subscriptionId,
+    );
+
+    return allSubscriptionIds.filter((id) =>
+      failedSubscriptionIds.includes(id),
+    );
+  };
+
+  const eventBus: EventBus<Event> = {
+    publish: async (event) => {
+      const publishedAt = new Date();
+      const topic = event.topic;
+
+      const callbacksBySubscriptionSlug = subscriptions[topic];
+
+      if (!callbacksBySubscriptionSlug) {
+        event.publications.push({
+          publishedAt,
+          publishedSubscribers: [],
+          failures: [],
+        });
+        event.status = "published";
+        await withUow(async (uow) => {
+          await uow.eventRepository.save(event);
+        });
+        return;
+      }
+
+      const subscriptionIdsToPublish = getSubscriptionIdsToPublish(
+        event,
+        callbacksBySubscriptionSlug,
+      );
+
+      const failuresOrUndefined = await Promise.all(
+        subscriptionIdsToPublish.map((subscriptionId) =>
+          executeCallback(
+            event,
+            subscriptionId,
+            callbacksBySubscriptionSlug[subscriptionId],
+          ),
+        ),
+      );
+
+      const failures = failuresOrUndefined.filter(
+        (
+          f,
+        ): f is {
+          subscriptionId: string;
+          errorMessage: string;
+          stack?: string;
+        } => f !== undefined,
+      );
+
+      const publications: EventPublication[] = [
+        ...event.publications,
+        {
+          publishedAt,
+          publishedSubscribers: subscriptionIdsToPublish.map(
+            (id) => id as SubscriptionId,
+          ),
+          failures,
+        },
+      ];
+
+      if (failures.length === 0) {
+        event.status = "published";
+      } else {
+        const wasMaxNumberOfErrorsReached = publications.length >= maxRetries;
+        event.status = wasMaxNumberOfErrorsReached
+          ? "quarantined"
+          : "failed-but-will-retry";
+      }
+
+      event.publications = publications;
+
+      await withUow(async (uow) => {
+        await uow.eventRepository.save(event);
+      });
+    },
+
+    subscribe: ({ topic, subscriptionId, callBack }) => {
+      if (!subscriptions[topic]) {
+        subscriptions[topic] = {};
+      }
+
+      const subscriptionsForTopic = subscriptions[topic];
+      if (subscriptionsForTopic) {
+        subscriptionsForTopic[subscriptionId] = callBack as (
+          event: GenericEvent<string, unknown, DefaultContext>,
+        ) => Promise<void>;
+      }
+    },
+  };
+
+  return { eventBus, createNewEvent };
+};

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

@@ -0,0 +1,30 @@
+import type { EventQueries } from "../../ports/EventQueries.ts";
+import type { DefaultContext, GenericEvent } from "../../types.ts";
+import type { InMemoryEventRepositoryHelpers } from "./InMemoryEventRepository.ts";
+
+export const createInMemoryEventQueries = <
+  Event extends GenericEvent<string, unknown, DefaultContext>,
+>(
+  helpers: InMemoryEventRepositoryHelpers<Event>,
+): { eventQueries: EventQueries<Event> } => ({
+  eventQueries: {
+    getEvents: async ({ filters, limit }) => {
+      const matchesContext = (event: Event): boolean => {
+        if (!filters.context) return true;
+        if (!event.context) return false;
+
+        return Object.entries(filters.context).every(
+          ([key, value]) => event.context?.[key] === value,
+        );
+      };
+
+      return helpers
+        .getAllEvents()
+        .filter(
+          (event) =>
+            filters.statuses.includes(event.status) && matchesContext(event),
+        )
+        .slice(0, limit);
+    },
+  },
+});

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

@@ -0,0 +1,61 @@
+import type {
+  EventRepository,
+  WithEventsUow,
+} from "../../ports/EventRepository.ts";
+import type { DefaultContext, GenericEvent } from "../../types.ts";
+
+export type InMemoryEventRepositoryHelpers<
+  Event extends GenericEvent<string, unknown, DefaultContext>,
+> = { getAllEvents: () => Event[]; setEvents: (events: Event[]) => void };
+
+export const createInMemoryEventRepository = <
+  Event extends GenericEvent<string, unknown, DefaultContext>,
+>(): {
+  eventRepository: EventRepository<Event>;
+  helpers: InMemoryEventRepositoryHelpers<Event>;
+} => {
+  const eventById: Record<string, Event> = {};
+
+  const eventRepository: EventRepository<Event> = {
+    save: async (event) => {
+      eventById[event.id] = event;
+    },
+    saveNewEventsBatch: async (events) => {
+      events.forEach((event) => {
+        eventById[event.id] = event;
+      });
+    },
+    markEventsAsInProcess: async (events) => {
+      events.forEach((event) => {
+        eventById[event.id] = { ...event, status: "in-process" };
+      });
+    },
+  };
+
+  return {
+    eventRepository,
+    helpers: {
+      getAllEvents: () => Object.values(eventById),
+      setEvents: (events) => {
+        Object.keys(eventById).forEach((key) => {
+          delete eventById[key];
+        });
+
+        events.forEach((event) => {
+          eventById[event.id] = event;
+        });
+      },
+    },
+  };
+};
+
+export const createInMemoryWithUow = <
+  Event extends GenericEvent<string, unknown, DefaultContext>,
+>(
+  eventRepository: EventRepository<Event>,
+): { withUow: WithEventsUow<Event> } => {
+  const withUow: WithEventsUow<Event> = async (fn) => {
+    await fn({ eventRepository });
+  };
+  return { withUow };
+};

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

@@ -0,0 +1,19 @@
+import type { DefaultContext, GenericEvent } from "../../types.ts";
+import { createInMemoryEventQueries } from "./InMemoryEventQueries.ts";
+import {
+  createInMemoryEventRepository,
+  createInMemoryWithUow,
+} from "./InMemoryEventRepository.ts";
+
+export * from "./InMemoryEventBus.ts";
+export * from "./InMemoryEventQueries.ts";
+export * from "./InMemoryEventRepository.ts";
+
+export const createInMemoryEventRepositoryAndQueries = <
+  Event extends GenericEvent<string, unknown, DefaultContext>,
+>() => {
+  const { eventRepository, helpers } = createInMemoryEventRepository<Event>();
+  const { eventQueries } = createInMemoryEventQueries<Event>(helpers);
+  const { withUow } = createInMemoryWithUow<Event>(eventRepository);
+  return { eventRepository, eventQueries, helpers, withUow };
+};

package/src/adapters/kysely/KyselyEventQueries.ts

@@ -0,0 +1,35 @@
+import type { Kysely, SqlBool } from "kysely";
+import { sql } from "kysely";
+import type { EventQueries } from "../../ports/EventQueries.ts";
+import type { DefaultContext, GenericEvent } from "../../types.ts";
+import type { EventsTable } from "./types.ts";
+
+export const createKyselyEventQueries = <
+  Event extends GenericEvent<string, unknown, DefaultContext>,
+>(
+  db: Kysely<EventsTable>,
+): EventQueries<Event> => ({
+  getEvents: async ({ filters, limit }) => {
+    let query = db
+      .selectFrom("events")
+      .selectAll()
+      .where("status", "in", filters.statuses)
+      .limit(limit);
+
+    if (filters.context) {
+      for (const [key, value] of Object.entries(filters.context)) {
+        query = query.where(sql<SqlBool>`context->>${key} = ${value}`);
+      }
+    }
+
+    const rows = await query.execute();
+    return rows.map(
+      (row) =>
+        ({
+          ...row,
+          context: row.context ?? undefined,
+          priority: row.priority ?? undefined,
+        }) as Event,
+    );
+  },
+});

package/src/adapters/kysely/KyselyEventRepository.ts

@@ -0,0 +1,44 @@
+import type { Kysely } from "kysely";
+import type { EventRepository } from "../../ports/EventRepository.ts";
+import type { DefaultContext, GenericEvent } from "../../types.ts";
+import type { EventsTable } from "./types.ts";
+
+export const createKyselyEventRepository = <
+  Event extends GenericEvent<string, unknown, DefaultContext>,
+>(
+  db: Kysely<EventsTable>,
+): EventRepository<Event> => ({
+  save: async (event) => {
+    await db
+      .insertInto("events")
+      .values(event)
+      .onConflict((oc) =>
+        oc.column("id").doUpdateSet({
+          topic: event.topic,
+          payload: event.payload,
+          context: event.context,
+          status: event.status,
+          triggeredByUserId: event.triggeredByUserId,
+          occurredAt: event.occurredAt,
+          publications: event.publications,
+          priority: event.priority,
+        }),
+      )
+      .execute();
+  },
+
+  saveNewEventsBatch: async (events) => {
+    if (events.length === 0) return;
+    await db.insertInto("events").values(events).execute();
+  },
+
+  markEventsAsInProcess: async (events) => {
+    if (events.length === 0) return;
+    const ids = events.map((e) => e.id);
+    await db
+      .updateTable("events")
+      .set({ status: "in-process" })
+      .where("id", "in", ids)
+      .execute();
+  },
+});

package/src/adapters/kysely/index.ts

@@ -0,0 +1,3 @@
+export { createKyselyEventQueries } from "./KyselyEventQueries.ts";
+export { createKyselyEventRepository } from "./KyselyEventRepository.ts";
+export type { EventsTable, TypedEventsTable } from "./types.ts";

package/src/adapters/kysely/migration.ts

@@ -0,0 +1,39 @@
+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();
+
+  // Add B-tree indexes for context keys you query frequently.
+  // Kysely's .column() doesn't support expressions, use raw SQL:
+  //
+  // await sql`CREATE INDEX events_context_user_id_idx ON events ((context->>'userId'))`.execute(db);
+  // await sql`CREATE INDEX events_context_tenant_id_idx ON events ((context->>'tenantId'))`.execute(db);
+  // await sql`CREATE INDEX events_context_project_id_idx ON events ((context->>'projectId'))`.execute(db);
+}
+
+export async function down(db: Kysely<unknown>): Promise<void> {
+  await db.schema.dropTable("events").execute();
+}

package/src/adapters/kysely/types.ts

@@ -0,0 +1,37 @@
+import type {
+  DefaultContext,
+  EventPublication,
+  EventStatus,
+  GenericEvent,
+} from "../../types.ts";
+
+export type EventsTable = {
+  events: {
+    id: string;
+    topic: string;
+    payload: unknown;
+    context: unknown;
+    status: EventStatus;
+    triggeredByUserId: string;
+    occurredAt: Date;
+    publications: EventPublication[];
+    priority: number | null;
+  };
+};
+
+export type TypedEventsTable<
+  Event extends GenericEvent<string, unknown, DefaultContext>,
+  Topic extends Event["topic"] = Event["topic"],
+> = {
+  events: {
+    id: string;
+    topic: Topic;
+    payload: Extract<Event, { topic: Topic }>["payload"];
+    context: Extract<Event, { topic: Topic }>["context"] | null;
+    status: EventStatus;
+    triggeredByUserId: string;
+    occurredAt: Date;
+    publications: EventPublication[];
+    priority: number | null;
+  };
+};

package/src/createEventCrawler.ts

@@ -0,0 +1,139 @@
+import type { EventBus } from "./ports/EventBus.ts";
+import type { EventQueries } from "./ports/EventQueries.ts";
+import type { WithEventsUow } from "./ports/EventRepository.ts";
+import type { DefaultContext, GenericEvent } from "./types.ts";
+
+/** Configuration options for the event crawler. */
+type CreateEventCrawlerOptions = {
+  /** Max events to fetch per batch (default: 100). */
+  batchSize?: number;
+  /** Max events to publish in parallel (default: 1). */
+  maxParallelProcessing?: number;
+  /** Interval for processing new events in ms (default: 10000). */
+  newEventsIntervalMs?: number;
+  /** Interval for retrying failed events in ms (default: 60000). */
+  failedEventsIntervalMs?: number;
+};
+
+const splitIntoChunks = <T>(array: T[], chunkSize: number): T[][] => {
+  const chunks: T[][] = [];
+  for (let i = 0; i < array.length; i += chunkSize) {
+    chunks.push(array.slice(i, i + chunkSize));
+  }
+  return chunks;
+};
+
+/**
+ * Creates a background event crawler that processes and publishes events.
+ *
+ * The crawler runs two loops:
+ * 1. Process new events: polls for "never-published" events and publishes them
+ * 2. Retry failed events: polls for failed events and retries them
+ *
+ * @returns Object with:
+ * - `start()`: Start the background polling loops
+ * - `processNewEvents()`: Manually trigger new event processing
+ * - `retryFailedEvents()`: Manually trigger failed event retry
+ *
+ * @example
+ * ```typescript
+ * const crawler = createEventCrawler({
+ *   withUow,
+ *   eventQueries,
+ *   eventBus,
+ *   options: { batchSize: 50, newEventsIntervalMs: 5000 },
+ * });
+ *
+ * // Start background processing
+ * crawler.start();
+ *
+ * // Or trigger manually (useful for testing)
+ * await crawler.processNewEvents();
+ * ```
+ */
+export const createEventCrawler = <
+  Event extends GenericEvent<string, unknown, DefaultContext>,
+>({
+  withUow,
+  eventQueries,
+  eventBus,
+  options = {},
+}: {
+  withUow: WithEventsUow<Event>;
+  eventQueries: EventQueries<Event>;
+  eventBus: EventBus<Event>;
+  options?: CreateEventCrawlerOptions;
+}) => {
+  const batchSize = options.batchSize ?? 100;
+  const maxParallelProcessing = options.maxParallelProcessing ?? 1;
+  const newEventsIntervalMs = options.newEventsIntervalMs ?? 10_000;
+  const failedEventsIntervalMs = options.failedEventsIntervalMs ?? 60_000;
+
+  const publishEventsInParallel = async (events: Event[]) => {
+    const eventChunks = splitIntoChunks(events, maxParallelProcessing);
+    for (const chunk of eventChunks) {
+      await Promise.all(chunk.map((event) => eventBus.publish(event)));
+    }
+  };
+
+  const processNewEvents = async (): Promise<void> => {
+    const events = await eventQueries.getEvents({
+      filters: { statuses: ["never-published"] },
+      limit: batchSize,
+    });
+
+    if (events.length === 0) return;
+
+    await withUow(async (uow) => {
+      await uow.eventRepository.markEventsAsInProcess(events);
+    });
+
+    await publishEventsInParallel(events);
+  };
+
+  const retryFailedEvents = async (): Promise<void> => {
+    const events = await eventQueries.getEvents({
+      filters: { statuses: ["to-republish", "failed-but-will-retry"] },
+      limit: batchSize,
+    });
+
+    if (events.length === 0) return;
+
+    await publishEventsInParallel(events);
+  };
+
+  const start = () => {
+    const scheduleProcessNewEvents = () => {
+      setTimeout(async () => {
+        try {
+          await processNewEvents();
+        } catch (error) {
+          console.error("Error processing new events:", error);
+        } finally {
+          scheduleProcessNewEvents();
+        }
+      }, newEventsIntervalMs);
+    };
+
+    const scheduleRetryFailedEvents = () => {
+      setTimeout(async () => {
+        try {
+          await retryFailedEvents();
+        } catch (error) {
+          console.error("Error retrying failed events:", error);
+        } finally {
+          scheduleRetryFailedEvents();
+        }
+      }, failedEventsIntervalMs);
+    };
+
+    scheduleProcessNewEvents();
+    scheduleRetryFailedEvents();
+  };
+
+  return {
+    processNewEvents,
+    retryFailedEvents,
+    start,
+  };
+};

package/src/createNewEvent.ts

@@ -0,0 +1,87 @@
+import type { DefaultContext, EventId, GenericEvent, UserId } from "./types.ts";
+
+type MakeCreateNewEventOptions = {
+  getNow?: () => Date;
+  generateId?: () => EventId;
+};
+
+type ContextParam<
+  Event extends GenericEvent<string, unknown, DefaultContext>,
+  Topic extends Event["topic"],
+> = Extract<Event, { topic: Topic }>["context"] extends undefined
+  ? { context?: undefined }
+  : { context: Extract<Event, { topic: Topic }>["context"] };
+
+type CreateNewEventParams<
+  Event extends GenericEvent<string, unknown, DefaultContext>,
+  Topic extends Event["topic"],
+> = {
+  topic: Topic;
+  payload: Extract<Event, { topic: Topic }>["payload"];
+  triggeredByUserId: UserId;
+  id?: EventId;
+  occurredAt?: Date;
+  priority?: number;
+} & ContextParam<Event, Topic>;
+
+/**
+ * Creates a typed event creator factory for your event union.
+ * Provides type-safe event creation where topic constrains payload type.
+ *
+ * @param options.getNow - Function to get current time (default: `() => new Date()`)
+ * @param options.generateId - Function to generate event IDs (default: `() => crypto.randomUUID()`)
+ *
+ * @example
+ * ```typescript
+ * type MyEvents =
+ *   | GenericEvent<"UserCreated", { email: string }>
+ *   | GenericEvent<"OrderPlaced", { orderId: string }>;
+ *
+ * // Standalone usage:
+ * const createEvent = makeCreateNewEvent<MyEvents>();
+ *
+ * // Or get it from createInMemoryEventBus (recommended):
+ * const { eventBus, createEvent } = createInMemoryEventBus<MyEvents>(withUow);
+ *
+ * // Type-safe: payload must match topic
+ * createEvent({ topic: "UserCreated", payload: { email: "a@b.com" }, triggeredByUserId: "u1" }); // OK
+ * createEvent({ topic: "UserCreated", payload: { orderId: "123" }, triggeredByUserId: "u1" }); // Error!
+ *
+ * // For testing, inject deterministic functions:
+ * const createEvent = makeCreateNewEvent<MyEvents>({
+ *   getNow: () => new Date("2024-01-01"),
+ *   generateId: () => "test-id",
+ * });
+ * ```
+ */
+
+export type CreateNewEvent<
+  Event extends GenericEvent<string, unknown, DefaultContext>,
+> = <Topic extends Event["topic"]>(
+  params: CreateNewEventParams<Event, Topic>,
+) => Extract<Event, { topic: Topic }>;
+
+export const makeCreateNewEvent = <
+  Event extends GenericEvent<string, unknown, DefaultContext>,
+>(
+  options: MakeCreateNewEventOptions = {},
+): CreateNewEvent<Event> => {
+  const getNow = options.getNow ?? (() => new Date());
+  const generateId =
+    options.generateId ?? (() => crypto.randomUUID() as EventId);
+
+  return <Topic extends Event["topic"]>(
+    params: CreateNewEventParams<Event, Topic>,
+  ): Extract<Event, { topic: Topic }> =>
+    ({
+      id: params.id ?? generateId(),
+      topic: params.topic,
+      payload: params.payload,
+      triggeredByUserId: params.triggeredByUserId,
+      occurredAt: params.occurredAt ?? getNow(),
+      status: "never-published",
+      publications: [],
+      priority: params.priority,
+      context: params.context,
+    }) as unknown as Extract<Event, { topic: Topic }>;
+};

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from "./adapters/in-memory/index.ts";
+export * from "./createEventCrawler.ts";
+export * from "./createNewEvent.ts";
+export type * from "./ports/EventBus.ts";
+export type * from "./ports/EventQueries.ts";
+export type * from "./ports/EventRepository.ts";
+export type * from "./types.ts";