@woltz/rich-domain 1.2.0 → 1.2.2

package/src/base-entity.ts

@@ -1,14 +1,8 @@
-// ============================================================================
-// Base Entity Class with Standard Schema Validation
-// ============================================================================
-
 import { Id } from "./id";
-import { DeepProxy } from "./deep-proxy";
 import { ValidationError } from "./validation-error";
 import { IDomainEvent } from ".";
 import {
   BaseProps,
-  SubscriptionConfig,
   HistoryEntry,
   DeepJsonResult,
   EntityHooks,
@@ -19,8 +13,9 @@ import {
 import { DomainEventBus } from "./domain-event-bus";
 import { DEFAULT_VALIDATION_CONFIG } from "./constants";
 import { DomainError } from "./exceptions";
+import { ChangeTracker } from "./change-tracker";
+import { AggregateChanges } from "./aggregate-changes";
 
-// Helper to get static properties from constructor
 function getStaticProperty<T>(
   instance: any,
   propertyName: string
@@ -30,7 +25,7 @@ function getStaticProperty<T>(
 
 export abstract class BaseEntity<T extends BaseProps> {
   private _props: T;
-  private proxy: DeepProxy;
+  private tracker: ChangeTracker;
   private proxiedProps: T;
   private snapshot: T | null = null;
   private validationConfig: Required<ValidationConfig>;
@@ -38,12 +33,10 @@ export abstract class BaseEntity<T extends BaseProps> {
   private entitySchema?: StandardSchema<T>;
   private domainEvents: IDomainEvent[] = [];
 
-  // Static properties that subclasses can override
   protected static validation?: EntityValidation<any>;
   protected static hooks?: EntityHooks<any, any>;
 
   constructor(props: Omit<T, "id"> & { id?: Id }) {
-    // Get static configuration from subclass
     const validation = getStaticProperty<EntityValidation<T>>(
       this,
       "validation"
@@ -63,36 +56,31 @@ export abstract class BaseEntity<T extends BaseProps> {
 
     let finalProps = { ...props } as T;
 
-    // Generate ID if not provided
     if (!finalProps.id) {
       finalProps.id = new Id();
     }
 
-    // Validate schema on creation
     if (this.entitySchema && this.validationConfig.onCreate) {
       this.validateProps(finalProps);
     }
 
     this._props = finalProps;
-    this.proxy = new DeepProxy(this._props);
-    this.proxiedProps = this.proxy.createProxy();
+    this.tracker = new ChangeTracker(this._props, this.constructor.name);
+
+    if (this.validationConfig.onUpdate) {
+      this.setupUpdateValidation();
+    }
+
+    this.proxiedProps = this.tracker.createProxy();
 
-    // Execute rules (custom validations)
     if (hooks?.rules) {
       hooks.rules(this as any);
     }
 
-    // Hook onCreate
     if (hooks?.onCreate) {
       hooks.onCreate(this as any);
     }
 
-    // Setup update validation
-    if (this.entitySchema && this.validationConfig.onUpdate) {
-      this.setupUpdateValidation();
-    }
-
-    // Take initial snapshot for onBeforeUpdate
     this.takeSnapshot();
   }
 
@@ -119,7 +107,6 @@ export abstract class BaseEntity<T extends BaseProps> {
         throw validationError;
       }
 
-      // If not throwing, store error for later retrieval
       (this as any)._validationError = validationError;
     }
   }
@@ -128,90 +115,93 @@ export abstract class BaseEntity<T extends BaseProps> {
     if (pathSegment === null || pathSegment === undefined) {
       return "";
     }
-    // Handle PropertyKey (string | number | symbol)
     if (typeof pathSegment === "string" || typeof pathSegment === "number") {
       return String(pathSegment);
     }
     if (typeof pathSegment === "symbol") {
       return pathSegment.toString();
     }
-    // Handle object with 'key' property (Zod's PathSegment)
     if (typeof pathSegment === "object" && "key" in pathSegment) {
       return String((pathSegment as { key: unknown }).key);
     }
-    // Fallback
     return String(pathSegment);
   }
 
+  /**
+   * Setup validation that runs on every property change.
+   * Uses the ChangeTracker's onChangeValidator callback.
+   */
   private setupUpdateValidation(): void {
     const self = this;
 
-    const validateOnChange = () => {
-      // Check onBeforeUpdate hook
-      if (self.entityHooks?.onBeforeUpdate && self.snapshot) {
-        const shouldContinue = self.entityHooks.onBeforeUpdate(
-          self as any,
-          self.snapshot
-        );
-        if (!shouldContinue) {
-          // Revert changes
-          Object.assign(self._props, self.snapshot);
-          return;
-        }
-      }
+    this.tracker.setOnChangeValidator((path, oldValue, newValue) => {
+      const originalValue = self._props[path as keyof T];
+      (self._props as any)[path] = newValue;
 
-      // Validate with schema
-      if (self.entitySchema) {
-        const result = self.entitySchema["~standard"].validate(self._props);
-
-        if (result instanceof Promise) {
-          console.warn(
-            "Async validation on update not supported. Consider using sync validation."
+      try {
+        if (self.entityHooks?.onBeforeUpdate && self.snapshot) {
+          const shouldContinue = self.entityHooks.onBeforeUpdate(
+            self as any,
+            self.snapshot
           );
-          return;
+          if (!shouldContinue) {
+            (self._props as any)[path] = originalValue;
+            return false;
+          }
         }
 
-        if (result.issues && result.issues.length > 0) {
-          const validationError = new ValidationError(
-            result.issues.map((issue) => ({
-              path: issue.path?.map((p) => self.extractPathKey(p)) || [],
-              message: issue.message,
-            }))
-          );
+        if (self.entitySchema) {
+          const result = self.entitySchema["~standard"].validate(self._props);
+
+          if (result instanceof Promise) {
+            console.warn(
+              "Async validation on update not supported. Consider using sync validation."
+            );
+            (self._props as any)[path] = originalValue;
+            return true;
+          }
+
+          if (result.issues && result.issues.length > 0) {
+            const validationError = new ValidationError(
+              result.issues.map((issue) => ({
+                path: issue.path?.map((p) => self.extractPathKey(p)) || [],
+                message: issue.message,
+              }))
+            );
 
-          if (self.validationConfig.throwOnError) {
-            // Revert changes before throwing
-            if (self.snapshot) {
-              Object.assign(self._props, self.snapshot);
+            (self._props as any)[path] = originalValue;
+
+            if (self.validationConfig.throwOnError) {
+              throw validationError;
             }
-            throw validationError;
+
+            console.error("Validation failed on update:", validationError);
+            return false;
           }
-          console.error("Validation failed on update:", validationError);
         }
-      }
 
-      // Execute rules after schema validation
-      if (self.entityHooks?.rules) {
-        try {
-          self.entityHooks.rules(self as any);
-        } catch (error) {
-          if (self.validationConfig.throwOnError) {
-            // Revert changes before throwing
-            if (self.snapshot) {
-              Object.assign(self._props, self.snapshot);
+        if (self.entityHooks?.rules) {
+          try {
+            self.entityHooks.rules(self as any);
+          } catch (error) {
+            (self._props as any)[path] = originalValue;
+
+            if (self.validationConfig.throwOnError) {
+              throw error;
             }
-            throw error;
+
+            console.error("Rules validation failed on update:", error);
+            return false;
           }
-          console.error("Rules validation failed on update:", error);
         }
-      }
-
-      // Update snapshot after successful validation
-      self.takeSnapshot();
-    };
 
-    // Subscribe to all changes
-    this.proxy.subscribe("*", validateOnChange);
+        (self._props as any)[path] = originalValue;
+        return true;
+      } catch (error) {
+        (self._props as any)[path] = originalValue;
+        throw error;
+      }
+    });
   }
 
   private takeSnapshot(): void {
@@ -220,36 +210,28 @@ export abstract class BaseEntity<T extends BaseProps> {
 
   private deepCloneProps(obj: any, seen: WeakSet<object> = new WeakSet()): any {
     if (obj === null || obj === undefined) return obj;
-
-    // Primitives
     if (typeof obj !== "object") return obj;
-
-    // Special cases - don't clone these, just return the reference
     if (obj instanceof Id) return obj;
     if (obj instanceof Date) return new Date(obj.getTime());
 
-    // Check for circular references
     if (seen.has(obj)) {
-      return obj; // Return reference to avoid infinite loop
+      return obj;
     }
 
-    // Handle BaseEntity instances - just keep the reference
     if (obj instanceof BaseEntity) {
       return obj;
     }
 
-    // Handle ValueObject instances - just keep the reference (they're immutable)
     if (
       obj.constructor &&
       obj.constructor.name !== "Object" &&
       obj.constructor.name !== "Array"
     ) {
-      // Check if it has toJson method (likely a ValueObject or similar)
       if (
         typeof obj.toJson === "function" &&
         typeof obj.equals === "function"
       ) {
-        return obj; // Keep reference for ValueObjects
+        return obj;
       }
     }
 
@@ -259,7 +241,6 @@ export abstract class BaseEntity<T extends BaseProps> {
       return obj.map((item) => this.deepCloneProps(item, seen));
     }
 
-    // Plain objects only
     if (obj.constructor === Object) {
       const cloned: any = {};
       for (const key in obj) {
@@ -270,7 +251,6 @@ export abstract class BaseEntity<T extends BaseProps> {
       return cloned;
     }
 
-    // For other object types (custom classes), just keep the reference
     return obj;
   }
 
@@ -284,27 +264,20 @@ export abstract class BaseEntity<T extends BaseProps> {
 
   /**
    * Check equality with another entity by comparing IDs
-   * Entities are equal if they have the same ID, regardless of other properties
-   *
-   * @param other - Another entity or an ID to compare with
-   * @returns true if entities have the same ID
    */
   equals(other: BaseEntity<T> | Id | string): boolean {
     if (!other) {
       return false;
     }
 
-    // Compare with another entity
     if (other instanceof BaseEntity) {
       return this.id.equals(other.id);
     }
 
-    // Compare with an ID
     if (other instanceof Id) {
       return this.id.equals(other);
     }
 
-    // Compare with a string ID
     if (typeof other === "string") {
       return this.id.equals(other);
     }
@@ -330,21 +303,37 @@ export abstract class BaseEntity<T extends BaseProps> {
     return (this as any)._validationError;
   }
 
-  subscribe(config: SubscriptionConfig<T>): void {
-    Object.keys(config).forEach((key) => {
-      const sub = config[key as keyof T];
-      if (sub && "onChange" in sub) {
-        this.proxy.subscribe(key, sub.onChange);
-      }
-    });
+  /**
+   * Returns all detected changes as AggregateChanges.
+   *
+   * @example
+   * ```typescript
+   * const changes = user.getChanges();
+   * const batch = changes.toBatchOperations();
+   *
+   * for (const del of batch.deletes) { ... }
+   * for (const create of batch.creates) { ... }
+   * for (const upd of batch.updates) { ... }
+   * ```
+   */
+  getChanges<TEntityMap = Record<string, any>>(): AggregateChanges<TEntityMap> {
+    return this.tracker.getChanges<TEntityMap>();
   }
 
+  /**
+   * Returns the change history (for debugging).
+   */
   getHistory(): HistoryEntry[] {
-    return this.proxy.getHistory();
+    return this.tracker.getHistory();
   }
 
-  clearHistory(): void {
-    this.proxy.clearHistory();
+  /**
+   * Clears history and marks entity as "clean".
+   * Call this after successfully persisting to the database.
+   */
+  markAsClean(): void {
+    this.tracker.markAsClean();
+    this.takeSnapshot();
   }
 
   /**
@@ -354,8 +343,12 @@ export abstract class BaseEntity<T extends BaseProps> {
     this.domainEvents.push(event);
   }
 
-  public async dispatchAll(bus: DomainEventBus) {
+  /**
+   * Dispatch all events through the event bus
+   */
+  public async dispatchAll(bus: DomainEventBus): Promise<void> {
     await bus.publishAll(this.getUncommittedEvents());
+    this.clearEvents();
   }
 
   /**