@woltz/rich-domain 0.2.1

package/src/deep-proxy.ts

@@ -0,0 +1,339 @@
+// ============================================================================
+// Deep Proxy - Core Change Tracking
+// ============================================================================
+
+import { Id } from './id';
+import { HistoryEntry } from './types';
+
+export class DeepProxy {
+  private history: HistoryEntry[] = [];
+  private subscribers: Map<string, Set<Function>> = new Map();
+  private originalValues: Map<string, any> = new Map();
+  private trackedArraysCloned: Map<string, any[]> = new Map();
+  private trackedArraysOriginal: Map<string, any[]> = new Map();
+  private globalSubscribers: Set<Function> = new Set();
+  private updateInProgress: boolean = false;
+  private pendingNotifications: Array<() => void> = [];
+
+  constructor(
+    private target: any,
+    private path: string = '',
+    private rootProxy?: DeepProxy
+  ) {
+    if (!rootProxy) this.rootProxy = this;
+  }
+
+  createProxy(): any {
+    const handler: ProxyHandler<any> = {
+      get: (target, prop, receiver) => {
+        const value = Reflect.get(target, prop, receiver);
+        const currentPath = this.path
+          ? `${this.path}.${String(prop)}`
+          : String(prop);
+
+        if (
+          prop === '__isProxy' ||
+          prop === '__originalTarget' ||
+          prop === '__path' ||
+          prop === 'constructor' ||
+          prop === 'prototype'
+        ) {
+          return value;
+        }
+
+        if (typeof value === 'function') return value.bind(target);
+
+        if (Array.isArray(value)) {
+          if (!this.rootProxy!.trackedArraysCloned.has(currentPath)) {
+            this.rootProxy!.storeArrayState(currentPath, value);
+          }
+          return this.createArrayProxy(value, currentPath);
+        }
+
+        if (value && typeof value === 'object' && !value.__isProxy) {
+          const nestedProxy = new DeepProxy(value, currentPath, this.rootProxy);
+          return nestedProxy.createProxy();
+        }
+
+        return value;
+      },
+
+      set: (target, prop, newValue, receiver) => {
+        const currentPath = this.path
+          ? `${this.path}.${String(prop)}`
+          : String(prop);
+        const oldValue = Reflect.get(target, prop, receiver);
+        const isArrayAssignment = Array.isArray(newValue);
+
+        if (!isArrayAssignment && oldValue === newValue) return true;
+
+        if (!this.rootProxy!.originalValues.has(currentPath)) {
+          this.rootProxy!.originalValues.set(currentPath, oldValue);
+        }
+
+        this.rootProxy!.history.push({
+          path: currentPath,
+          previousValue: oldValue,
+          currentValue: newValue,
+          timestamp: Date.now(),
+        });
+
+        const result = Reflect.set(target, prop, newValue, receiver);
+
+        if (isArrayAssignment) {
+          if (!this.rootProxy!.trackedArraysCloned.has(currentPath)) {
+            if (Array.isArray(oldValue)) {
+              this.rootProxy!.storeArrayState(currentPath, oldValue);
+            } else {
+              this.rootProxy!.storeArrayState(currentPath, []);
+            }
+          }
+          this.rootProxy!.scheduleNotification(() =>
+            this.rootProxy!.notifyArrayChange(currentPath, newValue)
+          );
+        } else {
+          this.rootProxy!.scheduleNotification(() =>
+            this.rootProxy!.notifySubscribers(currentPath, oldValue, newValue)
+          );
+        }
+
+        // Notify global subscribers
+        this.rootProxy!.scheduleNotification(() =>
+          this.rootProxy!.notifyGlobalSubscribers()
+        );
+
+        this.rootProxy!.flushNotifications();
+
+        return result;
+      },
+    };
+
+    const proxy = new Proxy(this.target, handler);
+    Object.defineProperty(proxy, '__isProxy', { value: true, writable: false });
+    return proxy;
+  }
+
+  private scheduleNotification(notification: () => void): void {
+    this.pendingNotifications.push(notification);
+  }
+
+  private flushNotifications(): void {
+    if (this.updateInProgress) return;
+
+    this.updateInProgress = true;
+    try {
+      const notifications = [...this.pendingNotifications];
+      this.pendingNotifications = [];
+      notifications.forEach((notify) => notify());
+    } finally {
+      this.updateInProgress = false;
+    }
+  }
+
+  private storeArrayState(path: string, arr: any[]): void {
+    this.trackedArraysCloned.set(path, this.cloneArray(arr));
+    this.trackedArraysOriginal.set(path, arr.slice());
+  }
+
+  private createArrayProxy(array: any[], path: string): any[] {
+    const self = this;
+    return new Proxy(array, {
+      get(target, prop, receiver) {
+        const value = Reflect.get(target, prop, receiver);
+        if (typeof value === 'function') {
+          const mutatingMethods = [
+            'push',
+            'pop',
+            'shift',
+            'unshift',
+            'splice',
+            'sort',
+            'reverse',
+          ];
+          if (mutatingMethods.includes(String(prop))) {
+            return function (...args: any[]) {
+              const result = value.apply(target, args);
+              if (!self.rootProxy!.trackedArraysCloned.has(path)) {
+                self.rootProxy!.storeArrayState(path, target);
+              }
+              self.rootProxy!.notifyArrayChange(path, target);
+              self.rootProxy!.notifyGlobalSubscribers();
+              return result;
+            };
+          }
+          return value.bind(target);
+        }
+        if (typeof value === 'object' && value !== null && !value.__isProxy) {
+          const nestedPath = `${path}[${String(prop)}]`;
+          const nestedProxy = new DeepProxy(value, nestedPath, self.rootProxy);
+          return nestedProxy.createProxy();
+        }
+        return value;
+      },
+      set(target, prop, newValue, receiver) {
+        if (!isNaN(Number(prop))) {
+          const result = Reflect.set(target, prop, newValue, receiver);
+          if (!self.rootProxy!.trackedArraysCloned.has(path)) {
+            self.rootProxy!.storeArrayState(path, target);
+          }
+          self.rootProxy!.notifyArrayChange(path, target);
+          self.rootProxy!.notifyGlobalSubscribers();
+          return result;
+        }
+        return Reflect.set(target, prop, newValue, receiver);
+      },
+    });
+  }
+
+  subscribe(path: string, callback: Function): void {
+    if (path === '*') {
+      this.rootProxy!.globalSubscribers.add(callback);
+      return;
+    }
+
+    if (!this.rootProxy!.subscribers.has(path)) {
+      this.rootProxy!.subscribers.set(path, new Set());
+    }
+    this.rootProxy!.subscribers.get(path)!.add(callback);
+
+    const actualValue = this.rootProxy!.target[path];
+    if (
+      Array.isArray(actualValue) &&
+      !this.rootProxy!.trackedArraysCloned.has(path)
+    ) {
+      this.rootProxy!.storeArrayState(path, actualValue);
+    }
+  }
+
+  unsubscribe(path: string, callback: Function): void {
+    if (path === '*') {
+      this.rootProxy!.globalSubscribers.delete(callback);
+      return;
+    }
+
+    const subs = this.rootProxy!.subscribers.get(path);
+    if (subs) {
+      subs.delete(callback);
+    }
+  }
+
+  private notifySubscribers(path: string, oldValue: any, newValue: any): void {
+    const subs = this.subscribers.get(path);
+    if (subs) {
+      subs.forEach((cb) => cb({ previous: oldValue, current: newValue, path }));
+    }
+  }
+
+  private notifyGlobalSubscribers(): void {
+    this.globalSubscribers.forEach((cb) => cb());
+  }
+
+  private notifyArrayChange(path: string, newArray: any[]): void {
+    const subs = this.subscribers.get(path);
+    if (!subs) return;
+
+    const clonedInitial = this.trackedArraysCloned.get(path);
+    const originalInitial = this.trackedArraysOriginal.get(path);
+
+    if (!clonedInitial || !originalInitial) {
+      this.storeArrayState(path, newArray);
+      return;
+    }
+
+    const changes = this.detectArrayChanges(clonedInitial, originalInitial, newArray);
+    subs.forEach((cb) => cb({ ...changes, path }));
+  }
+
+  private detectArrayChanges(
+    oldCloned: any[],
+    oldOriginal: any[],
+    newArray: any[]
+  ): { toCreate: any[]; toUpdate: any[]; toDelete: any[] } {
+    const toCreate: any[] = [];
+    const toUpdate: any[] = [];
+    const toDelete: any[] = [];
+
+    const oldMap = new Map<string, any>();
+    const newMap = new Map<string, any>();
+
+    oldCloned.forEach((item) => {
+      const id = this.getItemId(item);
+      if (id) oldMap.set(id, item);
+    });
+
+    newArray.forEach((item) => {
+      const id = this.getItemId(item);
+      if (id) newMap.set(id, item);
+    });
+
+    newArray.forEach((item) => {
+      const id = this.getItemId(item);
+      if (!id) {
+        toCreate.push(item);
+      } else if (!oldMap.has(id)) {
+        toCreate.push(item);
+      } else if (this.hasChanged(oldMap.get(id), item)) {
+        toUpdate.push(item);
+      }
+    });
+
+    oldOriginal.forEach((item) => {
+      const id = this.getItemId(item);
+      if (id && !newMap.has(id)) {
+        toDelete.push(item);
+      }
+    });
+
+    return { toCreate, toUpdate, toDelete };
+  }
+
+  private cloneArray(arr: any[]): any[] {
+    return arr.map((item) => this.deepClone(item));
+  }
+
+  private deepClone(obj: any): any {
+    if (obj === null || obj === undefined) return obj;
+    if (typeof obj !== 'object') return obj;
+    if (obj instanceof Date) return new Date(obj.getTime());
+    if (obj instanceof Id) return obj.value;
+    if (obj.toJson && typeof obj.toJson === 'function') return obj.toJson();
+    if (Array.isArray(obj)) return obj.map((item) => this.deepClone(item));
+    const cloned: any = {};
+    for (const key in obj) {
+      if (obj.hasOwnProperty(key)) cloned[key] = this.deepClone(obj[key]);
+    }
+    return cloned;
+  }
+
+  private getItemId(item: any): string | undefined {
+    if (!item) return undefined;
+    if (item.id instanceof Id) return item.id.value;
+    if (item.id !== undefined) return String(item.id);
+    if (typeof item === 'object' && 'id' in item) {
+      const id = item.id;
+      return id instanceof Id ? id.value : String(id);
+    }
+    return undefined;
+  }
+
+  private hasChanged(obj1: any, obj2: any): boolean {
+    const json1 = this.deepClone(obj1);
+    const json2 = this.deepClone(obj2);
+    return JSON.stringify(json1) !== JSON.stringify(json2);
+  }
+
+  getHistory(): HistoryEntry[] {
+    return [...this.history];
+  }
+
+  clearHistory(): void {
+    this.history = [];
+    this.originalValues.clear();
+    this.trackedArraysCloned.clear();
+    this.trackedArraysOriginal.clear();
+  }
+
+  getTarget(): any {
+    return this.target;
+  }
+}

package/src/domain-event-bus.ts

@@ -0,0 +1,166 @@
+// ============================================================================
+// Domain Event Bus - Pub/Sub for Domain Events
+// ============================================================================
+
+import {
+  IDomainEvent,
+  DomainEventHandler,
+  IDomainEventHandler,
+} from "./domain-event";
+
+type EventConstructor<T extends IDomainEvent = IDomainEvent> = new (
+  ...args: any[]
+) => T;
+
+/**
+ * Domain Event Bus - Singleton pattern for event pub/sub
+ */
+export class DomainEventBus {
+  private static instance: DomainEventBus;
+  private handlers: Map<
+    string,
+    Set<DomainEventHandler<any> | IDomainEventHandler<any>>
+  > = new Map();
+  private wildcardHandlers: Set<
+    DomainEventHandler<any> | IDomainEventHandler<any>
+  > = new Set();
+
+  private constructor() {}
+
+  /**
+   * Get the singleton instance
+   */
+  static getInstance(): DomainEventBus {
+    if (!DomainEventBus.instance) {
+      DomainEventBus.instance = new DomainEventBus();
+    }
+    return DomainEventBus.instance;
+  }
+
+  /**
+   * Subscribe to a specific event type
+   */
+  subscribe<T extends IDomainEvent>(
+    eventType: EventConstructor<T> | string,
+    handler: DomainEventHandler<T> | IDomainEventHandler<T>
+  ): void {
+    const eventName =
+      typeof eventType === "string" ? eventType : eventType.name;
+
+    if (!this.handlers.has(eventName)) {
+      this.handlers.set(eventName, new Set());
+    }
+
+    this.handlers.get(eventName)!.add(handler);
+  }
+
+  /**
+   * Subscribe to all events (wildcard)
+   */
+  subscribeAll(
+    handler: DomainEventHandler<IDomainEvent> | IDomainEventHandler<IDomainEvent>
+  ): void {
+    this.wildcardHandlers.add(handler);
+  }
+
+  /**
+   * Unsubscribe from a specific event type
+   */
+  unsubscribe<T extends IDomainEvent>(
+    eventType: EventConstructor<T> | string,
+    handler: DomainEventHandler<T> | IDomainEventHandler<T>
+  ): void {
+    const eventName =
+      typeof eventType === "string" ? eventType : eventType.name;
+    const handlers = this.handlers.get(eventName);
+
+    if (handlers) {
+      handlers.delete(handler);
+      if (handlers.size === 0) {
+        this.handlers.delete(eventName);
+      }
+    }
+  }
+
+  /**
+   * Unsubscribe from all events
+   */
+  unsubscribeAll(
+    handler: DomainEventHandler<IDomainEvent> | IDomainEventHandler<IDomainEvent>
+  ): void {
+    this.wildcardHandlers.delete(handler);
+  }
+
+  /**
+   * Publish a single event
+   */
+  async publish<T extends IDomainEvent>(event: T): Promise<void> {
+    const eventName = event.eventName;
+    const handlers = this.handlers.get(eventName) || new Set();
+
+    // Execute specific handlers
+    const specificPromises = Array.from(handlers).map((handler) =>
+      this.executeHandler(handler, event)
+    );
+
+    // Execute wildcard handlers
+    const wildcardPromises = Array.from(this.wildcardHandlers).map((handler) =>
+      this.executeHandler(handler, event)
+    );
+
+    await Promise.all([...specificPromises, ...wildcardPromises]);
+  }
+
+  /**
+   * Publish multiple events
+   */
+  async publishAll(events: IDomainEvent[]): Promise<void> {
+    await Promise.all(events.map((event) => this.publish(event)));
+  }
+
+  /**
+   * Clear all handlers (useful for testing)
+   */
+  clearAllHandlers(): void {
+    this.handlers.clear();
+    this.wildcardHandlers.clear();
+  }
+
+  /**
+   * Get count of handlers for an event type
+   */
+  getHandlerCount(eventType: EventConstructor | string): number {
+    const eventName =
+      typeof eventType === "string" ? eventType : eventType.name;
+    return this.handlers.get(eventName)?.size || 0;
+  }
+
+  /**
+   * Execute a handler (function or class)
+   */
+  private async executeHandler(
+    handler: DomainEventHandler<any> | IDomainEventHandler<any>,
+    event: IDomainEvent
+  ): Promise<void> {
+    try {
+      if (typeof handler === "function") {
+        await handler(event);
+      } else {
+        await handler.handle(event);
+      }
+    } catch (error) {
+      console.error(
+        `Error handling event ${event.eventName}:`,
+        error
+      );
+      // Don't throw - we don't want one handler failure to break others
+    }
+  }
+}
+
+/**
+ * Convenience function to get the event bus instance
+ */
+export function getEventBus(): DomainEventBus {
+  return DomainEventBus.getInstance();
+}

package/src/domain-event.ts

@@ -0,0 +1,90 @@
+// ============================================================================
+// Domain Events - Event-Driven Architecture Support
+// ============================================================================
+
+import { Id } from "./id";
+
+/**
+ * Interface for all domain events
+ */
+export interface IDomainEvent {
+  /**
+   * Unique identifier for this event occurrence
+   */
+  readonly eventId: string;
+
+  /**
+   * When the event occurred
+   */
+  readonly occurredOn: Date;
+
+  /**
+   * Name/type of the event (e.g., "UserCreated", "OrderPlaced")
+   */
+  readonly eventName: string;
+
+  /**
+   * ID of the aggregate that raised this event
+   */
+  readonly aggregateId: string;
+}
+
+/**
+ * Base class for domain events
+ */
+export abstract class DomainEvent implements IDomainEvent {
+  public readonly eventId: string;
+  public readonly occurredOn: Date;
+  public readonly aggregateId: string;
+
+  constructor(aggregateId: Id | string) {
+    this.eventId = this.generateEventId();
+    this.occurredOn = new Date();
+    this.aggregateId = aggregateId instanceof Id ? aggregateId.value : aggregateId;
+  }
+
+  /**
+   * Get the event name (defaults to class name)
+   */
+  get eventName(): string {
+    return this.constructor.name;
+  }
+
+  private generateEventId(): string {
+    return `${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+  }
+
+  /**
+   * Convert event to JSON
+   */
+  toJSON(): Record<string, any> {
+    return {
+      eventId: this.eventId,
+      eventName: this.eventName,
+      occurredOn: this.occurredOn.toISOString(),
+      aggregateId: this.aggregateId,
+      ...this.getPayload(),
+    };
+  }
+
+  /**
+   * Override this to provide event-specific data
+   */
+  protected getPayload(): Record<string, any> {
+    return {};
+  }
+}
+
+/**
+ * Event handler function type
+ */
+export type DomainEventHandler<T extends IDomainEvent = IDomainEvent> = (
+  event: T
+) => void | Promise<void>;
+
+/**
+ * Event handler class type
+ */
+export interface IDomainEventHandler<T extends IDomainEvent = IDomainEvent> {
+  handle(event: T): void | Promise<void>;
+}

package/src/entity.ts

@@ -0,0 +1,16 @@
+// ============================================================================
+// 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/id.ts

@@ -0,0 +1,94 @@
+import { randomUUID } from 'crypto';
+// ============================================================================
+// Id Class - Smart Identity Management
+// ============================================================================
+
+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();
+   * newId.isNew // true
+   *
+   * // Existing entity (uses provided ID)
+   * const existingId = new Id("550e8400-e29b-41d4-a716-446655440000");
+   * existingId.isNew // false
+   */
+  constructor(value?: string) {
+    if (value !== undefined) {
+      // ID was provided - this is an existing entity
+      this._value = value;
+      this._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
+   */
+  get 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 randomUUID();
+  }
+
+  /**
+   * Create a new Id (convenience static method)
+   */
+  static create(): Id {
+    return new Id();
+  }
+
+  /**
+   * Create an Id from an existing value
+   */
+  static from(value: string): Id {
+    return new Id(value);
+  }
+}