orchid-pagination 1.0.0 → 2.1.0

package/README.md

@@ -18,8 +18,8 @@ import { paginateByPage } from "orchid-pagination"
 
 defineEventHandler(async (ctx) => {
   const query = db.user.where(conditions).order({ name: "ASC", id: "DESC" })
-  const params = getValidatedParams(ctx) // prepare object with { page?, size? }
-  const page = await paginateByPage(query, { pageSize: 10, maxPageSize: 1000 }, ctx.params)
+  const params = getValidatedParams(ctx) // prepare object with { page?, limit? }
+  const page = await paginateByPage(query, { limit: 10, maxLimit: 1000 }, params)
   return page
 })
 ```
@@ -29,17 +29,25 @@ Alternatively, pre-create the paginator:
 ```ts
 import { createPagePaginator } from "orchid-pagination"
 
-const paginate = createPagePaginator({ pageSize: 10, maxPageSize: 1000 })
+const paginate = createPagePaginator({ limit: 10, maxLimit: 1000 })
 
 defineEventHandler(async (ctx) => {
   const query = db.user.where(conditions).order({ name: "ASC", id: "DESC" })
-  const params = getValidatedParams(ctx) // prepare object with { page?, size? }
+  const params = getValidatedParams(ctx) // prepare object with { page?, limit? }
   const page = await paginate(query, params)
   return page
 })
 ```
 
-The page will have `items`, and possibly `nextPage` and/or `prevPage`.
+The page has `{ items, page, limit, offset, prevPage?, nextPage? }`.
+
+### No total count by default
+
+By default, this library does not run `COUNT(*)` queries, keeping pagination fast and lightweight.
+If a requested page is beyond the last page, the result contains an empty `items` array and keeps the requested page number unchanged.
+
+Set `total: true` to include `totalItems` and `totalPages` in the response.
+Pages beyond the last page are still left unchanged; to clamp them to the last available page, set `clampPage: true` together with `total: true`.
 
 ## Cursor pagination
 
@@ -48,8 +56,8 @@ import { paginateByCursor } from "orchid-pagination"
 
 defineEventHandler(async (ctx) => {
   const query = db.user.where(conditions).order({ name: "ASC", id: "DESC" })
-  const params = getValidatedParams(ctx) // prepare object with { cursor?, size? }
-  const page = await paginateByCursor(query, { pageSize: 10, maxPageSize: 1000 }, ctx.params)
+  const params = getValidatedParams(ctx) // prepare object with { cursor?, limit? }
+  const page = await paginateByCursor(query, { limit: 10, maxLimit: 1000 }, params)
   return page
 })
 ```
@@ -57,16 +65,59 @@ defineEventHandler(async (ctx) => {
 Alternatively, pre-create the paginator:
 
 ```ts
-import { createCursorPagination } from "orchid-pagination"
+import { createCursorPaginator } from "orchid-pagination"
 
-const paginate = createCursorPagination({ pageSize: 10, maxPageSize: 1000 })
+const paginate = createCursorPaginator({ limit: 10, maxLimit: 1000 })
 
 defineEventHandler(async (ctx) => {
   const query = db.user.where(conditions).order({ name: "ASC", id: "DESC" })
-  const params = getValidatedParams(ctx) // prepare object with { cursor?, size? }
+  const params = getValidatedParams(ctx) // prepare object with { cursor?, limit? }
   const page = await paginate(query, params)
   return page
 })
 ```
 
-The page will have `items`, and possibly `nextCursor` and/or `prevCursor` which should be sent in subsequent calls to paginate forth and back.
+The page has `{ items, limit, prevCursor?, nextCursor? }`.
+
+Cursor queries must be ordered.
+Include a deterministic tie-breaker, usually `id`.
+Treat cursors as opaque strings and pass them back unchanged.
+
+### Aliases and relations
+
+You can order by selected aliases or by relation paths:
+
+```ts
+const page = await paginateByCursor(
+  db.post
+    .select("id", "text", {
+      authorName: q => q.author.get("name"),
+    })
+    .order("authorName", { id: "DESC" }),
+  { limit: 10 },
+)
+```
+
+```ts
+const page = await paginateByCursor(
+  db.post
+    .select("id", "text", {
+      author: q => q.author.select("id", "name"),
+    })
+    .order("author.name", { id: "DESC" }),
+  { limit: 10 },
+)
+```
+
+## Pagination config
+
+- `limit`: default page size.
+- `maxLimit`: maximum accepted client-provided `limit`.
+- Client-provided `limit` is only used when `maxLimit` is set.
+- If `maxLimit` is set without `limit`, client-provided `limit` is required.
+- If no config is provided, the query must already have `.limit(...)`.
+
+### Page number pagination
+
+- `total`: run a `COUNT(*)` query and include `totalItems` / `totalPages` in the response.
+- `clampPage`: clamp pages beyond the last page to the last available page. Requires `total: true`.

package/dist/index.cjs

@@ -22,27 +22,47 @@ var src_exports = {};
 __export(src_exports, {
   createCursorPaginator: () => createCursorPaginator,
   createPagePaginator: () => createPagePaginator,
-  getPageSize: () => getPageSize,
+  getLimit: () => getLimit,
   paginateByCursor: () => paginateByCursor,
   paginateByPage: () => paginateByPage
 });
 module.exports = __toCommonJS(src_exports);
 
-// src/base.ts
-function getPageSize(query, config, params) {
+// src/limit.ts
+function getLimit(query, config, params) {
+  if (config) {
+    const limit = config.maxLimit !== void 0 ? params?.limit ?? config.limit : config.limit;
+    if (limit === void 0) {
+      throw new Error("Set config.limit or params.limit with config.maxLimit.");
+    }
+    return Math.max(1, Math.min(limit, config.maxLimit ?? limit));
+  }
   const queryLimit = query.q.limit;
-  const maxPageSize = config?.maxPageSize ?? config?.pageSize ?? queryLimit;
-  if (!maxPageSize) {
-    throw new Error("Set query limit, config.maxPageSize, config.pageSize or params.limit.");
+  if (!queryLimit) {
+    throw new Error("Set query limit or config.limit.");
   }
-  return Math.max(1, Math.min(params?.size ?? config?.pageSize ?? maxPageSize, maxPageSize));
+  return Math.max(1, queryLimit);
 }
 
-// src/cursor.ts
-var import_orchid_orm = require("orchid-orm");
-
-// src/cursor/utils.ts
+// src/paginators/cursor/cursor.ts
 var import_node_buffer = require("buffer");
+function createCursor(parts) {
+  return import_node_buffer.Buffer.from(parts.map(String).join(String.fromCharCode(0))).toString("base64url");
+}
+function parseCursor(cursor) {
+  return import_node_buffer.Buffer.from(cursor, "base64url").toString().split(String.fromCharCode(0));
+}
+function createDirectedCursor(parts, reverse) {
+  const cursor = createCursor(parts);
+  return reverse ? "-" + cursor : cursor;
+}
+function parseDirectedCursor(directedCursor) {
+  const [cursor, reverse] = directedCursor.startsWith("-") ? [directedCursor.slice(1), true] : [directedCursor, false];
+  return { cursor, parts: parseCursor(cursor), reverse };
+}
+
+// src/paginators/cursor/order.ts
+var import_node_buffer2 = require("buffer");
 function getQueryOrderFields(query) {
   const orderFields = query.q.order?.flatMap((orderItem) => {
     if (typeof orderItem === "string") {
@@ -64,29 +84,10 @@ function getQueryOrderFields(query) {
   }
   return orderFields;
 }
-function createCursor(parts) {
-  return import_node_buffer.Buffer.from(parts.map(String).join(String.fromCharCode(0))).toString("base64url");
-}
-function parseCursor(cursor) {
-  return import_node_buffer.Buffer.from(cursor, "base64url").toString().split(String.fromCharCode(0));
-}
-function createDirectedCursor(parts, reverse) {
-  const cursor = createCursor(parts);
-  return reverse ? "-" + cursor : cursor;
-}
-function parseDirectedCursor(directedCursor) {
-  const [cursor, reverse] = directedCursor.startsWith("-") ? [directedCursor.slice(1), true] : [directedCursor, false];
-  return { cursor, parts: parseCursor(cursor), reverse };
-}
 
-// src/cursor.ts
-async function createCursorPaginator(config) {
-  return function paginate(query, params) {
-    return paginateByCursor(query, config, params);
-  };
-}
+// src/paginators/cursor/paginator.ts
 async function paginateByCursor(query, config, params) {
-  const size = getPageSize(query, config, params);
+  const limit = getLimit(query, config, params);
   const orderFields = getQueryOrderFields(query);
   const parsedCursorMaybeValid = params?.cursor ? parseDirectedCursor(params.cursor) : void 0;
   const parsedCursor = parsedCursorMaybeValid && parsedCursorMaybeValid.parts.length >= orderFields.length ? parsedCursorMaybeValid : void 0;
@@ -99,57 +100,93 @@ async function paginateByCursor(query, config, params) {
     query = query.clear("order").order(orderArg);
   }
   if (parsedCursor) {
-    const leftSqlExpr = orderFields.map(([field, asc]) => asc ? field : `$${field}`).join(",");
-    const rightSqlExp = orderFields.map(([field, asc]) => asc ? `$${field}` : field).join(",");
-    const sqlExpr = `(${leftSqlExpr}) > (${rightSqlExp})`;
-    const values = Object.fromEntries(orderFields.map(([field], i) => [field, parsedCursor.parts[i]]));
-    query = query.where((0, import_orchid_orm.raw)({ raw: sqlExpr, values }));
+    const leftRawSql = orderFields.map(([field, asc], i) => asc ? query.ref(field).toSQL() : `$value${i}`).join(",");
+    const rightRawSql = orderFields.map(([field, asc], i) => !asc ? query.ref(field).toSQL() : `$value${i}`).join(",");
+    const rawSql = `(${leftRawSql}) > (${rightRawSql})`;
+    const rawSqlValues = Object.fromEntries(
+      orderFields.map((_field, i) => [`value${i}`, parsedCursor.parts[i]])
+    );
+    const sqlExpr = query.qb.sql({ raw: rawSql, values: rawSqlValues });
+    query = query.where(sqlExpr);
   }
-  const items = await query.limit(size + 1);
+  const items = await query.limit(limit + 1);
   if (!Array.isArray(items)) {
     throw new TypeError("Query must return an array.");
   }
-  const hasContinuation = items.length > size;
+  const hasContinuation = items.length > limit;
   if (hasContinuation) {
-    items.splice(size);
+    items.splice(limit);
   }
   if (reverse) {
     items.reverse();
   }
   function createItemCursor(item, reverse2) {
     return createDirectedCursor(orderFields.map(([field]) => {
-      return String(item[field]);
+      return String(getItemValue(item, field));
     }), reverse2);
   }
   const prevCursor = parsedCursor && (parsedCursor.reverse === false || hasContinuation) ? createItemCursor(items[0], true) : void 0;
   const nextCursor = parsedCursor?.reverse === true || hasContinuation ? createItemCursor(items.at(-1), false) : void 0;
-  return { items, size, prevCursor, nextCursor };
+  return { items, limit, prevCursor, nextCursor };
+}
+function getItemValue(item, field) {
+  if (!field.includes(".")) {
+    return item[field];
+  }
+  return field.split(".").reduce((obj, key) => {
+    return obj == null ? void 0 : obj[key];
+  }, item);
 }
 
-// src/page.ts
-function createPagePaginator(config) {
+// src/paginators/cursor/factory.ts
+function createCursorPaginator(config) {
   return function paginate(query, params) {
-    return paginateByPage(query, config, params);
+    return paginateByCursor(query, config, params);
   };
 }
+
+// src/paginators/page/paginator.ts
 async function paginateByPage(query, config, params) {
-  const size = getPageSize(query, config, params);
-  const page = Math.max(1, params?.page ?? 1);
-  const offset = (page - 1) * size;
-  const items = await query.offset(offset).limit(size + 1);
-  const hasContinuation = items.length > size;
-  if (hasContinuation) {
-    items.splice(size);
+  const limit = getLimit(query, config, params);
+  let page = Math.max(1, params?.page ?? 1);
+  let total;
+  if (config?.total) {
+    const totalItems = await query.clear("select", "order").count();
+    const totalPages = Math.max(1, Math.ceil(totalItems / limit));
+    total = { totalItems, totalPages };
+    if (config.clampPage) {
+      page = Math.min(page, totalPages);
+    }
+  }
+  const offset = (page - 1) * limit;
+  const items = await query.offset(offset).limit(total ? limit : limit + 1);
+  if (!Array.isArray(items)) {
+    throw new TypeError("Query must return an array.");
+  }
+  const hasContinuation = total ? page < total.totalPages : items.length > limit;
+  if (items.length > limit) {
+    items.splice(limit);
   }
   const prevPage = page > 1 ? page - 1 : void 0;
   const nextPage = hasContinuation ? page + 1 : void 0;
-  return { items, page, size, offset, prevPage, nextPage };
+  const result = { items, page, limit, offset, prevPage, nextPage };
+  if (total) {
+    return { ...result, ...total };
+  }
+  return result;
+}
+
+// src/paginators/page/factory.ts
+function createPagePaginator(config) {
+  return function paginate(query, params) {
+    return paginateByPage(query, config, params);
+  };
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   createCursorPaginator,
   createPagePaginator,
-  getPageSize,
+  getLimit,
   paginateByCursor,
   paginateByPage
 });

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/base.ts","../src/cursor.ts","../src/cursor/utils.ts","../src/page.ts"],"sourcesContent":["export * from \"./base\"\nexport * from \"./cursor\"\nexport * from \"./page\"\n","import type { Query, QueryThen, SelectQueryData } from \"orchid-orm\"\n\nexport interface ListQuery extends Query {\n  then: QueryThen<unknown[]>\n}\n\nexport interface PaginationConfig {\n  /** Default page size. If not set, `maxPageSize` is used. */\n  pageSize?: number\n  /** Max page size allowed to be passed in params. If not set, `pageSize` is used. */\n  maxPageSize?: number\n}\n\nexport interface PaginationParams {\n  /** Requested page size. */\n  size?: number\n}\n\nexport function getPageSize(query: ListQuery, config?: PaginationConfig, params?: PaginationParams): number {\n  const queryLimit = (query.q as SelectQueryData).limit\n\n  const maxPageSize = config?.maxPageSize ?? config?.pageSize ?? queryLimit\n  if (!maxPageSize) {\n    throw new Error(\"Set query limit, config.maxPageSize, config.pageSize or params.limit.\")\n  }\n\n  return Math.max(1, Math.min(params?.size ?? config?.pageSize ?? maxPageSize, maxPageSize))\n}\n","import type { SortDir } from \"orchid-orm\"\nimport { raw } from \"orchid-orm\"\n\nimport type { ListQuery, PaginationConfig } from \"./base\"\nimport { getPageSize } from \"./base\"\nimport { createDirectedCursor, getQueryOrderFields, parseDirectedCursor } from \"./cursor/utils\"\n\nexport interface CursorPaginationParams {\n  /** Page cursor, as returned by previous call in prevCursor / nextCursor. */\n  cursor?: string\n  /** Page size. */\n  size?: number\n}\n\nexport type CursorPaginationPage<T extends ListQuery = ListQuery> = {\n  items: Awaited<T>\n  /** Effective page size. Number of items is guaranteed to be less or equal. */\n  size: number\n  /** Cursor pointing to previous page. */\n  prevCursor?: string\n  /** Cursor pointing to next page. */\n  nextCursor?: string\n}\n\nexport async function createCursorPaginator(config?: PaginationConfig) {\n  return function paginate<T extends ListQuery>(query: T, params?: CursorPaginationParams) {\n    return paginateByCursor(query, config, params)\n  }\n}\n\nexport async function paginateByCursor<T extends ListQuery>(query: T, config?: PaginationConfig, params?: CursorPaginationParams): Promise<CursorPaginationPage<T>> {\n  const size = getPageSize(query, config, params)\n\n  const orderFields = getQueryOrderFields(query)\n\n  // poor man validation, TODO improve\n  const parsedCursorMaybeValid = params?.cursor ? parseDirectedCursor(params.cursor) : undefined\n  const parsedCursor = parsedCursorMaybeValid && parsedCursorMaybeValid.parts.length >= orderFields.length ? parsedCursorMaybeValid : undefined\n\n  const reverse = parsedCursor?.reverse ?? false\n\n  if (reverse) {\n    // Reverse parsed order fields + reverse query ordering.\n    orderFields.forEach((of) => {\n      of[1] = !of[1]\n    })\n    const orderArg = Object.fromEntries(orderFields.map<[string, SortDir]>(([field, asc]) => [field, asc ? \"ASC\" : \"DESC\"]))\n    query = query.clear(\"order\").order(orderArg as any)\n  }\n\n  if (parsedCursor) {\n    // Prepare raw SQL.\n    // For example, for (amount asc, id asc) order, that would be:\n    // (amount, $id) >= ($amount, id)\n    const leftSqlExpr = orderFields.map(([field, asc]) => asc ? field : `$${field}`).join(\",\")\n    const rightSqlExp = orderFields.map(([field, asc]) => asc ? `$${field}` : field).join(\",\")\n    const sqlExpr = `(${leftSqlExpr}) > (${rightSqlExp})`\n    const values = Object.fromEntries(orderFields.map(([field], i) => [field, parsedCursor.parts[i]]))\n    query = query.where(raw({ raw: sqlExpr, values }))\n  }\n\n  // Query 1 extra item to see if we can paginate farther in current direction.\n  const items = await query.limit(size + 1)\n  if (!Array.isArray(items)) {\n    throw new TypeError(\"Query must return an array.\")\n  }\n  const hasContinuation = items.length > size\n  if (hasContinuation) {\n    items.splice(size)\n  }\n  if (reverse) {\n    items.reverse()\n  }\n\n  function createItemCursor(item: any, reverse: boolean) {\n    return createDirectedCursor(orderFields.map(([field]) => {\n      // Can add custom serializer here if needed.\n      return String(item[field])\n    }), reverse)\n  }\n\n  // Prev cursor:\n  // - for initial pagination, there is no prev page\n  // - for forward pagination, prev page exists always\n  // - for reverse pagination, prev page exists if we have a continuation\n  const prevCursor = (parsedCursor && (parsedCursor.reverse === false || hasContinuation))\n    ? createItemCursor(items[0], true)\n    : undefined\n\n  // Next cursor:\n  // - for reverse pagination, next page exists always\n  // - for initial or forward pagination, next page exists if we have a continuation\n  const nextCursor = (parsedCursor?.reverse === true || hasContinuation)\n    ? createItemCursor(items.at(-1), false)\n    : undefined\n\n  return { items, size, prevCursor, nextCursor }\n}\n","import { Buffer } from \"node:buffer\"\n\nimport type { SelectQueryData } from \"orchid-orm\"\n\nimport type { ListQuery } from \"../base\"\n\ntype OrderField = [field: string, asc: boolean]\n\nexport function getQueryOrderFields(query: ListQuery): OrderField[] {\n  const orderFields = (query.q as SelectQueryData).order?.flatMap<[field: string, asc: boolean]>((orderItem) => {\n    if (typeof orderItem === \"string\") {\n      return [[orderItem, true]]\n    } else if (typeof orderItem === \"object\") {\n      return Object.entries(orderItem).map<[string, boolean]>(([field, order]) => {\n        if (order === \"ASC\" || order === \"DESC\") {\n          return [field, order === \"ASC\"]\n        } else {\n          throw new Error(\"Unsupported order: \" + order)\n        }\n      })\n    } else {\n      throw new TypeError(\"Unsupported order type: \" + orderItem)\n    }\n  })\n  if (!orderFields?.length) {\n    throw new Error(\"Query must be ordered.\")\n  }\n  return orderFields\n}\n\nexport function createCursor(parts: string[]) {\n  return Buffer.from(parts.map(String).join(String.fromCharCode(0))).toString(\"base64url\")\n}\n\nexport function parseCursor(cursor: string) {\n  return Buffer.from(cursor, \"base64url\").toString().split(String.fromCharCode(0))\n}\n\nexport function createDirectedCursor(parts: string[], reverse: boolean) {\n  const cursor = createCursor(parts)\n  return reverse ? \"-\" + cursor : cursor\n}\n\nexport function parseDirectedCursor(directedCursor: string) {\n  const [cursor, reverse] = directedCursor.startsWith(\"-\") ? [directedCursor.slice(1), true] : [directedCursor, false]\n  return { cursor, parts: parseCursor(cursor), reverse }\n}\n","import { getPageSize, type ListQuery, type PaginationConfig } from \"./base\"\n\nexport interface PagePaginationParams {\n  /** Page, 1-based. */\n  page?: number\n  /** Page size. */\n  size?: number\n}\n\nexport type PagePaginationPage<T extends ListQuery = ListQuery> = {\n  items: Awaited<T>\n  /** Effective page number. */\n  page: number\n  /** Effective page size. Number of items is guaranteed to be less or equal. */\n  size: number\n  /** Offset of the first item, 1-based. */\n  offset: number\n  /** Prev page numberm (if exists). */\n  prevPage?: number\n  /** Next page number (if exists). */\n  nextPage?: number\n}\n\nexport function createPagePaginator(config?: PaginationConfig) {\n  return function paginate<T extends ListQuery>(query: T, params?: PagePaginationParams) {\n    return paginateByPage(query, config, params)\n  }\n}\n\nexport async function paginateByPage<T extends ListQuery>(query: T, config?: PaginationConfig, params?: PagePaginationParams): Promise<PagePaginationPage<T>> {\n  const size = getPageSize(query, config, params)\n\n  const page = Math.max(1, params?.page ?? 1)\n  const offset = (page - 1) * size\n\n  const items = await query.offset(offset).limit(size + 1)\n  const hasContinuation = items.length > size\n  if (hasContinuation) {\n    items.splice(size)\n  }\n\n  const prevPage = page > 1 ? page - 1 : undefined\n  const nextPage = hasContinuation ? page + 1 : undefined\n\n  return { items, page, size, offset, prevPage, nextPage }\n}\n"],"mappings":"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","names":["reverse"]}
+{"version":3,"sources":["../src/index.ts","../src/limit.ts","../src/paginators/cursor/cursor.ts","../src/paginators/cursor/order.ts","../src/paginators/cursor/paginator.ts","../src/paginators/cursor/factory.ts","../src/paginators/page/paginator.ts","../src/paginators/page/factory.ts"],"sourcesContent":["export * from \"./limit\"\nexport * from \"./paginators/cursor\"\nexport * from \"./paginators/page\"\nexport * from \"./types\"\n","import type { ListQuery } from \"./types\"\n\nexport interface PaginationConfig {\n  /** Default limit. If `maxLimit` is not set, client params limit is ignored. */\n  limit?: number\n  /** Max limit allowed to be passed in params. */\n  maxLimit?: number\n}\n\nexport interface PaginationParams {\n  /** Requested limit. */\n  limit?: number\n}\n\n/** getLimit returns the effective limit for a query and pagination parameters. */\nexport function getLimit(query: ListQuery, config?: PaginationConfig, params?: PaginationParams): number {\n  if (config) {\n    const limit = config.maxLimit !== undefined ? (params?.limit ?? config.limit) : config.limit\n    if (limit === undefined) {\n      throw new Error(\"Set config.limit or params.limit with config.maxLimit.\")\n    }\n\n    return Math.max(1, Math.min(limit, config.maxLimit ?? limit))\n  }\n\n  const queryLimit = query.q.limit\n  if (!queryLimit) {\n    throw new Error(\"Set query limit or config.limit.\")\n  }\n\n  return Math.max(1, queryLimit)\n}\n","import { Buffer } from \"node:buffer\"\n\n/** createCursor encodes cursor parts into an opaque cursor string. */\nexport function createCursor(parts: string[]) {\n  return Buffer.from(parts.map(String).join(String.fromCharCode(0))).toString(\"base64url\")\n}\n\n/** parseCursor decodes an opaque cursor string into cursor parts. */\nexport function parseCursor(cursor: string) {\n  return Buffer.from(cursor, \"base64url\").toString().split(String.fromCharCode(0))\n}\n\n/** createDirectedCursor encodes cursor parts and pagination direction into an opaque cursor string. */\nexport function createDirectedCursor(parts: string[], reverse: boolean) {\n  const cursor = createCursor(parts)\n  return reverse ? \"-\" + cursor : cursor\n}\n\n/** parseDirectedCursor decodes an opaque directed cursor string into cursor parts and pagination direction. */\nexport function parseDirectedCursor(directedCursor: string) {\n  const [cursor, reverse] = directedCursor.startsWith(\"-\") ? [directedCursor.slice(1), true] : [directedCursor, false]\n  return { cursor, parts: parseCursor(cursor), reverse }\n}\n","import { Buffer } from \"node:buffer\"\n\nimport type { ListQuery } from \"../../types\"\n\ntype OrderField = [field: string, asc: boolean]\n\n/** getQueryOrderFields returns ordered query fields as field and ascending-direction pairs. */\nexport function getQueryOrderFields(query: ListQuery): OrderField[] {\n  const orderFields = query.q.order?.flatMap<[field: string, asc: boolean]>((orderItem) => {\n    if (typeof orderItem === \"string\") {\n      return [[orderItem, true]]\n    } else if (typeof orderItem === \"object\") {\n      return Object.entries(orderItem).map<[string, boolean]>(([field, order]) => {\n        if (order === \"ASC\" || order === \"DESC\") {\n          return [field, order === \"ASC\"]\n        } else {\n          throw new Error(\"Unsupported order: \" + order)\n        }\n      })\n    } else {\n      throw new TypeError(\"Unsupported order type: \" + orderItem)\n    }\n  })\n  if (!orderFields?.length) {\n    throw new Error(\"Query must be ordered.\")\n  }\n  return orderFields\n}\n\n/** createCursor encodes cursor parts into an opaque cursor string. */\nexport function createCursor(parts: string[]) {\n  return Buffer.from(parts.map(String).join(String.fromCharCode(0))).toString(\"base64url\")\n}\n\n/** parseCursor decodes an opaque cursor string into cursor parts. */\nexport function parseCursor(cursor: string) {\n  return Buffer.from(cursor, \"base64url\").toString().split(String.fromCharCode(0))\n}\n\n/** createDirectedCursor encodes cursor parts and pagination direction into an opaque cursor string. */\nexport function createDirectedCursor(parts: string[], reverse: boolean) {\n  const cursor = createCursor(parts)\n  return reverse ? \"-\" + cursor : cursor\n}\n\n/** parseDirectedCursor decodes an opaque directed cursor string into cursor parts and pagination direction. */\nexport function parseDirectedCursor(directedCursor: string) {\n  const [cursor, reverse] = directedCursor.startsWith(\"-\") ? [directedCursor.slice(1), true] : [directedCursor, false]\n  return { cursor, parts: parseCursor(cursor), reverse }\n}\n","import { getLimit, type PaginationConfig } from \"../../limit\"\nimport type { ListQuery, SortDir } from \"../../types\"\n\nimport { createDirectedCursor, parseDirectedCursor } from \"./cursor\"\nimport { getQueryOrderFields } from \"./order\"\n\nexport interface CursorPaginationParams {\n  /** Cursor returned as prevCursor or nextCursor by a previous call. */\n  cursor?: string\n  /** Page size. */\n  limit?: number\n}\n\nexport type CursorPaginationPage<T extends ListQuery = ListQuery> = {\n  items: Awaited<T>\n  /** Effective page size. Number of items is guaranteed to be less than or equal to this value. */\n  limit: number\n  /** Cursor for fetching the previous page, if it exists. */\n  prevCursor?: string\n  /** Cursor for fetching the next page, if it exists. */\n  nextCursor?: string\n}\n\n/** paginateByCursor returns one page of results using cursor-based pagination. */\nexport async function paginateByCursor<T extends ListQuery>(query: T, config?: PaginationConfig, params?: CursorPaginationParams): Promise<CursorPaginationPage<T>> {\n  const limit = getLimit(query, config, params)\n\n  const orderFields = getQueryOrderFields(query)\n\n  // poor man validation, TODO improve\n  const parsedCursorMaybeValid = params?.cursor ? parseDirectedCursor(params.cursor) : undefined\n  const parsedCursor = parsedCursorMaybeValid && parsedCursorMaybeValid.parts.length >= orderFields.length ? parsedCursorMaybeValid : undefined\n\n  const reverse = parsedCursor?.reverse ?? false\n\n  if (reverse) {\n    // Reverse parsed order fields + reverse query ordering.\n    orderFields.forEach((of) => {\n      of[1] = !of[1]\n    })\n    const orderArg = Object.fromEntries(orderFields.map<[string, SortDir]>(([field, asc]) => [field, asc ? \"ASC\" : \"DESC\"]))\n    query = query.clear(\"order\").order(orderArg as any)\n  }\n\n  if (parsedCursor) {\n    // Prepare raw SQL.\n    // For example, for (amount ASC, id DESC) ordering, that would be:\n    // (amount, $id) >= ($amount, id)\n    const leftRawSql = orderFields.map(([field, asc], i) => asc ? query.ref(field).toSQL() : `$value${i}`).join(\",\")\n    const rightRawSql = orderFields.map(([field, asc], i) => !asc ? query.ref(field).toSQL() : `$value${i}`).join(\",\")\n    const rawSql = `(${leftRawSql}) > (${rightRawSql})`\n    const rawSqlValues = Object.fromEntries(\n      orderFields.map((_field, i) => [`value${i}`, parsedCursor.parts[i]]),\n    )\n    const sqlExpr = query.qb.sql({ raw: rawSql, values: rawSqlValues })\n    // query.where doesn't like low-level RawSql objects, cast to any to silence\n    query = query.where(sqlExpr as any)\n  }\n\n  // Query 1 extra item to see if we can paginate farther in current direction.\n  const items = await (query as ListQuery).limit(limit + 1) as Awaited<T>\n  if (!Array.isArray(items)) {\n    throw new TypeError(\"Query must return an array.\")\n  }\n  const hasContinuation = items.length > limit\n  if (hasContinuation) {\n    items.splice(limit)\n  }\n  if (reverse) {\n    items.reverse()\n  }\n\n  function createItemCursor(item: any, reverse: boolean) {\n    return createDirectedCursor(orderFields.map(([field]) => {\n      // Can add custom serializer here if needed.\n      return String(getItemValue(item, field))\n    }), reverse)\n  }\n\n  // Prev cursor:\n  // - for initial pagination, there is no prev page\n  // - for forward pagination, prev page exists always\n  // - for reverse pagination, prev page exists if we have a continuation\n  const prevCursor = (parsedCursor && (parsedCursor.reverse === false || hasContinuation))\n    ? createItemCursor(items[0], true)\n    : undefined\n\n  // Next cursor:\n  // - for reverse pagination, next page exists always\n  // - for initial or forward pagination, next page exists if we have a continuation\n  const nextCursor = (parsedCursor?.reverse === true || hasContinuation)\n    ? createItemCursor(items.at(-1), false)\n    : undefined\n\n  return { items, limit, prevCursor, nextCursor }\n}\n\n/** getItemValue returns an item's field value, resolving dot-notation paths against nested objects. */\nfunction getItemValue(item: unknown, field: string): unknown {\n  if (!field.includes(\".\")) {\n    return (item as Record<string, unknown>)[field]\n  }\n\n  return field.split(\".\").reduce<unknown>((obj, key) => {\n    return obj == null ? undefined : (obj as Record<string, unknown>)[key]\n  }, item)\n}\n","import type { PaginationConfig } from \"../../limit\"\nimport type { ListQuery } from \"../../types\"\n\nimport { type CursorPaginationParams, paginateByCursor } from \"./paginator\"\n\n/** createCursorPaginator creates a reusable cursor paginator with the given config. */\nexport function createCursorPaginator(config?: PaginationConfig) {\n  return function paginate<T extends ListQuery>(query: T, params?: CursorPaginationParams) {\n    return paginateByCursor(query, config, params)\n  }\n}\n","import { getLimit, type PaginationConfig } from \"../../limit\"\nimport type { ListQuery } from \"../../types\"\n\nexport type PagePaginationConfig = PaginationConfig & {\n  /**\n   * When true, runs a COUNT(*) query and returns `totalItems` / `totalPages` in the result.\n   * Requested pages beyond the last are not clamped unless `clampPage` is true.\n   */\n  total?: boolean\n}\n\nexport type PagePaginationConfigWithTotal = PagePaginationConfig & {\n  total: true\n  /** When true, requested pages beyond the last are clamped to the last page. */\n  clampPage?: boolean\n}\n\nexport interface PagePaginationParams {\n  /** Page number, 1-based. */\n  page?: number\n  /** Page size. */\n  limit?: number\n}\n\nexport type PagePaginationPage<T extends ListQuery = ListQuery> = {\n  items: Awaited<T>\n  /** Effective page number, 1-based. */\n  page: number\n  /** Effective page size. Number of items is guaranteed to be less than or equal to this value. */\n  limit: number\n  /** Offset passed to the query, 0-based. */\n  offset: number\n  /** Previous page number, if it exists. */\n  prevPage?: number\n  /** Next page number, if it exists. */\n  nextPage?: number\n}\n\nexport type PagePaginationTotal = {\n  /** Total number of items across all pages. */\n  totalItems: number\n  /** Total number of pages. */\n  totalPages: number\n}\n\nexport type PagePaginationPageWithTotal<T extends ListQuery = ListQuery> = PagePaginationPage<T> & PagePaginationTotal\n\n/** paginateByPage returns one page of results using offset-based pagination. */\nexport async function paginateByPage<T extends ListQuery>(\n  query: T,\n  config: PagePaginationConfigWithTotal,\n  params?: PagePaginationParams,\n): Promise<PagePaginationPageWithTotal<T>>\nexport async function paginateByPage<T extends ListQuery>(\n  query: T,\n  config?: PagePaginationConfig,\n  params?: PagePaginationParams,\n): Promise<PagePaginationPage<T>>\nexport async function paginateByPage<T extends ListQuery>(\n  query: T,\n  config?: PagePaginationConfig | PagePaginationConfigWithTotal,\n  params?: PagePaginationParams,\n) {\n  const limit = getLimit(query, config, params)\n\n  let page = Math.max(1, params?.page ?? 1)\n\n  let total: PagePaginationTotal | undefined\n  if (config?.total) {\n    const totalItems = await (query as ListQuery).clear(\"select\", \"order\").count() as number\n    const totalPages = Math.max(1, Math.ceil(totalItems / limit))\n    total = { totalItems, totalPages }\n    if ((config as PagePaginationConfigWithTotal).clampPage) {\n      page = Math.min(page, totalPages)\n    }\n  }\n\n  const offset = (page - 1) * limit\n\n  // When total is known, we can request exactly `limit` items;\n  // otherwise, request limit + 1 to detect continuation.\n  const items = await (query as ListQuery)\n    .offset(offset)\n    .limit(total ? limit : limit + 1) as Awaited<T>\n  if (!Array.isArray(items)) {\n    throw new TypeError(\"Query must return an array.\")\n  }\n\n  const hasContinuation = total ? page < total.totalPages : items.length > limit\n  if (items.length > limit) {\n    items.splice(limit)\n  }\n\n  const prevPage = page > 1 ? page - 1 : undefined\n  const nextPage = hasContinuation ? page + 1 : undefined\n\n  const result: PagePaginationPage<T> = { items, page, limit, offset, prevPage, nextPage }\n\n  if (total) {\n    return { ...result, ...total } as PagePaginationPageWithTotal<T>\n  }\n\n  return result\n}\n","import type { ListQuery } from \"../../types\"\n\nimport type {\n  PagePaginationConfig,\n  PagePaginationConfigWithTotal,\n  PagePaginationPage,\n  PagePaginationPageWithTotal,\n  PagePaginationParams,\n} from \"./paginator\"\nimport { paginateByPage } from \"./paginator\"\n\n/** createPagePaginator creates a reusable page paginator with the given config. */\nexport function createPagePaginator(config: PagePaginationConfigWithTotal): <T extends ListQuery>(\n  query: T,\n  params?: PagePaginationParams,\n) => Promise<PagePaginationPageWithTotal<T>>\nexport function createPagePaginator(config?: PagePaginationConfig): <T extends ListQuery>(\n  query: T,\n  params?: PagePaginationParams,\n) => Promise<PagePaginationPage<T>>\nexport function createPagePaginator(config?: PagePaginationConfig | PagePaginationConfigWithTotal) {\n  return function paginate<T extends ListQuery>(query: T, params?: PagePaginationParams) {\n    return paginateByPage(query, config, params)\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACeO,SAAS,SAAS,OAAkB,QAA2B,QAAmC;AACvG,MAAI,QAAQ;AACV,UAAM,QAAQ,OAAO,aAAa,SAAa,QAAQ,SAAS,OAAO,QAAS,OAAO;AACvF,QAAI,UAAU,QAAW;AACvB,YAAM,IAAI,MAAM,wDAAwD;AAAA,IAC1E;AAEA,WAAO,KAAK,IAAI,GAAG,KAAK,IAAI,OAAO,OAAO,YAAY,KAAK,CAAC;AAAA,EAC9D;AAEA,QAAM,aAAa,MAAM,EAAE;AAC3B,MAAI,CAAC,YAAY;AACf,UAAM,IAAI,MAAM,kCAAkC;AAAA,EACpD;AAEA,SAAO,KAAK,IAAI,GAAG,UAAU;AAC/B;;;AC/BA,yBAAuB;AAGhB,SAAS,aAAa,OAAiB;AAC5C,SAAO,0BAAO,KAAK,MAAM,IAAI,MAAM,EAAE,KAAK,OAAO,aAAa,CAAC,CAAC,CAAC,EAAE,SAAS,WAAW;AACzF;AAGO,SAAS,YAAY,QAAgB;AAC1C,SAAO,0BAAO,KAAK,QAAQ,WAAW,EAAE,SAAS,EAAE,MAAM,OAAO,aAAa,CAAC,CAAC;AACjF;AAGO,SAAS,qBAAqB,OAAiB,SAAkB;AACtE,QAAM,SAAS,aAAa,KAAK;AACjC,SAAO,UAAU,MAAM,SAAS;AAClC;AAGO,SAAS,oBAAoB,gBAAwB;AAC1D,QAAM,CAAC,QAAQ,OAAO,IAAI,eAAe,WAAW,GAAG,IAAI,CAAC,eAAe,MAAM,CAAC,GAAG,IAAI,IAAI,CAAC,gBAAgB,KAAK;AACnH,SAAO,EAAE,QAAQ,OAAO,YAAY,MAAM,GAAG,QAAQ;AACvD;;;ACtBA,IAAAA,sBAAuB;AAOhB,SAAS,oBAAoB,OAAgC;AAClE,QAAM,cAAc,MAAM,EAAE,OAAO,QAAuC,CAAC,cAAc;AACvF,QAAI,OAAO,cAAc,UAAU;AACjC,aAAO,CAAC,CAAC,WAAW,IAAI,CAAC;AAAA,IAC3B,WAAW,OAAO,cAAc,UAAU;AACxC,aAAO,OAAO,QAAQ,SAAS,EAAE,IAAuB,CAAC,CAAC,OAAO,KAAK,MAAM;AAC1E,YAAI,UAAU,SAAS,UAAU,QAAQ;AACvC,iBAAO,CAAC,OAAO,UAAU,KAAK;AAAA,QAChC,OAAO;AACL,gBAAM,IAAI,MAAM,wBAAwB,KAAK;AAAA,QAC/C;AAAA,MACF,CAAC;AAAA,IACH,OAAO;AACL,YAAM,IAAI,UAAU,6BAA6B,SAAS;AAAA,IAC5D;AAAA,EACF,CAAC;AACD,MAAI,CAAC,aAAa,QAAQ;AACxB,UAAM,IAAI,MAAM,wBAAwB;AAAA,EAC1C;AACA,SAAO;AACT;;;ACHA,eAAsB,iBAAsC,OAAU,QAA2B,QAAmE;AAClK,QAAM,QAAQ,SAAS,OAAO,QAAQ,MAAM;AAE5C,QAAM,cAAc,oBAAoB,KAAK;AAG7C,QAAM,yBAAyB,QAAQ,SAAS,oBAAoB,OAAO,MAAM,IAAI;AACrF,QAAM,eAAe,0BAA0B,uBAAuB,MAAM,UAAU,YAAY,SAAS,yBAAyB;AAEpI,QAAM,UAAU,cAAc,WAAW;AAEzC,MAAI,SAAS;AAEX,gBAAY,QAAQ,CAAC,OAAO;AAC1B,SAAG,CAAC,IAAI,CAAC,GAAG,CAAC;AAAA,IACf,CAAC;AACD,UAAM,WAAW,OAAO,YAAY,YAAY,IAAuB,CAAC,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,MAAM,QAAQ,MAAM,CAAC,CAAC;AACvH,YAAQ,MAAM,MAAM,OAAO,EAAE,MAAM,QAAe;AAAA,EACpD;AAEA,MAAI,cAAc;AAIhB,UAAM,aAAa,YAAY,IAAI,CAAC,CAAC,OAAO,GAAG,GAAG,MAAM,MAAM,MAAM,IAAI,KAAK,EAAE,MAAM,IAAI,SAAS,CAAC,EAAE,EAAE,KAAK,GAAG;AAC/G,UAAM,cAAc,YAAY,IAAI,CAAC,CAAC,OAAO,GAAG,GAAG,MAAM,CAAC,MAAM,MAAM,IAAI,KAAK,EAAE,MAAM,IAAI,SAAS,CAAC,EAAE,EAAE,KAAK,GAAG;AACjH,UAAM,SAAS,IAAI,UAAU,QAAQ,WAAW;AAChD,UAAM,eAAe,OAAO;AAAA,MAC1B,YAAY,IAAI,CAAC,QAAQ,MAAM,CAAC,QAAQ,CAAC,IAAI,aAAa,MAAM,CAAC,CAAC,CAAC;AAAA,IACrE;AACA,UAAM,UAAU,MAAM,GAAG,IAAI,EAAE,KAAK,QAAQ,QAAQ,aAAa,CAAC;AAElE,YAAQ,MAAM,MAAM,OAAc;AAAA,EACpC;AAGA,QAAM,QAAQ,MAAO,MAAoB,MAAM,QAAQ,CAAC;AACxD,MAAI,CAAC,MAAM,QAAQ,KAAK,GAAG;AACzB,UAAM,IAAI,UAAU,6BAA6B;AAAA,EACnD;AACA,QAAM,kBAAkB,MAAM,SAAS;AACvC,MAAI,iBAAiB;AACnB,UAAM,OAAO,KAAK;AAAA,EACpB;AACA,MAAI,SAAS;AACX,UAAM,QAAQ;AAAA,EAChB;AAEA,WAAS,iBAAiB,MAAWC,UAAkB;AACrD,WAAO,qBAAqB,YAAY,IAAI,CAAC,CAAC,KAAK,MAAM;AAEvD,aAAO,OAAO,aAAa,MAAM,KAAK,CAAC;AAAA,IACzC,CAAC,GAAGA,QAAO;AAAA,EACb;AAMA,QAAM,aAAc,iBAAiB,aAAa,YAAY,SAAS,mBACnE,iBAAiB,MAAM,CAAC,GAAG,IAAI,IAC/B;AAKJ,QAAM,aAAc,cAAc,YAAY,QAAQ,kBAClD,iBAAiB,MAAM,GAAG,EAAE,GAAG,KAAK,IACpC;AAEJ,SAAO,EAAE,OAAO,OAAO,YAAY,WAAW;AAChD;AAGA,SAAS,aAAa,MAAe,OAAwB;AAC3D,MAAI,CAAC,MAAM,SAAS,GAAG,GAAG;AACxB,WAAQ,KAAiC,KAAK;AAAA,EAChD;AAEA,SAAO,MAAM,MAAM,GAAG,EAAE,OAAgB,CAAC,KAAK,QAAQ;AACpD,WAAO,OAAO,OAAO,SAAa,IAAgC,GAAG;AAAA,EACvE,GAAG,IAAI;AACT;;;ACpGO,SAAS,sBAAsB,QAA2B;AAC/D,SAAO,SAAS,SAA8B,OAAU,QAAiC;AACvF,WAAO,iBAAiB,OAAO,QAAQ,MAAM;AAAA,EAC/C;AACF;;;ACgDA,eAAsB,eACpB,OACA,QACA,QACA;AACA,QAAM,QAAQ,SAAS,OAAO,QAAQ,MAAM;AAE5C,MAAI,OAAO,KAAK,IAAI,GAAG,QAAQ,QAAQ,CAAC;AAExC,MAAI;AACJ,MAAI,QAAQ,OAAO;AACjB,UAAM,aAAa,MAAO,MAAoB,MAAM,UAAU,OAAO,EAAE,MAAM;AAC7E,UAAM,aAAa,KAAK,IAAI,GAAG,KAAK,KAAK,aAAa,KAAK,CAAC;AAC5D,YAAQ,EAAE,YAAY,WAAW;AACjC,QAAK,OAAyC,WAAW;AACvD,aAAO,KAAK,IAAI,MAAM,UAAU;AAAA,IAClC;AAAA,EACF;AAEA,QAAM,UAAU,OAAO,KAAK;AAI5B,QAAM,QAAQ,MAAO,MAClB,OAAO,MAAM,EACb,MAAM,QAAQ,QAAQ,QAAQ,CAAC;AAClC,MAAI,CAAC,MAAM,QAAQ,KAAK,GAAG;AACzB,UAAM,IAAI,UAAU,6BAA6B;AAAA,EACnD;AAEA,QAAM,kBAAkB,QAAQ,OAAO,MAAM,aAAa,MAAM,SAAS;AACzE,MAAI,MAAM,SAAS,OAAO;AACxB,UAAM,OAAO,KAAK;AAAA,EACpB;AAEA,QAAM,WAAW,OAAO,IAAI,OAAO,IAAI;AACvC,QAAM,WAAW,kBAAkB,OAAO,IAAI;AAE9C,QAAM,SAAgC,EAAE,OAAO,MAAM,OAAO,QAAQ,UAAU,SAAS;AAEvF,MAAI,OAAO;AACT,WAAO,EAAE,GAAG,QAAQ,GAAG,MAAM;AAAA,EAC/B;AAEA,SAAO;AACT;;;ACnFO,SAAS,oBAAoB,QAA+D;AACjG,SAAO,SAAS,SAA8B,OAAU,QAA+B;AACrF,WAAO,eAAe,OAAO,QAAQ,MAAM;AAAA,EAC7C;AACF;","names":["import_node_buffer","reverse"]}

package/dist/index.d.cts

@@ -1,58 +1,88 @@
-import { Query, QueryThen } from 'orchid-orm';
+import { Query } from 'orchid-orm';
+
+type ListQuery = Query & {
+    returnType: undefined | "all";
+};
+type SortDir = "ASC" | "DESC";
 
-interface ListQuery extends Query {
-    then: QueryThen<unknown[]>;
-}
 interface PaginationConfig {
-    /** Default page size. If not set, `maxPageSize` is used. */
-    pageSize?: number;
-    /** Max page size allowed to be passed in params. If not set, `pageSize` is used. */
-    maxPageSize?: number;
+    /** Default limit. If `maxLimit` is not set, client params limit is ignored. */
+    limit?: number;
+    /** Max limit allowed to be passed in params. */
+    maxLimit?: number;
 }
 interface PaginationParams {
-    /** Requested page size. */
-    size?: number;
+    /** Requested limit. */
+    limit?: number;
 }
-declare function getPageSize(query: ListQuery, config?: PaginationConfig, params?: PaginationParams): number;
+/** getLimit returns the effective limit for a query and pagination parameters. */
+declare function getLimit(query: ListQuery, config?: PaginationConfig, params?: PaginationParams): number;
 
 interface CursorPaginationParams {
-    /** Page cursor, as returned by previous call in prevCursor / nextCursor. */
+    /** Cursor returned as prevCursor or nextCursor by a previous call. */
     cursor?: string;
     /** Page size. */
-    size?: number;
+    limit?: number;
 }
 type CursorPaginationPage<T extends ListQuery = ListQuery> = {
     items: Awaited<T>;
-    /** Effective page size. Number of items is guaranteed to be less or equal. */
-    size: number;
-    /** Cursor pointing to previous page. */
+    /** Effective page size. Number of items is guaranteed to be less than or equal to this value. */
+    limit: number;
+    /** Cursor for fetching the previous page, if it exists. */
     prevCursor?: string;
-    /** Cursor pointing to next page. */
+    /** Cursor for fetching the next page, if it exists. */
     nextCursor?: string;
 };
-declare function createCursorPaginator(config?: PaginationConfig): Promise<(<T extends ListQuery>(query: T, params?: CursorPaginationParams) => Promise<CursorPaginationPage<T>>)>;
+/** paginateByCursor returns one page of results using cursor-based pagination. */
 declare function paginateByCursor<T extends ListQuery>(query: T, config?: PaginationConfig, params?: CursorPaginationParams): Promise<CursorPaginationPage<T>>;
 
+/** createCursorPaginator creates a reusable cursor paginator with the given config. */
+declare function createCursorPaginator(config?: PaginationConfig): <T extends ListQuery>(query: T, params?: CursorPaginationParams) => Promise<CursorPaginationPage<T>>;
+
+type PagePaginationConfig = PaginationConfig & {
+    /**
+     * When true, runs a COUNT(*) query and returns `totalItems` / `totalPages` in the result.
+     * Requested pages beyond the last are not clamped unless `clampPage` is true.
+     */
+    total?: boolean;
+};
+type PagePaginationConfigWithTotal = PagePaginationConfig & {
+    total: true;
+    /** When true, requested pages beyond the last are clamped to the last page. */
+    clampPage?: boolean;
+};
 interface PagePaginationParams {
-    /** Page, 1-based. */
+    /** Page number, 1-based. */
     page?: number;
     /** Page size. */
-    size?: number;
+    limit?: number;
 }
 type PagePaginationPage<T extends ListQuery = ListQuery> = {
     items: Awaited<T>;
-    /** Effective page number. */
+    /** Effective page number, 1-based. */
     page: number;
-    /** Effective page size. Number of items is guaranteed to be less or equal. */
-    size: number;
-    /** Offset of the first item, 1-based. */
+    /** Effective page size. Number of items is guaranteed to be less than or equal to this value. */
+    limit: number;
+    /** Offset passed to the query, 0-based. */
     offset: number;
-    /** Prev page numberm (if exists). */
+    /** Previous page number, if it exists. */
     prevPage?: number;
-    /** Next page number (if exists). */
+    /** Next page number, if it exists. */
     nextPage?: number;
 };
-declare function createPagePaginator(config?: PaginationConfig): <T extends ListQuery>(query: T, params?: PagePaginationParams) => Promise<PagePaginationPage<T>>;
-declare function paginateByPage<T extends ListQuery>(query: T, config?: PaginationConfig, params?: PagePaginationParams): Promise<PagePaginationPage<T>>;
+type PagePaginationTotal = {
+    /** Total number of items across all pages. */
+    totalItems: number;
+    /** Total number of pages. */
+    totalPages: number;
+};
+type PagePaginationPageWithTotal<T extends ListQuery = ListQuery> = PagePaginationPage<T> & PagePaginationTotal;
+/** paginateByPage returns one page of results using offset-based pagination. */
+declare function paginateByPage<T extends ListQuery>(query: T, config: PagePaginationConfigWithTotal, params?: PagePaginationParams): Promise<PagePaginationPageWithTotal<T>>;
+declare function paginateByPage<T extends ListQuery>(query: T, config?: PagePaginationConfig, params?: PagePaginationParams): Promise<PagePaginationPage<T>>;
+
+/** createPagePaginator creates a reusable page paginator with the given config. */
+declare function createPagePaginator(config: PagePaginationConfigWithTotal): <T extends ListQuery>(query: T, params?: PagePaginationParams) => Promise<PagePaginationPageWithTotal<T>>;
+declare function createPagePaginator(config?: PagePaginationConfig): <T extends ListQuery>(query: T, params?: PagePaginationParams) => Promise<PagePaginationPage<T>>;
 
-export { type CursorPaginationPage, type CursorPaginationParams, type ListQuery, type PagePaginationPage, type PagePaginationParams, type PaginationConfig, type PaginationParams, createCursorPaginator, createPagePaginator, getPageSize, paginateByCursor, paginateByPage };
+export { type CursorPaginationPage, type CursorPaginationParams, type ListQuery, type PagePaginationConfig, type PagePaginationConfigWithTotal, type PagePaginationPage, type PagePaginationPageWithTotal, type PagePaginationParams, type PagePaginationTotal, type PaginationConfig, type PaginationParams, type SortDir, createCursorPaginator, createPagePaginator, getLimit, paginateByCursor, paginateByPage };

package/dist/index.d.ts

@@ -1,58 +1,88 @@
-import { Query, QueryThen } from 'orchid-orm';
+import { Query } from 'orchid-orm';
+
+type ListQuery = Query & {
+    returnType: undefined | "all";
+};
+type SortDir = "ASC" | "DESC";
 
-interface ListQuery extends Query {
-    then: QueryThen<unknown[]>;
-}
 interface PaginationConfig {
-    /** Default page size. If not set, `maxPageSize` is used. */
-    pageSize?: number;
-    /** Max page size allowed to be passed in params. If not set, `pageSize` is used. */
-    maxPageSize?: number;
+    /** Default limit. If `maxLimit` is not set, client params limit is ignored. */
+    limit?: number;
+    /** Max limit allowed to be passed in params. */
+    maxLimit?: number;
 }
 interface PaginationParams {
-    /** Requested page size. */
-    size?: number;
+    /** Requested limit. */
+    limit?: number;
 }
-declare function getPageSize(query: ListQuery, config?: PaginationConfig, params?: PaginationParams): number;
+/** getLimit returns the effective limit for a query and pagination parameters. */
+declare function getLimit(query: ListQuery, config?: PaginationConfig, params?: PaginationParams): number;
 
 interface CursorPaginationParams {
-    /** Page cursor, as returned by previous call in prevCursor / nextCursor. */
+    /** Cursor returned as prevCursor or nextCursor by a previous call. */
     cursor?: string;
     /** Page size. */
-    size?: number;
+    limit?: number;
 }
 type CursorPaginationPage<T extends ListQuery = ListQuery> = {
     items: Awaited<T>;
-    /** Effective page size. Number of items is guaranteed to be less or equal. */
-    size: number;
-    /** Cursor pointing to previous page. */
+    /** Effective page size. Number of items is guaranteed to be less than or equal to this value. */
+    limit: number;
+    /** Cursor for fetching the previous page, if it exists. */
     prevCursor?: string;
-    /** Cursor pointing to next page. */
+    /** Cursor for fetching the next page, if it exists. */
     nextCursor?: string;
 };
-declare function createCursorPaginator(config?: PaginationConfig): Promise<(<T extends ListQuery>(query: T, params?: CursorPaginationParams) => Promise<CursorPaginationPage<T>>)>;
+/** paginateByCursor returns one page of results using cursor-based pagination. */
 declare function paginateByCursor<T extends ListQuery>(query: T, config?: PaginationConfig, params?: CursorPaginationParams): Promise<CursorPaginationPage<T>>;
 
+/** createCursorPaginator creates a reusable cursor paginator with the given config. */
+declare function createCursorPaginator(config?: PaginationConfig): <T extends ListQuery>(query: T, params?: CursorPaginationParams) => Promise<CursorPaginationPage<T>>;
+
+type PagePaginationConfig = PaginationConfig & {
+    /**
+     * When true, runs a COUNT(*) query and returns `totalItems` / `totalPages` in the result.
+     * Requested pages beyond the last are not clamped unless `clampPage` is true.
+     */
+    total?: boolean;
+};
+type PagePaginationConfigWithTotal = PagePaginationConfig & {
+    total: true;
+    /** When true, requested pages beyond the last are clamped to the last page. */
+    clampPage?: boolean;
+};
 interface PagePaginationParams {
-    /** Page, 1-based. */
+    /** Page number, 1-based. */
     page?: number;
     /** Page size. */
-    size?: number;
+    limit?: number;
 }
 type PagePaginationPage<T extends ListQuery = ListQuery> = {
     items: Awaited<T>;
-    /** Effective page number. */
+    /** Effective page number, 1-based. */
     page: number;
-    /** Effective page size. Number of items is guaranteed to be less or equal. */
-    size: number;
-    /** Offset of the first item, 1-based. */
+    /** Effective page size. Number of items is guaranteed to be less than or equal to this value. */
+    limit: number;
+    /** Offset passed to the query, 0-based. */
     offset: number;
-    /** Prev page numberm (if exists). */
+    /** Previous page number, if it exists. */
     prevPage?: number;
-    /** Next page number (if exists). */
+    /** Next page number, if it exists. */
     nextPage?: number;
 };
-declare function createPagePaginator(config?: PaginationConfig): <T extends ListQuery>(query: T, params?: PagePaginationParams) => Promise<PagePaginationPage<T>>;
-declare function paginateByPage<T extends ListQuery>(query: T, config?: PaginationConfig, params?: PagePaginationParams): Promise<PagePaginationPage<T>>;
+type PagePaginationTotal = {
+    /** Total number of items across all pages. */
+    totalItems: number;
+    /** Total number of pages. */
+    totalPages: number;
+};
+type PagePaginationPageWithTotal<T extends ListQuery = ListQuery> = PagePaginationPage<T> & PagePaginationTotal;
+/** paginateByPage returns one page of results using offset-based pagination. */
+declare function paginateByPage<T extends ListQuery>(query: T, config: PagePaginationConfigWithTotal, params?: PagePaginationParams): Promise<PagePaginationPageWithTotal<T>>;
+declare function paginateByPage<T extends ListQuery>(query: T, config?: PagePaginationConfig, params?: PagePaginationParams): Promise<PagePaginationPage<T>>;
+
+/** createPagePaginator creates a reusable page paginator with the given config. */
+declare function createPagePaginator(config: PagePaginationConfigWithTotal): <T extends ListQuery>(query: T, params?: PagePaginationParams) => Promise<PagePaginationPageWithTotal<T>>;
+declare function createPagePaginator(config?: PagePaginationConfig): <T extends ListQuery>(query: T, params?: PagePaginationParams) => Promise<PagePaginationPage<T>>;
 
-export { type CursorPaginationPage, type CursorPaginationParams, type ListQuery, type PagePaginationPage, type PagePaginationParams, type PaginationConfig, type PaginationParams, createCursorPaginator, createPagePaginator, getPageSize, paginateByCursor, paginateByPage };
+export { type CursorPaginationPage, type CursorPaginationParams, type ListQuery, type PagePaginationConfig, type PagePaginationConfigWithTotal, type PagePaginationPage, type PagePaginationPageWithTotal, type PagePaginationParams, type PagePaginationTotal, type PaginationConfig, type PaginationParams, type SortDir, createCursorPaginator, createPagePaginator, getLimit, paginateByCursor, paginateByPage };