feat: nested fields

.changeset/twenty-chefs-grab.md

@@ -0,0 +1,36 @@
+---
+"@filter-def/in-memory": minor
+"@filter-def/bigquery": minor
+"@filter-def/drizzle": minor
+"@filter-def/core": minor
+---
+
+## Changes
+
+- Adds support for filtering on nested fields in `@filter-def/in-memory` and `@filter-def/bigquery` packages
+- errors for `@filter-def/drizzle`, due to driver-specific implementations. For now, we are driver agnostic.
+
+## Example (BigQuery):
+
+```typescript
+interface UserWithAddress {
+    name: { first: string; last: string };
+    address: { city: string; geo: { lat: number; lng: number } };
+}
+
+interface UserWithAddress {
+    name: { first: string; last: string };
+    address: { city: string; geo: { lat: number; lng: number } };
+}
+
+const userFilter = bigqueryFilter<UserWithAddress>().def({
+    firstName: { kind: "eq", field: "name.first" },
+    lat: { kind: "eq", field: "address.geo.lat" },
+});
+
+const where = userFilter({ firstName: 'Bob', lat: 25 });
+// {
+//     sql: 'name.first = @firstName AND address.geo.lat = @lat',
+//     params: { firstName: 'Bob', lat: 21 },
+// }
+```

packages/bigquery/src/bigquery-filter.spec.ts

@@ -878,3 +878,80 @@ describe("BigQuery Integration Usage Pattern", () => {
         // });
     });
 });
+
+describe("Nested field filtering", () => {
+    interface UserWithAddress {
+        name: { first: string; last: string };
+        address: { city: string; geo: { lat: number; lng: number } };
+    }
+
+    it("eq on nested field produces dot-path SQL with sanitized param", () => {
+        const filter = bigqueryFilter<UserWithAddress>().def({
+            firstName: { kind: "eq", field: "name.first" },
+        });
+        const result = filter({ firstName: "Alice" });
+        expect(result).toEqual({
+            sql: "name.first = @firstName",
+            params: { firstName: "Alice" },
+        });
+    });
+
+    it("handles booleans with nested fields", () => {
+        const filter = bigqueryFilter<UserWithAddress>().def({
+            firstName: { kind: "eq", field: "name.first" },
+            lat: { kind: "eq", field: "address.geo.lat" },
+        });
+
+        const result = filter({ firstName: "Bob", lat: 21 });
+
+        expect(result).toEqual({
+            sql: "name.first = @firstName AND address.geo.lat = @lat",
+            params: { firstName: "Bob", lat: 21 },
+        });
+    });
+
+    it("eq using key-as-path sanitizes param key", () => {
+        const filter = bigqueryFilter<UserWithAddress>().def({
+            "name.first": { kind: "eq" },
+        });
+        const result = filter({ "name.first": "Bob" });
+        expect(result).toEqual({
+            sql: "name.first = @name_first",
+            params: { name_first: "Bob" },
+        });
+    });
+
+    it("contains on nested field", () => {
+        const filter = bigqueryFilter<UserWithAddress>().def({
+            cityContains: {
+                kind: "contains",
+                field: "address.city",
+                caseInsensitive: true,
+            },
+        });
+        const result = filter({ cityContains: "port" });
+        expect(result).toEqual({
+            sql: "LOWER(address.city) LIKE LOWER(@cityContains)",
+            params: { cityContains: "%port%" },
+        });
+    });
+
+    it("gt on deeply nested field", () => {
+        const filter = bigqueryFilter<UserWithAddress>().def({
+            latAbove: { kind: "gt", field: "address.geo.lat" },
+        });
+        const result = filter({ latAbove: 46 });
+        expect(result).toEqual({
+            sql: "address.geo.lat > @latAbove",
+            params: { latAbove: 46 },
+        });
+    });
+
+    it("type-checks: nested field input has correct type", () => {
+        const filter = bigqueryFilter<UserWithAddress>().def({
+            firstName: { kind: "eq", field: "name.first" },
+        });
+        type Input = BigQueryFilterInput<typeof filter>;
+        expectTypeOf<Input["firstName"]>().toEqualTypeOf<string | undefined>();
+    });
+});

packages/bigquery/src/bigquery-filter.ts

@@ -195,7 +195,7 @@ const compileFilterDef = <Entity, TFilterDef extends BigQueryFilterDef<Entity>>(
                 continue;
             }
 
-            const result = compiler(filterValue, key);
+            const result = compiler(filterValue, sanitizeParamKey(key));
             sqlFragments.push(result.sql);
             Object.assign(allParams, result.params);
         }
@@ -265,7 +265,7 @@ const compileBooleanFilter = <Entity>(
                 for (let i = 0; i < compiledConditions.length; i++) {
                     const result = compiledConditions[i](
                         filterValue,
-                        `${key}_${i}`,
+                        `${sanitizeParamKey(key)}_${i}`,
                     );
                     fragments.push(result.sql);
                     Object.assign(params, result.params);
@@ -285,7 +285,7 @@ const compileBooleanFilter = <Entity>(
                 for (let i = 0; i < compiledConditions.length; i++) {
                     const result = compiledConditions[i](
                         filterValue,
-                        `${key}_${i}`,
+                        `${sanitizeParamKey(key)}_${i}`,
                     );
                     fragments.push(result.sql);
                     Object.assign(params, result.params);
@@ -383,3 +383,9 @@ const compilePrimitiveFilter = <Entity>(
             return () => EMPTY_FILTER_RESULT;
     }
 };
+
+/**
+ * Sanitizes a filter key to be used as a BigQuery parameter name
+ * by replacing dots with underscores.
+ */
+const sanitizeParamKey = (key: string): string => key.replace(/\./g, "_");

packages/core/src/index.ts

@@ -36,4 +36,10 @@ export type { AndFilter, BooleanFilter, OrFilter } from "./types.ts";
 export type { ValidateFilterDef } from "./types.ts";
 
 // Utilities
-export type { GetFieldForFilter, Simplify, TypeError } from "./types.ts";
+export type {
+    FieldPath,
+    GetFieldForFilter,
+    PathValue,
+    Simplify,
+    TypeError,
+} from "./types.ts";

packages/core/src/types.spec.ts

@@ -1,5 +1,5 @@
 import { describe, expectTypeOf, it } from "vitest";
-import type { CoreFilterInput } from "./types.ts";
+import type { CoreFilterInput, FieldPath, PathValue } from "./types.ts";
 
 interface User {
     id: string | null;
@@ -13,3 +13,59 @@ describe("CoreFilterInput", () => {
         expectTypeOf<EqInput>().toEqualTypeOf<string>();
     });
 });
+
+describe("FieldPath", () => {
+    interface Nested {
+        name: { first: string; last: string };
+        address: { city: string; geo: { lat: number; lng: number } };
+        age: number;
+    }
+
+    it("should produce top-level keys", () => {
+        type Paths = FieldPath<Nested>;
+        expectTypeOf<"age">().toMatchTypeOf<Paths>();
+        expectTypeOf<"name">().toMatchTypeOf<Paths>();
+    });
+
+    it("should produce dot-separated nested paths", () => {
+        type Paths = FieldPath<Nested>;
+        expectTypeOf<"name.first">().toMatchTypeOf<Paths>();
+        expectTypeOf<"address.geo.lat">().toMatchTypeOf<Paths>();
+    });
+
+    it("should not produce invalid paths", () => {
+        type Paths = FieldPath<Nested>;
+        expectTypeOf<"invalid">().not.toMatchTypeOf<Paths>();
+        expectTypeOf<"name.middle">().not.toMatchTypeOf<Paths>();
+    });
+});
+
+describe("PathValue", () => {
+    interface Nested {
+        name: { first: string; last: string };
+        age: number;
+    }
+
+    it("should resolve top-level field types", () => {
+        expectTypeOf<PathValue<Nested, "age">>().toEqualTypeOf<number>();
+    });
+
+    it("should resolve nested field types", () => {
+        expectTypeOf<PathValue<Nested, "name.first">>().toEqualTypeOf<string>();
+    });
+});
+
+describe("CoreFilterInput with nested fields", () => {
+    interface Nested {
+        name: { first: string; last: string };
+    }
+
+    it("should resolve input type for nested field path", () => {
+        type EqInput = CoreFilterInput<
+            "firstName",
+            Nested,
+            { kind: "eq"; field: "name.first" }
+        >;
+        expectTypeOf<EqInput>().toEqualTypeOf<string>();
+    });
+});

packages/core/src/types.ts

@@ -37,8 +37,61 @@ export type PrimitiveFilter<Entity> =
     | LTFilter<Entity>
     | LTEFilter<Entity>;
 
+/**
+ * Produces a union of all dot-separated paths into T.
+ *
+ *   FieldPath<{ name: { first: string } }>
+ *   // => "name" | "name.first"
+ *
+ * Depth is capped to avoid TS instantiation-depth errors on large types.
+ */
+export type FieldPath<T, Depth extends number = 4> = [Depth] extends [0]
+    ? never
+    : IsPlainObject<T> extends true
+      ? {
+            [K in Extract<keyof T, string>]:
+                | K
+                | (IsPlainObject<NonNullable<T[K]>> extends true
+                      ? `${K}.${FieldPath<NonNullable<T[K]>, DepthLimit[Depth]>}`
+                      : never);
+        }[Extract<keyof T, string>]
+      : never;
+
+/**
+ * Helper type to limit recursion depth in FieldPath to prevent TS errors.
+ */
+type DepthLimit = [never, 0, 1, 2, 3];
+
+/**
+ * Helper type to check if a type is a plain object (not a function, array, or date).
+ */
+type IsPlainObject<T> = T extends object
+    ? T extends Function | readonly any[] | Date
+        ? false
+        : true
+    : false;
+
+/**
+ * Resolves the value type at a dot-separated path.
+ *
+ * ```typescript
+ * PathValue<{ name: { first: string } }, "name.first">
+ * // => string
+ * ```
+ */
+export type PathValue<
+    T,
+    P extends string,
+> = P extends `${infer K}.${infer Rest}`
+    ? K extends keyof T
+        ? PathValue<NonNullable<T[K]>, Rest>
+        : never
+    : P extends keyof T
+      ? T[P]
+      : never;
+
 export interface CommonFilterOptions<Entity> {
-    field?: keyof Entity;
+    field?: FieldPath<Entity>;
 }
 
 /**
@@ -172,7 +225,10 @@ type FieldTypeForFilter<
     TFilterField extends CoreFilter<Entity>,
     TFilter extends CoreFilter<Entity>,
 > = Exclude<
-    Entity[GetFieldForFilter<K, Entity, Extract<TFilterField, TFilter>>],
+    PathValue<
+        Entity,
+        GetFieldForFilter<K, Entity, Extract<TFilterField, TFilter>> & string
+    >,
     null | undefined
 >;
 
@@ -304,7 +360,7 @@ export type ValidateFilterDef<Entity, TFilterDef> = {
           : TFilterDef[K] extends (...args: any[]) => any
             ? // Custom filters do not rely on fields, so they are always valid.
               TFilterDef[K]
-            : K extends keyof Entity
+            : K extends FieldPath<Entity>
               ? // We otherwise require the filter key to be a valid field.
                 TFilterDef[K]
               : // Everything else is invalid
@@ -353,8 +409,8 @@ export type GetFieldForFilter<
     K extends PropertyKey,
     Entity,
     TFilterField,
-> = TFilterField extends { field: infer F extends keyof Entity }
+> = TFilterField extends { field: infer F extends FieldPath<Entity> }
     ? F
-    : K extends keyof Entity
+    : K extends FieldPath<Entity>
       ? K
       : never;

packages/drizzle/src/drizzle-filter.spec.ts

@@ -1228,3 +1228,13 @@ describe("SQL Output Verification", () => {
         expect(where).toBeDefined();
     });
 });
+
+describe("Nested field paths", () => {
+    it("should throw for nested field paths", () => {
+        expect(() =>
+            drizzleFilter(usersTable).def({
+                firstName: { kind: "eq", field: "name.first" as any },
+            }),
+        ).toThrow(/Nested field path.*not supported by drizzleFilter/);
+    });
+});

packages/drizzle/src/drizzle-filter.ts

@@ -285,6 +285,15 @@ const compilePrimitiveFilter = <Entity>(
     filterField: PrimitiveFilter<Entity>,
 ): CompiledFilterField => {
     const fieldName = (filterField.field ?? key) as string;
+
+    if (fieldName.includes(".")) {
+        throw new Error(
+            `Nested field path "${fieldName}" is not supported by drizzleFilter. ` +
+                `Drizzle operates on flat table columns. Use a custom filter with ` +
+                `JSON operators or joins for nested data.`,
+        );
+    }
+
     const column = columns[fieldName];
 
     if (!column) {