@visulima/pagination 5.0.0-alpha.9 → 5.0.0

package/dist/index.d.ts

@@ -1,5 +1,377 @@
-import type { Paginator as PaginatorInterface } from "./types.d.d.ts";
-export { default as Paginator } from "./paginator.d.ts";
-export { createPaginationMetaSchemaObject, createPaginationSchemaObject } from "./swagger.d.ts";
-export declare const paginate: <Result>(page: number, perPage: number, total: number, rows: Result[]) => PaginatorInterface<Result>;
-export type { PaginationMeta, PaginationResult, Paginator as PaginatorInterface } from "./types.d.ts";
+import { OpenAPIV3 } from 'openapi-types';
+interface PaginationMeta {
+  firstPage: number;
+  /**
+   * The URL for the first page. Always a string — `getUrl()` never returns null.
+   */
+  firstPageUrl: string;
+  lastPage: number;
+  /**
+   * The URL for the last page. Always a string — `getUrl()` never returns null.
+   */
+  lastPageUrl: string;
+  nextPageUrl: string | null;
+  page: number;
+  perPage: number;
+  previousPageUrl: string | null;
+  total: number;
+}
+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;
+  currentPage: number;
+  readonly firstPage: number;
+  getMeta: (namingStrategy?: NamingStrategy) => PaginationMeta;
+  getNextPageUrl: () => string | null;
+  getPreviousPageUrl: () => string | null;
+  getUrl: (page: number) => string;
+  getUrlsForRange: (start: number, end: number) => {
+    isActive: boolean;
+    page: number;
+    url: string;
+  }[];
+  getUrlsForWindow: (options?: WindowOptions) => WindowedUrl[];
+  readonly hasMorePages: boolean;
+  readonly hasPages: boolean;
+  readonly hasTotal: boolean;
+  readonly isEmpty: boolean;
+  readonly lastPage: number;
+  readonly perPage: number;
+  queryString: (values: Record<string, unknown>) => this;
+  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> {
+  /**
+  * 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
+  */
+  readonly firstPage: number;
+  /**
+  * 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 url;
+  /**
+  * 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[];
+  /**
+  * Define base url for making the pagination links.
+  */
+  baseUrl(url: string): this;
+  /**
+  * Returns JSON meta data. Pass `snakeCaseNamingStrategy` for
+  * Laravel/AdonisJS-style output.
+  * @param namingStrategy Optional key-transform applied to every meta key.
+  */
+  getMeta(namingStrategy?: NamingStrategy): PaginationMeta;
+  /**
+  * Returns url for the next page.
+  */
+  getNextPageUrl(): string | null;
+  /**
+  * Returns URL for the previous page.
+  */
+  getPreviousPageUrl(): string | null;
+  /**
+  * Returns url for a given page. Doesn't validate the integrity of the
+  * page (only clamps the page number to be at least 1).
+  */
+  getUrl(page: number): string;
+  /**
+  * 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(namingStrategy?: NamingStrategy): PaginationResult<T>;
+  /**
+  * Find if there are more pages to come.
+  */
+  get hasMorePages(): boolean;
+  /**
+  * Find if there are enough results to be paginated or not.
+  */
+  get hasPages(): boolean;
+  /**
+  * Find if there are total records or not. This is not same as
+  * `isEmpty`.
+  *
+  * The `isEmpty` reports about the current set of results. However, `hasTotal`
+  * reports about the total number of records, regardless of the current.
+  */
+  get hasTotal(): boolean;
+  /**
+  * The Last page number.
+  */
+  get lastPage(): number;
+  /**
+  * Casting `total` to a number. Later, we can think of situations
+  * to cast it to a bigint.
+  */
+  get total(): number;
+}
+/**
+* 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 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,6 +1 @@
-import Paginator from './packem_shared/Paginator-D40bQfqD.js';
-export { createPaginationMetaSchemaObject, createPaginationSchemaObject } from './packem_shared/createPaginationMetaSchemaObject-AoC1C8S-.js';
-
-const paginate = (page, perPage, total, rows) => new Paginator(total, perPage, page, ...rows);
-
-export { Paginator, 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,21 +1,19 @@
 {
   "name": "@visulima/pagination",
-  "version": "5.0.0-alpha.9",
+  "version": "5.0.0",
   "description": "Simple Pagination for Node.",
   "keywords": [
     "anolilab",
-    "visulima",
-    "pagination",
-    "paginator",
-    "offset",
     "limit",
+    "offset",
     "page",
-    "paging"
+    "pagination",
+    "paginator",
+    "paging",
+    "visulima"
   ],
   "homepage": "https://visulima.com/packages/pagination/",
-  "bugs": {
-    "url": "https://github.com/visulima/visulima/issues"
-  },
+  "bugs": "https://github.com/visulima/visulima/issues",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/visulima/visulima.git",
@@ -52,7 +50,7 @@
     "LICENSE.md"
   ],
   "engines": {
-    "node": ">=22.13 <=25.x"
+    "node": "^22.14.0 || >=24.10.0"
   },
   "os": [
     "darwin",