nhb-toolbox/dist/dts/utils/Paginator.d.ts

A versatile collection of smart, efficient, and reusable utility functions, classes and types for everyday development needs.

import type { FromMetaOptions, PageListOptions, PaginatorMeta, PaginatorOptions } from './types';
/** @class Generates pagination logic, offsets, metadata and other pagination logic(s) for APIs and UIs. */
export declare class Paginator {
    #private;
    /**
     * * Creates an instance of the Paginator.
     * @param options - The options for pagination.
     */
    constructor(options: PaginatorOptions);
    /**
     * @instance Returns a new Paginator instance with the given page number.
     * * This method does not modify the current instance.
     * - **N.B.** *If the provided page is out of range, it will be clamped between 1 and the last page.*
     * @param page - The new current page to use.
     * @returns A new Paginator instance with the updated (clamped) page.
     */
    withPage(page: number): Paginator;
    /**
     * @instance Returns a new Paginator instance with the given items per page.
     * - **N.B.** *If the value is less than `1`, it will be clamped to 1.*
     * @param perPage - New items per page value.
     * @returns A new Paginator instance with updated items per page.
     */
    withPerPage(perPage: number): Paginator;
    /**
     * @instance Returns a new Paginator instance with the given total items.
     * - **N.B.** *If the value is `negative`, it will be clamped to `0`.*
     * @param totalItems - New total items value.
     * @returns A new Paginator instance with updated total items.
     */
    withTotalItems(totalItems: number): Paginator;
    /**
     * @instance Returns a new Paginator instance with updated pagination options.
     * - **N.B.** *Any value provided will override the existing one, with clamping applied for safety.*
     * @param options - Partial pagination options to override the current instance.
     * @returns A new Paginator instance with merged and clamped options.
     */
    withOptions(options: Partial<PaginatorOptions>): Paginator;
    /**
     * @instance Calculates the offset (number of items to skip) based on the `current page` and `items per page`.
     * @returns The number of items to skip.
     */
    offset(): number;
    /**
     * @instance Calculates the offset (number of items to skip) based on the `current page` and `items per page`.
     * @alias of {@link offset}
     * @returns The number of items to skip.
     */
    getOffset(): number;
    /**
     * @instance Calculates the number of items to skip based on the `current page` and `items per page`.
     * @alias of {@link offset}
     * @returns The number of items to skip.
     */
    skipCount(): number;
    /**
     * @instance Calculates the total number of pages based on `total items` and `items per page`.
     * @returns The total number of pages.
     */
    totalPages(): number;
    /**
     * * Returns pagination metadata useful for API responses or UI rendering.
     * @returns An object with pagination metadata.
     */
    getMeta(): PaginatorMeta;
    /**
     * @instance Returns the next page number if it exists.
     * @returns The next page number or null if it's the last page.
     */
    nextPage(): number | null;
    /**
     * @instance Returns the previous page number if it exists.
     * @returns The previous page number or null if it's the first page.
     */
    prevPage(): number | null;
    /**
     * @instance Checks if the current page is the first page.
     * @returns Whether the current page is the first page.
     */
    isFirstPage(): boolean;
    /**
     * @instance Checks if the current page is the last page.
     * @returns Whether the current page is the last page.
     */
    isLastPage(): boolean;
    /**
     * @instance Checks if a previous page exists.
     * @returns Whether a previous page exists.
     */
    hasPrevPage(): boolean;
    /**
     * @instance Checks if a next page exists.
     * @returns Whether a next page exists.
     */
    hasNextPage(): boolean;
    /**
     * @instance Creates an array of page numbers for UI pagination display.
     * @param options Options for customizing the page list.
     * @returns An array of visible page numbers.
     */
    pageList(options?: PageListOptions): number[];
    /**
     * @instance Returns the first page number.
     * @returns Always returns 1.
     */
    firstPage(): number;
    /**
     * @instance Returns the last page number based on total items and per page count.
     * @returns The last page number.
     */
    lastPage(): number;
    /**
     * @instance Checks if a page number is valid within the pagination range.
     * @param page - The page number to validate.
     * @returns Whether the page number is within range.
     */
    isPageValid(page: number): boolean;
    /**
     * @static Creates a new Paginator instance from a meta object.
     * @param meta - A pagination metadata object.
     * @returns A new Paginator instance.
     */
    static fromMeta(meta: FromMetaOptions): Paginator;
}