@pattern-stack/codegen 0.4.0 → 0.4.2

package/runtime/base-classes/base-repository.ts

@@ -0,0 +1,289 @@
+/**
+ * BaseRepository<TEntity>
+ *
+ * Abstract base class providing standard CRUD operations via Drizzle ORM.
+ * Every generated repository extends this class.
+ *
+ * Family-specific bases (CrmEntityRepository, etc.) extend this in v0.1
+ * without any changes to BaseRepository.
+ *
+ * NOT @Injectable — concrete repositories are @Injectable and inject DRIZZLE.
+ */
+import { eq, inArray, isNull, sql } from 'drizzle-orm';
+import type { PgTableWithColumns, PgColumn } from 'drizzle-orm/pg-core';
+import type { SQL } from 'drizzle-orm';
+import type { DrizzleClient, DrizzleTx } from '../types/drizzle';
+
+// ============================================================================
+// Interfaces
+// ============================================================================
+
+/**
+ * Behavior flags for the repository. Controls automatic timestamp injection
+ * and soft-delete filtering.
+ */
+export interface BehaviorConfig {
+  timestamps: boolean;
+  softDelete: boolean;
+  userTracking: boolean;
+}
+
+/**
+ * Options for the list() method.
+ */
+export interface ListOptions {
+  where?: SQL;
+  limit?: number;
+  offset?: number;
+  orderBy?: PgColumn | SQL;
+}
+
+// ============================================================================
+// BaseRepository
+// ============================================================================
+
+export abstract class BaseRepository<TEntity> {
+  /**
+   * The Drizzle table schema for this entity.
+   * Concrete repositories declare this as a class property.
+   */
+  protected abstract readonly table: PgTableWithColumns<any>; // eslint-disable-line @typescript-eslint/no-explicit-any
+
+  /**
+   * Behavior flags controlling automatic behavior injection.
+   * Override in concrete repositories to enable behaviors.
+   */
+  protected readonly behaviors: BehaviorConfig = {
+    timestamps: false,
+    softDelete: false,
+    userTracking: false,
+  };
+
+  protected readonly db: DrizzleClient;
+
+  constructor(db: DrizzleClient) {
+    this.db = db;
+  }
+
+  /**
+   * Pick the runner for a write: the caller-supplied transaction handle
+   * if present, otherwise the repository's own client. Keeps the `tx`
+   * parameter purely additive — callers without a transaction call as
+   * before. Used by the write methods below + consumer overrides (e.g.
+   * the generated `upsertCurrentValues` on EAV value tables).
+   */
+  protected runner(tx?: DrizzleTx): DrizzleClient {
+    return tx ?? this.db;
+  }
+
+  // ============================================================================
+  // Read Operations
+  // ============================================================================
+
+  /**
+   * Find a single entity by its primary key.
+   * Returns null if not found (or soft-deleted when softDelete=true).
+   */
+  async findById(id: string): Promise<TEntity | null> {
+    const rows = await this.baseQuery()
+      .where(eq(this.table['id'], id))
+      .limit(1);
+    return (rows[0] as TEntity) ?? null;
+  }
+
+  /**
+   * Find multiple entities by their primary keys.
+   * Returns empty array immediately for empty input (avoids DB errors).
+   */
+  async findByIds(ids: string[]): Promise<TEntity[]> {
+    if (ids.length === 0) return [];
+    const rows = await this.baseQuery().where(inArray(this.table['id'], ids));
+    return rows as TEntity[];
+  }
+
+  /**
+   * List entities with optional filtering, pagination, and ordering.
+   */
+  async list(options?: ListOptions): Promise<TEntity[]> {
+    let query = this.baseQuery();
+
+    if (options?.where) {
+      query = query.where(options.where) as typeof query;
+    }
+    if (options?.orderBy) {
+      query = query.orderBy(options.orderBy as SQL) as typeof query;
+    }
+    if (options?.limit !== undefined) {
+      query = query.limit(options.limit) as typeof query;
+    }
+    if (options?.offset !== undefined) {
+      query = query.offset(options.offset) as typeof query;
+    }
+
+    const rows = await query;
+    return rows as TEntity[];
+  }
+
+  /**
+   * Count entities matching an optional WHERE clause.
+   * Soft-deleted rows are always excluded when softDelete=true.
+   */
+  async count(where?: SQL): Promise<number> {
+    let query = this.db
+      .select({ count: sql<number>`cast(count(*) as integer)` })
+      .from(this.table);
+
+    const conditions: SQL[] = [];
+    if (this.behaviors.softDelete) {
+      conditions.push(isNull(this.table['deletedAt']));
+    }
+    if (where) {
+      conditions.push(where);
+    }
+
+    if (conditions.length === 1) {
+      query = query.where(conditions[0]) as typeof query;
+    } else if (conditions.length > 1) {
+      // Combine with AND by building the condition inline
+      const { and } = await import('drizzle-orm');
+      query = query.where(and(...conditions)) as typeof query;
+    }
+
+    const rows = await query;
+    return rows[0]?.count ?? 0;
+  }
+
+  /**
+   * Check whether an entity with the given id exists.
+   */
+  async exists(id: string): Promise<boolean> {
+    const result = await this.findById(id);
+    return result !== null;
+  }
+
+  // ============================================================================
+  // Write Operations
+  // ============================================================================
+
+  /**
+   * Insert a new entity. Timestamps are auto-injected when timestamps=true.
+   */
+  async create(input: Partial<TEntity>, tx?: DrizzleTx): Promise<TEntity> {
+    const data = this.withTimestamps(input as Record<string, unknown>, 'create');
+    const rows = await this.runner(tx)
+      .insert(this.table)
+      .values(data as any) // eslint-disable-line @typescript-eslint/no-explicit-any
+      .returning();
+    return rows[0] as TEntity;
+  }
+
+  /**
+   * Update an existing entity by id. updatedAt is auto-injected when timestamps=true.
+   * Returns the updated entity.
+   */
+  async update(id: string, input: Partial<TEntity>, tx?: DrizzleTx): Promise<TEntity> {
+    const data = this.withTimestamps(input as Record<string, unknown>, 'update');
+    const rows = await this.runner(tx)
+      .update(this.table)
+      .set(data as any) // eslint-disable-line @typescript-eslint/no-explicit-any
+      .where(eq(this.table['id'], id))
+      .returning();
+    return rows[0] as TEntity;
+  }
+
+  /**
+   * Delete an entity by id.
+   * - softDelete=true: sets deletedAt to current timestamp
+   * - softDelete=false: hard-deletes the row
+   */
+  async delete(id: string, tx?: DrizzleTx): Promise<void> {
+    const runner = this.runner(tx);
+    if (this.behaviors.softDelete) {
+      await runner
+        .update(this.table)
+        .set({ deletedAt: new Date() } as any) // eslint-disable-line @typescript-eslint/no-explicit-any
+        .where(eq(this.table['id'], id));
+    } else {
+      await runner
+        .delete(this.table)
+        .where(eq(this.table['id'], id));
+    }
+  }
+
+  /**
+   * Insert or update multiple entities.
+   * Default naive implementation — family repositories override with
+   * proper conflict-target upsert (e.g., CrmEntityRepository).
+   */
+  async upsertMany(inputs: Array<Partial<TEntity>>, tx?: DrizzleTx): Promise<TEntity[]> {
+    return Promise.all(inputs.map((input) => this.create(input, tx)));
+  }
+
+  // ============================================================================
+  // Protected Helpers
+  // ============================================================================
+
+  /**
+   * Base SELECT query that automatically excludes soft-deleted rows
+   * when softDelete behavior is enabled.
+   */
+  protected baseQuery() {
+    const query = this.db.select().from(this.table).$dynamic();
+    if (this.behaviors.softDelete) {
+      return query.where(isNull(this.table['deletedAt']));
+    }
+    return query;
+  }
+
+  /**
+   * Merge timestamp fields into an input object.
+   * - mode='create': adds createdAt and updatedAt
+   * - mode='update': adds updatedAt only
+   *
+   * No-op when timestamps behavior is disabled.
+   */
+  protected withTimestamps(
+    input: Record<string, unknown>,
+    mode: 'create' | 'update',
+  ): Record<string, unknown> {
+    if (!this.behaviors.timestamps) return input;
+    const now = new Date();
+    if (mode === 'create') {
+      return { ...input, createdAt: now, updatedAt: now };
+    }
+    return { ...input, updatedAt: now };
+  }
+
+  /**
+   * Build a WHERE clause fragment that restricts results to rows whose
+   * parent (identified by a belongs_to FK) is not soft-deleted.
+   *
+   * Use this in custom repository methods when you need "rows reachable
+   * from an active parent". The default findAll / findById behavior is
+   * NOT changed by this helper — opt in explicitly where needed.
+   *
+   * ADR-021 — Soft-delete cascade: Option A (filter at query time).
+   * `on_delete` FK rules do not fire for soft-deletes; use this helper
+   * instead of expecting cascade semantics on the DB level.
+   *
+   * Example:
+   *   async listActiveMessages(): Promise<Message[]> {
+   *     return this.list({
+   *       where: this.activeParentFilter(conversations, this.table['conversationId']),
+   *     });
+   *   }
+   *
+   * @param parentTable  The Drizzle table object for the parent entity.
+   * @param parentFkColumn  The FK column on this (child) table that references parent.id.
+   */
+  protected activeParentFilter(
+    parentTable: PgTableWithColumns<any>, // eslint-disable-line @typescript-eslint/no-explicit-any
+    parentFkColumn: PgColumn,
+  ): SQL {
+    return sql`EXISTS (
+      SELECT 1 FROM ${parentTable} p
+      WHERE p.id = ${parentFkColumn}
+        AND p.deleted_at IS NULL
+    )`;
+  }
+}

package/runtime/base-classes/base-service.ts

@@ -0,0 +1,183 @@
+/**
+ * BaseService<TRepo, TEntity>
+ *
+ * Abstract base class providing 8 CRUD pass-through methods delegating to
+ * an injected repository. Every generated service extends this class.
+ *
+ * Lifecycle event emission (LIFECYCLE + CHANGE categories) is built into
+ * create/update/delete — matching pattern-stack's BaseService. Events are
+ * fire-and-forget: emission never fails the CRUD operation. If no IEventBus
+ * is injected (eventBus is undefined), emission is silently skipped.
+ *
+ * Generated services set `entityName` and optionally inject `eventBus` via
+ * NestJS property injection (@Inject(EVENT_BUS) @Optional()).
+ *
+ * Note: @Injectable() is applied on concrete services (not here) so that
+ * NestJS DI metadata is emitted at the concrete class level. This matches
+ * the pattern established by BaseRepository.
+ */
+
+import type { IEventBus } from '../subsystems/events/event-bus.protocol';
+import {
+  entitySnapshot,
+  diffSnapshots,
+  buildLifecycleEvent,
+  buildChangeEvents,
+  emitSafely,
+} from './lifecycle-events';
+
+// ============================================================================
+// IBaseRepository interface
+// ============================================================================
+
+/**
+ * Structural interface that BaseRepository satisfies.
+ * Use this as the TRepo constraint so BaseService is not coupled to the
+ * concrete Drizzle-backed BaseRepository.
+ */
+export interface IBaseRepository<TEntity> {
+  findById(id: string): Promise<TEntity | null>;
+  findByIds(ids: string[]): Promise<TEntity[]>;
+  list(options?: unknown): Promise<TEntity[]>;
+  count(where?: unknown): Promise<number>;
+  exists(id: string): Promise<boolean>;
+  create(input: Partial<TEntity>, tx?: unknown): Promise<TEntity>;
+  update(id: string, input: Partial<TEntity>, tx?: unknown): Promise<TEntity>;
+  delete(id: string, tx?: unknown): Promise<void>;
+}
+
+// ============================================================================
+// BaseService
+// ============================================================================
+
+export abstract class BaseService<TRepo extends IBaseRepository<TEntity>, TEntity> {
+  /**
+   * Entity name for event types (e.g., 'account' → 'account.created').
+   * Set by generated services. If empty, lifecycle events are skipped.
+   */
+  protected entityName?: string;
+
+  /**
+   * Event bus for lifecycle/change event emission.
+   * Injected via @Inject(EVENT_BUS) @Optional() on generated services.
+   * If undefined (no events subsystem installed), emission is silently skipped.
+   */
+  protected eventBus?: IEventBus;
+
+  /**
+   * Whether to emit lifecycle events. Default: true.
+   * Override to false in entity YAML via behaviors or in the service class.
+   */
+  protected emitLifecycleEvents = true;
+
+  constructor(protected readonly repository: TRepo) {}
+
+  /**
+   * Find a single entity by its primary key.
+   * Returns null if not found.
+   */
+  findById(id: string): Promise<TEntity | null> {
+    return this.repository.findById(id);
+  }
+
+  /**
+   * Find multiple entities by their primary keys.
+   */
+  findByIds(ids: string[]): Promise<TEntity[]> {
+    return this.repository.findByIds(ids);
+  }
+
+  /**
+   * List entities with optional filtering/pagination options.
+   */
+  list(options?: unknown): Promise<TEntity[]> {
+    return this.repository.list(options);
+  }
+
+  /**
+   * Count entities matching an optional filter.
+   */
+  count(where?: unknown): Promise<number> {
+    return this.repository.count(where);
+  }
+
+  /**
+   * Check whether an entity with the given id exists.
+   */
+  exists(id: string): Promise<boolean> {
+    return this.repository.exists(id);
+  }
+
+  /**
+   * Insert a new entity.
+   * Emits a LIFECYCLE 'created' event with entity snapshot.
+   */
+  async create(input: Partial<TEntity>, tx?: unknown): Promise<TEntity> {
+    const result = await this.repository.create(input, tx);
+
+    if (this._shouldEmit()) {
+      const snap = entitySnapshot(result as Record<string, unknown>);
+      const id = (result as Record<string, unknown>).id as string;
+      const event = buildLifecycleEvent(this.entityName!, 'created', id, snap);
+      void emitSafely(this.eventBus, [event]);
+    }
+
+    return result;
+  }
+
+  /**
+   * Update an existing entity by id.
+   * Emits a LIFECYCLE 'updated' event + CHANGE events for each modified field.
+   */
+  async update(id: string, input: Partial<TEntity>, tx?: unknown): Promise<TEntity> {
+    // Snapshot before for change diffing
+    let before: Record<string, unknown> | undefined;
+    if (this._shouldEmit()) {
+      const existing = await this.repository.findById(id);
+      if (existing) {
+        before = entitySnapshot(existing as Record<string, unknown>);
+      }
+    }
+
+    const result = await this.repository.update(id, input, tx);
+
+    if (this._shouldEmit()) {
+      const after = entitySnapshot(result as Record<string, unknown>);
+      const events = [
+        buildLifecycleEvent(this.entityName!, 'updated', id, after),
+      ];
+      // Append per-field CHANGE events
+      if (before) {
+        const changes = diffSnapshots(before, after);
+        if (changes.length > 0) {
+          events.push(...buildChangeEvents(this.entityName!, id, changes));
+        }
+      }
+      void emitSafely(this.eventBus, events);
+    }
+
+    return result;
+  }
+
+  /**
+   * Delete an entity by id.
+   * Emits a LIFECYCLE 'deleted' event.
+   */
+  async delete(id: string, tx?: unknown): Promise<void> {
+    await this.repository.delete(id, tx);
+
+    if (this._shouldEmit()) {
+      const event = buildLifecycleEvent(this.entityName!, 'deleted', id);
+      void emitSafely(this.eventBus, [event]);
+    }
+  }
+
+  /** Check whether lifecycle event emission is active. */
+  private _shouldEmit(): boolean {
+    return Boolean(
+      this.emitLifecycleEvents &&
+      this.entityName &&
+      this.eventBus,
+    );
+  }
+}

package/runtime/base-classes/index.ts

@@ -0,0 +1,38 @@
+/**
+ * Base classes barrel export
+ */
+export { BaseRepository } from './base-repository';
+export type { BehaviorConfig, ListOptions } from './base-repository';
+
+export { BaseService } from './base-service';
+export type { IBaseRepository } from './base-service';
+
+export {
+  entitySnapshot,
+  diffSnapshots,
+  buildLifecycleEvent,
+  buildChangeEvents,
+  emitSafely,
+} from './lifecycle-events';
+export type { EventCategory } from './lifecycle-events';
+
+export { BaseFindByIdUseCase, BaseListUseCase } from './base-read-use-cases';
+export type { IFindByIdService, IListService } from './base-read-use-cases';
+
+// Family-specific repository base classes
+export { SyncedEntityRepository } from './synced-entity-repository';
+export { ActivityEntityRepository } from './activity-entity-repository';
+export { MetadataEntityRepository } from './metadata-entity-repository';
+export { KnowledgeEntityRepository } from './knowledge-entity-repository';
+
+// Family-specific service base classes
+export { SyncedEntityService } from './synced-entity-service';
+export type { ISyncedEntityRepository } from './synced-entity-service';
+export { ActivityEntityService } from './activity-entity-service';
+export type { IActivityEntityRepository } from './activity-entity-service';
+export { MetadataEntityService } from './metadata-entity-service';
+export type { IMetadataEntityRepository } from './metadata-entity-service';
+export { KnowledgeEntityService } from './knowledge-entity-service';
+
+// Mixins
+export { WithAnalytics } from './with-analytics';

package/runtime/base-classes/knowledge-entity-repository.ts

@@ -0,0 +1,12 @@
+/**
+ * KnowledgeEntityRepository<TEntity>
+ *
+ * Stub for the knowledge family (requires pgvector — parked for now).
+ * Concrete repos extend this when pgvector is available.
+ */
+import { BaseRepository } from './base-repository';
+
+export abstract class KnowledgeEntityRepository<TEntity> extends BaseRepository<TEntity> {
+  // pgvector-dependent methods will be added when the extension is available:
+  //   semanticSearch, findPendingByOpportunityId, updateStatus, updateStatusBatch
+}

package/runtime/base-classes/knowledge-entity-service.ts

@@ -0,0 +1,14 @@
+/**
+ * KnowledgeEntityService<TRepo, TEntity>
+ *
+ * Stub for the knowledge family (requires pgvector — parked for now).
+ */
+import { BaseService, type IBaseRepository } from './base-service';
+
+export abstract class KnowledgeEntityService<
+  TRepo extends IBaseRepository<TEntity>,
+  TEntity,
+> extends BaseService<TRepo, TEntity> {
+  // pgvector-dependent methods will be added when the extension is available:
+  //   semanticSearch, findPendingByOpportunityId, updateStatus, updateStatusBatch
+}

package/runtime/base-classes/lifecycle-events.ts

@@ -0,0 +1,152 @@
+/**
+ * Lifecycle event emission for BaseService.
+ *
+ * Ported from pattern-stack/atoms/patterns/services/base.py — the Python
+ * BaseService emits LIFECYCLE and CHANGE events on every CRUD operation.
+ * This module provides the same capability for the TypeScript codegen stack.
+ *
+ * Design:
+ *   - Fire-and-forget: event emission never fails the CRUD operation.
+ *   - IEventBus is optional: if no EVENT_BUS is injected, emission is silently
+ *     skipped. This means base classes work in projects that haven't installed
+ *     the events subsystem.
+ *   - LIFECYCLE events carry an entity snapshot in payload.
+ *   - CHANGE events carry per-field old/new diffs.
+ *   - Controlled per-entity via `emitLifecycleEvents` flag (default: true).
+ *
+ * @deprecated EVT-7 — Lifecycle events are untyped and emit outside of the
+ *   CRUD transaction. New work should declare an `emits:` block on the entity
+ *   and publish typed domain events from use-cases via TYPED_EVENT_BUS inside
+ *   the same Drizzle transaction. See `docs/specs/EVT-7.md`. This helper is
+ *   retained for BaseService backward compatibility until all entities have
+ *   migrated to typed emits.
+ */
+
+import { randomUUID } from 'crypto';
+import type { IEventBus, DomainEvent } from '../subsystems/events/event-bus.protocol';
+
+// ============================================================================
+// Event categories (subset of pattern-stack's EventCategory)
+// ============================================================================
+
+export type EventCategory = 'lifecycle' | 'change';
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/** System fields excluded from entity snapshots and change diffs. */
+const SYSTEM_FIELDS = new Set([
+	'id',
+	'createdAt',
+	'updatedAt',
+	'deletedAt',
+]);
+
+/**
+ * Snapshot an entity's field values, excluding system fields.
+ * Mirrors pattern-stack's `_get_entity_snapshot()`.
+ */
+export function entitySnapshot(entity: Record<string, unknown>): Record<string, unknown> {
+	const snap: Record<string, unknown> = {};
+	for (const [key, value] of Object.entries(entity)) {
+		if (!SYSTEM_FIELDS.has(key)) {
+			snap[key] = value;
+		}
+	}
+	return snap;
+}
+
+/**
+ * Diff two entity snapshots, returning per-field old/new pairs.
+ * Only includes fields that actually changed.
+ */
+export function diffSnapshots(
+	before: Record<string, unknown>,
+	after: Record<string, unknown>,
+): Array<{ field: string; oldValue: unknown; newValue: unknown }> {
+	const changes: Array<{ field: string; oldValue: unknown; newValue: unknown }> = [];
+	const allKeys = new Set([...Object.keys(before), ...Object.keys(after)]);
+
+	for (const key of allKeys) {
+		if (SYSTEM_FIELDS.has(key)) continue;
+		const oldVal = before[key];
+		const newVal = after[key];
+		// Simple equality — good enough for primitives and nulls.
+		// For deep objects, JSON.stringify comparison.
+		if (oldVal !== newVal && JSON.stringify(oldVal) !== JSON.stringify(newVal)) {
+			changes.push({ field: key, oldValue: oldVal, newValue: newVal });
+		}
+	}
+
+	return changes;
+}
+
+// ============================================================================
+// Event builders
+// ============================================================================
+
+export function buildLifecycleEvent(
+	entityName: string,
+	action: 'created' | 'updated' | 'deleted',
+	entityId: string,
+	snapshot?: Record<string, unknown>,
+): DomainEvent {
+	return {
+		id: randomUUID(),
+		type: `${entityName}.${action}`,
+		aggregateId: entityId,
+		aggregateType: entityName,
+		payload: snapshot ? { snapshot } : {},
+		occurredAt: new Date(),
+		metadata: { category: 'lifecycle' as EventCategory },
+	};
+}
+
+export function buildChangeEvents(
+	entityName: string,
+	entityId: string,
+	changes: Array<{ field: string; oldValue: unknown; newValue: unknown }>,
+): DomainEvent[] {
+	return changes.map((c) => ({
+		id: randomUUID(),
+		type: `${entityName}.field_changed`,
+		aggregateId: entityId,
+		aggregateType: entityName,
+		payload: {
+			fieldName: c.field,
+			oldValue: c.oldValue,
+			newValue: c.newValue,
+		},
+		occurredAt: new Date(),
+		metadata: { category: 'change' as EventCategory },
+	}));
+}
+
+// ============================================================================
+// Emission helper (fire-and-forget)
+// ============================================================================
+
+/**
+ * Emit events to the bus, swallowing errors.
+ * Mirrors pattern-stack's `_emit_lifecycle_event()` try/except.
+ */
+export async function emitSafely(
+	eventBus: IEventBus | undefined,
+	events: DomainEvent[],
+): Promise<void> {
+	if (!eventBus || events.length === 0) return;
+	try {
+		if (events.length === 1) {
+			const only = events[0];
+			if (!only) return;
+			await eventBus.publish(only);
+		} else {
+			await eventBus.publishMany(events);
+		}
+	} catch {
+		// Log but never fail the CRUD operation.
+		// In production, this would use a structured logger.
+		console.warn(`[lifecycle-events] failed to emit ${events.length} event(s)`);
+	}
+}