postgresdk 0.16.10 → 0.16.13

package/README.md

@@ -146,6 +146,7 @@ export default {
   schema: "public",                    // Database schema to introspect
   outDir: "./api",                     // Output directory (or { client: "./sdk", server: "./api" })
   softDeleteColumn: null,              // Column name for soft deletes (e.g., "deleted_at")
+  numericMode: "auto",                 // "auto" | "number" | "string" - How to type numeric columns
   includeMethodsDepth: 2,              // Max depth for nested includes
   dateType: "date",                    // "date" | "string" - How to handle timestamps
   serverFramework: "hono",             // Currently only hono is supported
@@ -175,6 +176,14 @@ export default {
 };
 ```
 
+#### Type Mapping (numericMode)
+
+Controls how PostgreSQL numeric types map to TypeScript:
+
+- **`"auto"` (default)**: `int2`/`int4`/floats → `number`, `int8`/`numeric` → `string`
+- **`"number"`**: All numeric → `number` (⚠️ unsafe for bigint - JS can't handle values > 2^53)
+- **`"string"`**: All numeric → `string` (safe but requires parsing)
+
 ### Database Drivers
 
 The generated code works with any PostgreSQL client that implements a simple `query` interface:
@@ -584,6 +593,58 @@ const nestedResult = await sdk.authors.list({
 const authorsWithBooksAndTags = nestedResult.data;
 ```
 
+**Typed Include Methods:**
+
+For convenience and better type safety, the SDK generates `listWith*` and `getByPkWith*` methods for common include patterns:
+
+```typescript
+// Typed methods provide full autocomplete and type safety
+const result = await sdk.authors.listWithBooks();
+// result.data[0].books is typed as SelectBooks[]
+
+// Control included relations with options
+const topAuthors = await sdk.authors.listWithBooks({
+  limit: 10,
+  booksInclude: {
+    orderBy: 'published_at',
+    order: 'desc',
+    limit: 5  // Only get top 5 books per author
+  }
+});
+
+// Parallel includes (multiple relations at once)
+const result2 = await sdk.books.listWithAuthorAndTags({
+  tagsInclude: {
+    orderBy: 'name',
+    limit: 3
+  }
+  // author is included automatically (one-to-one)
+});
+
+// Nested includes with control at each level
+const result3 = await sdk.authors.listWithBooksAndTags({
+  booksInclude: {
+    orderBy: 'title',
+    limit: 10,
+    include: {
+      tags: {
+        orderBy: 'name',
+        order: 'asc',
+        limit: 5
+      }
+    }
+  }
+});
+
+// Works with getByPk too
+const author = await sdk.authors.getByPkWithBooks('author-id', {
+  booksInclude: {
+    orderBy: 'published_at',
+    limit: 3
+  }
+});
+```
+
 #### Filtering & Pagination
 
 All `list()` methods return pagination metadata:

package/dist/cli.js

@@ -1751,6 +1751,15 @@ function extractConfigFields(configContent) {
       isCommented: !!depthMatch[1]
     });
   }
+  const numericModeMatch = configContent.match(/^\s*(\/\/)?\s*numericMode:\s*"(.+)"/m);
+  if (numericModeMatch) {
+    fields.push({
+      key: "numericMode",
+      value: numericModeMatch[2],
+      description: "How to type numeric columns in TypeScript",
+      isCommented: !!numericModeMatch[1]
+    });
+  }
   const frameworkMatch = configContent.match(/^\s*(\/\/)?\s*serverFramework:\s*"(.+)"/m);
   if (frameworkMatch) {
     fields.push({
@@ -1918,7 +1927,16 @@ export default {
    * @example "deleted_at"
    */
   ${getFieldLine("softDeleteColumn", existingFields, mergeStrategy, "null", userChoices)}
-  
+
+  /**
+   * How to type numeric columns in TypeScript
+   * - "auto": int2/int4/float → number, int8/numeric → string (recommended)
+   * - "number": All numeric types become TypeScript number (unsafe for bigint)
+   * - "string": All numeric types become TypeScript string (legacy)
+   * @default "auto"
+   */
+  ${getFieldLine("numericMode", existingFields, mergeStrategy, '"auto"', userChoices)}
+
   /**
    * Maximum depth for nested relationship includes to prevent infinite loops
    * @default 2
@@ -2347,6 +2365,20 @@ export default {
    */
   // softDeleteColumn: null,
 
+  /**
+   * How to type numeric columns in TypeScript
+   * Options:
+   *   - "auto": int2/int4/float → number, int8/numeric → string (recommended, default)
+   *   - "number": All numeric types become TypeScript number (unsafe for bigint)
+   *   - "string": All numeric types become TypeScript string (legacy behavior)
+   *
+   * Auto mode is safest - keeps JavaScript-safe integers as numbers,
+   * but preserves precision for bigint/numeric by using strings.
+   *
+   * Default: "auto"
+   */
+  // numericMode: "auto",
+
   /**
    * Maximum depth for nested relationship includes to prevent infinite loops
    * Default: 2
@@ -2810,7 +2842,7 @@ function emitIncludeSpec(graph) {
 `;
     for (const [relKey, edge] of entries) {
       if (edge.kind === "many") {
-        out += `  ${relKey}?: boolean | { include?: ${toPascal(edge.target)}IncludeSpec; limit?: number; offset?: number; };
+        out += `  ${relKey}?: boolean | { include?: ${toPascal(edge.target)}IncludeSpec; limit?: number; offset?: number; orderBy?: string; order?: "asc" | "desc"; };
 `;
       } else {
         out += `  ${relKey}?: boolean | ${toPascal(edge.target)}IncludeSpec;
@@ -2879,10 +2911,20 @@ function emitZod(table, opts, enums) {
       return `z.string()`;
     if (t === "bool" || t === "boolean")
       return `z.boolean()`;
-    if (t === "int2" || t === "int4" || t === "int8")
-      return opts.numericMode === "number" ? `z.number()` : `z.string()`;
-    if (t === "numeric" || t === "float4" || t === "float8")
-      return opts.numericMode === "number" ? `z.number()` : `z.string()`;
+    if (t === "int2" || t === "int4" || t === "int8") {
+      if (opts.numericMode === "number")
+        return `z.number()`;
+      if (opts.numericMode === "string")
+        return `z.string()`;
+      return t === "int2" || t === "int4" ? `z.number()` : `z.string()`;
+    }
+    if (t === "numeric" || t === "float4" || t === "float8") {
+      if (opts.numericMode === "number")
+        return `z.number()`;
+      if (opts.numericMode === "string")
+        return `z.string()`;
+      return t === "float4" || t === "float8" ? `z.number()` : `z.string()`;
+    }
     if (t === "jsonb" || t === "json")
       return `z.unknown()`;
     if (t === "date" || t.startsWith("timestamp"))
@@ -3255,6 +3297,24 @@ function isJsonbType(pgType) {
   const t = pgType.toLowerCase();
   return t === "json" || t === "jsonb";
 }
+function toIncludeParamName(relationKey) {
+  return `${relationKey}Include`;
+}
+function analyzeIncludeSpec(includeSpec) {
+  const keys = Object.keys(includeSpec);
+  if (keys.length > 1) {
+    return { type: "parallel", keys };
+  }
+  const key = keys[0];
+  if (!key) {
+    return { type: "single", keys: [] };
+  }
+  const value = includeSpec[key];
+  if (typeof value === "object" && value !== null) {
+    return { type: "nested", keys: [key], nestedKey: key, nestedValue: value };
+  }
+  return { type: "single", keys: [key] };
+}
 function emitClient(table, graph, opts, model) {
   const Type = pascal(table.name);
   const ext = opts.useJsExtensions ? ".js" : "";
@@ -3293,39 +3353,157 @@ 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?: Where<Select${Type}>; orderBy?: string | string[]; order?: "asc" | "desc" | ("asc" | "desc")[]; }, "include">`;
+    const pattern = analyzeIncludeSpec(method.includeSpec);
     const relationshipDesc = method.path.map((p, i) => {
       const isLast = i === method.path.length - 1;
       const relation = method.isMany[i] ? "many" : "one";
       return isLast ? p : `${p} -> `;
     }).join("");
+    let paramsType = "";
+    const includeParamNames = [];
+    if (pattern.type === "single") {
+      const key = pattern.keys[0];
+      if (key) {
+        const paramName = toIncludeParamName(key);
+        includeParamNames.push(paramName);
+        paramsType = `{
+    limit?: number;
+    offset?: number;
+    where?: Where<Select${Type}>;
+    orderBy?: string | string[];
+    order?: "asc" | "desc" | ("asc" | "desc")[];
+    ${paramName}?: {
+      orderBy?: string | string[];
+      order?: "asc" | "desc";
+      limit?: number;
+      offset?: number;
+    };
+  }`;
+      }
+    } else if (pattern.type === "parallel") {
+      const includeParams = pattern.keys.map((key) => {
+        const paramName = toIncludeParamName(key);
+        includeParamNames.push(paramName);
+        return `${paramName}?: {
+      orderBy?: string | string[];
+      order?: "asc" | "desc";
+      limit?: number;
+      offset?: number;
+    }`;
+      }).join(`;
+    `);
+      paramsType = `{
+    limit?: number;
+    offset?: number;
+    where?: Where<Select${Type}>;
+    orderBy?: string | string[];
+    order?: "asc" | "desc" | ("asc" | "desc")[];
+    ${includeParams};
+  }`;
+    } else if (pattern.type === "nested" && pattern.nestedKey) {
+      const paramName = toIncludeParamName(pattern.nestedKey);
+      includeParamNames.push(paramName);
+      paramsType = `{
+    limit?: number;
+    offset?: number;
+    where?: Where<Select${Type}>;
+    orderBy?: string | string[];
+    order?: "asc" | "desc" | ("asc" | "desc")[];
+    ${paramName}?: {
+      orderBy?: string | string[];
+      order?: "asc" | "desc";
+      limit?: number;
+      offset?: number;
+      include?: any;
+    };
+  }`;
+    }
     if (isGetByPk) {
       const pkWhere = hasCompositePk ? `{ ${safePk.map((col) => `${col}: pk.${col}`).join(", ")} }` : `{ ${safePk[0] || "id"}: pk }`;
       const baseReturnType = method.returnType.replace(" | null", "");
+      let transformCode = "";
+      if (includeParamNames.length > 0) {
+        const destructure = includeParamNames.map((name) => name).join(", ");
+        if (pattern.type === "single") {
+          const key = pattern.keys[0];
+          const paramName = includeParamNames[0];
+          transformCode = `
+    const { ${destructure} } = params ?? {};
+    const includeSpec = ${paramName} ? { ${key}: ${paramName} } : ${JSON.stringify(method.includeSpec)};`;
+        } else if (pattern.type === "parallel") {
+          const includeSpecCode = pattern.keys.map((key, idx) => {
+            const paramName = includeParamNames[idx];
+            return `${key}: ${paramName} ?? true`;
+          }).join(", ");
+          transformCode = `
+    const { ${destructure} } = params ?? {};
+    const includeSpec = { ${includeSpecCode} };`;
+        } else if (pattern.type === "nested" && pattern.nestedKey) {
+          const key = pattern.nestedKey;
+          const paramName = includeParamNames[0];
+          transformCode = `
+    const { ${destructure} } = params ?? {};
+    const includeSpec = ${paramName} ? { ${key}: ${paramName} } : ${JSON.stringify(method.includeSpec)};`;
+        }
+      } else {
+        transformCode = `
+    const includeSpec = ${JSON.stringify(method.includeSpec)};`;
+      }
       includeMethodsCode += `
   /**
    * Get a ${table.name} record by primary key with included related ${relationshipDesc}
    * @param pk - The primary key value${hasCompositePk ? "s" : ""}
+   * @param params - Optional include options
    * @returns The record with nested ${method.path.join(" and ")} if found, null otherwise
    */
-  async ${method.name}(pk: ${pkType}): Promise<${method.returnType}> {
+  async ${method.name}(pk: ${pkType}, params?: ${paramsType}): Promise<${method.returnType}> {${transformCode}
     const results = await this.post<PaginatedResponse<${baseReturnType}>>(\`\${this.resource}/list\`, {
       where: ${pkWhere},
-      include: ${JSON.stringify(method.includeSpec)},
+      include: includeSpec,
       limit: 1
     });
     return (results.data[0] as ${baseReturnType}) ?? null;
   }
 `;
     } else {
+      let transformCode = "";
+      if (includeParamNames.length > 0) {
+        const destructure = includeParamNames.map((name) => name).join(", ");
+        if (pattern.type === "single") {
+          const key = pattern.keys[0];
+          const paramName = includeParamNames[0];
+          transformCode = `
+    const { ${destructure}, ...baseParams } = params ?? {};
+    const includeSpec = ${paramName} ? { ${key}: ${paramName} } : ${JSON.stringify(method.includeSpec)};
+    return this.post<${method.returnType}>(\`\${this.resource}/list\`, { ...baseParams, include: includeSpec });`;
+        } else if (pattern.type === "parallel") {
+          const includeSpecCode = pattern.keys.map((key, idx) => {
+            const paramName = includeParamNames[idx];
+            return `${key}: ${paramName} ?? true`;
+          }).join(", ");
+          transformCode = `
+    const { ${destructure}, ...baseParams } = params ?? {};
+    const includeSpec = { ${includeSpecCode} };
+    return this.post<${method.returnType}>(\`\${this.resource}/list\`, { ...baseParams, include: includeSpec });`;
+        } else if (pattern.type === "nested" && pattern.nestedKey) {
+          const key = pattern.nestedKey;
+          const paramName = includeParamNames[0];
+          transformCode = `
+    const { ${destructure}, ...baseParams } = params ?? {};
+    const includeSpec = ${paramName} ? { ${key}: ${paramName} } : ${JSON.stringify(method.includeSpec)};
+    return this.post<${method.returnType}>(\`\${this.resource}/list\`, { ...baseParams, include: includeSpec });`;
+        }
+      } else {
+        transformCode = `
+    return this.post<${method.returnType}>(\`\${this.resource}/list\`, { ...params, include: ${JSON.stringify(method.includeSpec)} });`;
+      }
       includeMethodsCode += `
   /**
    * List ${table.name} records with included related ${relationshipDesc}
-   * @param params - Query parameters (where, orderBy, order, limit, offset)
+   * @param params - Query parameters (where, orderBy, order, limit, offset) and include options
    * @returns Paginated results with nested ${method.path.join(" and ")} included
    */
-  async ${method.name}(${baseParams}): Promise<${method.returnType}> {
-    return this.post<${method.returnType}>(\`\${this.resource}/list\`, { ...params, include: ${JSON.stringify(method.includeSpec)} });
+  async ${method.name}(params?: ${paramsType}): Promise<${method.returnType}> {${transformCode}
   }
 `;
     }
@@ -3402,7 +3580,7 @@ ${hasJsonbColumns ? `  /**
    * @param params.where - Filter conditions using operators like $eq, $gt, $in, $like, etc.
    * @param params.orderBy - Column(s) to sort by
    * @param params.order - Sort direction(s): "asc" or "desc"
-   * @param params.limit - Maximum number of records to return (default: 50, max: 100)
+   * @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 data, total count, and hasMore flag
@@ -3431,7 +3609,7 @@ ${hasJsonbColumns ? `  /**
    * @param params.where - Filter conditions using operators like $eq, $gt, $in, $like, etc.
    * @param params.orderBy - Column(s) to sort by
    * @param params.order - Sort direction(s): "asc" or "desc"
-   * @param params.limit - Maximum number of records to return (default: 50, max: 100)
+   * @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 data, total count, and hasMore flag
@@ -3768,6 +3946,13 @@ type Graph = typeof RELATION_GRAPH;
 type TableName = keyof Graph;
 type IncludeSpec = any;
 
+type RelationOptions = {
+  limit?: number;
+  offset?: number;
+  orderBy?: string;
+  order?: "asc" | "desc";
+};
+
 // Debug helpers (enabled with SDK_DEBUG=1)
 const DEBUG = process.env.SDK_DEBUG === "1" || process.env.SDK_DEBUG === "true";
 const log = {
@@ -3869,14 +4054,43 @@ 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.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 !== 'limit' && k !== 'offset' && k !== 'orderBy' && k !== 'order'
+            );
+            if (nonOptionKeys.length > 0) {
+              childSpec = {};
+              for (const k of nonOptionKeys) {
+                childSpec[k] = specValue[k];
+              }
+            }
+          }
+        }
+
         try {
-          await loadManyToMany(table, target, rel.via as string, rows, key);
+          await loadManyToMany(table, target, rel.via as string, rows, key, options);
         } catch (e: any) {
           log.error("loadManyToMany failed", { table, key, via: rel.via, target }, e?.message ?? e);
           for (const r of rows) r[key] = [];
         }
-        // Recurse if nested include specified
-        const childSpec = s[key] && typeof s[key] === "object" ? s[key] : undefined;
+
         if (childSpec) {
           const children = rows.flatMap(r => (r[key] ?? []));
           try {
@@ -3890,13 +4104,43 @@ 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.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 !== 'limit' && k !== 'offset' && k !== 'orderBy' && k !== 'order'
+            );
+            if (nonOptionKeys.length > 0) {
+              childSpec = {};
+              for (const k of nonOptionKeys) {
+                childSpec[k] = specValue[k];
+              }
+            }
+          }
+        }
+
         try {
-          await loadOneToMany(table, target, rows, key);
+          await loadOneToMany(table, target, rows, key, options);
         } catch (e: any) {
           log.error("loadOneToMany failed", { table, key, target }, e?.message ?? e);
           for (const r of rows) r[key] = [];
         }
-        const childSpec = s[key] && typeof s[key] === "object" ? s[key] : undefined;
+
         if (childSpec) {
           const children = rows.flatMap(r => (r[key] ?? []));
           try {
@@ -3984,7 +4228,7 @@ export async function loadIncludes(
     }
   }
 
-  async function loadOneToMany(curr: TableName, target: TableName, rows: any[], key: string) {
+  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);
     if (!fk) { for (const r of rows) r[key] = []; return; }
@@ -3995,18 +4239,50 @@ export async function loadIncludes(
 
     const where = buildOrAndPredicate(fk.from, tuples.length, 1);
     const params = tuples.flat();
-    const sql = \`SELECT * FROM "\${target}" WHERE \${where}\`;
-    log.debug("oneToMany SQL", { curr, target, key, sql, paramsCount: params.length });
+
+    // Build SQL with optional ORDER BY, LIMIT, OFFSET
+    let sql = \`SELECT * FROM "\${target}" WHERE \${where}\`;
+
+    // If limit/offset are needed, use window functions to limit per parent
+    if (options.limit !== undefined || options.offset !== undefined) {
+      const orderByClause = options.orderBy
+        ? \`ORDER BY "\${options.orderBy}" \${options.order === 'desc' ? 'DESC' : 'ASC'}\`
+        : 'ORDER BY (SELECT NULL)';
+
+      const partitionCols = fk.from.map((c: string) => \`"\${c}"\`).join(', ');
+      const offset = options.offset ?? 0;
+      const limit = options.limit ?? 999999999;
+
+      sql = \`
+        SELECT * FROM (
+          SELECT *, ROW_NUMBER() OVER (PARTITION BY \${partitionCols} \${orderByClause}) as __rn
+          FROM "\${target}"
+          WHERE \${where}
+        ) __sub
+        WHERE __rn > \${offset} AND __rn <= \${offset + limit}
+      \`;
+    } else if (options.orderBy) {
+      // Just ORDER BY without limit/offset
+      sql += \` ORDER BY "\${options.orderBy}" \${options.order === 'desc' ? 'DESC' : 'ASC'}\`;
+    }
+
+    log.debug("oneToMany SQL", { curr, target, key, sql, paramsCount: params.length, options });
     const { rows: children } = await pg.query(sql, params);
 
-    const groups = groupByTuple(children, fk.from);
+    // Remove __rn column if it exists
+    const cleanChildren = children.map((row: any) => {
+      const { __rn, ...rest } = row;
+      return rest;
+    });
+
+    const groups = groupByTuple(cleanChildren, fk.from);
     for (const r of rows) {
       const keyStr = JSON.stringify(pkCols.map((c: string) => r[c]));
       r[key] = groups.get(keyStr) ?? [];
     }
   }
 
-  async function loadManyToMany(curr: TableName, target: TableName, via: string, rows: any[], key: string) {
+  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);
@@ -4016,31 +4292,83 @@ export async function loadIncludes(
     const tuples = distinctTuples(rows, pkCols).filter(t => t.every((v: any) => v != null));
     if (!tuples.length) { for (const r of rows) r[key] = []; return; }
 
-    // 1) Load junction rows for current parents
     const whereVia = buildOrAndPredicate(toCurr.from, tuples.length, 1);
-    const sqlVia = \`SELECT * FROM "\${via}" WHERE \${whereVia}\`;
-    const paramsVia = tuples.flat();
-    log.debug("manyToMany junction SQL", { curr, target, via, key, sql: sqlVia, paramsCount: paramsVia.length });
-    const { rows: jrows } = await pg.query(sqlVia, paramsVia);
-
-    if (!jrows.length) { for (const r of rows) r[key] = []; return; }
+    const params = tuples.flat();
 
-    // 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 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);
+    // If we have limit/offset/orderBy, use a JOIN with window functions
+    if (options.limit !== undefined || options.offset !== undefined || options.orderBy) {
+      const orderByClause = options.orderBy
+        ? \`ORDER BY t."\${options.orderBy}" \${options.order === 'desc' ? 'DESC' : 'ASC'}\`
+        : 'ORDER BY (SELECT NULL)';
+
+      const partitionCols = toCurr.from.map((c: string) => \`j."\${c}"\`).join(', ');
+      const offset = options.offset ?? 0;
+      const limit = options.limit ?? 999999999;
+
+      const targetPkCols = (PKS as any)[target] as string[];
+      const joinConditions = toTarget.from.map((jCol: string, i: number) => {
+        return \`j."\${jCol}" = t."\${targetPkCols[i]}"\`;
+      }).join(' AND ');
+
+      const sql = \`
+        SELECT __numbered.*
+        FROM (
+          SELECT t.*,
+                 ROW_NUMBER() OVER (PARTITION BY \${partitionCols} \${orderByClause}) as __rn,
+                 \${toCurr.from.map((c: string) => \`j."\${c}"\`).join(' || \\',\\' || ')} as __parent_fk
+          FROM "\${via}" j
+          INNER JOIN "\${target}" t ON \${joinConditions}
+          WHERE \${whereVia}
+        ) __numbered
+        WHERE __numbered.__rn > \${offset} AND __numbered.__rn <= \${offset + limit}
+      \`;
+
+      log.debug("manyToMany SQL with options", { curr, target, via, key, sql, paramsCount: params.length, options });
+      const { rows: results } = await pg.query(sql, params);
+
+      // Clean and group results
+      const cleanResults = results.map((row: any) => {
+        const { __rn, __parent_fk, ...rest } = row;
+        return { ...rest, __parent_fk };
+      });
 
-    const tIdx = indexByTuple(targets, (PKS as any)[target]);
+      const grouped = new Map<string, any[]>();
+      for (const row of cleanResults) {
+        const { __parent_fk, ...cleanRow } = row;
+        const arr = grouped.get(__parent_fk) ?? [];
+        arr.push(cleanRow);
+        grouped.set(__parent_fk, arr);
+      }
 
-    // 3) Group junction rows by current pk tuple, map to target rows
-    const byCurr = groupByTuple(jrows, toCurr.from);
-    for (const r of rows) {
-      const currKey = JSON.stringify(pkCols.map((c: string) => r[c]));
-      const j = byCurr.get(currKey) ?? [];
-      r[key] = j.map(jr => tIdx.get(JSON.stringify(toTarget.from.map((c: string) => jr[c])))).filter(Boolean);
+      for (const r of rows) {
+        const currKey = pkCols.map((c: string) => r[c]).join(',');
+        r[key] = grouped.get(currKey) ?? [];
+      }
+    } else {
+      // Original logic without options
+      const sqlVia = \`SELECT * FROM "\${via}" WHERE \${whereVia}\`;
+      log.debug("manyToMany junction SQL", { curr, target, via, key, sql: sqlVia, paramsCount: params.length });
+      const { rows: jrows } = await pg.query(sqlVia, params);
+
+      if (!jrows.length) { for (const r of rows) r[key] = []; return; }
+
+      // 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 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);
+
+      const tIdx = indexByTuple(targets, (PKS as any)[target]);
+
+      // 3) Group junction rows by current pk tuple, map to target rows
+      const byCurr = groupByTuple(jrows, toCurr.from);
+      for (const r of rows) {
+        const currKey = JSON.stringify(pkCols.map((c: string) => r[c]));
+        const j = byCurr.get(currKey) ?? [];
+        r[key] = j.map(jr => tIdx.get(JSON.stringify(toTarget.from.map((c: string) => jr[c])))).filter(Boolean);
+      }
     }
   }
 }
@@ -4060,7 +4388,11 @@ function tsTypeFor(pgType, opts, enums) {
   if (t === "bool" || t === "boolean")
     return "boolean";
   if (t === "int2" || t === "int4" || t === "int8" || t === "float4" || t === "float8" || t === "numeric") {
-    return opts.numericMode === "number" ? "number" : "string";
+    if (opts.numericMode === "number")
+      return "number";
+    if (opts.numericMode === "string")
+      return "string";
+    return t === "int2" || t === "int4" || t === "float4" || t === "float8" ? "number" : "string";
   }
   if (t === "date" || t.startsWith("timestamp"))
     return "string";
@@ -6265,10 +6597,11 @@ async function generate(configPath) {
     console.log(`[Index] About to process ${Object.keys(model.tables || {}).length} tables for generation`);
   }
   for (const table of Object.values(model.tables)) {
-    const typesSrc = emitTypes(table, { numericMode: "string" }, model.enums);
+    const numericMode = cfg.numericMode ?? "auto";
+    const typesSrc = emitTypes(table, { numericMode }, model.enums);
     files.push({ path: join(serverDir, "types", `${table.name}.ts`), content: typesSrc });
     files.push({ path: join(clientDir, "types", `${table.name}.ts`), content: typesSrc });
-    const zodSrc = emitZod(table, { numericMode: "string" }, model.enums);
+    const zodSrc = emitZod(table, { numericMode }, model.enums);
     files.push({ path: join(serverDir, "zod", `${table.name}.ts`), content: zodSrc });
     files.push({ path: join(clientDir, "zod", `${table.name}.ts`), content: zodSrc });
     const paramsZodSrc = emitParamsZod(table, graph);

package/dist/emit-types.d.ts

@@ -1,4 +1,4 @@
 import type { Table } from "./introspect";
 export declare function emitTypes(table: Table, opts: {
-    numericMode: "string" | "number";
+    numericMode: "string" | "number" | "auto";
 }, enums: Record<string, string[]>): string;

package/dist/emit-zod.d.ts

@@ -1,4 +1,4 @@
 import type { Table } from "./introspect";
 export declare function emitZod(table: Table, opts: {
-    numericMode: "string" | "number";
+    numericMode: "string" | "number" | "auto";
 }, enums: Record<string, string[]>): string;

package/dist/index.js

@@ -1909,7 +1909,7 @@ function emitIncludeSpec(graph) {
 `;
     for (const [relKey, edge] of entries) {
       if (edge.kind === "many") {
-        out += `  ${relKey}?: boolean | { include?: ${toPascal(edge.target)}IncludeSpec; limit?: number; offset?: number; };
+        out += `  ${relKey}?: boolean | { include?: ${toPascal(edge.target)}IncludeSpec; limit?: number; offset?: number; orderBy?: string; order?: "asc" | "desc"; };
 `;
       } else {
         out += `  ${relKey}?: boolean | ${toPascal(edge.target)}IncludeSpec;
@@ -1978,10 +1978,20 @@ function emitZod(table, opts, enums) {
       return `z.string()`;
     if (t === "bool" || t === "boolean")
       return `z.boolean()`;
-    if (t === "int2" || t === "int4" || t === "int8")
-      return opts.numericMode === "number" ? `z.number()` : `z.string()`;
-    if (t === "numeric" || t === "float4" || t === "float8")
-      return opts.numericMode === "number" ? `z.number()` : `z.string()`;
+    if (t === "int2" || t === "int4" || t === "int8") {
+      if (opts.numericMode === "number")
+        return `z.number()`;
+      if (opts.numericMode === "string")
+        return `z.string()`;
+      return t === "int2" || t === "int4" ? `z.number()` : `z.string()`;
+    }
+    if (t === "numeric" || t === "float4" || t === "float8") {
+      if (opts.numericMode === "number")
+        return `z.number()`;
+      if (opts.numericMode === "string")
+        return `z.string()`;
+      return t === "float4" || t === "float8" ? `z.number()` : `z.string()`;
+    }
     if (t === "jsonb" || t === "json")
       return `z.unknown()`;
     if (t === "date" || t.startsWith("timestamp"))
@@ -2354,6 +2364,24 @@ function isJsonbType(pgType) {
   const t = pgType.toLowerCase();
   return t === "json" || t === "jsonb";
 }
+function toIncludeParamName(relationKey) {
+  return `${relationKey}Include`;
+}
+function analyzeIncludeSpec(includeSpec) {
+  const keys = Object.keys(includeSpec);
+  if (keys.length > 1) {
+    return { type: "parallel", keys };
+  }
+  const key = keys[0];
+  if (!key) {
+    return { type: "single", keys: [] };
+  }
+  const value = includeSpec[key];
+  if (typeof value === "object" && value !== null) {
+    return { type: "nested", keys: [key], nestedKey: key, nestedValue: value };
+  }
+  return { type: "single", keys: [key] };
+}
 function emitClient(table, graph, opts, model) {
   const Type = pascal(table.name);
   const ext = opts.useJsExtensions ? ".js" : "";
@@ -2392,39 +2420,157 @@ 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?: Where<Select${Type}>; orderBy?: string | string[]; order?: "asc" | "desc" | ("asc" | "desc")[]; }, "include">`;
+    const pattern = analyzeIncludeSpec(method.includeSpec);
     const relationshipDesc = method.path.map((p, i) => {
       const isLast = i === method.path.length - 1;
       const relation = method.isMany[i] ? "many" : "one";
       return isLast ? p : `${p} -> `;
     }).join("");
+    let paramsType = "";
+    const includeParamNames = [];
+    if (pattern.type === "single") {
+      const key = pattern.keys[0];
+      if (key) {
+        const paramName = toIncludeParamName(key);
+        includeParamNames.push(paramName);
+        paramsType = `{
+    limit?: number;
+    offset?: number;
+    where?: Where<Select${Type}>;
+    orderBy?: string | string[];
+    order?: "asc" | "desc" | ("asc" | "desc")[];
+    ${paramName}?: {
+      orderBy?: string | string[];
+      order?: "asc" | "desc";
+      limit?: number;
+      offset?: number;
+    };
+  }`;
+      }
+    } else if (pattern.type === "parallel") {
+      const includeParams = pattern.keys.map((key) => {
+        const paramName = toIncludeParamName(key);
+        includeParamNames.push(paramName);
+        return `${paramName}?: {
+      orderBy?: string | string[];
+      order?: "asc" | "desc";
+      limit?: number;
+      offset?: number;
+    }`;
+      }).join(`;
+    `);
+      paramsType = `{
+    limit?: number;
+    offset?: number;
+    where?: Where<Select${Type}>;
+    orderBy?: string | string[];
+    order?: "asc" | "desc" | ("asc" | "desc")[];
+    ${includeParams};
+  }`;
+    } else if (pattern.type === "nested" && pattern.nestedKey) {
+      const paramName = toIncludeParamName(pattern.nestedKey);
+      includeParamNames.push(paramName);
+      paramsType = `{
+    limit?: number;
+    offset?: number;
+    where?: Where<Select${Type}>;
+    orderBy?: string | string[];
+    order?: "asc" | "desc" | ("asc" | "desc")[];
+    ${paramName}?: {
+      orderBy?: string | string[];
+      order?: "asc" | "desc";
+      limit?: number;
+      offset?: number;
+      include?: any;
+    };
+  }`;
+    }
     if (isGetByPk) {
       const pkWhere = hasCompositePk ? `{ ${safePk.map((col) => `${col}: pk.${col}`).join(", ")} }` : `{ ${safePk[0] || "id"}: pk }`;
       const baseReturnType = method.returnType.replace(" | null", "");
+      let transformCode = "";
+      if (includeParamNames.length > 0) {
+        const destructure = includeParamNames.map((name) => name).join(", ");
+        if (pattern.type === "single") {
+          const key = pattern.keys[0];
+          const paramName = includeParamNames[0];
+          transformCode = `
+    const { ${destructure} } = params ?? {};
+    const includeSpec = ${paramName} ? { ${key}: ${paramName} } : ${JSON.stringify(method.includeSpec)};`;
+        } else if (pattern.type === "parallel") {
+          const includeSpecCode = pattern.keys.map((key, idx) => {
+            const paramName = includeParamNames[idx];
+            return `${key}: ${paramName} ?? true`;
+          }).join(", ");
+          transformCode = `
+    const { ${destructure} } = params ?? {};
+    const includeSpec = { ${includeSpecCode} };`;
+        } else if (pattern.type === "nested" && pattern.nestedKey) {
+          const key = pattern.nestedKey;
+          const paramName = includeParamNames[0];
+          transformCode = `
+    const { ${destructure} } = params ?? {};
+    const includeSpec = ${paramName} ? { ${key}: ${paramName} } : ${JSON.stringify(method.includeSpec)};`;
+        }
+      } else {
+        transformCode = `
+    const includeSpec = ${JSON.stringify(method.includeSpec)};`;
+      }
       includeMethodsCode += `
   /**
    * Get a ${table.name} record by primary key with included related ${relationshipDesc}
    * @param pk - The primary key value${hasCompositePk ? "s" : ""}
+   * @param params - Optional include options
    * @returns The record with nested ${method.path.join(" and ")} if found, null otherwise
    */
-  async ${method.name}(pk: ${pkType}): Promise<${method.returnType}> {
+  async ${method.name}(pk: ${pkType}, params?: ${paramsType}): Promise<${method.returnType}> {${transformCode}
     const results = await this.post<PaginatedResponse<${baseReturnType}>>(\`\${this.resource}/list\`, {
       where: ${pkWhere},
-      include: ${JSON.stringify(method.includeSpec)},
+      include: includeSpec,
       limit: 1
     });
     return (results.data[0] as ${baseReturnType}) ?? null;
   }
 `;
     } else {
+      let transformCode = "";
+      if (includeParamNames.length > 0) {
+        const destructure = includeParamNames.map((name) => name).join(", ");
+        if (pattern.type === "single") {
+          const key = pattern.keys[0];
+          const paramName = includeParamNames[0];
+          transformCode = `
+    const { ${destructure}, ...baseParams } = params ?? {};
+    const includeSpec = ${paramName} ? { ${key}: ${paramName} } : ${JSON.stringify(method.includeSpec)};
+    return this.post<${method.returnType}>(\`\${this.resource}/list\`, { ...baseParams, include: includeSpec });`;
+        } else if (pattern.type === "parallel") {
+          const includeSpecCode = pattern.keys.map((key, idx) => {
+            const paramName = includeParamNames[idx];
+            return `${key}: ${paramName} ?? true`;
+          }).join(", ");
+          transformCode = `
+    const { ${destructure}, ...baseParams } = params ?? {};
+    const includeSpec = { ${includeSpecCode} };
+    return this.post<${method.returnType}>(\`\${this.resource}/list\`, { ...baseParams, include: includeSpec });`;
+        } else if (pattern.type === "nested" && pattern.nestedKey) {
+          const key = pattern.nestedKey;
+          const paramName = includeParamNames[0];
+          transformCode = `
+    const { ${destructure}, ...baseParams } = params ?? {};
+    const includeSpec = ${paramName} ? { ${key}: ${paramName} } : ${JSON.stringify(method.includeSpec)};
+    return this.post<${method.returnType}>(\`\${this.resource}/list\`, { ...baseParams, include: includeSpec });`;
+        }
+      } else {
+        transformCode = `
+    return this.post<${method.returnType}>(\`\${this.resource}/list\`, { ...params, include: ${JSON.stringify(method.includeSpec)} });`;
+      }
       includeMethodsCode += `
   /**
    * List ${table.name} records with included related ${relationshipDesc}
-   * @param params - Query parameters (where, orderBy, order, limit, offset)
+   * @param params - Query parameters (where, orderBy, order, limit, offset) and include options
    * @returns Paginated results with nested ${method.path.join(" and ")} included
    */
-  async ${method.name}(${baseParams}): Promise<${method.returnType}> {
-    return this.post<${method.returnType}>(\`\${this.resource}/list\`, { ...params, include: ${JSON.stringify(method.includeSpec)} });
+  async ${method.name}(params?: ${paramsType}): Promise<${method.returnType}> {${transformCode}
   }
 `;
     }
@@ -2501,7 +2647,7 @@ ${hasJsonbColumns ? `  /**
    * @param params.where - Filter conditions using operators like $eq, $gt, $in, $like, etc.
    * @param params.orderBy - Column(s) to sort by
    * @param params.order - Sort direction(s): "asc" or "desc"
-   * @param params.limit - Maximum number of records to return (default: 50, max: 100)
+   * @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 data, total count, and hasMore flag
@@ -2530,7 +2676,7 @@ ${hasJsonbColumns ? `  /**
    * @param params.where - Filter conditions using operators like $eq, $gt, $in, $like, etc.
    * @param params.orderBy - Column(s) to sort by
    * @param params.order - Sort direction(s): "asc" or "desc"
-   * @param params.limit - Maximum number of records to return (default: 50, max: 100)
+   * @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 data, total count, and hasMore flag
@@ -2867,6 +3013,13 @@ type Graph = typeof RELATION_GRAPH;
 type TableName = keyof Graph;
 type IncludeSpec = any;
 
+type RelationOptions = {
+  limit?: number;
+  offset?: number;
+  orderBy?: string;
+  order?: "asc" | "desc";
+};
+
 // Debug helpers (enabled with SDK_DEBUG=1)
 const DEBUG = process.env.SDK_DEBUG === "1" || process.env.SDK_DEBUG === "true";
 const log = {
@@ -2968,14 +3121,43 @@ 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.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 !== 'limit' && k !== 'offset' && k !== 'orderBy' && k !== 'order'
+            );
+            if (nonOptionKeys.length > 0) {
+              childSpec = {};
+              for (const k of nonOptionKeys) {
+                childSpec[k] = specValue[k];
+              }
+            }
+          }
+        }
+
         try {
-          await loadManyToMany(table, target, rel.via as string, rows, key);
+          await loadManyToMany(table, target, rel.via as string, rows, key, options);
         } catch (e: any) {
           log.error("loadManyToMany failed", { table, key, via: rel.via, target }, e?.message ?? e);
           for (const r of rows) r[key] = [];
         }
-        // Recurse if nested include specified
-        const childSpec = s[key] && typeof s[key] === "object" ? s[key] : undefined;
+
         if (childSpec) {
           const children = rows.flatMap(r => (r[key] ?? []));
           try {
@@ -2989,13 +3171,43 @@ 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.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 !== 'limit' && k !== 'offset' && k !== 'orderBy' && k !== 'order'
+            );
+            if (nonOptionKeys.length > 0) {
+              childSpec = {};
+              for (const k of nonOptionKeys) {
+                childSpec[k] = specValue[k];
+              }
+            }
+          }
+        }
+
         try {
-          await loadOneToMany(table, target, rows, key);
+          await loadOneToMany(table, target, rows, key, options);
         } catch (e: any) {
           log.error("loadOneToMany failed", { table, key, target }, e?.message ?? e);
           for (const r of rows) r[key] = [];
         }
-        const childSpec = s[key] && typeof s[key] === "object" ? s[key] : undefined;
+
         if (childSpec) {
           const children = rows.flatMap(r => (r[key] ?? []));
           try {
@@ -3083,7 +3295,7 @@ export async function loadIncludes(
     }
   }
 
-  async function loadOneToMany(curr: TableName, target: TableName, rows: any[], key: string) {
+  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);
     if (!fk) { for (const r of rows) r[key] = []; return; }
@@ -3094,18 +3306,50 @@ export async function loadIncludes(
 
     const where = buildOrAndPredicate(fk.from, tuples.length, 1);
     const params = tuples.flat();
-    const sql = \`SELECT * FROM "\${target}" WHERE \${where}\`;
-    log.debug("oneToMany SQL", { curr, target, key, sql, paramsCount: params.length });
+
+    // Build SQL with optional ORDER BY, LIMIT, OFFSET
+    let sql = \`SELECT * FROM "\${target}" WHERE \${where}\`;
+
+    // If limit/offset are needed, use window functions to limit per parent
+    if (options.limit !== undefined || options.offset !== undefined) {
+      const orderByClause = options.orderBy
+        ? \`ORDER BY "\${options.orderBy}" \${options.order === 'desc' ? 'DESC' : 'ASC'}\`
+        : 'ORDER BY (SELECT NULL)';
+
+      const partitionCols = fk.from.map((c: string) => \`"\${c}"\`).join(', ');
+      const offset = options.offset ?? 0;
+      const limit = options.limit ?? 999999999;
+
+      sql = \`
+        SELECT * FROM (
+          SELECT *, ROW_NUMBER() OVER (PARTITION BY \${partitionCols} \${orderByClause}) as __rn
+          FROM "\${target}"
+          WHERE \${where}
+        ) __sub
+        WHERE __rn > \${offset} AND __rn <= \${offset + limit}
+      \`;
+    } else if (options.orderBy) {
+      // Just ORDER BY without limit/offset
+      sql += \` ORDER BY "\${options.orderBy}" \${options.order === 'desc' ? 'DESC' : 'ASC'}\`;
+    }
+
+    log.debug("oneToMany SQL", { curr, target, key, sql, paramsCount: params.length, options });
     const { rows: children } = await pg.query(sql, params);
 
-    const groups = groupByTuple(children, fk.from);
+    // Remove __rn column if it exists
+    const cleanChildren = children.map((row: any) => {
+      const { __rn, ...rest } = row;
+      return rest;
+    });
+
+    const groups = groupByTuple(cleanChildren, fk.from);
     for (const r of rows) {
       const keyStr = JSON.stringify(pkCols.map((c: string) => r[c]));
       r[key] = groups.get(keyStr) ?? [];
     }
   }
 
-  async function loadManyToMany(curr: TableName, target: TableName, via: string, rows: any[], key: string) {
+  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);
@@ -3115,31 +3359,83 @@ export async function loadIncludes(
     const tuples = distinctTuples(rows, pkCols).filter(t => t.every((v: any) => v != null));
     if (!tuples.length) { for (const r of rows) r[key] = []; return; }
 
-    // 1) Load junction rows for current parents
     const whereVia = buildOrAndPredicate(toCurr.from, tuples.length, 1);
-    const sqlVia = \`SELECT * FROM "\${via}" WHERE \${whereVia}\`;
-    const paramsVia = tuples.flat();
-    log.debug("manyToMany junction SQL", { curr, target, via, key, sql: sqlVia, paramsCount: paramsVia.length });
-    const { rows: jrows } = await pg.query(sqlVia, paramsVia);
-
-    if (!jrows.length) { for (const r of rows) r[key] = []; return; }
+    const params = tuples.flat();
 
-    // 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 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);
+    // If we have limit/offset/orderBy, use a JOIN with window functions
+    if (options.limit !== undefined || options.offset !== undefined || options.orderBy) {
+      const orderByClause = options.orderBy
+        ? \`ORDER BY t."\${options.orderBy}" \${options.order === 'desc' ? 'DESC' : 'ASC'}\`
+        : 'ORDER BY (SELECT NULL)';
+
+      const partitionCols = toCurr.from.map((c: string) => \`j."\${c}"\`).join(', ');
+      const offset = options.offset ?? 0;
+      const limit = options.limit ?? 999999999;
+
+      const targetPkCols = (PKS as any)[target] as string[];
+      const joinConditions = toTarget.from.map((jCol: string, i: number) => {
+        return \`j."\${jCol}" = t."\${targetPkCols[i]}"\`;
+      }).join(' AND ');
+
+      const sql = \`
+        SELECT __numbered.*
+        FROM (
+          SELECT t.*,
+                 ROW_NUMBER() OVER (PARTITION BY \${partitionCols} \${orderByClause}) as __rn,
+                 \${toCurr.from.map((c: string) => \`j."\${c}"\`).join(' || \\',\\' || ')} as __parent_fk
+          FROM "\${via}" j
+          INNER JOIN "\${target}" t ON \${joinConditions}
+          WHERE \${whereVia}
+        ) __numbered
+        WHERE __numbered.__rn > \${offset} AND __numbered.__rn <= \${offset + limit}
+      \`;
+
+      log.debug("manyToMany SQL with options", { curr, target, via, key, sql, paramsCount: params.length, options });
+      const { rows: results } = await pg.query(sql, params);
+
+      // Clean and group results
+      const cleanResults = results.map((row: any) => {
+        const { __rn, __parent_fk, ...rest } = row;
+        return { ...rest, __parent_fk };
+      });
 
-    const tIdx = indexByTuple(targets, (PKS as any)[target]);
+      const grouped = new Map<string, any[]>();
+      for (const row of cleanResults) {
+        const { __parent_fk, ...cleanRow } = row;
+        const arr = grouped.get(__parent_fk) ?? [];
+        arr.push(cleanRow);
+        grouped.set(__parent_fk, arr);
+      }
 
-    // 3) Group junction rows by current pk tuple, map to target rows
-    const byCurr = groupByTuple(jrows, toCurr.from);
-    for (const r of rows) {
-      const currKey = JSON.stringify(pkCols.map((c: string) => r[c]));
-      const j = byCurr.get(currKey) ?? [];
-      r[key] = j.map(jr => tIdx.get(JSON.stringify(toTarget.from.map((c: string) => jr[c])))).filter(Boolean);
+      for (const r of rows) {
+        const currKey = pkCols.map((c: string) => r[c]).join(',');
+        r[key] = grouped.get(currKey) ?? [];
+      }
+    } else {
+      // Original logic without options
+      const sqlVia = \`SELECT * FROM "\${via}" WHERE \${whereVia}\`;
+      log.debug("manyToMany junction SQL", { curr, target, via, key, sql: sqlVia, paramsCount: params.length });
+      const { rows: jrows } = await pg.query(sqlVia, params);
+
+      if (!jrows.length) { for (const r of rows) r[key] = []; return; }
+
+      // 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 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);
+
+      const tIdx = indexByTuple(targets, (PKS as any)[target]);
+
+      // 3) Group junction rows by current pk tuple, map to target rows
+      const byCurr = groupByTuple(jrows, toCurr.from);
+      for (const r of rows) {
+        const currKey = JSON.stringify(pkCols.map((c: string) => r[c]));
+        const j = byCurr.get(currKey) ?? [];
+        r[key] = j.map(jr => tIdx.get(JSON.stringify(toTarget.from.map((c: string) => jr[c])))).filter(Boolean);
+      }
     }
   }
 }
@@ -3159,7 +3455,11 @@ function tsTypeFor(pgType, opts, enums) {
   if (t === "bool" || t === "boolean")
     return "boolean";
   if (t === "int2" || t === "int4" || t === "int8" || t === "float4" || t === "float8" || t === "numeric") {
-    return opts.numericMode === "number" ? "number" : "string";
+    if (opts.numericMode === "number")
+      return "number";
+    if (opts.numericMode === "string")
+      return "string";
+    return t === "int2" || t === "int4" || t === "float4" || t === "float8" ? "number" : "string";
   }
   if (t === "date" || t.startsWith("timestamp"))
     return "string";
@@ -5364,10 +5664,11 @@ async function generate(configPath) {
     console.log(`[Index] About to process ${Object.keys(model.tables || {}).length} tables for generation`);
   }
   for (const table of Object.values(model.tables)) {
-    const typesSrc = emitTypes(table, { numericMode: "string" }, model.enums);
+    const numericMode = cfg.numericMode ?? "auto";
+    const typesSrc = emitTypes(table, { numericMode }, model.enums);
     files.push({ path: join(serverDir, "types", `${table.name}.ts`), content: typesSrc });
     files.push({ path: join(clientDir, "types", `${table.name}.ts`), content: typesSrc });
-    const zodSrc = emitZod(table, { numericMode: "string" }, model.enums);
+    const zodSrc = emitZod(table, { numericMode }, model.enums);
     files.push({ path: join(serverDir, "zod", `${table.name}.ts`), content: zodSrc });
     files.push({ path: join(clientDir, "zod", `${table.name}.ts`), content: zodSrc });
     const paramsZodSrc = emitParamsZod(table, graph);

package/dist/types.d.ts

@@ -24,6 +24,7 @@ export interface Config {
     };
     softDeleteColumn?: string | null;
     dateType?: "date" | "string";
+    numericMode?: "string" | "number" | "auto";
     includeMethodsDepth?: number;
     skipJunctionTables?: boolean;
     serverFramework?: "hono" | "express" | "fastify";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "postgresdk",
-  "version": "0.16.10",
+  "version": "0.16.13",
   "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 test/test-where-clause.test.ts && bun test test/test-where-or-and.test.ts && bun test:gen-with-tests && bun test:pull && bun test:enums && bun test:typecheck && bun test:drizzle-e2e",
+    "test": "bun test:init && bun test:gen && bun test test/test-where-clause.test.ts && bun test test/test-where-or-and.test.ts && bun test test/test-nested-include-options.test.ts && bun test test/test-include-methods-with-options.test.ts && bun test:gen-with-tests && bun test:pull && bun test:enums && bun test:typecheck && bun test:drizzle-e2e && bun test test/test-numeric-mode-integration.test.ts",
     "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",