@pattern-stack/codegen 0.4.1 → 0.4.3

package/runtime/subsystems/events/event-bus.memory-backend.ts

@@ -0,0 +1,142 @@
+/**
+ * MemoryEventBus — in-memory backend for the event bus.
+ *
+ * Dispatches events synchronously to registered subscribers. The `tx`
+ * parameter is ignored — all events are dispatched immediately.
+ *
+ * Use this backend in tests to assert event publication without a database.
+ * Swap via EventsModule.forRoot({ backend: 'memory' }).
+ *
+ * Pool awareness (EVT-5):
+ * - Mirrors the `DrizzleEventBus` per-process restriction (EVT-4). When
+ *   `opts.pools` is set, `publish`/`publishMany` still push the event into
+ *   `publishedEvents` (so test code can assert the full set of emitted
+ *   events regardless of pool filter), but handlers are NOT invoked for
+ *   events whose `metadata.pool` is outside the configured pools.
+ * - `publishedEventsForPool(pool)` and `publishedEventsForDirection(dir)`
+ *   helpers are provided for targeted assertions.
+ * - Shares the `EventsModuleOptions` shape (same token as Drizzle) rather
+ *   than introducing a memory-only options type — the surface is the same
+ *   and keeping them unified avoids drift between backends.
+ */
+import { Inject, Injectable, Logger, Optional } from '@nestjs/common';
+import type { DomainEvent, IEventBus } from './event-bus.protocol';
+import { EVENTS_MODULE_OPTIONS } from './events.tokens';
+import type { EventsModuleOptions } from './events.module';
+
+@Injectable()
+export class MemoryEventBus implements IEventBus {
+  private readonly logger = new Logger(MemoryEventBus.name);
+
+  /** All events published since construction (or last clear). */
+  readonly publishedEvents: DomainEvent[] = [];
+
+  private readonly handlers = new Map<string, Set<(event: DomainEvent) => Promise<void>>>();
+  private readonly opts: EventsModuleOptions;
+
+  constructor(
+    @Optional() @Inject(EVENTS_MODULE_OPTIONS) opts?: EventsModuleOptions,
+  ) {
+    // Default so direct construction (e.g. `new MemoryEventBus()` from a
+    // unit test outside NestJS DI) keeps working without an explicit
+    // options object.
+    this.opts = opts ?? { backend: 'memory' };
+  }
+
+  async publish(event: DomainEvent): Promise<void> {
+    // Always record the event — even if this process is configured with a
+    // pool filter that excludes it. Test code relies on `publishedEvents`
+    // being a complete log of what was published, not a filtered view.
+    this.publishedEvents.push(event);
+
+    if (this.shouldDispatch(event)) {
+      await this.dispatch(event);
+    }
+  }
+
+  async publishMany(events: DomainEvent[]): Promise<void> {
+    for (const event of events) {
+      await this.publish(event);
+    }
+  }
+
+  async findById(eventId: string): Promise<DomainEvent | null> {
+    return this.publishedEvents.find((e) => e.id === eventId) ?? null;
+  }
+
+  subscribe<T extends DomainEvent = DomainEvent>(
+    eventType: string,
+    handler: (event: T) => Promise<void>,
+  ): () => void {
+    if (!this.handlers.has(eventType)) {
+      this.handlers.set(eventType, new Set());
+    }
+    // Cast is safe — callers pass a typed handler; we store as the base type
+    const set = this.handlers.get(eventType)!;
+    const h = handler as (event: DomainEvent) => Promise<void>;
+    set.add(h);
+
+    return () => {
+      set.delete(h);
+    };
+  }
+
+  /** Remove all published events and subscriptions. Useful in beforeEach. */
+  clear(): void {
+    this.publishedEvents.length = 0;
+    this.handlers.clear();
+  }
+
+  /** Filter published events by `metadata.pool`. */
+  publishedEventsForPool(pool: string): DomainEvent[] {
+    return this.publishedEvents.filter((e) => e.metadata?.['pool'] === pool);
+  }
+
+  /** Filter published events by `metadata.direction`. */
+  publishedEventsForDirection(direction: string): DomainEvent[] {
+    return this.publishedEvents.filter((e) => e.metadata?.['direction'] === direction);
+  }
+
+  /**
+   * Decide whether `event` should be dispatched to handlers given the
+   * current pool filter.
+   *
+   * Semantics (mirroring `DrizzleEventBus.processBatch`):
+   * - `opts.pools` undefined  → dispatch everything (no filter).
+   * - `opts.pools` empty array → treated as "no filter" to match the
+   *   Drizzle backend, where `pools && pools.length > 0` is the gate on
+   *   the `inArray` WHERE clause. Empty arrays dispatch everything.
+   * - `opts.pools` non-empty  → dispatch only when `event.metadata.pool`
+   *   is in the list. Events without `metadata.pool` do NOT match — they
+   *   are out of all configured pools by definition.
+   */
+  private shouldDispatch(event: DomainEvent): boolean {
+    const pools = this.opts.pools;
+    if (!pools || pools.length === 0) return true;
+    const eventPool = event.metadata?.['pool'];
+    return typeof eventPool === 'string' && pools.includes(eventPool);
+  }
+
+  private async dispatch(event: DomainEvent): Promise<void> {
+    const set = this.handlers.get(event.type);
+    if (!set) return;
+
+    let firstError: unknown;
+    for (const handler of set) {
+      try {
+        await handler(event);
+      } catch (err) {
+        this.logger.error(
+          `Handler error for event type "${event.type}" (id: ${event.id}): ${err}`,
+        );
+        if (firstError === undefined) {
+          firstError = err;
+        }
+      }
+    }
+
+    if (firstError !== undefined) {
+      throw firstError;
+    }
+  }
+}

package/runtime/subsystems/events/event-bus.protocol.ts

@@ -0,0 +1,86 @@
+/**
+ * Events subsystem — protocol (port)
+ *
+ * IEventBus is the hexagonal port. Use cases inject this interface via
+ * EVENT_BUS token. They never depend on a specific backend implementation.
+ *
+ * The DrizzleTransaction type mirrors what the Drizzle client exposes
+ * so callers can pass a transaction for the outbox pattern.
+ */
+import type { DrizzleClient } from '../../types/drizzle';
+
+// Derive the transaction type from the DrizzleClient so it stays in sync
+// without introducing an additional import alias.
+export type DrizzleTransaction = Parameters<
+  Parameters<DrizzleClient['transaction']>[0]
+>[0];
+
+// ============================================================================
+// Domain event shape
+// ============================================================================
+
+export interface DomainEvent {
+  /** UUID — used for deduplication and idempotency. */
+  readonly id: string;
+  /** Event type discriminator, e.g. 'contact_created'. */
+  readonly type: string;
+  /** ID of the aggregate that produced this event. */
+  readonly aggregateId: string;
+  /** Aggregate type name, e.g. 'contact'. */
+  readonly aggregateType: string;
+  /** Event-specific payload. */
+  readonly payload: Record<string, unknown>;
+  /** Wall-clock time the event occurred. */
+  readonly occurredAt: Date;
+  /** Optional routing / audit metadata. */
+  readonly metadata?: Record<string, unknown>;
+}
+
+// ============================================================================
+// IEventBus
+// ============================================================================
+
+export interface IEventBus {
+  /**
+   * Publish a single domain event.
+   *
+   * Pass `tx` to include the event in an ongoing Drizzle transaction
+   * (transactional outbox pattern). If the transaction rolls back, the
+   * event is never persisted.
+   */
+  publish(event: DomainEvent, tx?: DrizzleTransaction): Promise<void>;
+
+  /**
+   * Publish multiple domain events atomically.
+   * Same transactional semantics as `publish`.
+   */
+  publishMany(events: DomainEvent[], tx?: DrizzleTransaction): Promise<void>;
+
+  /**
+   * Subscribe to events of the given type.
+   * Returns an unsubscribe function — call it to remove the handler.
+   */
+  subscribe<T extends DomainEvent = DomainEvent>(
+    eventType: string,
+    handler: (event: T) => Promise<void>,
+  ): () => void;
+
+  /**
+   * Lookup a single event by its id. Returns `null` when no event matches.
+   *
+   * Added in BRIDGE-5 (ADR-023 Phase 2). The bridge `BridgeDeliveryHandler`
+   * uses this to re-fetch the authoritative `domain_events` row at claim
+   * time so `triggers[].when` and `triggers[].map` callbacks see the
+   * committed payload, not a copy that may have drifted between drain and
+   * handler execution. Other consumers may use it for replay tooling and
+   * audit dashboards.
+   *
+   * Backends:
+   *   - `MemoryEventBus` — searches its in-memory `publishedEvents` log.
+   *   - `DrizzleEventBus` — `SELECT … FROM domain_events WHERE id = ? LIMIT 1`.
+   *   - `RedisEventBus` — Redis Pub/Sub does not retain history; returns
+   *     `null` (and logs a one-time warning at first call). Bridge usage
+   *     of Redis backend is unsupported.
+   */
+  findById(eventId: string): Promise<DomainEvent | null>;
+}

package/runtime/subsystems/events/event-bus.redis-backend.ts

@@ -0,0 +1,304 @@
+/**
+ * RedisEventBus — Redis Pub/Sub backend for the event bus.
+ *
+ * Publishes events to Redis channels and dispatches incoming messages to
+ * registered in-process subscribers. Events are serialized as JSON strings.
+ *
+ * Channel naming:
+ *   - Per-type channel:  events:{event.type}   (e.g. events:contact_created)
+ *   - Catch-all channel: events:*
+ *
+ * Transactional semantics:
+ *   The `tx` parameter (Drizzle transaction) is accepted to satisfy the
+ *   IEventBus interface but has no effect — Redis Pub/Sub is not transactional.
+ *   Events published with a `tx` argument are dispatched immediately without
+ *   waiting for the surrounding transaction to commit. If you need
+ *   at-least-once delivery tied to a database transaction, use DrizzleEventBus.
+ *
+ * Connection model:
+ *   ioredis requires a dedicated connection for subscribers (a client in
+ *   subscribe mode cannot issue regular commands). This backend creates two
+ *   clients: one for publishing (`publisher`) and one for subscribing
+ *   (`subscriber`). Both are connected on module init and disconnected on
+ *   module destroy.
+ *
+ * Usage:
+ *   EventsModule.forRoot({ backend: 'redis', redisUrl: 'redis://localhost:6379' })
+ *
+ * Requires `ioredis` — install it separately if you use this backend:
+ *   npm install ioredis   /   bun add ioredis
+ */
+import { Injectable, OnModuleInit, OnModuleDestroy, Inject, Logger } from '@nestjs/common';
+import type { DomainEvent, DrizzleTransaction, IEventBus } from './event-bus.protocol';
+import { REDIS_URL } from './events.tokens';
+
+/** Redis channel prefix for all domain events. */
+const CHANNEL_PREFIX = 'events:';
+/** Catch-all channel that receives every published event. */
+const WILDCARD_CHANNEL = 'events:*';
+
+// ioredis is an optional peer dependency; import lazily so consumers who do
+// not use this backend do not need it on their classpath.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type RedisClient = any;
+
+async function createRedisClient(url: string): Promise<RedisClient> {
+  let Redis: { new (url: string): RedisClient };
+  try {
+    const mod = await import('ioredis');
+    Redis = mod.default ?? mod;
+  } catch {
+    throw new Error(
+      'RedisEventBus requires the "ioredis" package. Install it with: npm install ioredis',
+    );
+  }
+  return new Redis(url);
+}
+
+@Injectable()
+export class RedisEventBus implements IEventBus, OnModuleInit, OnModuleDestroy {
+  private readonly logger = new Logger(RedisEventBus.name);
+
+  private publisher: RedisClient | null = null;
+  private subscriber: RedisClient | null = null;
+  private connected = false;
+
+  /**
+   * In-process subscriber registry. Handlers registered here are called when
+   * a message arrives on the subscriber client — keeping fan-out within the
+   * same process without an extra round-trip through Redis.
+   */
+  private readonly handlers = new Map<string, Set<(event: DomainEvent) => Promise<void>>>();
+
+  /**
+   * Track which event types have active Redis subscriptions.
+   * Used to avoid subscribing multiple times to the same type channel.
+   */
+  private readonly subscribedTypes = new Set<string>();
+
+  constructor(@Inject(REDIS_URL) private readonly redisUrl: string) {}
+
+  // ============================================================================
+  // Lifecycle
+  // ============================================================================
+
+  async onModuleInit(): Promise<void> {
+    this.publisher = await createRedisClient(this.redisUrl);
+    this.subscriber = await createRedisClient(this.redisUrl);
+
+    // Surface connection errors without crashing the process.
+    this.publisher.on('error', (err: Error) =>
+      this.logger.error(`Redis publisher error: ${err.message}`, err.stack),
+    );
+    this.subscriber.on('error', (err: Error) =>
+      this.logger.error(`Redis subscriber error: ${err.message}`, err.stack),
+    );
+
+    // Set up message listener for per-type subscriptions.
+    // Subscriptions are created lazily when the first handler is registered for a type.
+    this.subscriber.on('message', (channel: string, message: string) => {
+      void this.handleMessage(channel, message);
+    });
+
+    this.connected = true;
+    this.logger.log(`RedisEventBus connected to ${this.redisUrl}`);
+  }
+
+  async onModuleDestroy(): Promise<void> {
+    this.connected = false;
+
+    if (this.subscriber) {
+      // Unsubscribe from all channels and disconnect the subscriber.
+      // unsubscribe() with no args unsubscribes from all channels.
+      await this.subscriber.unsubscribe();
+      this.subscriber.disconnect();
+      this.subscriber = null;
+    }
+
+    if (this.publisher) {
+      this.publisher.disconnect();
+      this.publisher = null;
+    }
+
+    this.subscribedTypes.clear();
+    this.logger.log('RedisEventBus disconnected');
+  }
+
+  // ============================================================================
+  // IEventBus
+  // ============================================================================
+
+  /**
+   * Publish a single event.
+   *
+   * `tx` is accepted but ignored — see module-level JSDoc for details.
+   */
+  async publish(event: DomainEvent, tx?: DrizzleTransaction): Promise<void> {
+    void tx; // intentionally unused — Redis Pub/Sub is not transactional
+    this.assertConnected();
+
+    const payload = this.serialize(event);
+    const channel = `${CHANNEL_PREFIX}${event.type}`;
+
+    await this.publisher!.publish(channel, payload);
+  }
+
+  /**
+   * Publish multiple events using a pipeline so all PUBLISH commands are sent
+   * in a single round-trip.
+   *
+   * `tx` is accepted but ignored — see module-level JSDoc for details.
+   */
+  async publishMany(events: DomainEvent[], tx?: DrizzleTransaction): Promise<void> {
+    void tx; // intentionally unused — Redis Pub/Sub is not transactional
+    if (events.length === 0) return;
+    this.assertConnected();
+
+    const pipeline = this.publisher!.pipeline();
+    for (const event of events) {
+      const payload = this.serialize(event);
+      const channel = `${CHANNEL_PREFIX}${event.type}`;
+      pipeline.publish(channel, payload);
+    }
+    await pipeline.exec();
+  }
+
+  /**
+   * Register a handler for a specific event type.
+   * Returns an unsubscribe function — call it to remove the handler.
+   *
+   * On first handler for a type, subscribes to the per-type Redis channel.
+   * On removal of the last handler for a type, unsubscribes from the channel.
+   */
+  /**
+   * Lookup by id is unsupported on the Redis Pub/Sub backend — Pub/Sub
+   * does not retain history. Always returns `null`. Logs a warning the
+   * first time it's called so a misconfiguration surfaces visibly. Using
+   * the bridge with the Redis backend is unsupported (the bridge requires
+   * a durable event store).
+   */
+  private warnedFindById = false;
+  async findById(_eventId: string): Promise<DomainEvent | null> {
+    if (!this.warnedFindById) {
+      this.warnedFindById = true;
+      this.logger.warn(
+        'RedisEventBus.findById is unsupported (Pub/Sub has no history). ' +
+          'The bridge subsystem requires a durable event store; switch to ' +
+          'DrizzleEventBus if you need bridge fanout.',
+      );
+    }
+    return null;
+  }
+
+  subscribe<T extends DomainEvent = DomainEvent>(
+    eventType: string,
+    handler: (event: T) => Promise<void>,
+  ): () => void {
+    if (!this.handlers.has(eventType)) {
+      this.handlers.set(eventType, new Set());
+      // First handler for this type — subscribe to the per-type channel in Redis.
+      void this.subscribeToType(eventType);
+    }
+    const set = this.handlers.get(eventType)!;
+    const h = handler as (event: DomainEvent) => Promise<void>;
+    set.add(h);
+
+    return () => {
+      set.delete(h);
+      // If no more handlers for this type, unsubscribe from the Redis channel.
+      if (set.size === 0) {
+        this.handlers.delete(eventType);
+        void this.unsubscribeFromType(eventType);
+      }
+    };
+  }
+
+  // ============================================================================
+  // Internal helpers
+  // ============================================================================
+
+  private assertConnected(): void {
+    if (!this.connected || !this.publisher) {
+      throw new Error(
+        'RedisEventBus is not connected. Ensure the module has been initialised before publishing.',
+      );
+    }
+  }
+
+  private serialize(event: DomainEvent): string {
+    return JSON.stringify({
+      ...event,
+      occurredAt: event.occurredAt.toISOString(),
+    });
+  }
+
+  private deserialize(raw: string): DomainEvent {
+    const parsed = JSON.parse(raw) as DomainEvent & { occurredAt: string };
+    return {
+      ...parsed,
+      occurredAt: new Date(parsed.occurredAt),
+    };
+  }
+
+  private async handleMessage(channel: string, message: string): Promise<void> {
+    let event: DomainEvent;
+    try {
+      event = this.deserialize(message);
+    } catch (err) {
+      this.logger.warn(`Failed to deserialize event on channel "${channel}": ${err}`);
+      return;
+    }
+
+    await this.dispatch(event);
+  }
+
+  private async dispatch(event: DomainEvent): Promise<void> {
+    const set = this.handlers.get(event.type);
+    if (!set) return;
+    for (const handler of set) {
+      try {
+        await handler(event);
+      } catch (err) {
+        this.logger.error(
+          `Handler error for event type "${event.type}" (id: ${event.id}): ${err}`,
+        );
+      }
+    }
+  }
+
+  /**
+   * Subscribe to a per-type Redis channel.
+   * Called lazily when the first handler is registered for a type.
+   */
+  private async subscribeToType(eventType: string): Promise<void> {
+    if (this.subscribedTypes.has(eventType)) {
+      return; // Already subscribed to this type.
+    }
+
+    const channel = `${CHANNEL_PREFIX}${eventType}`;
+    try {
+      await this.subscriber!.subscribe(channel);
+      this.subscribedTypes.add(eventType);
+    } catch (err) {
+      this.logger.error(`Failed to subscribe to channel "${channel}": ${err}`);
+    }
+  }
+
+  /**
+   * Unsubscribe from a per-type Redis channel.
+   * Called when the last handler for a type is removed.
+   */
+  private async unsubscribeFromType(eventType: string): Promise<void> {
+    if (!this.subscribedTypes.has(eventType)) {
+      return; // Not subscribed to this type.
+    }
+
+    const channel = `${CHANNEL_PREFIX}${eventType}`;
+    try {
+      await this.subscriber!.unsubscribe(channel);
+      this.subscribedTypes.delete(eventType);
+    } catch (err) {
+      this.logger.error(`Failed to unsubscribe from channel "${channel}": ${err}`);
+    }
+  }
+}

package/runtime/subsystems/events/events-errors.ts

@@ -0,0 +1,30 @@
+/**
+ * Typed errors for the events subsystem (ADR-024, EVT-6).
+ *
+ * All thrown from the publish path of `TypedEventBus`. They exist as
+ * classes so consumers can `instanceof` them in catch blocks and
+ * exception filters can map them to HTTP codes.
+ */
+
+/**
+ * Thrown by `TypedEventBus.publish()` when the EventsModule is configured
+ * with `multiTenant: true` and the caller did not supply
+ * `opts.metadata.tenantId`. Multi-tenant mode requires every outbox row to
+ * be attributable to a tenant — the `domain_events.tenant_id` column is
+ * populated from this value and the drain loop uses it for future
+ * tenant-scoped filtering (deferred — see ADR-024 §Multi-tenancy).
+ *
+ * Disable multi-tenancy at the module level (`multiTenant: false`, the
+ * default) to opt out of the requirement entirely.
+ */
+export class MissingTenantIdError extends Error {
+  override readonly name = 'MissingTenantIdError';
+  constructor(public readonly eventType: string) {
+    super(
+      `Missing tenantId for event '${eventType}'. EventsModule is configured ` +
+        `with multiTenant: true — every publish must include ` +
+        `opts.metadata.tenantId. Either pass the tenantId or disable ` +
+        `multi-tenancy on the module.`,
+    );
+  }
+}