@woltz/rich-domain 0.2.1

package/src/index.ts

@@ -0,0 +1,33 @@
+// ============================================================================
+// Rich Domain Library - Main Exports
+// ============================================================================
+
+// Core Classes
+export { Id } from "./id";
+export { BaseEntity } from "./base-entity";
+export { Entity, Aggregate } from "./entity";
+export { ValueObject } from "./value-object";
+
+export * from "./validation-error";
+
+// Domain Events
+export * from "./domain-event";
+
+export * from "./domain-event-bus";
+
+// Criteria & Repository
+export * from "./criteria";
+export * from "./paginated-result";
+
+// Repository
+export * from "./repository";
+// Backward compatibility - re-export InMemoryRepository at top level
+export { InMemoryRepository } from "./repository";
+
+// Types
+export * from "./types";
+
+export * from "./constants";
+
+// Internal (for advanced usage)
+export { DeepProxy } from "./deep-proxy";

package/src/paginated-result.ts

@@ -0,0 +1,274 @@
+// ============================================================================
+// PaginatedResult - Container for paginated data with deep serialization
+// ============================================================================
+
+import { Id } from "./id";
+import type { Criteria } from "./criteria";
+import type { Pagination, PaginationMeta, Filter } from "./types";
+
+// ============================================================================
+// Type Utilities
+// ============================================================================
+
+/**
+ * Infers the JSON result type from T
+ * - If T has toJson(), returns its return type
+ * - Otherwise returns T as-is
+ */
+type InferJsonResult<T> = T extends { toJson(): infer R } ? R : T;
+
+/**
+ * Type for the serialized result of PaginatedResult.toJSON()
+ */
+export type PaginatedJsonResult<T> = {
+  data: InferJsonResult<T>[];
+  meta: PaginationMeta;
+};
+
+// ============================================================================
+// PaginatedResult Class
+// ============================================================================
+
+export class PaginatedResult<T> {
+  constructor(
+    public readonly data: T[],
+    public readonly meta: PaginationMeta
+  ) {}
+
+  /**
+   * Creates a PaginatedResult with calculated metadata
+   */
+  static create<T>(
+    data: T[],
+    pagination: Pagination,
+    total: number
+  ): PaginatedResult<T> {
+    const meta = this.createMeta(pagination, total);
+    return new PaginatedResult(data, meta);
+  }
+
+  /**
+   * Creates pagination metadata from total count
+   */
+  static createMeta(pagination: Pagination, total: number): PaginationMeta {
+    const totalPages = Math.ceil(total / pagination.limit);
+
+    return {
+      page: pagination.page,
+      limit: pagination.limit,
+      total,
+      totalPages,
+      hasNext: pagination.page < totalPages,
+      hasPrevious: pagination.page > 1,
+    };
+  }
+
+  /**
+   * Applies criteria to an in-memory array (useful for testing)
+   */
+  static fromArray<T>(
+    items: T[],
+    criteria: Criteria<T>
+  ): PaginatedResult<T> {
+    let result = [...items];
+
+    // Apply filters
+    for (const filter of criteria.getFilters()) {
+      result = result.filter((item) => applyFilter(item, filter));
+    }
+
+    const total = result.length;
+
+    // Apply ordering
+    for (const order of criteria.getOrders().reverse()) {
+      result.sort((a, b) => {
+        const aVal = getNestedValue(a, order.field);
+        const bVal = getNestedValue(b, order.field);
+
+        let comparison = 0;
+        if (aVal < bVal) comparison = -1;
+        if (aVal > bVal) comparison = 1;
+
+        return order.direction === "desc" ? -comparison : comparison;
+      });
+    }
+
+    // Apply pagination
+    const pagination = criteria.getPagination();
+    if (pagination) {
+      result = result.slice(
+        pagination.offset,
+        pagination.offset + pagination.limit
+      );
+      return PaginatedResult.create(result, pagination, total);
+    }
+
+    // No pagination - return all with default meta
+    return PaginatedResult.create(
+      result,
+      { page: 1, limit: result.length, offset: 0 },
+      total
+    );
+  }
+
+  /**
+   * Converts the result to JSON, deeply serializing all entities/aggregates/value objects
+   * - Entities/Aggregates → calls toJson() recursively
+   * - Value Objects → calls toJson()
+   * - Id → converts to string
+   * - Arrays → maps recursively
+   * - Plain objects → serializes properties recursively
+   * - Primitives → returns as-is
+   */
+  toJSON(): PaginatedJsonResult<T> {
+    return {
+      data: this.data.map((item) =>
+        this.deepSerialize(item)
+      ) as InferJsonResult<T>[],
+      meta: this.meta,
+    };
+  }
+
+  /**
+   * Deep serialization logic (similar to BaseEntity.deepToJson)
+   */
+  private deepSerialize(obj: any): any {
+    if (obj === null || obj === undefined) return obj;
+
+    // Id → string
+    if (obj instanceof Id) return obj.value;
+
+    // Arrays → map recursively
+    if (Array.isArray(obj)) {
+      return obj.map((item) => this.deepSerialize(item));
+    }
+
+    // Objects with toJson() method (Entity/Aggregate/ValueObject)
+    if (obj && typeof obj.toJson === "function") {
+      return obj.toJson();
+    }
+
+    // Plain objects → serialize properties recursively
+    if (typeof obj === "object") {
+      const result: any = {};
+      for (const key in obj) {
+        if (obj.hasOwnProperty(key)) {
+          result[key] = this.deepSerialize(obj[key]);
+        }
+      }
+      return result;
+    }
+
+    // Primitives
+    return obj;
+  }
+
+  /**
+   * Transform each item in the result using a mapper function
+   */
+  map<U>(fn: (item: T) => U): PaginatedResult<U> {
+    return new PaginatedResult(this.data.map(fn), this.meta);
+  }
+
+  /**
+   * Check if result has no data
+   */
+  get isEmpty(): boolean {
+    return this.data.length === 0;
+  }
+
+  /**
+   * Check if there are more pages available
+   */
+  get hasMore(): boolean {
+    return this.meta.hasNext;
+  }
+}
+
+// ============================================================================
+// Helper Functions (moved from criteria.ts)
+// ============================================================================
+
+function applyFilter<T>(item: T, filter: Filter): boolean {
+  const value = getNestedValue(item, filter.field);
+
+  const isValueDate = value instanceof Date;
+
+  const parseValue = (v: any) => {
+    if (isValueDate && typeof v === "string") return new Date(v);
+    if (isValueDate && typeof v === "number") return new Date(v);
+    return v;
+  };
+
+  switch (filter.operator) {
+    case "equals":
+      return value === filter.value;
+
+    case "notEquals":
+      return value !== filter.value;
+
+    case "greaterThan": {
+      const compareTo = parseValue(filter.value);
+      return isValueDate ? value > compareTo : value > (filter.value as any);
+    }
+
+    case "greaterThanOrEqual": {
+      const compareTo = parseValue(filter.value);
+      return isValueDate ? value >= compareTo : value >= (filter.value as any);
+    }
+
+    case "lessThan":
+      const lt = parseValue(filter.value);
+      return isValueDate ? value < lt : value < (filter.value as any);
+
+    case "lessThanOrEqual":
+      const lte = parseValue(filter.value);
+      return isValueDate ? value <= lte : value <= (filter.value as any);
+
+    case "contains":
+      return String(value)
+        .toLowerCase()
+        .includes(String(filter.value).toLowerCase());
+
+    case "startsWith":
+      return String(value)
+        .toLowerCase()
+        .startsWith(String(filter.value).toLowerCase());
+
+    case "endsWith":
+      return String(value)
+        .toLowerCase()
+        .endsWith(String(filter.value).toLowerCase());
+
+    case "in":
+      return Array.isArray(filter.value) && filter.value.includes(value);
+
+    case "notIn":
+      return Array.isArray(filter.value) && !filter.value.includes(value);
+
+    case "between":
+      if (Array.isArray(filter.value) && filter.value.length === 2) {
+        const [min, max] = filter.value.map(parseValue);
+        return isValueDate
+          ? value >= min && value <= max
+          : value >= filter.value[0] && value <= filter.value[1];
+      }
+      return false;
+
+    case "isNull":
+      return value === null || value === undefined;
+
+    case "isNotNull":
+      return value !== null && value !== undefined;
+
+    default:
+      return true;
+  }
+}
+
+function getNestedValue(obj: any, path: string): any {
+  return path.split(".").reduce((current, key) => {
+    if (current === null || current === undefined) return undefined;
+    return current[key];
+  }, obj);
+}

package/src/repository/base-repository.ts

@@ -0,0 +1,152 @@
+// ============================================================================
+// Base Repository - Abstract implementation with common logic
+// ============================================================================
+
+import type { Id } from "../id";
+import type { Aggregate } from "../entity";
+import type { Criteria } from "../criteria";
+import { PaginatedResult } from "../paginated-result";
+import type { IRepository } from "../types";
+import type { IMapper } from "./mapper";
+
+/**
+ * Abstract base repository
+ * Implements common logic, delegates persistence to subclasses
+ *
+ * @example
+ * ```ts
+ * class UserRepository extends BaseRepository<User, PrismaUser> {
+ *   constructor(prisma: PrismaClient) {
+ *     super(new UserMapper());
+ *     this.prisma = prisma;
+ *   }
+ *
+ *   protected async insertOne(data: PrismaUser): Promise<PrismaUser> {
+ *     return this.prisma.user.create({ data });
+ *   }
+ *
+ *   protected async updateOne(id: string, data: PrismaUser): Promise<PrismaUser> {
+ *     return this.prisma.user.update({ where: { id }, data });
+ *   }
+ *
+ *   // ... implement other abstract methods
+ * }
+ * ```
+ */
+export abstract class BaseRepository<
+  TDomain extends Aggregate<any>,
+  TPersistence = any
+> implements IRepository<TDomain>
+{
+  constructor(protected readonly mapper: IMapper<TDomain, TPersistence>) {}
+
+  // ============================================================================
+  // Abstract methods - Must be implemented by subclasses
+  // ============================================================================
+
+  /**
+   * Insert new record in database
+   */
+  protected abstract insertOne(data: TPersistence): Promise<TPersistence>;
+
+  /**
+   * Update existing record in database
+   */
+  protected abstract updateOne(
+    id: string,
+    data: TPersistence
+  ): Promise<TPersistence>;
+
+  /**
+   * Delete record from database
+   */
+  protected abstract deleteOne(id: string): Promise<void>;
+
+  /**
+   * Find record by ID in database
+   */
+  protected abstract findOneById(id: string): Promise<TDomain | null>;
+
+  /**
+   * Find all records in database (no filtering)
+   */
+  protected abstract findMany(): Promise<TDomain[]>;
+
+  /**
+   * Apply criteria to query (filtering, ordering, pagination)
+   * Returns [data, total]
+   */
+  protected abstract applyCriteria(
+    criteria: Criteria<TDomain>
+  ): Promise<PaginatedResult<TDomain>>;
+
+  /**
+   * Count records matching criteria
+   */
+  protected abstract countByCriteria(
+    criteria?: Criteria<TDomain>
+  ): Promise<number>;
+
+  /**
+   * Check if record exists by ID
+   */
+  protected abstract existsById(id: string): Promise<boolean>;
+
+  // ============================================================================
+  // Public API - Implemented using abstract methods
+  // ============================================================================
+
+  async findById(id: Id): Promise<TDomain | null> {
+    const domain = await this.findOneById(id.value);
+    if (!domain) return null;
+    return domain;
+  }
+
+  async find(criteria: Criteria<TDomain>): Promise<PaginatedResult<TDomain>> {
+    return await this.applyCriteria(criteria);
+  }
+
+  async findAll(criteria?: Criteria<TDomain>): Promise<TDomain[]> {
+    if (criteria) {
+      const result = await this.find(criteria);
+      return result.data;
+    }
+
+    const domains = await this.findMany();
+    return domains;
+  }
+
+  async findOne(criteria: Criteria<TDomain>): Promise<TDomain | null> {
+    // Limit to 1 result
+    const limitedCriteria = criteria.clone().limit(1);
+    const result = await this.find(limitedCriteria);
+
+    return result.data.length > 0 ? result.data[0] : null;
+  }
+
+  async save(aggregate: TDomain): Promise<void> {
+    const persistence = this.mapper.toPersistence(aggregate);
+
+    if (aggregate.isNew) {
+      await this.insertOne(persistence);
+    } else {
+      await this.updateOne(aggregate.id.value, persistence);
+    }
+  }
+
+  async delete(aggregate: TDomain): Promise<void> {
+    await this.deleteOne(aggregate.id.value);
+  }
+
+  async deleteById(id: Id): Promise<void> {
+    await this.deleteOne(id.value);
+  }
+
+  async exists(id: Id): Promise<boolean> {
+    return this.existsById(id.value);
+  }
+
+  async count(criteria?: Criteria<TDomain>): Promise<number> {
+    return this.countByCriteria(criteria);
+  }
+}

package/src/repository/in-memory-repository.ts

@@ -0,0 +1,104 @@
+// ============================================================================
+// In-Memory Repository - Perfect for testing
+// ============================================================================
+
+import type { Id } from "../id";
+import type { Aggregate } from "../entity";
+import type { Criteria } from "../criteria";
+import { PaginatedResult } from "../paginated-result";
+import type { IRepository } from "../types";
+
+/**
+ * In-memory repository implementation
+ * Perfect for unit tests and prototyping
+ *
+ * @example
+ * ```ts
+ * const userRepo = new InMemoryRepository<User>();
+ *
+ * await userRepo.save(user);
+ * const found = await userRepo.findById(user.id);
+ * const active = await userRepo.find(
+ *   Criteria.create<User>().whereEquals('status', 'active')
+ * );
+ * ```
+ */
+export class InMemoryRepository<TDomain extends Aggregate<any>>
+  implements IRepository<TDomain>
+{
+  protected items: Map<string, TDomain> = new Map();
+
+  async findById(id: Id): Promise<TDomain | null> {
+    return this.items.get(id.value) || null;
+  }
+
+  async find(criteria: Criteria<TDomain>): Promise<PaginatedResult<TDomain>> {
+    const allItems = Array.from(this.items.values());
+    return PaginatedResult.fromArray(allItems, criteria);
+  }
+
+  async findAll(criteria?: Criteria<TDomain>): Promise<TDomain[]> {
+    if (criteria) {
+      const result = await this.find(criteria);
+      return result.data;
+    }
+
+    return Array.from(this.items.values());
+  }
+
+  async findOne(criteria: Criteria<TDomain>): Promise<TDomain | null> {
+    const result = await this.find(criteria.clone().limit(1));
+    return result.data.length > 0 ? result.data[0] : null;
+  }
+
+  async save(aggregate: TDomain): Promise<void> {
+    this.items.set(aggregate.id.value, aggregate);
+  }
+
+  async saveMany(aggregates: TDomain[]): Promise<void> {
+    for (const aggregate of aggregates) {
+      await this.save(aggregate);
+    }
+  }
+
+  async delete(aggregate: TDomain): Promise<void> {
+    this.items.delete(aggregate.id.value);
+  }
+
+  async deleteById(id: Id): Promise<void> {
+    this.items.delete(id.value);
+  }
+
+  async exists(id: Id): Promise<boolean> {
+    return this.items.has(id.value);
+  }
+
+  async count(criteria?: Criteria<TDomain>): Promise<number> {
+    if (criteria) {
+      const result = await this.find(criteria);
+      return result.meta.total;
+    }
+    return this.items.size;
+  }
+
+  /**
+   * Clear all items (useful for test cleanup)
+   */
+  clear(): void {
+    this.items.clear();
+  }
+
+  /**
+   * Get all items as array (useful for debugging)
+   */
+  getAll(): TDomain[] {
+    return Array.from(this.items.values());
+  }
+
+  /**
+   * Get items count
+   */
+  size(): number {
+    return this.items.size;
+  }
+}

package/src/repository/index.ts

@@ -0,0 +1,55 @@
+// ============================================================================
+// Repository Module - Clean exports
+// ============================================================================
+
+// Mapper
+export { BaseMapper } from "./mapper";
+export type { IMapper } from "./mapper";
+
+// Base implementations
+export { BaseRepository } from "./base-repository";
+export { InMemoryRepository } from "./in-memory-repository";
+
+// Unit of Work
+export {
+  UnitOfWork,
+  BaseTransactionContext,
+  InMemoryUnitOfWork,
+} from "./unit-of-work";
+
+/**
+ * QUICK START:
+ *
+ * 1. For Testing:
+ * ```ts
+ * import { InMemoryRepository } from 'rich-domain';
+ *
+ * const userRepo = new InMemoryRepository<User>();
+ * await userRepo.save(user);
+ * const found = await userRepo.findById(user.id);
+ * ```
+ *
+ * 2. For Production (Prisma, TypeORM, etc):
+ * - Extend BaseRepository
+ * - Implement abstract methods
+ * - Create a Mapper
+ * - See examples/ folder for reference
+ *
+ * 3. With Criteria:
+ * ```ts
+ * const result = await userRepo.find(
+ *   Criteria.create<User>()
+ *     .whereEquals('status', 'active')
+ *     .orderByDesc('createdAt')
+ *     .paginate(1, 10)
+ * );
+ * ```
+ *
+ * 4. With Unit of Work:
+ * ```ts
+ * await uow.transaction(async (ctx) => {
+ *   const userRepo = uow.getRepository(UserRepository);
+ *   await userRepo.save(user);
+ * });
+ * ```
+ */

package/src/repository/mapper.ts

@@ -0,0 +1,74 @@
+// ============================================================================
+// Mapper - Domain ↔ Persistence
+// ============================================================================
+
+import type { Aggregate } from "../entity";
+
+/**
+ * Mapper interface for converting between Domain and Persistence models
+ *
+ * @template TDomain - Domain aggregate/entity
+ * @template TPersistence - Database model (Prisma, TypeORM, etc.)
+ *
+ * @example
+ * ```ts
+ * class UserMapper implements IMapper<User, PrismaUser> {
+ *   toDomain(persistence: PrismaUser): User {
+ *     return new User({
+ *       id: Id.from(persistence.id),
+ *       name: persistence.name,
+ *       email: persistence.email,
+ *     });
+ *   }
+ *
+ *   toPersistence(domain: User): PrismaUser {
+ *     return {
+ *       id: domain.id.value,
+ *       name: domain.props.name,
+ *       email: domain.props.email,
+ *     };
+ *   }
+ * }
+ * ```
+ */
+export interface IMapper<TDomain extends Aggregate<any>, TPersistence = any> {
+  /**
+   * Convert from persistence model to domain aggregate
+   */
+  toDomain(persistence: TPersistence): TDomain;
+
+  /**
+   * Convert from domain aggregate to persistence model
+   */
+  toPersistence(domain: TDomain): TPersistence;
+
+  /**
+   * Convert array of persistence models to domain aggregates
+   */
+  toDomainList?(persistence: TPersistence[]): TDomain[];
+
+  /**
+   * Convert array of domain aggregates to persistence models
+   */
+  toPersistenceList?(domain: TDomain[]): TPersistence[];
+}
+
+/**
+ * Base mapper with default array implementations
+ */
+export abstract class BaseMapper<
+  TDomain extends Aggregate<any>,
+  TPersistence = any
+> implements IMapper<TDomain, TPersistence>
+{
+  abstract toDomain(persistence: TPersistence): TDomain;
+  abstract toPersistence(domain: TDomain): TPersistence;
+
+  toDomainList(persistence: TPersistence[]): TDomain[] {
+    return persistence.map((p) => this.toDomain(p));
+  }
+
+  toPersistenceList(domain: TDomain[]): TPersistence[] {
+    return domain.map((d) => this.toPersistence(d));
+  }
+}