@arki/event-sourcing 0.1.0 → 0.1.2

package/src/dot.ts

@@ -0,0 +1,161 @@
+/**
+ * DOT adapter for `@arki/event-sourcing`.
+ *
+ * Wraps `eventSourcingFeatures.initEventSourcing` + `initMessageBus` as a
+ * single `DotPip`. The pip opens the PostgreSQL event store in
+ * `boot`, attaches command handlers to an in-memory message bus, publishes
+ * both as `services.eventStore` and `services.messageBus`, and closes the
+ * event store pool in `dispose` (reverse-topological order).
+ *
+ * @example
+ * ```ts
+ * import { defineApp } from '@arki/dot';
+ * import { eventSourcing } from '@arki/event-sourcing/dot';
+ *
+ * const app = await defineApp('my-app')
+ *   .use(eventSourcing({
+ *     projections: [orderProjection, invoiceProjection],
+ *     commandHandlers: [placeOrderHandler, cancelOrderHandler],
+ *   }))
+ *   .boot();
+ *
+ * await app.services.messageBus.send({ type: 'PlaceOrder', payload: { ... } });
+ * await app.dispose();
+ * ```
+ *
+ * The connection URL is resolved in this order:
+ *   1. `options.dbUrl` if provided
+ *   2. `process.env.EVENT_STORE_URL`
+ *   3. `process.env.EVENTSTORE_URL`
+ *   4. `process.env.EVENT_DB_URL`
+ *
+ * If none are set, `boot` throws with a message naming every accepted env
+ * var — same contract as `eventSourcingFeatures.initEventSourcing`.
+ *
+ * The `@arki/dot` package is an OPTIONAL peer of `@arki/event-sourcing`.
+ * Importing this adapter without `@arki/dot` installed will fail at module
+ * load — that is intentional: the adapter only makes sense in a DOT app.
+ */
+
+import type { EventStore, MessageBus } from '@event-driven-io/emmett';
+
+import type { EmptyShape, Pip } from '@arki/dot/pip';
+import { pip, DotPipError } from '@arki/dot/pip';
+
+import type { CommandHandlerRegistration } from './command.js';
+import type { PostgreSQLProjectionInput } from './event-sourcing-features.js';
+import { EVENT_STORE_URL_VARIANTS, eventSourcingFeatures } from './event-sourcing-features.js';
+
+/**
+ * Stable error codes thrown by the event-sourcing pip. Exported so consumers
+ * and coding agents can match against them — never parse the message.
+ *
+ * @see packages/dot/docs/principles.md — principle 1.3 ("errors are part
+ * of the API") and principle 4 ("agent-discoverable everywhere").
+ */
+export const EVENT_SOURCING_PIP_ERROR_CODES = {
+  /** boot was called without a configured event-store URL. */
+  dbUrlNotConfigured: 'EVENT_SOURCING_PIP_E001',
+} as const;
+
+/**
+ * Options for the event-sourcing DOT adapter.
+ */
+export type EventSourcingDotOptions = {
+  /**
+   * PostgreSQL projection definitions registered inline on the event store.
+   * Accepts the three projection builder patterns documented on
+   * {@link PostgreSQLProjectionInput}.
+   */
+  readonly projections: readonly PostgreSQLProjectionInput[];
+  /**
+   * Command handlers wired into the in-memory message bus. Each handler's
+   * `getStreamName` callback maps an incoming command to its target stream.
+   *
+   * Defaults to `[]` — useful when an app only does projections / event
+   * appends without command-side dispatch.
+   */
+  readonly commandHandlers?: readonly CommandHandlerRegistration[];
+  /**
+   * Connection URL for the event store. When omitted, the pip reads
+   * `EVENT_STORE_URL`, `EVENTSTORE_URL`, or `EVENT_DB_URL` from
+   * `process.env`. If none are set, `boot` throws.
+   */
+  readonly dbUrl?: string;
+};
+
+/** Services published by the event-sourcing adapter. */
+export type EventSourcingServices = {
+  /** The Emmett event store handle, ready to load/append streams. */
+  readonly eventStore: EventStore;
+  /**
+   * The in-memory message bus. Already has the configured command handlers
+   * attached — call `messageBus.send(command)` to dispatch.
+   */
+  readonly messageBus: MessageBus;
+};
+
+/**
+ * Resolve the event-store connection URL from explicit options first, then
+ * from the recognised env vars in priority order. Returns `undefined` when
+ * none are set so the underlying factory can throw the canonical error.
+ */
+function resolveDbUrl(explicit: string | undefined): string | undefined {
+  if (explicit !== undefined && explicit !== '') return explicit;
+  for (const name of EVENT_STORE_URL_VARIANTS) {
+    const value = process.env[name];
+    if (value !== undefined && value !== '') return value;
+  }
+  return undefined;
+}
+
+/**
+ * Build a DOT pip that opens the event store, wires command handlers
+ * into an in-memory message bus, and publishes both as services. The
+ * kernel calls `dispose` in reverse declaration order to release the
+ * underlying PG pool.
+ */
+export function eventSourcing(options: EventSourcingDotOptions): Pip<EmptyShape, EventSourcingServices> {
+  const commandHandlers = options.commandHandlers ?? [];
+
+  // Captured at boot so dispose can call it without re-reading services
+  // (dispose is allowed to run even when services failed to publish).
+  let closeStore: (() => Promise<void>) | undefined;
+
+  return pip({
+    name: 'event-sourcing',
+    version: '0.1.0',
+    configure(ctx) {
+      ctx.registerService('eventStore', 'event-store');
+      ctx.registerService('messageBus', 'message-bus');
+      ctx.declareProvides('event-store', 'message-bus');
+    },
+    boot(): EventSourcingServices {
+      // Validate at the pip boundary so the DOT lifecycle gets a coded
+      // error. `eventSourcingFeatures.initEventSourcing` still throws raw
+      // `Error` for non-DOT consumers (its public contract is unchanged);
+      // the check here makes sure we never reach it without a URL.
+      const dbUrl = resolveDbUrl(options.dbUrl);
+      if (dbUrl === undefined) {
+        throw new DotPipError({
+          code: EVENT_SOURCING_PIP_ERROR_CODES.dbUrlNotConfigured,
+          message: '[event-sourcing] Event Store database URL is not configured.',
+          remediation: `Pass options.dbUrl to eventSourcing(...) or set one of ${EVENT_STORE_URL_VARIANTS.join(
+            ', ',
+          )} in the environment before booting the app.`,
+          docsUrl: 'https://arki.dev/dot/errors/event-sourcing-pip-e001',
+        });
+      }
+      const { eventStore, close } = eventSourcingFeatures.initEventSourcing(options.projections, dbUrl);
+      closeStore = close;
+      const messageBus = eventSourcingFeatures.initMessageBus(eventStore, [...commandHandlers]);
+      return { eventStore, messageBus };
+    },
+    async dispose() {
+      if (closeStore !== undefined) {
+        await closeStore();
+        closeStore = undefined;
+      }
+    },
+  });
+}

package/src/error.ts

@@ -0,0 +1 @@
+export { EmmettError, IllegalStateError } from '@event-driven-io/emmett';

package/src/event-sourcing-features.ts

@@ -0,0 +1,215 @@
+import type {
+  Event,
+  EventStore,
+  MessageBus,
+  MessageProcessor,
+  ProjectionDefinition,
+} from '@event-driven-io/emmett';
+import { getInMemoryMessageBus } from '@event-driven-io/emmett';
+
+import type { CommandHandler } from './builders/command-handler.js';
+import type { CommandHandlerRegistration } from './command.js';
+import { debugCommand, debugStore } from './debug.js';
+import type {
+  PostgresEventStore,
+  PostgreSQLProjectionHandlerContext,
+  PostgresReadEventMetadata,
+} from './store.js';
+import { getEventStore, projections } from './store.js';
+
+/**
+ * Structural interface for projection definitions accepted by
+ * {@link initEventSourcing}.
+ *
+ * Uses method syntax for `handle` to enable TypeScript's bivariant parameter
+ * checking, which allows heterogeneous projection arrays where each projection
+ * is parametrised on a different event type.
+ *
+ * Accepts projections produced by three different builder patterns:
+ * 1. Emmett's `postgreSQLProjection` / `PostgreSQLProjectionDefinition<E>`.
+ * 2. The `defineProjection` builder from this package.
+ * 3. The `@arki/db` builder `projection.named().on().handle()`.
+ */
+export type PostgreSQLProjectionInput = {
+  name?: string;
+  canHandle: string[];
+  handle(events: Event[], context: object): void;
+};
+
+/** Alternative names for the Event Store connection URL environment variable. */
+export const EVENT_STORE_URL_VARIANTS = ['EVENT_STORE_URL', 'EVENTSTORE_URL', 'EVENT_DB_URL'];
+
+/**
+ * Event sourcing wiring helpers.
+ *
+ * Bundles the three most common bootstrap operations into a single namespace:
+ *
+ * - {@link eventSourcingFeatures.initEventSourcing} — open the PostgreSQL
+ *   event store with a set of inline projections, returning a `close()`
+ *   function for graceful shutdown.
+ * - {@link eventSourcingFeatures.initMessageBus} — create an in-memory
+ *   message bus and register a list of command handler descriptors against it.
+ * - {@link eventSourcingFeatures.setupProcessManagers} — attach process
+ *   manager consumers to the event store, start them, and wire SIGTERM-driven
+ *   graceful shutdown.
+ *
+ * The helpers are intentionally framework-agnostic: any composition root
+ * (DI container, plugin, plain `bus.ts` factory function) can call them.
+ */
+export const eventSourcingFeatures = {
+  /**
+   * Initialises the PostgreSQL event store with the given inline projections.
+   *
+   * @param p Projections to register inline on the event store.
+   * @param dbUrl Connection string for the event store. When omitted, an
+   *   error is thrown that names the recognised environment variables.
+   * @returns The event store handle plus a `close()` function that releases
+   *   the underlying connection pool.
+   */
+  initEventSourcing(p: readonly PostgreSQLProjectionInput[], dbUrl?: string) {
+    if (!dbUrl) {
+      debugStore(
+        '[eventSourcingFeatures] Event Store URL not found. Required environment variables: %s',
+        EVENT_STORE_URL_VARIANTS.join(', '),
+      );
+      throw new Error(
+        `Event Store database URL is not defined. Please set one of the following environment variables: ${EVENT_STORE_URL_VARIANTS.join(
+          ', ',
+        )}`,
+      );
+    }
+    debugStore('[eventSourcingFeatures] Initializing Event Store with %d projection(s)', p.length);
+    const { eventStore, close } = getEventStore(dbUrl, {
+      projections: projections.inline(
+        p as ProjectionDefinition<Event, PostgresReadEventMetadata, PostgreSQLProjectionHandlerContext>[],
+      ),
+    });
+    debugStore('[eventSourcingFeatures] Event Store initialized successfully');
+    return { eventStore, close };
+  },
+
+  /**
+   * Creates an in-memory message bus and registers a list of command handlers.
+   *
+   * Each registration is bound to the event store so command handlers can
+   * load and append to streams. If the event store is missing, a warning is
+   * logged and an empty bus is returned.
+   *
+   * @param eventStore Event store used to load and append streams.
+   * @param commandHandlers Command handler descriptors to register.
+   * @returns A message bus with handlers attached.
+   */
+  initMessageBus(eventStore: EventStore | undefined, commandHandlers: CommandHandlerRegistration[]): MessageBus {
+    debugCommand(
+      '[eventSourcingFeatures] Initializing Message Bus with %d command handler(s)',
+      commandHandlers.length,
+    );
+    const messageBus = getInMemoryMessageBus();
+
+    if (!eventStore) {
+      if (commandHandlers.length > 0) {
+        debugCommand(
+          '[eventSourcingFeatures] Warning: %d command handler(s) configured but Event Store not initialized',
+          commandHandlers.length,
+        );
+        console.warn('Command handlers were configured, but the Event Store is not initialized. Commands may fail.');
+      } else {
+        debugCommand(
+          '[eventSourcingFeatures] No Event Store and no command handlers - returning empty Message Bus',
+        );
+      }
+      return messageBus;
+    }
+
+    if (commandHandlers.length > 0) {
+      const createCommandHandlerWrapper = <C extends { type: string }, State, StreamEvent extends Event>(
+        handler: CommandHandler<State, C, StreamEvent>,
+        getStreamNameFn: (cmd: C) => string,
+      ) => {
+        return async (command: C) => {
+          const streamName = getStreamNameFn(command);
+          debugCommand('[MessageBus] Executing command handler for %s on stream: %s', command.type, streamName);
+          try {
+            if (typeof handler === 'function') {
+              await handler(eventStore, streamName, command);
+              debugCommand('[MessageBus] Command handler for %s completed successfully', command.type);
+            } else {
+              debugCommand('[MessageBus] Invalid handler type for command: %s', command.type);
+              console.error(`Invalid handler type encountered for command: ${command.type}`);
+            }
+          } catch (error) {
+            debugCommand(
+              '[MessageBus] Error executing command handler for %s on stream %s: %s',
+              command.type,
+              streamName,
+              error instanceof Error ? error.message : String(error),
+            );
+            console.error(`Error executing command handler for ${command.type} on stream ${streamName}:`, error);
+            throw error;
+          }
+        };
+      };
+
+      for (const config of commandHandlers) {
+        debugCommand('[eventSourcingFeatures] Registering command handler for type: %s', config.commandType);
+        // Type erasure boundary: registrations are stored with C=never so
+        // arrays of differently-typed handlers compose. We cast back to
+        // callable types for the runtime dispatch wrapper.
+        type Cmd = { type: string };
+        const handler = config.handler as CommandHandler<unknown, Cmd, Event>;
+        const getStreamName = config.getStreamName as (cmd: Cmd) => string;
+        messageBus.handle(createCommandHandlerWrapper(handler, getStreamName), config.commandType);
+      }
+
+      debugCommand(
+        '[eventSourcingFeatures] Message Bus initialized with %d command handler(s)',
+        commandHandlers.length,
+      );
+    } else {
+      debugCommand('[eventSourcingFeatures] No command handlers to register');
+    }
+
+    return messageBus;
+  },
+
+  /**
+   * Attaches process managers as event store consumers, starts them, and
+   * wires SIGTERM-driven shutdown of the resulting consumers.
+   *
+   * @param eventStore Event store the process managers consume from.
+   * @param processManagers Process manager `MessageProcessor` instances to
+   *   register, typically produced by {@link createProcessManager},
+   *   {@link createStatefulProcessManager}, or
+   *   `createSimpleProcessManager`.
+   * @returns The started consumer handles. Useful for tests that need to
+   *   stop them explicitly.
+   */
+  async setupProcessManagers(eventStore: PostgresEventStore, processManagers: MessageProcessor[]) {
+    debugStore('[eventSourcingFeatures] Setting up %d process manager(s)', processManagers.length);
+    const processManagerConsumers = processManagers.map(pm => {
+      debugStore('[eventSourcingFeatures] Creating consumer for process manager: %s', pm.id);
+      return eventStore.consumer({
+        consumerId: pm.id,
+        processors: [pm],
+      });
+    });
+
+    debugStore(
+      '[eventSourcingFeatures] Starting %d process manager consumer(s)',
+      processManagerConsumers.length,
+    );
+    await Promise.all(processManagerConsumers.map(consumer => consumer.start()));
+    debugStore('[eventSourcingFeatures] All process manager consumers started successfully');
+
+    process.on('SIGTERM', async () => {
+      debugStore('[eventSourcingFeatures] SIGTERM received, stopping process managers');
+      await Promise.all(processManagerConsumers.map(consumer => consumer.stop()));
+      debugStore('[eventSourcingFeatures] All process managers stopped, closing consumers');
+      await Promise.all(processManagerConsumers.map(consumer => consumer.close()));
+      debugStore('[eventSourcingFeatures] All consumers closed, exiting');
+      process.exit(0);
+    });
+
+    return processManagerConsumers;
+  },
+};

package/src/event.ts

@@ -0,0 +1,46 @@
+import type { DefaultRecord } from './types.js';
+
+export type {
+  EventsPublisher,
+  EventStore,
+  ReadEvent,
+  ReadEventMetadataWithGlobalPosition,
+} from '@event-driven-io/emmett';
+
+export type Event<
+  EventType extends string = string,
+  EventData extends DefaultRecord = DefaultRecord,
+  EventMetaData extends DefaultRecord | undefined = undefined,
+> = Readonly<{
+  type: EventType;
+  data: EventData;
+  metadata?: EventMetaData;
+  kind?: 'Event';
+}>;
+
+export type AnyEvent = Event<any, any, any>;
+export type EventTypeOf<T extends Event> = T['type'];
+export type EventDataOf<T extends Event> = T['data'];
+export type EventMetaDataOf<T extends Event> = T extends {
+  metadata: infer M;
+}
+  ? M
+  : undefined;
+export type CreateEventType<
+  EventType extends string,
+  EventData extends DefaultRecord,
+  EventMetaData extends DefaultRecord | undefined = undefined,
+> = Readonly<
+  EventMetaData extends undefined
+    ? {
+        type: EventType;
+        data: EventData;
+      }
+    : {
+        type: EventType;
+        data: EventData;
+        metadata: EventMetaData;
+      }
+> & {
+  readonly kind?: 'Event';
+};

package/src/index.ts

@@ -0,0 +1,10 @@
+export * from './command.js';
+export * from './decide.js';
+export * from './event.js';
+export { createSimpleProcessManager } from './simple-process-manager.js';
+export {
+  EVENT_STORE_URL_VARIANTS,
+  eventSourcingFeatures,
+  type PostgreSQLProjectionInput,
+} from './event-sourcing-features.js';
+export type { DefaultRecord } from './types.js';