Pagex 📖

Fast, minimal, production-ready pagination for Ecto and Phoenix.

Inspired by Pagy (Ruby), Pagex is designed specifically for the Elixir/Phoenix ecosystem. It takes the approach of explicit, small functions over magic. No use Pagex in your schema, no global config macros, and no hidden schema introspection.

🚀 Example Integration

If you want to see a full, production-ready implementation of pagex in a Phoenix application, check out our example repository:

👉 Simple Pagination Example

This example project demonstrates:

• ✅ Phoenix LiveView pagination.
• ✅ JSON API pagination.

📺 Demo Videos

Phoenix LiveView Integration

See how smoothly pagex handles real-time pagination in LiveView:

JSON API Response

Standardized metadata structure ready for any front-end:

✨ Features & Comparison

Pagex offers a modern alternative to existing pagination libraries by combining performance with extreme simplicity.

Pagination Benchmark

Comparing offset-based vs cursor-based pagination — with and without COUNT(*) — across different page depths.

Test Environment

Key Findings

• ✅ Fastest overall:offset pagination (no count)
• ❌ Worst performance:offset pagination with COUNT(*) (~45× slower)
• 🔄 Cursor pagination: slower per request, but more stable for deeper pagination
• 💾 Memory tradeoff: cursor chaining increases memory usage significantly (~2×)

Performance Results

Relative Speed (vs. fastest baseline)

Memory Usage

Relative Memory (vs. baseline)

Conclusion

Offset pagination without COUNT(*) performs best for shallow pages and simple use cases, but degrades with expensive counting operations.

Cursor-based pagination provides more predictable scaling for deeper pagination, but introduces higher per-request latency and increased memory usage when chaining queries.

When to use what

📦 Installation

Add pagex to your list of dependencies in mix.exs:

# mix.exs
def deps do
  [
    {:pagex, "~> 0.2.3"}
  ]
end

Then, run mix deps.get in your terminal.

📖 Documentation

Full API documentation is available via HexDocs:

👉 https://hexdocs.pm/pagex

To generate and view the full API documentation locally:

mix docs

Then open:

open doc/index.html

On Linux:

xdg-open doc/index.html

Or simply open doc/index.html in your browser.

🚀 Quick Start

Pagex provides a clean and straightforward API. You can paginate your Ecto queries using either Offset or Cursor-based pagination.

Offset Pagination

Ideal for standard table views and web interfaces.

alias App.Repo
alias App.Blog.Post

# Using default params
{posts, meta} = Pagex.paginate(Post, params, Repo)

# With a custom Ecto query
query = from p in Post, where: p.published == true, order_by: [desc: p.inserted_at]
{posts, meta} = Pagex.paginate(query, %{"page" => 2, "page_size" => 20}, Repo)

Cursor Pagination

Highly recommended for large datasets, JSON APIs, and infinite scrolling interfaces.

{posts, meta} = Pagex.paginate_cursor(Post, params, Repo)

(Note: The returned meta struct contains helpful data like next_cursor, prev_cursor, total_pages, etc., depending on your chosen pagination strategy.)

💻 Phoenix & LiveView Integration

Pagex is built with Phoenix in mind. While staying un-intrusive, it ships with out-of-the-box helpers for:

• HTML Views: Easy-to-use template functions to generate pagination links.
• LiveView: Drop-in helpers for managing pagination state and events without boilerplate.
• JSON APIs: Standardized metadata structures ready to be merged into your API responses.

Project Structure

pagex/
├── lib/
│   ├── pagex.ex                  # Public API — paginate/4 and paginate_cursor/4
│   └── pagex/
│       ├── meta.ex               # Meta struct + constructors
│       ├── params.ex             # Parameter validation
│       ├── offset.ex             # Offset pagination engine
│       ├── cursor.ex             # Cursor pagination engine
│       ├── phoenix/
│             └── live_view.ex    # Phoenix LiveView helpers
│             └── html.ex       # HTML helper functions
│ 
│ 
│               
├── test/
│   └── pagex/
│       ├── params_test.exs
│       ├── meta_test.exs
│       ├── cursor_encode_test.exs
│       └── phoenix/
│           ├── html_test.exs
│           ├── live_view_test.exs
├── benchmarks/
│   └── support/
│       ├── post.ex
│       ├── repo.ex
│   └── pagination_benchmark.exs
│   └── setup.exs
├── mix.exs
├── README.md
├── CHANGELOG.md
└── LICENSE

🤝 Contributing

Contributions, bug reports, and feature requests are welcome!

Feel free to check the issues page to get involved.

1. Fork and Clone

First, fork the repository by clicking the "Fork" button at the top right of this page [1]. Then, clone your fork to your local machine:

    git clone https://github.com/Null-logic-0/pagex.git
    cd pagex

1. Install Dependencies

Pagex is an Elixir project. Fetch the required dependencies using mix:

    mix deps.get

1. Create a Branch

Create a new branch for your feature, improvement, or bug fix:

    git checkout -b feature/my-awesome-feature

1. Make Your Changes

Write your code and implement your changes. If you are adding a new feature or fixing a bug, please write tests to cover your changes to maintain the library's stability.

1. Run Tests & Format Code

Before committing, ensure that all tests pass and that the code adheres to the standard Elixir formatting rules:

# Run the test suite
mix test

# Format the code
mix format

1. Commit and Push

Commit your changes with a descriptive message and push the branch to your fork:

git add .
git commit -m "Add my awesome feature"
git push origin feature/my-awesome-feature

1. Open a Pull Request

Go back to the main Pagex repository and you'll see a prompt to open a Pull Request. Submit your PR against the master branch and describe the changes you've made!

Why this is helpful:

• Elixir specific: It uses the standard mix commands (mix deps.get, mix test, mix format) that Elixir developers expect.

• Step-by-step: It walks beginners completely through the process of interacting with a GitHub repo, making it much more inviting for open-source newcomers.

📜 License

Pagex is open-source software released under the MIT LICENSE