orchid-pagination 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Ilya Semenov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,72 @@
+# orchid-pagination
+
+Pagination helpers for Orchid ORM:
+
+- Page number pagination.
+- Cursor pagination (better for larger datasets).
+
+## Install
+
+```sh
+npm install orchid-pagination
+```
+
+## Page number pagination
+
+```ts
+import { paginateByPage } from "orchid-pagination"
+
+defineEventHandler(async (ctx) => {
+  const query = db.user.where(conditions).order({ name: "ASC", id: "DESC" })
+  const params = getValidatedParams(ctx) // prepare object with { page?, size? }
+  const page = await paginateByPage(query, { pageSize: 10, maxPageSize: 1000 }, ctx.params)
+  return page
+})
+```
+
+Alternatively, pre-create the paginator:
+
+```ts
+import { createPagePaginator } from "orchid-pagination"
+
+const paginate = createPagePaginator({ pageSize: 10, maxPageSize: 1000 })
+
+defineEventHandler(async (ctx) => {
+  const query = db.user.where(conditions).order({ name: "ASC", id: "DESC" })
+  const params = getValidatedParams(ctx) // prepare object with { page?, size? }
+  const page = await paginate(query, params)
+  return page
+})
+```
+
+The page will have `items`, and possibly `nextPage` and/or `prevPage`.
+
+## Cursor pagination
+
+```ts
+import { paginateByCursor } from "orchid-pagination"
+
+defineEventHandler(async (ctx) => {
+  const query = db.user.where(conditions).order({ name: "ASC", id: "DESC" })
+  const params = getValidatedParams(ctx) // prepare object with { cursor?, size? }
+  const page = await paginateByCursor(query, { pageSize: 10, maxPageSize: 1000 }, ctx.params)
+  return page
+})
+```
+
+Alternatively, pre-create the paginator:
+
+```ts
+import { createCursorPagination } from "orchid-pagination"
+
+const paginate = createCursorPagination({ pageSize: 10, maxPageSize: 1000 })
+
+defineEventHandler(async (ctx) => {
+  const query = db.user.where(conditions).order({ name: "ASC", id: "DESC" })
+  const params = getValidatedParams(ctx) // prepare object with { cursor?, size? }
+  const page = await paginate(query, params)
+  return page
+})
+```
+
+The page will have `items`, and possibly `nextCursor` and/or `prevCursor` which should be sent in subsequent calls to paginate forth and back.

package/dist/index.cjs

@@ -0,0 +1,156 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  createCursorPaginator: () => createCursorPaginator,
+  createPagePaginator: () => createPagePaginator,
+  getPageSize: () => getPageSize,
+  paginateByCursor: () => paginateByCursor,
+  paginateByPage: () => paginateByPage
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/base.ts
+function getPageSize(query, config, params) {
+  const queryLimit = query.q.limit;
+  const maxPageSize = config?.maxPageSize ?? config?.pageSize ?? queryLimit;
+  if (!maxPageSize) {
+    throw new Error("Set query limit, config.maxPageSize, config.pageSize or params.limit.");
+  }
+  return Math.max(1, Math.min(params?.size ?? config?.pageSize ?? maxPageSize, maxPageSize));
+}
+
+// src/cursor.ts
+var import_orchid_orm = require("orchid-orm");
+
+// src/cursor/utils.ts
+var import_node_buffer = require("buffer");
+function getQueryOrderFields(query) {
+  const orderFields = query.q.order?.flatMap((orderItem) => {
+    if (typeof orderItem === "string") {
+      return [[orderItem, true]];
+    } else if (typeof orderItem === "object") {
+      return Object.entries(orderItem).map(([field, order]) => {
+        if (order === "ASC" || order === "DESC") {
+          return [field, order === "ASC"];
+        } else {
+          throw new Error("Unsupported order: " + order);
+        }
+      });
+    } else {
+      throw new TypeError("Unsupported order type: " + orderItem);
+    }
+  });
+  if (!orderFields?.length) {
+    throw new Error("Query must be ordered.");
+  }
+  return orderFields;
+}
+function createCursor(parts) {
+  return import_node_buffer.Buffer.from(parts.map(String).join(String.fromCharCode(0))).toString("base64url");
+}
+function parseCursor(cursor) {
+  return import_node_buffer.Buffer.from(cursor, "base64url").toString().split(String.fromCharCode(0));
+}
+function createDirectedCursor(parts, reverse) {
+  const cursor = createCursor(parts);
+  return reverse ? "-" + cursor : cursor;
+}
+function parseDirectedCursor(directedCursor) {
+  const [cursor, reverse] = directedCursor.startsWith("-") ? [directedCursor.slice(1), true] : [directedCursor, false];
+  return { cursor, parts: parseCursor(cursor), reverse };
+}
+
+// src/cursor.ts
+async function createCursorPaginator(config) {
+  return function paginate(query, params) {
+    return paginateByCursor(query, config, params);
+  };
+}
+async function paginateByCursor(query, config, params) {
+  const size = getPageSize(query, config, params);
+  const orderFields = getQueryOrderFields(query);
+  const parsedCursorMaybeValid = params?.cursor ? parseDirectedCursor(params.cursor) : void 0;
+  const parsedCursor = parsedCursorMaybeValid && parsedCursorMaybeValid.parts.length >= orderFields.length ? parsedCursorMaybeValid : void 0;
+  const reverse = parsedCursor?.reverse ?? false;
+  if (reverse) {
+    orderFields.forEach((of) => {
+      of[1] = !of[1];
+    });
+    const orderArg = Object.fromEntries(orderFields.map(([field, asc]) => [field, asc ? "ASC" : "DESC"]));
+    query = query.clear("order").order(orderArg);
+  }
+  if (parsedCursor) {
+    const leftSqlExpr = orderFields.map(([field, asc]) => asc ? field : `$${field}`).join(",");
+    const rightSqlExp = orderFields.map(([field, asc]) => asc ? `$${field}` : field).join(",");
+    const sqlExpr = `(${leftSqlExpr}) > (${rightSqlExp})`;
+    const values = Object.fromEntries(orderFields.map(([field], i) => [field, parsedCursor.parts[i]]));
+    query = query.where((0, import_orchid_orm.raw)({ raw: sqlExpr, values }));
+  }
+  const items = await query.limit(size + 1);
+  if (!Array.isArray(items)) {
+    throw new TypeError("Query must return an array.");
+  }
+  const hasContinuation = items.length > size;
+  if (hasContinuation) {
+    items.splice(size);
+  }
+  if (reverse) {
+    items.reverse();
+  }
+  function createItemCursor(item, reverse2) {
+    return createDirectedCursor(orderFields.map(([field]) => {
+      return String(item[field]);
+    }), reverse2);
+  }
+  const prevCursor = parsedCursor && (parsedCursor.reverse === false || hasContinuation) ? createItemCursor(items[0], true) : void 0;
+  const nextCursor = parsedCursor?.reverse === true || hasContinuation ? createItemCursor(items.at(-1), false) : void 0;
+  return { items, size, prevCursor, nextCursor };
+}
+
+// src/page.ts
+function createPagePaginator(config) {
+  return function paginate(query, params) {
+    return paginateByPage(query, config, params);
+  };
+}
+async function paginateByPage(query, config, params) {
+  const size = getPageSize(query, config, params);
+  const page = Math.max(1, params?.page ?? 1);
+  const offset = (page - 1) * size;
+  const items = await query.offset(offset).limit(size + 1);
+  const hasContinuation = items.length > size;
+  if (hasContinuation) {
+    items.splice(size);
+  }
+  const prevPage = page > 1 ? page - 1 : void 0;
+  const nextPage = hasContinuation ? page + 1 : void 0;
+  return { items, page, size, offset, prevPage, nextPage };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createCursorPaginator,
+  createPagePaginator,
+  getPageSize,
+  paginateByCursor,
+  paginateByPage
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/base.ts","../src/cursor.ts","../src/cursor/utils.ts","../src/page.ts"],"sourcesContent":["export * from \"./base\"\nexport * from \"./cursor\"\nexport * from \"./page\"\n","import type { Query, QueryThen, SelectQueryData } from \"orchid-orm\"\n\nexport interface ListQuery extends Query {\n  then: QueryThen<unknown[]>\n}\n\nexport interface PaginationConfig {\n  /** Default page size. If not set, `maxPageSize` is used. */\n  pageSize?: number\n  /** Max page size allowed to be passed in params. If not set, `pageSize` is used. */\n  maxPageSize?: number\n}\n\nexport interface PaginationParams {\n  /** Requested page size. */\n  size?: number\n}\n\nexport function getPageSize(query: ListQuery, config?: PaginationConfig, params?: PaginationParams): number {\n  const queryLimit = (query.q as SelectQueryData).limit\n\n  const maxPageSize = config?.maxPageSize ?? config?.pageSize ?? queryLimit\n  if (!maxPageSize) {\n    throw new Error(\"Set query limit, config.maxPageSize, config.pageSize or params.limit.\")\n  }\n\n  return Math.max(1, Math.min(params?.size ?? config?.pageSize ?? maxPageSize, maxPageSize))\n}\n","import type { SortDir } from \"orchid-orm\"\nimport { raw } from \"orchid-orm\"\n\nimport type { ListQuery, PaginationConfig } from \"./base\"\nimport { getPageSize } from \"./base\"\nimport { createDirectedCursor, getQueryOrderFields, parseDirectedCursor } from \"./cursor/utils\"\n\nexport interface CursorPaginationParams {\n  /** Page cursor, as returned by previous call in prevCursor / nextCursor. */\n  cursor?: string\n  /** Page size. */\n  size?: number\n}\n\nexport type CursorPaginationPage<T extends ListQuery = ListQuery> = {\n  items: Awaited<T>\n  /** Effective page size. Number of items is guaranteed to be less or equal. */\n  size: number\n  /** Cursor pointing to previous page. */\n  prevCursor?: string\n  /** Cursor pointing to next page. */\n  nextCursor?: string\n}\n\nexport async function createCursorPaginator(config?: PaginationConfig) {\n  return function paginate<T extends ListQuery>(query: T, params?: CursorPaginationParams) {\n    return paginateByCursor(query, config, params)\n  }\n}\n\nexport async function paginateByCursor<T extends ListQuery>(query: T, config?: PaginationConfig, params?: CursorPaginationParams): Promise<CursorPaginationPage<T>> {\n  const size = getPageSize(query, config, params)\n\n  const orderFields = getQueryOrderFields(query)\n\n  // poor man validation, TODO improve\n  const parsedCursorMaybeValid = params?.cursor ? parseDirectedCursor(params.cursor) : undefined\n  const parsedCursor = parsedCursorMaybeValid && parsedCursorMaybeValid.parts.length >= orderFields.length ? parsedCursorMaybeValid : undefined\n\n  const reverse = parsedCursor?.reverse ?? false\n\n  if (reverse) {\n    // Reverse parsed order fields + reverse query ordering.\n    orderFields.forEach((of) => {\n      of[1] = !of[1]\n    })\n    const orderArg = Object.fromEntries(orderFields.map<[string, SortDir]>(([field, asc]) => [field, asc ? \"ASC\" : \"DESC\"]))\n    query = query.clear(\"order\").order(orderArg as any)\n  }\n\n  if (parsedCursor) {\n    // Prepare raw SQL.\n    // For example, for (amount asc, id asc) order, that would be:\n    // (amount, $id) >= ($amount, id)\n    const leftSqlExpr = orderFields.map(([field, asc]) => asc ? field : `$${field}`).join(\",\")\n    const rightSqlExp = orderFields.map(([field, asc]) => asc ? `$${field}` : field).join(\",\")\n    const sqlExpr = `(${leftSqlExpr}) > (${rightSqlExp})`\n    const values = Object.fromEntries(orderFields.map(([field], i) => [field, parsedCursor.parts[i]]))\n    query = query.where(raw({ raw: sqlExpr, values }))\n  }\n\n  // Query 1 extra item to see if we can paginate farther in current direction.\n  const items = await query.limit(size + 1)\n  if (!Array.isArray(items)) {\n    throw new TypeError(\"Query must return an array.\")\n  }\n  const hasContinuation = items.length > size\n  if (hasContinuation) {\n    items.splice(size)\n  }\n  if (reverse) {\n    items.reverse()\n  }\n\n  function createItemCursor(item: any, reverse: boolean) {\n    return createDirectedCursor(orderFields.map(([field]) => {\n      // Can add custom serializer here if needed.\n      return String(item[field])\n    }), reverse)\n  }\n\n  // Prev cursor:\n  // - for initial pagination, there is no prev page\n  // - for forward pagination, prev page exists always\n  // - for reverse pagination, prev page exists if we have a continuation\n  const prevCursor = (parsedCursor && (parsedCursor.reverse === false || hasContinuation))\n    ? createItemCursor(items[0], true)\n    : undefined\n\n  // Next cursor:\n  // - for reverse pagination, next page exists always\n  // - for initial or forward pagination, next page exists if we have a continuation\n  const nextCursor = (parsedCursor?.reverse === true || hasContinuation)\n    ? createItemCursor(items.at(-1), false)\n    : undefined\n\n  return { items, size, prevCursor, nextCursor }\n}\n","import { Buffer } from \"node:buffer\"\n\nimport type { SelectQueryData } from \"orchid-orm\"\n\nimport type { ListQuery } from \"../base\"\n\ntype OrderField = [field: string, asc: boolean]\n\nexport function getQueryOrderFields(query: ListQuery): OrderField[] {\n  const orderFields = (query.q as SelectQueryData).order?.flatMap<[field: string, asc: boolean]>((orderItem) => {\n    if (typeof orderItem === \"string\") {\n      return [[orderItem, true]]\n    } else if (typeof orderItem === \"object\") {\n      return Object.entries(orderItem).map<[string, boolean]>(([field, order]) => {\n        if (order === \"ASC\" || order === \"DESC\") {\n          return [field, order === \"ASC\"]\n        } else {\n          throw new Error(\"Unsupported order: \" + order)\n        }\n      })\n    } else {\n      throw new TypeError(\"Unsupported order type: \" + orderItem)\n    }\n  })\n  if (!orderFields?.length) {\n    throw new Error(\"Query must be ordered.\")\n  }\n  return orderFields\n}\n\nexport function createCursor(parts: string[]) {\n  return Buffer.from(parts.map(String).join(String.fromCharCode(0))).toString(\"base64url\")\n}\n\nexport function parseCursor(cursor: string) {\n  return Buffer.from(cursor, \"base64url\").toString().split(String.fromCharCode(0))\n}\n\nexport function createDirectedCursor(parts: string[], reverse: boolean) {\n  const cursor = createCursor(parts)\n  return reverse ? \"-\" + cursor : cursor\n}\n\nexport function parseDirectedCursor(directedCursor: string) {\n  const [cursor, reverse] = directedCursor.startsWith(\"-\") ? [directedCursor.slice(1), true] : [directedCursor, false]\n  return { cursor, parts: parseCursor(cursor), reverse }\n}\n","import { getPageSize, type ListQuery, type PaginationConfig } from \"./base\"\n\nexport interface PagePaginationParams {\n  /** Page, 1-based. */\n  page?: number\n  /** Page size. */\n  size?: number\n}\n\nexport type PagePaginationPage<T extends ListQuery = ListQuery> = {\n  items: Awaited<T>\n  /** Effective page number. */\n  page: number\n  /** Effective page size. Number of items is guaranteed to be less or equal. */\n  size: number\n  /** Offset of the first item, 1-based. */\n  offset: number\n  /** Prev page numberm (if exists). */\n  prevPage?: number\n  /** Next page number (if exists). */\n  nextPage?: number\n}\n\nexport function createPagePaginator(config?: PaginationConfig) {\n  return function paginate<T extends ListQuery>(query: T, params?: PagePaginationParams) {\n    return paginateByPage(query, config, params)\n  }\n}\n\nexport async function paginateByPage<T extends ListQuery>(query: T, config?: PaginationConfig, params?: PagePaginationParams): Promise<PagePaginationPage<T>> {\n  const size = getPageSize(query, config, params)\n\n  const page = Math.max(1, params?.page ?? 1)\n  const offset = (page - 1) * size\n\n  const items = await query.offset(offset).limit(size + 1)\n  const hasContinuation = items.length > size\n  if (hasContinuation) {\n    items.splice(size)\n  }\n\n  const prevPage = page > 1 ? page - 1 : undefined\n  const nextPage = hasContinuation ? page + 1 : undefined\n\n  return { items, page, size, offset, prevPage, nextPage }\n}\n"],"mappings":"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","names":["reverse"]}

package/dist/index.d.cts

@@ -0,0 +1,58 @@
+import { Query, QueryThen } from 'orchid-orm';
+
+interface ListQuery extends Query {
+    then: QueryThen<unknown[]>;
+}
+interface PaginationConfig {
+    /** Default page size. If not set, `maxPageSize` is used. */
+    pageSize?: number;
+    /** Max page size allowed to be passed in params. If not set, `pageSize` is used. */
+    maxPageSize?: number;
+}
+interface PaginationParams {
+    /** Requested page size. */
+    size?: number;
+}
+declare function getPageSize(query: ListQuery, config?: PaginationConfig, params?: PaginationParams): number;
+
+interface CursorPaginationParams {
+    /** Page cursor, as returned by previous call in prevCursor / nextCursor. */
+    cursor?: string;
+    /** Page size. */
+    size?: number;
+}
+type CursorPaginationPage<T extends ListQuery = ListQuery> = {
+    items: Awaited<T>;
+    /** Effective page size. Number of items is guaranteed to be less or equal. */
+    size: number;
+    /** Cursor pointing to previous page. */
+    prevCursor?: string;
+    /** Cursor pointing to next page. */
+    nextCursor?: string;
+};
+declare function createCursorPaginator(config?: PaginationConfig): Promise<(<T extends ListQuery>(query: T, params?: CursorPaginationParams) => Promise<CursorPaginationPage<T>>)>;
+declare function paginateByCursor<T extends ListQuery>(query: T, config?: PaginationConfig, params?: CursorPaginationParams): Promise<CursorPaginationPage<T>>;
+
+interface PagePaginationParams {
+    /** Page, 1-based. */
+    page?: number;
+    /** Page size. */
+    size?: number;
+}
+type PagePaginationPage<T extends ListQuery = ListQuery> = {
+    items: Awaited<T>;
+    /** Effective page number. */
+    page: number;
+    /** Effective page size. Number of items is guaranteed to be less or equal. */
+    size: number;
+    /** Offset of the first item, 1-based. */
+    offset: number;
+    /** Prev page numberm (if exists). */
+    prevPage?: number;
+    /** Next page number (if exists). */
+    nextPage?: number;
+};
+declare function createPagePaginator(config?: PaginationConfig): <T extends ListQuery>(query: T, params?: PagePaginationParams) => Promise<PagePaginationPage<T>>;
+declare function paginateByPage<T extends ListQuery>(query: T, config?: PaginationConfig, params?: PagePaginationParams): Promise<PagePaginationPage<T>>;
+
+export { type CursorPaginationPage, type CursorPaginationParams, type ListQuery, type PagePaginationPage, type PagePaginationParams, type PaginationConfig, type PaginationParams, createCursorPaginator, createPagePaginator, getPageSize, paginateByCursor, paginateByPage };

package/dist/index.d.ts

@@ -0,0 +1,58 @@
+import { Query, QueryThen } from 'orchid-orm';
+
+interface ListQuery extends Query {
+    then: QueryThen<unknown[]>;
+}
+interface PaginationConfig {
+    /** Default page size. If not set, `maxPageSize` is used. */
+    pageSize?: number;
+    /** Max page size allowed to be passed in params. If not set, `pageSize` is used. */
+    maxPageSize?: number;
+}
+interface PaginationParams {
+    /** Requested page size. */
+    size?: number;
+}
+declare function getPageSize(query: ListQuery, config?: PaginationConfig, params?: PaginationParams): number;
+
+interface CursorPaginationParams {
+    /** Page cursor, as returned by previous call in prevCursor / nextCursor. */
+    cursor?: string;
+    /** Page size. */
+    size?: number;
+}
+type CursorPaginationPage<T extends ListQuery = ListQuery> = {
+    items: Awaited<T>;
+    /** Effective page size. Number of items is guaranteed to be less or equal. */
+    size: number;
+    /** Cursor pointing to previous page. */
+    prevCursor?: string;
+    /** Cursor pointing to next page. */
+    nextCursor?: string;
+};
+declare function createCursorPaginator(config?: PaginationConfig): Promise<(<T extends ListQuery>(query: T, params?: CursorPaginationParams) => Promise<CursorPaginationPage<T>>)>;
+declare function paginateByCursor<T extends ListQuery>(query: T, config?: PaginationConfig, params?: CursorPaginationParams): Promise<CursorPaginationPage<T>>;
+
+interface PagePaginationParams {
+    /** Page, 1-based. */
+    page?: number;
+    /** Page size. */
+    size?: number;
+}
+type PagePaginationPage<T extends ListQuery = ListQuery> = {
+    items: Awaited<T>;
+    /** Effective page number. */
+    page: number;
+    /** Effective page size. Number of items is guaranteed to be less or equal. */
+    size: number;
+    /** Offset of the first item, 1-based. */
+    offset: number;
+    /** Prev page numberm (if exists). */
+    prevPage?: number;
+    /** Next page number (if exists). */
+    nextPage?: number;
+};
+declare function createPagePaginator(config?: PaginationConfig): <T extends ListQuery>(query: T, params?: PagePaginationParams) => Promise<PagePaginationPage<T>>;
+declare function paginateByPage<T extends ListQuery>(query: T, config?: PaginationConfig, params?: PagePaginationParams): Promise<PagePaginationPage<T>>;
+
+export { type CursorPaginationPage, type CursorPaginationParams, type ListQuery, type PagePaginationPage, type PagePaginationParams, type PaginationConfig, type PaginationParams, createCursorPaginator, createPagePaginator, getPageSize, paginateByCursor, paginateByPage };

package/dist/index.js

@@ -0,0 +1,125 @@
+// src/base.ts
+function getPageSize(query, config, params) {
+  const queryLimit = query.q.limit;
+  const maxPageSize = config?.maxPageSize ?? config?.pageSize ?? queryLimit;
+  if (!maxPageSize) {
+    throw new Error("Set query limit, config.maxPageSize, config.pageSize or params.limit.");
+  }
+  return Math.max(1, Math.min(params?.size ?? config?.pageSize ?? maxPageSize, maxPageSize));
+}
+
+// src/cursor.ts
+import { raw } from "orchid-orm";
+
+// src/cursor/utils.ts
+import { Buffer } from "node:buffer";
+function getQueryOrderFields(query) {
+  const orderFields = query.q.order?.flatMap((orderItem) => {
+    if (typeof orderItem === "string") {
+      return [[orderItem, true]];
+    } else if (typeof orderItem === "object") {
+      return Object.entries(orderItem).map(([field, order]) => {
+        if (order === "ASC" || order === "DESC") {
+          return [field, order === "ASC"];
+        } else {
+          throw new Error("Unsupported order: " + order);
+        }
+      });
+    } else {
+      throw new TypeError("Unsupported order type: " + orderItem);
+    }
+  });
+  if (!orderFields?.length) {
+    throw new Error("Query must be ordered.");
+  }
+  return orderFields;
+}
+function createCursor(parts) {
+  return Buffer.from(parts.map(String).join(String.fromCharCode(0))).toString("base64url");
+}
+function parseCursor(cursor) {
+  return Buffer.from(cursor, "base64url").toString().split(String.fromCharCode(0));
+}
+function createDirectedCursor(parts, reverse) {
+  const cursor = createCursor(parts);
+  return reverse ? "-" + cursor : cursor;
+}
+function parseDirectedCursor(directedCursor) {
+  const [cursor, reverse] = directedCursor.startsWith("-") ? [directedCursor.slice(1), true] : [directedCursor, false];
+  return { cursor, parts: parseCursor(cursor), reverse };
+}
+
+// src/cursor.ts
+async function createCursorPaginator(config) {
+  return function paginate(query, params) {
+    return paginateByCursor(query, config, params);
+  };
+}
+async function paginateByCursor(query, config, params) {
+  const size = getPageSize(query, config, params);
+  const orderFields = getQueryOrderFields(query);
+  const parsedCursorMaybeValid = params?.cursor ? parseDirectedCursor(params.cursor) : void 0;
+  const parsedCursor = parsedCursorMaybeValid && parsedCursorMaybeValid.parts.length >= orderFields.length ? parsedCursorMaybeValid : void 0;
+  const reverse = parsedCursor?.reverse ?? false;
+  if (reverse) {
+    orderFields.forEach((of) => {
+      of[1] = !of[1];
+    });
+    const orderArg = Object.fromEntries(orderFields.map(([field, asc]) => [field, asc ? "ASC" : "DESC"]));
+    query = query.clear("order").order(orderArg);
+  }
+  if (parsedCursor) {
+    const leftSqlExpr = orderFields.map(([field, asc]) => asc ? field : `$${field}`).join(",");
+    const rightSqlExp = orderFields.map(([field, asc]) => asc ? `$${field}` : field).join(",");
+    const sqlExpr = `(${leftSqlExpr}) > (${rightSqlExp})`;
+    const values = Object.fromEntries(orderFields.map(([field], i) => [field, parsedCursor.parts[i]]));
+    query = query.where(raw({ raw: sqlExpr, values }));
+  }
+  const items = await query.limit(size + 1);
+  if (!Array.isArray(items)) {
+    throw new TypeError("Query must return an array.");
+  }
+  const hasContinuation = items.length > size;
+  if (hasContinuation) {
+    items.splice(size);
+  }
+  if (reverse) {
+    items.reverse();
+  }
+  function createItemCursor(item, reverse2) {
+    return createDirectedCursor(orderFields.map(([field]) => {
+      return String(item[field]);
+    }), reverse2);
+  }
+  const prevCursor = parsedCursor && (parsedCursor.reverse === false || hasContinuation) ? createItemCursor(items[0], true) : void 0;
+  const nextCursor = parsedCursor?.reverse === true || hasContinuation ? createItemCursor(items.at(-1), false) : void 0;
+  return { items, size, prevCursor, nextCursor };
+}
+
+// src/page.ts
+function createPagePaginator(config) {
+  return function paginate(query, params) {
+    return paginateByPage(query, config, params);
+  };
+}
+async function paginateByPage(query, config, params) {
+  const size = getPageSize(query, config, params);
+  const page = Math.max(1, params?.page ?? 1);
+  const offset = (page - 1) * size;
+  const items = await query.offset(offset).limit(size + 1);
+  const hasContinuation = items.length > size;
+  if (hasContinuation) {
+    items.splice(size);
+  }
+  const prevPage = page > 1 ? page - 1 : void 0;
+  const nextPage = hasContinuation ? page + 1 : void 0;
+  return { items, page, size, offset, prevPage, nextPage };
+}
+export {
+  createCursorPaginator,
+  createPagePaginator,
+  getPageSize,
+  paginateByCursor,
+  paginateByPage
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/base.ts","../src/cursor.ts","../src/cursor/utils.ts","../src/page.ts"],"sourcesContent":["import type { Query, QueryThen, SelectQueryData } from \"orchid-orm\"\n\nexport interface ListQuery extends Query {\n  then: QueryThen<unknown[]>\n}\n\nexport interface PaginationConfig {\n  /** Default page size. If not set, `maxPageSize` is used. */\n  pageSize?: number\n  /** Max page size allowed to be passed in params. If not set, `pageSize` is used. */\n  maxPageSize?: number\n}\n\nexport interface PaginationParams {\n  /** Requested page size. */\n  size?: number\n}\n\nexport function getPageSize(query: ListQuery, config?: PaginationConfig, params?: PaginationParams): number {\n  const queryLimit = (query.q as SelectQueryData).limit\n\n  const maxPageSize = config?.maxPageSize ?? config?.pageSize ?? queryLimit\n  if (!maxPageSize) {\n    throw new Error(\"Set query limit, config.maxPageSize, config.pageSize or params.limit.\")\n  }\n\n  return Math.max(1, Math.min(params?.size ?? config?.pageSize ?? maxPageSize, maxPageSize))\n}\n","import type { SortDir } from \"orchid-orm\"\nimport { raw } from \"orchid-orm\"\n\nimport type { ListQuery, PaginationConfig } from \"./base\"\nimport { getPageSize } from \"./base\"\nimport { createDirectedCursor, getQueryOrderFields, parseDirectedCursor } from \"./cursor/utils\"\n\nexport interface CursorPaginationParams {\n  /** Page cursor, as returned by previous call in prevCursor / nextCursor. */\n  cursor?: string\n  /** Page size. */\n  size?: number\n}\n\nexport type CursorPaginationPage<T extends ListQuery = ListQuery> = {\n  items: Awaited<T>\n  /** Effective page size. Number of items is guaranteed to be less or equal. */\n  size: number\n  /** Cursor pointing to previous page. */\n  prevCursor?: string\n  /** Cursor pointing to next page. */\n  nextCursor?: string\n}\n\nexport async function createCursorPaginator(config?: PaginationConfig) {\n  return function paginate<T extends ListQuery>(query: T, params?: CursorPaginationParams) {\n    return paginateByCursor(query, config, params)\n  }\n}\n\nexport async function paginateByCursor<T extends ListQuery>(query: T, config?: PaginationConfig, params?: CursorPaginationParams): Promise<CursorPaginationPage<T>> {\n  const size = getPageSize(query, config, params)\n\n  const orderFields = getQueryOrderFields(query)\n\n  // poor man validation, TODO improve\n  const parsedCursorMaybeValid = params?.cursor ? parseDirectedCursor(params.cursor) : undefined\n  const parsedCursor = parsedCursorMaybeValid && parsedCursorMaybeValid.parts.length >= orderFields.length ? parsedCursorMaybeValid : undefined\n\n  const reverse = parsedCursor?.reverse ?? false\n\n  if (reverse) {\n    // Reverse parsed order fields + reverse query ordering.\n    orderFields.forEach((of) => {\n      of[1] = !of[1]\n    })\n    const orderArg = Object.fromEntries(orderFields.map<[string, SortDir]>(([field, asc]) => [field, asc ? \"ASC\" : \"DESC\"]))\n    query = query.clear(\"order\").order(orderArg as any)\n  }\n\n  if (parsedCursor) {\n    // Prepare raw SQL.\n    // For example, for (amount asc, id asc) order, that would be:\n    // (amount, $id) >= ($amount, id)\n    const leftSqlExpr = orderFields.map(([field, asc]) => asc ? field : `$${field}`).join(\",\")\n    const rightSqlExp = orderFields.map(([field, asc]) => asc ? `$${field}` : field).join(\",\")\n    const sqlExpr = `(${leftSqlExpr}) > (${rightSqlExp})`\n    const values = Object.fromEntries(orderFields.map(([field], i) => [field, parsedCursor.parts[i]]))\n    query = query.where(raw({ raw: sqlExpr, values }))\n  }\n\n  // Query 1 extra item to see if we can paginate farther in current direction.\n  const items = await query.limit(size + 1)\n  if (!Array.isArray(items)) {\n    throw new TypeError(\"Query must return an array.\")\n  }\n  const hasContinuation = items.length > size\n  if (hasContinuation) {\n    items.splice(size)\n  }\n  if (reverse) {\n    items.reverse()\n  }\n\n  function createItemCursor(item: any, reverse: boolean) {\n    return createDirectedCursor(orderFields.map(([field]) => {\n      // Can add custom serializer here if needed.\n      return String(item[field])\n    }), reverse)\n  }\n\n  // Prev cursor:\n  // - for initial pagination, there is no prev page\n  // - for forward pagination, prev page exists always\n  // - for reverse pagination, prev page exists if we have a continuation\n  const prevCursor = (parsedCursor && (parsedCursor.reverse === false || hasContinuation))\n    ? createItemCursor(items[0], true)\n    : undefined\n\n  // Next cursor:\n  // - for reverse pagination, next page exists always\n  // - for initial or forward pagination, next page exists if we have a continuation\n  const nextCursor = (parsedCursor?.reverse === true || hasContinuation)\n    ? createItemCursor(items.at(-1), false)\n    : undefined\n\n  return { items, size, prevCursor, nextCursor }\n}\n","import { Buffer } from \"node:buffer\"\n\nimport type { SelectQueryData } from \"orchid-orm\"\n\nimport type { ListQuery } from \"../base\"\n\ntype OrderField = [field: string, asc: boolean]\n\nexport function getQueryOrderFields(query: ListQuery): OrderField[] {\n  const orderFields = (query.q as SelectQueryData).order?.flatMap<[field: string, asc: boolean]>((orderItem) => {\n    if (typeof orderItem === \"string\") {\n      return [[orderItem, true]]\n    } else if (typeof orderItem === \"object\") {\n      return Object.entries(orderItem).map<[string, boolean]>(([field, order]) => {\n        if (order === \"ASC\" || order === \"DESC\") {\n          return [field, order === \"ASC\"]\n        } else {\n          throw new Error(\"Unsupported order: \" + order)\n        }\n      })\n    } else {\n      throw new TypeError(\"Unsupported order type: \" + orderItem)\n    }\n  })\n  if (!orderFields?.length) {\n    throw new Error(\"Query must be ordered.\")\n  }\n  return orderFields\n}\n\nexport function createCursor(parts: string[]) {\n  return Buffer.from(parts.map(String).join(String.fromCharCode(0))).toString(\"base64url\")\n}\n\nexport function parseCursor(cursor: string) {\n  return Buffer.from(cursor, \"base64url\").toString().split(String.fromCharCode(0))\n}\n\nexport function createDirectedCursor(parts: string[], reverse: boolean) {\n  const cursor = createCursor(parts)\n  return reverse ? \"-\" + cursor : cursor\n}\n\nexport function parseDirectedCursor(directedCursor: string) {\n  const [cursor, reverse] = directedCursor.startsWith(\"-\") ? [directedCursor.slice(1), true] : [directedCursor, false]\n  return { cursor, parts: parseCursor(cursor), reverse }\n}\n","import { getPageSize, type ListQuery, type PaginationConfig } from \"./base\"\n\nexport interface PagePaginationParams {\n  /** Page, 1-based. */\n  page?: number\n  /** Page size. */\n  size?: number\n}\n\nexport type PagePaginationPage<T extends ListQuery = ListQuery> = {\n  items: Awaited<T>\n  /** Effective page number. */\n  page: number\n  /** Effective page size. Number of items is guaranteed to be less or equal. */\n  size: number\n  /** Offset of the first item, 1-based. */\n  offset: number\n  /** Prev page numberm (if exists). */\n  prevPage?: number\n  /** Next page number (if exists). */\n  nextPage?: number\n}\n\nexport function createPagePaginator(config?: PaginationConfig) {\n  return function paginate<T extends ListQuery>(query: T, params?: PagePaginationParams) {\n    return paginateByPage(query, config, params)\n  }\n}\n\nexport async function paginateByPage<T extends ListQuery>(query: T, config?: PaginationConfig, params?: PagePaginationParams): Promise<PagePaginationPage<T>> {\n  const size = getPageSize(query, config, params)\n\n  const page = Math.max(1, params?.page ?? 1)\n  const offset = (page - 1) * size\n\n  const items = await query.offset(offset).limit(size + 1)\n  const hasContinuation = items.length > size\n  if (hasContinuation) {\n    items.splice(size)\n  }\n\n  const prevPage = page > 1 ? page - 1 : undefined\n  const nextPage = hasContinuation ? page + 1 : undefined\n\n  return { items, page, size, offset, prevPage, nextPage }\n}\n"],"mappings":"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","names":["reverse"]}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "orchid-pagination",
+  "type": "module",
+  "version": "1.0.0",
+  "description": "Orchid ORM query pagination helpers",
+  "author": "Ilya Semenov",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/IlyaSemenov/orchid-pagination"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "dist/index.cjs",
+  "types": "dist/index.d.ts",
+  "files": [
+    "!src/**/*.test.*",
+    "!src/**/*.tst.*",
+    "dist",
+    "src"
+  ],
+  "peerDependencies": {
+    "@types/node": ">=18",
+    "orchid-orm": "^1.12.0"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.27.10",
+    "@ilyasemenov/eslint-config": "^1.0.1",
+    "@types/node": "^22.10.1",
+    "eslint": "^9.15.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^15.2.10",
+    "tsconfig-vite-node": "^1.1.2",
+    "tstyche": "^3.1.1",
+    "tsup": "^8.3.5",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.5"
+  },
+  "scripts": {
+    "build": "tsup",
+    "lint": "eslint --fix .",
+    "test": "vitest run && tstyche"
+  }
+}

package/src/base.ts

@@ -0,0 +1,28 @@
+import type { Query, QueryThen, SelectQueryData } from "orchid-orm"
+
+export interface ListQuery extends Query {
+  then: QueryThen<unknown[]>
+}
+
+export interface PaginationConfig {
+  /** Default page size. If not set, `maxPageSize` is used. */
+  pageSize?: number
+  /** Max page size allowed to be passed in params. If not set, `pageSize` is used. */
+  maxPageSize?: number
+}
+
+export interface PaginationParams {
+  /** Requested page size. */
+  size?: number
+}
+
+export function getPageSize(query: ListQuery, config?: PaginationConfig, params?: PaginationParams): number {
+  const queryLimit = (query.q as SelectQueryData).limit
+
+  const maxPageSize = config?.maxPageSize ?? config?.pageSize ?? queryLimit
+  if (!maxPageSize) {
+    throw new Error("Set query limit, config.maxPageSize, config.pageSize or params.limit.")
+  }
+
+  return Math.max(1, Math.min(params?.size ?? config?.pageSize ?? maxPageSize, maxPageSize))
+}

package/src/cursor/utils.ts

@@ -0,0 +1,47 @@
+import { Buffer } from "node:buffer"
+
+import type { SelectQueryData } from "orchid-orm"
+
+import type { ListQuery } from "../base"
+
+type OrderField = [field: string, asc: boolean]
+
+export function getQueryOrderFields(query: ListQuery): OrderField[] {
+  const orderFields = (query.q as SelectQueryData).order?.flatMap<[field: string, asc: boolean]>((orderItem) => {
+    if (typeof orderItem === "string") {
+      return [[orderItem, true]]
+    } else if (typeof orderItem === "object") {
+      return Object.entries(orderItem).map<[string, boolean]>(([field, order]) => {
+        if (order === "ASC" || order === "DESC") {
+          return [field, order === "ASC"]
+        } else {
+          throw new Error("Unsupported order: " + order)
+        }
+      })
+    } else {
+      throw new TypeError("Unsupported order type: " + orderItem)
+    }
+  })
+  if (!orderFields?.length) {
+    throw new Error("Query must be ordered.")
+  }
+  return orderFields
+}
+
+export function createCursor(parts: string[]) {
+  return Buffer.from(parts.map(String).join(String.fromCharCode(0))).toString("base64url")
+}
+
+export function parseCursor(cursor: string) {
+  return Buffer.from(cursor, "base64url").toString().split(String.fromCharCode(0))
+}
+
+export function createDirectedCursor(parts: string[], reverse: boolean) {
+  const cursor = createCursor(parts)
+  return reverse ? "-" + cursor : cursor
+}
+
+export function parseDirectedCursor(directedCursor: string) {
+  const [cursor, reverse] = directedCursor.startsWith("-") ? [directedCursor.slice(1), true] : [directedCursor, false]
+  return { cursor, parts: parseCursor(cursor), reverse }
+}

package/src/cursor.ts

@@ -0,0 +1,98 @@
+import type { SortDir } from "orchid-orm"
+import { raw } from "orchid-orm"
+
+import type { ListQuery, PaginationConfig } from "./base"
+import { getPageSize } from "./base"
+import { createDirectedCursor, getQueryOrderFields, parseDirectedCursor } from "./cursor/utils"
+
+export interface CursorPaginationParams {
+  /** Page cursor, as returned by previous call in prevCursor / nextCursor. */
+  cursor?: string
+  /** Page size. */
+  size?: number
+}
+
+export type CursorPaginationPage<T extends ListQuery = ListQuery> = {
+  items: Awaited<T>
+  /** Effective page size. Number of items is guaranteed to be less or equal. */
+  size: number
+  /** Cursor pointing to previous page. */
+  prevCursor?: string
+  /** Cursor pointing to next page. */
+  nextCursor?: string
+}
+
+export async function createCursorPaginator(config?: PaginationConfig) {
+  return function paginate<T extends ListQuery>(query: T, params?: CursorPaginationParams) {
+    return paginateByCursor(query, config, params)
+  }
+}
+
+export async function paginateByCursor<T extends ListQuery>(query: T, config?: PaginationConfig, params?: CursorPaginationParams): Promise<CursorPaginationPage<T>> {
+  const size = getPageSize(query, config, params)
+
+  const orderFields = getQueryOrderFields(query)
+
+  // poor man validation, TODO improve
+  const parsedCursorMaybeValid = params?.cursor ? parseDirectedCursor(params.cursor) : undefined
+  const parsedCursor = parsedCursorMaybeValid && parsedCursorMaybeValid.parts.length >= orderFields.length ? parsedCursorMaybeValid : undefined
+
+  const reverse = parsedCursor?.reverse ?? false
+
+  if (reverse) {
+    // Reverse parsed order fields + reverse query ordering.
+    orderFields.forEach((of) => {
+      of[1] = !of[1]
+    })
+    const orderArg = Object.fromEntries(orderFields.map<[string, SortDir]>(([field, asc]) => [field, asc ? "ASC" : "DESC"]))
+    query = query.clear("order").order(orderArg as any)
+  }
+
+  if (parsedCursor) {
+    // Prepare raw SQL.
+    // For example, for (amount asc, id asc) order, that would be:
+    // (amount, $id) >= ($amount, id)
+    const leftSqlExpr = orderFields.map(([field, asc]) => asc ? field : `$${field}`).join(",")
+    const rightSqlExp = orderFields.map(([field, asc]) => asc ? `$${field}` : field).join(",")
+    const sqlExpr = `(${leftSqlExpr}) > (${rightSqlExp})`
+    const values = Object.fromEntries(orderFields.map(([field], i) => [field, parsedCursor.parts[i]]))
+    query = query.where(raw({ raw: sqlExpr, values }))
+  }
+
+  // Query 1 extra item to see if we can paginate farther in current direction.
+  const items = await query.limit(size + 1)
+  if (!Array.isArray(items)) {
+    throw new TypeError("Query must return an array.")
+  }
+  const hasContinuation = items.length > size
+  if (hasContinuation) {
+    items.splice(size)
+  }
+  if (reverse) {
+    items.reverse()
+  }
+
+  function createItemCursor(item: any, reverse: boolean) {
+    return createDirectedCursor(orderFields.map(([field]) => {
+      // Can add custom serializer here if needed.
+      return String(item[field])
+    }), reverse)
+  }
+
+  // Prev cursor:
+  // - for initial pagination, there is no prev page
+  // - for forward pagination, prev page exists always
+  // - for reverse pagination, prev page exists if we have a continuation
+  const prevCursor = (parsedCursor && (parsedCursor.reverse === false || hasContinuation))
+    ? createItemCursor(items[0], true)
+    : undefined
+
+  // Next cursor:
+  // - for reverse pagination, next page exists always
+  // - for initial or forward pagination, next page exists if we have a continuation
+  const nextCursor = (parsedCursor?.reverse === true || hasContinuation)
+    ? createItemCursor(items.at(-1), false)
+    : undefined
+
+  return { items, size, prevCursor, nextCursor }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from "./base"
+export * from "./cursor"
+export * from "./page"

package/src/page.ts

@@ -0,0 +1,46 @@
+import { getPageSize, type ListQuery, type PaginationConfig } from "./base"
+
+export interface PagePaginationParams {
+  /** Page, 1-based. */
+  page?: number
+  /** Page size. */
+  size?: number
+}
+
+export type PagePaginationPage<T extends ListQuery = ListQuery> = {
+  items: Awaited<T>
+  /** Effective page number. */
+  page: number
+  /** Effective page size. Number of items is guaranteed to be less or equal. */
+  size: number
+  /** Offset of the first item, 1-based. */
+  offset: number
+  /** Prev page numberm (if exists). */
+  prevPage?: number
+  /** Next page number (if exists). */
+  nextPage?: number
+}
+
+export function createPagePaginator(config?: PaginationConfig) {
+  return function paginate<T extends ListQuery>(query: T, params?: PagePaginationParams) {
+    return paginateByPage(query, config, params)
+  }
+}
+
+export async function paginateByPage<T extends ListQuery>(query: T, config?: PaginationConfig, params?: PagePaginationParams): Promise<PagePaginationPage<T>> {
+  const size = getPageSize(query, config, params)
+
+  const page = Math.max(1, params?.page ?? 1)
+  const offset = (page - 1) * size
+
+  const items = await query.offset(offset).limit(size + 1)
+  const hasContinuation = items.length > size
+  if (hasContinuation) {
+    items.splice(size)
+  }
+
+  const prevPage = page > 1 ? page - 1 : undefined
+  const nextPage = hasContinuation ? page + 1 : undefined
+
+  return { items, page, size, offset, prevPage, nextPage }
+}