@woltz/rich-domain 1.2.0 → 1.2.1

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,6 +13,8 @@ import {
 import { DomainEventBus } from "./domain-event-bus";
 import { DEFAULT_VALIDATION_CONFIG } from "./constants";
 import { DomainError } from "./exceptions";
+import { HistoryTracker } from "./history-tracker";
+import { AggregateChanges } from "./aggregate-changes";
 
 // Helper to get static properties from constructor
 function getStaticProperty<T>(
@@ -30,7 +26,7 @@ function getStaticProperty<T>(
 
 export abstract class BaseEntity<T extends BaseProps> {
   private _props: T;
-  private proxy: DeepProxy;
+  private tracker: HistoryTracker;
   private proxiedProps: T;
   private snapshot: T | null = null;
   private validationConfig: Required<ValidationConfig>;
@@ -74,8 +70,16 @@ export abstract class BaseEntity<T extends BaseProps> {
     }
 
     this._props = finalProps;
-    this.proxy = new DeepProxy(this._props);
-    this.proxiedProps = this.proxy.createProxy();
+
+    // Initialize tracker and proxy
+    this.tracker = new HistoryTracker(this._props, this.constructor.name);
+
+    // Setup validation on update BEFORE creating proxy
+    if (this.validationConfig.onUpdate) {
+      this.setupUpdateValidation();
+    }
+
+    this.proxiedProps = this.tracker.createProxy();
 
     // Execute rules (custom validations)
     if (hooks?.rules) {
@@ -87,15 +91,14 @@ export abstract class BaseEntity<T extends BaseProps> {
       hooks.onCreate(this as any);
     }
 
-    // Setup update validation
-    if (this.entitySchema && this.validationConfig.onUpdate) {
-      this.setupUpdateValidation();
-    }
-
     // Take initial snapshot for onBeforeUpdate
     this.takeSnapshot();
   }
 
+  // ============================================================================
+  // Validation
+  // ============================================================================
+
   private validateProps(props: T): void {
     if (!this.entitySchema) return;
 
@@ -119,7 +122,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 +130,105 @@ 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 HistoryTracker'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) => {
+      // Temporarily apply the change to validate
+      const originalValue = self._props[path as keyof T];
+      (self._props as any)[path] = newValue;
+
+      try {
+        // Check onBeforeUpdate hook
+        if (self.entityHooks?.onBeforeUpdate && self.snapshot) {
+          const shouldContinue = self.entityHooks.onBeforeUpdate(
+            self as any,
+            self.snapshot
+          );
+          if (!shouldContinue) {
+            // Revert change
+            (self._props as any)[path] = originalValue;
+            return false;
+          }
         }
-      }
 
-      // Validate with schema
-      if (self.entitySchema) {
-        const result = self.entitySchema["~standard"].validate(self._props);
+        // 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."
-          );
-          return;
-        }
+          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 (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);
+            // Revert change before throwing
+            (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);
+        // Execute rules after schema validation
+        if (self.entityHooks?.rules) {
+          try {
+            self.entityHooks.rules(self as any);
+          } catch (error) {
+            // Revert change before throwing
+            (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();
-    };
+        // Revert for now - the actual set will happen in the proxy
+        (self._props as any)[path] = originalValue;
 
-    // Subscribe to all changes
-    this.proxy.subscribe("*", validateOnChange);
+        // Update snapshot after successful validation
+        // Note: snapshot is updated after the change is applied
+        return true;
+      } catch (error) {
+        // Revert on any error
+        (self._props as any)[path] = originalValue;
+        throw error;
+      }
+    });
   }
 
   private takeSnapshot(): void {
@@ -220,36 +237,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 +268,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,10 +278,13 @@ export abstract class BaseEntity<T extends BaseProps> {
       return cloned;
     }
 
-    // For other object types (custom classes), just keep the reference
     return obj;
   }
 
+  // ============================================================================
+  // Identity
+  // ============================================================================
+
   get id(): Id {
     return this._props.id;
   }
@@ -284,27 +295,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);
     }
@@ -312,6 +316,10 @@ export abstract class BaseEntity<T extends BaseProps> {
     return false;
   }
 
+  // ============================================================================
+  // Props Access
+  // ============================================================================
+
   public get props(): T {
     return this.proxiedProps;
   }
@@ -330,23 +338,47 @@ 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);
-      }
-    });
+  // ============================================================================
+  // Change Tracking
+  // ============================================================================
+
+  /**
+   * 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();
   }
 
+  // ============================================================================
+  // Domain Events
+  // ============================================================================
+
   /**
    * Add a domain event to this entity
    */
@@ -354,8 +386,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();
   }
 
   /**
@@ -379,6 +415,10 @@ export abstract class BaseEntity<T extends BaseProps> {
     return this.domainEvents.length > 0;
   }
 
+  // ============================================================================
+  // Serialization
+  // ============================================================================
+
   toJson(): DeepJsonResult<T> {
     return this.deepToJson(this._props) as DeepJsonResult<T>;
   }

package/src/criteria.ts

@@ -13,6 +13,7 @@ import {
   PathValue,
   Search,
   TypedFilter,
+  TypedOrder,
 } from "./types";
 import {
   isValidOperatorForType,
@@ -278,7 +279,7 @@ export class Criteria<T = any> {
   static fromObject<T>(
     obj: {
       filters?: TypedFilter<T>[];
-      orders?: Order[];
+      orders?: TypedOrder<T>[];
       pagination?: Pagination;
       search?: { fields: FieldPath<T>[]; value: string };
     },

package/src/crypto.ts

@@ -0,0 +1,31 @@
+const customCrypto = {
+  randomUUID: () => {
+    if (
+      typeof globalThis !== "undefined" &&
+      globalThis?.crypto &&
+      typeof globalThis.crypto.randomUUID === "function"
+    ) {
+      return globalThis.crypto.randomUUID();
+    }
+
+    const hexChars = "0123456789abcdef";
+    let uuid = "";
+
+    for (let i = 0; i < 36; i++) {
+      if (i === 8 || i === 13 || i === 18 || i === 23) {
+        uuid += "-";
+      } else if (i === 14) {
+        uuid += "4";
+      } else if (i === 19) {
+        uuid += hexChars.charAt(Math.floor(Math.random() * 4) + 8);
+      } else {
+        uuid += hexChars.charAt(Math.floor(Math.random() * 16));
+      }
+    }
+
+    return uuid;
+  },
+};
+
+export const UUID = customCrypto.randomUUID;
+export default UUID;

package/src/entity-changes.ts

@@ -0,0 +1,151 @@
+// ============================================================================
+// Entity Changes
+// Changes filtered by entity type
+// ============================================================================
+
+import {
+  Operation,
+  CreateOperation,
+  UpdateOperation,
+  DeleteOperation,
+} from "./types/change-tracker";
+
+/**
+ * Represents the changes filtered for a specific entity.
+ *
+ * @example
+ * ```typescript
+ * const changes = user.getChanges();
+ * const postChanges = changes.for('Post');
+ *
+ * if (postChanges.hasCreates()) {
+ *   console.log('Created posts:', postChanges.creates);
+ * }
+ *
+ * if (postChanges.hasUpdates()) {
+ *   postChanges.updates.forEach(({ entity, changed }) => {
+ *     console.log(`Post ${entity.id} has changed:`, changed);
+ *   });
+ * }
+ * ```
+ */
+export class EntityChanges<T = any> {
+  constructor(private readonly operations: Operation<T>[]) {}
+
+  /**
+   * Returns all created entities
+   */
+  get creates(): T[] {
+    return this.operations
+      .filter((op): op is CreateOperation<T> => op.type === "create")
+      .map((op) => op.data);
+  }
+
+  /**
+   * Returns all updated entities with their changed fields
+   */
+  get updates(): Array<{ entity: T; changed: Record<string, any> }> {
+    return this.operations
+      .filter((op): op is UpdateOperation<T> => op.type === "update")
+      .map((op) => ({
+        entity: op.data,
+        changed: op.changedFields,
+      }));
+  }
+
+  /**
+   * Returns all deleted entities
+   */
+  get deletes(): T[] {
+    return this.operations
+      .filter((op): op is DeleteOperation<T> => op.type === "delete")
+      .map((op) => op.data);
+  }
+
+  /**
+   * Returns the IDs of the created entities
+   */
+  get createIds(): string[] {
+    return this.operations
+      .filter((op): op is CreateOperation<T> => op.type === "create")
+      .map((op) => this.extractId(op.data))
+      .filter((id): id is string => id !== undefined);
+  }
+
+  /**
+   * Returns the IDs of the updated entities
+   */
+  get updateIds(): string[] {
+    return this.operations
+      .filter((op): op is UpdateOperation<T> => op.type === "update")
+      .map((op) => op.id);
+  }
+
+  /**
+   * Returns the IDs of the deleted entities
+   */
+  get deleteIds(): string[] {
+    return this.operations
+      .filter((op): op is DeleteOperation<T> => op.type === "delete")
+      .map((op) => op.id);
+  }
+
+  /**
+   * Checks if there are any creates
+   */
+  hasCreates(): boolean {
+    return this.creates.length > 0;
+  }
+
+  /**
+   * Checks if there are any updates
+   */
+  hasUpdates(): boolean {
+    return this.updates.length > 0;
+  }
+
+  /**
+   * Checks if there are any deletes
+   */
+  hasDeletes(): boolean {
+    return this.deletes.length > 0;
+  }
+
+  /**
+   * Checks if there is any change
+   */
+  hasChanges(): boolean {
+    return this.operations.length > 0;
+  }
+
+  /**
+   * Checks if it is empty (no changes)
+   */
+  isEmpty(): boolean {
+    return this.operations.length === 0;
+  }
+
+  /**
+   * Returns the total number of operations
+   */
+  get count(): number {
+    return this.operations.length;
+  }
+
+  /**
+   * Returns the raw operations (for advanced use cases)
+   */
+  get rawOperations(): Operation<T>[] {
+    return [...this.operations];
+  }
+
+  /**
+   * Extracts the ID from an entity
+   */
+  private extractId(entity: any): string | undefined {
+    if (!entity) return undefined;
+    if (entity.id?.value) return entity.id.value;
+    if (typeof entity.id === "string") return entity.id;
+    return undefined;
+  }
+}