@woltz/rich-domain 1.0.0 → 1.2.0

package/src/criteria.ts

@@ -1,69 +1,93 @@
+import { InvalidCriteriaError } from "./exceptions";
 import {
+  CriteriaAdapter,
+  CriteriaOptions,
   FieldPath,
   Filter,
-  FILTER_OPERATORS,
   FilterOperator,
   FilterValueFor,
+  OperatorsForType,
   Order,
   OrderDirection,
   Pagination,
   PathValue,
+  Search,
   TypedFilter,
 } from "./types";
+import {
+  isValidOperatorForType,
+  getValidOperatorsForType,
+  isOperator,
+} from "./utils/criteria-operator-validation";
+import { parseQueryValue } from "./utils/helpers";
 
-// ============================================================================
-// Filter Types
-// ============================================================================
-
-export class Criteria<T = unknown> {
+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?: {
-    fields: FieldPath<T>[];
-    value: string;
-  };
+  private _search?: Search<T>;
+  private _adapter?: CriteriaAdapter<any, any>;
 
   private constructor() {}
 
-  /**
-   * Create a new Criteria instance
-   */
-  static create<T = unknown>(): Criteria<T> {
+  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>>(
@@ -71,28 +95,51 @@ export class Criteria<T = unknown> {
     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;
@@ -106,13 +153,9 @@ export class Criteria<T = unknown> {
     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;
@@ -123,11 +166,14 @@ export class Criteria<T = unknown> {
   }
 
   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;
@@ -144,14 +190,20 @@ export class Criteria<T = unknown> {
     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 {
@@ -170,47 +222,132 @@ export class Criteria<T = unknown> {
     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?: Order[];
+      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;
@@ -219,34 +356,78 @@ export class Criteria<T = unknown> {
         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) throw new Error(`Invalid filter operator: ${operatorRaw}`);
+      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 any, 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 +435,14 @@ export class Criteria<T = unknown> {
       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");
+        criteria.orderBy(
+          field as FieldPath<T>,
+          (direction as OrderDirection) || "asc"
+        );
       });
     }
 
@@ -268,24 +451,22 @@ export class Criteria<T = unknown> {
         .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
+      );
+    }
+  }
 }