@woltz/rich-domain 1.2.4 → 1.3.1

package/src/aggregate-changes.ts

@@ -17,6 +17,7 @@ import { EntityChanges } from "./entity-changes";
  * - Orders operations respecting FK dependencies
  * - Groups operations by entity for batch execution
  * - Provides query and iteration methods
+ * - Includes relationField, parentId, parentEntity for N:N support
  *
  * @example
  * ```typescript
@@ -31,9 +32,9 @@ import { EntityChanges } from "./entity-changes";
  * const changes = user.getChanges<UserEntities>();
  *
  * // Filtering by entity with autocompletion
- * const postChanges = changes.for('Post'); // 'Post' autocompletes
+ * const postChanges = changes.for('Post');
  * postChanges.creates.forEach(post => {
- *   console.log(post.title); // 'post' is typed as Post
+ *   console.log(post.title);
  * });
  * ```
  */
@@ -46,13 +47,21 @@ export class AggregateChanges<TEntityMap = Record<string, any>> {
 
   /**
    * Adds a create operation.
+   *
+   * @param entity - Entity name
+   * @param data - Entity data
+   * @param depth - Depth in the aggregate tree
+   * @param parentId - Parent entity ID (for FK)
+   * @param parentEntity - Parent entity name
+   * @param relationField - Name of the relation field in parent (e.g., 'tags', 'comments')
    */
   addCreate<T>(
     entity: string,
     data: T,
     depth: number,
     parentId?: string,
-    parentEntity?: string
+    parentEntity?: string,
+    relationField?: string
   ): void {
     this.ops.push({
       type: "create",
@@ -61,6 +70,7 @@ export class AggregateChanges<TEntityMap = Record<string, any>> {
       depth,
       parentId,
       parentEntity,
+      relationField,
     } as CreateOperation<T>);
   }
 
@@ -86,14 +96,33 @@ export class AggregateChanges<TEntityMap = Record<string, any>> {
 
   /**
    * Adds a delete operation.
+   *
+   * @param entity - Entity name
+   * @param id - Entity ID
+   * @param data - Entity data (for reference)
+   * @param depth - Depth in the aggregate tree
+   * @param relationField - Name of the relation field in parent (e.g., 'tags', 'comments')
+   * @param parentId - Parent entity ID (for N:N disconnect)
+   * @param parentEntity - Parent entity name (for N:N disconnect)
    */
-  addDelete<T>(entity: string, id: string, data: T, depth: number): void {
+  addDelete<T>(
+    entity: string,
+    id: string,
+    data: T,
+    depth: number,
+    relationField?: string,
+    parentId?: string,
+    parentEntity?: string
+  ): void {
     this.ops.push({
       type: "delete",
       entity,
       id,
       data,
       depth,
+      relationField,
+      parentId,
+      parentEntity,
     } as DeleteOperation<T>);
   }
 
@@ -145,8 +174,8 @@ export class AggregateChanges<TEntityMap = Record<string, any>> {
    * Converts the changes into BatchOperations for optimized execution.
    *
    * Groups operations by entity and sorts by depth:
-   * - Deletes: depth DESC (leaf → root)
-   * - Creates: depth ASC (root → leaf)
+   * - Deletes: depth DESC (leaf → root), grouped by entity + relationField + parentId
+   * - Creates: depth ASC (root → leaf), grouped by entity + relationField
    * - Updates: grouped by entity
    *
    * @example
@@ -155,12 +184,16 @@ export class AggregateChanges<TEntityMap = Record<string, any>> {
    *
    * // Run deletes
    * for (const del of batch.deletes) {
-   *   await tx[del.entity].deleteMany({ where: { id: { in: del.ids } } });
-   * }
-   *
-   * // Run creates
-   * for (const create of batch.creates) {
-   *   await tx[create.entity].createMany({ data: create.items });
+   *   if (registry.isReferenceCollection(del.parentEntity, del.relationField)) {
+   *     // N:N - disconnect only
+   *     await prisma[del.parentEntity].update({
+   *       where: { id: del.parentId },
+   *       data: { [del.relationField]: { disconnect: del.ids.map(id => ({ id })) } }
+   *     });
+   *   } else {
+   *     // 1:N - delete entities
+   *     await prisma[del.entity].deleteMany({ where: { id: { in: del.ids } } });
+   *   }
    * }
    * ```
    */
@@ -173,46 +206,90 @@ export class AggregateChanges<TEntityMap = Record<string, any>> {
   }
 
   /**
-   * Groups deletes by entity, sorted by descending depth.
+   * Groups deletes by entity + relationField + parentId, sorted by descending depth.
+   *
+   * For N:N relations, we need to group by parentId because disconnect
+   * operations are performed on the parent entity.
    */
   private groupDeletes(): BatchOperations["deletes"] {
     const deleteOps = this.deletes();
-    const grouped = new Map<string, { depth: number; ids: string[] }>();
+    const grouped = new Map<
+      string,
+      {
+        depth: number;
+        ids: string[];
+        relationField?: string;
+        parentEntity?: string;
+        parentId?: string;
+      }
+    >();
 
     for (const op of deleteOps) {
-      if (!grouped.has(op.entity)) {
-        grouped.set(op.entity, { depth: op.depth, ids: [] });
+      // Group by entity + relationField + parentId
+      // This ensures N:N disconnects are grouped per parent
+      const key = `${op.entity}:${op.relationField ?? ""}:${op.parentId ?? ""}`;
+
+      if (!grouped.has(key)) {
+        grouped.set(key, {
+          depth: op.depth,
+          ids: [],
+          relationField: op.relationField,
+          parentEntity: op.parentEntity,
+          parentId: op.parentId,
+        });
       }
-      grouped.get(op.entity)!.ids.push(op.id);
+      grouped.get(key)!.ids.push(op.id);
     }
 
     return Array.from(grouped.entries())
-      .map(([entity, { depth, ids }]) => ({ entity, depth, ids }))
+      .map(([key, { depth, ids, relationField, parentEntity, parentId }]) => {
+        const entity = key.split(":")[0];
+        return { entity, depth, ids, parentId, relationField, parentEntity };
+      })
       .sort((a, b) => b.depth - a.depth);
   }
 
   /**
-   * Groups creates by entity, sorted by ascending depth.
+   * Groups creates by entity + relationField, sorted by ascending depth.
+   *
+   * Preserves parentEntity for N:N connect operations.
    */
   private groupCreates(): BatchOperations["creates"] {
     const createOps = this.creates();
     const grouped = new Map<
       string,
-      { depth: number; items: BatchCreateItem[] }
+      {
+        depth: number;
+        items: BatchCreateItem[];
+        relationField?: string;
+        parentEntity?: string;
+      }
     >();
 
     for (const op of createOps) {
-      if (!grouped.has(op.entity)) {
-        grouped.set(op.entity, { depth: op.depth, items: [] });
+      const key = `${op.entity}:${op.relationField ?? ""}`;
+
+      if (!grouped.has(key)) {
+        grouped.set(key, {
+          depth: op.depth,
+          items: [],
+          relationField: op.relationField,
+          parentEntity: op.parentEntity,
+        });
       }
-      grouped.get(op.entity)!.items.push({
+      grouped.get(key)!.items.push({
         data: op.data,
         parentId: op.parentId,
+        parentEntity: op.parentEntity,
+        relationField: op.relationField,
       });
     }
 
     return Array.from(grouped.entries())
-      .map(([entity, { depth, items }]) => ({ entity, depth, items }))
+      .map(([key, { depth, items, relationField, parentEntity }]) => {
+        const entity = key.split(":")[0];
+        return { entity, depth, items, relationField, parentEntity };
+      })
       .sort((a, b) => a.depth - b.depth);
   }
 
@@ -261,6 +338,25 @@ export class AggregateChanges<TEntityMap = Record<string, any>> {
     return new EntityChanges<TEntityMap[K]>(filtered);
   }
 
+  /**
+   * Filters changes by relation field.
+   *
+   * @param relationField - Name of the relation field (e.g., 'tags', 'comments')
+   * @returns New AggregateChanges containing only operations for this relation
+   *
+   * @example
+   * ```typescript
+   * const tagChanges = changes.forRelation('tags');
+   * // Contains only creates/deletes for the 'tags' relation
+   * ```
+   */
+  forRelation(relationField: string): AggregateChanges<TEntityMap> {
+    const filtered = this.ops.filter(
+      (op) => op.relationField === relationField
+    );
+    return new AggregateChanges<TEntityMap>(filtered);
+  }
+
   /**
    * Checks if there are create operations.
    */
@@ -319,6 +415,19 @@ export class AggregateChanges<TEntityMap = Record<string, any>> {
     return Array.from(entities);
   }
 
+  /**
+   * Lists all relation fields that have changes.
+   */
+  getAffectedRelations(): string[] {
+    const relations = new Set<string>();
+    this.ops.forEach((op) => {
+      if (op.relationField) {
+        relations.add(op.relationField);
+      }
+    });
+    return Array.from(relations);
+  }
+
   /**
    * Clears all operations.
    */

package/src/base-entity.ts

@@ -41,8 +41,17 @@ export abstract class BaseEntity<T extends BaseProps> {
       this,
       "validation"
     );
+
     const hooks = getStaticProperty<EntityHooks<T, any>>(this, "hooks");
 
+    if (!props.id) {
+      props.id = new Id();
+    }
+
+    if (hooks?.onBeforeCreate) {
+      hooks.onBeforeCreate(props as T);
+    }
+
     this.entityHooks = hooks;
 
     if (validation?.schema) {
@@ -56,10 +65,6 @@ export abstract class BaseEntity<T extends BaseProps> {
 
     let finalProps = { ...props } as T;
 
-    if (!finalProps.id) {
-      finalProps.id = new Id();
-    }
-
     if (this.entitySchema && this.validationConfig.onCreate) {
       this.validateProps(finalProps);
     }
@@ -100,7 +105,10 @@ export abstract class BaseEntity<T extends BaseProps> {
         result.issues.map((issue) => ({
           path: issue.path?.map((p) => this.extractPathKey(p)) || [],
           message: issue.message,
-        }))
+        })),
+        {
+          entityName: this.constructor.name,
+        }
       );
 
       if (this.validationConfig.throwOnError) {
@@ -134,7 +142,7 @@ export abstract class BaseEntity<T extends BaseProps> {
   private setupUpdateValidation(): void {
     const self = this;
 
-    this.tracker.setOnChangeValidator((path, oldValue, newValue) => {
+    this.tracker.setOnChangeValidator((path, newValue) => {
       const originalValue = self._props[path as keyof T];
       (self._props as any)[path] = newValue;
 
@@ -166,7 +174,10 @@ export abstract class BaseEntity<T extends BaseProps> {
               result.issues.map((issue) => ({
                 path: issue.path?.map((p) => self.extractPathKey(p)) || [],
                 message: issue.message,
-              }))
+              })),
+              {
+                entityName: self.constructor.name,
+              }
             );
 
             (self._props as any)[path] = originalValue;
@@ -228,7 +239,7 @@ export abstract class BaseEntity<T extends BaseProps> {
       obj.constructor.name !== "Array"
     ) {
       if (
-        typeof obj.toJson === "function" &&
+        typeof obj.toJSON === "function" &&
         typeof obj.equals === "function"
       ) {
         return obj;
@@ -376,7 +387,7 @@ export abstract class BaseEntity<T extends BaseProps> {
     return this.domainEvents.length > 0;
   }
 
-  toJson(): DeepJsonResult<T> {
+  toJSON(): DeepJsonResult<T> {
     return this.deepToJson(this._props) as DeepJsonResult<T>;
   }
 
@@ -385,8 +396,8 @@ export abstract class BaseEntity<T extends BaseProps> {
     if (obj instanceof Id) return obj.value;
     if (obj instanceof Date) return obj.toISOString();
     if (Array.isArray(obj)) return obj.map((item) => this.deepToJson(item));
-    if (obj instanceof BaseEntity) return obj.toJson();
-    if (obj && typeof obj.toJson === "function") return obj.toJson();
+    if (obj instanceof BaseEntity) return obj.toJSON();
+    if (obj && typeof obj.toJSON === "function") return obj.toJSON();
     if (typeof obj === "object") {
       const result: any = {};
       for (const key in obj) {

package/src/change-tracker.ts

@@ -9,11 +9,7 @@ import { AggregateChanges } from "./aggregate-changes";
  * Callback for validation on property change.
  * Return false to reject the change, or throw an error.
  */
-export type OnChangeValidator = (
-  path: string,
-  oldValue: any,
-  newValue: any
-) => boolean | void;
+export type OnChangeValidator = (path: string, newValue: any) => boolean | void;
 
 /**
  * Tracks changes in Aggregates using Proxy.
@@ -39,7 +35,9 @@ export class ChangeTracker {
     private rootEntityName: string,
     private path: string = "",
     private depth: number = 0,
+    // @ts-expect-error - This is a private property
     private parentId?: string,
+    // @ts-expect-error - This is a private property
     private parentEntity?: string,
     private rootTracker?: ChangeTracker
   ) {
@@ -195,11 +193,7 @@ export class ChangeTracker {
         const rootTracker = this.getRootTracker();
         if (rootTracker.onChangeValidator) {
           try {
-            const result = rootTracker.onChangeValidator(
-              currentPath,
-              oldValue,
-              newValue
-            );
+            const result = rootTracker.onChangeValidator(currentPath, newValue);
             if (result === false) {
               return true;
             }
@@ -272,7 +266,7 @@ export class ChangeTracker {
 
               if (rootTracker.onChangeValidator) {
                 try {
-                  const result = rootTracker.onChangeValidator(path, oldArray, [
+                  const result = rootTracker.onChangeValidator(path, [
                     ...oldArray,
                     ...args,
                   ]);
@@ -322,11 +316,7 @@ export class ChangeTracker {
 
           if (rootTracker.onChangeValidator) {
             try {
-              const result = rootTracker.onChangeValidator(
-                path,
-                oldArray,
-                newValue
-              );
+              const result = rootTracker.onChangeValidator(path, newValue);
               if (result === false) {
                 return true;
               }
@@ -431,9 +421,18 @@ export class ChangeTracker {
 
       const { depth, parentId, parentEntity } = arrayState.metadata;
 
+      const relationField = this.extractRelationField(path);
+
       for (const item of created) {
         const itemEntityName = this.getEntityName(item);
-        changes.addCreate(itemEntityName, item, depth, parentId, parentEntity);
+        changes.addCreate(
+          itemEntityName,
+          item,
+          depth,
+          parentId,
+          parentEntity,
+          relationField
+        );
 
         this.markNestedItemsAsCreated(item, depth, changes);
       }
@@ -458,7 +457,15 @@ export class ChangeTracker {
         if (id || key) {
           const itemEntityName = this.getEntityName(item);
           const deleteId = id || key!;
-          changes.addDelete(itemEntityName, deleteId, item, depth);
+          changes.addDelete(
+            itemEntityName,
+            deleteId,
+            item,
+            depth,
+            relationField,
+            parentId,
+            parentEntity
+          );
 
           this.markNestedItemsAsDeleted(item, depth, changes, rootTracker);
         }
@@ -476,37 +483,41 @@ export class ChangeTracker {
   ): void {
     if (!item || typeof item !== "object") return;
 
-    const itemId = this.getEntityId(item);
-    if (!itemId) return;
-
-    const props = item.props || item;
+    const propsToScan = item.props || item;
+    const parentId = this.getEntityId(item);
+    const parentEntity = this.getEntityName(item);
 
-    for (const [propName, value] of Object.entries(props)) {
+    for (const [propName, value] of Object.entries(propsToScan)) {
       if (propName === "id") continue;
 
       if (Array.isArray(value)) {
-        for (const nestedItem of value) {
-          if (this.isEntityOrVO(nestedItem)) {
-            const nestedId = this.getEntityId(nestedItem);
-            const nestedKey = this.getItemKey(nestedItem);
-            if (nestedId || nestedKey) {
-              const entityName = this.getEntityName(nestedItem);
-              changes.addCreate(
-                entityName,
-                nestedItem,
-                parentDepth + 1,
-                itemId,
-                this.getEntityName(item)
-              );
-
-              this.markNestedItemsAsCreated(
-                nestedItem,
-                parentDepth + 1,
-                changes
-              );
-            }
+        const relationField = propName;
+
+        for (const child of value) {
+          if (this.isEntityOrVO(child)) {
+            const childEntityName = this.getEntityName(child);
+            changes.addCreate(
+              childEntityName,
+              child,
+              parentDepth + 1,
+              parentId,
+              parentEntity,
+              relationField
+            );
+            this.markNestedItemsAsCreated(child, parentDepth + 1, changes);
           }
         }
+      } else if (this.isEntityOrVO(value)) {
+        const childEntityName = this.getEntityName(value);
+        changes.addCreate(
+          childEntityName,
+          value,
+          parentDepth + 1,
+          parentId,
+          parentEntity,
+          propName
+        );
+        this.markNestedItemsAsCreated(value, parentDepth + 1, changes);
       }
     }
   }
@@ -526,8 +537,12 @@ export class ChangeTracker {
     const itemId = this.getEntityId(item);
     if (!itemId) return;
 
-    for (const [, arrayState] of rootTracker.trackedArrays) {
+    for (const [path, arrayState] of rootTracker.trackedArrays) {
       if (arrayState.metadata.parentId === itemId) {
+        const relationField = this.extractRelationField(path);
+        const parentEntity = arrayState.metadata.parentEntity;
+        const parentId = arrayState.metadata.parentId;
+
         for (const nestedItem of arrayState.cloned) {
           const id =
             typeof nestedItem === "object" && nestedItem !== null
@@ -535,7 +550,15 @@ export class ChangeTracker {
               : undefined;
           if (id) {
             const entityName = arrayState.metadata.entityName;
-            changes.addDelete(entityName, id, nestedItem, parentDepth + 1);
+            changes.addDelete(
+              entityName,
+              id,
+              nestedItem,
+              parentDepth + 1,
+              relationField,
+              parentEntity,
+              parentId
+            );
 
             this.markNestedJsonItemAsDeleted(
               id,
@@ -559,21 +582,28 @@ export class ChangeTracker {
     changes: AggregateChanges<any>,
     rootTracker: ChangeTracker
   ): void {
-    for (const [, arrayState] of rootTracker.trackedArrays) {
+    for (const [path, arrayState] of rootTracker.trackedArrays) {
       if (arrayState.metadata.parentId === itemId) {
+        const relationField = this.extractRelationField(path);
+
         for (const nestedJsonItem of arrayState.cloned) {
           if (typeof nestedJsonItem !== "object" || nestedJsonItem === null)
             continue;
 
           const nestedId = nestedJsonItem.id;
           const entityName = arrayState.metadata.entityName;
+          const parentEntity = arrayState.metadata.parentEntity;
+          const parentId = arrayState.metadata.parentId;
 
           if (nestedId) {
             changes.addDelete(
               entityName,
               nestedId,
               nestedJsonItem,
-              parentDepth + 1
+              parentDepth + 1,
+              relationField,
+              parentId,
+              parentEntity
             );
 
             this.markNestedJsonItemAsDeleted(
@@ -592,7 +622,10 @@ export class ChangeTracker {
                 entityName,
                 key,
                 nestedJsonItem,
-                parentDepth + 1
+                parentDepth + 1,
+                relationField,
+                parentId,
+                parentEntity
               );
             }
           }
@@ -668,6 +701,8 @@ export class ChangeTracker {
       const { entityName, depth, parentId, parentEntity } =
         trackedItem.metadata;
 
+      const relationField = this.extractRelationField(path);
+
       const state = this.detectEntityChangeState(originalValue, currentValue);
 
       switch (state) {
@@ -677,28 +712,46 @@ export class ChangeTracker {
             currentValue,
             depth,
             parentId,
-            parentEntity
+            parentEntity,
+            relationField
           );
           break;
 
         case "deleted":
           const id = this.getEntityId(originalValue);
           if (id) {
-            changes.addDelete(entityName, id, originalEntity, depth);
+            changes.addDelete(
+              entityName,
+              id,
+              originalEntity,
+              depth,
+              relationField,
+              parentId,
+              parentEntity
+            );
           }
           break;
 
         case "replaced":
           const oldId = this.getEntityId(originalValue);
           if (oldId) {
-            changes.addDelete(entityName, oldId, originalEntity, depth);
+            changes.addDelete(
+              entityName,
+              oldId,
+              originalEntity,
+              depth,
+              relationField,
+              parentId,
+              parentEntity
+            );
           }
           changes.addCreate(
             entityName,
             currentValue,
             depth,
             parentId,
-            parentEntity
+            parentEntity,
+            relationField
           );
           break;
 
@@ -894,6 +947,12 @@ export class ChangeTracker {
     return current;
   }
 
+  private extractRelationField(path: string): string {
+    const withoutIndices = path.replace(/\[\d+\]/g, "");
+    const parts = withoutIndices.split(".");
+    return parts[parts.length - 1];
+  }
+
   private getItemKey(item: any): string | undefined {
     const id = this.getEntityId(item);
     if (id) return id;
@@ -998,8 +1057,8 @@ export class ChangeTracker {
       return obj.value;
     }
 
-    if (typeof obj.toJson === "function") {
-      return obj.toJson();
+    if (typeof obj.toJSON === "function") {
+      return obj.toJSON();
     }
 
     if (Array.isArray(obj)) {