How ddnexus/pagy works
Main Components
• Core Library Module – The central pagination logic is implemented in the gem’s core (look at gem/lib/pagy.rb and its supporting files under gem/lib/pagy/…) which provides the fundamental functionality.
• Extras Modules – There are many optional integration modules for additional features (e.g., calendar pagination, keyset pagination, countless, headers, JSON:API, CSS framework helpers like bootstrap, bulma, tailwind, etc.) that extend or plug into the core.
• Frontend Integration – The gem provides view helpers in the frontend (pagy_nav, pagy_nav_js, pagy_info, etc.) and associated JavaScript/TypeScript components (supported via the src and gem/javascripts directories) to enhance client-side rendering.
• Configuration & Initializers – Files in gem/config and perhaps some of the Rake tasks are used to configure defaults for pagination behavior.
• Testing & CI – The repository is thoroughly tested, with Ruby tests (located under test/), end-to-end tests using Cypress (e2e/), and CI workflows (.github/workflows) that automate builds and releases.
• Documentation & Examples – Extensive documentation is provided in the docs folder (with API, extras, how-to guides) and playground examples showing integration scenarios.
• Build & Release Infrastructure – The tasks, Rakefile, versioning (CHANGELOG, Gemfile), and GitHub release workflows indicate a well-organized release and development process.
Relationships and Interactions
• The Core Library is the central engine that all other components rely on. It exposes backend functions (for wrapping collections with pagy) and frontend view helpers.
• Extras modules “plug in” to augment the core functionality. They are loaded in an initializer and then mix into the main module to support integrations with ActiveRecord, Sequel, JSON rendering, search frameworks, CSS frameworks, etc.
• The frontend components are designed to be used in views of web frameworks. They interact with the backend by receiving the pagy instance and rendering the corresponding navigation and pagination information.
• The testing layers (both Ruby and JavaScript E2E tests) interact with the core and extras – verifying that pagination works correctly across multiple scenarios and environments.
• CI workflows and tasks automate code quality checks, test runs, and documentation builds before publishing the gem.
Important Architectural Patterns and Technologies
• Modular Design and Mixins: The gem employs Ruby’s module and mixin features, segregating the backend and frontend functionalities and then enabling extras to extend these.
• Separation of Concerns: There is a clear separation between the core logic, the user-interface rendering, and integration “extras.”
• Integration Points: The project supports multiple integration environments including server-side Ruby frameworks and client-side JavaScript (as indicated by the src, gem/javascripts, and e2e directories).
• Testing and CI/CD: With dedicated tests and GitHub workflows, the project emphasizes robust testing and continuous integration.