@woltz/rich-domain 1.1.0 → 1.2.0

package/src/types/criteria.ts

@@ -17,12 +17,65 @@ export const FILTER_OPERATORS = [
   "isNotNull",
 ] as const;
 
+export type FilterOperator = (typeof FILTER_OPERATORS)[number];
+
+export type StringOperators =
+  | "equals"
+  | "notEquals"
+  | "contains"
+  | "startsWith"
+  | "endsWith"
+  | "in"
+  | "notIn"
+  | "isNull"
+  | "isNotNull";
+
+export type NumberOperators =
+  | "equals"
+  | "notEquals"
+  | "greaterThan"
+  | "greaterThanOrEqual"
+  | "lessThan"
+  | "lessThanOrEqual"
+  | "in"
+  | "notIn"
+  | "between"
+  | "isNull"
+  | "isNotNull";
+
+export type DateOperators =
+  | "equals"
+  | "notEquals"
+  | "greaterThan"
+  | "greaterThanOrEqual"
+  | "lessThan"
+  | "lessThanOrEqual"
+  | "in"
+  | "notIn"
+  | "between"
+  | "isNull"
+  | "isNotNull";
+
+export type BooleanOperators = "equals" | "notEquals" | "isNull" | "isNotNull";
+
+export type ArrayOperators = "in" | "notIn" | "isNull" | "isNotNull";
+
+export type OperatorsForType<T> = T extends string
+  ? StringOperators
+  : T extends number
+  ? NumberOperators
+  : T extends Date
+  ? DateOperators
+  : T extends boolean
+  ? BooleanOperators
+  : T extends Array<any>
+  ? ArrayOperators
+  : FilterOperator;
+
 export type FilterValueFor<T> =
-  | T // equals, notEquals
-  | (T extends number | Date
-      ? [T, T] // between
-      : never)
-  | T[] // in, notIn
+  | T
+  | (T extends number | Date ? [T, T] : never)
+  | T[]
   | null;
 
 export type PathValue<
@@ -30,24 +83,34 @@ export type PathValue<
   P extends string
 > = P extends `${infer K}.${infer Rest}`
   ? K extends keyof T
-    ? PathValue<T[K], Rest>
+    ? T[K] extends Array<infer U>
+      ? PathValue<U, Rest>
+      : PathValue<T[K], Rest>
     : never
   : P extends keyof T
   ? T[P]
   : never;
 
-export type FilterOperator = (typeof FILTER_OPERATORS)[number];
-
 export interface Filter<TField = string, TValue = unknown> {
   field: TField;
-  operator: FilterOperator;
+  operator: unknown extends TValue ? FilterOperator : OperatorsForType<TValue>;
   value: TValue;
+  options?: CriteriaOptions;
 }
 
 export type TypedFilter<T> = {
-  [K in FieldPath<T>]: Filter<K, FilterValueFor<PathValue<T, K>>>;
+  [K in FieldPath<T>]: {
+    field: K;
+    operator: OperatorsForType<NonNullable<PathValue<T, K>>>;
+    value: FilterValueFor<NonNullable<PathValue<T, K>>>;
+    options?: CriteriaOptions;
+  };
 }[FieldPath<T>];
 
+export type CriteriaAdapter<Input, Output> = {
+  [K in FieldPath<Input>]?: FieldPath<Output>;
+};
+
 export type OrderDirection = "asc" | "desc";
 
 export interface Order {
@@ -75,10 +138,20 @@ export interface PaginationMeta {
   hasPrevious: boolean;
 }
 
-export type FieldPath<T> = {
-  [K in keyof T & string]: T[K] extends Primitive
-    ? K
-    : T[K] extends Array<infer U>
-    ? K | `${K}.${FieldPath<U>}`
-    : K | `${K}.${FieldPath<T[K]>}`;
-}[keyof T & string];
+export interface CriteriaOptions {
+  quantifier?: "some" | "every" | "none";
+}
+
+type ExcludeBuiltInKeys<T> = Exclude<keyof T, keyof any[] | number | symbol>;
+
+export type FieldPath<T> = T extends Primitive
+  ? never
+  : {
+      [K in ExcludeBuiltInKeys<T> & string]: NonNullable<T[K]> extends Primitive
+        ? K
+        : NonNullable<T[K]> extends Array<infer U>
+        ? U extends Primitive
+          ? K
+          : K | `${K}.${FieldPath<U>}`
+        : K | `${K}.${FieldPath<NonNullable<T[K]>>}`;
+    }[ExcludeBuiltInKeys<T> & string];

package/src/utils/criteria-operator-validation.ts

@@ -0,0 +1,171 @@
+import {
+  ArrayOperators,
+  BooleanOperators,
+  DateOperators,
+  FILTER_OPERATORS,
+  FilterOperator,
+  NumberOperators,
+  StringOperators,
+} from "../types";
+
+export function isValidOperatorForType(
+  value: unknown,
+  operator: FilterOperator
+): boolean {
+  // Handle null/undefined
+  if (value === null || value === undefined) {
+    return ["isNull", "isNotNull", "equals", "notEquals"].includes(operator);
+  }
+
+  // Special case: between operator with array [min, max]
+  if (operator === "between" && Array.isArray(value) && value.length === 2) {
+    // Validate based on the type of the first element
+    const elementType = typeof value[0];
+    if (elementType === "number" || value[0] instanceof Date) {
+      return true;
+    }
+    return false;
+  }
+
+  const valueType = typeof value;
+
+  // String operators
+  if (valueType === "string") {
+    const validOps: StringOperators[] = [
+      "equals",
+      "notEquals",
+      "contains",
+      "startsWith",
+      "endsWith",
+      "in",
+      "notIn",
+      "isNull",
+      "isNotNull",
+    ];
+    return validOps.includes(operator as StringOperators);
+  }
+
+  // Number operators
+  if (valueType === "number") {
+    const validOps: NumberOperators[] = [
+      "equals",
+      "notEquals",
+      "greaterThan",
+      "greaterThanOrEqual",
+      "lessThan",
+      "lessThanOrEqual",
+      "in",
+      "notIn",
+      "between",
+      "isNull",
+      "isNotNull",
+    ];
+    return validOps.includes(operator as NumberOperators);
+  }
+
+  // Boolean operators
+  if (valueType === "boolean") {
+    const validOps: BooleanOperators[] = [
+      "equals",
+      "notEquals",
+      "isNull",
+      "isNotNull",
+    ];
+    return validOps.includes(operator as BooleanOperators);
+  }
+
+  // Date operators
+  if (value instanceof Date) {
+    const validOps: DateOperators[] = [
+      "equals",
+      "notEquals",
+      "greaterThan",
+      "greaterThanOrEqual",
+      "lessThan",
+      "lessThanOrEqual",
+      "in",
+      "notIn",
+      "between",
+      "isNull",
+      "isNotNull",
+    ];
+    return validOps.includes(operator as DateOperators);
+  }
+
+  // Array operators
+  if (Array.isArray(value)) {
+    const validOps: ArrayOperators[] = ["in", "notIn", "isNull", "isNotNull"];
+    return validOps.includes(operator as ArrayOperators);
+  }
+
+  // For unknown types, allow all operators
+  return true;
+}
+
+export function getValidOperatorsForType(value: unknown): FilterOperator[] {
+  if (value === null || value === undefined) {
+    return ["isNull", "isNotNull", "equals", "notEquals"];
+  }
+
+  const valueType = typeof value;
+
+  if (valueType === "string" && Number.isNaN(Number(value))) {
+    return [
+      "equals",
+      "notEquals",
+      "contains",
+      "startsWith",
+      "endsWith",
+      "in",
+      "notIn",
+      "isNull",
+      "isNotNull",
+    ];
+  }
+
+  if (valueType === "number") {
+    return [
+      "equals",
+      "notEquals",
+      "greaterThan",
+      "greaterThanOrEqual",
+      "lessThan",
+      "lessThanOrEqual",
+      "in",
+      "notIn",
+      "between",
+      "isNull",
+      "isNotNull",
+    ];
+  }
+
+  if (valueType === "boolean") {
+    return ["equals", "notEquals", "isNull", "isNotNull"];
+  }
+
+  if (value instanceof Date) {
+    return [
+      "equals",
+      "notEquals",
+      "greaterThan",
+      "greaterThanOrEqual",
+      "lessThan",
+      "lessThanOrEqual",
+      "in",
+      "notIn",
+      "between",
+      "isNull",
+      "isNotNull",
+    ];
+  }
+
+  if (Array.isArray(value)) {
+    return ["in", "notIn", "isNull", "isNotNull"];
+  }
+
+  return [...FILTER_OPERATORS];
+}
+
+export function isOperator(value: string): value is FilterOperator {
+  return FILTER_OPERATORS.includes(value as FilterOperator);
+}

package/src/utils/helpers.ts

@@ -0,0 +1,6 @@
+export 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
+}

package/tests/criteria.test.ts

@@ -1,6 +1,7 @@
 import { Pagination } from "../src";
 import { Criteria } from "../src/criteria";
 import { PaginatedResult } from "../src/paginated-result";
+import { CriteriaAdapter } from "../src/types";
 import { Post } from "./utils";
 
 interface TestUser {
@@ -12,6 +13,17 @@ interface TestUser {
   createdAt: Date;
 }
 
+interface UserWithPostsDto {
+  id: string;
+  name: string;
+  posts: { title: string; content: string }[];
+  leads: {
+    contact: {
+      name: string;
+    };
+  }[];
+}
+
 const testUsers: TestUser[] = [
   {
     id: "1",
@@ -56,6 +68,20 @@ const testUsers: TestUser[] = [
 ];
 
 describe("Criteria", () => {
+  describe("Search", () => {
+    it("should search by all items ignoring pagination and limit", () => {
+      const criteria = Criteria.create<TestUser>()
+        .search(["name"], "Eve")
+        .paginate(3, 1);
+      const result = PaginatedResult.fromArray(testUsers, criteria);
+      expect(result.data).toHaveLength(1);
+      expect(result.data[0].name).toBe("Eve");
+      expect(result.meta.total).toBe(1);
+      expect(result.meta.totalPages).toBe(1);
+      expect(result.meta.page).toBe(1);
+      expect(result.meta.limit).toBe(1);
+    });
+  });
   describe("Fluent API", () => {
     it("should create empty criteria", () => {
       const criteria = Criteria.create<TestUser>();
@@ -297,7 +323,7 @@ describe("Criteria", () => {
 
       expect(result.data).toHaveLength(2);
       expect(result.data.map((u) => u.name)).toEqual(["Bob", "Diana"]);
-      expect(result.meta.total).toBe(3); // Total active users
+      expect(result.meta.total).toBe(3);
       expect(result.meta.totalPages).toBe(2);
     });
   });
@@ -437,4 +463,293 @@ describe("Criteria", () => {
       expect(criteria.getPagination()?.limit).toBe(2);
     });
   });
+
+  describe("Quantifiers", () => {
+    describe("Fluent API methods", () => {
+      it("should create filter with whereSome", () => {
+        const criteria = Criteria.create<UserWithPostsDto>().whereSome(
+          "posts.title",
+          "contains",
+          "test"
+        );
+
+        const filters = criteria.getFilters();
+
+        expect(filters).toHaveLength(1);
+        expect(filters[0].field).toBe("posts.title");
+        expect(filters[0].operator).toBe("contains");
+        expect(filters[0].value).toBe("test");
+        expect(filters[0].options?.quantifier).toBe("some");
+      });
+
+      it("should create filter with whereEvery", () => {
+        const criteria = Criteria.create<UserWithPostsDto>().whereEvery(
+          "posts.title",
+          "contains",
+          "test"
+        );
+
+        const filters = criteria.getFilters();
+        expect(filters).toHaveLength(1);
+        expect(filters[0].options?.quantifier).toBe("every");
+      });
+
+      it("should create filter with whereNone", () => {
+        const criteria = Criteria.create<UserWithPostsDto>().whereNone(
+          "posts.title",
+          "contains",
+          "test"
+        );
+
+        const filters = criteria.getFilters();
+        expect(filters).toHaveLength(1);
+        expect(filters[0].options?.quantifier).toBe("none");
+      });
+
+      it("should create filter without quantifier using where", () => {
+        const criteria = Criteria.create<UserWithPostsDto>().where(
+          "posts.title",
+          "contains",
+          "test"
+        );
+
+        const filters = criteria.getFilters();
+        expect(filters).toHaveLength(1);
+        expect(filters[0].options).toBeUndefined();
+      });
+    });
+
+    describe("fromQueryParams with quantifier", () => {
+      it("should parse quantifier from query params with @some", () => {
+        const queryParams = {
+          "posts.title:contains@some": "test",
+        };
+
+        const criteria =
+          Criteria.fromQueryParams<UserWithPostsDto>(queryParams);
+        const filters = criteria.getFilters();
+
+        expect(filters).toHaveLength(1);
+        expect(filters[0].field).toBe("posts.title");
+        expect(filters[0].operator).toBe("contains");
+        expect(filters[0].value).toBe("test");
+        expect(filters[0].options?.quantifier).toBe("some");
+      });
+
+      it("should parse quantifier from query params with @every", () => {
+        const queryParams = {
+          "posts.title:equals@every": "test",
+        };
+
+        const criteria =
+          Criteria.fromQueryParams<UserWithPostsDto>(queryParams);
+        const filters = criteria.getFilters();
+
+        expect(filters).toHaveLength(1);
+        expect(filters[0].options?.quantifier).toBe("every");
+      });
+
+      it("should parse quantifier from query params with @none", () => {
+        const queryParams = {
+          "posts.title:contains@none": "spam",
+        };
+
+        const criteria =
+          Criteria.fromQueryParams<UserWithPostsDto>(queryParams);
+        const filters = criteria.getFilters();
+
+        expect(filters).toHaveLength(1);
+        expect(filters[0].options?.quantifier).toBe("none");
+      });
+
+      it("should work with in operator and quantifier", () => {
+        const queryParams = {
+          "posts.title:in@some": "test1,test2,test3",
+        };
+
+        const criteria =
+          Criteria.fromQueryParams<UserWithPostsDto>(queryParams);
+        const filters = criteria.getFilters();
+
+        expect(filters).toHaveLength(1);
+        expect(filters[0].operator).toBe("in");
+        expect(filters[0].value).toEqual(["test1", "test2", "test3"]);
+        expect(filters[0].options?.quantifier).toBe("some");
+      });
+
+      it("should work with between operator and quantifier", () => {
+        const queryParams = {
+          "posts.likes:between@some": "10,100",
+        };
+
+        const criteria =
+          Criteria.fromQueryParams<UserWithPostsDto>(queryParams);
+        const filters = criteria.getFilters();
+
+        expect(filters).toHaveLength(1);
+        expect(filters[0].operator).toBe("between");
+        expect(filters[0].value).toEqual([10, 100]);
+        expect(filters[0].options?.quantifier).toBe("some");
+      });
+
+      it("should maintain backward compatibility without quantifier", () => {
+        const queryParams = {
+          "posts.title:contains": "test",
+        };
+
+        const criteria =
+          Criteria.fromQueryParams<UserWithPostsDto>(queryParams);
+        const filters = criteria.getFilters();
+
+        expect(filters).toHaveLength(1);
+        expect(filters[0].field).toBe("posts.title");
+        expect(filters[0].operator).toBe("contains");
+        expect(filters[0].value).toBe("test");
+        expect(filters[0].options).toBeUndefined();
+      });
+
+      it("should throw error for invalid quantifier", () => {
+        const queryParams = {
+          "posts.title:contains@invalid": "test",
+        };
+
+        expect(() => {
+          Criteria.fromQueryParams<UserWithPostsDto>(queryParams);
+        }).toThrow("Invalid quantifier");
+      });
+
+      it("should handle multiple filters with mixed quantifiers", () => {
+        const queryParams = {
+          "posts.title:contains@some": "test",
+          "posts.content:equals@every": "content",
+          "name:contains": "John",
+        };
+
+        const criteria =
+          Criteria.fromQueryParams<UserWithPostsDto>(queryParams);
+        const filters = criteria.getFilters();
+
+        expect(filters).toHaveLength(3);
+        expect(filters[0].options?.quantifier).toBe("some");
+        expect(filters[1].options?.quantifier).toBe("every");
+        expect(filters[2].options).toBeUndefined();
+      });
+    });
+
+    describe("fromObject with quantifier", () => {
+      it("should create criteria from object with quantifier", () => {
+        const criteria = Criteria.fromObject<UserWithPostsDto>({
+          filters: [
+            {
+              field: "posts.title",
+              operator: "contains",
+              value: "test",
+              options: { quantifier: "some" },
+            },
+          ],
+        });
+
+        const filters = criteria.getFilters();
+        expect(filters).toHaveLength(1);
+        expect(filters[0].options?.quantifier).toBe("some");
+      });
+
+      it("should preserve quantifier when cloning", () => {
+        const original = Criteria.create<UserWithPostsDto>().whereSome(
+          "posts.title",
+          "contains",
+          "test"
+        );
+
+        const cloned = original.clone();
+        const filters = cloned.getFilters();
+
+        expect(filters).toHaveLength(1);
+        expect(filters[0].options?.quantifier).toBe("some");
+      });
+    });
+
+    describe("toJSON with quantifier", () => {
+      it("should serialize quantifier to JSON", () => {
+        const criteria = Criteria.create<UserWithPostsDto>()
+          .whereSome("posts.title", "contains", "test")
+          .whereEvery("posts.content", "equals", "content");
+
+        const json = criteria.toJSON();
+
+        expect(json.filters).toHaveLength(2);
+        expect(json.filters[0].options?.quantifier).toBe("some");
+        expect(json.filters[1].options?.quantifier).toBe("every");
+      });
+    });
+  });
+
+  describe("Adapter", () => {
+    type UserInDatabase = {
+      id: string;
+      name: string;
+      user_posts: { title: string; content: string }[];
+      leads: {
+        contact: {
+          fullName: string;
+        };
+      };
+    };
+    const UserWithPostsAdapter: CriteriaAdapter<
+      UserWithPostsDto,
+      UserInDatabase
+    > = {
+      posts: "user_posts",
+      "leads.contact.name": "leads.contact.fullName",
+    };
+
+    let criteria: Criteria<UserWithPostsDto>;
+    beforeEach(() => {
+      criteria =
+        Criteria.create<UserWithPostsDto>().useAdapter(UserWithPostsAdapter);
+    });
+
+    it("should resolve field path", () => {
+      const filters = criteria
+        .where("leads.contact.name", "contains", "John")
+        .getFilters();
+
+      expect(filters[0].field).toBe("leads.contact.fullName");
+    });
+
+    it("should resolve field path from query params", () => {
+      const queryParams = {
+        "posts:contains": "test",
+      };
+
+      const result = Criteria.fromQueryParams<UserWithPostsDto>(
+        queryParams,
+        UserWithPostsAdapter
+      );
+      const filters = result.getFilters();
+
+      expect(filters).toHaveLength(1);
+      expect(filters[0].field).toBe("user_posts");
+      expect(filters[0].operator).toBe("contains");
+      expect(filters[0].value).toBe("test");
+    });
+
+    it("should resolve field path from object", () => {
+      const criteria = Criteria.fromObject<UserWithPostsDto>(
+        {
+          filters: [
+            {
+              field: "posts",
+              operator: "in",
+              value: [{ title: "test", content: "test" }],
+            },
+          ],
+        },
+        UserWithPostsAdapter
+      );
+      const filters = criteria.getFilters();
+      expect(filters).toHaveLength(1);
+      expect(filters[0].field).toBe("user_posts");
+    });
+  });
 });