@woltz/rich-domain 1.2.0 → 1.2.2

package/src/constants.ts

@@ -1,7 +1,81 @@
-import { ValidationConfig } from ".";
+import {
+  ArrayOperators,
+  BooleanOperators,
+  DateOperators,
+  FilterOperator,
+  NumberOperators,
+  StringOperators,
+  ValidationConfig,
+} from ".";
 
 export const DEFAULT_VALIDATION_CONFIG: Required<ValidationConfig> = {
   onCreate: true,
   onUpdate: true,
   throwOnError: true,
 };
+
+export const ARRAY_OPERATORS: ArrayOperators[] = [
+  "in",
+  "notIn",
+  "isNull",
+  "isNotNull",
+];
+export const BOOLEAN_OPERATORS: BooleanOperators[] = [
+  "equals",
+  "notEquals",
+  "isNull",
+  "isNotNull",
+];
+export const DATE_OPERATORS: DateOperators[] = [
+  "equals",
+  "notEquals",
+  "greaterThan",
+  "greaterThanOrEqual",
+  "lessThan",
+  "lessThanOrEqual",
+  "in",
+  "notIn",
+  "between",
+  "isNull",
+  "isNotNull",
+];
+export const NUMBER_OPERATORS: NumberOperators[] = [
+  "equals",
+  "notEquals",
+  "greaterThan",
+  "greaterThanOrEqual",
+  "lessThan",
+  "lessThanOrEqual",
+  "in",
+  "notIn",
+  "between",
+  "isNull",
+  "isNotNull",
+];
+export const STRING_OPERATORS: StringOperators[] = [
+  "equals",
+  "notEquals",
+  "contains",
+  "startsWith",
+  "endsWith",
+  "in",
+  "notIn",
+  "isNull",
+  "isNotNull",
+];
+export const FILTER_OPERATORS: FilterOperator[] = [
+  "equals",
+  "notEquals",
+  "greaterThan",
+  "greaterThanOrEqual",
+  "lessThan",
+  "lessThanOrEqual",
+  "contains",
+  "startsWith",
+  "endsWith",
+  "in",
+  "notIn",
+  "between",
+  "isNull",
+  "isNotNull",
+];

package/src/criteria.ts

@@ -13,11 +13,13 @@ import {
   PathValue,
   Search,
   TypedFilter,
+  TypedOrder,
 } from "./types";
 import {
   isValidOperatorForType,
   getValidOperatorsForType,
   isOperator,
+  sanitizeFieldValue,
 } from "./utils/criteria-operator-validation";
 import { parseQueryValue } from "./utils/helpers";
 
@@ -278,7 +280,7 @@ export class Criteria<T = any> {
   static fromObject<T>(
     obj: {
       filters?: TypedFilter<T>[];
-      orders?: Order[];
+      orders?: TypedOrder<T>[];
       pagination?: Pagination;
       search?: { fields: FieldPath<T>[]; value: string };
     },
@@ -459,10 +461,15 @@ export class Criteria<T = any> {
   }
 
   private validateOperator(operator: FilterOperator, value: any): void {
-    if (value !== undefined && !isValidOperatorForType(value, operator)) {
-      const validOps = getValidOperatorsForType(value);
+    const sanitizedValue = sanitizeFieldValue(value, operator);
+
+    if (
+      sanitizedValue !== undefined &&
+      !isValidOperatorForType(sanitizedValue, operator)
+    ) {
+      const validOps = getValidOperatorsForType(sanitizedValue);
       throw new InvalidCriteriaError(
-        `Operator "${operator}" is not valid for type "${typeof value}". Valid operators: ${validOps.join(
+        `Operator "${operator}" is not valid for type "${typeof sanitizedValue}". Valid operators: ${validOps.join(
           ", "
         )}`,
         operator

package/src/crypto.ts

@@ -0,0 +1,31 @@
+const customCrypto = {
+  randomUUID: () => {
+    if (
+      typeof globalThis !== "undefined" &&
+      globalThis?.crypto &&
+      typeof globalThis.crypto.randomUUID === "function"
+    ) {
+      return globalThis.crypto.randomUUID();
+    }
+
+    const hexChars = "0123456789abcdef";
+    let uuid = "";
+
+    for (let i = 0; i < 36; i++) {
+      if (i === 8 || i === 13 || i === 18 || i === 23) {
+        uuid += "-";
+      } else if (i === 14) {
+        uuid += "4";
+      } else if (i === 19) {
+        uuid += hexChars.charAt(Math.floor(Math.random() * 4) + 8);
+      } else {
+        uuid += hexChars.charAt(Math.floor(Math.random() * 16));
+      }
+    }
+
+    return uuid;
+  },
+};
+
+export const UUID = customCrypto.randomUUID;
+export default UUID;

package/src/domain-event.ts

@@ -1,7 +1,3 @@
-// ============================================================================
-// Domain Events - Event-Driven Architecture Support
-// ============================================================================
-
 import { IDomainEvent } from ".";
 import { Id } from "./id";
 

package/src/entity-changes.ts

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

@@ -0,0 +1,255 @@
+import { Entity } from "./entity";
+import { ValueObject } from "./value-object";
+import { Id } from "./id";
+
+/**
+ * Mapping schema for a domain entity.
+ */
+export interface EntitySchema {
+  /** Entity name in the domain (e.g., 'User', 'Post') */
+  entity: string;
+  /** Table name in the database (e.g., 'users', 'blog_posts') */
+  table: string;
+  /**
+   * Field mapping: domain → database.
+   * Only include fields with different names.
+   * @example { email: 'user_email', createdAt: 'created_at' }
+   */
+  fields?: Record<string, string>;
+  /**
+   * FK configuration for parent relation.
+   */
+  parentFk?: {
+    /** Name of the FK field in the database (e.g., 'author_id') */
+    field: string;
+    /** Name of the parent entity (e.g., 'User') */
+    parentEntity: string;
+  };
+}
+
+/**
+ * Result of entity mapping.
+ */
+export interface MappedEntityData {
+  [key: string]: any;
+}
+
+/**
+ * Registry for mapping domain entities to database tables and fields.
+ *
+ * @example
+ * ```typescript
+ * const registry = new EntitySchemaRegistry()
+ *   .register({
+ *     entity: 'User',
+ *     table: 'users',
+ *     fields: { email: 'user_email', name: 'user_name' },
+ *   })
+ *   .register({
+ *     entity: 'Post',
+ *     table: 'blog_posts',
+ *     fields: { content: 'post_content' },
+ *     parentFk: { field: 'author_id', parentEntity: 'User' },
+ *   });
+ *
+ * const table = registry.getTable('Post'); // 'blog_posts'
+ * const mapped = registry.mapFields('User', { email: 'test@test.com' });
+ * // { user_email: 'test@test.com' }
+ * ```
+ */
+export class EntitySchemaRegistry {
+  private schemas = new Map<string, EntitySchema>();
+
+  /**
+   * Registers an entity schema.
+   * @param schema - Schema to be registered.
+   * @returns this (for chaining)
+   */
+  register(schema: EntitySchema): this {
+    if (this.schemas.has(schema.entity)) {
+      console.warn(
+        `EntitySchemaRegistry: Schema for '${schema.entity}' is being overwritten`
+      );
+    }
+    this.schemas.set(schema.entity, schema);
+    return this;
+  }
+
+  /**
+   * Registers multiple schemas at once.
+   * @param schemas - Array of schemas.
+   * @returns this (for chaining)
+   */
+  registerAll(schemas: EntitySchema[]): this {
+    schemas.forEach((schema) => this.register(schema));
+    return this;
+  }
+
+  /**
+   * Gets the schema of an entity.
+   * @param entity - Entity name.
+   * @throws Error if the entity is not registered.
+   */
+  getSchema(entity: string): EntitySchema {
+    const schema = this.schemas.get(entity);
+    if (!schema) {
+      throw new Error(
+        `EntitySchemaRegistry: No schema registered for entity '${entity}'. ` +
+          `Available entities: ${Array.from(this.schemas.keys()).join(", ") || "none"}`
+      );
+    }
+    return schema;
+  }
+
+  /**
+   * Checks if an entity is registered.
+   * @param entity - Entity name.
+   */
+  has(entity: string): boolean {
+    return this.schemas.has(entity);
+  }
+
+  /**
+   * Gets the table name for an entity.
+   * @param entity - Entity name.
+   */
+  getTable(entity: string): string {
+    return this.getSchema(entity).table;
+  }
+
+  /**
+   * Gets the field mapping for an entity.
+   * @param entity - Entity name.
+   */
+  getFieldsMap(entity: string): Record<string, string> {
+    return this.getSchema(entity).fields || {};
+  }
+
+  /**
+   * Maps a domain field name to the database field name.
+   * @param entity - Entity name.
+   * @param fieldName - Domain field name.
+   */
+  mapFieldName(entity: string, fieldName: string): string {
+    const fields = this.getFieldsMap(entity);
+    return fields[fieldName] ?? fieldName;
+  }
+
+  /**
+   * Maps fields of a domain object to database field names.
+   * Ignores values that are Entity, ValueObject, or Arrays.
+   *
+   * @param entity - Entity name.
+   * @param data - Data to be mapped.
+   */
+  mapFields(entity: string, data: Record<string, any>): MappedEntityData {
+    const fields = this.getFieldsMap(entity);
+    const result: MappedEntityData = {};
+    for (const [key, value] of Object.entries(data)) {
+      if (this.isEntityOrCollection(value)) continue;
+      const mappedKey = fields[key] ?? key;
+      result[mappedKey] = this.normalizeValue(value);
+    }
+    return result;
+  }
+
+  /**
+   * Maps a complete domain entity to database data.
+   * Used for CREATE operations.
+   *
+   * @param entity - Entity name.
+   * @param domainEntity - Domain entity instance.
+   */
+  mapEntity(
+    entity: string,
+    domainEntity: Entity<any> | ValueObject<any>
+  ): MappedEntityData {
+    const fields = this.getFieldsMap(entity);
+    const result: MappedEntityData = {};
+    const hasId = (domainEntity as any).id;
+    if (hasId) {
+      const idValue = hasId.value ?? hasId;
+      result["id"] = idValue;
+    }
+    const props = (domainEntity as any).props || domainEntity;
+    for (const [key, value] of Object.entries(props)) {
+      if (key === "id") continue;
+      if (this.isEntityOrCollection(value)) continue;
+      const mappedKey = fields[key] ?? key;
+      result[mappedKey] = this.normalizeValue(value);
+    }
+    return result;
+  }
+
+  /**
+   * Gets the FK object to relate with the parent.
+   *
+   * @param entity - Entity name.
+   * @param parentId - Parent ID.
+   * @returns Object with the FK field or null if there is no parent.
+   */
+  getParentFk(entity: string, parentId: string): Record<string, string> | null {
+    const schema = this.getSchema(entity);
+    if (!schema.parentFk) return null;
+    return { [schema.parentFk.field]: parentId };
+  }
+
+  /**
+   * Gets the name of the parent entity.
+   * @param entity - Entity name.
+   */
+  getParentEntity(entity: string): string | null {
+    const schema = this.getSchema(entity);
+    return schema.parentFk?.parentEntity ?? null;
+  }
+
+  /**
+   * Gets the FK field name.
+   * @param entity - Entity name.
+   */
+  getParentFkField(entity: string): string | null {
+    const schema = this.getSchema(entity);
+    return schema.parentFk?.field ?? null;
+  }
+
+  /**
+   * Lists all registered entities.
+   */
+  getRegisteredEntities(): string[] {
+    return Array.from(this.schemas.keys());
+  }
+
+  /**
+   * Clears all registered schemas.
+   */
+  clear(): void {
+    this.schemas.clear();
+  }
+
+  /**
+   * Checks if a value is Entity, ValueObject, or Array.
+   */
+  private isEntityOrCollection(value: any): boolean {
+    if (value === null || value === undefined) return false;
+    if (Array.isArray(value)) return true;
+    if (value instanceof Entity) return true;
+    if (value instanceof ValueObject) return true;
+    if (typeof value === 'object' && value.id && typeof value.id === 'object' && 'value' in value.id) {
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Normalizes a value for persistence.
+   */
+  private normalizeValue(value: any): any {
+    if (value === null || value === undefined) return value;
+    if (value instanceof Id) return value.value;
+    if (value instanceof Date) return value;
+    if (typeof value === "object" && "value" in value) {
+      return value.value;
+    }
+    return value;
+  }
+}

package/src/entity.ts

@@ -1,16 +1,5 @@
-// ============================================================================
-// 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

@@ -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

@@ -1,28 +1,16 @@
-// ============================================================================
-// Rich Domain Library - Main Exports
-// ============================================================================
-
-// Core Classes
-export { Id } from "./id";
-export { Entity, Aggregate } from "./entity";
-export { ValueObject } from "./value-object";
-export { Mapper } from "./mapper";
-
 export * from "./validation-error";
-
-// Domain Events
 export * from "./domain-event";
 export * from "./domain-event-bus";
 export * from "./exceptions";
-
-// Criteria
 export * from "./criteria";
 export * from "./paginated-result";
-
-// Repository
 export * from "./repository";
-
-// Types
+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 { AggregateChanges } from "./aggregate-changes";
 export {
   DomainEventHandler,
   EntityHooks,
@@ -40,7 +28,6 @@ export {
   Order,
   IUnitOfWork,
   IDomainEventHandler,
-  EntityId,
   FieldPath,
   FilterOperator,
   Search,
@@ -54,3 +41,12 @@ export {
   ArrayOperators,
   CriteriaOptions,
 } from "./types";
+export {
+  ARRAY_OPERATORS,
+  BOOLEAN_OPERATORS,
+  DATE_OPERATORS,
+  NUMBER_OPERATORS,
+  STRING_OPERATORS,
+  FILTER_OPERATORS,
+} from "./constants";
+export { isValidOperatorForType } from "./utils/criteria-operator-validation";