@l-etabli/events 0.6.0 → 0.7.0

package/src/effect/EffectInMemoryEventBus.ts

@@ -0,0 +1,231 @@
+import { Cause, Effect, Exit } from "effect";
+import {
+  type CreateNewEvent,
+  type CreateNewEventFromDefinitions,
+  makeCreateNewEvent,
+} from "../createNewEvent.ts";
+import type {
+  EventDefinitions,
+  InferEventsFromDefinitions,
+} from "../eventDefinitions.ts";
+import { getSubscriptionIdsToPublish } from "../getSubscriptionIdsToPublish.ts";
+import type {
+  DefaultContext,
+  EventId,
+  EventPublication,
+  GenericEvent,
+  SubscriptionId,
+} from "../types.ts";
+import {
+  type GlobalSubscriberConfig,
+  subscribeByTopic,
+  subscribeGlobalToTopics,
+  type TopicSubscriptions,
+} from "./EffectSubscriptions.ts";
+import type { EventBus } from "./ports/EffectEventBus.ts";
+import type { WithEventsUow } from "./ports/EffectEventRepository.ts";
+
+type SubscriptionsForTopic = Record<
+  string,
+  (event: GenericEvent<string, unknown, DefaultContext>) => Effect.Effect<void>
+>;
+
+type CreateEffectInMemoryEventBusOptions = {
+  maxRetries?: number;
+  getNow?: () => Date;
+  generateId?: () => EventId;
+};
+
+type CreateEffectInMemoryEventBusFromDefinitionsOptions<
+  Definitions extends EventDefinitions,
+> = CreateEffectInMemoryEventBusOptions & {
+  eventDefinitions: Definitions;
+};
+
+type CreateEffectInMemoryEventBusResult<
+  Event extends GenericEvent<string, unknown, DefaultContext>,
+> = {
+  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 function createEffectInMemoryEventBus<
+  Event extends GenericEvent<string, unknown, DefaultContext>,
+>(
+  withUow: WithEventsUow<Event>,
+  options?: CreateEffectInMemoryEventBusOptions,
+): CreateEffectInMemoryEventBusResult<Event>;
+export function createEffectInMemoryEventBus<
+  Definitions extends EventDefinitions,
+>(
+  withUow: WithEventsUow<InferEventsFromDefinitions<Definitions>>,
+  options: CreateEffectInMemoryEventBusFromDefinitionsOptions<Definitions>,
+): Omit<
+  CreateEffectInMemoryEventBusResult<InferEventsFromDefinitions<Definitions>>,
+  "createNewEvent"
+> & {
+  createNewEvent: CreateNewEventFromDefinitions<Definitions>;
+};
+export function createEffectInMemoryEventBus<
+  Event extends GenericEvent<string, unknown, DefaultContext>,
+>(
+  withUow: WithEventsUow<Event>,
+  options:
+    | CreateEffectInMemoryEventBusOptions
+    | CreateEffectInMemoryEventBusFromDefinitionsOptions<EventDefinitions> = {},
+) {
+  const maxRetries = options.maxRetries ?? 3;
+  const eventDefinitions =
+    "eventDefinitions" in options ? options.eventDefinitions : undefined;
+  const createNewEvent = eventDefinitions
+    ? makeCreateNewEvent({
+        getNow: options.getNow,
+        generateId: options.generateId,
+        eventDefinitions,
+      })
+    : makeCreateNewEvent<Event>({
+        getNow: options.getNow,
+        generateId: options.generateId,
+      });
+  const subscriptions: Partial<Record<string, SubscriptionsForTopic>> = {};
+
+  const executeCallback = (
+    event: Event,
+    subscriptionId: string,
+    callback: (
+      event: GenericEvent<string, unknown, DefaultContext>,
+    ) => Effect.Effect<void>,
+  ): Effect.Effect<
+    { subscriptionId: string; errorMessage: string; stack?: string } | undefined
+  > =>
+    Effect.map(
+      Effect.exit(callback(event)),
+      (
+        exit,
+      ):
+        | { subscriptionId: string; errorMessage: string; stack?: string }
+        | undefined => {
+        if (Exit.isSuccess(exit)) return undefined;
+        const error = Cause.squash(exit.cause);
+        return {
+          subscriptionId,
+          errorMessage: error instanceof Error ? error.message : String(error),
+          stack: error instanceof Error ? error.stack : undefined,
+        };
+      },
+    );
+
+  const eventBus: EventBus<Event> = {
+    publish: (event) =>
+      Effect.gen(function* () {
+        const publishedAt = new Date();
+        const topic = event.topic;
+
+        const callbacksBySubscriptionSlug = subscriptions[topic];
+
+        if (!callbacksBySubscriptionSlug) {
+          event.publications.push({
+            publishedAt,
+            publishedSubscribers: [],
+          });
+          event.status = "published";
+          yield* withUow((uow) => uow.eventRepository.save(event));
+          return;
+        }
+
+        const subscriptionIdsToPublish = getSubscriptionIdsToPublish(
+          event,
+          Object.keys(callbacksBySubscriptionSlug),
+        );
+
+        const failuresOrUndefined = yield* Effect.all(
+          subscriptionIdsToPublish.map((subscriptionId) =>
+            executeCallback(
+              event,
+              subscriptionId,
+              callbacksBySubscriptionSlug[subscriptionId],
+            ),
+          ),
+          { concurrency: "unbounded" },
+        );
+
+        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.length > 0 && { 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;
+
+        yield* withUow((uow) => 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>,
+        ) => Effect.Effect<void>;
+      }
+    },
+  };
+
+  const defineSubscriptions = (
+    subs: TopicSubscriptions<Event>,
+  ): TopicSubscriptions<Event> => subs;
+
+  const subscribeAll = (subs: TopicSubscriptions<Event>): void => {
+    subscribeByTopic(eventBus, subs);
+  };
+
+  const subscribeGlobal = (
+    subs: TopicSubscriptions<Event>,
+    config: GlobalSubscriberConfig<Event>,
+  ): void => {
+    subscribeGlobalToTopics(eventBus, subs, config);
+  };
+
+  return {
+    eventBus,
+    createNewEvent,
+    defineSubscriptions,
+    subscribeAll,
+    subscribeGlobal,
+  };
+}

package/src/effect/EffectInMemoryEventQueries.ts

@@ -0,0 +1,16 @@
+import { Effect } from "effect";
+import { filterEvents } from "../filterEvents.ts";
+import type { DefaultContext, GenericEvent } from "../types.ts";
+import type { InMemoryEventRepositoryHelpers } from "./EffectInMemoryEventRepository.ts";
+import type { EventQueries } from "./ports/EffectEventQueries.ts";
+
+export const createEffectInMemoryEventQueries = <
+  Event extends GenericEvent<string, unknown, DefaultContext>,
+>(
+  helpers: InMemoryEventRepositoryHelpers<Event>,
+): { eventQueries: EventQueries<Event> } => ({
+  eventQueries: {
+    getEvents: (params) =>
+      Effect.sync(() => filterEvents(helpers.getAllEvents(), params)),
+  },
+});

package/src/effect/EffectInMemoryEventRepository.ts

@@ -0,0 +1,68 @@
+import { Effect } from "effect";
+import type { InMemoryEventRepositoryHelpers } from "../adapters/in-memory/InMemoryEventRepository.ts";
+import type { DefaultContext, GenericEvent } from "../types.ts";
+import type {
+  EventRepository,
+  WithEventsUow,
+} from "./ports/EffectEventRepository.ts";
+
+export type { InMemoryEventRepositoryHelpers };
+
+export const createEffectInMemoryEventRepository = <
+  Event extends GenericEvent<string, unknown, DefaultContext>,
+>(): {
+  eventRepository: EventRepository<Event>;
+  helpers: InMemoryEventRepositoryHelpers<Event>;
+} => {
+  const eventById: Record<string, Event> = {};
+
+  const eventRepository: EventRepository<Event> = {
+    save: (event) =>
+      Effect.sync(() => {
+        eventById[event.id] = event;
+      }),
+    saveNewEventsBatch: (events) =>
+      Effect.sync(() => {
+        for (const event of events) {
+          eventById[event.id] = event;
+        }
+      }),
+    markEventsAsInProcess: (events) =>
+      Effect.sync(() => {
+        for (const event of events) {
+          eventById[event.id] = { ...event, status: "in-process" };
+        }
+      }),
+  };
+
+  return {
+    eventRepository,
+    helpers: {
+      getAllEvents: () => Object.values(eventById),
+      setEvents: (events) => {
+        for (const key of Object.keys(eventById)) {
+          delete eventById[key];
+        }
+        for (const event of events) {
+          eventById[event.id] = event;
+        }
+      },
+    },
+  };
+};
+
+export const createEffectInMemoryWithUow = <
+  Event extends GenericEvent<string, unknown, DefaultContext>,
+>(
+  eventRepository: EventRepository<Event>,
+): { withUow: WithEventsUow<Event> } => {
+  const withUow: WithEventsUow<Event> = (fn, options) =>
+    Effect.gen(function* () {
+      const result = yield* fn({ eventRepository });
+      if (options?.afterCommit) {
+        yield* options.afterCommit();
+      }
+      return result;
+    });
+  return { withUow };
+};

package/src/effect/EffectSubscriptions.ts

@@ -0,0 +1,74 @@
+import type { Effect } from "effect";
+import type { NarrowEvent, TopicFilter } from "../subscriptions.ts";
+import type { DefaultContext, GenericEvent, SubscriptionId } from "../types.ts";
+import type { EventBus } from "./ports/EffectEventBus.ts";
+
+export type { NarrowEvent, TopicFilter };
+
+export type TopicSubscriber<
+  E extends GenericEvent<string, unknown, DefaultContext>,
+> = {
+  subscriptionId: SubscriptionId;
+  handler: (event: E) => Effect.Effect<void>;
+};
+
+export type TopicSubscriptions<
+  AllEvents extends GenericEvent<string, unknown, DefaultContext>,
+> = {
+  [K in AllEvents["topic"]]: Array<TopicSubscriber<NarrowEvent<AllEvents, K>>>;
+};
+
+export type GlobalSubscriberConfig<
+  AllEvents extends GenericEvent<string, unknown, DefaultContext>,
+> = {
+  subscriptionId: SubscriptionId;
+  handler: (event: AllEvents) => Effect.Effect<void>;
+  filter?: TopicFilter<AllEvents["topic"]>;
+};
+
+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,
+      });
+    }
+  }
+}
+
+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/effect/index.ts

@@ -0,0 +1,26 @@
+import type { DefaultContext, GenericEvent } from "../types.ts";
+import { createEffectInMemoryEventQueries } from "./EffectInMemoryEventQueries.ts";
+import {
+  createEffectInMemoryEventRepository,
+  createEffectInMemoryWithUow,
+} from "./EffectInMemoryEventRepository.ts";
+
+export type { GetEventsParams } from "../ports/EventQueries.ts";
+export * from "./EffectEventCrawler.ts";
+export * from "./EffectInMemoryEventBus.ts";
+export * from "./EffectInMemoryEventQueries.ts";
+export * from "./EffectInMemoryEventRepository.ts";
+export * from "./EffectSubscriptions.ts";
+export type * from "./ports/EffectEventBus.ts";
+export type * from "./ports/EffectEventQueries.ts";
+export type * from "./ports/EffectEventRepository.ts";
+
+export const createEffectInMemoryEventRepositoryAndQueries = <
+  Event extends GenericEvent<string, unknown, DefaultContext>,
+>() => {
+  const { eventRepository, helpers } =
+    createEffectInMemoryEventRepository<Event>();
+  const { eventQueries } = createEffectInMemoryEventQueries<Event>(helpers);
+  const { withUow } = createEffectInMemoryWithUow<Event>(eventRepository);
+  return { eventRepository, eventQueries, helpers, withUow };
+};

package/src/effect/ports/EffectEventBus.ts

@@ -0,0 +1,17 @@
+import type { Effect } from "effect";
+import type {
+  DefaultContext,
+  GenericEvent,
+  SubscriptionId,
+} from "../../types.ts";
+
+export type EventBus<
+  Event extends GenericEvent<string, unknown, DefaultContext>,
+> = {
+  publish: (event: Event) => Effect.Effect<void>;
+  subscribe: <E extends GenericEvent<string, unknown, DefaultContext>>(params: {
+    topic: E["topic"];
+    subscriptionId: SubscriptionId;
+    callBack: (e: E) => Effect.Effect<void>;
+  }) => void;
+};

package/src/effect/ports/EffectEventQueries.ts

@@ -0,0 +1,9 @@
+import type { Effect } from "effect";
+import type { GetEventsParams } from "../../ports/EventQueries.ts";
+import type { DefaultContext, GenericEvent } from "../../types.ts";
+
+export type EventQueries<
+  Event extends GenericEvent<string, unknown, DefaultContext>,
+> = {
+  getEvents: (params: GetEventsParams) => Effect.Effect<Event[]>;
+};

package/src/effect/ports/EffectEventRepository.ts

@@ -0,0 +1,27 @@
+import type { Effect } from "effect";
+import type { DefaultContext, GenericEvent } from "../../types.ts";
+
+export type EventRepository<
+  Event extends GenericEvent<string, unknown, DefaultContext>,
+> = {
+  save: (event: Event) => Effect.Effect<void>;
+  saveNewEventsBatch: (events: Event[]) => Effect.Effect<void>;
+  markEventsAsInProcess: (events: Event[]) => Effect.Effect<void>;
+};
+
+export type EventsUnitOfWork<
+  Event extends GenericEvent<string, unknown, DefaultContext>,
+> = {
+  eventRepository: EventRepository<Event>;
+};
+
+export type WithEventsUowOptions = {
+  afterCommit?: () => Effect.Effect<void>;
+};
+
+export type WithEventsUow<
+  Event extends GenericEvent<string, unknown, DefaultContext>,
+> = <T>(
+  fn: (uow: EventsUnitOfWork<Event>) => Effect.Effect<T>,
+  options?: WithEventsUowOptions,
+) => Effect.Effect<T>;

package/src/filterEvents.ts

@@ -0,0 +1,39 @@
+import type { GetEventsParams } from "./ports/EventQueries.ts";
+import type { DefaultContext, GenericEvent } from "./types.ts";
+
+export const filterEvents = <
+  Event extends GenericEvent<string, unknown, DefaultContext>,
+>(
+  events: Event[],
+  { filters, limit }: GetEventsParams,
+): Event[] => {
+  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,
+    );
+  };
+
+  const matchesOccurredAt = (event: Event): boolean => {
+    if (!filters.occurredAt) return true;
+
+    const { from, to } = filters.occurredAt;
+    const eventTime = event.occurredAt.getTime();
+
+    if (from && eventTime < from.getTime()) return false;
+    if (to && eventTime > to.getTime()) return false;
+
+    return true;
+  };
+
+  return events
+    .filter(
+      (event) =>
+        filters.statuses.includes(event.status) &&
+        matchesContext(event) &&
+        matchesOccurredAt(event),
+    )
+    .slice(0, limit);
+};

package/src/getSubscriptionIdsToPublish.ts

@@ -0,0 +1,21 @@
+import type { DefaultContext, GenericEvent } from "./types.ts";
+
+export const getSubscriptionIdsToPublish = <
+  Event extends GenericEvent<string, unknown, DefaultContext>,
+>(
+  event: Event,
+  allSubscriptionIds: string[],
+): string[] => {
+  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));
+};

package/src/ports/EventQueries.ts

@@ -1,7 +1,7 @@
 import type { DefaultContext, EventStatus, GenericEvent } from "../types.ts";
 
 /** Parameters for querying events. */
-type GetEventsParams = {
+export type GetEventsParams = {
   filters: {
     /** Filter by event status (e.g., ["never-published", "failed-but-will-retry"]). */
     statuses: EventStatus[];

package/src/splitIntoChunks.ts

@@ -0,0 +1,7 @@
+export 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;
+};