@woltz/rich-domain 1.1.0 → 1.2.1

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

@@ -0,0 +1,171 @@
+import {
+  ArrayOperators,
+  BooleanOperators,
+  DateOperators,
+  FILTER_OPERATORS,
+  FilterOperator,
+  NumberOperators,
+  StringOperators,
+} from "../types";
+
+export function isValidOperatorForType(
+  value: unknown,
+  operator: FilterOperator
+): boolean {
+  // Handle null/undefined
+  if (value === null || value === undefined) {
+    return ["isNull", "isNotNull", "equals", "notEquals"].includes(operator);
+  }
+
+  // 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 true;
+    }
+    return false;
+  }
+
+  const valueType = typeof value;
+
+  // String operators
+  if (valueType === "string") {
+    const validOps: StringOperators[] = [
+      "equals",
+      "notEquals",
+      "contains",
+      "startsWith",
+      "endsWith",
+      "in",
+      "notIn",
+      "isNull",
+      "isNotNull",
+    ];
+    return validOps.includes(operator as StringOperators);
+  }
+
+  // Number operators
+  if (valueType === "number") {
+    const validOps: NumberOperators[] = [
+      "equals",
+      "notEquals",
+      "greaterThan",
+      "greaterThanOrEqual",
+      "lessThan",
+      "lessThanOrEqual",
+      "in",
+      "notIn",
+      "between",
+      "isNull",
+      "isNotNull",
+    ];
+    return validOps.includes(operator as NumberOperators);
+  }
+
+  // Boolean operators
+  if (valueType === "boolean") {
+    const validOps: BooleanOperators[] = [
+      "equals",
+      "notEquals",
+      "isNull",
+      "isNotNull",
+    ];
+    return validOps.includes(operator as BooleanOperators);
+  }
+
+  // Date operators
+  if (value instanceof Date) {
+    const validOps: DateOperators[] = [
+      "equals",
+      "notEquals",
+      "greaterThan",
+      "greaterThanOrEqual",
+      "lessThan",
+      "lessThanOrEqual",
+      "in",
+      "notIn",
+      "between",
+      "isNull",
+      "isNotNull",
+    ];
+    return validOps.includes(operator as DateOperators);
+  }
+
+  // Array operators
+  if (Array.isArray(value)) {
+    const validOps: ArrayOperators[] = ["in", "notIn", "isNull", "isNotNull"];
+    return validOps.includes(operator as ArrayOperators);
+  }
+
+  // For unknown types, allow all operators
+  return true;
+}
+
+export function getValidOperatorsForType(value: unknown): FilterOperator[] {
+  if (value === null || value === undefined) {
+    return ["isNull", "isNotNull", "equals", "notEquals"];
+  }
+
+  const valueType = typeof value;
+
+  if (valueType === "string" && Number.isNaN(Number(value))) {
+    return [
+      "equals",
+      "notEquals",
+      "contains",
+      "startsWith",
+      "endsWith",
+      "in",
+      "notIn",
+      "isNull",
+      "isNotNull",
+    ];
+  }
+
+  if (valueType === "number") {
+    return [
+      "equals",
+      "notEquals",
+      "greaterThan",
+      "greaterThanOrEqual",
+      "lessThan",
+      "lessThanOrEqual",
+      "in",
+      "notIn",
+      "between",
+      "isNull",
+      "isNotNull",
+    ];
+  }
+
+  if (valueType === "boolean") {
+    return ["equals", "notEquals", "isNull", "isNotNull"];
+  }
+
+  if (value instanceof Date) {
+    return [
+      "equals",
+      "notEquals",
+      "greaterThan",
+      "greaterThanOrEqual",
+      "lessThan",
+      "lessThanOrEqual",
+      "in",
+      "notIn",
+      "between",
+      "isNull",
+      "isNotNull",
+    ];
+  }
+
+  if (Array.isArray(value)) {
+    return ["in", "notIn", "isNull", "isNotNull"];
+  }
+
+  return [...FILTER_OPERATORS];
+}
+
+export function isOperator(value: string): value is FilterOperator {
+  return FILTER_OPERATORS.includes(value as FilterOperator);
+}

package/src/utils/helpers.ts

@@ -0,0 +1,6 @@
+export function parseQueryValue(value: string): any {
+  if (!isNaN(Number(value))) return Number(value); // number
+  if (value === "true" || value === "false") return value === "true"; // boolean
+  if (!isNaN(Date.parse(value))) return new Date(value); // Date
+  return value; // string
+}

package/src/validation-error.ts

@@ -1,7 +1,3 @@
-// ============================================================================
-// Validation Error - Domain Validation Errors
-// ============================================================================
-
 export interface ValidationIssue {
   path: string[];
   message: string;

package/src/value-object.ts

@@ -1,7 +1,3 @@
-// ============================================================================
-// Value Object - Immutable Domain Objects
-// ============================================================================
-
 import { ValidationError } from "./validation-error";
 import { IDomainEvent } from ".";
 import {
@@ -21,6 +17,11 @@ function getStaticProperty<T>(
   return instance.constructor[propertyName];
 }
 
+/**
+ * Identity key type for a Value Object. Can be a single key or an array of keys (composite key).
+ */
+export type IdentityKeyDefinition<T> = (keyof T)[] | keyof T;
+
 export abstract class ValueObject<T> {
   protected readonly props!: T;
   private validationConfig: Required<ValidationConfig>;
@@ -28,12 +29,29 @@ export abstract class ValueObject<T> {
   private domainSchema?: StandardSchema<T>;
   private domainEvents: IDomainEvent[] = [];
 
-  // Static properties that subclasses can override
   protected static validation?: EntityValidation<any>;
   protected static hooks?: VOHooks<any, any>;
 
+  /**
+   * Identity key for identification in collections.
+   * Used by HistoryTracker to track changes in arrays of Value Objects.
+   *
+   * @example
+   * ```typescript
+   * // Simple key
+   * class TagReference extends ValueObject<{ tagId: string }> {
+   *   static readonly identityKey = 'tagId';
+   * }
+   *
+   * // Composite key
+   * class Like extends ValueObject<{ postId: string; userId: string }> {
+   *   static readonly identityKey = ['postId', 'userId'];
+   * }
+   * ```
+   */
+  protected static identityKey?: IdentityKeyDefinition<any>;
+
   constructor(props: T) {
-    // Get static configuration from subclass
     const validation = getStaticProperty<EntityValidation<T>>(
       this,
       "validation"
@@ -53,23 +71,18 @@ export abstract class ValueObject<T> {
 
     let finalProps = { ...props } as T;
 
-    // Validate schema on creation
     if (this.domainSchema && this.validationConfig.onCreate) {
       this.validateProps(finalProps);
     }
 
-    // Set props (not frozen yet) so rules can access them
     (this as any).props = finalProps;
 
-    // Execute rules (custom validations) - after props is set but before freezing
     if (hooks?.rules) {
       hooks.rules(this as any);
     }
 
-    // Now freeze the props for immutability
     Object.freeze(this.props);
 
-    // Hook onCreate
     if (hooks?.onCreate) {
       hooks.onCreate(this as any);
     }
@@ -98,7 +111,6 @@ export abstract class ValueObject<T> {
         throw validationError;
       }
 
-      // If not throwing, store error for later retrieval
       (this as any)._validationError = validationError;
     }
   }
@@ -107,63 +119,112 @@ export abstract class ValueObject<T> {
     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);
   }
 
   /**
-   * Check if value object has validation errors (when throwOnError is false)
+   * Returns true if the value object has validation errors (when throwOnError is false).
    */
   get hasValidationErrors(): boolean {
     return !!(this as any)._validationError;
   }
 
   /**
-   * Get validation errors (when throwOnError is false)
+   * Returns the validation errors (when throwOnError is false).
    */
   get validationErrors(): ValidationError | undefined {
     return (this as any)._validationError;
   }
 
+  /**
+   * Compare this ValueObject with another for equality based on their properties.
+   */
   equals(other: ValueObject<T>): boolean {
     if (!other || !(other instanceof ValueObject)) return false;
     return JSON.stringify(this.props) === JSON.stringify(other.props);
   }
 
   /**
-   * Add a domain event to this value object
+   * Returns the identity key for this Value Object.
+   * Used for identification in collections when identityKey is set.
+   *
+   * @returns String with the identity key or null if not defined
+   *
+   * @example
+   * ```typescript
+   * const like = new Like({ postId: 'p1', userId: 'u1' });
+   * like.getIdentityKey(); // 'p1:u1'
+   *
+   * const tag = new TagReference({ tagId: 'tag-123' });
+   * tag.getIdentityKey(); // 'tag-123'
+   * ```
+   */
+  getIdentityKey(): string | null {
+    const keyDef = getStaticProperty<IdentityKeyDefinition<T>>(
+      this,
+      "identityKey"
+    );
+
+    if (!keyDef) {
+      return null;
+    }
+
+    if (Array.isArray(keyDef)) {
+      return keyDef.map((k) => String(this.props[k])).join(":");
+    }
+
+    return String(this.props[keyDef]);
+  }
+
+  /**
+   * Returns true if this Value Object has an identity key defined.
+   */
+  hasIdentityKey(): boolean {
+    return (
+      getStaticProperty<IdentityKeyDefinition<T>>(this, "identityKey") !==
+      undefined
+    );
+  }
+
+  /**
+   * Returns the identity key definition (if any).
+   */
+  static getIdentityKeyDefinition<P>(): IdentityKeyDefinition<P> | undefined {
+    return (this as any).identityKey;
+  }
+
+  /**
+   * Adds a domain event to this value object.
    */
   protected addDomainEvent(event: IDomainEvent): void {
     this.domainEvents.push(event);
   }
 
   /**
-   * Get all uncommitted domain events
+   * Returns all uncommitted domain events.
    */
   getUncommittedEvents(): IDomainEvent[] {
     return [...this.domainEvents];
   }
 
   /**
-   * Clear all domain events (call after publishing)
+   * Clears all domain events (call after publishing).
    */
   clearEvents(): void {
     this.domainEvents = [];
   }
 
   /**
-   * Check if value object has uncommitted events
+   * Returns true if the value object has uncommitted events.
    */
   hasUncommittedEvents(): boolean {
     return this.domainEvents.length > 0;
@@ -174,8 +235,8 @@ export abstract class ValueObject<T> {
   }
 
   /**
-   * Create a new ValueObject with updated properties
-   * Since ValueObjects are immutable, this returns a new instance
+   * Creates a new ValueObject with updated properties.
+   * ValueObjects are immutable, so this returns a new instance.
    */
   protected clone(updates: Partial<T>): this {
     const Constructor = this.constructor as new (props: T) => this;

package/tests/aggregate-changes.test.ts

@@ -0,0 +1,284 @@
+// ============================================================================
+// Tests: AggregateChanges
+// ============================================================================
+
+import { AggregateChanges } from "../src/aggregate-changes";
+
+describe("AggregateChanges", () => {
+  let changes: AggregateChanges;
+
+  beforeEach(() => {
+    changes = new AggregateChanges();
+  });
+
+  describe("isEmpty / hasChanges", () => {
+    it("should be empty initially", () => {
+      expect(changes.isEmpty()).toBe(true);
+      expect(changes.hasChanges()).toBe(false);
+      expect(changes.count).toBe(0);
+    });
+
+    it("should not be empty after adding operation", () => {
+      changes.addCreate("User", { id: "1", name: "Test" }, 0);
+      expect(changes.isEmpty()).toBe(false);
+      expect(changes.hasChanges()).toBe(true);
+      expect(changes.count).toBe(1);
+    });
+  });
+
+  describe("addCreate", () => {
+    it("should add create operation", () => {
+      const data = { id: "1", name: "Test User" };
+      changes.addCreate("User", data, 0);
+
+      expect(changes.hasCreates()).toBe(true);
+      expect(changes.creates()).toHaveLength(1);
+      expect(changes.creates()[0]).toMatchObject({
+        type: "create",
+        entity: "User",
+        data,
+        depth: 0,
+      });
+    });
+
+    it("should add create with parent info", () => {
+      const data = { id: "post-1", title: "Test Post" };
+      changes.addCreate("Post", data, 1, "user-1", "User");
+
+      const create = changes.creates()[0];
+      expect(create.parentId).toBe("user-1");
+      expect(create.parentEntity).toBe("User");
+    });
+  });
+
+  describe("addUpdate", () => {
+    it("should add update operation", () => {
+      const data = { id: "1", name: "Updated" };
+      const changedFields = { name: "Updated" };
+      changes.addUpdate("User", "1", data, changedFields, 0);
+
+      expect(changes.hasUpdates()).toBe(true);
+      expect(changes.updates()).toHaveLength(1);
+      expect(changes.updates()[0]).toMatchObject({
+        type: "update",
+        entity: "User",
+        id: "1",
+        changedFields,
+        depth: 0,
+      });
+    });
+  });
+
+  describe("addDelete", () => {
+    it("should add delete operation", () => {
+      const data = { id: "1", name: "To Delete" };
+      changes.addDelete("User", "1", data, 0);
+
+      expect(changes.hasDeletes()).toBe(true);
+      expect(changes.deletes()).toHaveLength(1);
+      expect(changes.deletes()[0]).toMatchObject({
+        type: "delete",
+        entity: "User",
+        id: "1",
+        depth: 0,
+      });
+    });
+  });
+
+  describe("ordering", () => {
+    beforeEach(() => {
+      // Add operations in random order
+      changes.addCreate("Comment", { id: "c1" }, 2);
+      changes.addDelete("Like", "l1", { id: "l1" }, 3);
+      changes.addCreate("User", { id: "u1" }, 0);
+      changes.addDelete("Comment", "c2", { id: "c2" }, 2);
+      changes.addCreate("Post", { id: "p1" }, 1);
+      changes.addDelete("Post", "p2", { id: "p2" }, 1);
+    });
+
+    it("should order creates by depth ASC (root → leaf)", () => {
+      const creates = changes.creates();
+      expect(creates[0].entity).toBe("User"); // depth 0
+      expect(creates[1].entity).toBe("Post"); // depth 1
+      expect(creates[2].entity).toBe("Comment"); // depth 2
+    });
+
+    it("should order deletes by depth DESC (leaf → root)", () => {
+      const deletes = changes.deletes();
+      expect(deletes[0].entity).toBe("Like"); // depth 3
+      expect(deletes[1].entity).toBe("Comment"); // depth 2
+      expect(deletes[2].entity).toBe("Post"); // depth 1
+    });
+  });
+
+  describe("operations iterator", () => {
+    it("should yield operations in correct order: deletes, creates, updates", () => {
+      changes.addCreate("Post", { id: "p1" }, 1);
+      changes.addUpdate("User", "u1", { id: "u1" }, { name: "New" }, 0);
+      changes.addDelete("Comment", "c1", { id: "c1" }, 2);
+
+      const ops = [...changes.operations()];
+
+      expect(ops[0].type).toBe("delete"); // deletes first
+      expect(ops[1].type).toBe("create"); // creates second
+      expect(ops[2].type).toBe("update"); // updates last
+    });
+  });
+
+  describe("toBatchOperations", () => {
+    beforeEach(() => {
+      // Creates
+      changes.addCreate("User", { id: "u1" }, 0);
+      changes.addCreate("Post", { id: "p1" }, 1, "u1", "User");
+      changes.addCreate("Post", { id: "p2" }, 1, "u1", "User");
+      changes.addCreate("Comment", { id: "c1" }, 2, "p1", "Post");
+
+      // Updates
+      changes.addUpdate("User", "u2", { id: "u2" }, { name: "Updated" }, 0);
+      changes.addUpdate("Post", "p3", { id: "p3" }, { title: "New Title" }, 1);
+
+      // Deletes
+      changes.addDelete("Comment", "c2", { id: "c2" }, 2);
+      changes.addDelete("Comment", "c3", { id: "c3" }, 2);
+      changes.addDelete("Post", "p4", { id: "p4" }, 1);
+    });
+
+    it("should group deletes by entity and order by depth DESC", () => {
+      const batch = changes.toBatchOperations();
+
+      expect(batch.deletes).toHaveLength(2); // Comment and Post
+
+      // Comments should come first (depth 2)
+      expect(batch.deletes[0].entity).toBe("Comment");
+      expect(batch.deletes[0].ids).toEqual(["c2", "c3"]);
+
+      // Posts second (depth 1)
+      expect(batch.deletes[1].entity).toBe("Post");
+      expect(batch.deletes[1].ids).toEqual(["p4"]);
+    });
+
+    it("should group creates by entity and order by depth ASC", () => {
+      const batch = changes.toBatchOperations();
+
+      expect(batch.creates).toHaveLength(3); // User, Post, Comment
+
+      // User first (depth 0)
+      expect(batch.creates[0].entity).toBe("User");
+      expect(batch.creates[0].items).toHaveLength(1);
+
+      // Post second (depth 1)
+      expect(batch.creates[1].entity).toBe("Post");
+      expect(batch.creates[1].items).toHaveLength(2);
+
+      // Comment last (depth 2)
+      expect(batch.creates[2].entity).toBe("Comment");
+      expect(batch.creates[2].items).toHaveLength(1);
+    });
+
+    it("should group updates by entity", () => {
+      const batch = changes.toBatchOperations();
+
+      expect(batch.updates).toHaveLength(2); // User and Post
+
+      const userUpdates = batch.updates.find((u) => u.entity === "User");
+      expect(userUpdates?.items).toHaveLength(1);
+      expect(userUpdates?.items[0].id).toBe("u2");
+
+      const postUpdates = batch.updates.find((u) => u.entity === "Post");
+      expect(postUpdates?.items).toHaveLength(1);
+      expect(postUpdates?.items[0].id).toBe("p3");
+    });
+
+    it("should include parentId in create items", () => {
+      const batch = changes.toBatchOperations();
+
+      const postCreates = batch.creates.find((c) => c.entity === "Post");
+      expect(postCreates?.items[0].parentId).toBe("u1");
+      expect(postCreates?.items[1].parentId).toBe("u1");
+
+      const commentCreates = batch.creates.find((c) => c.entity === "Comment");
+      expect(commentCreates?.items[0].parentId).toBe("p1");
+    });
+  });
+
+  describe("for (filter by entity)", () => {
+    beforeEach(() => {
+      changes.addCreate("Post", { id: "p1", title: "Post 1" }, 1);
+      changes.addCreate("Post", { id: "p2", title: "Post 2" }, 1);
+      changes.addUpdate("Post", "p3", { id: "p3" }, { title: "Updated" }, 1);
+      changes.addDelete("Post", "p4", { id: "p4" }, 1);
+      changes.addCreate("Comment", { id: "c1" }, 2);
+    });
+
+    it("should filter creates by entity", () => {
+      const postChanges = changes.for("Post");
+      expect(postChanges.creates).toHaveLength(2);
+      expect(postChanges.creates[0].id).toBe("p1");
+    });
+
+    it("should filter updates by entity", () => {
+      const postChanges = changes.for("Post");
+      expect(postChanges.updates).toHaveLength(1);
+      expect(postChanges.updates[0].entity.id).toBe("p3");
+    });
+
+    it("should filter deletes by entity", () => {
+      const postChanges = changes.for("Post");
+      expect(postChanges.deletes).toHaveLength(1);
+      expect(postChanges.deletes[0].id).toBe("p4");
+    });
+
+    it("should return empty for non-existent entity", () => {
+      const userChanges = changes.for("User");
+      expect(userChanges.isEmpty()).toBe(true);
+    });
+
+    it("should have helper methods", () => {
+      const postChanges = changes.for("Post");
+      expect(postChanges.hasCreates()).toBe(true);
+      expect(postChanges.hasUpdates()).toBe(true);
+      expect(postChanges.hasDeletes()).toBe(true);
+      expect(postChanges.hasChanges()).toBe(true);
+    });
+  });
+
+  describe("getAffectedEntities", () => {
+    it("should return list of unique entities", () => {
+      changes.addCreate("User", { id: "u1" }, 0);
+      changes.addCreate("Post", { id: "p1" }, 1);
+      changes.addUpdate("Post", "p2", { id: "p2" }, {}, 1);
+      changes.addDelete("Comment", "c1", { id: "c1" }, 2);
+
+      const entities = changes.getAffectedEntities();
+
+      expect(entities).toContain("User");
+      expect(entities).toContain("Post");
+      expect(entities).toContain("Comment");
+      expect(entities).toHaveLength(3);
+    });
+  });
+
+  describe("clone", () => {
+    it("should create independent copy", () => {
+      changes.addCreate("User", { id: "u1" }, 0);
+
+      const cloned = changes.clone();
+      cloned.addCreate("Post", { id: "p1" }, 1);
+
+      expect(changes.count).toBe(1);
+      expect(cloned.count).toBe(2);
+    });
+  });
+
+  describe("clear", () => {
+    it("should remove all operations", () => {
+      changes.addCreate("User", { id: "u1" }, 0);
+      changes.addUpdate("Post", "p1", { id: "p1" }, {}, 1);
+
+      changes.clear();
+
+      expect(changes.isEmpty()).toBe(true);
+      expect(changes.count).toBe(0);
+    });
+  });
+});