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:

Click to view LiveView Demo

Screen.Recording.2026-04-16.at.6.58.28.PM.mov

JSON API Response

Standardized metadata structure ready for any front-end:

Click to view JSON API Demo

Screen.Recording.2026-04-16.at.6.59.40.PM.mov

---

✨ Features & Comparison

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

Feature	Pagex	Scrivener	Paginator
Offset pagination	✅	✅	✅
Cursor pagination	✅	❌	✅
LiveView helpers	✅	❌	❌
JSON API support	✅	Partial	Partial
No macros/DSLs	✅	❌	❌
Max page size guard	✅	❌	❌
Optional count query	✅	❌	❌

---

Pagination Benchmark

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

---

Test Environment

Parameter	Value
Page size	(not specified)
Dataset size	(not specified)
Database	(add here)
Measurement	Average latency, p99 latency, memory usage per query
Cache	(add warm/cold if relevant)

---

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

Method	Throughput (ops/sec)	Avg Latency	Deviation	Median	p99
Offset page 1 (no count)	16.49K	60.64 µs	±12.79%	59.67 µs	81.04 µs
Cursor first page	15.44K	64.77 µs	±27.23%	60.29 µs	146.58 µs
Offset page 100 (no count)	12.18K	82.07 µs	±8.56%	80.96 µs	100.05 µs
Cursor next page chain	8.22K	121.71 µs	±9.15%	119.92 µs	160.47 µs
Offset page 1 (with count)	0.37K	2731.43 µs	±5.89%	2738.56 µs	3195.07 µs
Offset page 100 (with count)	0.36K	2759.19 µs	±5.48%	2766.46 µs	3148.26 µs

Relative Speed (vs. fastest baseline)

Method	Relative Speed	Latency Delta
Offset page 1 (no count)	1.00× (baseline)	—
Cursor first page	1.07× slower	+4.13 µs
Offset page 100 (no count)	1.35× slower	+21.44 µs
Cursor next page chain	2.01× slower	+61.07 µs
Offset page 1 (with count)	45.05× slower	+2670.79 µs
Offset page 100 (with count)	45.50× slower	+2698.55 µs

---

Memory Usage

Method	Avg Memory	Deviation	Median	p99
Offset page 1 (no count)	55.06 KB	±0.07%	55.05 KB	55.19 KB
Cursor first page	53.68 KB	±0.02%	53.67 KB	53.72 KB
Offset page 100 (no count)	55.30 KB	±0.02%	55.30 KB	55.34 KB
Cursor next page chain	109.01 KB	±0.01%	109.02 KB	109.02 KB
Offset page 1 (with count)	76.89 KB	±0.27%	76.83 KB	77.75 KB
Offset page 100 (with count)	77.10 KB	±0.16%	77.09 KB	77.59 KB

Relative Memory (vs. baseline)

Method	Relative Memory	Delta
Offset page 1 (no count)	1.00× (baseline)	—
Cursor first page	0.97×	−1.38 KB
Offset page 100 (no count)	1.00×	+0.24 KB
Cursor next page chain	1.98×	+53.95 KB
Offset page 1 (with count)	1.40×	+21.83 KB
Offset page 100 (with count)	1.40×	+22.04 KB

---

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

Scenario	Recommendation
Simple, shallow listing pages	✅ Offset pagination (no count)
Deep pagination / large datasets	✅ Cursor pagination
High-traffic hot paths	⛔ Avoid COUNT(*)

---

📦 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

2. Install Dependencies

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

    mix deps.get

3. Create a Branch

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

    git checkout -b feature/my-awesome-feature

4. 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.

5. 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

6. 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

7. 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