@woltz/rich-domain 1.2.1 → 1.2.2

package/src/{history-tracker.ts → change-tracker.ts}

@@ -27,7 +27,7 @@ export type OnChangeValidator = (
  * - Generates AggregateChanges for persistence
  * - Supports validation on change via onChangeValidator
  */
-export class HistoryTracker {
+export class ChangeTracker {
   private history: HistoryEntry[] = [];
   private originalValues: Map<string, any> = new Map();
   private trackedArrays: Map<string, ArrayState> = new Map();
@@ -41,7 +41,7 @@ export class HistoryTracker {
     private depth: number = 0,
     private parentId?: string,
     private parentEntity?: string,
-    private rootTracker?: HistoryTracker
+    private rootTracker?: ChangeTracker
   ) {
     if (!rootTracker) {
       this.rootTracker = this;
@@ -60,10 +60,6 @@ export class HistoryTracker {
     this.getRootTracker().onChangeValidator = validator;
   }
 
-  // ============================================================================
-  // Initial State Capture
-  // ============================================================================
-
   private captureInitialState(): void {
     if (this.depth > 0) return;
     this.captureEntityState(this.target, this.rootEntityName, "", 0);
@@ -153,10 +149,6 @@ export class HistoryTracker {
     });
   }
 
-  // ============================================================================
-  // Proxy Creation
-  // ============================================================================
-
   createProxy(): any {
     const handler: ProxyHandler<any> = {
       get: (target, prop, receiver) => {
@@ -177,7 +169,7 @@ export class HistoryTracker {
         }
 
         if (this.isEntityOrVO(value)) {
-          const nestedTracker = new HistoryTracker(
+          const nestedTracker = new ChangeTracker(
             value,
             this.getEntityName(value),
             currentPath,
@@ -200,7 +192,6 @@ export class HistoryTracker {
           return true;
         }
 
-        // Call validator before making the change
         const rootTracker = this.getRootTracker();
         if (rootTracker.onChangeValidator) {
           try {
@@ -210,21 +201,17 @@ export class HistoryTracker {
               newValue
             );
             if (result === false) {
-              // Validator rejected the change
-              return true; // Return true to not throw, but don't apply change
+              return true;
             }
           } catch (error) {
-            // Validator threw an error - propagate it
             throw error;
           }
         }
 
-        // Store original value
         if (!rootTracker.originalValues.has(currentPath)) {
           rootTracker.originalValues.set(currentPath, oldValue);
         }
 
-        // Record in history
         rootTracker.history.push({
           path: currentPath,
           previousValue: oldValue,
@@ -234,7 +221,6 @@ export class HistoryTracker {
 
         const result = Reflect.set(target, prop, newValue, receiver);
 
-        // Handle special cases
         if (Array.isArray(newValue)) {
           this.handleArrayAssignment(currentPath, oldValue);
         } else if (this.isEntityOrVO(newValue) || this.isEntityOrVO(oldValue)) {
@@ -284,14 +270,12 @@ export class HistoryTracker {
             return function (...args: any[]) {
               const oldArray = target.slice();
 
-              // Call validator before array mutation
               if (rootTracker.onChangeValidator) {
                 try {
-                  const result = rootTracker.onChangeValidator(
-                    path,
-                    oldArray,
-                    [...oldArray, ...args] // Preview of change
-                  );
+                  const result = rootTracker.onChangeValidator(path, oldArray, [
+                    ...oldArray,
+                    ...args,
+                  ]);
                   if (result === false) {
                     return undefined;
                   }
@@ -317,7 +301,7 @@ export class HistoryTracker {
 
         if (!isNaN(Number(prop)) && tracker.isEntityOrVO(value)) {
           const nestedPath = `${path}[${String(prop)}]`;
-          const nestedTracker = new HistoryTracker(
+          const nestedTracker = new ChangeTracker(
             value,
             tracker.getEntityName(value),
             nestedPath,
@@ -336,7 +320,6 @@ export class HistoryTracker {
         if (!isNaN(Number(prop))) {
           const oldArray = target.slice();
 
-          // Call validator before array item change
           if (rootTracker.onChangeValidator) {
             try {
               const result = rootTracker.onChangeValidator(
@@ -368,10 +351,6 @@ export class HistoryTracker {
     });
   }
 
-  // ============================================================================
-  // getChanges() - Main Method
-  // ============================================================================
-
   /**
    * Returns all detected changes as AggregateChanges.
    */
@@ -388,7 +367,7 @@ export class HistoryTracker {
 
   private analyzeRootChanges(
     changes: AggregateChanges<any>,
-    rootTracker: HistoryTracker
+    rootTracker: ChangeTracker
   ): void {
     const changedFields: Record<string, any> = {};
     let hasChanges = false;
@@ -420,7 +399,7 @@ export class HistoryTracker {
 
   private analyzeCollectionChanges(
     changes: AggregateChanges<any>,
-    rootTracker: HistoryTracker
+    rootTracker: ChangeTracker
   ): void {
     const allTrackedArrays = new Map<string, ArrayState>();
     const processedArrays = new Set<any>();
@@ -456,7 +435,6 @@ export class HistoryTracker {
         const itemEntityName = this.getEntityName(item);
         changes.addCreate(itemEntityName, item, depth, parentId, parentEntity);
 
-        // Recursively mark nested items as created
         this.markNestedItemsAsCreated(item, depth, changes);
       }
 
@@ -482,7 +460,6 @@ export class HistoryTracker {
           const deleteId = id || key!;
           changes.addDelete(itemEntityName, deleteId, item, depth);
 
-          // Recursively mark nested items as deleted using ORIGINAL state
           this.markNestedItemsAsDeleted(item, depth, changes, rootTracker);
         }
       }
@@ -508,7 +485,6 @@ export class HistoryTracker {
       if (propName === "id") continue;
 
       if (Array.isArray(value)) {
-        // Process all items in the array
         for (const nestedItem of value) {
           if (this.isEntityOrVO(nestedItem)) {
             const nestedId = this.getEntityId(nestedItem);
@@ -523,8 +499,11 @@ export class HistoryTracker {
                 this.getEntityName(item)
               );
 
-              // Recursively process nested items
-              this.markNestedItemsAsCreated(nestedItem, parentDepth + 1, changes);
+              this.markNestedItemsAsCreated(
+                nestedItem,
+                parentDepth + 1,
+                changes
+              );
             }
           }
         }
@@ -540,22 +519,16 @@ export class HistoryTracker {
     item: any,
     parentDepth: number,
     changes: AggregateChanges<any>,
-    rootTracker: HistoryTracker
+    rootTracker: ChangeTracker
   ): void {
     if (!item || typeof item !== "object") return;
 
-    // Get the ID to look up the original state
     const itemId = this.getEntityId(item);
     if (!itemId) return;
 
-    // Look through all tracked arrays to find nested items
     for (const [, arrayState] of rootTracker.trackedArrays) {
-      // Check if this array belongs to our deleted item
       if (arrayState.metadata.parentId === itemId) {
-        // Use the CLONED (original) state to get the items
-        // Note: cloned items are JSON objects, not Entity/VO instances
         for (const nestedItem of arrayState.cloned) {
-          // Cloned items are JSON objects with an 'id' property
           const id =
             typeof nestedItem === "object" && nestedItem !== null
               ? nestedItem.id
@@ -564,7 +537,6 @@ export class HistoryTracker {
             const entityName = arrayState.metadata.entityName;
             changes.addDelete(entityName, id, nestedItem, parentDepth + 1);
 
-            // Recursively process this item's nested arrays
             this.markNestedJsonItemAsDeleted(
               id,
               parentDepth + 1,
@@ -585,12 +557,10 @@ export class HistoryTracker {
     itemId: string,
     parentDepth: number,
     changes: AggregateChanges<any>,
-    rootTracker: HistoryTracker
+    rootTracker: ChangeTracker
   ): void {
-    // Look through all tracked arrays to find nested items of this parent
     for (const [, arrayState] of rootTracker.trackedArrays) {
       if (arrayState.metadata.parentId === itemId) {
-        // Process all items in this nested array
         for (const nestedJsonItem of arrayState.cloned) {
           if (typeof nestedJsonItem !== "object" || nestedJsonItem === null)
             continue;
@@ -606,7 +576,6 @@ export class HistoryTracker {
               parentDepth + 1
             );
 
-            // Recursively process further nesting
             this.markNestedJsonItemAsDeleted(
               nestedId,
               parentDepth + 1,
@@ -614,7 +583,6 @@ export class HistoryTracker {
               rootTracker
             );
           } else {
-            // Value object - try to extract identity key
             const key = this.extractIdentityKeyFromJson(
               nestedJsonItem,
               arrayState.original
@@ -640,20 +608,16 @@ export class HistoryTracker {
     jsonItem: any,
     originalArray: any[]
   ): string | undefined {
-    // Try to find the original ValueObject to get its identity key
     for (const originalItem of originalArray) {
       if (this.isEntityOrVO(originalItem)) {
         const originalJson = this.deepClone(originalItem);
-        // Check if this matches our JSON item (rough comparison)
         if (JSON.stringify(originalJson) === JSON.stringify(jsonItem)) {
-          // Found the matching original item - extract its identity key
           const key = this.getItemKey(originalItem);
           if (key) return key;
         }
       }
     }
 
-    // Fallback: if it has an id, use that
     if (jsonItem.id) return jsonItem.id;
 
     return undefined;
@@ -692,7 +656,7 @@ export class HistoryTracker {
 
   private analyzeEntityChanges(
     changes: AggregateChanges<any>,
-    rootTracker: HistoryTracker
+    rootTracker: ChangeTracker
   ): void {
     for (const [path, trackedItem] of rootTracker.trackedEntities) {
       if (path === "root") continue;
@@ -720,7 +684,6 @@ export class HistoryTracker {
         case "deleted":
           const id = this.getEntityId(originalValue);
           if (id) {
-            // Use originalEntity instead of originalValue to preserve entity instance
             changes.addDelete(entityName, id, originalEntity, depth);
           }
           break;
@@ -728,7 +691,6 @@ export class HistoryTracker {
         case "replaced":
           const oldId = this.getEntityId(originalValue);
           if (oldId) {
-            // Use originalEntity instead of originalValue to preserve entity instance
             changes.addDelete(entityName, oldId, originalEntity, depth);
           }
           changes.addCreate(
@@ -762,10 +724,6 @@ export class HistoryTracker {
     }
   }
 
-  // ============================================================================
-  // Change Detection Helpers
-  // ============================================================================
-
   private detectEntityChangeState(
     previous: any,
     current: any
@@ -864,10 +822,6 @@ export class HistoryTracker {
     return changes;
   }
 
-  // ============================================================================
-  // Internal Handlers
-  // ============================================================================
-
   private handleArrayAssignment(path: string, oldValue: any): void {
     const rootTracker = this.getRootTracker();
 
@@ -892,7 +846,6 @@ export class HistoryTracker {
     const existingTracked = rootTracker.trackedEntities.get(path);
 
     rootTracker.trackedEntities.set(path, {
-      // Preserve original entity, or use oldValue if this is the first change
       entity: existingTracked?.entity || oldValue,
       metadata: {
         entityName,
@@ -901,16 +854,11 @@ export class HistoryTracker {
         parentEntity: this.rootEntityName,
         path,
       },
-      // Preserve original state
       originalState: existingTracked?.originalState,
     });
   }
 
-  // ============================================================================
-  // Utility Methods
-  // ============================================================================
-
-  private getRootTracker(): HistoryTracker {
+  private getRootTracker(): ChangeTracker {
     return this.rootTracker || this;
   }
 

package/src/constants.ts

@@ -1,7 +1,81 @@
-import { ValidationConfig } from ".";
+import {
+  ArrayOperators,
+  BooleanOperators,
+  DateOperators,
+  FilterOperator,
+  NumberOperators,
+  StringOperators,
+  ValidationConfig,
+} from ".";
 
 export const DEFAULT_VALIDATION_CONFIG: Required<ValidationConfig> = {
   onCreate: true,
   onUpdate: true,
   throwOnError: true,
 };
+
+export const ARRAY_OPERATORS: ArrayOperators[] = [
+  "in",
+  "notIn",
+  "isNull",
+  "isNotNull",
+];
+export const BOOLEAN_OPERATORS: BooleanOperators[] = [
+  "equals",
+  "notEquals",
+  "isNull",
+  "isNotNull",
+];
+export const DATE_OPERATORS: DateOperators[] = [
+  "equals",
+  "notEquals",
+  "greaterThan",
+  "greaterThanOrEqual",
+  "lessThan",
+  "lessThanOrEqual",
+  "in",
+  "notIn",
+  "between",
+  "isNull",
+  "isNotNull",
+];
+export const NUMBER_OPERATORS: NumberOperators[] = [
+  "equals",
+  "notEquals",
+  "greaterThan",
+  "greaterThanOrEqual",
+  "lessThan",
+  "lessThanOrEqual",
+  "in",
+  "notIn",
+  "between",
+  "isNull",
+  "isNotNull",
+];
+export const STRING_OPERATORS: StringOperators[] = [
+  "equals",
+  "notEquals",
+  "contains",
+  "startsWith",
+  "endsWith",
+  "in",
+  "notIn",
+  "isNull",
+  "isNotNull",
+];
+export const FILTER_OPERATORS: FilterOperator[] = [
+  "equals",
+  "notEquals",
+  "greaterThan",
+  "greaterThanOrEqual",
+  "lessThan",
+  "lessThanOrEqual",
+  "contains",
+  "startsWith",
+  "endsWith",
+  "in",
+  "notIn",
+  "between",
+  "isNull",
+  "isNotNull",
+];

package/src/criteria.ts

@@ -19,6 +19,7 @@ import {
   isValidOperatorForType,
   getValidOperatorsForType,
   isOperator,
+  sanitizeFieldValue,
 } from "./utils/criteria-operator-validation";
 import { parseQueryValue } from "./utils/helpers";
 
@@ -460,10 +461,15 @@ export class Criteria<T = any> {
   }
 
   private validateOperator(operator: FilterOperator, value: any): void {
-    if (value !== undefined && !isValidOperatorForType(value, operator)) {
-      const validOps = getValidOperatorsForType(value);
+    const sanitizedValue = sanitizeFieldValue(value, operator);
+
+    if (
+      sanitizedValue !== undefined &&
+      !isValidOperatorForType(sanitizedValue, operator)
+    ) {
+      const validOps = getValidOperatorsForType(sanitizedValue);
       throw new InvalidCriteriaError(
-        `Operator "${operator}" is not valid for type "${typeof value}". Valid operators: ${validOps.join(
+        `Operator "${operator}" is not valid for type "${typeof sanitizedValue}". Valid operators: ${validOps.join(
           ", "
         )}`,
         operator

package/src/domain-event.ts

@@ -1,7 +1,3 @@
-// ============================================================================
-// Domain Events - Event-Driven Architecture Support
-// ============================================================================
-
 import { IDomainEvent } from ".";
 import { Id } from "./id";
 

package/src/entity-changes.ts

@@ -1,8 +1,3 @@
-// ============================================================================
-// Entity Changes
-// Changes filtered by entity type
-// ============================================================================
-
 import {
   Operation,
   CreateOperation,

package/src/entity-schema-registry.ts

@@ -8,17 +8,14 @@ import { Id } from "./id";
 export interface EntitySchema {
   /** Entity name in the domain (e.g., 'User', 'Post') */
   entity: string;
-
   /** Table name in the database (e.g., 'users', 'blog_posts') */
   table: string;
-
   /**
    * Field mapping: domain → database.
    * Only include fields with different names.
    * @example { email: 'user_email', createdAt: 'created_at' }
    */
   fields?: Record<string, string>;
-
   /**
    * FK configuration for parent relation.
    */
@@ -148,15 +145,11 @@ export class EntitySchemaRegistry {
   mapFields(entity: string, data: Record<string, any>): MappedEntityData {
     const fields = this.getFieldsMap(entity);
     const result: MappedEntityData = {};
-
     for (const [key, value] of Object.entries(data)) {
-      if (this.isEntityOrCollection(value)) {
-        continue;
-      }
+      if (this.isEntityOrCollection(value)) continue;
       const mappedKey = fields[key] ?? key;
       result[mappedKey] = this.normalizeValue(value);
     }
-
     return result;
   }
 
@@ -173,26 +166,18 @@ export class EntitySchemaRegistry {
   ): MappedEntityData {
     const fields = this.getFieldsMap(entity);
     const result: MappedEntityData = {};
-
-    // Map ID if it is an Entity or has entity-like structure
     const hasId = (domainEntity as any).id;
     if (hasId) {
-      // Extract id value
       const idValue = hasId.value ?? hasId;
       result["id"] = idValue;
     }
-
-    // Get props
     const props = (domainEntity as any).props || domainEntity;
-
     for (const [key, value] of Object.entries(props)) {
-      if (key === "id") continue; // ID already mapped
+      if (key === "id") continue;
       if (this.isEntityOrCollection(value)) continue;
-
       const mappedKey = fields[key] ?? key;
       result[mappedKey] = this.normalizeValue(value);
     }
-
     return result;
   }
 
@@ -206,7 +191,6 @@ export class EntitySchemaRegistry {
   getParentFk(entity: string, parentId: string): Record<string, string> | null {
     const schema = this.getSchema(entity);
     if (!schema.parentFk) return null;
-
     return { [schema.parentFk.field]: parentId };
   }
 
@@ -250,12 +234,9 @@ export class EntitySchemaRegistry {
     if (Array.isArray(value)) return true;
     if (value instanceof Entity) return true;
     if (value instanceof ValueObject) return true;
-
-    // Checks if it has the structure of an Entity (object with 'id' that has 'value')
     if (typeof value === 'object' && value.id && typeof value.id === 'object' && 'value' in value.id) {
       return true;
     }
-
     return false;
   }
 
@@ -267,7 +248,6 @@ export class EntitySchemaRegistry {
     if (value instanceof Id) return value.value;
     if (value instanceof Date) return value;
     if (typeof value === "object" && "value" in value) {
-      // Might be an ID or other wrapper
       return value.value;
     }
     return value;

package/src/entity.ts

@@ -1,16 +1,5 @@
-// ============================================================================
-// Entity & Aggregate Classes
-// ============================================================================
-
 import { BaseEntity } from "./base-entity";
 import { BaseProps } from "./types";
 
-/**
- * Entity - Has identity and lifecycle, but is not an aggregate root
- */
 export class Entity<T extends BaseProps> extends BaseEntity<T> {}
-
-/**
- * Aggregate - Aggregate root that manages a consistency boundary
- */
 export class Aggregate<T extends BaseProps> extends BaseEntity<T> {}

package/src/index.ts

@@ -1,29 +1,16 @@
-// ============================================================================
-// Rich Domain Library - Main Exports
-// ============================================================================
-
-// Core Classes
-export { Id } from "./id";
-export { Entity, Aggregate } from "./entity";
-export { ValueObject } from "./value-object";
-export { Mapper } from "./mapper";
-export { EntitySchemaRegistry } from "./entity-schema-registry";
-
 export * from "./validation-error";
-
-// Domain Events
 export * from "./domain-event";
 export * from "./domain-event-bus";
 export * from "./exceptions";
-
-// Criteria
 export * from "./criteria";
 export * from "./paginated-result";
-
-// Repository
 export * from "./repository";
-
-// Types
+export { Id } from "./id";
+export { Entity, Aggregate } from "./entity";
+export { ValueObject } from "./value-object";
+export { Mapper } from "./mapper";
+export { EntitySchemaRegistry } from "./entity-schema-registry";
+export { AggregateChanges } from "./aggregate-changes";
 export {
   DomainEventHandler,
   EntityHooks,
@@ -41,7 +28,6 @@ export {
   Order,
   IUnitOfWork,
   IDomainEventHandler,
-  EntityId,
   FieldPath,
   FilterOperator,
   Search,
@@ -55,3 +41,12 @@ export {
   ArrayOperators,
   CriteriaOptions,
 } from "./types";
+export {
+  ARRAY_OPERATORS,
+  BOOLEAN_OPERATORS,
+  DATE_OPERATORS,
+  NUMBER_OPERATORS,
+  STRING_OPERATORS,
+  FILTER_OPERATORS,
+} from "./constants";
+export { isValidOperatorForType } from "./utils/criteria-operator-validation";