keryx 0.18.0 → 0.19.0

package/index.ts

@@ -34,11 +34,13 @@ export type { WebServer } from "./servers/web";
 export { buildProgram } from "./util/cli";
 export { deepMerge, loadFromEnvIfSet } from "./util/config";
 export { globLoader } from "./util/glob";
+export { type PaginatedResult, paginate } from "./util/pagination";
 export { toMarkdown } from "./util/toMarkdown";
 export type { DbOrTransaction, Transaction } from "./util/transaction";
 export { withTransaction } from "./util/transaction";
 export {
   isSecret,
+  paginationInputs,
   secret,
   zBooleanFromString,
   zIdOrModel,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keryx",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "module": "index.ts",
   "type": "module",
   "license": "MIT",

package/util/pagination.ts

@@ -0,0 +1,54 @@
+/**
+ * Standardized pagination response envelope.
+ */
+export interface PaginatedResult<T> {
+  data: T[];
+  pagination: {
+    page: number;
+    limit: number;
+    total: number;
+    pages: number;
+  };
+}
+
+/**
+ * Applies pagination to a Drizzle select query and returns a standardized envelope.
+ *
+ * Runs the data query (with LIMIT/OFFSET) and a COUNT query in parallel for efficiency.
+ * The caller provides both queries separately so they can use different joins or WHERE
+ * clauses for the count (e.g., skipping expensive JOINs that don't affect the total).
+ *
+ * @param query - A Drizzle select query builder that has not yet had `.limit()` or
+ *   `.offset()` applied. Must support chaining `.limit(n).offset(n)`.
+ * @param countQuery - A promise resolving to `[{ count: number }]`. Typically built with
+ *   `db.select({ count: count() }).from(table).where(...)`.
+ * @param params - Object with `page` (1-indexed) and `limit`, matching the output of
+ *   `paginationInputs()`.
+ * @returns A `PaginatedResult<T>` containing the `data` array and `pagination` metadata.
+ */
+export async function paginate<T>(
+  query: {
+    limit: (n: number) => { offset: (n: number) => PromiseLike<T[]> };
+  },
+  countQuery: PromiseLike<{ count: number }[]>,
+  params: { page: number; limit: number },
+): Promise<PaginatedResult<T>> {
+  const offset = (params.page - 1) * params.limit;
+
+  const [data, countResult] = await Promise.all([
+    query.limit(params.limit).offset(offset),
+    countQuery,
+  ]);
+
+  const total = Number(countResult[0]?.count ?? 0);
+
+  return {
+    data,
+    pagination: {
+      page: params.page,
+      limit: params.limit,
+      total,
+      pages: Math.ceil(total / params.limit),
+    },
+  };
+}

package/util/zodMixins.ts

@@ -46,6 +46,39 @@ export function zBooleanFromString() {
   });
 }
 
+/**
+ * Creates a Zod schema for pagination inputs with sensible defaults.
+ * Returns `{ page, limit }` where `page` is 1-indexed.
+ *
+ * @param options - Optional overrides for default values and bounds.
+ * @param options.defaultLimit - Default number of items per page (default: 25).
+ * @param options.maxLimit - Maximum allowed items per page (default: 100).
+ * @returns A Zod object schema with `page` and `limit` fields.
+ */
+export function paginationInputs(options?: {
+  defaultLimit?: number;
+  maxLimit?: number;
+}) {
+  const defaultLimit = options?.defaultLimit ?? 25;
+  const maxLimit = options?.maxLimit ?? 100;
+
+  return z.object({
+    page: z.coerce
+      .number()
+      .int()
+      .min(1)
+      .default(1)
+      .describe("Page number (1-indexed)"),
+    limit: z.coerce
+      .number()
+      .int()
+      .min(1)
+      .max(maxLimit)
+      .default(defaultLimit)
+      .describe("Number of items per page"),
+  });
+}
+
 // Type for Drizzle tables with an id column
 type TableWithId = { id: any; $inferSelect: any };