postgresdk 0.9.8 → 0.10.0

package/README.md

@@ -160,6 +160,7 @@ const authors = await sdk.authors.list({
 ### Filtering & Pagination
 
 ```typescript
+// Simple equality filtering
 const users = await sdk.users.list({
   where: { status: "active" },
   orderBy: "created_at",
@@ -167,8 +168,20 @@ const users = await sdk.users.list({
   limit: 20,
   offset: 40
 });
+
+// Advanced WHERE operators
+const filtered = await sdk.users.list({
+  where: {
+    age: { $gte: 18, $lt: 65 },           // Range queries
+    email: { $ilike: '%@company.com' },   // Pattern matching
+    status: { $in: ['active', 'pending'] }, // Array matching
+    deleted_at: { $is: null }              // NULL checks
+  }
+});
 ```
 
+See the generated SDK documentation for all available operators: `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$like`, `$ilike`, `$is`, `$isNot`.
+
 ## Authentication
 
 postgresdk supports API key and JWT authentication:

package/dist/cli.js

@@ -1170,6 +1170,140 @@ 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("**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) {
@@ -1826,115 +1960,131 @@ async function initCommand(args) {
 }
 var CONFIG_TEMPLATE = `/**
  * PostgreSDK Configuration
- * 
- * This file configures how postgresdk generates your SDK.
+ *
+ * This file configures how postgresdk generates your type-safe API and SDK
+ * from your PostgreSQL database schema.
+ *
+ * QUICK START:
+ *   1. Update the connectionString below
+ *   2. Run: postgresdk generate
+ *   3. Start using your generated SDK!
+ *
+ * CLI COMMANDS:
+ *   postgresdk init              Initialize this config file
+ *   postgresdk generate          Generate API and SDK from your database
+ *   postgresdk pull              Pull SDK from a remote API
+ *   postgresdk help              Show help and examples
+ *
  * Environment variables are automatically loaded from .env files.
  */
 
 export default {
   // ========== DATABASE CONNECTION (Required) ==========
-  
+
   /**
    * PostgreSQL connection string
    * Format: postgres://user:password@host:port/database
+   *
+   * Tip: Use environment variables to keep credentials secure
    */
   connectionString: process.env.DATABASE_URL || "postgres://user:password@localhost:5432/mydb",
-  
+
   // ========== BASIC OPTIONS ==========
-  
+
   /**
    * Database schema to introspect
-   * @default "public"
+   * Default: "public"
    */
   // schema: "public",
-  
+
   /**
    * Output directory for server-side code (routes, validators, etc.)
-   * @default "./api/server"
+   * Default: "./api/server"
    */
   // outServer: "./api/server",
-  
+
   /**
    * Output directory for client SDK
-   * @default "./api/client"
+   * Default: "./api/client"
    */
   // outClient: "./api/client",
-  
+
   // ========== ADVANCED OPTIONS ==========
-  
+
   /**
    * Column name for soft deletes. When set, DELETE operations will update
    * this column instead of removing rows.
-   * @default null (hard deletes)
-   * @example "deleted_at"
+   *
+   * Default: null (hard deletes)
+   * Example: "deleted_at"
    */
   // softDeleteColumn: null,
-  
+
   /**
    * Maximum depth for nested relationship includes to prevent infinite loops
-   * @default 2
+   * Default: 2
    */
   // includeMethodsDepth: 2,
-  
-  
+
+
   /**
    * Server framework for generated API routes
-   * - "hono": Lightweight, edge-compatible web framework (default)
-   * - "express": Traditional Node.js framework (planned)
-   * - "fastify": High-performance Node.js framework (planned)
-   * @default "hono"
+   * Options:
+   *   - "hono": Lightweight, edge-compatible web framework (default)
+   *   - "express": Traditional Node.js framework (planned)
+   *   - "fastify": High-performance Node.js framework (planned)
+   *
+   * Default: "hono"
    */
   // serverFramework: "hono",
-  
+
   /**
    * Use .js extensions in server imports (for Vercel Edge, Deno, etc.)
-   * @default false
+   * Default: false
    */
   // useJsExtensions: false,
-  
+
   /**
    * Use .js extensions in client SDK imports (rarely needed)
-   * @default false
+   * Default: false
    */
   // useJsExtensionsClient: false,
-  
+
   // ========== TEST GENERATION ==========
-  
+
   /**
-   * Generate basic SDK tests
-   * Uncomment to enable test generation with Docker setup
+   * Generate basic SDK tests with Docker setup
+   * Uncomment to enable test generation
    */
   // tests: {
   //   generate: true,
   //   output: "./api/tests",
   //   framework: "vitest"  // or "jest" or "bun"
   // },
-  
+
   // ========== AUTHENTICATION ==========
-  
+
   /**
    * Authentication configuration for your API
-   * 
-   * Simple syntax examples:
+   *
+   * SIMPLE SYNTAX (recommended):
    *   auth: { apiKey: process.env.API_KEY }
    *   auth: { jwt: process.env.JWT_SECRET }
-   * 
-   * Multiple API keys:
    *   auth: { apiKeys: [process.env.KEY1, process.env.KEY2] }
-   * 
-   * Full syntax for advanced options:
+   *
+   * FULL SYNTAX (advanced):
    */
   // auth: {
   //   // Strategy: "none" | "api-key" | "jwt-hs256"
   //   strategy: "none",
-  //   
+  //
   //   // For API Key authentication
   //   apiKeyHeader: "x-api-key",  // Header name for API key
   //   apiKeys: [                  // List of valid API keys
   //     process.env.API_KEY_1,
   //     process.env.API_KEY_2,
   //   ],
-  //   
+  //
   //   // For JWT (HS256) authentication
   //   jwt: {
   //     sharedSecret: process.env.JWT_SECRET,  // Secret for signing/verifying
@@ -1942,12 +2092,12 @@ export default {
   //     audience: "my-users",                  // Optional: validate 'aud' claim
   //   }
   // },
-  
+
   // ========== SDK DISTRIBUTION (Pull Configuration) ==========
-  
+
   /**
    * Configuration for pulling SDK from a remote API
-   * Used when running 'postgresdk pull' command
+   * Used when running: postgresdk pull
    */
   // pull: {
   //   from: "https://api.myapp.com",     // API URL to pull SDK from
@@ -2423,6 +2573,7 @@ import * as coreOps from "../core/operations${ext}";
 ${authImport}
 
 const listSchema = z.object({
+  where: z.any().optional(),
   include: z.any().optional(),
   limit: z.number().int().positive().max(100).optional(),
   offset: z.number().int().min(0).optional(),
@@ -2593,7 +2744,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", "");
@@ -2617,6 +2768,7 @@ function emitClient(table, graph, opts, model) {
   }
   return `/* Generated. Do not edit. */
 import { BaseClient } from "./base-client${ext}";
+import type { Where } from "./where-types${ext}";
 ${typeImports}
 ${otherTableImports.join(`
 `)}
@@ -2636,10 +2788,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}[]> {
@@ -2701,6 +2854,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) {
@@ -3238,6 +3402,54 @@ export function safe<T extends (c: any) => any>(handler: T) {
 `;
 }
 
+// src/emit-where-types.ts
+function emitWhereTypes() {
+  return `/* Generated. Do not edit. */
+
+/**
+ * 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>;
+
+/**
+ * WHERE clause type for a given table type
+ */
+export type Where<T> = {
+  [K in keyof T]?: WhereCondition<T[K]>;
+};
+`;
+}
+
 // src/emit-auth.ts
 function emitAuth(cfgAuth) {
   const strategy = cfgAuth?.strategy ?? "none";
@@ -3652,19 +3864,124 @@ export async function getByPk(
  */
 export async function listRecords(
   ctx: OperationContext,
-  params: { limit?: number; offset?: number; include?: any }
-): Promise<{ data?: any; error?: string; issues?: any; status: number; needsIncludes?: boolean; includeSpec?: any }> {
+  params: { where?: any; limit?: number; offset?: number; include?: any }
+): Promise<{ data?: any; error?: string; issues?: any; needsIncludes?: boolean; includeSpec?: any; status: number }> {
   try {
-    const { limit = 50, offset = 0, include } = params;
+    const { where: whereClause, limit = 50, offset = 0, include } = params;
+    
+    // Build WHERE clause
+    const whereParts: string[] = [];
+    const whereParams: any[] = [];
+    let paramIndex = 1;
+    
+    // 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 === undefined) {
+          // Skip undefined values
+          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++;
+        }
+      }
+    }
+    
+    const whereSQL = whereParts.length > 0 ? \`WHERE \${whereParts.join(" AND ")}\` : "";
     
-    const where = ctx.softDeleteColumn 
-      ? \`WHERE "\${ctx.softDeleteColumn}" IS NULL\` 
-      : "";
+    // Add limit and offset params
+    const limitParam = \`$\${paramIndex}\`;
+    const offsetParam = \`$\${paramIndex + 1}\`;
+    const allParams = [...whereParams, limit, offset];
     
-    const text = \`SELECT * FROM "\${ctx.table}" \${where} LIMIT $1 OFFSET $2\`;
-    log.debug(\`LIST \${ctx.table} SQL:\`, text, "params:", [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, [limit, offset]);
+    const { rows } = await ctx.pg.query(text, allParams);
     
     if (!include) {
       log.debug(\`LIST \${ctx.table} rows:\`, rows.length);
@@ -4582,6 +4899,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)

package/dist/core/operations.d.ts

@@ -35,6 +35,7 @@ export declare function getByPk(ctx: OperationContext, pkValues: any[]): Promise
  * LIST operation - Get multiple records with optional filters
  */
 export declare function listRecords(ctx: OperationContext, params: {
+    where?: any;
     limit?: number;
     offset?: number;
     include?: any;

package/dist/emit-where-types.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Emits WHERE clause type utilities for type-safe filtering
+ */
+export declare function emitWhereTypes(): string;

package/dist/index.js

@@ -1169,6 +1169,140 @@ 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("**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) {
@@ -1679,6 +1813,7 @@ import * as coreOps from "../core/operations${ext}";
 ${authImport}
 
 const listSchema = z.object({
+  where: z.any().optional(),
   include: z.any().optional(),
   limit: z.number().int().positive().max(100).optional(),
   offset: z.number().int().min(0).optional(),
@@ -1849,7 +1984,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", "");
@@ -1873,6 +2008,7 @@ function emitClient(table, graph, opts, model) {
   }
   return `/* Generated. Do not edit. */
 import { BaseClient } from "./base-client${ext}";
+import type { Where } from "./where-types${ext}";
 ${typeImports}
 ${otherTableImports.join(`
 `)}
@@ -1892,10 +2028,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}[]> {
@@ -1957,6 +2094,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) {
@@ -2494,6 +2642,54 @@ export function safe<T extends (c: any) => any>(handler: T) {
 `;
 }
 
+// src/emit-where-types.ts
+function emitWhereTypes() {
+  return `/* Generated. Do not edit. */
+
+/**
+ * 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>;
+
+/**
+ * WHERE clause type for a given table type
+ */
+export type Where<T> = {
+  [K in keyof T]?: WhereCondition<T[K]>;
+};
+`;
+}
+
 // src/emit-auth.ts
 function emitAuth(cfgAuth) {
   const strategy = cfgAuth?.strategy ?? "none";
@@ -2908,19 +3104,124 @@ export async function getByPk(
  */
 export async function listRecords(
   ctx: OperationContext,
-  params: { limit?: number; offset?: number; include?: any }
-): Promise<{ data?: any; error?: string; issues?: any; status: number; needsIncludes?: boolean; includeSpec?: any }> {
+  params: { where?: any; limit?: number; offset?: number; include?: any }
+): Promise<{ data?: any; error?: string; issues?: any; needsIncludes?: boolean; includeSpec?: any; status: number }> {
   try {
-    const { limit = 50, offset = 0, include } = params;
+    const { where: whereClause, limit = 50, offset = 0, include } = params;
+    
+    // Build WHERE clause
+    const whereParts: string[] = [];
+    const whereParams: any[] = [];
+    let paramIndex = 1;
+    
+    // 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 === undefined) {
+          // Skip undefined values
+          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++;
+        }
+      }
+    }
+    
+    const whereSQL = whereParts.length > 0 ? \`WHERE \${whereParts.join(" AND ")}\` : "";
     
-    const where = ctx.softDeleteColumn 
-      ? \`WHERE "\${ctx.softDeleteColumn}" IS NULL\` 
-      : "";
+    // Add limit and offset params
+    const limitParam = \`$\${paramIndex}\`;
+    const offsetParam = \`$\${paramIndex + 1}\`;
+    const allParams = [...whereParams, limit, offset];
     
-    const text = \`SELECT * FROM "\${ctx.table}" \${where} LIMIT $1 OFFSET $2\`;
-    log.debug(\`LIST \${ctx.table} SQL:\`, text, "params:", [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, [limit, offset]);
+    const { rows } = await ctx.pg.query(text, allParams);
     
     if (!include) {
       log.debug(\`LIST \${ctx.table} rows:\`, rows.length);
@@ -3838,6 +4139,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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "postgresdk",
-  "version": "0.9.8",
+  "version": "0.10.0",
   "description": "Generate a typed server/client SDK from a Postgres schema (includes, Zod, Hono).",
   "type": "module",
   "bin": {
@@ -22,7 +22,7 @@
   },
   "scripts": {
     "build": "bun build src/cli.ts src/index.ts --outdir dist --target node --format esm --external=pg --external=zod --external=hono --external=prompts --external=node:* && tsc -p tsconfig.build.json --emitDeclarationOnly",
-    "test": "bun test:init && bun test:gen && bun test:gen-with-tests && bun test:pull && bun test:typecheck && bun test:drizzle-e2e",
+    "test": "bun test:init && bun test:gen && bun test test/test-where-clause.test.ts && bun test:gen-with-tests && bun test:pull && bun test:typecheck && bun test:drizzle-e2e",
     "test:init": "bun test/test-init.ts",
     "test:gen": "bun test/test-gen.ts",
     "test:gen-with-tests": "bun test/test-gen-with-tests.ts",