@woltz/rich-domain 1.2.0 → 1.2.1

package/src/id.ts

@@ -2,42 +2,33 @@
 // Id Class - Smart Identity Management
 // ============================================================================
 
-function randomUUID(): string {
-  // If we are in the browser, use the browser's crypto API
-  // @ts-expect-error - window.crypto is not defined in the browser
-  if (typeof window !== "undefined" && window.crypto) {
-    // @ts-expect-error - window.crypto is not defined in the browser
-    return window.crypto.randomUUID();
-  }
-  // If we are in the server, use the crypto library
-  // eslint-disable-next-line @typescript-eslint/no-require-imports
-  const crypto = require("crypto");
-
-  return crypto.randomUUID();
-}
+import UUID from "./crypto";
 
 export class Id {
   private readonly _value: string;
   private readonly _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) {
+  *
+  * @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 = false;
+      this._isNew = isNew ?? false;
     } else {
       // No ID provided - generate new one, this is a new entity
       this._value = this.generateUUID();
@@ -88,7 +79,7 @@ export class Id {
    */
   private generateUUID(): string {
     // Simple UUID v4 implementation
-    return randomUUID();
+    return UUID();
   }
 
   /**

package/src/index.ts

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

package/src/mapper.ts

@@ -1,3 +1,6 @@
 export abstract class Mapper<Input, Output> {
-  public abstract build(input: Input, ...args: unknown[]): Output;
+  public abstract build(
+    input: Input,
+    ...args: unknown[]
+  ): Output | Promise<Output>;
 }

package/src/repository/base-repository.ts

@@ -1,57 +1,26 @@
-// ============================================================================
-// Base Repository - Abstract implementation with common logic
-// ============================================================================
-
 import type { Aggregate } from "../entity";
 import type { Criteria } from "../criteria";
 import { PaginatedResult } from "../paginated-result";
 import { Mapper } from "../mapper";
 
-/**
- * Abstract base repository
- * Implements common logic, delegates persistence to subclasses
- *
- * @example
- * ```ts
- * class UserRepository extends BaseRepository<User, PrismaUser> {
- *   constructor(prisma: PrismaClient) {
- *     super(new UserMapper());
- *     this.prisma = prisma;
- *   }
- *
- *   protected async insertOne(data: PrismaUser): Promise<PrismaUser> {
- *     return this.prisma.user.create({ data });
- *   }
- *
- *   protected async updateOne(id: string, data: PrismaUser): Promise<PrismaUser> {
- *     return this.prisma.user.update({ where: { id }, data });
- *   }
- *
- *   // ... implement other abstract methods
- * }
- * ```
- */
-
 export abstract class ReadRepository<Agg extends Aggregate<any>> {
-  abstract find(criteria: Criteria<Agg>): Promise<PaginatedResult<Agg>>;
+  abstract find(criteria?: Criteria<Agg>): Promise<PaginatedResult<Agg>>;
   abstract findById(id: string): Promise<Agg | null>;
-  abstract count(criteria: Criteria<Agg>): Promise<number>;
+  abstract count(criteria?: Criteria<Agg>): Promise<number>;
   abstract exists(id: string): Promise<boolean>;
 }
 
 export abstract class WriteRepository<Agg extends Aggregate<any>> {
-  abstract create(entity: Agg): Promise<void>;
-  abstract update(entity: Agg): Promise<void>;
+  abstract save(entity: Agg): Promise<void>;
   abstract delete(entity: Agg): Promise<void>;
 }
 
 export abstract class WriteAndRead<Agg extends Aggregate<any>> {
-  abstract find(criteria: Criteria<Agg>): Promise<PaginatedResult<Agg>>;
+  abstract find(criteria?: Criteria<Agg>): Promise<PaginatedResult<Agg>>;
   abstract findById(id: string): Promise<Agg | null>;
-  abstract create(entity: Agg): Promise<void>;
-  abstract update(entity: Agg): Promise<void>;
+  abstract save(entity: Agg): Promise<void>;
   abstract delete(entity: Agg): Promise<void>;
-  abstract count(criteria: Criteria<Agg>): Promise<number>;
+  abstract count(criteria?: Criteria<Agg>): Promise<number>;
   abstract exists(id: string): Promise<boolean>;
 }
 

package/src/repository/unit-of-work.ts

@@ -7,31 +7,6 @@ import type { IUnitOfWork, TransactionContext } from "../types";
 /**
  * Abstract Unit of Work
  * Provides transaction management across multiple repositories
- *
- * @example
- * ```ts
- * // Using transaction helper (recommended)
- * await uow.transaction(async (ctx) => {
- *   const userRepo = uow.getRepository(UserRepository);
- *   const orderRepo = uow.getRepository(OrderRepository);
- *
- *   await userRepo.save(user);
- *   await orderRepo.save(order);
- *
- *   // Auto-commits on success, rolls back on error
- * });
- *
- * // Manual control
- * const ctx = await uow.begin();
- * try {
- *   await userRepo.save(user);
- *   await orderRepo.save(order);
- *   await ctx.commit();
- * } catch (error) {
- *   await ctx.rollback();
- *   throw error;
- * }
- * ```
  */
 export abstract class UnitOfWork implements IUnitOfWork {
   protected currentContext: TransactionContext | null = null;

package/src/types/change-tracker.ts

@@ -0,0 +1,221 @@
+import { Entity } from "../entity";
+import { ValueObject } from "../value-object";
+
+/**
+ * Base operation with common information.
+ */
+export interface BaseOperation {
+  /** Entity name in the domain (e.g., 'User', 'Post', 'Comment') */
+  entity: string;
+  /** Depth in the aggregate tree (0 = root, 1 = direct children, etc.) */
+  depth: number;
+}
+
+/**
+ * Create operation.
+ */
+export interface CreateOperation<T = any> extends BaseOperation {
+  type: "create";
+  /** Entity data to be created */
+  data: T;
+  /** Parent ID (for FK) */
+  parentId?: string;
+  /** Parent entity name */
+  parentEntity?: string;
+}
+
+/**
+ * Update operation.
+ */
+export interface UpdateOperation<T = any> extends BaseOperation {
+  type: "update";
+  /** Entity ID */
+  id: string;
+  /** Current entity instance */
+  data: T;
+  /** Only fields that have changed */
+  changedFields: Record<string, any>;
+}
+
+/**
+ * Delete operation.
+ */
+export interface DeleteOperation<T = any> extends BaseOperation {
+  type: "delete";
+  /** Entity ID to be deleted */
+  id: string;
+  /** Entity data (for reference) */
+  data: T;
+}
+
+/**
+ * Union of all possible operations.
+ */
+export type Operation<T = any> =
+  | CreateOperation<T>
+  | UpdateOperation<T>
+  | DeleteOperation<T>;
+
+/**
+ * Item for batch creation.
+ */
+export interface BatchCreateItem<T = any> {
+  /** Entity data */
+  data: T;
+  /** Parent ID (for FK) */
+  parentId?: string;
+}
+
+/**
+ * Item for batch update.
+ */
+export interface BatchUpdateItem {
+  /** Entity ID */
+  id: string;
+  /** Fields that have changed */
+  changedFields: Record<string, any>;
+}
+
+/**
+ * Grouped and ordered operations for batch execution.
+ */
+export interface BatchOperations {
+  /**
+   * Deletes grouped by entity, ordered by depth descending (leaf → root).
+   */
+  deletes: Array<{
+    entity: string;
+    depth: number;
+    ids: string[];
+  }>;
+
+  /**
+   * Creates grouped by entity, ordered by depth ascending (root → leaf).
+   */
+  creates: Array<{
+    entity: string;
+    depth: number;
+    items: BatchCreateItem[];
+  }>;
+
+  /**
+   * Updates grouped by entity.
+   */
+  updates: Array<{
+    entity: string;
+    items: BatchUpdateItem[];
+  }>;
+}
+
+/**
+ * Changes detected in a collection (1:N).
+ */
+export interface CollectionChanges<T = any> {
+  /** Created items */
+  created: T[];
+  /** Updated items with their changes */
+  updated: Array<{
+    entity: T;
+    changes: Record<string, { from: any; to: any }>;
+  }>;
+  /** Deleted items */
+  deleted: T[];
+}
+
+/**
+ * Possible states for a 1:1 relationship.
+ */
+export type EntityChangeState =
+  | "created"    // null → Entity
+  | "updated"    // Entity(id:1) → Entity(id:1) with changes
+  | "deleted"    // Entity → null
+  | "replaced"   // Entity(id:1) → Entity(id:2)
+  | "unchanged"; // No changes
+
+/**
+ * Change in a 1:1 entity relationship.
+ */
+export interface EntityChange<T = any> {
+  /** State of the change */
+  state: EntityChangeState;
+  /** Current entity (null if deleted) */
+  current: T | null;
+  /** Previous entity (null if created) */
+  previous: T | null;
+  /** Field changes (if state === 'updated') */
+  changes?: Record<string, { from: any; to: any }>;
+}
+
+/**
+ * Change in a primitive field.
+ */
+export interface FieldChange<T = any> {
+  from: T;
+  to: T;
+}
+
+/**
+ * Extracts the props type from an Entity or ValueObject.
+ */
+export type ExtractProps<T> = T extends Entity<infer P>
+  ? P
+  : T extends ValueObject<infer P>
+  ? P
+  : never;
+
+/**
+ * Keys of primitive properties (not Entity, ValueObject or Array).
+ */
+export type PrimitiveKeys<T> = {
+  [K in keyof T]: T[K] extends
+    | Entity<any>
+    | ValueObject<any>
+    | Array<any>
+    | undefined
+    ? never
+    : K;
+}[keyof T];
+
+/**
+ * Keys of collections (arrays).
+ */
+export type CollectionKeys<T> = {
+  [K in keyof T]: T[K] extends Array<any> ? K : never;
+}[keyof T];
+
+/**
+ * Keys of single entities (1:1).
+ */
+export type SingleEntityKeys<T> = {
+  [K in keyof T]: T[K] extends Entity<any> | ValueObject<any> | null | undefined
+    ? T[K] extends Array<any>
+      ? never
+      : K
+    : never;
+}[keyof T];
+
+/**
+ * Change history entry.
+ */
+export interface HistoryEntry {
+  path: string;
+  previousValue: any;
+  currentValue: any;
+  timestamp: number;
+}
+
+/**
+ * Metadata from a tracked entity/VO.
+ */
+export interface TrackedEntityMetadata {
+  /** Entity name */
+  entityName: string;
+  /** Depth in the tree */
+  depth: number;
+  /** Parent ID */
+  parentId?: string;
+  /** Parent entity name */
+  parentEntity?: string;
+  /** Path in the object (e.g., 'posts[0].comments[1]') */
+  path: string;
+}

package/src/types/criteria.ts

@@ -118,6 +118,11 @@ export interface Order {
   direction: OrderDirection;
 }
 
+export type TypedOrder<T> = {
+  field: FieldPath<T>;
+  direction: OrderDirection;
+};
+
 export interface Pagination {
   page: number;
   limit: number;
@@ -153,5 +158,5 @@ export type FieldPath<T> = T extends Primitive
         ? U extends Primitive
           ? K
           : K | `${K}.${FieldPath<U>}`
-        : K | `${K}.${FieldPath<NonNullable<T[K]>>}`;
+        : `${K}.${FieldPath<NonNullable<T[K]>>}`;
     }[ExcludeBuiltInKeys<T> & string];

package/src/types/history-tracker.ts

@@ -1,3 +1,4 @@
+import { TrackedEntityMetadata } from "./change-tracker";
 import { BaseProps } from "./domain";
 import { IsArray, NonUndefined, UnwrapArray } from "./utils";
 
@@ -7,6 +8,18 @@ export interface ChangeEvent<T> {
   path: string;
 }
 
+export interface TrackedItem {
+  entity: any;
+  metadata: TrackedEntityMetadata;
+  originalState: any;
+}
+
+export interface ArrayState {
+  cloned: any[];
+  original: any[];
+  metadata: TrackedEntityMetadata;
+}
+
 export interface ArrayChangeEvent<T> {
   toCreate: T[];
   toUpdate: T[];

package/src/types/utils.ts

@@ -14,16 +14,7 @@ export type DeepJsonResult<T> = {
     : T[K];
 };
 
-export type DeepKeyOf<T, K extends keyof T = keyof T> = K extends string
-  ? T[K] extends Primitive
-    ? K
-    : T[K] extends object
-    ? `${K}` | `${K}.${DeepKeyOf<T[K]>}`
-    : never
-  : never;
-
 export type Primitive = string | number | boolean | Date | null | undefined;
-
 export type UnwrapArray<T> = T extends Array<infer U> ? U : never;
 export type IsArray<T> = T extends Array<any> ? true : false;
 export type NonUndefined<T> = T extends undefined ? never : T;

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;