postgresdk 0.12.0 → 0.13.0

package/README.md

@@ -7,7 +7,7 @@ Generate a typed server/client SDK from your PostgreSQL database schema.
 ## Features
 
 - 🚀 **Instant SDK Generation** - Point at your PostgreSQL database and get a complete SDK
-- 🔒 **Type Safety** - Full TypeScript types derived from your database schema  
+- 🔒 **Type Safety** - Full TypeScript types derived from your database schema (including enum types)
 - ✅ **Runtime Validation** - Zod schemas for request/response validation
 - 🔗 **Smart Relationships** - Automatic handling of 1:N and M:N relationships with eager loading
 - 🔐 **Built-in Auth** - API key and JWT authentication
@@ -121,7 +121,8 @@ const user = await sdk.users.create({ name: "Bob", email: "bob@example.com" });
 
 // Read
 const user = await sdk.users.getByPk(123);
-const users = await sdk.users.list();
+const result = await sdk.users.list();
+const users = result.data;  // Array of users
 
 // Update  
 const updated = await sdk.users.update(123, { name: "Robert" });
@@ -136,17 +137,19 @@ Automatically handles relationships with the `include` parameter:
 
 ```typescript
 // 1:N relationship - Get authors with their books
-const authors = await sdk.authors.list({
+const authorsResult = await sdk.authors.list({
   include: { books: true }
 });
+const authors = authorsResult.data;
 
 // M:N relationship - Get books with their tags
-const books = await sdk.books.list({
+const booksResult = await sdk.books.list({
   include: { tags: true }
 });
+const books = booksResult.data;
 
 // Nested includes - Get authors with books and their tags
-const authors = await sdk.authors.list({
+const nestedResult = await sdk.authors.list({
   include: {
     books: {
       include: {
@@ -155,13 +158,15 @@ const authors = await sdk.authors.list({
     }
   }
 });
+const authorsWithBooksAndTags = nestedResult.data;
 ```
 
 ### Filtering & Pagination
 
+All `list()` methods return pagination metadata:
+
 ```typescript
-// Simple equality filtering with single-column sorting
-const users = await sdk.users.list({
+const result = await sdk.users.list({
   where: { status: "active" },
   orderBy: "created_at",
   order: "desc",
@@ -169,6 +174,17 @@ const users = await sdk.users.list({
   offset: 40
 });
 
+// Access results
+result.data;       // User[] - array of records
+result.total;      // number - total matching records
+result.limit;      // number - page size used
+result.offset;     // number - offset used
+result.hasMore;    // boolean - more pages available
+
+// Calculate pagination info
+const totalPages = Math.ceil(result.total / result.limit);
+const currentPage = Math.floor(result.offset / result.limit) + 1;
+
 // Multi-column sorting
 const sorted = await sdk.users.list({
   orderBy: ["status", "created_at"],
@@ -184,6 +200,7 @@ const filtered = await sdk.users.list({
     deleted_at: { $is: null }              // NULL checks
   }
 });
+// filtered.total respects WHERE clause for accurate counts
 
 // OR logic - match any condition
 const results = await sdk.users.list({
@@ -221,6 +238,17 @@ const nested = await sdk.users.list({
     ]
   }
 });
+
+// Pagination with filtered results
+let allResults = [];
+let offset = 0;
+const limit = 50;
+do {
+  const page = await sdk.users.list({ where: { status: 'active' }, limit, offset });
+  allResults = allResults.concat(page.data);
+  offset += limit;
+  if (!page.hasMore) break;
+} while (true);
 ```
 
 See the generated SDK documentation for all available operators: `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$like`, `$ilike`, `$is`, `$isNot`, `$or`, `$and`.

package/dist/cli.js

@@ -578,7 +578,7 @@ function generateIncludeMethods(table, graph, opts, allTables) {
         path: newPath,
         isMany: newIsMany,
         targets: newTargets,
-        returnType: `(${buildReturnType(baseTableName, newPath, newIsMany, newTargets, graph)})[]`,
+        returnType: `{ data: (${buildReturnType(baseTableName, newPath, newIsMany, newTargets, graph)})[]; total: number; limit: number; offset: number; hasMore: boolean; }`,
         includeSpec: buildIncludeSpec(newPath)
       });
       methods.push({
@@ -618,7 +618,7 @@ function generateIncludeMethods(table, graph, opts, allTables) {
               path: combinedPath,
               isMany: [edge1.kind === "many", edge2.kind === "many"],
               targets: [edge1.target, edge2.target],
-              returnType: `(Select${pascal(baseTableName)} & { ${type1}; ${type2} })[]`,
+              returnType: `{ data: (Select${pascal(baseTableName)} & { ${type1}; ${type2} })[]; total: number; limit: number; offset: number; hasMore: boolean; }`,
               includeSpec: { [key1]: true, [key2]: true }
             });
             methods.push({
@@ -780,14 +780,18 @@ function generateResourceWithSDK(table, model, graph, config) {
   const basePath = `/v1/${tableName}`;
   const hasSinglePK = table.pk.length === 1;
   const pkField = hasSinglePK ? table.pk[0] : "id";
+  const enums = model.enums || {};
   const sdkMethods = [];
   const endpoints = [];
   sdkMethods.push({
     name: "list",
-    signature: `list(params?: ListParams): Promise<${Type}[]>`,
-    description: `List ${tableName} with filtering, sorting, and pagination`,
+    signature: `list(params?: ListParams): Promise<{ data: ${Type}[]; total: number; limit: number; offset: number; hasMore: boolean; }>`,
+    description: `List ${tableName} with filtering, sorting, and pagination. Returns paginated results with metadata.`,
     example: `// Get all ${tableName}
-const items = await sdk.${tableName}.list();
+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({
@@ -796,15 +800,19 @@ const filtered = await sdk.${tableName}.list({
   where: { ${table.columns[0]?.name || "field"}: { $like: '%search%' } },
   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;`,
     correspondsTo: `GET ${basePath}`
   });
   endpoints.push({
     method: "GET",
     path: basePath,
-    description: `List all ${tableName} records`,
-    queryParameters: generateQueryParams(table),
-    responseBody: `${Type}[]`
+    description: `List all ${tableName} records with pagination metadata`,
+    queryParameters: generateQueryParams(table, enums),
+    responseBody: `{ data: ${Type}[]; total: number; limit: number; offset: number; hasMore: boolean; }`
   });
   if (hasSinglePK) {
     sdkMethods.push({
@@ -894,7 +902,10 @@ console.log('Deleted:', deleted);`,
     }, 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 results = await sdk.${tableName}.${method.name}();
+      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}({
@@ -911,7 +922,7 @@ const filtered = await sdk.${tableName}.${method.name}({
       });
     }
   }
-  const fields = table.columns.map((col) => generateFieldContract(col, table));
+  const fields = table.columns.map((col) => generateFieldContract(col, table, enums));
   return {
     name: Type,
     tableName,
@@ -926,11 +937,11 @@ const filtered = await sdk.${tableName}.${method.name}({
     fields
   };
 }
-function generateFieldContract(column, table) {
+function generateFieldContract(column, table, enums) {
   const field = {
     name: column.name,
-    type: postgresTypeToJsonType(column.pgType),
-    tsType: postgresTypeToTsType(column),
+    type: postgresTypeToJsonType(column.pgType, enums),
+    tsType: postgresTypeToTsType(column, enums),
     required: !column.nullable && !column.hasDefault,
     description: generateFieldDescription(column, table)
   };
@@ -943,16 +954,41 @@ function generateFieldContract(column, table) {
   }
   return field;
 }
-function postgresTypeToTsType(column) {
+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 (column.pgType) {
+    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";
@@ -970,9 +1006,16 @@ function postgresTypeToTsType(column) {
         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[]";
       default:
         return "string";
@@ -1054,7 +1097,7 @@ function generateExampleValue(column) {
       return `'example value'`;
   }
 }
-function generateQueryParams(table) {
+function generateQueryParams(table, enums) {
   const params = {
     limit: "number - Max records to return (default: 50)",
     offset: "number - Records to skip",
@@ -1065,7 +1108,7 @@ function generateQueryParams(table) {
   for (const col of table.columns) {
     if (filterCount >= 3)
       break;
-    const type = postgresTypeToJsonType(col.pgType);
+    const type = postgresTypeToJsonType(col.pgType, enums);
     params[col.name] = `${type} - Filter by ${col.name}`;
     if (type === "string") {
       params[`${col.name}_like`] = `string - Search in ${col.name}`;
@@ -1078,15 +1121,27 @@ function generateQueryParams(table) {
   params["..."] = "Additional filters for all fields";
   return params;
 }
-function postgresTypeToJsonType(pgType) {
-  switch (pgType) {
+function postgresTypeToJsonType(pgType, enums) {
+  const t = pgType.toLowerCase();
+  if (enums[t]) {
+    return t;
+  }
+  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";
@@ -1104,9 +1159,16 @@ function postgresTypeToJsonType(pgType) {
       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[]";
     default:
       return "string";
@@ -2566,23 +2628,28 @@ export const buildWithFor = (t: TableName) =>
 
 // src/emit-zod.ts
 init_utils();
-function emitZod(table, opts) {
+function emitZod(table, opts, enums) {
   const Type = pascal(table.name);
   const zFor = (pg) => {
-    if (pg === "uuid")
+    const t = pg.toLowerCase();
+    if (enums[t]) {
+      const values = enums[t].map((v) => `"${v}"`).join(", ");
+      return `z.enum([${values}])`;
+    }
+    if (t === "uuid")
       return `z.string()`;
-    if (pg === "bool" || pg === "boolean")
+    if (t === "bool" || t === "boolean")
       return `z.boolean()`;
-    if (pg === "int2" || pg === "int4" || pg === "int8")
+    if (t === "int2" || t === "int4" || t === "int8")
       return opts.numericMode === "number" ? `z.number()` : `z.string()`;
-    if (pg === "numeric" || pg === "float4" || pg === "float8")
+    if (t === "numeric" || t === "float4" || t === "float8")
       return opts.numericMode === "number" ? `z.number()` : `z.string()`;
-    if (pg === "jsonb" || pg === "json")
+    if (t === "jsonb" || t === "json")
       return `z.unknown()`;
-    if (pg === "date" || pg.startsWith("timestamp"))
+    if (t === "date" || t.startsWith("timestamp"))
       return `z.string()`;
-    if (pg.startsWith("_"))
-      return `z.array(${zFor(pg.slice(1))})`;
+    if (t.startsWith("_"))
+      return `z.array(${zFor(t.slice(1))})`;
     return `z.string()`;
   };
   const selectFields = table.columns.map((c) => {
@@ -2711,6 +2778,13 @@ const listSchema = z.object({
   order: z.union([z.enum(["asc", "desc"]), z.array(z.enum(["asc", "desc"]))]).optional()
 });
 
+/**
+ * Register all CRUD routes for the ${fileTableName} table
+ * @param app - Hono application instance
+ * @param deps - Dependencies including database client and optional request hook
+ * @param deps.pg - PostgreSQL client with query method
+ * @param deps.onRequest - Optional hook that runs before each request (for audit logging, RLS, etc.)
+ */
 export function register${Type}Routes(app: Hono, deps: { pg: { query: (text: string, params?: any[]) => Promise<{ rows: any[] }> }, onRequest?: (c: Context, pg: { query: (text: string, params?: any[]) => Promise<{ rows: any[] }> }) => Promise<void> }) {
   const base = "/v1/${fileTableName}";
   
@@ -2790,34 +2864,50 @@ ${hasAuth ? `
     if (result.needsIncludes && result.includeSpec) {
       try {
         const stitched = await loadIncludes(
-          "${fileTableName}", 
-          result.data, 
-          result.includeSpec, 
-          deps.pg, 
+          "${fileTableName}",
+          result.data,
+          result.includeSpec,
+          deps.pg,
           ${opts.includeMethodsDepth}
         );
-        return c.json(stitched);
+        return c.json({
+          data: stitched,
+          total: result.total,
+          limit: result.limit,
+          offset: result.offset,
+          hasMore: result.hasMore
+        });
       } catch (e: any) {
         const strict = process.env.SDK_STRICT_INCLUDE === "1";
         if (strict) {
-          return c.json({ 
-            error: "include-stitch-failed", 
+          return c.json({
+            error: "include-stitch-failed",
             message: e?.message,
             ...(process.env.SDK_DEBUG === "1" ? { stack: e?.stack } : {})
           }, 500);
         }
         // Non-strict: return base rows with error metadata
-        return c.json({ 
-          data: result.data, 
-          includeError: { 
+        return c.json({
+          data: result.data,
+          total: result.total,
+          limit: result.limit,
+          offset: result.offset,
+          hasMore: result.hasMore,
+          includeError: {
             message: e?.message,
             ...(process.env.SDK_DEBUG === "1" ? { stack: e?.stack } : {})
           }
         }, 200);
       }
     }
-    
-    return c.json(result.data, result.status as any);
+
+    return c.json({
+      data: result.data,
+      total: result.total,
+      limit: result.limit,
+      offset: result.offset,
+      hasMore: result.hasMore
+    }, result.status as any);
   });
 
   // UPDATE
@@ -2898,21 +2988,36 @@ function emitClient(table, graph, opts, model) {
   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 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("");
     if (isGetByPk) {
       const pkWhere = hasCompositePk ? `{ ${safePk.map((col) => `${col}: pk.${col}`).join(", ")} }` : `{ ${safePk[0] || "id"}: pk }`;
       const baseReturnType = method.returnType.replace(" | null", "");
       includeMethodsCode += `
+  /**
+   * Get a ${table.name} record by primary key with included related ${relationshipDesc}
+   * @param pk - The primary key value${hasCompositePk ? "s" : ""}
+   * @returns The record with nested ${method.path.join(" and ")} if found, null otherwise
+   */
   async ${method.name}(pk: ${pkType}): Promise<${method.returnType}> {
-    const results = await this.post<${baseReturnType}[]>(\`\${this.resource}/list\`, { 
+    const results = await this.post<{ data: ${baseReturnType}[]; total: number; limit: number; offset: number; hasMore: boolean; }>(\`\${this.resource}/list\`, {
       where: ${pkWhere},
       include: ${JSON.stringify(method.includeSpec)},
-      limit: 1 
+      limit: 1
     });
-    return (results[0] as ${baseReturnType}) ?? null;
+    return (results.data[0] as ${baseReturnType}) ?? null;
   }
 `;
     } else {
       includeMethodsCode += `
+  /**
+   * List ${table.name} records with included related ${relationshipDesc}
+   * @param params - Query parameters (where, orderBy, order, limit, offset)
+   * @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)} });
   }
@@ -2939,15 +3044,36 @@ ${otherTableImports.join(`
 export class ${Type}Client extends BaseClient {
   private readonly resource = "/v1/${table.name}";
 
+  /**
+   * Create a new ${table.name} record
+   * @param data - The data to insert
+   * @returns The created record
+   */
   async create(data: Insert${Type}): Promise<Select${Type}> {
     return this.post<Select${Type}>(this.resource, data);
   }
 
+  /**
+   * Get a ${table.name} record by primary key
+   * @param pk - The primary key value${hasCompositePk ? "s" : ""}
+   * @returns The record if found, null otherwise
+   */
   async getByPk(pk: ${pkType}): Promise<Select${Type} | null> {
     const path = ${pkPathExpr};
     return this.get<Select${Type} | null>(\`\${this.resource}/\${path}\`);
   }
 
+  /**
+   * List ${table.name} records with pagination and filtering
+   * @param params - Query parameters
+   * @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.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
+   */
   async list(params?: {
     include?: any;
     limit?: number;
@@ -2955,15 +3081,38 @@ export class ${Type}Client extends BaseClient {
     where?: Where<Select${Type}>;
     orderBy?: string | string[];
     order?: "asc" | "desc" | ("asc" | "desc")[];
-  }): Promise<Select${Type}[]> {
-    return this.post<Select${Type}[]>(\`\${this.resource}/list\`, params ?? {});
+  }): Promise<{
+    data: Select${Type}[];
+    total: number;
+    limit: number;
+    offset: number;
+    hasMore: boolean;
+  }> {
+    return this.post<{
+      data: Select${Type}[];
+      total: number;
+      limit: number;
+      offset: number;
+      hasMore: boolean;
+    }>(\`\${this.resource}/list\`, params ?? {});
   }
 
+  /**
+   * Update a ${table.name} record by primary key
+   * @param pk - The primary key value${hasCompositePk ? "s" : ""}
+   * @param patch - Partial data to update
+   * @returns The updated record if found, null otherwise
+   */
   async update(pk: ${pkType}, patch: Update${Type}): Promise<Select${Type} | null> {
     const path = ${pkPathExpr};
     return this.patch<Select${Type} | null>(\`\${this.resource}/\${path}\`, patch);
   }
 
+  /**
+   * Delete a ${table.name} record by primary key
+   * @param pk - The primary key value${hasCompositePk ? "s" : ""}
+   * @returns The deleted record if found, null otherwise
+   */
   async delete(pk: ${pkType}): Promise<Select${Type} | null> {
     const path = ${pkPathExpr};
     return this.del<Select${Type} | null>(\`\${this.resource}/\${path}\`);
@@ -3510,10 +3659,13 @@ export async function loadIncludes(
 }
 
 // src/emit-types.ts
-function tsTypeFor(pgType, opts) {
+function tsTypeFor(pgType, opts, enums) {
   const t = pgType.toLowerCase();
+  if (enums[t]) {
+    return enums[t].map((v) => `"${v}"`).join(" | ");
+  }
   if (t.startsWith("_"))
-    return `${tsTypeFor(t.slice(1), opts)}[]`;
+    return `(${tsTypeFor(t.slice(1), opts, enums)})[]`;
   if (t === "uuid")
     return "string";
   if (t === "bool" || t === "boolean")
@@ -3528,17 +3680,17 @@ function tsTypeFor(pgType, opts) {
   return "string";
 }
 var pascal2 = (s) => s.split(/[_\s-]+/).map((w) => w?.[0] ? w[0].toUpperCase() + w.slice(1) : "").join("");
-function emitTypes(table, opts) {
+function emitTypes(table, opts, enums) {
   const Type = pascal2(table.name);
   const insertFields = table.columns.map((col) => {
-    const base = tsTypeFor(col.pgType, opts);
+    const base = tsTypeFor(col.pgType, opts, enums);
     const optional = col.hasDefault || col.nullable ? "?" : "";
     const valueType = col.nullable ? `${base} | null` : base;
     return `  ${col.name}${optional}: ${valueType};`;
   }).join(`
 `);
   const selectFields = table.columns.map((col) => {
-    const base = tsTypeFor(col.pgType, opts);
+    const base = tsTypeFor(col.pgType, opts, enums);
     const valueType = col.nullable ? `${base} | null` : base;
     return `  ${col.name}: ${valueType};`;
   }).join(`
@@ -3551,12 +3703,25 @@ function emitTypes(table, opts) {
  *
  * To make changes, modify your schema or configuration and regenerate.
  */
+
+/**
+ * Type for inserting a new ${table.name} record.
+ * Fields with defaults or nullable columns are optional.
+ */
 export type Insert${Type} = {
 ${insertFields}
 };
 
+/**
+ * Type for updating an existing ${table.name} record.
+ * All fields are optional, allowing partial updates.
+ */
 export type Update${Type} = Partial<Insert${Type}>;
 
+/**
+ * Type representing a ${table.name} record from the database.
+ * All fields are included as returned by SELECT queries.
+ */
 export type Select${Type} = {
 ${selectFields}
 };
@@ -4289,7 +4454,7 @@ function buildWhereClause(
 export async function listRecords(
   ctx: OperationContext,
   params: { where?: any; limit?: number; offset?: number; include?: any; orderBy?: string | string[]; order?: "asc" | "desc" | ("asc" | "desc")[] }
-): Promise<{ data?: any; error?: string; issues?: any; needsIncludes?: boolean; includeSpec?: any; status: number }> {
+): Promise<{ data?: any; total?: number; limit?: number; offset?: number; hasMore?: boolean; error?: string; issues?: any; needsIncludes?: boolean; includeSpec?: any; status: number }> {
   try {
     const { where: whereClause, limit = 50, offset = 0, include, orderBy, order } = params;
 
@@ -4334,20 +4499,34 @@ export async function listRecords(
     const offsetParam = \`$\${paramIndex + 1}\`;
     const allParams = [...whereParams, limit, offset];
 
+    // Get total count for pagination
+    const countText = \`SELECT COUNT(*) FROM "\${ctx.table}" \${whereSQL}\`;
+    log.debug(\`LIST \${ctx.table} COUNT SQL:\`, countText, "params:", whereParams);
+    const countResult = await ctx.pg.query(countText, whereParams);
+    const total = parseInt(countResult.rows[0].count, 10);
+
+    // Get paginated data
     const text = \`SELECT * FROM "\${ctx.table}" \${whereSQL} \${orderBySQL} LIMIT \${limitParam} OFFSET \${offsetParam}\`;
     log.debug(\`LIST \${ctx.table} SQL:\`, text, "params:", allParams);
 
     const { rows } = await ctx.pg.query(text, allParams);
 
-    if (!include) {
-      log.debug(\`LIST \${ctx.table} rows:\`, rows.length);
-      return { data: rows, status: 200 };
-    }
+    // Calculate hasMore
+    const hasMore = offset + limit < total;
+
+    const metadata = {
+      data: rows,
+      total,
+      limit,
+      offset,
+      hasMore,
+      needsIncludes: !!include,
+      includeSpec: include,
+      status: 200
+    };
 
-    // Include logic will be handled by the include-loader
-    // For now, just return the rows with a note that includes need to be applied
-    log.debug(\`LIST \${ctx.table} include spec:\`, include);
-    return { data: rows, needsIncludes: true, includeSpec: include, status: 200 };
+    log.debug(\`LIST \${ctx.table} result: \${rows.length} rows, \${total} total, hasMore=\${hasMore}\`);
+    return metadata;
   } catch (e: any) {
     log.error(\`LIST \${ctx.table} error:\`, e?.stack ?? e);
     return {
@@ -4489,8 +4668,11 @@ describe('${Type} SDK Operations', () => {
   });
   
   it('should list ${tableName} relationships', async () => {
-    const list = await sdk.${tableName}.list({ limit: 10 });
-    expect(Array.isArray(list)).toBe(true);
+    const result = await sdk.${tableName}.list({ limit: 10 });
+    expect(result).toBeDefined();
+    expect(Array.isArray(result.data)).toBe(true);
+    expect(typeof result.total).toBe('number');
+    expect(typeof result.hasMore).toBe('boolean');
   });
 });
 `;
@@ -5126,8 +5308,11 @@ function generateTestCases(table, sampleData, updateData, hasForeignKeys = false
   });
   
   it('should list ${table.name}', async () => {
-    const list = await sdk.${table.name}.list({ limit: 10 });
-    expect(Array.isArray(list)).toBe(true);
+    const result = await sdk.${table.name}.list({ limit: 10 });
+    expect(result).toBeDefined();
+    expect(Array.isArray(result.data)).toBe(true);
+    expect(typeof result.total).toBe('number');
+    expect(typeof result.hasMore).toBe('boolean');
   });
   
   ${hasData && hasSinglePK ? `it('should get ${table.name} by id', async () => {
@@ -5276,10 +5461,10 @@ 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" });
+    const typesSrc = emitTypes(table, { numericMode: "string" }, 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" });
+    const zodSrc = emitZod(table, { numericMode: "string" }, 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";
-}): string;
+}, 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";
-}): string;
+}, enums: Record<string, string[]>): string;

package/dist/index.js

@@ -577,7 +577,7 @@ function generateIncludeMethods(table, graph, opts, allTables) {
         path: newPath,
         isMany: newIsMany,
         targets: newTargets,
-        returnType: `(${buildReturnType(baseTableName, newPath, newIsMany, newTargets, graph)})[]`,
+        returnType: `{ data: (${buildReturnType(baseTableName, newPath, newIsMany, newTargets, graph)})[]; total: number; limit: number; offset: number; hasMore: boolean; }`,
         includeSpec: buildIncludeSpec(newPath)
       });
       methods.push({
@@ -617,7 +617,7 @@ function generateIncludeMethods(table, graph, opts, allTables) {
               path: combinedPath,
               isMany: [edge1.kind === "many", edge2.kind === "many"],
               targets: [edge1.target, edge2.target],
-              returnType: `(Select${pascal(baseTableName)} & { ${type1}; ${type2} })[]`,
+              returnType: `{ data: (Select${pascal(baseTableName)} & { ${type1}; ${type2} })[]; total: number; limit: number; offset: number; hasMore: boolean; }`,
               includeSpec: { [key1]: true, [key2]: true }
             });
             methods.push({
@@ -779,14 +779,18 @@ function generateResourceWithSDK(table, model, graph, config) {
   const basePath = `/v1/${tableName}`;
   const hasSinglePK = table.pk.length === 1;
   const pkField = hasSinglePK ? table.pk[0] : "id";
+  const enums = model.enums || {};
   const sdkMethods = [];
   const endpoints = [];
   sdkMethods.push({
     name: "list",
-    signature: `list(params?: ListParams): Promise<${Type}[]>`,
-    description: `List ${tableName} with filtering, sorting, and pagination`,
+    signature: `list(params?: ListParams): Promise<{ data: ${Type}[]; total: number; limit: number; offset: number; hasMore: boolean; }>`,
+    description: `List ${tableName} with filtering, sorting, and pagination. Returns paginated results with metadata.`,
     example: `// Get all ${tableName}
-const items = await sdk.${tableName}.list();
+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({
@@ -795,15 +799,19 @@ const filtered = await sdk.${tableName}.list({
   where: { ${table.columns[0]?.name || "field"}: { $like: '%search%' } },
   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;`,
     correspondsTo: `GET ${basePath}`
   });
   endpoints.push({
     method: "GET",
     path: basePath,
-    description: `List all ${tableName} records`,
-    queryParameters: generateQueryParams(table),
-    responseBody: `${Type}[]`
+    description: `List all ${tableName} records with pagination metadata`,
+    queryParameters: generateQueryParams(table, enums),
+    responseBody: `{ data: ${Type}[]; total: number; limit: number; offset: number; hasMore: boolean; }`
   });
   if (hasSinglePK) {
     sdkMethods.push({
@@ -893,7 +901,10 @@ console.log('Deleted:', deleted);`,
     }, 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 results = await sdk.${tableName}.${method.name}();
+      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}({
@@ -910,7 +921,7 @@ const filtered = await sdk.${tableName}.${method.name}({
       });
     }
   }
-  const fields = table.columns.map((col) => generateFieldContract(col, table));
+  const fields = table.columns.map((col) => generateFieldContract(col, table, enums));
   return {
     name: Type,
     tableName,
@@ -925,11 +936,11 @@ const filtered = await sdk.${tableName}.${method.name}({
     fields
   };
 }
-function generateFieldContract(column, table) {
+function generateFieldContract(column, table, enums) {
   const field = {
     name: column.name,
-    type: postgresTypeToJsonType(column.pgType),
-    tsType: postgresTypeToTsType(column),
+    type: postgresTypeToJsonType(column.pgType, enums),
+    tsType: postgresTypeToTsType(column, enums),
     required: !column.nullable && !column.hasDefault,
     description: generateFieldDescription(column, table)
   };
@@ -942,16 +953,41 @@ function generateFieldContract(column, table) {
   }
   return field;
 }
-function postgresTypeToTsType(column) {
+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 (column.pgType) {
+    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";
@@ -969,9 +1005,16 @@ function postgresTypeToTsType(column) {
         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[]";
       default:
         return "string";
@@ -1053,7 +1096,7 @@ function generateExampleValue(column) {
       return `'example value'`;
   }
 }
-function generateQueryParams(table) {
+function generateQueryParams(table, enums) {
   const params = {
     limit: "number - Max records to return (default: 50)",
     offset: "number - Records to skip",
@@ -1064,7 +1107,7 @@ function generateQueryParams(table) {
   for (const col of table.columns) {
     if (filterCount >= 3)
       break;
-    const type = postgresTypeToJsonType(col.pgType);
+    const type = postgresTypeToJsonType(col.pgType, enums);
     params[col.name] = `${type} - Filter by ${col.name}`;
     if (type === "string") {
       params[`${col.name}_like`] = `string - Search in ${col.name}`;
@@ -1077,15 +1120,27 @@ function generateQueryParams(table) {
   params["..."] = "Additional filters for all fields";
   return params;
 }
-function postgresTypeToJsonType(pgType) {
-  switch (pgType) {
+function postgresTypeToJsonType(pgType, enums) {
+  const t = pgType.toLowerCase();
+  if (enums[t]) {
+    return t;
+  }
+  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";
@@ -1103,9 +1158,16 @@ function postgresTypeToJsonType(pgType) {
       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[]";
     default:
       return "string";
@@ -1806,23 +1868,28 @@ export const buildWithFor = (t: TableName) =>
 
 // src/emit-zod.ts
 init_utils();
-function emitZod(table, opts) {
+function emitZod(table, opts, enums) {
   const Type = pascal(table.name);
   const zFor = (pg) => {
-    if (pg === "uuid")
+    const t = pg.toLowerCase();
+    if (enums[t]) {
+      const values = enums[t].map((v) => `"${v}"`).join(", ");
+      return `z.enum([${values}])`;
+    }
+    if (t === "uuid")
       return `z.string()`;
-    if (pg === "bool" || pg === "boolean")
+    if (t === "bool" || t === "boolean")
       return `z.boolean()`;
-    if (pg === "int2" || pg === "int4" || pg === "int8")
+    if (t === "int2" || t === "int4" || t === "int8")
       return opts.numericMode === "number" ? `z.number()` : `z.string()`;
-    if (pg === "numeric" || pg === "float4" || pg === "float8")
+    if (t === "numeric" || t === "float4" || t === "float8")
       return opts.numericMode === "number" ? `z.number()` : `z.string()`;
-    if (pg === "jsonb" || pg === "json")
+    if (t === "jsonb" || t === "json")
       return `z.unknown()`;
-    if (pg === "date" || pg.startsWith("timestamp"))
+    if (t === "date" || t.startsWith("timestamp"))
       return `z.string()`;
-    if (pg.startsWith("_"))
-      return `z.array(${zFor(pg.slice(1))})`;
+    if (t.startsWith("_"))
+      return `z.array(${zFor(t.slice(1))})`;
     return `z.string()`;
   };
   const selectFields = table.columns.map((c) => {
@@ -1951,6 +2018,13 @@ const listSchema = z.object({
   order: z.union([z.enum(["asc", "desc"]), z.array(z.enum(["asc", "desc"]))]).optional()
 });
 
+/**
+ * Register all CRUD routes for the ${fileTableName} table
+ * @param app - Hono application instance
+ * @param deps - Dependencies including database client and optional request hook
+ * @param deps.pg - PostgreSQL client with query method
+ * @param deps.onRequest - Optional hook that runs before each request (for audit logging, RLS, etc.)
+ */
 export function register${Type}Routes(app: Hono, deps: { pg: { query: (text: string, params?: any[]) => Promise<{ rows: any[] }> }, onRequest?: (c: Context, pg: { query: (text: string, params?: any[]) => Promise<{ rows: any[] }> }) => Promise<void> }) {
   const base = "/v1/${fileTableName}";
   
@@ -2030,34 +2104,50 @@ ${hasAuth ? `
     if (result.needsIncludes && result.includeSpec) {
       try {
         const stitched = await loadIncludes(
-          "${fileTableName}", 
-          result.data, 
-          result.includeSpec, 
-          deps.pg, 
+          "${fileTableName}",
+          result.data,
+          result.includeSpec,
+          deps.pg,
           ${opts.includeMethodsDepth}
         );
-        return c.json(stitched);
+        return c.json({
+          data: stitched,
+          total: result.total,
+          limit: result.limit,
+          offset: result.offset,
+          hasMore: result.hasMore
+        });
       } catch (e: any) {
         const strict = process.env.SDK_STRICT_INCLUDE === "1";
         if (strict) {
-          return c.json({ 
-            error: "include-stitch-failed", 
+          return c.json({
+            error: "include-stitch-failed",
             message: e?.message,
             ...(process.env.SDK_DEBUG === "1" ? { stack: e?.stack } : {})
           }, 500);
         }
         // Non-strict: return base rows with error metadata
-        return c.json({ 
-          data: result.data, 
-          includeError: { 
+        return c.json({
+          data: result.data,
+          total: result.total,
+          limit: result.limit,
+          offset: result.offset,
+          hasMore: result.hasMore,
+          includeError: {
             message: e?.message,
             ...(process.env.SDK_DEBUG === "1" ? { stack: e?.stack } : {})
           }
         }, 200);
       }
     }
-    
-    return c.json(result.data, result.status as any);
+
+    return c.json({
+      data: result.data,
+      total: result.total,
+      limit: result.limit,
+      offset: result.offset,
+      hasMore: result.hasMore
+    }, result.status as any);
   });
 
   // UPDATE
@@ -2138,21 +2228,36 @@ function emitClient(table, graph, opts, model) {
   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 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("");
     if (isGetByPk) {
       const pkWhere = hasCompositePk ? `{ ${safePk.map((col) => `${col}: pk.${col}`).join(", ")} }` : `{ ${safePk[0] || "id"}: pk }`;
       const baseReturnType = method.returnType.replace(" | null", "");
       includeMethodsCode += `
+  /**
+   * Get a ${table.name} record by primary key with included related ${relationshipDesc}
+   * @param pk - The primary key value${hasCompositePk ? "s" : ""}
+   * @returns The record with nested ${method.path.join(" and ")} if found, null otherwise
+   */
   async ${method.name}(pk: ${pkType}): Promise<${method.returnType}> {
-    const results = await this.post<${baseReturnType}[]>(\`\${this.resource}/list\`, { 
+    const results = await this.post<{ data: ${baseReturnType}[]; total: number; limit: number; offset: number; hasMore: boolean; }>(\`\${this.resource}/list\`, {
       where: ${pkWhere},
       include: ${JSON.stringify(method.includeSpec)},
-      limit: 1 
+      limit: 1
     });
-    return (results[0] as ${baseReturnType}) ?? null;
+    return (results.data[0] as ${baseReturnType}) ?? null;
   }
 `;
     } else {
       includeMethodsCode += `
+  /**
+   * List ${table.name} records with included related ${relationshipDesc}
+   * @param params - Query parameters (where, orderBy, order, limit, offset)
+   * @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)} });
   }
@@ -2179,15 +2284,36 @@ ${otherTableImports.join(`
 export class ${Type}Client extends BaseClient {
   private readonly resource = "/v1/${table.name}";
 
+  /**
+   * Create a new ${table.name} record
+   * @param data - The data to insert
+   * @returns The created record
+   */
   async create(data: Insert${Type}): Promise<Select${Type}> {
     return this.post<Select${Type}>(this.resource, data);
   }
 
+  /**
+   * Get a ${table.name} record by primary key
+   * @param pk - The primary key value${hasCompositePk ? "s" : ""}
+   * @returns The record if found, null otherwise
+   */
   async getByPk(pk: ${pkType}): Promise<Select${Type} | null> {
     const path = ${pkPathExpr};
     return this.get<Select${Type} | null>(\`\${this.resource}/\${path}\`);
   }
 
+  /**
+   * List ${table.name} records with pagination and filtering
+   * @param params - Query parameters
+   * @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.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
+   */
   async list(params?: {
     include?: any;
     limit?: number;
@@ -2195,15 +2321,38 @@ export class ${Type}Client extends BaseClient {
     where?: Where<Select${Type}>;
     orderBy?: string | string[];
     order?: "asc" | "desc" | ("asc" | "desc")[];
-  }): Promise<Select${Type}[]> {
-    return this.post<Select${Type}[]>(\`\${this.resource}/list\`, params ?? {});
+  }): Promise<{
+    data: Select${Type}[];
+    total: number;
+    limit: number;
+    offset: number;
+    hasMore: boolean;
+  }> {
+    return this.post<{
+      data: Select${Type}[];
+      total: number;
+      limit: number;
+      offset: number;
+      hasMore: boolean;
+    }>(\`\${this.resource}/list\`, params ?? {});
   }
 
+  /**
+   * Update a ${table.name} record by primary key
+   * @param pk - The primary key value${hasCompositePk ? "s" : ""}
+   * @param patch - Partial data to update
+   * @returns The updated record if found, null otherwise
+   */
   async update(pk: ${pkType}, patch: Update${Type}): Promise<Select${Type} | null> {
     const path = ${pkPathExpr};
     return this.patch<Select${Type} | null>(\`\${this.resource}/\${path}\`, patch);
   }
 
+  /**
+   * Delete a ${table.name} record by primary key
+   * @param pk - The primary key value${hasCompositePk ? "s" : ""}
+   * @returns The deleted record if found, null otherwise
+   */
   async delete(pk: ${pkType}): Promise<Select${Type} | null> {
     const path = ${pkPathExpr};
     return this.del<Select${Type} | null>(\`\${this.resource}/\${path}\`);
@@ -2750,10 +2899,13 @@ export async function loadIncludes(
 }
 
 // src/emit-types.ts
-function tsTypeFor(pgType, opts) {
+function tsTypeFor(pgType, opts, enums) {
   const t = pgType.toLowerCase();
+  if (enums[t]) {
+    return enums[t].map((v) => `"${v}"`).join(" | ");
+  }
   if (t.startsWith("_"))
-    return `${tsTypeFor(t.slice(1), opts)}[]`;
+    return `(${tsTypeFor(t.slice(1), opts, enums)})[]`;
   if (t === "uuid")
     return "string";
   if (t === "bool" || t === "boolean")
@@ -2768,17 +2920,17 @@ function tsTypeFor(pgType, opts) {
   return "string";
 }
 var pascal2 = (s) => s.split(/[_\s-]+/).map((w) => w?.[0] ? w[0].toUpperCase() + w.slice(1) : "").join("");
-function emitTypes(table, opts) {
+function emitTypes(table, opts, enums) {
   const Type = pascal2(table.name);
   const insertFields = table.columns.map((col) => {
-    const base = tsTypeFor(col.pgType, opts);
+    const base = tsTypeFor(col.pgType, opts, enums);
     const optional = col.hasDefault || col.nullable ? "?" : "";
     const valueType = col.nullable ? `${base} | null` : base;
     return `  ${col.name}${optional}: ${valueType};`;
   }).join(`
 `);
   const selectFields = table.columns.map((col) => {
-    const base = tsTypeFor(col.pgType, opts);
+    const base = tsTypeFor(col.pgType, opts, enums);
     const valueType = col.nullable ? `${base} | null` : base;
     return `  ${col.name}: ${valueType};`;
   }).join(`
@@ -2791,12 +2943,25 @@ function emitTypes(table, opts) {
  *
  * To make changes, modify your schema or configuration and regenerate.
  */
+
+/**
+ * Type for inserting a new ${table.name} record.
+ * Fields with defaults or nullable columns are optional.
+ */
 export type Insert${Type} = {
 ${insertFields}
 };
 
+/**
+ * Type for updating an existing ${table.name} record.
+ * All fields are optional, allowing partial updates.
+ */
 export type Update${Type} = Partial<Insert${Type}>;
 
+/**
+ * Type representing a ${table.name} record from the database.
+ * All fields are included as returned by SELECT queries.
+ */
 export type Select${Type} = {
 ${selectFields}
 };
@@ -3529,7 +3694,7 @@ function buildWhereClause(
 export async function listRecords(
   ctx: OperationContext,
   params: { where?: any; limit?: number; offset?: number; include?: any; orderBy?: string | string[]; order?: "asc" | "desc" | ("asc" | "desc")[] }
-): Promise<{ data?: any; error?: string; issues?: any; needsIncludes?: boolean; includeSpec?: any; status: number }> {
+): Promise<{ data?: any; total?: number; limit?: number; offset?: number; hasMore?: boolean; error?: string; issues?: any; needsIncludes?: boolean; includeSpec?: any; status: number }> {
   try {
     const { where: whereClause, limit = 50, offset = 0, include, orderBy, order } = params;
 
@@ -3574,20 +3739,34 @@ export async function listRecords(
     const offsetParam = \`$\${paramIndex + 1}\`;
     const allParams = [...whereParams, limit, offset];
 
+    // Get total count for pagination
+    const countText = \`SELECT COUNT(*) FROM "\${ctx.table}" \${whereSQL}\`;
+    log.debug(\`LIST \${ctx.table} COUNT SQL:\`, countText, "params:", whereParams);
+    const countResult = await ctx.pg.query(countText, whereParams);
+    const total = parseInt(countResult.rows[0].count, 10);
+
+    // Get paginated data
     const text = \`SELECT * FROM "\${ctx.table}" \${whereSQL} \${orderBySQL} LIMIT \${limitParam} OFFSET \${offsetParam}\`;
     log.debug(\`LIST \${ctx.table} SQL:\`, text, "params:", allParams);
 
     const { rows } = await ctx.pg.query(text, allParams);
 
-    if (!include) {
-      log.debug(\`LIST \${ctx.table} rows:\`, rows.length);
-      return { data: rows, status: 200 };
-    }
+    // Calculate hasMore
+    const hasMore = offset + limit < total;
+
+    const metadata = {
+      data: rows,
+      total,
+      limit,
+      offset,
+      hasMore,
+      needsIncludes: !!include,
+      includeSpec: include,
+      status: 200
+    };
 
-    // Include logic will be handled by the include-loader
-    // For now, just return the rows with a note that includes need to be applied
-    log.debug(\`LIST \${ctx.table} include spec:\`, include);
-    return { data: rows, needsIncludes: true, includeSpec: include, status: 200 };
+    log.debug(\`LIST \${ctx.table} result: \${rows.length} rows, \${total} total, hasMore=\${hasMore}\`);
+    return metadata;
   } catch (e: any) {
     log.error(\`LIST \${ctx.table} error:\`, e?.stack ?? e);
     return {
@@ -3729,8 +3908,11 @@ describe('${Type} SDK Operations', () => {
   });
   
   it('should list ${tableName} relationships', async () => {
-    const list = await sdk.${tableName}.list({ limit: 10 });
-    expect(Array.isArray(list)).toBe(true);
+    const result = await sdk.${tableName}.list({ limit: 10 });
+    expect(result).toBeDefined();
+    expect(Array.isArray(result.data)).toBe(true);
+    expect(typeof result.total).toBe('number');
+    expect(typeof result.hasMore).toBe('boolean');
   });
 });
 `;
@@ -4366,8 +4548,11 @@ function generateTestCases(table, sampleData, updateData, hasForeignKeys = false
   });
   
   it('should list ${table.name}', async () => {
-    const list = await sdk.${table.name}.list({ limit: 10 });
-    expect(Array.isArray(list)).toBe(true);
+    const result = await sdk.${table.name}.list({ limit: 10 });
+    expect(result).toBeDefined();
+    expect(Array.isArray(result.data)).toBe(true);
+    expect(typeof result.total).toBe('number');
+    expect(typeof result.hasMore).toBe('boolean');
   });
   
   ${hasData && hasSinglePK ? `it('should get ${table.name} by id', async () => {
@@ -4516,10 +4701,10 @@ 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" });
+    const typesSrc = emitTypes(table, { numericMode: "string" }, 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" });
+    const zodSrc = emitZod(table, { numericMode: "string" }, 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "postgresdk",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Generate a typed server/client SDK from a Postgres schema (includes, Zod, Hono).",
   "type": "module",
   "bin": {
@@ -22,11 +22,12 @@
   },
   "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: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:gen-with-tests && bun test:pull && bun test:enums && bun test:typecheck && bun test:drizzle-e2e",
     "test:init": "bun test/test-init.ts",
     "test:gen": "bun test/test-gen.ts",
     "test:gen-with-tests": "bun test/test-gen-with-tests.ts",
     "test:pull": "bun test/test-pull.ts",
+    "test:enums": "bun test/test-enums.ts",
     "test:typecheck": "bun test/test-typecheck.ts",
     "test:drizzle-e2e": "bun test/test-drizzle-e2e.ts",
     "typecheck": "tsc --noEmit",