postgresdk 0.9.9 → 0.10.1

package/dist/index.js

@@ -1169,6 +1169,187 @@ function generateUnifiedContractMarkdown(contract) {
       lines.push("");
     }
   }
+  lines.push("## Filtering with WHERE Clauses");
+  lines.push("");
+  lines.push("The SDK provides type-safe WHERE clause filtering with support for various operators.");
+  lines.push("");
+  lines.push("### Basic Filtering");
+  lines.push("");
+  lines.push("**Direct equality:**");
+  lines.push("");
+  lines.push("```typescript");
+  lines.push("// Find users with specific email");
+  lines.push("const users = await sdk.users.list({");
+  lines.push("  where: { email: 'user@example.com' }");
+  lines.push("});");
+  lines.push("");
+  lines.push("// Multiple conditions (AND)");
+  lines.push("const activeUsers = await sdk.users.list({");
+  lines.push("  where: {");
+  lines.push("    status: 'active',");
+  lines.push("    role: 'admin'");
+  lines.push("  }");
+  lines.push("});");
+  lines.push("```");
+  lines.push("");
+  lines.push("### Comparison Operators");
+  lines.push("");
+  lines.push("Use comparison operators for numeric, date, and other comparable fields:");
+  lines.push("");
+  lines.push("```typescript");
+  lines.push("// Greater than / Less than");
+  lines.push("const adults = await sdk.users.list({");
+  lines.push("  where: { age: { $gt: 18 } }");
+  lines.push("});");
+  lines.push("");
+  lines.push("// Range queries");
+  lines.push("const workingAge = await sdk.users.list({");
+  lines.push("  where: {");
+  lines.push("    age: { $gte: 18, $lte: 65 }");
+  lines.push("  }");
+  lines.push("});");
+  lines.push("");
+  lines.push("// Not equal");
+  lines.push("const notPending = await sdk.orders.list({");
+  lines.push("  where: { status: { $ne: 'pending' } }");
+  lines.push("});");
+  lines.push("```");
+  lines.push("");
+  lines.push("### String Operators");
+  lines.push("");
+  lines.push("Pattern matching for string fields:");
+  lines.push("");
+  lines.push("```typescript");
+  lines.push("// Case-sensitive LIKE");
+  lines.push("const johnsmiths = await sdk.users.list({");
+  lines.push("  where: { name: { $like: '%Smith%' } }");
+  lines.push("});");
+  lines.push("");
+  lines.push("// Case-insensitive ILIKE");
+  lines.push("const gmailUsers = await sdk.users.list({");
+  lines.push("  where: { email: { $ilike: '%@gmail.com' } }");
+  lines.push("});");
+  lines.push("```");
+  lines.push("");
+  lines.push("### Array Operators");
+  lines.push("");
+  lines.push("Filter by multiple possible values:");
+  lines.push("");
+  lines.push("```typescript");
+  lines.push("// IN - match any value in array");
+  lines.push("const specificUsers = await sdk.users.list({");
+  lines.push("  where: {");
+  lines.push("    id: { $in: ['id1', 'id2', 'id3'] }");
+  lines.push("  }");
+  lines.push("});");
+  lines.push("");
+  lines.push("// NOT IN - exclude values");
+  lines.push("const nonSystemUsers = await sdk.users.list({");
+  lines.push("  where: {");
+  lines.push("    role: { $nin: ['admin', 'system'] }");
+  lines.push("  }");
+  lines.push("});");
+  lines.push("```");
+  lines.push("");
+  lines.push("### NULL Checks");
+  lines.push("");
+  lines.push("Check for null or non-null values:");
+  lines.push("");
+  lines.push("```typescript");
+  lines.push("// IS NULL");
+  lines.push("const activeRecords = await sdk.records.list({");
+  lines.push("  where: { deleted_at: { $is: null } }");
+  lines.push("});");
+  lines.push("");
+  lines.push("// IS NOT NULL");
+  lines.push("const deletedRecords = await sdk.records.list({");
+  lines.push("  where: { deleted_at: { $isNot: null } }");
+  lines.push("});");
+  lines.push("```");
+  lines.push("");
+  lines.push("### Combining Operators");
+  lines.push("");
+  lines.push("Mix multiple operators for complex queries:");
+  lines.push("");
+  lines.push("```typescript");
+  lines.push("const filteredUsers = await sdk.users.list({");
+  lines.push("  where: {");
+  lines.push("    age: { $gte: 18, $lt: 65 },");
+  lines.push("    email: { $ilike: '%@company.com' },");
+  lines.push("    status: { $in: ['active', 'pending'] },");
+  lines.push("    deleted_at: { $is: null }");
+  lines.push("  },");
+  lines.push("  limit: 50,");
+  lines.push("  offset: 0");
+  lines.push("});");
+  lines.push("```");
+  lines.push("");
+  lines.push("### Available Operators");
+  lines.push("");
+  lines.push("| Operator | Description | Example | Types |");
+  lines.push("|----------|-------------|---------|-------|");
+  lines.push("| `$eq` | Equal to | `{ age: { $eq: 25 } }` | All |");
+  lines.push("| `$ne` | Not equal to | `{ status: { $ne: 'inactive' } }` | All |");
+  lines.push("| `$gt` | Greater than | `{ price: { $gt: 100 } }` | Number, Date |");
+  lines.push("| `$gte` | Greater than or equal | `{ age: { $gte: 18 } }` | Number, Date |");
+  lines.push("| `$lt` | Less than | `{ quantity: { $lt: 10 } }` | Number, Date |");
+  lines.push("| `$lte` | Less than or equal | `{ age: { $lte: 65 } }` | Number, Date |");
+  lines.push("| `$in` | In array | `{ id: { $in: ['a', 'b'] } }` | All |");
+  lines.push("| `$nin` | Not in array | `{ role: { $nin: ['admin'] } }` | All |");
+  lines.push("| `$like` | Pattern match (case-sensitive) | `{ name: { $like: '%John%' } }` | String |");
+  lines.push("| `$ilike` | Pattern match (case-insensitive) | `{ email: { $ilike: '%@GMAIL%' } }` | String |");
+  lines.push("| `$is` | IS NULL | `{ deleted_at: { $is: null } }` | Nullable fields |");
+  lines.push("| `$isNot` | IS NOT NULL | `{ created_by: { $isNot: null } }` | Nullable fields |");
+  lines.push("");
+  lines.push("### Logical Operators");
+  lines.push("");
+  lines.push("Combine conditions using `$or` and `$and` (supports 2 levels of nesting):");
+  lines.push("");
+  lines.push("| Operator | Description | Example |");
+  lines.push("|----------|-------------|---------|");
+  lines.push("| `$or` | Match any condition | `{ $or: [{ status: 'active' }, { role: 'admin' }] }` |");
+  lines.push("| `$and` | Match all conditions (explicit) | `{ $and: [{ age: { $gte: 18 } }, { status: 'verified' }] }` |");
+  lines.push("");
+  lines.push("```typescript");
+  lines.push("// OR - match any condition");
+  lines.push("const results = await sdk.users.list({");
+  lines.push("  where: {");
+  lines.push("    $or: [");
+  lines.push("      { email: { $ilike: '%@gmail.com' } },");
+  lines.push("      { status: 'premium' }");
+  lines.push("    ]");
+  lines.push("  }");
+  lines.push("});");
+  lines.push("");
+  lines.push("// Mixed AND + OR (implicit AND at root level)");
+  lines.push("const complex = await sdk.users.list({");
+  lines.push("  where: {");
+  lines.push("    status: 'active',  // AND");
+  lines.push("    $or: [");
+  lines.push("      { age: { $lt: 18 } },");
+  lines.push("      { age: { $gt: 65 } }");
+  lines.push("    ]");
+  lines.push("  }");
+  lines.push("});");
+  lines.push("");
+  lines.push("// Nested (2 levels max)");
+  lines.push("const nested = await sdk.users.list({");
+  lines.push("  where: {");
+  lines.push("    $and: [");
+  lines.push("      {");
+  lines.push("        $or: [");
+  lines.push("          { firstName: { $ilike: '%john%' } },");
+  lines.push("          { lastName: { $ilike: '%john%' } }");
+  lines.push("        ]");
+  lines.push("      },");
+  lines.push("      { status: 'active' }");
+  lines.push("    ]");
+  lines.push("  }");
+  lines.push("});");
+  lines.push("```");
+  lines.push("");
+  lines.push("**Note:** The WHERE clause types are fully type-safe. TypeScript will only allow operators that are valid for each field type.");
+  lines.push("");
   lines.push("## Resources");
   lines.push("");
   for (const resource of contract.resources) {
@@ -1493,7 +1674,14 @@ function buildGraph(model) {
 
 // src/emit-include-spec.ts
 function emitIncludeSpec(graph) {
-  let out = `/* Generated. Do not edit. */
+  let out = `/**
+ * AUTO-GENERATED FILE - DO NOT EDIT
+ *
+ * This file was automatically generated by PostgreSDK.
+ * Any manual changes will be overwritten on the next generation.
+ *
+ * To make changes, modify your schema or configuration and regenerate.
+ */
 `;
   const tables = Object.keys(graph);
   for (const table of tables) {
@@ -1522,7 +1710,14 @@ function toPascal(s) {
 
 // src/emit-include-builder.ts
 function emitIncludeBuilder(graph, maxDepth) {
-  return `// Generated. Do not edit.
+  return `/**
+ * AUTO-GENERATED FILE - DO NOT EDIT
+ *
+ * This file was automatically generated by PostgreSDK.
+ * Any manual changes will be overwritten on the next generation.
+ *
+ * To make changes, modify your schema or configuration and regenerate.
+ */
 export const RELATION_GRAPH = ${JSON.stringify(graph, null, 2)} as const;
 type TableName = keyof typeof RELATION_GRAPH;
 
@@ -1670,7 +1865,14 @@ function emitHonoRoutes(table, _graph, opts) {
   const hasAuth = opts.authStrategy && opts.authStrategy !== "none";
   const ext = opts.useJsExtensions ? ".js" : "";
   const authImport = hasAuth ? `import { authMiddleware } from "../auth${ext}";` : "";
-  return `/* Generated. Do not edit. */
+  return `/**
+ * AUTO-GENERATED FILE - DO NOT EDIT
+ *
+ * This file was automatically generated by PostgreSDK.
+ * Any manual changes will be overwritten on the next generation.
+ *
+ * To make changes, modify your schema or configuration and regenerate.
+ */
 import { Hono } from "hono";
 import { z } from "zod";
 import { Insert${Type}Schema, Update${Type}Schema } from "../zod/${fileTableName}${ext}";
@@ -1850,7 +2052,7 @@ function emitClient(table, graph, opts, model) {
   let includeMethodsCode = "";
   for (const method of includeMethods) {
     const isGetByPk = method.name.startsWith("getByPk");
-    const baseParams = isGetByPk ? "" : `params?: Omit<{ limit?: number; offset?: number; where?: any; orderBy?: string; order?: "asc" | "desc"; }, "include">`;
+    const baseParams = isGetByPk ? "" : `params?: Omit<{ limit?: number; offset?: number; where?: Where<Select${Type}>; orderBy?: string; order?: "asc" | "desc"; }, "include">`;
     if (isGetByPk) {
       const pkWhere = hasCompositePk ? `{ ${safePk.map((col) => `${col}: pk.${col}`).join(", ")} }` : `{ ${safePk[0] || "id"}: pk }`;
       const baseReturnType = method.returnType.replace(" | null", "");
@@ -1872,8 +2074,16 @@ function emitClient(table, graph, opts, model) {
 `;
     }
   }
-  return `/* Generated. Do not edit. */
+  return `/**
+ * AUTO-GENERATED FILE - DO NOT EDIT
+ *
+ * This file was automatically generated by PostgreSDK.
+ * Any manual changes will be overwritten on the next generation.
+ *
+ * To make changes, modify your schema or configuration and regenerate.
+ */
 import { BaseClient } from "./base-client${ext}";
+import type { Where } from "./where-types${ext}";
 ${typeImports}
 ${otherTableImports.join(`
 `)}
@@ -1893,10 +2103,11 @@ export class ${Type}Client extends BaseClient {
     return this.get<Select${Type} | null>(\`\${this.resource}/\${path}\`);
   }
 
-  async list(params?: { 
-    limit?: number; 
+  async list(params?: {
+    include?: any;
+    limit?: number;
     offset?: number;
-    where?: any;
+    where?: Where<Select${Type}>;
     orderBy?: string;
     order?: "asc" | "desc";
   }): Promise<Select${Type}[]> {
@@ -1917,7 +2128,14 @@ ${includeMethodsCode}}
 }
 function emitClientIndex(tables, useJsExtensions) {
   const ext = useJsExtensions ? ".js" : "";
-  let out = `/* Generated. Do not edit. */
+  let out = `/**
+ * AUTO-GENERATED FILE - DO NOT EDIT
+ *
+ * This file was automatically generated by PostgreSDK.
+ * Any manual changes will be overwritten on the next generation.
+ *
+ * To make changes, modify your schema or configuration and regenerate.
+ */
 `;
   out += `import { BaseClient, type AuthConfig } from "./base-client${ext}";
 `;
@@ -1958,6 +2176,17 @@ export type { AuthConfig, HeaderMap, AuthHeadersProvider } from "./base-client${
   out += `export { BaseClient } from "./base-client${ext}";
 `;
   out += `
+// Include specification types for custom queries
+`;
+  out += `export type {
+`;
+  for (const t of tables) {
+    out += `  ${pascal(t.name)}IncludeSpec,
+`;
+  }
+  out += `} from "./include-spec${ext}";
+`;
+  out += `
 // Zod schemas for form validation
 `;
   for (const t of tables) {
@@ -1979,7 +2208,14 @@ export type { AuthConfig, HeaderMap, AuthHeadersProvider } from "./base-client${
 
 // src/emit-base-client.ts
 function emitBaseClient() {
-  return `/* Generated. Do not edit. */
+  return `/**
+ * AUTO-GENERATED FILE - DO NOT EDIT
+ *
+ * This file was automatically generated by PostgreSDK.
+ * Any manual changes will be overwritten on the next generation.
+ *
+ * To make changes, modify your schema or configuration and regenerate.
+ */
 
 export type HeaderMap = Record<string, string>;
 export type AuthHeadersProvider = () => Promise<HeaderMap> | HeaderMap;
@@ -2126,7 +2362,14 @@ function emitIncludeLoader(graph, model, maxDepth, useJsExtensions) {
     fkIndex[t.name] = t.fks.map((f) => ({ from: f.from, toTable: f.toTable, to: f.to }));
   }
   const ext = useJsExtensions ? ".js" : "";
-  return `/* Generated. Do not edit. */
+  return `/**
+ * AUTO-GENERATED FILE - DO NOT EDIT
+ *
+ * This file was automatically generated by PostgreSDK.
+ * Any manual changes will be overwritten on the next generation.
+ *
+ * To make changes, modify your schema or configuration and regenerate.
+ */
 import { RELATION_GRAPH } from "./include-builder${ext}";
 
 // Minimal types to keep the file self-contained
@@ -2447,7 +2690,14 @@ function emitTypes(table, opts) {
     return `  ${col.name}: ${valueType};`;
   }).join(`
 `);
-  return `/* Generated. Do not edit. */
+  return `/**
+ * AUTO-GENERATED FILE - DO NOT EDIT
+ *
+ * This file was automatically generated by PostgreSDK.
+ * Any manual changes will be overwritten on the next generation.
+ *
+ * To make changes, modify your schema or configuration and regenerate.
+ */
 export type Insert${Type} = {
 ${insertFields}
 };
@@ -2462,7 +2712,14 @@ ${selectFields}
 
 // src/emit-logger.ts
 function emitLogger() {
-  return `/* Generated. Do not edit. */
+  return `/**
+ * AUTO-GENERATED FILE - DO NOT EDIT
+ *
+ * This file was automatically generated by PostgreSDK.
+ * Any manual changes will be overwritten on the next generation.
+ *
+ * To make changes, modify your schema or configuration and regenerate.
+ */
 const DEBUG = process.env.SDK_DEBUG === "1" || process.env.SDK_DEBUG === "true";
 
 export const logger = {
@@ -2495,6 +2752,76 @@ export function safe<T extends (c: any) => any>(handler: T) {
 `;
 }
 
+// src/emit-where-types.ts
+function emitWhereTypes() {
+  return `/**
+ * AUTO-GENERATED FILE - DO NOT EDIT
+ *
+ * This file was automatically generated by PostgreSDK.
+ * Any manual changes will be overwritten on the next generation.
+ *
+ * To make changes, modify your schema or configuration and regenerate.
+ */
+
+/**
+ * WHERE clause operators for filtering
+ */
+export type WhereOperator<T> = {
+  /** Equal to */
+  $eq?: T;
+  /** Not equal to */
+  $ne?: T;
+  /** Greater than */
+  $gt?: T;
+  /** Greater than or equal to */
+  $gte?: T;
+  /** Less than */
+  $lt?: T;
+  /** Less than or equal to */
+  $lte?: T;
+  /** In array */
+  $in?: T[];
+  /** Not in array */
+  $nin?: T[];
+  /** LIKE pattern match (strings only) */
+  $like?: T extends string ? string : never;
+  /** Case-insensitive LIKE (strings only) */
+  $ilike?: T extends string ? string : never;
+  /** IS NULL */
+  $is?: null;
+  /** IS NOT NULL */
+  $isNot?: null;
+};
+
+/**
+ * WHERE condition - can be a direct value or an operator object
+ */
+export type WhereCondition<T> = T | WhereOperator<T>;
+
+/**
+ * Field-level WHERE conditions (without logical operators)
+ */
+export type WhereFieldConditions<T> = {
+  [K in keyof T]?: WhereCondition<T[K]>;
+};
+
+/**
+ * WHERE clause type with support for $or/$and logical operators (2 levels max)
+ *
+ * Examples:
+ * - Basic OR: { $or: [{ name: 'Alice' }, { name: 'Bob' }] }
+ * - Mixed AND + OR: { status: 'active', $or: [{ age: { $gt: 65 } }, { age: { $lt: 18 } }] }
+ * - Nested (2 levels): { $and: [{ $or: [{ name: 'Alice' }, { name: 'Bob' }] }, { status: 'active' }] }
+ */
+export type Where<T> = WhereFieldConditions<T> & {
+  /** OR - at least one condition must be true */
+  $or?: (WhereFieldConditions<T>)[];
+  /** AND - all conditions must be true (alternative to implicit root-level AND) */
+  $and?: (WhereFieldConditions<T> | { $or?: WhereFieldConditions<T>[] })[];
+};
+`;
+}
+
 // src/emit-auth.ts
 function emitAuth(cfgAuth) {
   const strategy = cfgAuth?.strategy ?? "none";
@@ -2509,7 +2836,14 @@ function emitAuth(cfgAuth) {
   const JWT_SHARED_SECRET = JSON.stringify(jwtShared);
   const JWT_ISSUER = jwtIssuer === undefined ? "undefined" : JSON.stringify(jwtIssuer);
   const JWT_AUDIENCE = jwtAudience === undefined ? "undefined" : JSON.stringify(jwtAudience);
-  return `/* Generated. Do not edit. */
+  return `/**
+ * AUTO-GENERATED FILE - DO NOT EDIT
+ *
+ * This file was automatically generated by PostgreSDK.
+ * Any manual changes will be overwritten on the next generation.
+ *
+ * To make changes, modify your schema or configuration and regenerate.
+ */
 import type { Context, Next } from "hono";
 
 // ---- Config inlined by generator ----
@@ -2666,7 +3000,14 @@ function emitHonoRouter(tables, hasAuth, useJsExtensions) {
     return `export { register${Type}Routes } from "./routes/${name}${ext}";`;
   }).join(`
 `);
-  return `/* Generated. Do not edit. */
+  return `/**
+ * AUTO-GENERATED FILE - DO NOT EDIT
+ *
+ * This file was automatically generated by PostgreSDK.
+ * Any manual changes will be overwritten on the next generation.
+ *
+ * To make changes, modify your schema or configuration and regenerate.
+ */
 import { Hono } from "hono";
 import { SDK_MANIFEST } from "./sdk-bundle${ext}";
 import { getContract } from "./contract${ext}";
@@ -2800,7 +3141,14 @@ function emitSdkBundle(clientFiles, clientDir) {
   }
   const version = `1.0.0`;
   const generated = new Date().toISOString();
-  return `/* Generated. Do not edit. */
+  return `/**
+ * AUTO-GENERATED FILE - DO NOT EDIT
+ *
+ * This file was automatically generated by PostgreSDK.
+ * Any manual changes will be overwritten on the next generation.
+ *
+ * To make changes, modify your schema or configuration and regenerate.
+ */
 
 export const SDK_MANIFEST = {
   version: "${version}",
@@ -2904,6 +3252,155 @@ export async function getByPk(
   }
 }
 
+/**
+ * Build WHERE clause recursively, supporting $or/$and operators
+ * Returns { sql: string, params: any[], nextParamIndex: number }
+ */
+function buildWhereClause(
+  whereClause: any,
+  startParamIndex: number
+): { sql: string; params: any[]; nextParamIndex: number } {
+  const whereParts: string[] = [];
+  const whereParams: any[] = [];
+  let paramIndex = startParamIndex;
+
+  if (!whereClause || typeof whereClause !== 'object') {
+    return { sql: '', params: [], nextParamIndex: paramIndex };
+  }
+
+  // Separate logical operators from field conditions
+  const { $or, $and, ...fieldConditions } = whereClause;
+
+  // Process field-level conditions
+  for (const [key, value] of Object.entries(fieldConditions)) {
+    if (value === undefined) {
+      continue;
+    }
+
+    // Handle operator objects like { $gt: 5, $like: "%test%" }
+    if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+      for (const [op, opValue] of Object.entries(value)) {
+        if (opValue === undefined) continue;
+
+        switch (op) {
+          case '$eq':
+            whereParts.push(\`"\${key}" = $\${paramIndex}\`);
+            whereParams.push(opValue);
+            paramIndex++;
+            break;
+          case '$ne':
+            whereParts.push(\`"\${key}" != $\${paramIndex}\`);
+            whereParams.push(opValue);
+            paramIndex++;
+            break;
+          case '$gt':
+            whereParts.push(\`"\${key}" > $\${paramIndex}\`);
+            whereParams.push(opValue);
+            paramIndex++;
+            break;
+          case '$gte':
+            whereParts.push(\`"\${key}" >= $\${paramIndex}\`);
+            whereParams.push(opValue);
+            paramIndex++;
+            break;
+          case '$lt':
+            whereParts.push(\`"\${key}" < $\${paramIndex}\`);
+            whereParams.push(opValue);
+            paramIndex++;
+            break;
+          case '$lte':
+            whereParts.push(\`"\${key}" <= $\${paramIndex}\`);
+            whereParams.push(opValue);
+            paramIndex++;
+            break;
+          case '$in':
+            if (Array.isArray(opValue) && opValue.length > 0) {
+              whereParts.push(\`"\${key}" = ANY($\${paramIndex})\`);
+              whereParams.push(opValue);
+              paramIndex++;
+            }
+            break;
+          case '$nin':
+            if (Array.isArray(opValue) && opValue.length > 0) {
+              whereParts.push(\`"\${key}" != ALL($\${paramIndex})\`);
+              whereParams.push(opValue);
+              paramIndex++;
+            }
+            break;
+          case '$like':
+            whereParts.push(\`"\${key}" LIKE $\${paramIndex}\`);
+            whereParams.push(opValue);
+            paramIndex++;
+            break;
+          case '$ilike':
+            whereParts.push(\`"\${key}" ILIKE $\${paramIndex}\`);
+            whereParams.push(opValue);
+            paramIndex++;
+            break;
+          case '$is':
+            if (opValue === null) {
+              whereParts.push(\`"\${key}" IS NULL\`);
+            }
+            break;
+          case '$isNot':
+            if (opValue === null) {
+              whereParts.push(\`"\${key}" IS NOT NULL\`);
+            }
+            break;
+        }
+      }
+    } else if (value === null) {
+      // Direct null value
+      whereParts.push(\`"\${key}" IS NULL\`);
+    } else {
+      // Direct value (simple equality)
+      whereParts.push(\`"\${key}" = $\${paramIndex}\`);
+      whereParams.push(value);
+      paramIndex++;
+    }
+  }
+
+  // Handle $or operator
+  if ($or && Array.isArray($or)) {
+    if ($or.length === 0) {
+      // Empty OR is logically FALSE - matches nothing
+      whereParts.push('FALSE');
+    } else {
+      const orParts: string[] = [];
+      for (const orCondition of $or) {
+        const result = buildWhereClause(orCondition, paramIndex);
+        if (result.sql) {
+          orParts.push(result.sql);
+          whereParams.push(...result.params);
+          paramIndex = result.nextParamIndex;
+        }
+      }
+      if (orParts.length > 0) {
+        whereParts.push(\`(\${orParts.join(' OR ')})\`);
+      }
+    }
+  }
+
+  // Handle $and operator
+  if ($and && Array.isArray($and) && $and.length > 0) {
+    const andParts: string[] = [];
+    for (const andCondition of $and) {
+      const result = buildWhereClause(andCondition, paramIndex);
+      if (result.sql) {
+        andParts.push(result.sql);
+        whereParams.push(...result.params);
+        paramIndex = result.nextParamIndex;
+      }
+    }
+    if (andParts.length > 0) {
+      whereParts.push(\`(\${andParts.join(' AND ')})\`);
+    }
+  }
+
+  const sql = whereParts.join(' AND ');
+  return { sql, params: whereParams, nextParamIndex: paramIndex };
+}
+
 /**
  * LIST operation - Get multiple records with optional filters
  */
@@ -2913,60 +3410,54 @@ export async function listRecords(
 ): Promise<{ data?: any; error?: string; issues?: any; needsIncludes?: boolean; includeSpec?: any; status: number }> {
   try {
     const { where: whereClause, limit = 50, offset = 0, include } = params;
-    
+
     // Build WHERE clause
-    const whereParts: string[] = [];
-    const whereParams: any[] = [];
     let paramIndex = 1;
-    
+    const whereParts: string[] = [];
+    let whereParams: any[] = [];
+
     // Add soft delete filter if applicable
     if (ctx.softDeleteColumn) {
       whereParts.push(\`"\${ctx.softDeleteColumn}" IS NULL\`);
     }
-    
+
     // Add user-provided where conditions
-    if (whereClause && typeof whereClause === 'object') {
-      for (const [key, value] of Object.entries(whereClause)) {
-        if (value === null) {
-          whereParts.push(\`"\${key}" IS NULL\`);
-        } else if (value === undefined) {
-          // Skip undefined values
-          continue;
-        } else {
-          whereParts.push(\`"\${key}" = $\${paramIndex}\`);
-          whereParams.push(value);
-          paramIndex++;
-        }
+    if (whereClause) {
+      const result = buildWhereClause(whereClause, paramIndex);
+      if (result.sql) {
+        whereParts.push(result.sql);
+        whereParams = result.params;
+        paramIndex = result.nextParamIndex;
       }
     }
-    
+
     const whereSQL = whereParts.length > 0 ? \`WHERE \${whereParts.join(" AND ")}\` : "";
-    
+
     // Add limit and offset params
     const limitParam = \`$\${paramIndex}\`;
     const offsetParam = \`$\${paramIndex + 1}\`;
     const allParams = [...whereParams, limit, offset];
-    
+
     const text = \`SELECT * FROM "\${ctx.table}" \${whereSQL} LIMIT \${limitParam} OFFSET \${offsetParam}\`;
     log.debug(\`LIST \${ctx.table} SQL:\`, text, "params:", allParams);
-    
+
     const { rows } = await ctx.pg.query(text, allParams);
-    
+
     if (!include) {
       log.debug(\`LIST \${ctx.table} rows:\`, rows.length);
       return { data: rows, status: 200 };
     }
-    
+
     // Include logic will be handled by the include-loader
     // For now, just return the rows with a note that includes need to be applied
     log.debug(\`LIST \${ctx.table} include spec:\`, include);
     return { data: rows, needsIncludes: true, includeSpec: include, status: 200 };
   } catch (e: any) {
     log.error(\`LIST \${ctx.table} error:\`, e?.stack ?? e);
-    return { 
-      error: e?.message ?? "Internal error", 
+    return {
+      error: e?.message ?? "Internal error",
       ...(DEBUG ? { stack: e?.stack } : {}),
-      status: 500 
+      status: 500
     };
   }
 }
@@ -3868,6 +4359,7 @@ async function generate(configPath) {
   files.push({ path: join(clientDir, "include-spec.ts"), content: includeSpec });
   files.push({ path: join(clientDir, "params", "shared.ts"), content: emitSharedParamsZod() });
   files.push({ path: join(clientDir, "base-client.ts"), content: emitBaseClient() });
+  files.push({ path: join(clientDir, "where-types.ts"), content: emitWhereTypes() });
   files.push({
     path: join(serverDir, "include-builder.ts"),
     content: emitIncludeBuilder(graph, cfg.includeMethodsDepth || 2)