ddnexus/pagy
Pagy
Pagy is a framework-agnostic Ruby pagination library used to split large datasets into numbered pages. It provides multiple implementations for dividing data, including offset-based slicing for standard collections and high-performance keyset pagination for massive datasets.
The library includes a pagination UI generator for rendering accessible HTML navigation bars and a dedicated tool for REST API pagination that produces RFC-compliant link headers and JSON metadata. It also features specialized systems for dividing results from search engines like Elasticsearch, Meilisearch, and Typesense, as well as time-based pagination for organizing records into calendar units.
Broad capabilities cover data management for arrays and database collections, including record count memoization and page size rebalancing. The project also provides comprehensive UI and accessibility tools, such as ARIA labeling, right-to-left layout support, and integration with various CSS frameworks. Security is addressed through pagination parameter sanitization and error handling for out-of-range requests.
The system is extensible via a central configuration for global defaults and allows for core logic overriding through module prepending.
Features
- Ruby Pagination Libraries - A framework-agnostic library for splitting large datasets into numbered pages within the Ruby ecosystem.
- Collection Pagination - Splits data collections into smaller pages using offset or keyset techniques to improve load times.
- Keyset Pagination - Implements high-performance retrieval using record values as markers instead of numeric offsets.
- Offset Pagination - Divides collections into discrete pages by calculating the starting record index and a fixed limit.
- Pagination Metadata - Formats pagination details as hashes or nested query strings for use by external APIs and clients.
- Database Pagination Engines - Slices large database result sets into physical pages to reduce memory overhead and improve performance.
- API Pagination - Generates RFC-compliant link headers, JSON metadata, and pagination markers for REST API clients.
- In-Memory Array Pagination - Splits standard Ruby arrays of objects into numbered pages.
- API Pagination - Provides comprehensive tools for implementing API pagination including markers and metadata headers.
- Pagination UI Components - Renders accessible HTML navigation bars with ARIA labels and right-to-left support.
- Pagination URL Generation - Produces navigation links for first, previous, next, and last pages including custom paths.
- Pagination Link Generation - Renders previous and next page links using anchor tags with accessibility attributes.
- Count Caching - Caches the total record count to eliminate redundant database queries across multiple page requests.
- Count-Skipping Optimizations - Implements performance optimizations by omitting total record count queries during offset pagination.
- Calendar Pagination - Organizes data into time-based buckets such as years, quarters, or months combined with offset pagination.
- Temporal Range Pagination - Filters records by a specific time period and applies offset pagination within that window.
- Search Engine Pagination - Divides result sets from search platforms like Elasticsearch, Meilisearch, and Typesense into discrete pages.
- Independent Pagination Groups - Manages multiple independent pagination groups on a single page, each with its own unique page keys.
- Request Parameter Sanitization - Filters and validates incoming URL keys to ensure page and limit values are safe and within range.
- Configuration Defaults - Manages global and instance-level pagination settings through a centralized configuration object.
- Framework Agnostic Interfaces - Calculates page slices and navigation links independently of any specific web framework or database driver.
- Accessibility Labeling - Sets custom ARIA labels and roles on navigation elements for screen reader accessibility.
- Framework Agnostic UI Logic - Provides pagination logic that operates independently of any specific rendering framework.
- Page Number Link Generators - Outputs HTML strings of numbered navigation links for jumping between result pages.
- Navigation Bars - Produces pagination bars with customizable link positions and layout options.
- Pagination Range Displays - Generates human-readable strings displaying the current page range and total item count.
- Pagination Header Generation - The library creates compliant link headers and customizable metadata headers to describe the current page and record count.
- REST API Pagination Tooling - Produces RFC-compliant link headers and JSON:API metadata for web services.
- Pagination Tools - High-performance pagination gem for various frameworks.
