@woltz/rich-domain 1.9.2 → 1.9.3

package/src/core/base-entity.ts

@@ -14,7 +14,10 @@ import {
 } from "../types/index.js";
 import { DEFAULT_VALIDATION_CONFIG } from "../constants.js";
 import { DomainError } from "../exceptions.js";
-import { ChangeTracker, AggregateChanges, Id, ValueObject } from "./index";
+import { AggregateChanges } from "./aggregate-changes.js";
+import { ChangeTracker } from "./change-tracker.js";
+import { Id } from "./id.js";
+import { ValueObject } from "./value-object.js";
 import { getStaticProperty } from "../utils/helpers.js";
 
 export abstract class BaseEntity<

package/src/core/change-tracker.ts

@@ -1,5 +1,5 @@
 import { Id } from "./id.js";
-import { Entity } from "./entity.js";
+import { BaseEntity } from "./base-entity.js";
 import { ValueObject } from "./value-object.js";
 import { ArrayState, HistoryEntry, TrackedItem } from "../types/index.js";
 import { EntityChangeState } from "../types/change-tracker.js";
@@ -97,7 +97,7 @@ export class ChangeTracker {
 
       if (Array.isArray(value)) {
         this.captureArrayState(value, propPath, depth + 1, id, entityName);
-      } else if (value instanceof Entity) {
+      } else if (value instanceof BaseEntity) {
         const nestedName = this.getEntityName(value);
         this.captureEntityState(
           value,
@@ -137,7 +137,7 @@ export class ChangeTracker {
     // Only track individual items for non-primitive arrays
     if (!isPrimitive) {
       arr.forEach((item, index) => {
-        if (item instanceof Entity) {
+        if (item instanceof BaseEntity) {
           const itemPath = `${path}[${index}]`;
           this.captureEntityState(
             item,
@@ -175,7 +175,7 @@ export class ChangeTracker {
           return this.createArrayProxy(value, currentPath);
         }
 
-        if (value instanceof Entity) {
+        if (value instanceof BaseEntity) {
           const nestedTracker = new ChangeTracker(
             value,
             this.getEntityName(value),
@@ -230,7 +230,10 @@ export class ChangeTracker {
 
         if (Array.isArray(newValue)) {
           this.handleArrayAssignment(currentPath, oldValue);
-        } else if (newValue instanceof Entity || oldValue instanceof Entity) {
+        } else if (
+          (newValue instanceof BaseEntity && !this.isSelfReference(newValue)) ||
+          (oldValue instanceof BaseEntity && !this.isSelfReference(oldValue))
+        ) {
           this.handleEntityChange(currentPath, oldValue, newValue);
         }
 
@@ -277,7 +280,7 @@ export class ChangeTracker {
 
         const result = Reflect.deleteProperty(target, prop);
 
-        if (oldValue instanceof Entity) {
+        if (oldValue instanceof BaseEntity && !this.isSelfReference(oldValue)) {
           this.handleEntityChange(currentPath, oldValue, undefined);
         }
 
@@ -359,7 +362,7 @@ export class ChangeTracker {
           return value.bind(target);
         }
 
-        if (!isNaN(Number(prop)) && value instanceof Entity) {
+        if (!isNaN(Number(prop)) && value instanceof BaseEntity) {
           const nestedPath = `${path}[${String(prop)}]`;
           const nestedTracker = new ChangeTracker(
             value,
@@ -454,7 +457,12 @@ export class ChangeTracker {
 
       // 1:1 entity relations are tracked by analyzeEntityChanges
       if (rootTracker.trackedEntities.has(path)) continue;
-      if (originalValue instanceof Entity || currentValue instanceof Entity) {
+      if (
+        (originalValue instanceof BaseEntity &&
+          !this.isSelfReference(originalValue)) ||
+        (currentValue instanceof BaseEntity &&
+          !this.isSelfReference(currentValue))
+      ) {
         continue;
       }
 
@@ -605,7 +613,7 @@ export class ChangeTracker {
         const relationField = propName;
 
         for (const child of value) {
-          if (child instanceof Entity) {
+          if (child instanceof BaseEntity) {
             const childEntityName = this.getEntityName(child);
             changes.addCreate(
               childEntityName,
@@ -618,7 +626,7 @@ export class ChangeTracker {
             this.markNestedItemsAsCreated(child, parentDepth + 1, changes);
           }
         }
-      } else if (value instanceof Entity) {
+      } else if (value instanceof BaseEntity) {
         const childEntityName = this.getEntityName(value);
         changes.addCreate(
           childEntityName,
@@ -667,8 +675,8 @@ export class ChangeTracker {
               nestedItem,
               parentDepth + 1,
               relationField,
-              parentEntity,
-              parentId
+              parentId,
+              parentEntity
             );
 
             this.markNestedJsonItemAsDeleted(
@@ -753,7 +761,7 @@ export class ChangeTracker {
     originalArray: any[]
   ): string | undefined {
     for (const originalItem of originalArray) {
-      if (originalItem instanceof Entity) {
+      if (originalItem instanceof BaseEntity) {
         const originalJson = this.deepClone(originalItem);
         if (JSON.stringify(originalJson) === JSON.stringify(jsonItem)) {
           const key = this.getItemKey(originalItem);
@@ -783,7 +791,7 @@ export class ChangeTracker {
 
       if (Array.isArray(value)) {
         value.forEach((item, index) => {
-          if (item instanceof Entity) {
+          if (item instanceof BaseEntity) {
             this.collectNestedArrays(
               item,
               `${propPath}[${index}]`,
@@ -792,7 +800,7 @@ export class ChangeTracker {
             );
           }
         });
-      } else if (value instanceof Entity) {
+      } else if (value instanceof BaseEntity) {
         this.collectNestedArrays(value, propPath, allArrays, processedArrays);
       }
     }
@@ -1000,7 +1008,7 @@ export class ChangeTracker {
         continue;
       }
 
-      if (currValue instanceof Entity) {
+      if (currValue instanceof BaseEntity) {
         continue;
       }
 
@@ -1053,6 +1061,12 @@ export class ChangeTracker {
     return this.rootTracker || this;
   }
 
+  private isSelfReference(value: BaseEntity<any>): boolean {
+    const targetId = this.getEntityId(this.target);
+    const valueId = this.getEntityId(value);
+    return !!targetId && !!valueId && targetId === valueId;
+  }
+
   private buildPath(prop: string): string {
     return this.path ? `${this.path}.${prop}` : prop;
   }

package/src/core/domain-event.ts

@@ -1,41 +1,41 @@
-import { IDomainEvent } from "..";
-import UUID from "../utils/crypto";
-
-/**
- * Base class for domain events
- */
-export abstract class DomainEvent<P> implements IDomainEvent<P> {
-  public readonly eventId: string;
-  public readonly occurredOn: Date;
-  public readonly payload: P;
-  static readonly queueName?: string;
-
-  constructor(payload: P) {
-    this.eventId = this.generateEventId();
-    this.occurredOn = new Date();
-    this.payload = payload;
-  }
-
-  /**
-   * Get the event name (defaults to class name)
-   */
-  get eventName(): string {
-    return this.constructor.name;
-  }
-
-  /**
-   * Generate a UUID v4
-   */
-  private generateEventId(): string {
-    return UUID();
-  }
-
-  toJSON() {
-    return {
-      eventId: this.eventId,
-      eventName: this.eventName,
-      occurredOn: this.occurredOn.toISOString(),
-      payload: this.payload,
-    };
-  }
-}
+import type { IDomainEvent } from "../types/domain-event.js";
+import UUID from "../utils/crypto.js";
+
+/**
+ * Base class for domain events
+ */
+export abstract class DomainEvent<P> implements IDomainEvent<P> {
+  public readonly eventId: string;
+  public readonly occurredOn: Date;
+  public readonly payload: P;
+  static readonly queueName?: string;
+
+  constructor(payload: P) {
+    this.eventId = this.generateEventId();
+    this.occurredOn = new Date();
+    this.payload = payload;
+  }
+
+  /**
+   * Get the event name (defaults to class name)
+   */
+  get eventName(): string {
+    return this.constructor.name;
+  }
+
+  /**
+   * Generate a UUID v4
+   */
+  private generateEventId(): string {
+    return UUID();
+  }
+
+  toJSON() {
+    return {
+      eventId: this.eventId,
+      eventName: this.eventName,
+      occurredOn: this.occurredOn.toISOString(),
+      payload: this.payload,
+    };
+  }
+}

package/src/core/{entity.ts → entities.ts}

@@ -1,13 +1,13 @@
-import { BaseEntity } from "./base-entity.js";
-import { BaseAggregate } from "./base-aggregate.js";
-import { BaseProps } from "../types/index.js";
-
-export class Entity<
-  T extends BaseProps,
-  TOptionalInput extends keyof T = never,
-> extends BaseEntity<T, TOptionalInput> {}
-
-export class Aggregate<
-  T extends BaseProps,
-  TOptionalInput extends keyof T = never,
-> extends BaseAggregate<T, TOptionalInput> {}
+import { BaseEntity } from "./base-entity.js";
+import { BaseAggregate } from "./base-aggregate.js";
+import { BaseProps } from "../types/index.js";
+
+export class Entity<
+  T extends BaseProps,
+  TOptionalInput extends keyof T = never,
+> extends BaseEntity<T, TOptionalInput> {}
+
+export class Aggregate<
+  T extends BaseProps,
+  TOptionalInput extends keyof T = never,
+> extends BaseAggregate<T, TOptionalInput> {}

package/src/core/index.ts

@@ -1,9 +1,9 @@
-export * from "./base-entity";
-export * from "./base-aggregate";
-export * from "./aggregate-changes";
-export * from "./change-tracker";
-export * from "./domain-event";
-export * from "./entity-changes";
-export * from "./entity";
-export * from "./id";
-export * from "./value-object";
+export * from "./base-entity.js";
+export * from "./base-aggregate.js";
+export * from "./aggregate-changes.js";
+export * from "./change-tracker.js";
+export * from "./domain-event.js";
+export * from "./entity-changes.js";
+export * from "./entities.js";
+export * from "./id.js";
+export * from "./value-object.js";

package/src/core/value-object.ts

@@ -1,179 +1,179 @@
-import {
-  ValidationError,
-  ValidationIssue,
-  ValidationIssueCollector,
-} from "../validation-error.js";
-import {
-  VOHooks,
-  ValidationConfig,
-  StandardSchema,
-  EntityValidation,
-  Primitive,
-} from "../types/index.js";
-import { DEFAULT_VALIDATION_CONFIG } from "../constants.js";
-import { DomainError } from "../exceptions.js";
-import { getStaticProperty } from "../utils/helpers.js";
-
-export abstract class ValueObject<T extends Primitive> {
-  public readonly value!: T;
-  private validationConfig: Required<ValidationConfig>;
-  private domainHooks?: VOHooks<T, any>;
-  private domainSchema?: StandardSchema<T>;
-  private readonly issueCollector = new ValidationIssueCollector();
-
-  protected static validation?: EntityValidation<any>;
-  protected static hooks?: VOHooks<any, any>;
-
-  constructor(value: T) {
-    const validation = getStaticProperty<EntityValidation<T>>(
-      this,
-      "validation"
-    );
-    const hooks = getStaticProperty<VOHooks<T, any>>(this, "hooks");
-
-    if (hooks?.onBeforeCreate) {
-      hooks.onBeforeCreate(value);
-    }
-
-    this.domainHooks = hooks;
-
-    if (validation?.schema) {
-      this.domainSchema = validation.schema;
-    }
-
-    this.validationConfig = {
-      ...DEFAULT_VALIDATION_CONFIG,
-      ...validation?.config,
-    };
-
-    if (this.domainSchema && this.validationConfig.onCreate) {
-      this.validateValue(value);
-    }
-
-    this.value = value;
-
-    if (hooks?.rules) {
-      this.runRulesHook();
-    }
-
-    Object.freeze(this);
-  }
-
-  /**
-   * Add a validation issue during rules hook execution (non-throwing mode).
-   */
-  public addValidationIssue(path: string | string[], message: string): void {
-    this.issueCollector.add(path, message);
-  }
-
-  private beginValidationCycle(): void {
-    this.issueCollector.clear();
-  }
-
-  private finalizeValidation(collectedIssues: ValidationIssue[] = []): void {
-    const existing = (this as any)._validationError as
-      | ValidationError
-      | undefined;
-    const merged = ValidationError.merge(existing, collectedIssues);
-
-    if (!merged) {
-      delete (this as any)._validationError;
-      return;
-    }
-
-    if (this.validationConfig.throwOnError) {
-      throw merged;
-    }
-
-    (this as any)._validationError = merged;
-  }
-
-  private runRulesHook(): void {
-    if (!this.domainHooks?.rules) return;
-
-    this.beginValidationCycle();
-    this.domainHooks.rules(this as any);
-    this.finalizeValidation([...this.issueCollector.getIssues()]);
-  }
-
-  private validateValue(value: T): void {
-    const schemaError = this.validateSchema(value);
-    if (!schemaError) return;
-
-    if (this.validationConfig.throwOnError) {
-      throw schemaError;
-    }
-
-    (this as any)._validationError = schemaError;
-  }
-
-  private validateSchema(value: T): ValidationError | null {
-    if (!this.domainSchema) return null;
-
-    const result = this.domainSchema["~standard"].validate(value);
-
-    if (result instanceof Promise) {
-      throw new DomainError(
-        "Async validation not supported in constructor. Use sync validation schema."
-      );
-    }
-
-    if (result.issues && result.issues.length > 0) {
-      return new ValidationError(
-        result.issues.map((issue) => ({
-          path: issue.path?.map((p) => this.extractPathKey(p)) || [],
-          message: issue.message,
-        }))
-      );
-    }
-
-    return null;
-  }
-
-  private extractPathKey(pathSegment: unknown): string {
-    if (pathSegment === null || pathSegment === undefined) {
-      return "";
-    }
-    if (typeof pathSegment === "string" || typeof pathSegment === "number") {
-      return String(pathSegment);
-    }
-    if (typeof pathSegment === "symbol") {
-      return pathSegment.toString();
-    }
-    if (typeof pathSegment === "object" && "key" in pathSegment) {
-      return String((pathSegment as { key: unknown }).key);
-    }
-    return String(pathSegment);
-  }
-
-  /**
-   * Returns true if the value object has validation errors (when throwOnError is false).
-   */
-  get hasValidationErrors(): boolean {
-    return !!(this as any)._validationError;
-  }
-
-  /**
-   * 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 this.value === other.value;
-  }
-
-  /**
-   * Creates a new ValueObject with updated value.
-   * ValueObjects are immutable, so this returns a new instance.
-   */
-  protected clone(value: T): this {
-    const Constructor = this.constructor as new (value: T) => this;
-    return new Constructor(value);
-  }
-}
+import {
+  ValidationError,
+  ValidationIssue,
+  ValidationIssueCollector,
+} from "../validation-error.js";
+import {
+  VOHooks,
+  ValidationConfig,
+  StandardSchema,
+  EntityValidation,
+  Primitive,
+} from "../types/index.js";
+import { DEFAULT_VALIDATION_CONFIG } from "../constants.js";
+import { DomainError } from "../exceptions.js";
+import { getStaticProperty } from "../utils/helpers.js";
+
+export abstract class ValueObject<T extends Primitive> {
+  public readonly value!: T;
+  private validationConfig: Required<ValidationConfig>;
+  private domainHooks?: VOHooks<T, any>;
+  private domainSchema?: StandardSchema<T>;
+  private readonly issueCollector = new ValidationIssueCollector();
+
+  protected static validation?: EntityValidation<any>;
+  protected static hooks?: VOHooks<any, any>;
+
+  constructor(value: T) {
+    const validation = getStaticProperty<EntityValidation<T>>(
+      this,
+      "validation"
+    );
+    const hooks = getStaticProperty<VOHooks<T, any>>(this, "hooks");
+
+    if (hooks?.onBeforeCreate) {
+      hooks.onBeforeCreate(value);
+    }
+
+    this.domainHooks = hooks;
+
+    if (validation?.schema) {
+      this.domainSchema = validation.schema;
+    }
+
+    this.validationConfig = {
+      ...DEFAULT_VALIDATION_CONFIG,
+      ...validation?.config,
+    };
+
+    if (this.domainSchema && this.validationConfig.onCreate) {
+      this.validateValue(value);
+    }
+
+    this.value = value;
+
+    if (hooks?.rules) {
+      this.runRulesHook();
+    }
+
+    Object.freeze(this);
+  }
+
+  /**
+   * Add a validation issue during rules hook execution (non-throwing mode).
+   */
+  public addValidationIssue(path: string | string[], message: string): void {
+    this.issueCollector.add(path, message);
+  }
+
+  private beginValidationCycle(): void {
+    this.issueCollector.clear();
+  }
+
+  private finalizeValidation(collectedIssues: ValidationIssue[] = []): void {
+    const existing = (this as any)._validationError as
+      | ValidationError
+      | undefined;
+    const merged = ValidationError.merge(existing, collectedIssues);
+
+    if (!merged) {
+      delete (this as any)._validationError;
+      return;
+    }
+
+    if (this.validationConfig.throwOnError) {
+      throw merged;
+    }
+
+    (this as any)._validationError = merged;
+  }
+
+  private runRulesHook(): void {
+    if (!this.domainHooks?.rules) return;
+
+    this.beginValidationCycle();
+    this.domainHooks.rules(this as any);
+    this.finalizeValidation([...this.issueCollector.getIssues()]);
+  }
+
+  private validateValue(value: T): void {
+    const schemaError = this.validateSchema(value);
+    if (!schemaError) return;
+
+    if (this.validationConfig.throwOnError) {
+      throw schemaError;
+    }
+
+    (this as any)._validationError = schemaError;
+  }
+
+  private validateSchema(value: T): ValidationError | null {
+    if (!this.domainSchema) return null;
+
+    const result = this.domainSchema["~standard"].validate(value);
+
+    if (result instanceof Promise) {
+      throw new DomainError(
+        "Async validation not supported in constructor. Use sync validation schema."
+      );
+    }
+
+    if (result.issues && result.issues.length > 0) {
+      return new ValidationError(
+        result.issues.map((issue) => ({
+          path: issue.path?.map((p) => this.extractPathKey(p)) || [],
+          message: issue.message,
+        }))
+      );
+    }
+
+    return null;
+  }
+
+  private extractPathKey(pathSegment: unknown): string {
+    if (pathSegment === null || pathSegment === undefined) {
+      return "";
+    }
+    if (typeof pathSegment === "string" || typeof pathSegment === "number") {
+      return String(pathSegment);
+    }
+    if (typeof pathSegment === "symbol") {
+      return pathSegment.toString();
+    }
+    if (typeof pathSegment === "object" && "key" in pathSegment) {
+      return String((pathSegment as { key: unknown }).key);
+    }
+    return String(pathSegment);
+  }
+
+  /**
+   * Returns true if the value object has validation errors (when throwOnError is false).
+   */
+  get hasValidationErrors(): boolean {
+    return !!(this as any)._validationError;
+  }
+
+  /**
+   * 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 this.value === other.value;
+  }
+
+  /**
+   * Creates a new ValueObject with updated value.
+   * ValueObjects are immutable, so this returns a new instance.
+   */
+  protected clone(value: T): this {
+    const Constructor = this.constructor as new (value: T) => this;
+    return new Constructor(value);
+  }
+}