Registry / web-framework / ultimate-pagination

ultimate-pagination

library1.0.0jsnpmunverified

The `ultimate-pagination` library provides a universal algorithm for generating pagination models, designed to be framework-agnostic and reusable across various JavaScript environments, including client-side frameworks (React, Angular, Ember, etc.) and server-side Node.js applications. It abstracts the complex logic of determining which page numbers, ellipsis, and navigation links (first, last, previous, next) should be displayed, returning a structured array of item objects. The current stable version is `1.0.0`. It focuses purely on logic generation, decoupling it from UI rendering, allowing developers to implement custom UI components on top of its output. Its primary differentiator is this separation of concerns, enabling consistent pagination behavior across diverse tech stacks and making it suitable for server-side rendering. There is no explicit release cadence mentioned, but it appears to be a stable library with infrequent, feature-driven updates.

web-framework

npm install ultimate-pagination

github ↗package ↗

INSTALL

IMPORT

SIG · ULTIMATE-PAGINATIO

ultimate-pagination

web-frameworkjavascriptv1.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

getPaginationModel

✓ import { getPaginationModel } from 'ultimate-pagination';

✗ const getPaginationModel = require('ultimate-pagination');

For CommonJS, access `getPaginationModel` as a property of the main export (e.g., `require('ultimate-pagination').getPaginationModel`). For ESM, use named import.

ITEM_TYPES

✓ import { ITEM_TYPES } from 'ultimate-pagination';

✗ const ITEM_TYPES = require('ultimate-pagination');

Contains an enum of possible item types like `PAGE`, `ELLIPSIS`, `FIRST_PAGE_LINK`.

ITEM_KEYS

✓ import { ITEM_KEYS } from 'ultimate-pagination';

✗ const ITEM_KEYS = require('ultimate-pagination');

Provides unique keys for specific item types like `FIRST_ELLIPSIS` or `FIRST_PAGE_LINK`.

Demonstrates generating various pagination models using `getPaginationModel` with different options for page ranges and link visibility, showing the structured output and how to interpret `ITEM_TYPES`.

import { getPaginationModel, ITEM_TYPES } from 'ultimate-pagination'; interface PaginationItem { type: ITEM_TYPES; key: string | number; value: number; isActive: boolean; } const totalPages = 20; const currentPage = 10; // Basic pagination model const paginationModelBasic: PaginationItem[] = getPaginationModel({ currentPage: currentPage, totalPages: totalPages, }); console.log('--- Basic Model (currentPage 10, totalPages 20) ---'); console.log(paginationModelBasic.map(item => ({ type: ITEM_TYPES[item.type], value: item.value, isActive: item.isActive }))); // Pagination model with custom ranges and hidden links const paginationModelCustom: PaginationItem[] = getPaginationModel({ currentPage: 5, totalPages: 15, boundaryPagesRange: 2, // e.g., show pages 1, 2, ..., 14, 15 siblingPagesRange: 2, // e.g., show pages ..., 3, 4, [5], 6, 7, ... hideEllipsis: false, hidePreviousAndNextPageLinks: false, hideFirstAndLastPageLinks: false, }); console.log('\n--- Custom Model (currentPage 5, totalPages 15, boundary 2, sibling 2) ---'); console.log(paginationModelCustom.map(item => ({ type: ITEM_TYPES[item.type], value: item.value, isActive: item.isActive }))); // Model with all navigation links hidden const paginationModelMinimal: PaginationItem[] = getPaginationModel({ currentPage: 3, totalPages: 5, hidePreviousAndNextPageLinks: true, hideFirstAndLastPageLinks: true, hideEllipsis: true, }); console.log('\n--- Minimal Model (currentPage 3, totalPages 5, hidden links/ellipsis) ---'); console.log(paginationModelMinimal.map(item => ({ type: ITEM_TYPES[item.type], value: item.value, isActive: item.isActive })));

Debug

Known issues

breakingSince v1.0.0, the `getPaginationModel` function strictly validates input parameters and will throw exceptions (e.g., `RangeError`) for invalid values such as `currentPage` outside the `1` to `totalPages` range, or `totalPages` less than `1`. Earlier (pre-1.0) versions might have handled these cases differently, potentially returning empty or unexpected models without throwing.

fix

Always sanitize or validate `currentPage` and `totalPages` to be positive integers, ensuring `1 <= currentPage <= totalPages`. Implement `try...catch` blocks if inputs are untrusted or derived from user input.

affects: >=1.0.0

gotchaThe `key` property in the returned pagination model items can be either a `number` (for regular `PAGE` items) or a `string` (for special items like `ELLIPSIS`, `FIRST_PAGE_LINK`, etc., referencing `ITEM_KEYS`). Developers rendering lists of these items in frameworks like React or Vue need to handle this mixed type for consistent keying.

fix

When mapping over the `paginationModel` to render components, ensure your component's `key` prop can accept both numbers and strings, or normalize the `key` to a string: `item.key.toString()`.

affects: >=1.0.0

gotchaThe `ITEM_TYPES` enum provides numerical values for each type (e.g., `ITEM_TYPES.PAGE` might be `0`, `ITEM_TYPES.ELLIPSIS` might be `1`). When debugging or inspecting the model, note that `item.type` will be a number, not a string representation of the type. For human-readable output, you might need to map it back using `ITEM_TYPES[item.type]`.

fix

To display or log the string representation of an item type, use `ITEM_TYPES[item.type]` or create a mapping object from numerical values to string names.

affects: >=1.0.0

gotchaThe `currentPage` parameter in `getPaginationModel` is 1-indexed (e.g., the first page is `1`, not `0`). Developers coming from 0-indexed array or list contexts might accidentally pass `0` for the first page, leading to a `RangeError`.

fix

Always ensure `currentPage` is treated as 1-indexed. If converting from a 0-indexed source (e.g., an array index), remember to add `1`.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'getPaginationModel')

Attempting to call `require('ultimate-pagination')()` directly, treating the module's main export as the `getPaginationModel` function itself, instead of a module object containing it.

fix

For CommonJS, explicitly access the function: `const { getPaginationModel } = require('ultimate-pagination');` or `const ultimatePagination = require('ultimate-pagination'); const model = ultimatePagination.getPaginationModel(...);`

RangeError: Invalid pagination options: currentPage must be greater than 0.

The `currentPage` parameter was provided with a value of `0` or less, which is not allowed as pages are 1-indexed.

fix

Ensure `currentPage` is always a positive integer (`>= 1`). If converting from a 0-indexed source, remember to add `1`.

RangeError: Invalid pagination options: currentPage cannot be greater than totalPages.

The `currentPage` parameter was provided with a value greater than `totalPages`, which is logically impossible for a pagination model.

fix

Ensure `currentPage` is less than or equal to `totalPages`. Validate user input or state logic to prevent this scenario.

TS2305: Module '"ultimate-pagination"' has no exported member 'ITEM_TYPES'.

Attempting to use `ITEM_TYPES` (or `ITEM_KEYS`) in TypeScript without correctly importing it as a named export.

fix

Use a named import: `import { ITEM_TYPES, ITEM_KEYS } from 'ultimate-pagination';`

Upgrade

Version history

1.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/ultimate-pagination/ultimate-pagination ↗

packagehttps://www.npmjs.com/package/ultimate-pagination ↗