@visulima/pagination 5.0.0-alpha.12 → 5.0.0-alpha.14

package/CHANGELOG.md

@@ -1,3 +1,28 @@
+## @visulima/pagination [5.0.0-alpha.14](https://github.com/visulima/visulima/compare/@visulima/pagination@5.0.0-alpha.13...@visulima/pagination@5.0.0-alpha.14) (2026-06-13)
+
+### Features
+
+* **pagination:** fix docs, add cursor/window pagination + openapi nullability ([d33feb8](https://github.com/visulima/visulima/commit/d33feb85ad49a1336c55b5ab12a18a80c9a776b0))
+
+### Bug Fixes
+
+* **pagination:** accept rows as an array, not variadic ([f4c3940](https://github.com/visulima/visulima/commit/f4c3940a7c799b32f1639473c01e2d43426f3c0c))
+
+### Miscellaneous Chores
+
+* **pagination:** apply formatting ([52c9c3b](https://github.com/visulima/visulima/commit/52c9c3b312d9e918235e2403918539a653c53a87))
+* **pagination:** reformat long lines and normalize markdown italics ([8467425](https://github.com/visulima/visulima/commit/84674254fb5dcb2fcab600abe3f006b41bfabb88))
+
+## @visulima/pagination [5.0.0-alpha.13](https://github.com/visulima/visulima/compare/@visulima/pagination@5.0.0-alpha.12...@visulima/pagination@5.0.0-alpha.13) (2026-06-04)
+
+### Bug Fixes
+
+* **pagination:** 3 bug fixes ([bcc5dbf](https://github.com/visulima/visulima/commit/bcc5dbf91aac391b3df1d83d6a1850a7b4bdbcc2))
+
+### Miscellaneous Chores
+
+* apply eslint + prettier autofixes across packages ([c1bb784](https://github.com/visulima/visulima/commit/c1bb7848a0d93d0dfe2960c77e3cda22239c79a0))
+
 ## @visulima/pagination [5.0.0-alpha.12](https://github.com/visulima/visulima/compare/@visulima/pagination@5.0.0-alpha.11...@visulima/pagination@5.0.0-alpha.12) (2026-05-27)
 
 ### Bug Fixes

package/LICENSE.md

@@ -23,11 +23,14 @@ SOFTWARE.
 <!-- DEPENDENCIES -->
 
 # Licenses of bundled dependencies
+
 The published @visulima/pagination artifact additionally contains code with the following licenses:
 BSD-3-Clause
 
 # Bundled dependencies:
+
 ## qs-esm
+
 License: BSD-3-Clause
 By: Payload, Jordan Harband
 Repository: https://github.com/payloadcms/qs-esm.git
@@ -42,11 +45,9 @@ Repository: https://github.com/payloadcms/qs-esm.git
 >
 > 1. Redistributions of source code must retain the above copyright notice, this
 >    list of conditions and the following disclaimer.
->
 > 2. Redistributions in binary form must reproduce the above copyright notice,
 >    this list of conditions and the following disclaimer in the documentation
 >    and/or other materials provided with the distribution.
->
 > 3. Neither the name of the copyright holder nor the names of its
 >    contributors may be used to endorse or promote products derived from
 >    this software without specific prior written permission.

package/README.md

@@ -36,6 +36,18 @@
 
 ## Features
 
+- **Zero runtime dependencies** — tiny offset/limit paginator (Adonis-style).
+- **`Paginator`** — an `Array` subclass holding the current page's rows, with rich meta (`total`, `lastPage`, first/last/next/previous URLs).
+- **`CursorPaginator`** — cursor/keyset pagination for stable infinite scroll over large tables.
+- **URL helpers** — `baseUrl()`, `queryString()`, `getUrl()`, `getUrlsForRange()`, and `getUrlsForWindow()` (windowed page links with `…` ellipsis markers).
+- **Naming strategies** — emit `camelCase` (default) or `snake_case` (`per_page`, `last_page`, …) meta keys.
+- **OpenAPI schema builders** — `createPaginationSchemaObject` / `createPaginationMetaSchemaObject`, with correct nullability + `required`, and an OpenAPI 3.1 variant.
+
+> **Important:** `Paginator`/`paginate()` do **not** slice your rows. Pass in the
+> rows for the current page already sliced at the data source
+> (offset `(page - 1) * perPage`, limit `perPage`). `total` is the count of _all_
+> matching records and is what drives `lastPage` and the URLs.
+
 ## Installation
 
 ```sh
@@ -52,30 +64,103 @@ pnpm add @visulima/pagination
 
 ## Usage
 
+`paginate(page, perPage, total, rows)` returns a `Paginator` — an `Array`
+subclass that holds the **current page's rows** (it does not slice them for you).
+Call `.toJSON()` (or `JSON.stringify`) to get the `{ data, meta }` shape.
+
 ```ts
 import { paginate } from "@visulima/pagination";
 
-const items = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+const allItems = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+
+const page = 1;
+const perPage = 5;
 
-const pagination = paginate(1, 5, items.length, items);
+// Slice the rows for the current page yourself (a real app would do this in SQL).
+const pageRows = allItems.slice((page - 1) * perPage, page * perPage);
 
-console.log(pagination);
+const pagination = paginate(page, perPage, allItems.length, pageRows);
+
+console.log(pagination.toJSON());
 // {
 //   data: [1, 2, 3, 4, 5],
 //   meta: {
-//     total: 10,
-//     perPage: 5,
-//     page: 1,
-//     lastPage: 2,
 //     firstPage: 1,
 //     firstPageUrl: "/?page=1",
+//     lastPage: 2,
 //     lastPageUrl: "/?page=2",
 //     nextPageUrl: "/?page=2",
+//     page: 1,
+//     perPage: 5,
 //     previousPageUrl: null,
+//     total: 10,
 //   }
 // }
+
+// Note: `console.log(pagination)` prints just the array rows ([1,2,3,4,5]),
+// because `Paginator` extends `Array`. Use `.toJSON()` / `JSON.stringify` for
+// the full `{ data, meta }` payload.
+```
+
+### URLs and query strings
+
+```ts
+const p = paginate(2, 10, 200, pageRows).baseUrl("/api/items").queryString({ sort: "asc" });
+
+p.getUrl(3); // "/api/items?sort=asc&page=3"
+p.getNextPageUrl(); // "/api/items?sort=asc&page=3"
+p.getPreviousPageUrl(); // "/api/items?sort=asc&page=1"
+
+// Windowed page links with ellipsis markers (page === null => render "…").
+p.getUrlsForWindow({ eachSide: 2 });
+// [ {page:1,...}, {page:null,url:null,...}, ...window..., {page:null,url:null}, {page:20,...} ]
 ```
 
+### snake_case meta (Laravel / AdonisJS style)
+
+```ts
+import { paginate, snakeCaseNamingStrategy } from "@visulima/pagination";
+
+paginate(1, 10, 100, pageRows).getMeta(snakeCaseNamingStrategy);
+// { first_page: 1, per_page: 10, last_page: 10, ... }
+```
+
+### Cursor-based pagination
+
+For stable infinite scroll / keyset pagination over large tables, use
+`CursorPaginator`:
+
+```ts
+import { CursorPaginator } from "@visulima/pagination";
+
+const rows = [{ id: 5 }, { id: 6 }]; // pre-fetched page rows
+
+const p = CursorPaginator.fromArray(2, rows, { currentCursor: "4", hasMore: true }).baseUrl("/api/items");
+
+p.getMeta();
+// {
+//   nextCursor: "6",
+//   nextPageUrl: "/api/items?cursor=6",
+//   perPage: 2,
+//   previousCursor: "5",
+//   previousPageUrl: "/api/items?cursor=5",
+// }
+```
+
+### OpenAPI schemas
+
+```ts
+import { createPaginationMetaSchemaObject, createPaginationSchemaObject } from "@visulima/pagination";
+
+const meta = createPaginationMetaSchemaObject("PaginationData"); // OpenAPI 3.0
+const meta31 = createPaginationMetaSchemaObject("PaginationData", { openApiVersion: "3.1" });
+
+const schema = createPaginationSchemaObject("UserList", { $ref: "#/components/schemas/User" });
+```
+
+`nextPageUrl`/`previousPageUrl` are emitted as nullable (they are `null` on the
+last/first page) and every field is listed in `required`.
+
 ## Supported Node.js Versions
 
 Libraries in this ecosystem make the best effort to track

package/dist/index.d.ts

@@ -1,9 +1,15 @@
 import { OpenAPIV3 } from 'openapi-types';
 interface PaginationMeta {
   firstPage: number;
-  firstPageUrl: string | null;
+  /**
+   * The URL for the first page. Always a string — `getUrl()` never returns null.
+   */
+  firstPageUrl: string;
   lastPage: number;
-  lastPageUrl: string | null;
+  /**
+   * The URL for the last page. Always a string — `getUrl()` never returns null.
+   */
+  lastPageUrl: string;
   nextPageUrl: string | null;
   page: number;
   perPage: number;
@@ -14,12 +20,71 @@ interface PaginationResult<Result> {
   data: Result[];
   meta: PaginationMeta;
 }
+/**
+ * A key-transform applied to {@link PaginationMeta} keys. Return the desired
+ * output key for a given camelCase meta key (e.g. `perPage` -> `per_page`).
+ */
+type NamingStrategy = (key: string) => string;
+/**
+ * A windowed page-range entry. A `null` `page`/`url` represents an ellipsis ("…")
+ * gap that a UI should render between page links.
+ */
+interface WindowedUrl {
+  isActive: boolean;
+  page: number | null;
+  url: string | null;
+}
+interface WindowOptions {
+  eachSide?: number;
+}
+interface CursorPaginatorOptions<T> {
+  /**
+   * The cursor that was used to fetch the current page (e.g. the `cursor`
+   * query parameter), if any. Used to derive `previousCursor`.
+   */
+  currentCursor?: string | null;
+
+  /**
+   * Derives the opaque cursor string for a row. Defaults to `String(row.id)`
+   * when the row has an `id`, otherwise `String(row)`.
+   */
+  getCursor?: (row: T) => string;
+
+  /**
+   * Whether a next page exists. Defaults to `false`.
+   */
+  hasMore?: boolean;
+}
+interface CursorPaginationMeta {
+  nextCursor: string | null;
+  nextPageUrl: string | null;
+  perPage: number;
+  previousCursor: string | null;
+  previousPageUrl: string | null;
+}
+interface CursorPaginationResult<Result> {
+  data: Result[];
+  meta: CursorPaginationMeta;
+}
+interface CursorPaginator$1<Result> extends Array<Result> {
+  all: () => Result[];
+  baseUrl: (url: string) => this;
+  getMeta: () => CursorPaginationMeta;
+  getNextCursor: () => string | null;
+  getPreviousCursor: () => string | null;
+  getUrl: (cursor: string | null) => string | null;
+  readonly hasMorePages: boolean;
+  readonly isEmpty: boolean;
+  readonly perPage: number;
+  queryString: (values: Record<string, unknown>) => this;
+  toJSON: () => CursorPaginationResult<Result>;
+}
 interface Paginator$1<Result> extends Array<Result> {
   all: () => Result[];
   baseUrl: (url: string) => this;
-  readonly currentPage: number;
+  currentPage: number;
   readonly firstPage: number;
-  getMeta: () => PaginationMeta;
+  getMeta: (namingStrategy?: NamingStrategy) => PaginationMeta;
   getNextPageUrl: () => string | null;
   getPreviousPageUrl: () => string | null;
   getUrl: (page: number) => string;
@@ -28,6 +93,7 @@ interface Paginator$1<Result> extends Array<Result> {
     page: number;
     url: string;
   }[];
+  getUrlsForWindow: (options?: WindowOptions) => WindowedUrl[];
   readonly hasMorePages: boolean;
   readonly hasPages: boolean;
   readonly hasTotal: boolean;
@@ -35,22 +101,111 @@ interface Paginator$1<Result> extends Array<Result> {
   readonly lastPage: number;
   readonly perPage: number;
   queryString: (values: Record<string, unknown>) => this;
-  toJSON: () => PaginationResult<Result>;
+  toJSON: (namingStrategy?: NamingStrategy) => PaginationResult<Result>;
   readonly total: number;
 }
+/**
+* Cursor-based paginator for stable infinite-scroll / keyset pagination over
+* large tables. Unlike the offset-based `Paginator`, it exposes opaque
+* `nextCursor` / `previousCursor` values instead of page numbers.
+*
+* Like `Paginator`, the rows you pass are the pre-fetched rows for the current
+* page — they are not sliced. `nextCursor` is derived from the last row via
+* `getCursor`.
+*/
+declare class CursorPaginator<T = unknown> extends Array<T> implements CursorPaginator$1<T> {
+  static override get [Symbol.species](): ArrayConstructor;
+  /**
+  * Construct a `CursorPaginator` from an array of rows without spreading them
+  * as call arguments (safe for large row sets).
+  * @param perPage Rows requested per page (clamped to be at least 1).
+  * @param rows The pre-fetched rows for the current page.
+  * @param options Current cursor, `hasMore` flag and `getCursor` resolver.
+  */
+  static fromArray<Result = unknown>(perPage: number, rows: Result[], options?: CursorPaginatorOptions<Result>): CursorPaginator<Result>;
+  readonly isEmpty: boolean;
+  readonly perPage: number;
+  private url;
+  private qs;
+  private baseQuery;
+  private readonly currentCursor;
+  private readonly getCursor;
+  private readonly hasMore;
+  constructor(perPage: number, options?: CursorPaginatorOptions<T>);
+  /**
+  * A shallow copy of the result rows for the current page (plain `Array`).
+  */
+  all(): T[];
+  /**
+  * Define base url for making the pagination links.
+  */
+  baseUrl(url: string): this;
+  /**
+  * Define query string to be appended to the pagination links.
+  */
+  queryString(values: Record<string, unknown>): this;
+  /**
+  * The cursor pointing at the next page, or `null` when there is no next page.
+  */
+  getNextCursor(): string | null;
+  /**
+  * The cursor pointing at the previous page (the cursor of the first row of
+  * the current page), or `null` when there is no previous page.
+  */
+  getPreviousCursor(): string | null;
+  /**
+  * Returns the url for a given cursor, or `null` when the cursor is `null`.
+  */
+  getUrl(cursor: string | null): string | null;
+  /**
+  * Returns JSON meta data for the cursor page.
+  */
+  getMeta(): CursorPaginationMeta;
+  /**
+  * Returns JSON representation of the paginated data.
+  */
+  toJSON(): CursorPaginationResult<T>;
+  /**
+  * Whether there are more pages to come.
+  */
+  get hasMorePages(): boolean;
+}
 type UrlsForRange = {
   isActive: boolean;
   page: number;
   url: string;
 }[];
 /**
+* Built-in `snake_case` naming strategy. Use it to emit Laravel/AdonisJS-style
+* meta keys (`per_page`, `last_page`, …).
+*/
+declare const snakeCaseNamingStrategy: NamingStrategy;
+/**
 * Simple paginator works with the data set provided by the standard
 * `offset` and `limit` based pagination.
+*
+* `Paginator` is an `Array` subclass that holds **only the rows for the current
+* page**. It does NOT slice the rows you pass in — you are expected to pre-slice
+* the page rows (via your data store's `offset`/`limit`) before constructing it.
+* `total` is the count of *all* matching records, used to compute `lastPage` and
+* the pagination URLs.
 */
 declare class Paginator<T = unknown> extends Array<T> implements Paginator$1<T> {
-  private readonly totalNumber;
-  readonly perPage: number;
-  currentPage: number;
+  /**
+  * Ensure inherited Array methods (map/filter/slice/...) return plain Arrays
+  * instead of partially-constructed Paginator instances.
+  */
+  static override get [Symbol.species](): ArrayConstructor;
+  /**
+  * Construct a `Paginator` from an array of rows. Alias for the array-based
+  * constructor; kept for backward compatibility. Safe for arbitrarily large
+  * row sets (no `Maximum call stack size exceeded`).
+  * @param totalNumber Total number of matching records.
+  * @param perPage Rows per page (clamped to be at least 1).
+  * @param currentPage The current page number (clamped to be at least 1).
+  * @param rows The pre-sliced rows for the current page.
+  */
+  static fromArray<Result = unknown>(totalNumber: number, perPage: number, currentPage: number, rows: Result[]): Paginator<Result>;
   /**
   * The first page is always 1
   */
@@ -59,12 +214,40 @@ declare class Paginator<T = unknown> extends Array<T> implements Paginator$1<T>
   * Find if results set is empty or not
   */
   readonly isEmpty: boolean;
+  /**
+  * Current page number. Always clamped to be at least 1.
+  */
+  currentPage: number;
+  private readonly totalNumber;
+  private readonly perPageNumber;
   private qs;
-  private readonly rows;
   private url;
-  constructor(totalNumber: number, perPage: number, currentPage: number, ...rows: T[]);
   /**
-  * A reference to the result rows.
+  * Pre-serialized query string (without the trailing `page` parameter),
+  * recomputed only when `queryString()` changes. Avoids re-iterating and
+  * re-serializing `this.qs` on every `getUrl()` call in the `getMeta()` hot path.
+  */
+  private baseQuery;
+  /**
+  * The `rows` array is accepted as a single parameter (not spread as call
+  * arguments): spreading rows (`new Paginator(t, p, c, ...rows)`) or
+  * `this.push(...rows)` throws `RangeError: Maximum call stack size exceeded`
+  * around ~100k rows on V8. Index-writing the array avoids that entirely.
+  * @param totalNumber Total number of matching records (used for `lastPage`/URL math).
+  * @param perPage Rows per page (clamped to be at least 1).
+  * @param currentPage The current page number (clamped to be at least 1).
+  * @param rows The pre-sliced rows for the current page. They are NOT sliced by the paginator. Defaults to an empty array.
+  */
+  constructor(totalNumber: number, perPage: number, currentPage: number, rows?: T[]);
+  /**
+  * The number of rows shown per page.
+  */
+  get perPage(): number;
+  /**
+  * A reference to the result rows for the current page.
+  *
+  * Returns a shallow copy so callers cannot mutate the paginator's backing
+  * store, and so the returned value is a plain `Array` (not a `Paginator`).
   */
   all(): T[];
   /**
@@ -72,9 +255,11 @@ declare class Paginator<T = unknown> extends Array<T> implements Paginator$1<T>
   */
   baseUrl(url: string): this;
   /**
-  * Returns JSON meta data.
+  * Returns JSON meta data. Pass `snakeCaseNamingStrategy` for
+  * Laravel/AdonisJS-style output.
+  * @param namingStrategy Optional key-transform applied to every meta key.
   */
-  getMeta(): PaginationMeta;
+  getMeta(namingStrategy?: NamingStrategy): PaginationMeta;
   /**
   * Returns url for the next page.
   */
@@ -85,21 +270,29 @@ declare class Paginator<T = unknown> extends Array<T> implements Paginator$1<T>
   getPreviousPageUrl(): string | null;
   /**
   * Returns url for a given page. Doesn't validate the integrity of the
-  * page.
+  * page (only clamps the page number to be at least 1).
   */
   getUrl(page: number): string;
   /**
-  * Returns an array of urls under a given range.
+  * Returns an array of urls under a given inclusive range.
   */
   getUrlsForRange(start: number, end: number): UrlsForRange;
   /**
+  * Returns a windowed list of page urls centered on the current page, with
+  * `null`-page ellipsis markers for the gaps (e.g. `1 … 4 [5] 6 … 20`).
+  *
+  * Use the `page === null` entries to render an ellipsis ("…") in your UI.
+  */
+  getUrlsForWindow(options?: WindowOptions): WindowedUrl[];
+  /**
   * Define query string to be appended to the pagination links.
   */
   queryString(values: Record<string, unknown>): this;
   /**
   * Returns JSON representation of the paginated data.
+  * @param namingStrategy Optional key-transform applied to the `meta` keys.
   */
-  toJSON(): PaginationResult<T>;
+  toJSON(namingStrategy?: NamingStrategy): PaginationResult<T>;
   /**
   * Find if there are more pages to come.
   */
@@ -126,7 +319,59 @@ declare class Paginator<T = unknown> extends Array<T> implements Paginator$1<T>
   */
   get total(): number;
 }
-declare const createPaginationMetaSchemaObject: (name?: string) => Record<string, OpenAPIV3.SchemaObject>;
-declare const createPaginationSchemaObject: (name: string, items: OpenAPIV3.ReferenceObject | OpenAPIV3.SchemaObject, metaReference?: string) => Record<string, OpenAPIV3.SchemaObject>;
+/**
+* Which OpenAPI version to target. `"3.0"` (default) emits `nullable: true` on
+* nullable URL fields; `"3.1"` emits the JSON-Schema `type: ["string", "null"]`
+* form instead.
+*/
+type OpenApiVersion = "3.0" | "3.1";
+interface CreatePaginationMetaSchemaOptions {
+  /**
+  * Target OpenAPI version. Controls how nullable URL fields are encoded.
+  * Defaults to `"3.0"`.
+  */
+  openApiVersion?: OpenApiVersion;
+}
+interface CreatePaginationSchemaOptions {
+  /**
+  * The `$ref` pointing to the meta schema component.
+  * Defaults to `"#/components/schemas/PaginationData"`.
+  */
+  metaReference?: string;
+}
+/**
+* Builds an OpenAPI schema object describing the `meta` block returned by
+* `Paginator.getMeta()`.
+*
+* `nextPageUrl` and `previousPageUrl` are nullable at runtime (the paginator
+* returns `null` on the first/last page), so they are emitted as nullable.
+* `firstPageUrl`/`lastPageUrl` are always strings. A `required` array is emitted
+* so generated clients treat every field as present. Pass
+* `{ openApiVersion: "3.1" }` to emit JSON-Schema-style nullability.
+* @param name The schema/component name. Defaults to `"PaginationData"`.
+* @param options Schema-building options.
+*/
+declare const createPaginationMetaSchemaObject: (name?: string, options?: CreatePaginationMetaSchemaOptions) => Record<string, OpenAPIV3.SchemaObject>;
+/**
+* Builds an OpenAPI schema object describing a full paginated response
+* (`{ data: Item[], meta: PaginationData }`). Both `data` and `meta` are emitted
+* as `required`.
+* @param name The schema/component name.
+* @param items The schema (or `$ref`) for a single item in `data`.
+* @param metaReferenceOrOptions Either the meta `$ref` string (legacy) or an options object.
+*/
+declare const createPaginationSchemaObject: (name: string, items: OpenAPIV3.ReferenceObject | OpenAPIV3.SchemaObject, metaReferenceOrOptions?: string | CreatePaginationSchemaOptions) => Record<string, OpenAPIV3.SchemaObject>;
+/**
+* Create a {@link PaginatorInterface} for the given page of rows.
+* @remarks
+* The `rows` you pass in are treated as the rows for the current page **as-is** —
+* they are NOT sliced. Pre-slice your rows at the data source using the offset
+* (`(page - 1) * perPage`) and `perPage` limit. `total` is the count of all
+* matching records and drives `lastPage`/URL computation.
+* @param page The current page (clamped to be at least 1).
+* @param perPage Rows per page (clamped to be at least 1).
+* @param total Total number of matching records.
+* @param rows The pre-sliced rows for the current page.
+*/
 declare const paginate: <Result>(page: number, perPage: number, total: number, rows: Result[]) => Paginator$1<Result>;
-export { type PaginationMeta, type PaginationResult, Paginator, type Paginator$1 as PaginatorInterface, createPaginationMetaSchemaObject, createPaginationSchemaObject, paginate };
+export { type CreatePaginationMetaSchemaOptions, type CreatePaginationSchemaOptions, type CursorPaginationMeta, type CursorPaginationResult, CursorPaginator, type CursorPaginator$1 as CursorPaginatorInterface, type CursorPaginatorOptions, type NamingStrategy, type OpenApiVersion, type PaginationMeta, type PaginationResult, Paginator, type Paginator$1 as PaginatorInterface, type WindowOptions, type WindowedUrl, createPaginationMetaSchemaObject, createPaginationSchemaObject, paginate, snakeCaseNamingStrategy };

package/dist/index.js

@@ -1 +1 @@
-var o=Object.defineProperty;var t=(e,a)=>o(e,"name",{value:a,configurable:!0});import i from"./packem_shared/Paginator-Dj-l47Lc.js";import{createPaginationMetaSchemaObject as j,createPaginationSchemaObject as u}from"./packem_shared/createPaginationMetaSchemaObject-DGZPqai2.js";var c=Object.defineProperty,g=t((e,a)=>c(e,"name",{value:a,configurable:!0}),"e");const b=g((e,a,r,n)=>new i(r,a,e,...n),"paginate");export{i as Paginator,j as createPaginationMetaSchemaObject,u as createPaginationSchemaObject,b as paginate};
+import o from"./packem_shared/Paginator-BvWV_Gen.js";import{snakeCaseNamingStrategy as c}from"./packem_shared/Paginator-BvWV_Gen.js";import{default as p}from"./packem_shared/CursorPaginator-6bNX6Dri.js";import{createPaginationMetaSchemaObject as x,createPaginationSchemaObject as P}from"./packem_shared/createPaginationMetaSchemaObject-BLaJWuDt.js";const i=(a,r,t,e)=>o.fromArray(t,r,a,e);export{p as CursorPaginator,o as Paginator,x as createPaginationMetaSchemaObject,P as createPaginationSchemaObject,i as paginate,c as snakeCaseNamingStrategy};

package/dist/packem_shared/CursorPaginator-6bNX6Dri.js

@@ -0,0 +1 @@
+const h=s=>s!==null&&typeof s=="object"&&"id"in s?String(s.id):String(s);class o extends Array{static get[Symbol.species](){return Array}static fromArray(r,t,i={}){const e=new o(r,i),{length:n}=t;e.length=n;for(let u=0;u<n;u++)e[u]=t[u];return e.isEmpty=n===0,e}isEmpty;perPage;url="/";qs={};baseQuery="";currentCursor;getCursor;hasMore;constructor(r,t={}){super(),this.perPage=Number.isFinite(r)&&r>0?Math.trunc(r):1,this.currentCursor=t.currentCursor??null,this.getCursor=t.getCursor??h,this.hasMore=t.hasMore??!1,this.isEmpty=!0}all(){return[...this]}baseUrl(r){return this.url=r,this}queryString(r){this.qs=r;const t=new URLSearchParams;for(const[i,e]of Object.entries(this.qs))e!=null&&t.append(i,String(e));return this.baseQuery=t.toString(),this}getNextCursor(){return!this.hasMorePages||this.length===0?null:this.getCursor(this[this.length-1])}getPreviousCursor(){return this.currentCursor===null||this.length===0?null:this.getCursor(this[0])}getUrl(r){if(r===null)return null;const t=`cursor=${encodeURIComponent(r)}`;return this.baseQuery===""?`${this.url}?${t}`:`${this.url}?${this.baseQuery}&${t}`}getMeta(){const r=this.getNextCursor(),t=this.getPreviousCursor();return{nextCursor:r,nextPageUrl:this.getUrl(r),perPage:this.perPage,previousCursor:t,previousPageUrl:this.getUrl(t)}}toJSON(){return{data:this.all(),meta:this.getMeta()}}get hasMorePages(){return this.hasMore}}export{o as default};

package/dist/packem_shared/Paginator-BvWV_Gen.js

@@ -0,0 +1 @@
+const h=n=>n,P={firstPage:"first_page",firstPageUrl:"first_page_url",lastPage:"last_page",lastPageUrl:"last_page_url",nextPageUrl:"next_page_url",page:"page",perPage:"per_page",previousPageUrl:"previous_page_url",total:"total"},c=n=>P[n]??n;class o extends Array{static get[Symbol.species](){return Array}static fromArray(r,e,s,t){return new o(r,e,s,t)}firstPage=1;isEmpty;currentPage;totalNumber;perPageNumber;qs={};url="/";baseQuery="";constructor(r,e,s,t=[]){super();const{length:a}=t;this.length=a;for(let i=0;i<a;i++)this[i]=t[i];this.totalNumber=Number.isFinite(r)?Math.max(Math.trunc(r),0):0,this.perPageNumber=Number.isFinite(e)&&e>0?Math.trunc(e):1,this.currentPage=Number.isFinite(s)?Math.max(Math.trunc(s),1):1,this.isEmpty=a===0}get perPage(){return this.perPageNumber}all(){return[...this]}baseUrl(r){return this.url=r,this}getMeta(r=h){const e={firstPage:this.firstPage,firstPageUrl:this.getUrl(1),lastPage:this.lastPage,lastPageUrl:this.getUrl(this.lastPage),nextPageUrl:this.getNextPageUrl(),page:this.currentPage,perPage:this.perPage,previousPageUrl:this.getPreviousPageUrl(),total:this.total};if(r===h)return e;const s={};for(const[t,a]of Object.entries(e))s[r(t)]=a;return s}getNextPageUrl(){return this.hasMorePages?this.getUrl(this.currentPage+1):null}getPreviousPageUrl(){return this.currentPage>1?this.getUrl(this.currentPage-1):null}getUrl(r){const e=`page=${encodeURIComponent(String(Math.max(r,1)))}`;return this.baseQuery===""?`${this.url}?${e}`:`${this.url}?${this.baseQuery}&${e}`}getUrlsForRange(r,e){const s=[];for(let t=r;t<=e;t++)s.push({isActive:t===this.currentPage,page:t,url:this.getUrl(t)});return s}getUrlsForWindow(r={}){const e=r.eachSide,s=typeof e=="number"&&Number.isFinite(e)&&e>=0?Math.trunc(e):2,{lastPage:t}=this;if(t<=s*2+3)return this.getUrlsForRange(1,t).map(l=>({...l}));const a=Math.max(this.currentPage-s,1),i=Math.min(this.currentPage+s,t),g=[],u={isActive:!1,page:null,url:null};a>1&&(g.push({isActive:this.currentPage===1,page:1,url:this.getUrl(1)}),a>2&&g.push({...u}));for(const l of this.getUrlsForRange(a,i))g.push(l);return i<t&&(i<t-1&&g.push({...u}),g.push({isActive:this.currentPage===t,page:t,url:this.getUrl(t)})),g}queryString(r){this.qs=r;const e=new URLSearchParams;for(const[s,t]of Object.entries(this.qs))t!=null&&e.append(s,String(t));return this.baseQuery=e.toString(),this}toJSON(r){return{data:this.all(),meta:this.getMeta(r)}}get hasMorePages(){return this.lastPage>this.currentPage}get hasPages(){return this.lastPage!==1}get hasTotal(){return this.total>0}get lastPage(){return Math.max(Math.ceil(this.total/this.perPageNumber),1)}get total(){return this.totalNumber}}export{o as default,c as snakeCaseNamingStrategy};

package/dist/packem_shared/createPaginationMetaSchemaObject-BLaJWuDt.js

@@ -0,0 +1 @@
+const n=["firstPage","firstPageUrl","lastPage","lastPageUrl","nextPageUrl","page","perPage","previousPageUrl","total"],r=(e,a)=>a==="3.1"?{description:e,type:["string","null"]}:{description:e,nullable:!0,type:"string"},o=(e="PaginationData",a={})=>{const{openApiVersion:t="3.0"}=a;return{[e]:{properties:{firstPage:{description:"Returns the number for the first page. It is always 1",minimum:0,type:"integer"},firstPageUrl:{description:"The URL for the first page",type:"string"},lastPage:{description:"Returns the value for the last page by taking the total of rows into account",minimum:0,type:"integer"},lastPageUrl:{description:"The URL for the last page",type:"string"},nextPageUrl:r("The URL for the next page, or null when on the last page",t),page:{description:"Current page number",minimum:1,type:"integer"},perPage:{description:"Returns the value for the limit passed to the paginate method",minimum:0,type:"integer"},previousPageUrl:r("The URL for the previous page, or null when on the first page",t),total:{description:"Holds the value for the total number of rows in the database",minimum:0,type:"integer"}},required:[...n],type:"object",xml:{name:e}}}},s=(e,a,t="#/components/schemas/PaginationData")=>{const i=typeof t=="string"?t:t.metaReference??"#/components/schemas/PaginationData";return{[e]:{properties:{data:{items:a,type:"array",xml:{name:"data",wrapped:!0}},meta:{$ref:i}},required:["data","meta"],type:"object",xml:{name:e}}}};export{o as createPaginationMetaSchemaObject,s as createPaginationSchemaObject};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@visulima/pagination",
-  "version": "5.0.0-alpha.12",
+  "version": "5.0.0-alpha.14",
   "description": "Simple Pagination for Node.",
   "keywords": [
     "anolilab",

package/dist/packem_shared/Paginator-Dj-l47Lc.js

@@ -1 +0,0 @@
-var ot=Object.defineProperty;var P=(t,e)=>ot(t,"name",{value:e,configurable:!0});var nt=Object.defineProperty,B=P((t,e)=>nt(t,"name",{value:e,configurable:!0}),"e");const at=String.prototype.replace,lt=/%20/g,W={RFC1738:"RFC1738",RFC3986:"RFC3986"},K={RFC1738:B(function(t){return at.call(t,lt,"+")},"RFC1738"),RFC3986:B(function(t){return String(t)},"RFC3986")},it=W.RFC1738,G=W.RFC3986;var st=Object.defineProperty,d=P((t,e)=>st(t,"name",{value:e,configurable:!0}),"p");const I=Object.prototype.hasOwnProperty,j=Array.isArray,F=new WeakMap;var J=d(function(t,e){return F.set(t,e),t},"markOverflow");function U(t){return F.has(t)}P(U,"isOverflow");d(U,"isOverflow");var z=d(function(t){return F.get(t)},"getMaxIndex"),L=d(function(t,e){F.set(t,e)},"setMaxIndex");const m=(function(){const t=[];for(let e=0;e<256;++e)t.push("%"+((e<16?"0":"")+e.toString(16)).toUpperCase());return t})(),ct=d(function(t){for(;t.length>1;){const e=t.pop(),o=e.obj[e.prop];if(j(o)){const r=[];for(let a=0;a<o.length;++a)typeof o[a]<"u"&&r.push(o[a]);e.obj[e.prop]=r}}},"compactQueue"),X=d(function(t,e){const o=e&&e.plainObjects?Object.create(null):{};for(let r=0;r<t.length;++r)typeof t[r]<"u"&&(o[r]=t[r]);return o},"arrayToObject");d(P(function t(e,o,r){if(!o)return e;if(typeof o!="object"){if(j(e))e.push(o);else if(e&&typeof e=="object")if(U(e)){var a=z(e)+1;e[a]=o,L(e,a)}else(r&&(r.plainObjects||r.allowPrototypes)||!I.call(Object.prototype,o))&&(e[o]=!0);else return[e,o];return e}if(!e||typeof e!="object"){if(U(o)){for(var s=Object.keys(o),p=r&&r.plainObjects?{__proto__:null,0:e}:{0:e},u=0;u<s.length;u++){var i=parseInt(s[u],10);p[i+1]=o[s[u]]}return J(p,z(o)+1)}return[e].concat(o)}let c=e;return j(e)&&!j(o)&&(c=X(e,r)),j(e)&&j(o)?(o.forEach(function(n,y){if(I.call(e,y)){const h=e[y];h&&typeof h=="object"&&n&&typeof n=="object"?e[y]=t(h,n,r):e.push(n)}else e[y]=n}),e):Object.keys(o).reduce(function(n,y){const h=o[y];return I.call(n,y)?n[y]=t(n[y],h,r):n[y]=h,n},c)},"f"),"merge");d(function(t,e){return Object.keys(e).reduce(function(o,r){return o[r]=e[r],o},t)},"assignSingleSource");d(function(t){const e=t.replace(/\+/g," ");try{return decodeURIComponent(e)}catch{return e}},"decode");const T=1024,ut=d(function(t,e,o,r){if(t.length===0)return t;let a=t;typeof t=="symbol"?a=Symbol.prototype.toString.call(t):typeof t!="string"&&(a=String(t));let s="";for(let p=0;p<a.length;p+=T){const u=a.length>=T?a.slice(p,p+T):a,i=[];for(let c=0;c<u.length;++c){let n=u.charCodeAt(c);if(n===45||n===46||n===95||n===126||n>=48&&n<=57||n>=65&&n<=90||n>=97&&n<=122||r===it&&(n===40||n===41)){i[i.length]=u.charAt(c);continue}if(n<128){i[i.length]=m[n];continue}if(n<2048){i[i.length]=m[192|n>>6]+m[128|n&63];continue}if(n<55296||n>=57344){i[i.length]=m[224|n>>12]+m[128|n>>6&63]+m[128|n&63];continue}c+=1,n=65536+((n&1023)<<10|u.charCodeAt(c)&1023),i[i.length]=m[240|n>>18]+m[128|n>>12&63]+m[128|n>>6&63]+m[128|n&63]}s+=i.join("")}return s},"encode");d(function(t){const e=[{obj:{o:t},prop:"o"}],o=[];for(let r=0;r<e.length;++r){const a=e[r],s=a.obj[a.prop],p=Object.keys(s);for(let u=0;u<p.length;++u){const i=p[u],c=s[i];typeof c=="object"&&c!==null&&o.indexOf(c)===-1&&(e.push({obj:s,prop:i}),o.push(c))}}return ct(e),t},"compact");d(function(t){return Object.prototype.toString.call(t)==="[object RegExp]"},"isRegExp");const ft=d(function(t){return!t||typeof t!="object"?!1:!!(t.constructor&&t.constructor.isBuffer&&t.constructor.isBuffer(t))},"isBuffer");d(function(t,e,o,r){if(U(t)){var a=z(t)+1;return t[a]=e,L(t,a),t}var s=[].concat(t,e);return s.length>o?J(X(s,{plainObjects:r}),s.length-1):s},"combine");const _=d(function(t,e){if(j(t)){const o=[];for(let r=0;r<t.length;r+=1)o.push(e(t[r]));return o}return e(t)},"maybeMap");var pt=Object.defineProperty,w=P((t,e)=>pt(t,"name",{value:e,configurable:!0}),"s");const yt=Object.prototype.hasOwnProperty,Y={brackets:w(function(t){return t+"[]"},"brackets"),comma:"comma",indices:w(function(t,e){return t+"["+e+"]"},"indices"),repeat:w(function(t){return t},"repeat")},b=Array.isArray,gt=Array.prototype.push,Z=w(function(t,e){gt.apply(t,b(e)?e:[e])},"pushToArray"),dt=Date.prototype.toISOString,$=G,f={addQueryPrefix:!1,allowDots:!1,allowEmptyArrays:!1,arrayFormat:"indices",delimiter:"&",encode:!0,encodeDotInKeys:!1,encoder:ut,encodeValuesOnly:!1,format:$,formatter:K[$],indices:!1,serializeDate:w(function(t){return dt.call(t)},"serializeDate"),skipNulls:!1,strictNullHandling:!1},ht=w(function(t){return typeof t=="string"||typeof t=="number"||typeof t=="boolean"||typeof t=="symbol"||typeof t=="bigint"},"isNonNullishPrimitive"),M={},tt=w(function(t,e,o,r,a,s,p,u,i,c,n,y,h,v,E,x,k){let l=t,D=k,N=0,Q=!1;for(;(D=D.get(M))!==void 0&&!Q;){const g=D.get(t);if(N+=1,typeof g<"u"){if(g===N)throw new RangeError("Cyclic object value");Q=!0}typeof D.get(M)>"u"&&(N=0)}if(typeof c=="function"?l=c(e,l):l instanceof Date?l=h(l):o==="comma"&&b(l)&&(l=_(l,function(g){return g instanceof Date?h(g):g})),l===null){if(s)return i&&!x?i(e,f.encoder,"key",v):e;l=""}if(ht(l)||ft(l)){if(i){const g=x?e:i(e,f.encoder,"key",v);return[E(g)+"="+E(i(l,f.encoder,"value",v))]}return[E(e)+"="+E(String(l))]}const C=[];if(typeof l>"u")return C;let R;if(o==="comma"&&b(l))x&&i&&(l=_(l,i)),R=[{value:l.length>0?l.join(",")||null:void 0}];else if(b(c))R=c;else{const g=Object.keys(l);R=n?g.sort(n):g}const H=u?e.replace(/\./g,"%2E"):e,A=r&&b(l)&&l.length===1?H+"[]":H;if(a&&b(l)&&l.length===0)return A+"[]";for(let g=0;g<R.length;++g){const O=R[g],V=typeof O=="object"&&typeof O.value<"u"?O.value:l[O];if(p&&V===null)continue;const S=y&&u?O.replace(/\./g,"%2E"):O,rt=b(l)?typeof o=="function"?o(A,S):A:A+(y?"."+S:"["+S+"]");k.set(t,N);const q=new WeakMap;q.set(M,k),Z(C,tt(V,rt,o,r,a,s,p,u,o==="comma"&&x&&b(l)?null:i,c,n,y,h,v,E,x,q))}return C},"stringify"),mt=w(function(t){if(!t)return f;if(typeof t.allowEmptyArrays<"u"&&typeof t.allowEmptyArrays!="boolean")throw new TypeError("`allowEmptyArrays` option can only be `true` or `false`, when provided");if(typeof t.encodeDotInKeys<"u"&&typeof t.encodeDotInKeys!="boolean")throw new TypeError("`encodeDotInKeys` option can only be `true` or `false`, when provided");if(t.encoder!==null&&typeof t.encoder<"u"&&typeof t.encoder!="function")throw new TypeError("Encoder has to be a function.");let e=G;if(typeof t.format<"u"){if(!yt.call(K,t.format))throw new TypeError("Unknown format option provided.");e=t.format}const o=K[e];let r=f.filter;(typeof t.filter=="function"||b(t.filter))&&(r=t.filter);let a;if(t.arrayFormat in Y?a=t.arrayFormat:"indices"in t?a=t.indices?"indices":"repeat":a=f.arrayFormat,"commaRoundTrip"in t&&typeof t.commaRoundTrip!="boolean")throw new TypeError("`commaRoundTrip` must be a boolean, or absent");const s=typeof t.allowDots>"u"?t.encodeDotInKeys===!0?!0:f.allowDots:!!t.allowDots;return{addQueryPrefix:typeof t.addQueryPrefix=="boolean"?t.addQueryPrefix:f.addQueryPrefix,allowDots:s,allowEmptyArrays:typeof t.allowEmptyArrays=="boolean"?!!t.allowEmptyArrays:f.allowEmptyArrays,arrayFormat:a,commaRoundTrip:t.commaRoundTrip,delimiter:typeof t.delimiter>"u"?f.delimiter:t.delimiter,encode:typeof t.encode=="boolean"?t.encode:f.encode,encodeDotInKeys:typeof t.encodeDotInKeys=="boolean"?t.encodeDotInKeys:f.encodeDotInKeys,encoder:typeof t.encoder=="function"?t.encoder:f.encoder,encodeValuesOnly:typeof t.encodeValuesOnly=="boolean"?t.encodeValuesOnly:f.encodeValuesOnly,filter:r,format:e,formatter:o,serializeDate:typeof t.serializeDate=="function"?t.serializeDate:f.serializeDate,skipNulls:typeof t.skipNulls=="boolean"?t.skipNulls:f.skipNulls,sort:typeof t.sort=="function"?t.sort:null,strictNullHandling:typeof t.strictNullHandling=="boolean"?t.strictNullHandling:f.strictNullHandling}},"normalizeStringifyOptions");function et(t,e){let o=t;const r=mt(e);let a,s;typeof r.filter=="function"?(s=r.filter,o=s("",o)):b(r.filter)&&(s=r.filter,a=s);const p=[];if(typeof o!="object"||o===null)return"";const u=Y[r.arrayFormat],i=u==="comma"&&r.commaRoundTrip;a||(a=Object.keys(o)),r.sort&&a.sort(r.sort);const c=new WeakMap;for(let h=0;h<a.length;++h){const v=a[h];r.skipNulls&&o[v]===null||Z(p,tt(o[v],v,u,i,r.allowEmptyArrays,r.strictNullHandling,r.skipNulls,r.encodeDotInKeys,r.encode?r.encoder:null,r.filter,r.sort,r.allowDots,r.serializeDate,r.format,r.formatter,r.encodeValuesOnly,c))}const n=p.join(r.delimiter),y=r.addQueryPrefix===!0?"?":"";return n.length>0?y+n:""}P(et,"stringify");w(et,"stringify");var bt=Object.defineProperty,Pt=P((t,e)=>bt(t,"name",{value:e,configurable:!0}),"n");class vt extends Array{static{P(this,"g")}constructor(e,o,r,...a){super(...a),this.totalNumber=e,this.perPage=o,this.currentPage=r,this.totalNumber=e,this.rows=a,this.isEmpty=this.rows.length===0}totalNumber;perPage;currentPage;static{Pt(this,"Paginator")}firstPage=1;isEmpty;qs={};rows;url="/";all(){return this.rows}baseUrl(e){return this.url=e,this}getMeta(){return{firstPage:this.firstPage,firstPageUrl:this.getUrl(1),lastPage:this.lastPage,lastPageUrl:this.getUrl(this.lastPage),nextPageUrl:this.getNextPageUrl(),page:this.currentPage,perPage:this.perPage,previousPageUrl:this.getPreviousPageUrl(),total:this.total}}getNextPageUrl(){return this.hasMorePages?this.getUrl(this.currentPage+1):null}getPreviousPageUrl(){return this.currentPage>1?this.getUrl(this.currentPage-1):null}getUrl(e){const o=et({...this.qs,page:Math.max(e,1)});return`${this.url}?${o}`}getUrlsForRange(e,o){const r=[];for(let a=e;a<=o;a++)r.push({isActive:a===this.currentPage,page:a,url:this.getUrl(a)});return r}queryString(e){return this.qs=e,this}toJSON(){return{data:this.all(),meta:this.getMeta()}}get hasMorePages(){return this.lastPage>this.currentPage}get hasPages(){return this.lastPage!==1}get hasTotal(){return this.total>0}get lastPage(){return Math.max(Math.ceil(this.total/this.perPage),1)}get total(){return this.totalNumber}}export{vt as default};

package/dist/packem_shared/createPaginationMetaSchemaObject-DGZPqai2.js

@@ -1 +0,0 @@
-var n=Object.defineProperty;var a=(e,t)=>n(e,"name",{value:t,configurable:!0});var o=Object.defineProperty,r=a((e,t)=>o(e,"name",{value:t,configurable:!0}),"r");const s=r((e="PaginationData")=>({[e]:{properties:{firstPage:{description:"Returns the number for the first page. It is always 1",minimum:0,type:"integer"},firstPageUrl:{description:"The URL for the first page",type:"string"},lastPage:{description:"Returns the value for the last page by taking the total of rows into account",minimum:0,type:"integer"},lastPageUrl:{description:"The URL for the last page",type:"string"},nextPageUrl:{description:"The URL for the next page",type:"string"},page:{description:"Current page number",minimum:1,type:"integer"},perPage:{description:"Returns the value for the limit passed to the paginate method",minimum:0,type:"integer"},previousPageUrl:{description:"The URL for the previous page",type:"string"},total:{description:"Holds the value for the total number of rows in the database",minimum:0,type:"integer"}},type:"object",xml:{name:e}}}),"createPaginationMetaSchemaObject"),m=r((e,t,i="#/components/schemas/PaginationData")=>({[e]:{properties:{data:{items:t,type:"array",xml:{name:"data",wrapped:!0}},meta:{$ref:i}},type:"object",xml:{name:e}}}),"createPaginationSchemaObject");export{s as createPaginationMetaSchemaObject,m as createPaginationSchemaObject};