@woltz/rich-domain 0.2.1

package/src/base-entity.ts

@@ -0,0 +1,401 @@
+// ============================================================================
+// Base Entity Class with Standard Schema Validation
+// ============================================================================
+
+import { Id } from "./id";
+import { DeepProxy } from "./deep-proxy";
+import { ValidationError } from "./validation-error";
+import { IDomainEvent } from "./domain-event";
+import {
+  BaseProps,
+  SubscriptionConfig,
+  HistoryEntry,
+  DeepJsonResult,
+  EntityHooks,
+  ValidationConfig,
+  StandardSchema,
+  EntityValidation,
+} from "./types";
+import { DomainEventBus } from "./domain-event-bus";
+import { DEFAULT_VALIDATION_CONFIG } from "./constants";
+
+// Helper to get static properties from constructor
+function getStaticProperty<T>(
+  instance: any,
+  propertyName: string
+): T | undefined {
+  return instance.constructor[propertyName];
+}
+
+export abstract class BaseEntity<T extends BaseProps> {
+  private _props: T;
+  private proxy: DeepProxy;
+  private proxiedProps: T;
+  private snapshot: T | null = null;
+  private validationConfig: Required<ValidationConfig>;
+  private entityHooks?: EntityHooks<T, any>;
+  private entitySchema?: StandardSchema<T>;
+  private domainEvents: IDomainEvent[] = [];
+
+  // Static properties that subclasses can override
+  protected static validation?: EntityValidation<any>;
+  protected static hooks?: EntityHooks<any, any>;
+
+  constructor(props: Omit<T, "id"> & { id?: Id }) {
+    // Get static configuration from subclass
+    const validation = getStaticProperty<EntityValidation<T>>(
+      this,
+      "validation"
+    );
+    const hooks = getStaticProperty<EntityHooks<T, any>>(this, "hooks");
+
+    this.entityHooks = hooks;
+
+    if (validation?.schema) {
+      this.entitySchema = validation.schema;
+    }
+
+    this.validationConfig = {
+      ...DEFAULT_VALIDATION_CONFIG,
+      ...validation?.config,
+    };
+
+    // Apply defaultValues
+    let finalProps = { ...props } as T;
+
+    // Generate ID if not provided
+    if (!finalProps.id) {
+      finalProps.id = new Id();
+    }
+
+    // Validate schema on creation
+    if (this.entitySchema && this.validationConfig.onCreate) {
+      this.validateProps(finalProps);
+    }
+
+    this._props = finalProps;
+    this.proxy = new DeepProxy(this._props);
+    this.proxiedProps = this.proxy.createProxy();
+
+    // Execute rules (custom validations)
+    if (hooks?.rules) {
+      hooks.rules(this as any);
+    }
+
+    // Hook onCreate
+    if (hooks?.onCreate) {
+      hooks.onCreate(this as any);
+    }
+
+    // Setup update validation
+    if (this.entitySchema && this.validationConfig.onUpdate) {
+      this.setupUpdateValidation();
+    }
+
+    // Take initial snapshot for onBeforeUpdate
+    this.takeSnapshot();
+  }
+
+  private validateProps(props: T): void {
+    if (!this.entitySchema) return;
+
+    const result = this.entitySchema["~standard"].validate(props);
+
+    if (result instanceof Promise) {
+      throw new Error(
+        "Async validation not supported in constructor. Use sync validation schema."
+      );
+    }
+
+    if (result.issues && result.issues.length > 0) {
+      const validationError = new ValidationError(
+        result.issues.map((issue) => ({
+          path: issue.path?.map((p) => this.extractPathKey(p)) || [],
+          message: issue.message,
+        }))
+      );
+
+      if (this.validationConfig.throwOnError) {
+        throw validationError;
+      }
+
+      // If not throwing, store error for later retrieval
+      (this as any)._validationError = validationError;
+    }
+  }
+
+  private extractPathKey(pathSegment: unknown): string {
+    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);
+  }
+
+  private setupUpdateValidation(): void {
+    const self = this;
+
+    const validateOnChange = () => {
+      // Check onBeforeUpdate hook
+      if (self.entityHooks?.onBeforeUpdate && self.snapshot) {
+        const shouldContinue = self.entityHooks.onBeforeUpdate(
+          self as any,
+          self.snapshot
+        );
+        if (!shouldContinue) {
+          // Revert changes
+          Object.assign(self._props, self.snapshot);
+          return;
+        }
+      }
+
+      // Validate with schema
+      if (self.entitySchema) {
+        const result = self.entitySchema["~standard"].validate(self._props);
+
+        if (result instanceof Promise) {
+          console.warn(
+            "Async validation on update not supported. Consider using sync validation."
+          );
+          return;
+        }
+
+        if (result.issues && result.issues.length > 0) {
+          const validationError = new ValidationError(
+            result.issues.map((issue) => ({
+              path: issue.path?.map((p) => self.extractPathKey(p)) || [],
+              message: issue.message,
+            }))
+          );
+
+          if (self.validationConfig.throwOnError) {
+            // Revert changes before throwing
+            if (self.snapshot) {
+              Object.assign(self._props, self.snapshot);
+            }
+            throw validationError;
+          }
+          console.error("Validation failed on update:", validationError);
+        }
+      }
+
+      // Execute rules after schema validation
+      if (self.entityHooks?.rules) {
+        try {
+          self.entityHooks.rules(self as any);
+        } catch (error) {
+          if (self.validationConfig.throwOnError) {
+            // Revert changes before throwing
+            if (self.snapshot) {
+              Object.assign(self._props, self.snapshot);
+            }
+            throw error;
+          }
+          console.error("Rules validation failed on update:", error);
+        }
+      }
+
+      // Update snapshot after successful validation
+      self.takeSnapshot();
+    };
+
+    // Subscribe to all changes
+    this.proxy.subscribe("*", validateOnChange);
+  }
+
+  private takeSnapshot(): void {
+    this.snapshot = this.deepCloneProps(this._props);
+  }
+
+  private deepCloneProps(obj: any, seen: WeakSet<object> = new WeakSet()): any {
+    if (obj === null || obj === undefined) return obj;
+
+    // Primitives
+    if (typeof obj !== "object") return obj;
+
+    // Special cases - don't clone these, just return the reference
+    if (obj instanceof Id) return obj;
+    if (obj instanceof Date) return new Date(obj.getTime());
+
+    // Check for circular references
+    if (seen.has(obj)) {
+      return obj; // Return reference to avoid infinite loop
+    }
+
+    // Handle BaseEntity instances - just keep the reference
+    if (obj instanceof BaseEntity) {
+      return obj;
+    }
+
+    // Handle ValueObject instances - just keep the reference (they're immutable)
+    if (
+      obj.constructor &&
+      obj.constructor.name !== "Object" &&
+      obj.constructor.name !== "Array"
+    ) {
+      // Check if it has toJson method (likely a ValueObject or similar)
+      if (
+        typeof obj.toJson === "function" &&
+        typeof obj.equals === "function"
+      ) {
+        return obj; // Keep reference for ValueObjects
+      }
+    }
+
+    seen.add(obj);
+
+    if (Array.isArray(obj)) {
+      return obj.map((item) => this.deepCloneProps(item, seen));
+    }
+
+    // Plain objects only
+    if (obj.constructor === Object) {
+      const cloned: any = {};
+      for (const key in obj) {
+        if (obj.hasOwnProperty(key)) {
+          cloned[key] = this.deepCloneProps(obj[key], seen);
+        }
+      }
+      return cloned;
+    }
+
+    // For other object types (custom classes), just keep the reference
+    return obj;
+  }
+
+  get id(): Id {
+    return this._props.id;
+  }
+
+  get isNew(): boolean {
+    return this._props.id.isNew;
+  }
+
+  /**
+   * Check equality with another entity by comparing IDs
+   * Entities are equal if they have the same ID, regardless of other properties
+   *
+   * @param other - Another entity or an ID to compare with
+   * @returns true if entities have the same ID
+   */
+  equals(other: BaseEntity<T> | Id | string): boolean {
+    if (!other) {
+      return false;
+    }
+
+    // Compare with another entity
+    if (other instanceof BaseEntity) {
+      return this.id.equals(other.id);
+    }
+
+    // Compare with an ID
+    if (other instanceof Id) {
+      return this.id.equals(other);
+    }
+
+    // Compare with a string ID
+    if (typeof other === "string") {
+      return this.id.equals(other);
+    }
+
+    return false;
+  }
+
+  public get props(): T {
+    return this.proxiedProps;
+  }
+
+  /**
+   * Check if entity has validation errors (when throwOnError is false)
+   */
+  get hasValidationErrors(): boolean {
+    return !!(this as any)._validationError;
+  }
+
+  /**
+   * Get validation errors (when throwOnError is false)
+   */
+  get validationErrors(): ValidationError | undefined {
+    return (this as any)._validationError;
+  }
+
+  subscribe(config: SubscriptionConfig<T>): void {
+    Object.keys(config).forEach((key) => {
+      const sub = config[key as keyof T];
+      if (sub && "onChange" in sub) {
+        this.proxy.subscribe(key, sub.onChange);
+      }
+    });
+  }
+
+  getHistory(): HistoryEntry[] {
+    return this.proxy.getHistory();
+  }
+
+  clearHistory(): void {
+    this.proxy.clearHistory();
+  }
+
+  /**
+   * Add a domain event to this entity
+   */
+  protected addDomainEvent(event: IDomainEvent): void {
+    this.domainEvents.push(event);
+  }
+
+  public async dispatchAll(bus: DomainEventBus) {
+    await bus.publishAll(this.getUncommittedEvents());
+  }
+
+  /**
+   * Get all uncommitted domain events
+   */
+  getUncommittedEvents(): IDomainEvent[] {
+    return [...this.domainEvents];
+  }
+
+  /**
+   * Clear all domain events (call after publishing)
+   */
+  clearEvents(): void {
+    this.domainEvents = [];
+  }
+
+  /**
+   * Check if entity has uncommitted events
+   */
+  hasUncommittedEvents(): boolean {
+    return this.domainEvents.length > 0;
+  }
+
+  toJson(): DeepJsonResult<T> {
+    return this.deepToJson(this._props) as DeepJsonResult<T>;
+  }
+
+  private deepToJson(obj: any): any {
+    if (obj === null || obj === undefined) return obj;
+    if (obj instanceof Id) return obj.value;
+    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 (typeof obj === "object") {
+      const result: any = {};
+      for (const key in obj) {
+        if (obj.hasOwnProperty(key)) result[key] = this.deepToJson(obj[key]);
+      }
+      return result;
+    }
+    return obj;
+  }
+}

package/src/constants.ts

@@ -0,0 +1,7 @@
+import { ValidationConfig } from ".";
+
+export const DEFAULT_VALIDATION_CONFIG: Required<ValidationConfig> = {
+  onCreate: true,
+  onUpdate: true,
+  throwOnError: true,
+};

package/src/criteria.ts

@@ -0,0 +1,291 @@
+import {
+  FieldPath,
+  Filter,
+  FilterOperator,
+  FilterValueFor,
+  Order,
+  OrderDirection,
+  Pagination,
+  PathValue,
+  TypedFilter,
+} from "./types";
+
+// ============================================================================
+// Filter Types
+// ============================================================================
+
+export class Criteria<T = unknown> {
+  private _filters: Filter<FieldPath<T>, any>[] = [];
+  private _orders: Order[] = [];
+  private _pagination: Pagination = { page: 1, limit: 20, offset: 0 };
+  private _search?: {
+    fields: FieldPath<T>[];
+    value: string;
+  };
+
+  private constructor() {}
+
+  /**
+   * Create a new Criteria instance
+   */
+  static create<T = unknown>(): Criteria<T> {
+    return new Criteria<T>();
+  }
+
+  /**
+   * Add a filter condition
+   */
+  where<K extends FieldPath<T>>(
+    field: K,
+    operator: FilterOperator,
+    value?: FilterValueFor<PathValue<T, K>>
+  ): this {
+    this._filters.push({
+      field,
+      operator,
+      value,
+    });
+    return this;
+  }
+
+  // === Shorthand methods (tipados) ===
+
+  whereEquals<K extends FieldPath<T>>(field: K, value: PathValue<T, K>): this {
+    return this.where(field, "equals", value);
+  }
+
+  whereContains<K extends FieldPath<T>>(
+    field: K,
+    value: PathValue<T, K>
+  ): this {
+    return this.where(field, "contains", value);
+  }
+
+  whereIn<K extends FieldPath<T>>(field: K, values: PathValue<T, K>[]): this {
+    return this.where(field, "in", values);
+  }
+
+  whereBetween<K extends FieldPath<T>>(
+    field: K,
+    min: PathValue<T, K>,
+    max: PathValue<T, K>
+  ): this {
+    return this.where(field, "between", [min, max] as [
+      PathValue<T, K>,
+      PathValue<T, K>
+    ]);
+  }
+
+  whereNull<K extends FieldPath<T>>(field: K): this {
+    return this.where(field, "isNull");
+  }
+
+  whereNotNull<K extends FieldPath<T>>(field: K): this {
+    return this.where(field, "isNotNull");
+  }
+
+  // === OrderBy ===
+
+  orderBy<K extends FieldPath<T>>(
+    field: K,
+    direction: OrderDirection = "asc"
+  ): this {
+    this._orders.push({
+      field: String(field),
+      direction,
+    });
+    return this;
+  }
+
+  orderByAsc<K extends FieldPath<T>>(field: K): this {
+    return this.orderBy(field, "asc");
+  }
+
+  orderByDesc<K extends FieldPath<T>>(field: K): this {
+    return this.orderBy(field, "desc");
+  }
+
+  // --------------------------------------------------------------------------
+  // Search (tipado)
+  // --------------------------------------------------------------------------
+
+  search<K extends FieldPath<T>>(fields: K[], value: string): this {
+    this._search = {
+      fields,
+      value,
+    };
+    return this;
+  }
+
+  hasSearch(): boolean {
+    return !!this._search;
+  }
+
+  getSearch() {
+    return this._search;
+  }
+
+  // === Pagination ===
+
+  paginate(page: number, limit: number): this {
+    if (page < 1) page = 1;
+    if (limit < 1) limit = 10;
+
+    this._pagination = {
+      page,
+      limit,
+      offset: (page - 1) * limit,
+    };
+    return this;
+  }
+
+  limit(limit: number): this {
+    return this.paginate(1, limit);
+  }
+
+  // === Getters ===
+
+  getFilters(): Filter[] {
+    return this._filters;
+  }
+
+  getOrders(): Order[] {
+    return this._orders;
+  }
+
+  getPagination(): Pagination {
+    return this._pagination;
+  }
+
+  hasFilters(): boolean {
+    return this._filters.length > 0;
+  }
+
+  hasOrders(): boolean {
+    return this._orders.length > 0;
+  }
+
+  hasPagination(): boolean {
+    return this._pagination !== undefined;
+  }
+
+  // === Utilities ===
+
+  clone(): Criteria<T> {
+    const cloned = Criteria.create<T>();
+    cloned._filters = [...this._filters];
+    cloned._orders = [...this._orders];
+    cloned._pagination = { ...this._pagination };
+    return cloned;
+  }
+
+  toJSON() {
+    return {
+      filters: this._filters,
+      orders: this._orders,
+      pagination: this._pagination,
+      search: this._search,
+    };
+  }
+
+  static fromObject<T>(obj: {
+    filters?: TypedFilter<T>[];
+    orders?: Order[];
+    pagination?: Pagination;
+    search?: { fields: FieldPath<T>[]; value: string };
+  }): Criteria<T> {
+    const criteria = Criteria.create<T>();
+    if (obj.filters) criteria._filters = [...obj.filters];
+    if (obj.orders) criteria._orders = [...obj.orders];
+    if (obj.pagination) criteria._pagination = { ...obj.pagination };
+    if (obj.search) criteria._search = { ...obj.search };
+
+    return criteria;
+  }
+
+  static fromQueryParams<T>(query: Record<string, any>): Criteria<T> {
+    const criteria = Criteria.create<T>();
+
+    for (const [key, value] of Object.entries(query)) {
+      // Pagination
+      if (key === "page") {
+        continue; // We'll handle pagination after
+      }
+      if (key === "limit") {
+        continue;
+      }
+      if (key === "sort") {
+        continue;
+      }
+
+      const [field, operatorRaw] = key.split(":");
+
+      if (!operatorRaw || !field) continue;
+
+      const operator = isOperator(operatorRaw) ? operatorRaw : null;
+      if (!operator) throw new Error(`Invalid filter operator: ${operatorRaw}`);
+
+      let parsedValue: any = value;
+
+      if (operator === "between") {
+        parsedValue = value
+          .split(",")
+          .map((v: any) => parseQueryValue(v.trim()));
+        if (parsedValue.length === 2) {
+          criteria.whereBetween(field as any, parsedValue[0], parsedValue[1]);
+        }
+        continue;
+      }
+
+      if (operator === "in" || operator === "notIn") {
+        parsedValue = value.split(",").map(parseQueryValue);
+        criteria.where(field as any, operator, parsedValue);
+        continue;
+      }
+
+      criteria.where(field as any, operator, parseQueryValue(value));
+    }
+
+    // Pagination
+    const page = query.page ? parseInt(query.page) : undefined;
+    const limit = query.limit ? parseInt(query.limit) : undefined;
+
+    if (page && limit) {
+      criteria.paginate(page, limit);
+    }
+
+    // Sorting
+    if (query.orderBy) {
+      const sortParts = query.orderBy.split(",");
+      sortParts.forEach((part: string) => {
+        const [field, direction] = part.split(":");
+        criteria.orderBy(field as any, (direction as OrderDirection) || "asc");
+      });
+    }
+
+    if (query.search && query.searchFields) {
+      const fields = (query.searchFields as string)
+        .split(",")
+        .filter(Boolean) as FieldPath<T>[];
+
+      criteria.search(fields, query.search as string);
+    }
+
+    return criteria;
+  }
+}
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+function parseQueryValue(value: string): any {
+  if (!isNaN(Number(value))) return Number(value); // number
+  if (value === "true" || value === "false") return value === "true"; // boolean
+  if (!isNaN(Date.parse(value))) return new Date(value); // Date
+  return value; // string
+}
+
+function isOperator(value: string): value is FilterOperator {
+  return FilterOperator.includes(value as FilterOperator);
+}