@woltz/rich-domain 1.1.0 → 1.2.1

package/src/criteria.ts

@@ -1,68 +1,94 @@
 import { InvalidCriteriaError } from "./exceptions";
 import {
+  CriteriaAdapter,
+  CriteriaOptions,
   FieldPath,
   Filter,
-  FILTER_OPERATORS,
   FilterOperator,
   FilterValueFor,
+  OperatorsForType,
   Order,
   OrderDirection,
   Pagination,
   PathValue,
   Search,
   TypedFilter,
+  TypedOrder,
 } from "./types";
-
-// ============================================================================
-// Filter Types
-// ============================================================================
+import {
+  isValidOperatorForType,
+  getValidOperatorsForType,
+  isOperator,
+} from "./utils/criteria-operator-validation";
+import { parseQueryValue } from "./utils/helpers";
 
 export class Criteria<T = any> {
   private _filters: Filter<FieldPath<T>, any>[] = [];
   private _orders: Order[] = [];
   private _pagination: Pagination = { page: 1, limit: 20, offset: 0 };
-  private _search?: Search<T>
+  private _search?: Search<T>;
+  private _adapter?: CriteriaAdapter<any, any>;
 
   private constructor() {}
 
-  /**
-   * Create a new Criteria instance
-   */
   static create<T = any>(): Criteria<T> {
     return new Criteria<T>();
   }
 
-  /**
-   * Add a filter condition
-   */
+  useAdapter<A extends CriteriaAdapter<any, any>>(map: A): this {
+    this._adapter = map;
+    return this;
+  }
+
+  getAdapter(): CriteriaAdapter<any, any> | undefined {
+    return this._adapter;
+  }
+
+  where<K extends FieldPath<T>>(
+    field: K,
+    operator: OperatorsForType<NonNullable<PathValue<T, K>>>,
+    value?: FilterValueFor<PathValue<T, K>>,
+    options?: CriteriaOptions
+  ): this;
+
   where<K extends FieldPath<T>>(
     field: K,
     operator: FilterOperator,
-    value?: FilterValueFor<PathValue<T, K>>
+    value?: FilterValueFor<PathValue<T, K>>,
+    options?: CriteriaOptions
   ): this {
+    this.validateOperator(operator, value);
+
     this._filters.push({
-      field,
+      field: this.resolveFieldPath(field),
       operator,
       value,
+      options,
     });
     return this;
   }
 
-  // === Shorthand methods (tipados) ===
-
   whereEquals<K extends FieldPath<T>>(field: K, value: PathValue<T, K>): this {
-    return this.where(field, "equals", value);
+    return this.where(
+      field,
+      "equals" as OperatorsForType<PathValue<T, K>>,
+      value
+    );
   }
 
   whereContains<K extends FieldPath<T>>(
     field: K,
     value: PathValue<T, K>
   ): this {
-    return this.where(field, "contains", value);
+    return this.where(
+      field,
+      "contains" as OperatorsForType<PathValue<T, K>>,
+      value
+    );
   }
 
   whereIn<K extends FieldPath<T>>(field: K, values: PathValue<T, K>[]): this {
-    return this.where(field, "in", values);
+    return this.where(field, "in" as OperatorsForType<PathValue<T, K>>, values);
   }
 
   whereBetween<K extends FieldPath<T>>(
@@ -70,28 +96,51 @@ export class Criteria<T = any> {
     min: PathValue<T, K>,
     max: PathValue<T, K>
   ): this {
-    return this.where(field, "between", [min, max] as [
-      PathValue<T, K>,
-      PathValue<T, K>
-    ]);
+    return this.where(
+      field,
+      "between" as OperatorsForType<PathValue<T, K>>,
+      [min, max] as [PathValue<T, K>, PathValue<T, K>]
+    );
   }
 
   whereNull<K extends FieldPath<T>>(field: K): this {
-    return this.where(field, "isNull");
+    return this.where(field, "isNull" as OperatorsForType<PathValue<T, K>>);
   }
 
   whereNotNull<K extends FieldPath<T>>(field: K): this {
-    return this.where(field, "isNotNull");
+    return this.where(field, "isNotNull" as OperatorsForType<PathValue<T, K>>);
   }
 
-  // === OrderBy ===
+  whereSome<K extends FieldPath<T>>(
+    field: K,
+    operator: OperatorsForType<NonNullable<PathValue<T, K>>>,
+    value?: FilterValueFor<PathValue<T, K>>
+  ): this {
+    return this.where(field, operator, value, { quantifier: "some" });
+  }
+
+  whereEvery<K extends FieldPath<T>>(
+    field: K,
+    operator: OperatorsForType<NonNullable<PathValue<T, K>>>,
+    value?: FilterValueFor<PathValue<T, K>>
+  ): this {
+    return this.where(field, operator, value, { quantifier: "every" });
+  }
+
+  whereNone<K extends FieldPath<T>>(
+    field: K,
+    operator: OperatorsForType<NonNullable<PathValue<T, K>>>,
+    value?: FilterValueFor<PathValue<T, K>>
+  ): this {
+    return this.where(field, operator, value, { quantifier: "none" });
+  }
 
   orderBy<K extends FieldPath<T>>(
     field: K,
     direction: OrderDirection = "asc"
   ): this {
     this._orders.push({
-      field: String(field),
+      field: this.resolveFieldPath(field),
       direction,
     });
     return this;
@@ -105,13 +154,9 @@ export class Criteria<T = any> {
     return this.orderBy(field, "desc");
   }
 
-  // --------------------------------------------------------------------------
-  // Search (tipado)
-  // --------------------------------------------------------------------------
-
   search<K extends FieldPath<T>>(fields: K[], value: string): this {
     this._search = {
-      fields,
+      fields: fields.map(this.resolveFieldPath),
       value,
     };
     return this;
@@ -122,11 +167,14 @@ export class Criteria<T = any> {
   }
 
   getSearch() {
-    return this._search;
+    return this._search
+      ? {
+          fields: this._search.fields.map(this.resolveFieldPath),
+          value: this._search.value,
+        }
+      : undefined;
   }
 
-  // === Pagination ===
-
   paginate(page: number, limit: number): this {
     if (page < 1) page = 1;
     if (limit < 1) limit = 10;
@@ -143,14 +191,20 @@ export class Criteria<T = any> {
     return this.paginate(1, limit);
   }
 
-  // === Getters ===
-
   getFilters(): Filter[] {
-    return this._filters;
+    return this._filters.map((filter) => ({
+      field: this.resolveFieldPath(filter.field),
+      operator: filter.operator,
+      value: filter.value,
+      options: filter.options,
+    }));
   }
 
   getOrders(): Order[] {
-    return this._orders;
+    return this._orders.map((order) => ({
+      field: this.resolveFieldPath(order.field as FieldPath<T>),
+      direction: order.direction,
+    }));
   }
 
   getPagination(): Pagination {
@@ -169,47 +223,132 @@ export class Criteria<T = any> {
     return this._pagination !== undefined;
   }
 
-  // === Utilities ===
-
   clone(): Criteria<T> {
     const cloned = Criteria.create<T>();
-    cloned._filters = [...this._filters];
-    cloned._orders = [...this._orders];
+    cloned._filters = [
+      ...this._filters.map((filter) => ({
+        field: this.resolveFieldPath(filter.field),
+        operator: filter.operator,
+        value: filter.value,
+        options: filter.options,
+      })),
+    ];
+    cloned._orders = [
+      ...this._orders.map((order) => ({
+        field: this.resolveFieldPath(order.field as FieldPath<T>),
+        direction: order.direction,
+      })),
+    ];
     cloned._pagination = { ...this._pagination };
+    cloned._search = this._search
+      ? {
+          fields: this._search.fields.map(this.resolveFieldPath),
+          value: this._search.value,
+        }
+      : undefined;
+
+    if (this._adapter) {
+      cloned.useAdapter(this._adapter);
+    }
+
     return cloned;
   }
 
   toJSON() {
     return {
-      filters: this._filters,
-      orders: this._orders,
+      filters: this._filters.map((filter) => ({
+        field: this.resolveFieldPath(filter.field),
+        operator: filter.operator,
+        value: filter.value,
+        options: filter.options,
+      })),
+      orders: this._orders.map((order) => ({
+        field: this.resolveFieldPath(order.field as FieldPath<T>),
+        direction: order.direction,
+      })),
       pagination: this._pagination,
-      search: this._search,
+      search: this._search
+        ? {
+            fields: this._search.fields.map(this.resolveFieldPath),
+            value: this._search.value,
+          }
+        : undefined,
     };
   }
 
-  static fromObject<T>(obj: {
-    filters?: TypedFilter<T>[];
-    orders?: Order[];
-    pagination?: Pagination;
-    search?: { fields: FieldPath<T>[]; value: string };
-  }): Criteria<T> {
+  static fromObject<T>(
+    obj: {
+      filters?: TypedFilter<T>[];
+      orders?: TypedOrder<T>[];
+      pagination?: Pagination;
+      search?: { fields: FieldPath<T>[]; value: string };
+    },
+    adapter?: CriteriaAdapter<any, any>
+  ): Criteria<T> {
     const criteria = Criteria.create<T>();
-    if (obj.filters) criteria._filters = [...obj.filters];
-    if (obj.orders) criteria._orders = [...obj.orders];
+
+    if (adapter) {
+      criteria.useAdapter(adapter);
+    }
+
+    if (obj.filters) {
+      for (const filter of obj.filters) {
+        filter.field = criteria.resolveFieldPath(filter.field);
+        criteria.validateOperator(filter.operator, filter.value);
+      }
+      criteria._filters = [...obj.filters];
+    }
+    if (obj.orders)
+      criteria._orders = [
+        ...obj.orders.map((order) => ({
+          field: criteria.resolveFieldPath(order.field as FieldPath<T>),
+          direction: order.direction,
+        })),
+      ];
     if (obj.pagination) criteria._pagination = { ...obj.pagination };
-    if (obj.search) criteria._search = { ...obj.search };
+    if (obj.search)
+      criteria._search = {
+        ...obj.search,
+        fields: obj.search.fields.map(criteria.resolveFieldPath),
+      };
 
     return criteria;
   }
 
-  static fromQueryParams<T>(query: Record<string, any>): Criteria<T> {
+  protected resolveFieldPath(field: FieldPath<T>): FieldPath<T> {
+    if (!this?._adapter) return field;
+
+    if (this._adapter[field]) {
+      return this._adapter[field] as FieldPath<T>;
+    }
+
+    const parts = field.split(".");
+    for (let i = parts.length; i > 0; i--) {
+      const prefix = parts.slice(0, i).join(".");
+      if (this._adapter[prefix]) {
+        const rest = parts.slice(i).join(".");
+        return rest
+          ? (`${this._adapter[prefix]}.${rest}` as FieldPath<T>)
+          : (this._adapter[prefix] as FieldPath<T>);
+      }
+    }
+
+    return field;
+  }
+
+  static fromQueryParams<T>(
+    query: Record<string, any>,
+    adapter?: CriteriaAdapter<any, any>
+  ): Criteria<T> {
     const criteria = Criteria.create<T>();
 
+    if (adapter) {
+      criteria.useAdapter(adapter);
+    }
+
     for (const [key, value] of Object.entries(query)) {
-      // Pagination
       if (key === "page") {
-        continue; // We'll handle pagination after
+        continue;
       }
       if (key === "limit") {
         continue;
@@ -218,35 +357,78 @@ export class Criteria<T = any> {
         continue;
       }
 
-      const [field, operatorRaw] = key.split(":");
+      const [field, operatorWithQuantifier] = key.split(":");
 
-      if (!operatorRaw || !field) continue;
+      if (!operatorWithQuantifier || !field) continue;
+
+      const [operatorRaw, quantifierRaw] = operatorWithQuantifier.split("@");
       const operator = isOperator(operatorRaw) ? operatorRaw : null;
-      if (!operator)
+      if (!operator) {
         throw new InvalidCriteriaError(`Invalid filter operator`, operatorRaw);
+      }
+
+      const validQuantifiers = ["some", "every", "none"];
+      const quantifier =
+        quantifierRaw && validQuantifiers.includes(quantifierRaw)
+          ? (quantifierRaw as CriteriaOptions["quantifier"])
+          : undefined;
+
+      if (quantifierRaw && !quantifier) {
+        throw new InvalidCriteriaError(
+          `Invalid quantifier. Valid values: ${validQuantifiers.join(", ")}`,
+          quantifierRaw
+        );
+      }
+
+      const options: CriteriaOptions | undefined = quantifier
+        ? { quantifier }
+        : undefined;
 
       let parsedValue: any = value;
 
+      const resolvedField = criteria.resolveFieldPath(field as FieldPath<T>);
+
       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]);
+          criteria.where(
+            resolvedField,
+            "between" as OperatorsForType<PathValue<T, FieldPath<T>>>,
+            [parsedValue[0], parsedValue[1]] as [
+              PathValue<T, FieldPath<T>>,
+              PathValue<T, FieldPath<T>>
+            ],
+            options
+          );
         }
         continue;
       }
 
       if (operator === "in" || operator === "notIn") {
         parsedValue = value.split(",").map(parseQueryValue);
-        criteria.where(field as any, operator, parsedValue);
+        criteria.where(
+          field as any,
+          operator as OperatorsForType<PathValue<T, FieldPath<T>>>,
+          parsedValue,
+          options
+        );
         continue;
       }
 
-      criteria.where(field as FieldPath<T>, operator, parseQueryValue(value));
+      const parsedFinalValue = parseQueryValue(value);
+
+      criteria.validateOperator(operator, parsedFinalValue);
+
+      criteria.where(
+        field as FieldPath<T>,
+        operator as OperatorsForType<PathValue<T, FieldPath<T>>>,
+        parsedFinalValue,
+        options
+      );
     }
 
-    // Pagination
     const page = query.page ? parseInt(query.page) : undefined;
     const limit = query.limit ? parseInt(query.limit) : undefined;
 
@@ -254,12 +436,14 @@ export class Criteria<T = any> {
       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 FieldPath<T>, (direction as OrderDirection) || "asc");
+        criteria.orderBy(
+          field as FieldPath<T>,
+          (direction as OrderDirection) || "asc"
+        );
       });
     }
 
@@ -268,24 +452,22 @@ export class Criteria<T = any> {
         .split(",")
         .filter(Boolean) as FieldPath<T>[];
 
-      criteria.search(fields, query.search as string);
+      const resolvedFields = fields.map(criteria.resolveFieldPath);
+      criteria.search(resolvedFields, 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 FILTER_OPERATORS.includes(value as FilterOperator);
+  private validateOperator(operator: FilterOperator, value: any): void {
+    if (value !== undefined && !isValidOperatorForType(value, operator)) {
+      const validOps = getValidOperatorsForType(value);
+      throw new InvalidCriteriaError(
+        `Operator "${operator}" is not valid for type "${typeof value}". 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/entity-changes.ts

@@ -0,0 +1,151 @@
+// ============================================================================
+// Entity Changes
+// Changes filtered by entity type
+// ============================================================================
+
+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;
+  }
+}