postgresdk 0.18.23 → 0.18.25

package/dist/cli.js

@@ -750,7 +750,7 @@ __export(exports_emit_sdk_contract, {
 function generateUnifiedContract(model, config, graph) {
   const resources = [];
   const relationships = [];
-  const tables = model && model.tables ? Object.values(model.tables) : [];
+  const tables = Object.values(model.tables);
   if (process.env.SDK_DEBUG) {
     console.log(`[SDK Contract] Processing ${tables.length} tables`);
   }
@@ -880,30 +880,23 @@ function generateResourceWithSDK(table, model, graph, config) {
   const hasSinglePK = table.pk.length === 1;
   const pkField = hasSinglePK ? table.pk[0] : "id";
   const enums = model.enums || {};
+  const overrides = config?.softDeleteColumnOverrides;
+  const resolvedSoftDeleteCol = overrides && tableName in overrides ? overrides[tableName] ?? null : config?.softDeleteColumn ?? null;
+  const softDeleteCol = resolvedSoftDeleteCol && table.columns.some((c) => c.name === resolvedSoftDeleteCol) ? resolvedSoftDeleteCol : null;
   const sdkMethods = [];
   const endpoints = [];
   sdkMethods.push({
     name: "list",
     signature: `list(params?: ListParams): Promise<PaginatedResponse<${Type}>>`,
     description: `List ${tableName} with filtering, sorting, and pagination. Returns paginated results with metadata.`,
-    example: `// Get all ${tableName}
-const result = await sdk.${tableName}.list();
-console.log(result.data);        // array of records
-console.log(result.total);       // total matching records
-console.log(result.hasMore);     // true if more pages available
-
-// With filters and pagination
-const filtered = await sdk.${tableName}.list({
-  limit: 20,
-  offset: 0,
-  where: { ${table.columns[0]?.name || "field"}: { $like: '%search%' } },
+    example: `const result = await sdk.${tableName}.list({
+  where: { ${table.columns[0]?.name || "id"}: { $ilike: '%value%' } },
   orderBy: '${table.columns[0]?.name || "created_at"}',
-  order: 'desc'
-});
-
-// Calculate total pages
-const totalPages = Math.ceil(filtered.total / filtered.limit);
-const currentPage = Math.floor(filtered.offset / filtered.limit) + 1;`,
+  order: 'desc',
+  limit: 20,
+  offset: 0${softDeleteCol ? `,
+  includeSoftDeleted: false` : ""}
+}); // result.data, result.total, result.hasMore`,
     correspondsTo: `GET ${basePath}`
   });
   endpoints.push({
@@ -918,13 +911,8 @@ const currentPage = Math.floor(filtered.offset / filtered.limit) + 1;`,
       name: "getByPk",
       signature: `getByPk(${pkField}: string): Promise<${Type} | null>`,
       description: `Get a single ${tableName} by primary key`,
-      example: `// Get by ID
-const item = await sdk.${tableName}.getByPk('123e4567-e89b-12d3-a456-426614174000');
-
-// Check if exists
-if (item === null) {
-  console.log('Not found');
-}`,
+      example: `const item = await sdk.${tableName}.getByPk('id');${softDeleteCol ? `
+const withDeleted = await sdk.${tableName}.getByPk('id', { includeSoftDeleted: true });` : ""} // null if not found`,
       correspondsTo: `GET ${basePath}/:${pkField}`
     });
     endpoints.push({
@@ -938,14 +926,9 @@ if (item === null) {
     name: "create",
     signature: `create(data: Insert${Type}): Promise<${Type}>`,
     description: `Create a new ${tableName}`,
-    example: `import type { Insert${Type} } from './client/types/${tableName}';
-
-const newItem: Insert${Type} = {
+    example: `const created = await sdk.${tableName}.create({
   ${generateExampleFields(table, "create")}
-};
-
-const created = await sdk.${tableName}.create(newItem);
-console.log('Created:', created.${pkField});`,
+});`,
     correspondsTo: `POST ${basePath}`
   });
   endpoints.push({
@@ -960,13 +943,9 @@ console.log('Created:', created.${pkField});`,
       name: "update",
       signature: `update(${pkField}: string, data: Update${Type}): Promise<${Type}>`,
       description: `Update an existing ${tableName}`,
-      example: `import type { Update${Type} } from './client/types/${tableName}';
-
-const updates: Update${Type} = {
+      example: `const updated = await sdk.${tableName}.update('id', {
   ${generateExampleFields(table, "update")}
-};
-
-const updated = await sdk.${tableName}.update('123', updates);`,
+});`,
       correspondsTo: `PATCH ${basePath}/:${pkField}`
     });
     endpoints.push({
@@ -982,8 +961,7 @@ const updated = await sdk.${tableName}.update('123', updates);`,
       name: "delete",
       signature: `delete(${pkField}: string): Promise<${Type}>`,
       description: `Delete a ${tableName}`,
-      example: `const deleted = await sdk.${tableName}.delete('123');
-console.log('Deleted:', deleted);`,
+      example: `const deleted = await sdk.${tableName}.delete('id');`,
       correspondsTo: `DELETE ${basePath}/:${pkField}`
     });
     endpoints.push({
@@ -994,29 +972,17 @@ console.log('Deleted:', deleted);`,
     });
   }
   if (graph && config) {
-    const allTables = model && model.tables ? Object.values(model.tables) : undefined;
+    const allTables = Object.values(model.tables);
     const includeMethods = generateIncludeMethods(table, graph, {
       maxDepth: config.includeMethodsDepth ?? 2,
       skipJunctionTables: config.skipJunctionTables ?? true
     }, allTables);
     for (const method of includeMethods) {
       const isGetByPk = method.name.startsWith("getByPk");
-      const exampleCall = isGetByPk ? `const result = await sdk.${tableName}.${method.name}('123e4567-e89b-12d3-a456-426614174000');` : `const result = await sdk.${tableName}.${method.name}();
-console.log(result.data);    // array of records with includes
-console.log(result.total);   // total count
-console.log(result.hasMore); // more pages available
-
-// With filters and pagination
-const filtered = await sdk.${tableName}.${method.name}({
-  limit: 20,
-  offset: 0,
-  where: { /* filter conditions */ }
-});`;
       sdkMethods.push({
         name: method.name,
         signature: `${method.name}(${isGetByPk ? `${pkField}: string` : "params?: ListParams"}): ${method.returnType}`,
         description: `Get ${tableName} with included ${method.path.join(", ")} data`,
-        example: exampleCall,
         correspondsTo: `POST ${basePath}/list`
       });
     }
@@ -1053,79 +1019,68 @@ function generateFieldContract(column, table, enums) {
   }
   return field;
 }
+function pgTypeCategory(t) {
+  switch (t) {
+    case "int":
+    case "int2":
+    case "int4":
+    case "int8":
+    case "integer":
+    case "smallint":
+    case "bigint":
+    case "decimal":
+    case "numeric":
+    case "real":
+    case "float4":
+    case "float8":
+    case "double precision":
+    case "float":
+      return "number";
+    case "boolean":
+    case "bool":
+      return "boolean";
+    case "date":
+    case "timestamp":
+    case "timestamptz":
+      return "date";
+    case "json":
+    case "jsonb":
+      return "json";
+    case "uuid":
+      return "uuid";
+    case "text[]":
+    case "varchar[]":
+    case "_text":
+    case "_varchar":
+      return "string[]";
+    case "int[]":
+    case "integer[]":
+    case "_int":
+    case "_int2":
+    case "_int4":
+    case "_int8":
+    case "_integer":
+      return "number[]";
+    case "vector":
+      return "number[]";
+    default:
+      return "string";
+  }
+}
 function postgresTypeToTsType(column, enums) {
   const pgType = column.pgType.toLowerCase();
   if (enums[pgType]) {
     const enumType = enums[pgType].map((v) => `"${v}"`).join(" | ");
-    if (column.nullable) {
-      return `${enumType} | null`;
-    }
-    return enumType;
-  }
-  if (pgType.startsWith("_")) {
-    const enumName = pgType.slice(1);
-    const enumValues = enums[enumName];
-    if (enumValues) {
-      const enumType = enumValues.map((v) => `"${v}"`).join(" | ");
-      const arrayType = `(${enumType})[]`;
-      if (column.nullable) {
-        return `${arrayType} | null`;
-      }
-      return arrayType;
-    }
-  }
-  const baseType = (() => {
-    switch (pgType) {
-      case "int":
-      case "int2":
-      case "int4":
-      case "int8":
-      case "integer":
-      case "smallint":
-      case "bigint":
-      case "decimal":
-      case "numeric":
-      case "real":
-      case "float4":
-      case "float8":
-      case "double precision":
-      case "float":
-        return "number";
-      case "boolean":
-      case "bool":
-        return "boolean";
-      case "date":
-      case "timestamp":
-      case "timestamptz":
-        return "string";
-      case "json":
-      case "jsonb":
-        return "JsonValue";
-      case "uuid":
-        return "string";
-      case "text[]":
-      case "varchar[]":
-      case "_text":
-      case "_varchar":
-        return "string[]";
-      case "int[]":
-      case "integer[]":
-      case "_int":
-      case "_int2":
-      case "_int4":
-      case "_int8":
-      case "_integer":
-        return "number[]";
-      case "vector":
-        return "number[]";
-      default:
-        return "string";
-    }
-  })();
-  if (column.nullable) {
-    return `${baseType} | null`;
+    return column.nullable ? `${enumType} | null` : enumType;
+  }
+  const enumArrayValues = enums[pgType.slice(1)];
+  if (pgType.startsWith("_") && enumArrayValues) {
+    const arrayType = `(${enumArrayValues.map((v) => `"${v}"`).join(" | ")})[]`;
+    return column.nullable ? `${arrayType} | null` : arrayType;
   }
-  return baseType;
+  const cat = pgTypeCategory(pgType);
+  const baseType = cat === "date" || cat === "uuid" ? "string" : cat === "json" ? "JsonValue" : cat;
+  return column.nullable ? `${baseType} | null` : baseType;
 }
 function generateExampleFields(table, operation) {
   const fields = [];
@@ -1224,76 +1179,25 @@ function generateQueryParams(table, enums) {
 }
 function postgresTypeToJsonType(pgType, enums) {
   const t = pgType.toLowerCase();
-  if (enums[t]) {
+  if (enums[t])
     return t;
-  }
-  if (t.startsWith("_") && enums[t.slice(1)]) {
+  if (t.startsWith("_") && enums[t.slice(1)])
     return `${t.slice(1)}[]`;
-  }
-  switch (t) {
-    case "int":
-    case "int2":
-    case "int4":
-    case "int8":
-    case "integer":
-    case "smallint":
-    case "bigint":
-    case "decimal":
-    case "numeric":
-    case "real":
-    case "float4":
-    case "float8":
-    case "double precision":
-    case "float":
-      return "number";
-    case "boolean":
-    case "bool":
-      return "boolean";
-    case "date":
-    case "timestamp":
-    case "timestamptz":
-      return "date/datetime";
-    case "json":
-    case "jsonb":
-      return "object";
-    case "uuid":
-      return "uuid";
-    case "text[]":
-    case "varchar[]":
-    case "_text":
-    case "_varchar":
-      return "string[]";
-    case "int[]":
-    case "integer[]":
-    case "_int":
-    case "_int2":
-    case "_int4":
-    case "_int8":
-    case "_integer":
-      return "number[]";
-    case "vector":
-      return "number[]";
-    default:
-      return "string";
-  }
+  const cat = pgTypeCategory(t);
+  return cat === "date" ? "date/datetime" : cat === "json" ? "object" : cat;
 }
 function generateFieldDescription(column, table) {
-  const descriptions = [];
-  if (column.name === "id") {
-    descriptions.push("Primary key");
-  } else if (column.name === "created_at") {
-    descriptions.push("Creation timestamp");
-  } else if (column.name === "updated_at") {
-    descriptions.push("Last update timestamp");
-  } else if (column.name === "deleted_at") {
-    descriptions.push("Soft delete timestamp");
-  } else if (column.name.endsWith("_id")) {
-    const relatedTable = column.name.slice(0, -3);
-    descriptions.push(`Foreign key to ${relatedTable}`);
-  } else {
-    descriptions.push(column.name.replace(/_/g, " "));
-  }
-  return descriptions.join(", ");
+  if (column.name === "id")
+    return "Primary key";
+  if (column.name === "created_at")
+    return "Creation timestamp";
+  if (column.name === "updated_at")
+    return "Last update timestamp";
+  if (column.name === "deleted_at")
+    return "Soft delete timestamp";
+  if (column.name.endsWith("_id"))
+    return `Foreign key to ${column.name.slice(0, -3)}`;
+  return column.name.replace(/_/g, " ");
 }
 function generateUnifiedContractMarkdown(contract) {
   const lines = [];
@@ -1334,288 +1238,53 @@ 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("| `$jsonbContains` | JSONB contains | `{ metadata: { $jsonbContains: { tags: ['premium'] } } }` | JSONB/JSON |");
-  lines.push("| `$jsonbContainedBy` | JSONB contained by | `{ metadata: { $jsonbContainedBy: {...} } }` | JSONB/JSON |");
-  lines.push("| `$jsonbHasKey` | JSONB has key | `{ settings: { $jsonbHasKey: 'theme' } }` | JSONB/JSON |");
-  lines.push("| `$jsonbHasAnyKeys` | JSONB has any keys | `{ settings: { $jsonbHasAnyKeys: ['dark', 'light'] } }` | JSONB/JSON |");
-  lines.push("| `$jsonbHasAllKeys` | JSONB has all keys | `{ config: { $jsonbHasAllKeys: ['api', 'db'] } }` | JSONB/JSON |");
-  lines.push("| `$jsonbPath` | JSONB nested value | `{ meta: { $jsonbPath: { path: ['user', 'age'], operator: '$gte', value: 18 } } }` | JSONB/JSON |");
-  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("## Sorting");
-  lines.push("");
-  lines.push("Sort query results using the `orderBy` and `order` parameters. Supports both single and multi-column sorting.");
-  lines.push("");
-  lines.push("### Single Column Sorting");
-  lines.push("");
-  lines.push("```typescript");
-  lines.push("// Sort by one column ascending");
-  lines.push("const users = await sdk.users.list({");
-  lines.push("  orderBy: 'created_at',");
-  lines.push("  order: 'asc'");
-  lines.push("});");
-  lines.push("");
-  lines.push("// Sort descending");
-  lines.push("const latest = await sdk.users.list({");
-  lines.push("  orderBy: 'created_at',");
-  lines.push("  order: 'desc'");
-  lines.push("});");
-  lines.push("");
-  lines.push("// Order defaults to 'asc' if not specified");
-  lines.push("const sorted = await sdk.users.list({");
-  lines.push("  orderBy: 'name'");
-  lines.push("});");
-  lines.push("```");
-  lines.push("");
-  lines.push("### Multi-Column Sorting");
-  lines.push("");
-  lines.push("```typescript");
-  lines.push("// Sort by multiple columns (all same direction)");
-  lines.push("const users = await sdk.users.list({");
-  lines.push("  orderBy: ['status', 'created_at'],");
-  lines.push("  order: 'desc'");
-  lines.push("});");
-  lines.push("");
-  lines.push("// Different direction per column");
-  lines.push("const sorted = await sdk.users.list({");
-  lines.push("  orderBy: ['status', 'created_at'],");
-  lines.push("  order: ['asc', 'desc']  // status ASC, created_at DESC");
-  lines.push("});");
-  lines.push("```");
-  lines.push("");
-  lines.push("### Combining Sorting with Filters");
-  lines.push("");
-  lines.push("```typescript");
-  lines.push("const results = await sdk.users.list({");
-  lines.push("  where: {");
-  lines.push("    status: 'active',");
-  lines.push("    age: { $gte: 18 }");
-  lines.push("  },");
-  lines.push("  orderBy: 'created_at',");
-  lines.push("  order: 'desc',");
-  lines.push("  limit: 50,");
-  lines.push("  offset: 0");
-  lines.push("});");
-  lines.push("```");
-  lines.push("");
-  lines.push("**Note:** Column names are validated by Zod schemas. Only valid table columns are accepted, preventing SQL injection.");
-  lines.push("");
-  lines.push("## Vector Search");
-  lines.push("");
-  lines.push("For tables with `vector` columns (requires pgvector extension), use the `vector` parameter for similarity search:");
-  lines.push("");
-  lines.push("```typescript");
-  lines.push("// Basic similarity search");
-  lines.push("const results = await sdk.embeddings.list({");
-  lines.push("  vector: {");
-  lines.push("    field: 'embedding',");
-  lines.push("    query: [0.1, 0.2, 0.3, ...],  // Your embedding vector");
-  lines.push("    metric: 'cosine'  // 'cosine' (default), 'l2', or 'inner'");
-  lines.push("  },");
-  lines.push("  limit: 10");
-  lines.push("});");
-  lines.push("");
-  lines.push("// Results include _distance field");
-  lines.push("results.data[0]._distance;  // Similarity distance");
-  lines.push("");
-  lines.push("// Distance threshold filtering");
-  lines.push("const closeMatches = await sdk.embeddings.list({");
-  lines.push("  vector: {");
-  lines.push("    field: 'embedding',");
-  lines.push("    query: queryVector,");
-  lines.push("    maxDistance: 0.5  // Only return results within this distance");
-  lines.push("  }");
-  lines.push("});");
-  lines.push("");
-  lines.push("// Hybrid search: vector + WHERE filters");
-  lines.push("const filtered = await sdk.embeddings.list({");
-  lines.push("  vector: { field: 'embedding', query: queryVector },");
-  lines.push("  where: {");
-  lines.push("    status: 'published',");
-  lines.push("    embedding: { $isNot: null }");
-  lines.push("  }");
-  lines.push("});");
-  lines.push("```");
-  lines.push("");
+  lines.push(`## Filtering
+
+Type-safe WHERE clauses. Root-level keys are AND'd; use \`$or\`/\`$and\` for logic (2 levels max).
+
+\`\`\`typescript
+await sdk.users.list({
+  where: {
+    status:     { $in: ['active', 'pending'] },
+    age:        { $gte: 18, $lt: 65 },
+    email:      { $ilike: '%@company.com' },
+    deleted_at: { $is: null },
+    meta:       { $jsonbContains: { tag: 'vip' } },
+    $or: [{ role: 'admin' }, { role: 'mod' }]
+  }
+});
+\`\`\`
+
+| Operator | SQL | Types |
+|----------|-----|-------|
+| \`$eq\` \`$ne\` | = ≠ | All |
+| \`$gt\` \`$gte\` \`$lt\` \`$lte\` | > ≥ < ≤ | Number, Date |
+| \`$in\` \`$nin\` | IN / NOT IN | All |
+| \`$like\` \`$ilike\` | LIKE / ILIKE | String |
+| \`$is\` \`$isNot\` | IS NULL / IS NOT NULL | Nullable |
+| \`$jsonbContains\` \`$jsonbContainedBy\` \`$jsonbHasKey\` \`$jsonbHasAnyKeys\` \`$jsonbHasAllKeys\` \`$jsonbPath\` | JSONB ops | JSONB |
+| \`$or\` \`$and\` | OR / AND (2 levels) | — |
+
+## Sorting
+
+\`orderBy\` accepts a column name or array; \`order\` accepts \`'asc'\`/\`'desc'\` or a per-column array.
+
+\`\`\`typescript
+await sdk.users.list({ orderBy: ['status', 'created_at'], order: ['asc', 'desc'] });
+\`\`\`
+
+## Vector Search
+
+For tables with \`vector\` columns (requires pgvector). Results include a \`_distance\` field.
+
+\`\`\`typescript
+const results = await sdk.embeddings.list({
+  vector: { field: 'embedding', query: [0.1, 0.2, 0.3, /* ... */], metric: 'cosine', maxDistance: 0.5 },
+  where: { status: 'published' },
+  limit: 10
+}); // results.data[0]._distance
+\`\`\`
+`);
   lines.push("## Resources");
   lines.push("");
   for (const resource of contract.resources) {
@@ -1635,10 +1304,12 @@ function generateUnifiedContractMarkdown(contract) {
         lines.push(`- API: \`${method.correspondsTo}\``);
       }
       lines.push("");
-      lines.push("```typescript");
-      lines.push(method.example);
-      lines.push("```");
-      lines.push("");
+      if (method.example) {
+        lines.push("```typescript");
+        lines.push(method.example);
+        lines.push("```");
+        lines.push("");
+      }
     }
     lines.push("#### API Endpoints");
     lines.push("");
@@ -1672,23 +1343,14 @@ function generateUnifiedContractMarkdown(contract) {
     }
     lines.push("");
   }
-  lines.push("## Type Imports");
-  lines.push("");
-  lines.push("```typescript");
-  lines.push("// Import SDK and types");
-  lines.push("import { SDK } from './client';");
-  lines.push("");
-  lines.push("// Import types for a specific table");
-  lines.push("import type {");
-  lines.push("  SelectTableName,  // Full record type");
-  lines.push("  InsertTableName,  // Create payload type");
-  lines.push("  UpdateTableName   // Update payload type");
-  lines.push("} from './client/types/table_name';");
-  lines.push("");
-  lines.push("// Import all types");
-  lines.push("import type * as Types from './client/types';");
-  lines.push("```");
-  lines.push("");
+  lines.push(`## Type Imports
+
+\`\`\`typescript
+import { SDK } from './client';
+import type { SelectTableName, InsertTableName, UpdateTableName } from './client/types/table_name';
+import type * as Types from './client/types';
+\`\`\`
+`);
   return lines.join(`
 `);
 }
@@ -4578,7 +4240,8 @@ export abstract class BaseClient {
 }
 
 // src/emit-include-loader.ts
-function emitIncludeLoader(graph, model, maxDepth, useJsExtensions) {
+function emitIncludeLoader(model, maxDepth, opts = {}) {
+  const { softDeleteCols = {}, useJsExtensions } = opts;
   const fkIndex = {};
   for (const t of Object.values(model.tables)) {
     fkIndex[t.name] = t.fks.map((f) => ({ from: f.from, toTable: f.toTable, to: f.to }));
@@ -4617,8 +4280,18 @@ const log = {
 };
 
 // Helpers for PK/FK discovery from model (inlined)
-const FK_INDEX = ${JSON.stringify(fkIndex, null, 2)} as const;
-const PKS = ${JSON.stringify(Object.fromEntries(Object.values(model.tables).map((t) => [t.name, t.pk])), null, 2)} as const;
+const FK_INDEX: Record<string, Array<{from: string[]; toTable: string; to: string[]}>> = ${JSON.stringify(fkIndex, null, 2)};
+const PKS: Record<string, string[]> = ${JSON.stringify(Object.fromEntries(Object.values(model.tables).map((t) => [t.name, t.pk])), null, 2)};
+/** Soft-delete column per table, null if not applicable. Baked in at generation time. */
+const SOFT_DELETE_COLS: Record<string, string | null> = ${JSON.stringify(softDeleteCols, null, 2)};
+
+/** Returns a SQL fragment like ' AND "col" IS NULL' for the given table, or "" if none. */
+function softDeleteFilter(table: string, alias?: string): string {
+  const col = SOFT_DELETE_COLS[table];
+  if (!col) return "";
+  const ref = alias ? \`\${alias}."\${col}"\` : \`"\${col}"\`;
+  return \` AND \${ref} IS NULL\`;
+}
 
 // Build WHERE predicate for OR-of-AND on composite values
 function buildOrAndPredicate(cols: string[], count: number, startIndex: number) {
@@ -4708,6 +4381,49 @@ function filterFields<T extends Record<string, any>>(
   });
 }
 
+/** Sentinel used as window-function LIMIT when no per-parent limit is requested. */
+const NO_LIMIT = 999_999_999;
+
+/**
+ * FK_INDEX and PKS are fully populated at code-gen time for all schema tables,
+ * so lookups by TableName are always defined. These helpers assert non-null
+ * in one place rather than scattering \`!\` or \`as any\` at every call site.
+ */
+function fksOf(table: string): Array<{from: string[]; toTable: string; to: string[]}> {
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+  return FK_INDEX[table]!;
+}
+function pkOf(table: string): string[] {
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+  return PKS[table]!;
+}
+
+/** Parse relation options and nested child spec from a specValue entry. */
+function parseSpecOptions(specValue: any): { options: RelationOptions; childSpec: any } {
+  const options: RelationOptions = {};
+  let childSpec: any = undefined;
+  if (specValue && typeof specValue === "object" && specValue !== true) {
+    if (specValue.select !== undefined) options.select = specValue.select;
+    if (specValue.exclude !== undefined) options.exclude = specValue.exclude;
+    if (specValue.limit !== undefined) options.limit = specValue.limit;
+    if (specValue.offset !== undefined) options.offset = specValue.offset;
+    if (specValue.orderBy !== undefined) options.orderBy = specValue.orderBy;
+    if (specValue.order !== undefined) options.order = specValue.order;
+    if (specValue.include !== undefined) {
+      childSpec = specValue.include;
+    } else {
+      // Support legacy format: { tags: true } alongside new: { include: { tags: true } }
+      const nonOptionKeys = Object.keys(specValue).filter(
+        k => k !== 'select' && k !== 'exclude' && k !== 'limit' && k !== 'offset' && k !== 'orderBy' && k !== 'order'
+      );
+      if (nonOptionKeys.length > 0) {
+        childSpec = Object.fromEntries(nonOptionKeys.map(k => [k, specValue[k]]));
+      }
+    }
+  }
+  return { options, childSpec };
+}
+
 // Public entry
 export async function loadIncludes(
   root: TableName,
@@ -4747,37 +4463,7 @@ export async function loadIncludes(
       // Safely run each loader; never let one bad edge 500 the route
       if (rel.via) {
         // M:N via junction
-        const specValue = s[key];
-        const options: RelationOptions = {};
-        let childSpec: any = undefined;
-
-        if (specValue && typeof specValue === "object" && specValue !== true) {
-          // Extract options
-          if (specValue.select !== undefined) options.select = specValue.select;
-          if (specValue.exclude !== undefined) options.exclude = specValue.exclude;
-          if (specValue.limit !== undefined) options.limit = specValue.limit;
-          if (specValue.offset !== undefined) options.offset = specValue.offset;
-          if (specValue.orderBy !== undefined) options.orderBy = specValue.orderBy;
-          if (specValue.order !== undefined) options.order = specValue.order;
-
-          // Extract nested spec - support both formats:
-          // New: { limit: 3, include: { tags: true } }
-          // Old: { tags: true } (backward compatibility)
-          if (specValue.include !== undefined) {
-            childSpec = specValue.include;
-          } else {
-            // Build childSpec from non-option keys
-            const nonOptionKeys = Object.keys(specValue).filter(
-              k => k !== 'select' && k !== 'exclude' && k !== 'limit' && k !== 'offset' && k !== 'orderBy' && k !== 'order'
-            );
-            if (nonOptionKeys.length > 0) {
-              childSpec = {};
-              for (const k of nonOptionKeys) {
-                childSpec[k] = specValue[k];
-              }
-            }
-          }
-        }
+        const { options, childSpec } = parseSpecOptions(s[key]);
 
         try {
           await loadManyToMany(table, target, rel.via as string, rows, key, options);
@@ -4799,37 +4485,7 @@ export async function loadIncludes(
 
       if (rel.kind === "many") {
         // 1:N target has FK to current
-        const specValue = s[key];
-        const options: RelationOptions = {};
-        let childSpec: any = undefined;
-
-        if (specValue && typeof specValue === "object" && specValue !== true) {
-          // Extract options
-          if (specValue.select !== undefined) options.select = specValue.select;
-          if (specValue.exclude !== undefined) options.exclude = specValue.exclude;
-          if (specValue.limit !== undefined) options.limit = specValue.limit;
-          if (specValue.offset !== undefined) options.offset = specValue.offset;
-          if (specValue.orderBy !== undefined) options.orderBy = specValue.orderBy;
-          if (specValue.order !== undefined) options.order = specValue.order;
-
-          // Extract nested spec - support both formats:
-          // New: { limit: 3, include: { tags: true } }
-          // Old: { tags: true } (backward compatibility)
-          if (specValue.include !== undefined) {
-            childSpec = specValue.include;
-          } else {
-            // Build childSpec from non-option keys
-            const nonOptionKeys = Object.keys(specValue).filter(
-              k => k !== 'select' && k !== 'exclude' && k !== 'limit' && k !== 'offset' && k !== 'orderBy' && k !== 'order'
-            );
-            if (nonOptionKeys.length > 0) {
-              childSpec = {};
-              for (const k of nonOptionKeys) {
-                childSpec[k] = specValue[k];
-              }
-            }
-          }
-        }
+        const { options, childSpec } = parseSpecOptions(s[key]);
 
         try {
           await loadOneToMany(table, target, rows, key, options);
@@ -4849,20 +4505,11 @@ export async function loadIncludes(
       } else {
         // kind === "one"
         // Could be belongs-to (current has FK to target) OR has-one (target unique-FK to current)
-        const specValue = s[key];
-        const options: RelationOptions = {};
-        let childSpec: any = undefined;
-
-        if (specValue && typeof specValue === "object" && specValue !== true) {
-          if (specValue.select !== undefined) options.select = specValue.select;
-          if (specValue.exclude !== undefined) options.exclude = specValue.exclude;
-          // Support { include: TargetIncludeSpec } — mirrors the many/via handler
-          if (specValue.include !== undefined) {
-            childSpec = specValue.include;
-          }
-        }
+        // Destructure only select/exclude/childSpec — limit/offset/orderBy don't apply to 1:1 relations
+        const { options: { select, exclude }, childSpec } = parseSpecOptions(s[key]);
+        const options: RelationOptions = { select, exclude };
 
-        const currFks = (FK_INDEX as any)[table] as Array<{from:string[];toTable:string;to:string[]}>;
+        const currFks = fksOf(table);
         const toTarget = currFks.find(f => f.toTable === target);
         if (toTarget) {
           try {
@@ -4894,16 +4541,16 @@ export async function loadIncludes(
 
   async function loadBelongsTo(curr: TableName, target: TableName, rows: any[], key: string, options: RelationOptions = {}) {
     // current has FK cols referencing target PK
-    const fk = (FK_INDEX as any)[curr].find((f: any) => f.toTable === target);
+    const fk = fksOf(curr).find(f => f.toTable === target);
     if (!fk) { for (const r of rows) r[key] = null; return; }
     const tuples = distinctTuples(rows, fk.from).filter(t => t.every((v: any) => v != null));
     if (!tuples.length) { for (const r of rows) r[key] = null; return; }
 
     // Query target WHERE target.pk IN tuples
-    const pkCols = (PKS as any)[target] as string[];
+    const pkCols = pkOf(target);
     const where = buildOrAndPredicate(pkCols, tuples.length, 1);
     const params = tuples.flat();
-    const sql = \`SELECT * FROM "\${target}" WHERE \${where}\`;
+    const sql = \`SELECT * FROM "\${target}" WHERE (\${where})\${softDeleteFilter(target)}\`;
     log.debug("belongsTo SQL", { curr, target, key, sql, paramsCount: params.length });
     const { rows: targets } = await pg.query(sql, params);
 
@@ -4920,17 +4567,17 @@ export async function loadIncludes(
 
   async function loadHasOne(curr: TableName, target: TableName, rows: any[], key: string, options: RelationOptions = {}) {
     // target has FK cols referencing current PK (unique)
-    const fk = (FK_INDEX as any)[target].find((f: any) => f.toTable === curr);
+    const fk = fksOf(target).find(f => f.toTable === curr);
     if (!fk) { for (const r of rows) r[key] = null; return; }
 
-    const pkCols = (PKS as any)[curr] as string[];
+    const pkCols = pkOf(curr);
     const tuples = distinctTuples(rows, pkCols).filter(t => t.every((v: any) => v != null));
     if (!tuples.length) { for (const r of rows) r[key] = null; return; }
 
     // SELECT target WHERE fk IN tuples
     const where = buildOrAndPredicate(fk.from, tuples.length, 1);
     const params = tuples.flat();
-    const sql = \`SELECT * FROM "\${target}" WHERE \${where}\`;
+    const sql = \`SELECT * FROM "\${target}" WHERE (\${where})\${softDeleteFilter(target)}\`;
     log.debug("hasOne SQL", { curr, target, key, sql, paramsCount: params.length });
     const { rows: targets } = await pg.query(sql, params);
 
@@ -4946,10 +4593,10 @@ export async function loadIncludes(
 
   async function loadOneToMany(curr: TableName, target: TableName, rows: any[], key: string, options: RelationOptions = {}) {
     // target has FK cols referencing current PK
-    const fk = (FK_INDEX as any)[target].find((f: any) => f.toTable === curr);
+    const fk = fksOf(target).find(f => f.toTable === curr);
     if (!fk) { for (const r of rows) r[key] = []; return; }
 
-    const pkCols = (PKS as any)[curr] as string[];
+    const pkCols = pkOf(curr);
     const tuples = distinctTuples(rows, pkCols).filter(t => t.every((v: any) => v != null));
     if (!tuples.length) { for (const r of rows) r[key] = []; return; }
 
@@ -4957,7 +4604,7 @@ export async function loadIncludes(
     const params = tuples.flat();
 
     // Build SQL with optional ORDER BY, LIMIT, OFFSET
-    let sql = \`SELECT * FROM "\${target}" WHERE \${where}\`;
+    let sql = \`SELECT * FROM "\${target}" WHERE (\${where})\${softDeleteFilter(target)}\`;
 
     // If limit/offset are needed, use window functions to limit per parent
     if (options.limit !== undefined || options.offset !== undefined) {
@@ -4967,13 +4614,13 @@ export async function loadIncludes(
 
       const partitionCols = fk.from.map((c: string) => \`"\${c}"\`).join(', ');
       const offset = options.offset ?? 0;
-      const limit = options.limit ?? 999999999;
+      const limit = options.limit ?? NO_LIMIT;
 
       sql = \`
         SELECT * FROM (
           SELECT *, ROW_NUMBER() OVER (PARTITION BY \${partitionCols} \${orderByClause}) as __rn
           FROM "\${target}"
-          WHERE \${where}
+          WHERE (\${where})\${softDeleteFilter(target)}
         ) __sub
         WHERE __rn > \${offset} AND __rn <= \${offset + limit}
       \`;
@@ -5003,11 +4650,11 @@ export async function loadIncludes(
 
   async function loadManyToMany(curr: TableName, target: TableName, via: string, rows: any[], key: string, options: RelationOptions = {}) {
     // via has two FKs: one to curr, one to target
-    const toCurr = (FK_INDEX as any)[via].find((f: any) => f.toTable === curr);
-    const toTarget = (FK_INDEX as any)[via].find((f: any) => f.toTable === target);
+    const toCurr = fksOf(via).find(f => f.toTable === curr);
+    const toTarget = fksOf(via).find(f => f.toTable === target);
     if (!toCurr || !toTarget) { for (const r of rows) r[key] = []; return; }
 
-    const pkCols = (PKS as any)[curr] as string[];
+    const pkCols = pkOf(curr);
     const tuples = distinctTuples(rows, pkCols).filter(t => t.every((v: any) => v != null));
     if (!tuples.length) { for (const r of rows) r[key] = []; return; }
 
@@ -5022,9 +4669,9 @@ export async function loadIncludes(
 
       const partitionCols = toCurr.from.map((c: string) => \`j."\${c}"\`).join(', ');
       const offset = options.offset ?? 0;
-      const limit = options.limit ?? 999999999;
+      const limit = options.limit ?? NO_LIMIT;
 
-      const targetPkCols = (PKS as any)[target] as string[];
+      const targetPkCols = pkOf(target);
       const joinConditions = toTarget.from.map((jCol: string, i: number) => {
         return \`j."\${jCol}" = t."\${targetPkCols[i]}"\`;
       }).join(' AND ');
@@ -5037,7 +4684,7 @@ export async function loadIncludes(
                  \${toCurr.from.map((c: string) => \`j."\${c}"\`).join(' || \\',\\' || ')} as __parent_fk
           FROM "\${via}" j
           INNER JOIN "\${target}" t ON \${joinConditions}
-          WHERE \${whereVia}
+          WHERE (\${whereVia})\${softDeleteFilter(target, "t")}
         ) __numbered
         WHERE __numbered.__rn > \${offset} AND __numbered.__rn <= \${offset + limit}
       \`;
@@ -5080,8 +4727,8 @@ export async function loadIncludes(
 
       // 2) Load targets by distinct target fk tuples in junction
       const tTuples = distinctTuples(jrows, toTarget.from);
-      const whereT = buildOrAndPredicate((PKS as any)[target], tTuples.length, 1);
-      const sqlT = \`SELECT * FROM "\${target}" WHERE \${whereT}\`;
+      const whereT = buildOrAndPredicate(pkOf(target), tTuples.length, 1);
+      const sqlT = \`SELECT * FROM "\${target}" WHERE (\${whereT})\${softDeleteFilter(target)}\`;
       const paramsT = tTuples.flat();
       log.debug("manyToMany target SQL", { curr, target, via, key, sql: sqlT, paramsCount: paramsT.length });
       const { rows: targets } = await pg.query(sqlT, paramsT);
@@ -5089,7 +4736,7 @@ export async function loadIncludes(
       // Apply select/exclude filtering
       const filteredTargets = filterFields(targets, options.select, options.exclude);
 
-      const tIdx = indexByTuple(filteredTargets, (PKS as any)[target]);
+      const tIdx = indexByTuple(filteredTargets, pkOf(target));
 
       // 3) Group junction rows by current pk tuple, map to target rows
       const byCurr = groupByTuple(jrows, toCurr.from);
@@ -7513,9 +7160,14 @@ async function generate(configPath) {
     path: join2(serverDir, "include-builder.ts"),
     content: emitIncludeBuilder(graph, cfg.includeMethodsDepth || 2)
   });
+  const softDeleteCols = Object.fromEntries(Object.values(model.tables).map((t) => {
+    const col = resolveSoftDeleteColumn(cfg, t.name);
+    const validated = col && t.columns.some((c) => c.name === col) ? col : null;
+    return [t.name, validated];
+  }));
   files.push({
     path: join2(serverDir, "include-loader.ts"),
-    content: emitIncludeLoader(graph, model, cfg.includeMethodsDepth || 2, cfg.useJsExtensions)
+    content: emitIncludeLoader(model, cfg.includeMethodsDepth || 2, { softDeleteCols, useJsExtensions: cfg.useJsExtensions })
   });
   files.push({ path: join2(serverDir, "logger.ts"), content: emitLogger() });
   if (getAuthStrategy(normalizedAuth) !== "none") {
@@ -7541,7 +7193,7 @@ async function generate(configPath) {
     let routeContent;
     if (serverFramework === "hono") {
       routeContent = emitHonoRoutes(table, graph, {
-        softDeleteColumn: resolveSoftDeleteColumn(cfg, table.name),
+        softDeleteColumn: softDeleteCols[table.name] ?? null,
         includeMethodsDepth: cfg.includeMethodsDepth || 2,
         authStrategy: getAuthStrategy(normalizedAuth),
         useJsExtensions: cfg.useJsExtensions,