orchid-pagination 2.0.0 → 2.1.1

package/README.md

@@ -41,6 +41,14 @@ defineEventHandler(async (ctx) => {
 
 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
 
 ```ts
@@ -75,7 +83,9 @@ Cursor queries must be ordered.
 Include a deterministic tie-breaker, usually `id`.
 Treat cursors as opaque strings and pass them back unchanged.
 
-You can order by selected relation fields and aliases as long as the ordered value is present in the query result:
+### Aliases and relations
+
+You can order by selected aliases or by relation paths:
 
 ```ts
 const page = await paginateByCursor(
@@ -88,10 +98,26 @@ const page = await paginateByCursor(
 )
 ```
 
+```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 limit.
-- `maxLimit`: max accepted client `limit`.
-- Client `limit` is ignored unless `maxLimit` is set.
-- With only `maxLimit`, client `limit` is required.
-- Without config, query `.limit(...)` is required.
+- `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

@@ -122,7 +122,11 @@ async function paginateByCursor(query, config, params) {
   }
   function createItemCursor(item, reverse2) {
     return createDirectedCursor(orderFields.map(([field]) => {
-      return String(getItemValue(item, field));
+      const value = getItemValue(item, field);
+      if (value === void 0) {
+        throw new Error(`Order field "${field}" is missing from the result \u2014 cursor pagination requires every order field to be selected.`);
+      }
+      return String(value);
     }), reverse2);
   }
   const prevCursor = parsedCursor && (parsedCursor.reverse === false || hasContinuation) ? createItemCursor(items[0], true) : void 0;
@@ -148,19 +152,32 @@ function createCursorPaginator(config) {
 // src/paginators/page/paginator.ts
 async function paginateByPage(query, config, params) {
   const limit = getLimit(query, config, params);
-  const page = Math.max(1, params?.page ?? 1);
+  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(limit + 1);
+  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 = items.length > limit;
-  if (hasContinuation) {
+  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, limit, offset, prevPage, nextPage };
+  const result = { items, page, limit, offset, prevPage, nextPage };
+  if (total) {
+    return { ...result, ...total };
+  }
+  return result;
 }
 
 // src/paginators/page/factory.ts

package/dist/index.cjs.map

@@ -1 +1 @@
-{"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  /** Page cursor, as returned by previous call in prevCursor / nextCursor. */\n  cursor?: string\n  /** Limit. */\n  limit?: number\n}\n\nexport type CursorPaginationPage<T extends ListQuery = ListQuery> = {\n  items: Awaited<T>\n  /** Effective limit. Number of items is guaranteed to be less or equal. */\n  limit: number\n  /** Cursor pointing to previous page. */\n  prevCursor?: string\n  /** Cursor pointing to next page. */\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 interface PagePaginationParams {\n  /** Page, 1-based. */\n  page?: number\n  /** Limit. */\n  limit?: number\n}\n\nexport type PagePaginationPage<T extends ListQuery = ListQuery> = {\n  items: Awaited<T>\n  /** Effective page number. */\n  page: number\n  /** Effective limit. Number of items is guaranteed to be less or equal. */\n  limit: number\n  /** Offset of the first item, 1-based. */\n  offset: number\n  /** Prev page number (if exists). */\n  prevPage?: number\n  /** Next page number (if exists). */\n  nextPage?: number\n}\n\n/** paginateByPage returns one page of results using offset-based pagination. */\nexport async function paginateByPage<T extends ListQuery>(query: T, config?: PaginationConfig, params?: PagePaginationParams): Promise<PagePaginationPage<T>> {\n  const limit = getLimit(query, config, params)\n\n  const page = Math.max(1, params?.page ?? 1)\n  const offset = (page - 1) * limit\n\n  const items = await (query as ListQuery).offset(offset).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\n  const prevPage = page > 1 ? page - 1 : undefined\n  const nextPage = hasContinuation ? page + 1 : undefined\n\n  return { items, page, limit, offset, prevPage, nextPage }\n}\n","import type { PaginationConfig } from \"../../limit\"\nimport type { ListQuery } from \"../../types\"\n\nimport { type PagePaginationParams, paginateByPage } from \"./paginator\"\n\n/** createPagePaginator creates a reusable page paginator with the given config. */\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"],"mappings":"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","names":["import_node_buffer","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      const value = getItemValue(item, field)\n      // A missing order field (undefined) means it wasn't selected; encoding it would\n      // produce a broken cursor that later fails deep inside the database. A legitimate\n      // NULL value is fine and gets encoded as usual.\n      if (value === undefined) {\n        throw new Error(`Order field \"${field}\" is missing from the result — cursor pagination requires every order field to be selected.`)\n      }\n      // Can add custom serializer here if needed.\n      return String(value)\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":"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","names":["import_node_buffer","reverse"]}

package/dist/index.d.cts

@@ -19,18 +19,18 @@ interface PaginationParams {
 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;
-    /** Limit. */
+    /** Page size. */
     limit?: number;
 }
 type CursorPaginationPage<T extends ListQuery = ListQuery> = {
     items: Awaited<T>;
-    /** Effective limit. Number of items is guaranteed to be less or equal. */
+    /** Effective page size. Number of items is guaranteed to be less than or equal to this value. */
     limit: number;
-    /** Cursor pointing to previous page. */
+    /** 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;
 };
 /** paginateByCursor returns one page of results using cursor-based pagination. */
@@ -39,29 +39,50 @@ declare function paginateByCursor<T extends ListQuery>(query: T, config?: Pagina
 /** 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;
-    /** Limit. */
+    /** Page size. */
     limit?: number;
 }
 type PagePaginationPage<T extends ListQuery = ListQuery> = {
     items: Awaited<T>;
-    /** Effective page number. */
+    /** Effective page number, 1-based. */
     page: number;
-    /** Effective limit. Number of items is guaranteed to be less or equal. */
+    /** Effective page size. Number of items is guaranteed to be less than or equal to this value. */
     limit: number;
-    /** Offset of the first item, 1-based. */
+    /** Offset passed to the query, 0-based. */
     offset: number;
-    /** Prev page number (if exists). */
+    /** Previous page number, if it exists. */
     prevPage?: number;
-    /** Next page number (if exists). */
+    /** Next page number, if it exists. */
     nextPage?: number;
 };
+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?: PaginationConfig, params?: PagePaginationParams): Promise<PagePaginationPage<T>>;
+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?: PaginationConfig): <T extends ListQuery>(query: T, params?: PagePaginationParams) => Promise<PagePaginationPage<T>>;
+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, type SortDir, createCursorPaginator, createPagePaginator, getLimit, 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

@@ -19,18 +19,18 @@ interface PaginationParams {
 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;
-    /** Limit. */
+    /** Page size. */
     limit?: number;
 }
 type CursorPaginationPage<T extends ListQuery = ListQuery> = {
     items: Awaited<T>;
-    /** Effective limit. Number of items is guaranteed to be less or equal. */
+    /** Effective page size. Number of items is guaranteed to be less than or equal to this value. */
     limit: number;
-    /** Cursor pointing to previous page. */
+    /** 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;
 };
 /** paginateByCursor returns one page of results using cursor-based pagination. */
@@ -39,29 +39,50 @@ declare function paginateByCursor<T extends ListQuery>(query: T, config?: Pagina
 /** 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;
-    /** Limit. */
+    /** Page size. */
     limit?: number;
 }
 type PagePaginationPage<T extends ListQuery = ListQuery> = {
     items: Awaited<T>;
-    /** Effective page number. */
+    /** Effective page number, 1-based. */
     page: number;
-    /** Effective limit. Number of items is guaranteed to be less or equal. */
+    /** Effective page size. Number of items is guaranteed to be less than or equal to this value. */
     limit: number;
-    /** Offset of the first item, 1-based. */
+    /** Offset passed to the query, 0-based. */
     offset: number;
-    /** Prev page number (if exists). */
+    /** Previous page number, if it exists. */
     prevPage?: number;
-    /** Next page number (if exists). */
+    /** Next page number, if it exists. */
     nextPage?: number;
 };
+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?: PaginationConfig, params?: PagePaginationParams): Promise<PagePaginationPage<T>>;
+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?: PaginationConfig): <T extends ListQuery>(query: T, params?: PagePaginationParams) => Promise<PagePaginationPage<T>>;
+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, type SortDir, createCursorPaginator, createPagePaginator, getLimit, 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.js

@@ -91,7 +91,11 @@ async function paginateByCursor(query, config, params) {
   }
   function createItemCursor(item, reverse2) {
     return createDirectedCursor(orderFields.map(([field]) => {
-      return String(getItemValue(item, field));
+      const value = getItemValue(item, field);
+      if (value === void 0) {
+        throw new Error(`Order field "${field}" is missing from the result \u2014 cursor pagination requires every order field to be selected.`);
+      }
+      return String(value);
     }), reverse2);
   }
   const prevCursor = parsedCursor && (parsedCursor.reverse === false || hasContinuation) ? createItemCursor(items[0], true) : void 0;
@@ -117,19 +121,32 @@ function createCursorPaginator(config) {
 // src/paginators/page/paginator.ts
 async function paginateByPage(query, config, params) {
   const limit = getLimit(query, config, params);
-  const page = Math.max(1, params?.page ?? 1);
+  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(limit + 1);
+  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 = items.length > limit;
-  if (hasContinuation) {
+  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, limit, offset, prevPage, nextPage };
+  const result = { items, page, limit, offset, prevPage, nextPage };
+  if (total) {
+    return { ...result, ...total };
+  }
+  return result;
 }
 
 // src/paginators/page/factory.ts

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../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":["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  /** Page cursor, as returned by previous call in prevCursor / nextCursor. */\n  cursor?: string\n  /** Limit. */\n  limit?: number\n}\n\nexport type CursorPaginationPage<T extends ListQuery = ListQuery> = {\n  items: Awaited<T>\n  /** Effective limit. Number of items is guaranteed to be less or equal. */\n  limit: number\n  /** Cursor pointing to previous page. */\n  prevCursor?: string\n  /** Cursor pointing to next page. */\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 interface PagePaginationParams {\n  /** Page, 1-based. */\n  page?: number\n  /** Limit. */\n  limit?: number\n}\n\nexport type PagePaginationPage<T extends ListQuery = ListQuery> = {\n  items: Awaited<T>\n  /** Effective page number. */\n  page: number\n  /** Effective limit. Number of items is guaranteed to be less or equal. */\n  limit: number\n  /** Offset of the first item, 1-based. */\n  offset: number\n  /** Prev page number (if exists). */\n  prevPage?: number\n  /** Next page number (if exists). */\n  nextPage?: number\n}\n\n/** paginateByPage returns one page of results using offset-based pagination. */\nexport async function paginateByPage<T extends ListQuery>(query: T, config?: PaginationConfig, params?: PagePaginationParams): Promise<PagePaginationPage<T>> {\n  const limit = getLimit(query, config, params)\n\n  const page = Math.max(1, params?.page ?? 1)\n  const offset = (page - 1) * limit\n\n  const items = await (query as ListQuery).offset(offset).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\n  const prevPage = page > 1 ? page - 1 : undefined\n  const nextPage = hasContinuation ? page + 1 : undefined\n\n  return { items, page, limit, offset, prevPage, nextPage }\n}\n","import type { PaginationConfig } from \"../../limit\"\nimport type { ListQuery } from \"../../types\"\n\nimport { type PagePaginationParams, paginateByPage } from \"./paginator\"\n\n/** createPagePaginator creates a reusable page paginator with the given config. */\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"],"mappings":"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","names":["reverse"]}
+{"version":3,"sources":["../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":["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      const value = getItemValue(item, field)\n      // A missing order field (undefined) means it wasn't selected; encoding it would\n      // produce a broken cursor that later fails deep inside the database. A legitimate\n      // NULL value is fine and gets encoded as usual.\n      if (value === undefined) {\n        throw new Error(`Order field \"${field}\" is missing from the result — cursor pagination requires every order field to be selected.`)\n      }\n      // Can add custom serializer here if needed.\n      return String(value)\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":"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","names":["reverse"]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "orchid-pagination",
   "type": "module",
-  "version": "2.0.0",
+  "version": "2.1.1",
   "packageManager": "bun@1.3.14",
   "description": "Orchid ORM query pagination helpers",
   "author": "Ilya Semenov",

package/src/paginators/cursor/paginator.test.ts

@@ -9,6 +9,20 @@ describe("paginateByCursor", () => {
     await expect(paginateByCursor(db.user.all(), { limit: 2 })).rejects.toThrow("Query must be ordered.")
   })
 
+  test("throws when an order field is not selected", async () => {
+    await seedUsers([
+      { id: 1, name: "a", score: 10, group: "one" },
+      { id: 2, name: "b", score: 20, group: "one" },
+    ])
+
+    // score is ordered by but not selected, so it's missing from the result rows.
+    const query = db.user.select("id", "name").order({ score: "DESC", id: "DESC" })
+
+    await expect(paginateByCursor(query, { limit: 1 })).rejects.toThrow(
+      "Order field \"score\" is missing from the result — cursor pagination requires every order field to be selected.",
+    )
+  })
+
   test("paginates forward with single-field ascending order", async () => {
     await seedUsers([
       { id: 1, name: "a", score: 10, group: "one" },

package/src/paginators/cursor/paginator.ts

@@ -5,19 +5,19 @@ import { createDirectedCursor, parseDirectedCursor } from "./cursor"
 import { getQueryOrderFields } from "./order"
 
 export interface CursorPaginationParams {
-  /** Page cursor, as returned by previous call in prevCursor / nextCursor. */
+  /** Cursor returned as prevCursor or nextCursor by a previous call. */
   cursor?: string
-  /** Limit. */
+  /** Page size. */
   limit?: number
 }
 
 export type CursorPaginationPage<T extends ListQuery = ListQuery> = {
   items: Awaited<T>
-  /** Effective limit. Number of items is guaranteed to be less or equal. */
+  /** Effective page size. Number of items is guaranteed to be less than or equal to this value. */
   limit: number
-  /** Cursor pointing to previous page. */
+  /** 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
 }
 
@@ -72,8 +72,15 @@ export async function paginateByCursor<T extends ListQuery>(query: T, config?: P
 
   function createItemCursor(item: any, reverse: boolean) {
     return createDirectedCursor(orderFields.map(([field]) => {
+      const value = getItemValue(item, field)
+      // A missing order field (undefined) means it wasn't selected; encoding it would
+      // produce a broken cursor that later fails deep inside the database. A legitimate
+      // NULL value is fine and gets encoded as usual.
+      if (value === undefined) {
+        throw new Error(`Order field "${field}" is missing from the result — cursor pagination requires every order field to be selected.`)
+      }
       // Can add custom serializer here if needed.
-      return String(getItemValue(item, field))
+      return String(value)
     }), reverse)
   }
 

package/src/paginators/page/factory.test.ts

@@ -1,8 +1,9 @@
-import { describe, expect, test } from "bun:test"
+import { describe, expect, expectTypeOf, test } from "bun:test"
 
 import { db, getIds, seedUsers } from "#testing"
 
 import { createPagePaginator } from "./factory"
+import type { PagePaginationPage, PagePaginationPageWithTotal } from "./paginator"
 
 describe("createPagePaginator", () => {
   test("creates a reusable paginator with config", async () => {
@@ -18,4 +19,34 @@ describe("createPagePaginator", () => {
     expect(getIds(page.items)).toEqual([1, 2])
     expect(page.nextPage).toBe(2)
   })
+
+  test("creates a reusable paginator with total: true", async () => {
+    await seedUsers([
+      { id: 1, name: "a", score: 10, group: "one" },
+      { id: 2, name: "b", score: 20, group: "one" },
+      { id: 3, name: "c", score: 30, group: "one" },
+    ])
+
+    const paginate = createPagePaginator({ limit: 2, total: true })
+    const page = await paginate(db.user.order({ id: "ASC" }))
+
+    expect(getIds(page.items)).toEqual([1, 2])
+    expect(page).toMatchObject({ page: 1, limit: 2, offset: 0, nextPage: 2, totalItems: 3, totalPages: 2 })
+    expect(page.prevPage).toBeUndefined()
+  })
+
+  test("without total returns PagePaginationPage type", () => {
+    const paginate = createPagePaginator({ limit: 10 })
+    const result = paginate(db.user)
+    expectTypeOf(result).resolves.toExtend<PagePaginationPage>()
+    expectTypeOf(result).resolves.not.toExtend<PagePaginationPageWithTotal>()
+  })
+
+  test("with total: true returns PagePaginationPageWithTotal type", () => {
+    const paginate = createPagePaginator({ limit: 10, total: true })
+    const result = paginate(db.user)
+    expectTypeOf(result).resolves.toExtend<PagePaginationPageWithTotal>()
+    expectTypeOf(result).resolves.toHaveProperty("totalItems")
+    expectTypeOf(result).resolves.toHaveProperty("totalPages")
+  })
 })

package/src/paginators/page/factory.ts

@@ -1,10 +1,24 @@
-import type { PaginationConfig } from "../../limit"
 import type { ListQuery } from "../../types"
 
-import { type PagePaginationParams, paginateByPage } from "./paginator"
+import type {
+  PagePaginationConfig,
+  PagePaginationConfigWithTotal,
+  PagePaginationPage,
+  PagePaginationPageWithTotal,
+  PagePaginationParams,
+} from "./paginator"
+import { paginateByPage } from "./paginator"
 
 /** createPagePaginator creates a reusable page paginator with the given config. */
-export function createPagePaginator(config?: PaginationConfig) {
+export function createPagePaginator(config: PagePaginationConfigWithTotal): <T extends ListQuery>(
+  query: T,
+  params?: PagePaginationParams,
+) => Promise<PagePaginationPageWithTotal<T>>
+export function createPagePaginator(config?: PagePaginationConfig): <T extends ListQuery>(
+  query: T,
+  params?: PagePaginationParams,
+) => Promise<PagePaginationPage<T>>
+export function createPagePaginator(config?: PagePaginationConfig | PagePaginationConfigWithTotal) {
   return function paginate<T extends ListQuery>(query: T, params?: PagePaginationParams) {
     return paginateByPage(query, config, params)
   }

package/src/paginators/page/paginator.test.ts

@@ -1,8 +1,8 @@
-import { describe, expect, test } from "bun:test"
+import { describe, expect, expectTypeOf, test } from "bun:test"
 
 import { db, getIds, seedUsers } from "#testing"
 
-import { paginateByPage } from "./paginator"
+import { type PagePaginationPage, type PagePaginationPageWithTotal, paginateByPage } from "./paginator"
 
 describe("paginateByPage", () => {
   test("returns the first page with a next page", async () => {
@@ -61,6 +61,108 @@ describe("paginateByPage", () => {
     expect(page.prevPage).toBeUndefined()
   })
 
+  test("returns empty items for a page beyond available data", async () => {
+    await seedUsers([
+      { id: 1, name: "a", score: 10, group: "one" },
+      { id: 2, name: "b", score: 20, group: "one" },
+      { id: 3, name: "c", score: 30, group: "one" },
+    ])
+
+    // 3 items with limit 2 = 2 pages; requesting page 5
+    const page = await paginateByPage(db.user.order({ id: "ASC" }), { limit: 2 }, { page: 5 })
+
+    expect(page.items).toEqual([])
+    expect(page).toMatchObject({ page: 5, limit: 2, offset: 8, prevPage: 4 })
+    expect(page.nextPage).toBeUndefined()
+  })
+
+  test("with total: true, includes total and totalPages", async () => {
+    await seedUsers([
+      { id: 1, name: "a", score: 10, group: "one" },
+      { id: 2, name: "b", score: 20, group: "one" },
+      { id: 3, name: "c", score: 30, group: "one" },
+      { id: 4, name: "d", score: 40, group: "one" },
+      { id: 5, name: "e", score: 50, group: "one" },
+    ])
+
+    const page = await paginateByPage(db.user.order({ id: "ASC" }), { limit: 2, total: true }, { page: 2 })
+
+    expect(getIds(page.items)).toEqual([3, 4])
+    expect(page).toMatchObject({ page: 2, limit: 2, offset: 2, prevPage: 1, nextPage: 3, totalItems: 5, totalPages: 3 })
+  })
+
+  test("with total: true without clampPage, does not clamp page beyond last", async () => {
+    await seedUsers([
+      { id: 1, name: "a", score: 10, group: "one" },
+      { id: 2, name: "b", score: 20, group: "one" },
+      { id: 3, name: "c", score: 30, group: "one" },
+    ])
+
+    // 3 items with limit 2 = 2 pages; requesting page 10
+    const page = await paginateByPage(db.user.order({ id: "ASC" }), { limit: 2, total: true }, { page: 10 })
+
+    expect(page.items).toEqual([])
+    expect(page).toMatchObject({ page: 10, limit: 2, offset: 18, prevPage: 9, totalItems: 3, totalPages: 2 })
+    expect(page.nextPage).toBeUndefined()
+  })
+
+  test("with total: true and clampPage: true, clamps page to last when requested beyond", async () => {
+    await seedUsers([
+      { id: 1, name: "a", score: 10, group: "one" },
+      { id: 2, name: "b", score: 20, group: "one" },
+      { id: 3, name: "c", score: 30, group: "one" },
+    ])
+
+    // 3 items with limit 2 = 2 pages; requesting page 10
+    const page = await paginateByPage(db.user.order({ id: "ASC" }), { limit: 2, total: true, clampPage: true }, { page: 10 })
+
+    expect(getIds(page.items)).toEqual([3])
+    expect(page).toMatchObject({ page: 2, limit: 2, offset: 2, prevPage: 1, totalItems: 3, totalPages: 2 })
+    expect(page.nextPage).toBeUndefined()
+  })
+
+  test("with total: true, handles empty table", async () => {
+    const page = await paginateByPage(db.user.order({ id: "ASC" }), { limit: 2, total: true })
+
+    expect(page.items).toEqual([])
+    expect(page).toMatchObject({ page: 1, limit: 2, offset: 0, totalItems: 0, totalPages: 1 })
+    expect(page.prevPage).toBeUndefined()
+    expect(page.nextPage).toBeUndefined()
+  })
+
+  test("with total: true, single-page result", async () => {
+    await seedUsers([
+      { id: 1, name: "a", score: 10, group: "one" },
+      { id: 2, name: "b", score: 20, group: "one" },
+    ])
+
+    const page = await paginateByPage(db.user.order({ id: "ASC" }), { limit: 5, total: true })
+
+    expect(getIds(page.items)).toEqual([1, 2])
+    expect(page).toMatchObject({ page: 1, limit: 5, offset: 0, totalItems: 2, totalPages: 1 })
+    expect(page.prevPage).toBeUndefined()
+    expect(page.nextPage).toBeUndefined()
+  })
+
+  test("without total returns PagePaginationPage type", () => {
+    const result = paginateByPage(db.user, { limit: 10 })
+    expectTypeOf(result).resolves.toExtend<PagePaginationPage>()
+    expectTypeOf(result).resolves.not.toExtend<PagePaginationPageWithTotal>()
+  })
+
+  test("with total: true returns PagePaginationPageWithTotal type", () => {
+    const result = paginateByPage(db.user, { limit: 10, total: true })
+    expectTypeOf(result).resolves.toExtend<PagePaginationPageWithTotal>()
+    expectTypeOf(result).resolves.toHaveProperty("totalItems")
+    expectTypeOf(result).resolves.toHaveProperty("totalPages")
+  })
+
+  test("clampPage requires total: true", () => {
+    // @ts-expect-error — clampPage is not valid without total: true
+    paginateByPage(db.user, { limit: 10, clampPage: true })
+    expectTypeOf(paginateByPage<typeof db.user>).toBeCallableWith(db.user, { limit: 10, total: true, clampPage: true })
+  })
+
   test("clamps requested limit by config", async () => {
     await seedUsers([
       { id: 1, name: "a", score: 10, group: "one" },

package/src/paginators/page/paginator.ts

@@ -1,45 +1,104 @@
 import { getLimit, type PaginationConfig } from "../../limit"
 import type { ListQuery } from "../../types"
 
+export 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
+}
+
+export type PagePaginationConfigWithTotal = PagePaginationConfig & {
+  total: true
+  /** When true, requested pages beyond the last are clamped to the last page. */
+  clampPage?: boolean
+}
+
 export interface PagePaginationParams {
-  /** Page, 1-based. */
+  /** Page number, 1-based. */
   page?: number
-  /** Limit. */
+  /** Page size. */
   limit?: number
 }
 
 export type PagePaginationPage<T extends ListQuery = ListQuery> = {
   items: Awaited<T>
-  /** Effective page number. */
+  /** Effective page number, 1-based. */
   page: number
-  /** Effective limit. Number of items is guaranteed to be less or equal. */
+  /** Effective page size. Number of items is guaranteed to be less than or equal to this value. */
   limit: number
-  /** Offset of the first item, 1-based. */
+  /** Offset passed to the query, 0-based. */
   offset: number
-  /** Prev page number (if exists). */
+  /** Previous page number, if it exists. */
   prevPage?: number
-  /** Next page number (if exists). */
+  /** Next page number, if it exists. */
   nextPage?: number
 }
 
+export type PagePaginationTotal = {
+  /** Total number of items across all pages. */
+  totalItems: number
+  /** Total number of pages. */
+  totalPages: number
+}
+
+export type PagePaginationPageWithTotal<T extends ListQuery = ListQuery> = PagePaginationPage<T> & PagePaginationTotal
+
 /** paginateByPage returns one page of results using offset-based pagination. */
-export async function paginateByPage<T extends ListQuery>(query: T, config?: PaginationConfig, params?: PagePaginationParams): Promise<PagePaginationPage<T>> {
+export async function paginateByPage<T extends ListQuery>(
+  query: T,
+  config: PagePaginationConfigWithTotal,
+  params?: PagePaginationParams,
+): Promise<PagePaginationPageWithTotal<T>>
+export async function paginateByPage<T extends ListQuery>(
+  query: T,
+  config?: PagePaginationConfig,
+  params?: PagePaginationParams,
+): Promise<PagePaginationPage<T>>
+export async function paginateByPage<T extends ListQuery>(
+  query: T,
+  config?: PagePaginationConfig | PagePaginationConfigWithTotal,
+  params?: PagePaginationParams,
+) {
   const limit = getLimit(query, config, params)
 
-  const page = Math.max(1, params?.page ?? 1)
+  let page = Math.max(1, params?.page ?? 1)
+
+  let total: PagePaginationTotal | undefined
+  if (config?.total) {
+    const totalItems = await (query as ListQuery).clear("select", "order").count() as number
+    const totalPages = Math.max(1, Math.ceil(totalItems / limit))
+    total = { totalItems, totalPages }
+    if ((config as PagePaginationConfigWithTotal).clampPage) {
+      page = Math.min(page, totalPages)
+    }
+  }
+
   const offset = (page - 1) * limit
 
-  const items = await (query as ListQuery).offset(offset).limit(limit + 1) as Awaited<T>
+  // When total is known, we can request exactly `limit` items;
+  // otherwise, request limit + 1 to detect continuation.
+  const items = await (query as ListQuery)
+    .offset(offset)
+    .limit(total ? limit : limit + 1) as Awaited<T>
   if (!Array.isArray(items)) {
     throw new TypeError("Query must return an array.")
   }
-  const hasContinuation = items.length > limit
-  if (hasContinuation) {
+
+  const hasContinuation = total ? page < total.totalPages : items.length > limit
+  if (items.length > limit) {
     items.splice(limit)
   }
 
   const prevPage = page > 1 ? page - 1 : undefined
   const nextPage = hasContinuation ? page + 1 : undefined
 
-  return { items, page, limit, offset, prevPage, nextPage }
+  const result: PagePaginationPage<T> = { items, page, limit, offset, prevPage, nextPage }
+
+  if (total) {
+    return { ...result, ...total } as PagePaginationPageWithTotal<T>
+  }
+
+  return result
 }