@woltz/rich-domain-drizzle 0.1.0

package/src/mappers/to-persistence.ts

@@ -0,0 +1,101 @@
+import {
+  Mapper,
+  AggregateChanges,
+  EntitySchemaRegistry,
+} from "@woltz/rich-domain";
+import {
+  DrizzleClient,
+  DrizzleUnitOfWork,
+  UOWStorage,
+  Transactional,
+} from "../unit-of-work";
+import { DrizzleBatchExecutor } from "../batch-executor";
+
+export abstract class DrizzleToPersistence<TDomain> extends Mapper<
+  TDomain,
+  void
+> {
+  constructor(protected readonly uow: DrizzleUnitOfWork) {
+    super();
+  }
+
+  /**
+   * Schema registry for field mapping (entity → table, field → column).
+   */
+  protected abstract readonly registry: EntitySchemaRegistry;
+
+  /**
+   * Map of entity names to Drizzle table objects.
+   *
+   * @example
+   * ```typescript
+   * protected readonly tableMap = new Map([
+   *   ["User", usersTable],
+   *   ["Post", postsTable],
+   * ]);
+   * ```
+   */
+  protected abstract readonly tableMap: Map<string, any>;
+
+  /**
+   * Get the raw db instance.
+   */
+  protected abstract getDb(): DrizzleClient;
+
+  /**
+   * Get current context (transaction client or raw db).
+   */
+  protected get context(): DrizzleClient {
+    const ctx = UOWStorage.getStore()?.ctx;
+    return ctx?.client ?? this.getDb();
+  }
+
+  /**
+   * Build persistence operations.
+   */
+  async build(entity: TDomain): Promise<void> {
+    const isNew = (entity as any).isNew?.() ?? false;
+
+    if (isNew) {
+      await this.onCreate(entity);
+    } else {
+      await this.handleUpdate(entity);
+    }
+  }
+
+  /**
+   * Handle new aggregate creation.
+   * Must be implemented by subclass.
+   */
+  protected abstract onCreate(aggregate: TDomain): Promise<void>;
+
+  /**
+   * Handle aggregate update with changes.
+   * Default implementation uses DrizzleBatchExecutor.
+   * Subclass can override for custom logic.
+   */
+  protected async onUpdate(
+    changes: AggregateChanges,
+    _aggregate: TDomain
+  ): Promise<void> {
+    const executor = new DrizzleBatchExecutor({
+      registry: this.registry,
+      db: this.context,
+      tableMap: this.tableMap,
+    });
+    await executor.execute(changes);
+  }
+
+  @Transactional()
+  private async handleUpdate(entity: TDomain): Promise<void> {
+    const changes = (entity as any).getChanges?.() as
+      | AggregateChanges
+      | undefined;
+
+    if (!changes || changes.isEmpty()) {
+      return;
+    }
+
+    await this.onUpdate(changes, entity);
+  }
+}

package/src/query-builder.ts

@@ -0,0 +1,217 @@
+import {
+  eq,
+  ne,
+  gt,
+  gte,
+  lt,
+  lte,
+  ilike,
+  like,
+  inArray,
+  notInArray,
+  isNull,
+  isNotNull,
+  between,
+  and,
+  or,
+  asc,
+  desc,
+  SQL,
+} from "drizzle-orm";
+import { Criteria } from "@woltz/rich-domain";
+import { DrizzleAdapterError } from "./errors";
+
+export type SearchableField<T> =
+  | keyof T
+  | { field: string; caseSensitive?: boolean };
+
+type OperatorFn = (col: any, val: any) => SQL;
+
+const OPERATOR_MAP: Record<string, OperatorFn> = {
+  equals: (col, val) => eq(col, val),
+  notEquals: (col, val) => ne(col, val),
+  greaterThan: (col, val) => gt(col, val),
+  greaterThanOrEqual: (col, val) => gte(col, val),
+  lessThan: (col, val) => lt(col, val),
+  lessThanOrEqual: (col, val) => lte(col, val),
+  contains: (col, val) => ilike(col, `%${val}%`),
+  startsWith: (col, val) => ilike(col, `${val}%`),
+  endsWith: (col, val) => ilike(col, `%${val}`),
+  in: (col, val) => inArray(col, val),
+  notIn: (col, val) => notInArray(col, val),
+  isNull: (col) => isNull(col),
+  isNotNull: (col) => isNotNull(col),
+  between: (col, val) => between(col, val[0], val[1]),
+};
+
+export class DrizzleQueryBuilder {
+  /**
+   * Apply Criteria to a Drizzle select query.
+   *
+   * @param criteria - The Criteria instance with filters, orders, pagination, search
+   * @param table - The Drizzle table object (e.g., usersTable)
+   * @param searchableFields - Fields to search when criteria.hasSearch()
+   * @returns Object with { where, orderBy, limit, offset } ready for Drizzle query
+   */
+  static apply<T>(
+    criteria: Criteria<T>,
+    table: any,
+    searchableFields?: SearchableField<any>[]
+  ): {
+    where?: SQL;
+    orderBy?: SQL[];
+    limit?: number;
+    offset?: number;
+  } {
+    const result: {
+      where?: SQL;
+      orderBy?: SQL[];
+      limit?: number;
+      offset?: number;
+    } = {};
+
+    // Build filter conditions
+    const filterConditions: SQL[] = [];
+    for (const filter of criteria.getFilters()) {
+      if (filter.field.includes(".")) {
+        throw new DrizzleAdapterError(
+          `Filtering on relation field "${filter.field}" is not supported. ` +
+            `Drizzle requires explicit JOINs to filter across relations. ` +
+            `Add a custom method to your repository using the Drizzle SQL API instead.`
+        );
+      }
+
+      if (filter.options?.quantifier) {
+        throw new DrizzleAdapterError(
+          `Quantifier "${filter.options.quantifier}" on field "${filter.field}" is not supported. ` +
+            `Drizzle does not have a built-in some/every/none operator. ` +
+            `Add a custom method to your repository using EXISTS subqueries instead.`
+        );
+      }
+
+      const col = DrizzleQueryBuilder.resolveColumn(table, filter.field);
+      if (col === undefined) {
+        throw new DrizzleAdapterError(
+          `Column "${filter.field}" not found on table. ` +
+            `Available columns: ${Object.keys(table)
+              .filter((k) => typeof table[k] === "object")
+              .join(", ")}`
+        );
+      }
+
+      const operatorFn = OPERATOR_MAP[filter.operator];
+      if (!operatorFn) {
+        throw new DrizzleAdapterError(
+          `Operator "${filter.operator}" is not supported by the Drizzle adapter.`
+        );
+      }
+
+      filterConditions.push(operatorFn(col, filter.value));
+    }
+
+    // Build search conditions
+    let searchCondition: SQL | undefined;
+    if (
+      criteria.hasSearch() &&
+      searchableFields &&
+      searchableFields.length > 0
+    ) {
+      const search = criteria.getSearch()!;
+      const searchConditions: SQL[] = [];
+
+      for (const searchField of searchableFields) {
+        let fieldName: string;
+        let caseSensitive = false;
+
+        if (typeof searchField === "object" && "field" in searchField) {
+          fieldName = searchField.field;
+          caseSensitive = searchField.caseSensitive ?? false;
+        } else {
+          fieldName = String(searchField);
+        }
+
+        if (fieldName.includes(".")) {
+          throw new DrizzleAdapterError(
+            `Search field "${fieldName}" references a relation. ` +
+              `Drizzle does not support cross-table search via Criteria. ` +
+              `Use only top-level columns in getSearchableFields().`
+          );
+        }
+
+        const col = DrizzleQueryBuilder.resolveColumn(table, fieldName);
+        if (col === undefined) {
+          throw new DrizzleAdapterError(
+            `Search field "${fieldName}" not found on table. ` +
+              `Available columns: ${Object.keys(table)
+                .filter((k) => typeof table[k] === "object")
+                .join(", ")}`
+          );
+        }
+
+        if (caseSensitive) {
+          searchConditions.push(like(col, `%${search}%`));
+        } else {
+          searchConditions.push(ilike(col, `%${search}%`));
+        }
+      }
+
+      if (searchConditions.length > 0) {
+        searchCondition =
+          searchConditions.length === 1
+            ? searchConditions[0]
+            : or(...searchConditions)!;
+      }
+    }
+
+    // Combine filter and search conditions
+    if (filterConditions.length > 0 || searchCondition) {
+      const allConditions: SQL[] = [...filterConditions];
+      if (searchCondition) allConditions.push(searchCondition);
+
+      if (allConditions.length === 1) {
+        result.where = allConditions[0];
+      } else {
+        result.where = and(...allConditions)!;
+      }
+    }
+
+    // Build order conditions
+    const orders = criteria.getOrders();
+    if (orders.length > 0) {
+      result.orderBy = orders.map((o) => {
+        if (o.field.includes(".")) {
+          throw new DrizzleAdapterError(
+            `Ordering by relation field "${o.field}" is not supported. ` +
+              `Drizzle requires explicit JOINs to order across relations. ` +
+              `Add a custom method to your repository using the Drizzle SQL API instead.`
+          );
+        }
+
+        const col = DrizzleQueryBuilder.resolveColumn(table, o.field);
+        if (col === undefined) {
+          throw new DrizzleAdapterError(
+            `Order field "${o.field}" not found on table. ` +
+              `Available columns: ${Object.keys(table)
+                .filter((k) => typeof table[k] === "object")
+                .join(", ")}`
+          );
+        }
+
+        return o.direction === "desc" ? desc(col) : asc(col);
+      });
+    }
+
+    // Build pagination
+    const pagination = criteria.getPagination();
+    if (pagination) {
+      result.limit = pagination.limit;
+      result.offset = pagination.offset;
+    }
+
+    return result;
+  }
+
+  static resolveColumn(table: any, fieldPath: string): any {
+    return table[fieldPath];
+  }
+}

package/src/repository.ts

@@ -0,0 +1,252 @@
+import { eq, inArray, count, SQL } from "drizzle-orm";
+import {
+  Aggregate,
+  Repository,
+  Mapper,
+  Criteria,
+  PaginatedResult,
+} from "@woltz/rich-domain";
+import { DrizzleClient, DrizzleUnitOfWork, UOWStorage } from "./unit-of-work";
+import { NoRecordsAffectedError } from "./errors";
+import { DrizzleToPersistence } from "./mappers/to-persistence";
+import { DrizzleQueryBuilder, SearchableField } from "./query-builder";
+
+export interface DrizzleRepositoryConfig<TDomain, TPersistence> {
+  db: DrizzleClient;
+  table: any;
+  toDomainMapper: Mapper<TPersistence, TDomain>;
+  toPersistenceMapper: DrizzleToPersistence<TDomain>;
+  uow: DrizzleUnitOfWork;
+}
+
+export abstract class DrizzleRepository<
+  TDomain extends Aggregate<any>,
+  TPersistence,
+> extends Repository<TDomain> {
+  protected readonly db: DrizzleClient;
+  protected readonly table: any;
+  protected readonly toDomainMapper: Mapper<TPersistence, TDomain>;
+  protected readonly toPersistenceMapper: DrizzleToPersistence<TDomain>;
+  protected readonly uow: DrizzleUnitOfWork;
+
+  constructor(config: DrizzleRepositoryConfig<TDomain, TPersistence>) {
+    super();
+    this.db = config.db;
+    this.table = config.table;
+    this.toDomainMapper = config.toDomainMapper;
+    this.toPersistenceMapper = config.toPersistenceMapper;
+    this.uow = config.uow;
+  }
+
+  /**
+   * Returns tx from UOWStorage if inside a transaction, otherwise the raw db.
+   */
+  protected get context(): DrizzleClient {
+    const ctx = UOWStorage.getStore()?.ctx;
+    return ctx?.client ?? this.db;
+  }
+
+  /**
+   * The table name string used by EntitySchemaRegistry and db.query accessor.
+   */
+  protected abstract get model(): string;
+
+  /**
+   * Search conditions for full-text search via Criteria.search().
+   */
+  protected abstract getSearchableFields(): SearchableField<TPersistence>[];
+
+  /**
+   * Relations to include when fetching (for Drizzle relational query API).
+   */
+  protected getDefaultRelations(): Record<string, any> {
+    return {};
+  }
+
+  async find(criteria: Criteria<TDomain>): Promise<PaginatedResult<TDomain>> {
+    const { where, orderBy, limit, offset } = DrizzleQueryBuilder.apply(
+      criteria,
+      this.table,
+      this.getSearchableFields()
+    );
+
+    const queryModel = this.context.query?.[this.model];
+
+    let data: TPersistence[];
+    let total: number;
+
+    if (queryModel) {
+      [data, total] = await Promise.all([
+        queryModel.findMany({
+          where,
+          orderBy,
+          limit,
+          offset,
+          with: this.getDefaultRelations(),
+        }),
+        this.context
+          .select({ value: count() })
+          .from(this.table)
+          .where(where)
+          .then((r: any[]) => Number(r[0]?.value ?? 0)),
+      ]);
+    } else {
+      const selectQuery = this.context.select().from(this.table).$dynamic();
+
+      if (where) selectQuery.where(where);
+      if (orderBy && orderBy.length > 0) selectQuery.orderBy(...orderBy);
+      if (limit !== undefined) selectQuery.limit(limit);
+      if (offset !== undefined) selectQuery.offset(offset);
+
+      const countQuery = this.context
+        .select({ value: count() })
+        .from(this.table);
+      if (where) countQuery.where(where);
+
+      [data, [{ value: total }]] = await Promise.all([selectQuery, countQuery]);
+      total = Number(total ?? 0);
+    }
+
+    const toDomain: TDomain[] = (data as any[]).map((item) =>
+      this.toDomainMapper.build(item)
+    );
+
+    this.markArrayOfAggregateWithClean(toDomain);
+
+    return PaginatedResult.create(toDomain, criteria.getPagination(), total);
+  }
+
+  async findById(id: string): Promise<TDomain | null> {
+    const queryModel = this.context.query?.[this.model];
+
+    let data: any;
+
+    if (queryModel) {
+      data = await queryModel.findFirst({
+        where: eq(this.table.id, id),
+        with: this.getDefaultRelations(),
+      });
+    } else {
+      const rows = await this.context
+        .select()
+        .from(this.table)
+        .where(eq(this.table.id, id))
+        .limit(1);
+      data = rows[0] ?? null;
+    }
+
+    if (!data) return null;
+
+    const result = this.toDomainMapper.build(data);
+
+    if (result instanceof Aggregate) {
+      result.markAsClean();
+    }
+
+    return result;
+  }
+
+  async findManyByIds(ids: string[]): Promise<TDomain[]> {
+    if (ids.length === 0) return [];
+
+    const queryModel = this.context.query?.[this.model];
+
+    let data: any[];
+
+    if (queryModel) {
+      data = await queryModel.findMany({
+        where: inArray(this.table.id, ids),
+        with: this.getDefaultRelations(),
+      });
+    } else {
+      data = await this.context
+        .select()
+        .from(this.table)
+        .where(inArray(this.table.id, ids));
+    }
+
+    const toDomain: TDomain[] = data.map((item: any) =>
+      this.toDomainMapper.build(item)
+    );
+
+    this.markArrayOfAggregateWithClean(toDomain);
+
+    return toDomain;
+  }
+
+  async count(criteria?: Criteria<TDomain>): Promise<number> {
+    let where: SQL | undefined;
+
+    if (criteria) {
+      ({ where } = DrizzleQueryBuilder.apply(
+        criteria,
+        this.table,
+        this.getSearchableFields()
+      ));
+    }
+
+    const query = this.context.select({ value: count() }).from(this.table);
+    if (where) query.where(where);
+
+    const result = await query;
+    return Number(result[0]?.value ?? 0);
+  }
+
+  async exists(id: string): Promise<boolean> {
+    const result = await this.context
+      .select({ value: count() })
+      .from(this.table)
+      .where(eq(this.table.id, id));
+    return Number(result[0]?.value ?? 0) > 0;
+  }
+
+  async save(entity: TDomain): Promise<void> {
+    await this.toPersistenceMapper.build(entity);
+    entity.markAsPersisted();
+  }
+
+  async delete(entity: TDomain): Promise<void> {
+    const id = entity.id.value;
+    try {
+      const result = await this.context
+        .delete(this.table)
+        .where(eq(this.table.id, id))
+        .returning({ id: this.table.id });
+
+      if (!result || result.length === 0) {
+        throw new NoRecordsAffectedError("Delete", this.model, String(id));
+      }
+    } catch (error: any) {
+      if (error instanceof NoRecordsAffectedError) throw error;
+      throw error;
+    }
+  }
+
+  async deleteById(id: string): Promise<void> {
+    try {
+      const result = await this.context
+        .delete(this.table)
+        .where(eq(this.table.id, id))
+        .returning({ id: this.table.id });
+
+      if (!result || result.length === 0) {
+        throw new NoRecordsAffectedError("Delete", this.model, id);
+      }
+    } catch (error: any) {
+      if (error instanceof NoRecordsAffectedError) throw error;
+      throw error;
+    }
+  }
+
+  async transaction<T>(work: () => Promise<T>): Promise<T> {
+    return this.uow.transaction(work);
+  }
+
+  private markArrayOfAggregateWithClean(entities: TDomain[]): void {
+    for (const entity of entities) {
+      if (entity instanceof Aggregate) {
+        entity.markAsClean();
+      }
+    }
+  }
+}

package/src/unit-of-work.ts

@@ -0,0 +1,123 @@
+import { AsyncLocalStorage } from "async_hooks";
+
+/**
+ * Drizzle database instance type.
+ * Generic to support pg, mysql, sqlite, and other drivers.
+ */
+export type DrizzleClient = {
+  transaction: <T>(fn: (tx: any) => Promise<T>) => Promise<T>;
+  query: Record<string, any>;
+  select: (...args: any[]) => any;
+  insert: (table: any) => any;
+  update: (table: any) => any;
+  delete: (table: any) => any;
+  [key: string]: any;
+};
+
+export type DrizzleTransactionClient = DrizzleClient;
+
+export class DrizzleTransactionContext {
+  constructor(public readonly client: DrizzleTransactionClient) {}
+}
+
+export const UOWStorage = new AsyncLocalStorage<{
+  ctx: DrizzleTransactionContext | null;
+}>();
+
+export class DrizzleUnitOfWork {
+  constructor(private readonly db: DrizzleClient) {}
+
+  /**
+   * Get current transaction context (if any).
+   */
+  getCurrentContext(): DrizzleTransactionContext | null {
+    return UOWStorage.getStore()?.ctx ?? null;
+  }
+
+  /**
+   * Check if currently inside a transaction.
+   */
+  isInTransaction(): boolean {
+    return this.getCurrentContext() !== null;
+  }
+
+  /**
+   * Execute work inside a transaction.
+   * If already in a transaction, reuses the existing context (idempotent nesting).
+   */
+  async transaction<T>(work: () => Promise<T>): Promise<T> {
+    if (this.isInTransaction()) {
+      return work();
+    }
+
+    return this.db.transaction(async (tx: any) => {
+      const ctx = new DrizzleTransactionContext(tx);
+
+      return UOWStorage.run({ ctx }, async () => {
+        return await work();
+      });
+    });
+  }
+}
+
+/**
+ * Decorator that wraps a method in a transaction.
+ * If already inside a transaction, reuses the existing one.
+ */
+export function Transactional(inputUow?: DrizzleUnitOfWork): MethodDecorator {
+  return function (
+    _target: any,
+    _propertyKey: string | symbol,
+    descriptor: PropertyDescriptor
+  ) {
+    const original = descriptor.value;
+
+    descriptor.value = async function (this: any, ...args: any[]) {
+      if (UOWStorage.getStore()?.ctx) {
+        return original.apply(this, args);
+      }
+
+      const uow = inputUow ?? findUnitOfWork(this);
+
+      if (!uow) {
+        throw new Error(
+          `@Transactional: DrizzleUnitOfWork not found in ${this.constructor.name} instance. ` +
+            "Ensure your class has a 'uow' property. eg: constructor(private readonly uow: DrizzleUnitOfWork) {}"
+        );
+      }
+
+      return uow.transaction(() => original.apply(this, args));
+    };
+
+    return descriptor;
+  };
+}
+
+/**
+ * Find DrizzleUnitOfWork in instance.
+ */
+function findUnitOfWork(instance: any): DrizzleUnitOfWork | null {
+  if (instance.uow instanceof DrizzleUnitOfWork) {
+    return instance.uow;
+  }
+
+  if (instance._uow instanceof DrizzleUnitOfWork) {
+    return instance._uow;
+  }
+
+  for (const key of Object.keys(instance)) {
+    const value = instance[key];
+    if (value instanceof DrizzleUnitOfWork) {
+      return value;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Helper to get current transaction client from anywhere.
+ */
+export function getCurrentDrizzleContext(): DrizzleTransactionClient | null {
+  return UOWStorage.getStore()?.ctx?.client ?? null;
+}