@woltz/rich-domain 1.9.0 → 1.9.2

package/src/core/domain-event.ts

@@ -0,0 +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,
+    };
+  }
+}

package/src/core/entity-changes.ts

@@ -0,0 +1,146 @@
+import {
+  Operation,
+  CreateOperation,
+  UpdateOperation,
+  DeleteOperation,
+} from "../types/change-tracker.js";
+
+/**
+ * Represents the changes filtered for a specific entity.
+ *
+ * @example
+ * ```typescript
+ * const changes = user.getChanges();
+ * const postChanges = changes.of('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;
+  }
+}

package/src/core/entity.ts

@@ -0,0 +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> {}

package/src/core/id.ts

@@ -0,0 +1,124 @@
+import UUID from "../utils/crypto.js";
+
+export class Id {
+  private readonly _value: string;
+  private _isNew: boolean;
+
+  /**
+   * Create a new Id
+   * @param value - Optional existing ID value. If not provided, generates a new UUID.
+   *
+   * @example
+   * // New entity (generates UUID)
+   * const newId = new Id();
+   * newuser.isNew() // true
+   *
+   * // Existing entity (uses provided ID)
+   * const existingId = new Id("550e8400-e29b-41d4-a716-446655440000");
+   * existinguser.isNew() // false
+   */
+  constructor(value: string, isNew?: boolean);
+  constructor(value?: string);
+  constructor(value?: string, isNew?: boolean) {
+    if (value !== undefined) {
+      // ID was provided - this is an existing entity
+      this._value = value;
+      this._isNew = isNew ?? false;
+    } else {
+      // No ID provided - generate new one, this is a new entity
+      this._value = this.generateUUID();
+      this._isNew = true;
+    }
+  }
+
+  /**
+   * Get the string value of the ID
+   */
+  get value(): string {
+    return this._value;
+  }
+
+  /**
+   * Check if this ID represents a new entity
+   */
+  public isNew(): boolean {
+    return this._isNew;
+  }
+
+  /**
+   * Convert to string (for JSON serialization and comparisons)
+   */
+  toString(): string {
+    return this._value;
+  }
+
+  /**
+   * Convert to JSON (returns the string value)
+   */
+  toJSON(): string {
+    return this._value;
+  }
+
+  /**
+   * Check equality with another Id or string
+   */
+  equals(other: Id | string): boolean {
+    if (other instanceof Id) {
+      return this._value === other._value;
+    }
+    return this._value === other;
+  }
+
+  /**
+   * Generate a UUID v4
+   */
+  private generateUUID(): string {
+    // Simple UUID v4 implementation
+    return UUID();
+  }
+
+  /**
+   * Create a new Id (convenience static method)
+   */
+  static create(): Id {
+    return new Id();
+  }
+
+  /**
+   * Mark the Id as not new
+   */
+  public markAsNotNew(): void {
+    this._isNew = false;
+  }
+
+  /**
+   * Mark the Id as new
+   */
+  public markAsNew(): void {
+    this._isNew = true;
+  }
+
+  /**
+   * Create an Id from an existing value
+   */
+  static from(value: string): Id {
+    return new Id(value);
+  }
+
+  /**
+   * Compose two IDs into a single ID
+   * @param a - The first ID
+   * @param b - The second ID
+   * @returns The composed ID
+   */
+  static compose(a: string | Id, b: string | Id): string {
+    if (a instanceof Id) {
+      a = a.value;
+    }
+    if (b instanceof Id) {
+      b = b.value;
+    }
+
+    return `${a}-${b}`;
+  }
+}

package/src/core/index.ts

@@ -0,0 +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";

package/src/core/value-object.ts

@@ -0,0 +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);
+  }
+}