orchid-pagination 2.1.0 → 2.1.1

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;

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  /** 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":"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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":";;;;;;;;;;;;;;;;;;;;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;AACvD,YAAM,QAAQ,aAAa,MAAM,KAAK;AAItC,UAAI,UAAU,QAAW;AACvB,cAAM,IAAI,MAAM,gBAAgB,KAAK,kGAA6F;AAAA,MACpI;AAEA,aAAO,OAAO,KAAK;AAAA,IACrB,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;;;AC3GO,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.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;

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  /** 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":"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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.1.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

@@ -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)
   }