@woltz/rich-domain 1.2.0 → 1.2.2

package/src/mapper.ts

@@ -1,3 +1,6 @@
 export abstract class Mapper<Input, Output> {
-  public abstract build(input: Input, ...args: unknown[]): Output;
+  public abstract build(
+    input: Input,
+    ...args: unknown[]
+  ): Output | Promise<Output>;
 }

package/src/paginated-result.ts

@@ -2,10 +2,6 @@ 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
@@ -21,10 +17,6 @@ export type PaginatedJsonResult<T> = {
   meta: PaginationMeta;
 };
 
-// ============================================================================
-// PaginatedResult Class
-// ============================================================================
-
 export class PaginatedResult<T> {
   constructor(
     public readonly data: T[],
@@ -78,13 +70,11 @@ export class PaginatedResult<T> {
       total = result.length;
     }
 
-    // Apply filters
     for (const filter of criteria.getFilters()) {
       result = result.filter((item) => applyFilter(item, filter));
       total = result.length;
     }
 
-    // Apply ordering
     for (const order of criteria.getOrders().reverse()) {
       result.sort((a, b) => {
         const aVal = getNestedValue(a, order.field);
@@ -98,7 +88,6 @@ export class PaginatedResult<T> {
       });
     }
 
-    // Apply pagination
     const pagination = criteria.getPagination();
     if (pagination && !criteria.hasSearch()) {
       result = result.slice(
@@ -108,7 +97,6 @@ export class PaginatedResult<T> {
       return PaginatedResult.create(result, pagination, total);
     }
 
-    // No pagination - return all with default meta
     return PaginatedResult.create(
       result,
       { page: 1, limit: result.length, offset: 0 },
@@ -140,20 +128,16 @@ export class PaginatedResult<T> {
   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) {
@@ -164,7 +148,6 @@ export class PaginatedResult<T> {
       return result;
     }
 
-    // Primitives
     return obj;
   }
 
@@ -190,10 +173,6 @@ export class PaginatedResult<T> {
   }
 }
 
-// ============================================================================
-// Helper Functions (moved from criteria.ts)
-// ============================================================================
-
 function applyFilter<T>(item: T, filter: Filter): boolean {
   const value = getNestedValue(item, filter.field);
 

package/src/repository/base-repository.ts

@@ -1,57 +1,26 @@
-// ============================================================================
-// Base Repository - Abstract implementation with common logic
-// ============================================================================
-
 import type { Aggregate } from "../entity";
 import type { Criteria } from "../criteria";
 import { PaginatedResult } from "../paginated-result";
 import { Mapper } 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 ReadRepository<Agg extends Aggregate<any>> {
-  abstract find(criteria: Criteria<Agg>): Promise<PaginatedResult<Agg>>;
+  abstract find(criteria?: Criteria<Agg>): Promise<PaginatedResult<Agg>>;
   abstract findById(id: string): Promise<Agg | null>;
-  abstract count(criteria: Criteria<Agg>): Promise<number>;
+  abstract count(criteria?: Criteria<Agg>): Promise<number>;
   abstract exists(id: string): Promise<boolean>;
 }
 
 export abstract class WriteRepository<Agg extends Aggregate<any>> {
-  abstract create(entity: Agg): Promise<void>;
-  abstract update(entity: Agg): Promise<void>;
+  abstract save(entity: Agg): Promise<void>;
   abstract delete(entity: Agg): Promise<void>;
 }
 
 export abstract class WriteAndRead<Agg extends Aggregate<any>> {
-  abstract find(criteria: Criteria<Agg>): Promise<PaginatedResult<Agg>>;
+  abstract find(criteria?: Criteria<Agg>): Promise<PaginatedResult<Agg>>;
   abstract findById(id: string): Promise<Agg | null>;
-  abstract create(entity: Agg): Promise<void>;
-  abstract update(entity: Agg): Promise<void>;
+  abstract save(entity: Agg): Promise<void>;
   abstract delete(entity: Agg): Promise<void>;
-  abstract count(criteria: Criteria<Agg>): Promise<number>;
+  abstract count(criteria?: Criteria<Agg>): Promise<number>;
   abstract exists(id: string): Promise<boolean>;
 }
 
@@ -60,5 +29,5 @@ export abstract class Repository<
 > extends WriteAndRead<TDomain> {
   protected abstract readonly mapperToDomain: Mapper<unknown, TDomain>;
   protected abstract readonly mapperToPersistence: Mapper<TDomain, unknown>;
-  abstract get model(): any;
+  protected abstract get model(): any;
 }

package/src/repository/index.ts

@@ -1,12 +1,3 @@
-// ============================================================================
-// Repository Module - Clean exports
-// ============================================================================
-
-// Mapper
 export { Mapper } from "../mapper";
-
-// Base implementations
 export * from "./base-repository";
-
-// Unit of Work
 export { UnitOfWork, BaseTransactionContext } from "./unit-of-work";

package/src/repository/unit-of-work.ts

@@ -1,37 +1,8 @@
-// ============================================================================
-// Unit of Work - Simple transaction management
-// ============================================================================
-
 import type { IUnitOfWork, TransactionContext } from "../types";
 
 /**
  * Abstract Unit of Work
  * Provides transaction management across multiple repositories
- *
- * @example
- * ```ts
- * // Using transaction helper (recommended)
- * await uow.transaction(async (ctx) => {
- *   const userRepo = uow.getRepository(UserRepository);
- *   const orderRepo = uow.getRepository(OrderRepository);
- *
- *   await userRepo.save(user);
- *   await orderRepo.save(order);
- *
- *   // Auto-commits on success, rolls back on error
- * });
- *
- * // Manual control
- * const ctx = await uow.begin();
- * try {
- *   await userRepo.save(user);
- *   await orderRepo.save(order);
- *   await ctx.commit();
- * } catch (error) {
- *   await ctx.rollback();
- *   throw error;
- * }
- * ```
  */
 export abstract class UnitOfWork implements IUnitOfWork {
   protected currentContext: TransactionContext | null = null;

package/src/types/change-tracker.ts

@@ -0,0 +1,233 @@
+import { Entity } from "../entity";
+import { ValueObject } from "../value-object";
+
+/**
+ * Base operation with common information.
+ */
+export interface BaseOperation {
+  /** Entity name in the domain (e.g., 'User', 'Post', 'Comment') */
+  entity: string;
+  /** Depth in the aggregate tree (0 = root, 1 = direct children, etc.) */
+  depth: number;
+}
+
+/**
+ * Create operation.
+ */
+export interface CreateOperation<T = any> extends BaseOperation {
+  type: "create";
+  /** Entity data to be created */
+  data: T;
+  /** Parent ID (for FK) */
+  parentId?: string;
+  /** Parent entity name */
+  parentEntity?: string;
+}
+
+/**
+ * Update operation.
+ */
+export interface UpdateOperation<T = any> extends BaseOperation {
+  type: "update";
+  /** Entity ID */
+  id: string;
+  /** Current entity instance */
+  data: T;
+  /** Only fields that have changed */
+  changedFields: Record<string, any>;
+}
+
+/**
+ * Delete operation.
+ */
+export interface DeleteOperation<T = any> extends BaseOperation {
+  type: "delete";
+  /** Entity ID to be deleted */
+  id: string;
+  /** Entity data (for reference) */
+  data: T;
+}
+
+/**
+ * Union of all possible operations.
+ */
+export type Operation<T = any> =
+  | CreateOperation<T>
+  | UpdateOperation<T>
+  | DeleteOperation<T>;
+
+/**
+ * Item for batch creation.
+ */
+export interface BatchCreateItem<T = any> {
+  /** Entity data */
+  data: T;
+  /** Parent ID (for FK) */
+  parentId?: string;
+}
+
+/**
+ * Item for batch update.
+ */
+export interface BatchUpdateItem {
+  /** Entity ID */
+  id: string;
+  /** Fields that have changed */
+  changedFields: Record<string, any>;
+}
+
+/**
+ * Grouped and ordered operations for batch execution.
+ */
+export interface BatchOperations {
+  /**
+   * Deletes grouped by entity, ordered by depth descending (leaf → root).
+   */
+  deletes: Array<{
+    entity: string;
+    depth: number;
+    ids: string[];
+  }>;
+
+  /**
+   * Creates grouped by entity, ordered by depth ascending (root → leaf).
+   */
+  creates: Array<{
+    entity: string;
+    depth: number;
+    items: BatchCreateItem[];
+  }>;
+
+  /**
+   * Updates grouped by entity.
+   */
+  updates: Array<{
+    entity: string;
+    items: BatchUpdateItem[];
+  }>;
+}
+
+/**
+ * Changes detected in a collection (1:N).
+ */
+export interface CollectionChanges<T = any> {
+  /** Created items */
+  created: T[];
+  /** Updated items with their changes */
+  updated: Array<{
+    entity: T;
+    changes: Record<string, { from: any; to: any }>;
+  }>;
+  /** Deleted items */
+  deleted: T[];
+}
+
+/**
+ * Possible states for a 1:1 relationship.
+ */
+export type EntityChangeState =
+  | "created" // null → Entity
+  | "updated" // Entity(id:1) → Entity(id:1) with changes
+  | "deleted" // Entity → null
+  | "replaced" // Entity(id:1) → Entity(id:2)
+  | "unchanged"; // No changes
+
+/**
+ * Change in a 1:1 entity relationship.
+ */
+export interface EntityChange<T = any> {
+  /** State of the change */
+  state: EntityChangeState;
+  /** Current entity (null if deleted) */
+  current: T | null;
+  /** Previous entity (null if created) */
+  previous: T | null;
+  /** Field changes (if state === 'updated') */
+  changes?: Record<string, { from: any; to: any }>;
+}
+
+/**
+ * Change in a primitive field.
+ */
+export interface FieldChange<T = any> {
+  from: T;
+  to: T;
+}
+
+/**
+ * Extracts the props type from an Entity or ValueObject.
+ */
+export type ExtractProps<T> = T extends Entity<infer P>
+  ? P
+  : T extends ValueObject<infer P>
+  ? P
+  : never;
+
+/**
+ * Keys of primitive properties (not Entity, ValueObject or Array).
+ */
+export type PrimitiveKeys<T> = {
+  [K in keyof T]: T[K] extends
+    | Entity<any>
+    | ValueObject<any>
+    | Array<any>
+    | undefined
+    ? never
+    : K;
+}[keyof T];
+
+/**
+ * Keys of collections (arrays).
+ */
+export type CollectionKeys<T> = {
+  [K in keyof T]: T[K] extends Array<any> ? K : never;
+}[keyof T];
+
+/**
+ * Keys of single entities (1:1).
+ */
+export type SingleEntityKeys<T> = {
+  [K in keyof T]: T[K] extends Entity<any> | ValueObject<any> | null | undefined
+    ? T[K] extends Array<any>
+      ? never
+      : K
+    : never;
+}[keyof T];
+
+/**
+ * Change history entry.
+ */
+export interface HistoryEntry {
+  path: string;
+  previousValue: any;
+  currentValue: any;
+  timestamp: number;
+}
+
+/**
+ * Metadata from a tracked entity/VO.
+ */
+export interface TrackedEntityMetadata {
+  /** Entity name */
+  entityName: string;
+  /** Depth in the tree */
+  depth: number;
+  /** Parent ID */
+  parentId?: string;
+  /** Parent entity name */
+  parentEntity?: string;
+  /** Path in the object (e.g., 'posts[0].comments[1]') */
+  path: string;
+}
+
+export interface TrackedItem {
+  entity: any;
+  metadata: TrackedEntityMetadata;
+  originalState: any;
+}
+
+export interface ArrayState {
+  cloned: any[];
+  original: any[];
+  metadata: TrackedEntityMetadata;
+}

package/src/types/criteria.ts

@@ -118,6 +118,11 @@ export interface Order {
   direction: OrderDirection;
 }
 
+export type TypedOrder<T> = {
+  field: FieldPath<T>;
+  direction: OrderDirection;
+};
+
 export interface Pagination {
   page: number;
   limit: number;
@@ -153,5 +158,5 @@ export type FieldPath<T> = T extends Primitive
         ? U extends Primitive
           ? K
           : K | `${K}.${FieldPath<U>}`
-        : K | `${K}.${FieldPath<NonNullable<T[K]>>}`;
+        : `${K}.${FieldPath<NonNullable<T[K]>>}`;
     }[ExcludeBuiltInKeys<T> & string];

package/src/types/domain.ts

@@ -1,9 +1,6 @@
-import { ValidationConfig } from "..";
 import { Id } from "../id";
 import { StandardSchema } from "./standard-schema";
 
-export type EntityId = string | number;
-
 export interface BaseProps {
   id: Id;
 }
@@ -22,15 +19,14 @@ export interface VOHooks<T, E> {
   rules?: (entity: E) => void;
 }
 
-// Specialized hooks for entities (with BaseProps)
 export interface EntityHooks<T extends BaseProps, E> {
   onBeforeUpdate?: (entity: E, snapshot: T) => boolean;
   onCreate?: (entity: E) => void;
   rules?: (entity: E) => void;
 }
 
-export interface EntityConstructor<T extends BaseProps, E> {
-  new (props: T): E;
-  validation?: DomainValidation<T>;
-  hooks?: EntityHooks<T, E>;
+export interface ValidationConfig {
+  onCreate?: boolean;
+  onUpdate?: boolean;
+  throwOnError?: boolean;
 }

package/src/types/index.ts

@@ -1,7 +1,7 @@
 export * from "./criteria";
 export * from "./domain";
-export * from "./history-tracker";
 export * from "./standard-schema";
 export * from "./utils";
 export * from "./unit-of-work";
 export * from "./domain-event";
+export * from "./change-tracker";

package/src/types/utils.ts

@@ -14,16 +14,7 @@ export type DeepJsonResult<T> = {
     : T[K];
 };
 
-export type DeepKeyOf<T, K extends keyof T = keyof T> = K extends string
-  ? T[K] extends Primitive
-    ? K
-    : T[K] extends object
-    ? `${K}` | `${K}.${DeepKeyOf<T[K]>}`
-    : never
-  : never;
-
 export type Primitive = string | number | boolean | Date | null | undefined;
-
 export type UnwrapArray<T> = T extends Array<infer U> ? U : never;
 export type IsArray<T> = T extends Array<any> ? true : false;
 export type NonUndefined<T> = T extends undefined ? never : T;

package/src/utils/criteria-operator-validation.ts

@@ -8,28 +8,71 @@ import {
   StringOperators,
 } from "../types";
 
-export function isValidOperatorForType(
+const FORCE_STRING_OPERATORS = new Set(["contains", "startsWith", "endsWith"]);
+
+export function sanitizeFieldValue(
   value: unknown,
   operator: FilterOperator
-): boolean {
-  // Handle null/undefined
+): unknown {
   if (value === null || value === undefined) {
-    return ["isNull", "isNotNull", "equals", "notEquals"].includes(operator);
+    return value;
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((item) => sanitizeFieldValue(item, operator));
+  }
+
+  if (value instanceof Date) {
+    return value;
+  }
+
+  const stringValue = String(value).trim();
+
+  if (stringValue === "") {
+    return "";
+  }
+
+  if (operator && FORCE_STRING_OPERATORS.has(operator)) {
+    return stringValue;
+  }
+
+  if (stringValue === "true" || stringValue === "false") {
+    return stringValue === "true";
+  }
+
+  const numberValue = Number(stringValue);
+  if (!Number.isNaN(numberValue)) {
+    return numberValue;
+  }
+
+  const dateObj = new Date(stringValue);
+  if (!Number.isNaN(dateObj.getTime())) {
+    return dateObj;
   }
 
-  // Special case: between operator with array [min, max]
-  if (operator === "between" && Array.isArray(value) && value.length === 2) {
-    // Validate based on the type of the first element
-    const elementType = typeof value[0];
-    if (elementType === "number" || value[0] instanceof Date) {
+  return stringValue;
+}
+
+export function isValidOperatorForType(
+  value: unknown,
+  operator: FilterOperator
+): boolean {
+  const sanitizedValue = sanitizeFieldValue(value, operator);
+
+  if (
+    operator === "between" &&
+    Array.isArray(sanitizedValue) &&
+    sanitizedValue.length === 2
+  ) {
+    const elementType = typeof sanitizedValue[0];
+    if (elementType === "number" || sanitizedValue[0] instanceof Date) {
       return true;
     }
     return false;
   }
 
-  const valueType = typeof value;
+  const valueType = typeof sanitizedValue;
 
-  // String operators
   if (valueType === "string") {
     const validOps: StringOperators[] = [
       "equals",
@@ -45,7 +88,6 @@ export function isValidOperatorForType(
     return validOps.includes(operator as StringOperators);
   }
 
-  // Number operators
   if (valueType === "number") {
     const validOps: NumberOperators[] = [
       "equals",
@@ -63,7 +105,6 @@ export function isValidOperatorForType(
     return validOps.includes(operator as NumberOperators);
   }
 
-  // Boolean operators
   if (valueType === "boolean") {
     const validOps: BooleanOperators[] = [
       "equals",
@@ -74,8 +115,7 @@ export function isValidOperatorForType(
     return validOps.includes(operator as BooleanOperators);
   }
 
-  // Date operators
-  if (value instanceof Date) {
+  if (sanitizedValue instanceof Date) {
     const validOps: DateOperators[] = [
       "equals",
       "notEquals",
@@ -92,13 +132,11 @@ export function isValidOperatorForType(
     return validOps.includes(operator as DateOperators);
   }
 
-  // Array operators
-  if (Array.isArray(value)) {
+  if (Array.isArray(sanitizedValue)) {
     const validOps: ArrayOperators[] = ["in", "notIn", "isNull", "isNotNull"];
     return validOps.includes(operator as ArrayOperators);
   }
 
-  // For unknown types, allow all operators
   return true;
 }
 
@@ -168,4 +206,4 @@ export function getValidOperatorsForType(value: unknown): FilterOperator[] {
 
 export function isOperator(value: string): value is FilterOperator {
   return FILTER_OPERATORS.includes(value as FilterOperator);
-}
+}

package/src/validation-error.ts

@@ -1,7 +1,3 @@
-// ============================================================================
-// Validation Error - Domain Validation Errors
-// ============================================================================
-
 export interface ValidationIssue {
   path: string[];
   message: string;
@@ -9,7 +5,7 @@ export interface ValidationIssue {
 
 export class ValidationError extends Error {
   public readonly issues: ValidationIssue[];
-  public readonly __isValidationError = true; // Brand for identification
+  public readonly __isValidationError = true;
 
   constructor(issues: ValidationIssue[], message?: string) {
     const errorMessage =
@@ -18,7 +14,6 @@ export class ValidationError extends Error {
     this.name = 'ValidationError';
     this.issues = issues;
 
-    // Maintain proper stack trace
     if (Error.captureStackTrace) {
       Error.captureStackTrace(this, ValidationError);
     }
@@ -31,7 +26,6 @@ export class ValidationError extends Error {
     if (error instanceof ValidationError) {
       return true;
     }
-    // Check by duck typing for cross-module compatibility
     return (
       error instanceof Error &&
       error.name === 'ValidationError' &&