postgresdk 0.18.8 → 0.18.10

package/README.md

@@ -567,7 +567,7 @@ const deleted = await sdk.users.delete(123);
 
 #### Relationships & Eager Loading
 
-Automatically handles relationships with the `include` parameter:
+Automatically handles relationships with the `include` parameter. **Type inference works automatically** - no manual casts needed:
 
 ```typescript
 // 1:N relationship - Get authors with their books
@@ -575,12 +575,14 @@ const authorsResult = await sdk.authors.list({
   include: { books: true }
 });
 const authors = authorsResult.data;
+// ✅ authors[0].books is automatically typed as SelectBooks[]
 
 // M:N relationship - Get books with their tags
 const booksResult = await sdk.books.list({
   include: { tags: true }
 });
 const books = booksResult.data;
+// ✅ books[0].tags is automatically typed as SelectTags[]
 
 // Nested includes - Get authors with books and their tags
 const nestedResult = await sdk.authors.list({
@@ -591,6 +593,7 @@ const nestedResult = await sdk.authors.list({
   }
 });
 const authorsWithBooksAndTags = nestedResult.data;
+// ✅ TypeScript knows: data[0].books[0].tags exists and is SelectTags[]
 ```
 
 **Typed Include Methods:**

package/dist/cli.js

@@ -2899,6 +2899,73 @@ function toPascal(s) {
   return s.split(/[_\s-]+/).map((w) => w?.[0] ? w[0].toUpperCase() + w.slice(1) : "").join("");
 }
 
+// src/emit-include-resolver.ts
+init_utils();
+function emitIncludeResolver(graph, useJsExtensions) {
+  const ext = useJsExtensions ? ".js" : "";
+  let out = `/**
+ * AUTO-GENERATED FILE - DO NOT EDIT
+ *
+ * Type helpers for automatic include inference.
+ * These types transform IncludeSpec into the actual return type shape.
+ */
+`;
+  const tables = Object.keys(graph);
+  for (const table of tables) {
+    out += `import type { Select${pascal(table)} } from "./types/${table}${ext}";
+`;
+  }
+  for (const table of tables) {
+    out += `import type { ${pascal(table)}IncludeSpec } from "./include-spec${ext}";
+`;
+  }
+  out += `
+`;
+  for (const table of tables) {
+    const Type = pascal(table);
+    const edges = graph[table] || {};
+    const edgeEntries = Object.entries(edges);
+    if (edgeEntries.length === 0) {
+      out += `export type ${Type}WithIncludes<TInclude extends ${Type}IncludeSpec> = Select${Type};
+
+`;
+      continue;
+    }
+    out += `export type ${Type}WithIncludes<TInclude extends ${Type}IncludeSpec> =
+  Select${Type} & {
+    [K in keyof TInclude as TInclude[K] extends false | undefined ? never : K]:`;
+    for (let i = 0;i < edgeEntries.length; i++) {
+      const [relKey, edge] = edgeEntries[i];
+      if (!relKey || !edge)
+        continue;
+      const targetType = pascal(edge.target);
+      const isLast = i === edgeEntries.length - 1;
+      out += `
+      K extends '${relKey}' ? `;
+      if (edge.kind === "many") {
+        out += `(
+        TInclude[K] extends { include: infer U extends ${targetType}IncludeSpec }
+          ? Array<${targetType}WithIncludes<U>>
+          : Select${targetType}[]
+      )`;
+      } else {
+        out += `(
+        TInclude[K] extends { include: infer U extends ${targetType}IncludeSpec }
+          ? ${targetType}WithIncludes<U>
+          : Select${targetType}
+      )`;
+      }
+      out += ` :${isLast ? `
+      never` : ""}`;
+    }
+    out += `
+  };
+
+`;
+  }
+  return out;
+}
+
 // src/emit-include-builder.ts
 function emitIncludeBuilder(graph, maxDepth) {
   return `/**
@@ -3460,7 +3527,9 @@ function emitClient(table, graph, opts, model) {
     }
   }
   const typeImports = `import type { Insert${Type}, Update${Type}, Select${Type} } from "./types/${table.name}${ext}";`;
-  const includeSpecImport = `import type { ${Type}IncludeSpec } from "./include-spec${ext}";`;
+  const includeSpecTypes = [table.name, ...Array.from(importedTypes).filter((t) => t !== table.name)];
+  const includeSpecImport = `import type { ${includeSpecTypes.map((t) => `${pascal(t)}IncludeSpec`).join(", ")} } from "./include-spec${ext}";`;
+  const includeResolverImport = `import type { ${Type}WithIncludes } from "./include-resolver${ext}";`;
   const otherTableImports = [];
   for (const target of Array.from(importedTypes)) {
     if (target !== table.name) {
@@ -3528,6 +3597,8 @@ function emitClient(table, graph, opts, model) {
     } else if (pattern.type === "nested" && pattern.nestedKey) {
       const paramName = toIncludeParamName(pattern.nestedKey);
       includeParamNames.push(paramName);
+      const targetTable = method.targets[0];
+      const targetType = targetTable ? pascal(targetTable) : Type;
       paramsType = `{
     select?: string[];
     exclude?: string[];
@@ -3543,7 +3614,7 @@ function emitClient(table, graph, opts, model) {
       order?: "asc" | "desc";
       limit?: number;
       offset?: number;
-      include?: ${Type}IncludeSpec;
+      include?: ${targetType}IncludeSpec;
     };
   }`;
     }
@@ -3652,6 +3723,7 @@ import type { Where } from "./where-types${ext}";
 import type { PaginatedResponse } from "./types/shared${ext}";
 ${typeImports}
 ${includeSpecImport}
+${includeResolverImport}
 ${otherTableImports.join(`
 `)}
 
@@ -3842,14 +3914,17 @@ ${hasJsonbColumns ? `  /**
    * @param params.order - Sort direction(s): "asc" or "desc"
    * @param params.limit - Maximum number of records to return (default: 50, max: 1000)
    * @param params.offset - Number of records to skip for pagination
-   * @param params.include - Related records to include (see listWith* methods for typed includes)
-   * @returns Paginated results with all fields
+   * @param params.include - Related records to include (return type automatically infers included relations)
+   * @returns Paginated results with all fields (and included relations if specified)
    * @example
    * // With JSONB type override:
    * const users = await client.list<{ metadata: Metadata }>({ where: { status: 'active' } });
+   * // With automatic include inference:
+   * const users = await client.list({ include: { posts: true } });
+   * // users[0].posts is automatically typed
    */
-  async list<TJsonb extends Partial<Select${Type}> = {}>(params?: {
-    include?: ${Type}IncludeSpec;
+  async list<TJsonb extends Partial<Select${Type}> = {}, TInclude extends ${Type}IncludeSpec = {}>(params?: {
+    include?: TInclude;
     limit?: number;
     offset?: number;
     where?: Where<Select${Type}<TJsonb>>;${hasVectorColumns ? `
@@ -3861,7 +3936,7 @@ ${hasJsonbColumns ? `  /**
     };` : ""}
     orderBy?: string | string[];
     order?: "asc" | "desc" | ("asc" | "desc")[];
-  }): Promise<PaginatedResponse<Select${Type}<TJsonb>${hasVectorColumns ? " & { _distance?: number }" : ""}>>;
+  }): Promise<PaginatedResponse<${Type}WithIncludes<TInclude>${hasVectorColumns ? " & { _distance?: number }" : ""}>>;
   async list<TJsonb extends Partial<Select${Type}> = {}>(params?: {
     include?: ${Type}IncludeSpec;
     select?: string[];
@@ -3927,11 +4002,11 @@ ${hasJsonbColumns ? `  /**
    * @param params.order - Sort direction(s): "asc" or "desc"
    * @param params.limit - Maximum number of records to return (default: 50, max: 1000)
    * @param params.offset - Number of records to skip for pagination
-   * @param params.include - Related records to include (see listWith* methods for typed includes)
-   * @returns Paginated results with all fields
+   * @param params.include - Related records to include (return type automatically infers included relations)
+   * @returns Paginated results with all fields (and included relations if specified)
    */
-  async list(params?: {
-    include?: ${Type}IncludeSpec;
+  async list<TInclude extends ${Type}IncludeSpec = {}>(params?: {
+    include?: TInclude;
     limit?: number;
     offset?: number;
     where?: Where<Select${Type}>;${hasVectorColumns ? `
@@ -3943,7 +4018,7 @@ ${hasJsonbColumns ? `  /**
     };` : ""}
     orderBy?: string | string[];
     order?: "asc" | "desc" | ("asc" | "desc")[];
-  }): Promise<PaginatedResponse<Select${Type}${hasVectorColumns ? " & { _distance?: number }" : ""}>>;
+  }): Promise<PaginatedResponse<${Type}WithIncludes<TInclude>${hasVectorColumns ? " & { _distance?: number }" : ""}>>;
   async list(params?: {
     include?: ${Type}IncludeSpec;
     select?: string[];
@@ -7116,6 +7191,8 @@ async function generate(configPath) {
   const includeSpec = emitIncludeSpec(graph);
   files.push({ path: join(serverDir, "include-spec.ts"), content: includeSpec });
   files.push({ path: join(clientDir, "include-spec.ts"), content: includeSpec });
+  const includeResolver = emitIncludeResolver(graph, cfg.useJsExtensions);
+  files.push({ path: join(clientDir, "include-resolver.ts"), content: includeResolver });
   files.push({ path: join(clientDir, "params", "shared.ts"), content: emitSharedParamsZod() });
   files.push({ path: join(clientDir, "types", "shared.ts"), content: emitSharedTypes() });
   files.push({ path: join(clientDir, "base-client.ts"), content: emitBaseClient() });

package/dist/emit-include-resolver.d.ts

@@ -0,0 +1,9 @@
+import type { Graph } from "./rel-classify";
+/**
+ * Generate TypeScript types that resolve IncludeSpec to actual return types
+ *
+ * This allows automatic type inference:
+ * const result = await sdk.captures.list({ include: { website: true } });
+ * // result.data[0].website is typed as SelectWebsites
+ */
+export declare function emitIncludeResolver(graph: Graph, useJsExtensions?: boolean): string;

package/dist/index.js

@@ -1938,6 +1938,73 @@ function toPascal(s) {
   return s.split(/[_\s-]+/).map((w) => w?.[0] ? w[0].toUpperCase() + w.slice(1) : "").join("");
 }
 
+// src/emit-include-resolver.ts
+init_utils();
+function emitIncludeResolver(graph, useJsExtensions) {
+  const ext = useJsExtensions ? ".js" : "";
+  let out = `/**
+ * AUTO-GENERATED FILE - DO NOT EDIT
+ *
+ * Type helpers for automatic include inference.
+ * These types transform IncludeSpec into the actual return type shape.
+ */
+`;
+  const tables = Object.keys(graph);
+  for (const table of tables) {
+    out += `import type { Select${pascal(table)} } from "./types/${table}${ext}";
+`;
+  }
+  for (const table of tables) {
+    out += `import type { ${pascal(table)}IncludeSpec } from "./include-spec${ext}";
+`;
+  }
+  out += `
+`;
+  for (const table of tables) {
+    const Type = pascal(table);
+    const edges = graph[table] || {};
+    const edgeEntries = Object.entries(edges);
+    if (edgeEntries.length === 0) {
+      out += `export type ${Type}WithIncludes<TInclude extends ${Type}IncludeSpec> = Select${Type};
+
+`;
+      continue;
+    }
+    out += `export type ${Type}WithIncludes<TInclude extends ${Type}IncludeSpec> =
+  Select${Type} & {
+    [K in keyof TInclude as TInclude[K] extends false | undefined ? never : K]:`;
+    for (let i = 0;i < edgeEntries.length; i++) {
+      const [relKey, edge] = edgeEntries[i];
+      if (!relKey || !edge)
+        continue;
+      const targetType = pascal(edge.target);
+      const isLast = i === edgeEntries.length - 1;
+      out += `
+      K extends '${relKey}' ? `;
+      if (edge.kind === "many") {
+        out += `(
+        TInclude[K] extends { include: infer U extends ${targetType}IncludeSpec }
+          ? Array<${targetType}WithIncludes<U>>
+          : Select${targetType}[]
+      )`;
+      } else {
+        out += `(
+        TInclude[K] extends { include: infer U extends ${targetType}IncludeSpec }
+          ? ${targetType}WithIncludes<U>
+          : Select${targetType}
+      )`;
+      }
+      out += ` :${isLast ? `
+      never` : ""}`;
+    }
+    out += `
+  };
+
+`;
+  }
+  return out;
+}
+
 // src/emit-include-builder.ts
 function emitIncludeBuilder(graph, maxDepth) {
   return `/**
@@ -2499,7 +2566,9 @@ function emitClient(table, graph, opts, model) {
     }
   }
   const typeImports = `import type { Insert${Type}, Update${Type}, Select${Type} } from "./types/${table.name}${ext}";`;
-  const includeSpecImport = `import type { ${Type}IncludeSpec } from "./include-spec${ext}";`;
+  const includeSpecTypes = [table.name, ...Array.from(importedTypes).filter((t) => t !== table.name)];
+  const includeSpecImport = `import type { ${includeSpecTypes.map((t) => `${pascal(t)}IncludeSpec`).join(", ")} } from "./include-spec${ext}";`;
+  const includeResolverImport = `import type { ${Type}WithIncludes } from "./include-resolver${ext}";`;
   const otherTableImports = [];
   for (const target of Array.from(importedTypes)) {
     if (target !== table.name) {
@@ -2567,6 +2636,8 @@ function emitClient(table, graph, opts, model) {
     } else if (pattern.type === "nested" && pattern.nestedKey) {
       const paramName = toIncludeParamName(pattern.nestedKey);
       includeParamNames.push(paramName);
+      const targetTable = method.targets[0];
+      const targetType = targetTable ? pascal(targetTable) : Type;
       paramsType = `{
     select?: string[];
     exclude?: string[];
@@ -2582,7 +2653,7 @@ function emitClient(table, graph, opts, model) {
       order?: "asc" | "desc";
       limit?: number;
       offset?: number;
-      include?: ${Type}IncludeSpec;
+      include?: ${targetType}IncludeSpec;
     };
   }`;
     }
@@ -2691,6 +2762,7 @@ import type { Where } from "./where-types${ext}";
 import type { PaginatedResponse } from "./types/shared${ext}";
 ${typeImports}
 ${includeSpecImport}
+${includeResolverImport}
 ${otherTableImports.join(`
 `)}
 
@@ -2881,14 +2953,17 @@ ${hasJsonbColumns ? `  /**
    * @param params.order - Sort direction(s): "asc" or "desc"
    * @param params.limit - Maximum number of records to return (default: 50, max: 1000)
    * @param params.offset - Number of records to skip for pagination
-   * @param params.include - Related records to include (see listWith* methods for typed includes)
-   * @returns Paginated results with all fields
+   * @param params.include - Related records to include (return type automatically infers included relations)
+   * @returns Paginated results with all fields (and included relations if specified)
    * @example
    * // With JSONB type override:
    * const users = await client.list<{ metadata: Metadata }>({ where: { status: 'active' } });
+   * // With automatic include inference:
+   * const users = await client.list({ include: { posts: true } });
+   * // users[0].posts is automatically typed
    */
-  async list<TJsonb extends Partial<Select${Type}> = {}>(params?: {
-    include?: ${Type}IncludeSpec;
+  async list<TJsonb extends Partial<Select${Type}> = {}, TInclude extends ${Type}IncludeSpec = {}>(params?: {
+    include?: TInclude;
     limit?: number;
     offset?: number;
     where?: Where<Select${Type}<TJsonb>>;${hasVectorColumns ? `
@@ -2900,7 +2975,7 @@ ${hasJsonbColumns ? `  /**
     };` : ""}
     orderBy?: string | string[];
     order?: "asc" | "desc" | ("asc" | "desc")[];
-  }): Promise<PaginatedResponse<Select${Type}<TJsonb>${hasVectorColumns ? " & { _distance?: number }" : ""}>>;
+  }): Promise<PaginatedResponse<${Type}WithIncludes<TInclude>${hasVectorColumns ? " & { _distance?: number }" : ""}>>;
   async list<TJsonb extends Partial<Select${Type}> = {}>(params?: {
     include?: ${Type}IncludeSpec;
     select?: string[];
@@ -2966,11 +3041,11 @@ ${hasJsonbColumns ? `  /**
    * @param params.order - Sort direction(s): "asc" or "desc"
    * @param params.limit - Maximum number of records to return (default: 50, max: 1000)
    * @param params.offset - Number of records to skip for pagination
-   * @param params.include - Related records to include (see listWith* methods for typed includes)
-   * @returns Paginated results with all fields
+   * @param params.include - Related records to include (return type automatically infers included relations)
+   * @returns Paginated results with all fields (and included relations if specified)
    */
-  async list(params?: {
-    include?: ${Type}IncludeSpec;
+  async list<TInclude extends ${Type}IncludeSpec = {}>(params?: {
+    include?: TInclude;
     limit?: number;
     offset?: number;
     where?: Where<Select${Type}>;${hasVectorColumns ? `
@@ -2982,7 +3057,7 @@ ${hasJsonbColumns ? `  /**
     };` : ""}
     orderBy?: string | string[];
     order?: "asc" | "desc" | ("asc" | "desc")[];
-  }): Promise<PaginatedResponse<Select${Type}${hasVectorColumns ? " & { _distance?: number }" : ""}>>;
+  }): Promise<PaginatedResponse<${Type}WithIncludes<TInclude>${hasVectorColumns ? " & { _distance?: number }" : ""}>>;
   async list(params?: {
     include?: ${Type}IncludeSpec;
     select?: string[];
@@ -6155,6 +6230,8 @@ async function generate(configPath) {
   const includeSpec = emitIncludeSpec(graph);
   files.push({ path: join(serverDir, "include-spec.ts"), content: includeSpec });
   files.push({ path: join(clientDir, "include-spec.ts"), content: includeSpec });
+  const includeResolver = emitIncludeResolver(graph, cfg.useJsExtensions);
+  files.push({ path: join(clientDir, "include-resolver.ts"), content: includeResolver });
   files.push({ path: join(clientDir, "params", "shared.ts"), content: emitSharedParamsZod() });
   files.push({ path: join(clientDir, "types", "shared.ts"), content: emitSharedTypes() });
   files.push({ path: join(clientDir, "base-client.ts"), content: emitBaseClient() });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "postgresdk",
-  "version": "0.18.8",
+  "version": "0.18.10",
   "description": "Generate a typed server/client SDK from a Postgres schema (includes, Zod, Hono).",
   "type": "module",
   "bin": {