philiprehberger-pagination

Framework-agnostic pagination with cursor, offset, and keyset strategies

Requirements

Ruby >= 3.1

Installation

Add to your Gemfile:

gem "philiprehberger-pagination"

Or install directly:

gem install philiprehberger-pagination

Usage

require "philiprehberger/pagination"

page = Philiprehberger::Pagination.paginate(users,
  strategy: :offset,
  per_page: 25,
  page: 2
)

page.items       # => [user_26, user_27, ...]
page.total       # => 100
page.has_next?   # => true
page.has_prev?   # => true

Offset Pagination

page = Philiprehberger::Pagination.paginate(items, strategy: :offset, per_page: 10, page: 3)
page.next_cursor  # => "4" (next page number)
page.prev_cursor  # => "2" (previous page number)

Cursor Pagination

page = Philiprehberger::Pagination.paginate(items, strategy: :cursor, per_page: 10)
next_page = Philiprehberger::Pagination.paginate(items,
  strategy: :cursor,
  per_page: 10,
  cursor: page.next_cursor
)

Keyset Pagination

# Items must be sorted; cursor is based on the last item's value
page = Philiprehberger::Pagination.paginate(sorted_items, strategy: :keyset, per_page: 10)

Page Metadata

page = Philiprehberger::Pagination.paginate(items, strategy: :offset, per_page: 10, page: 2)
page.metadata
# => { current_page: 2, per_page: 10, total_pages: 5, total_count: 50, offset: 10 }

Page Size Limits

page = Philiprehberger::Pagination.paginate(items,
  per_page: 25,
  max_per_page: 100,
  min_per_page: 1
)
# Raises InvalidPageSizeError if per_page is out of bounds

Cursor Encryption

page = Philiprehberger::Pagination.paginate(items,
  strategy: :cursor,
  per_page: 10,
  secret: "my-secret-key"
)
# Cursors are signed with HMAC-SHA256
# Tampered cursors raise InvalidCursorError

API

`Pagination`

Method	Description
`.paginate(collection, strategy:, per_page:, cursor:, page:, max_per_page:, min_per_page:, secret:)`	Paginate a collection

`Page`

Method	Description
`#items`	Items on the current page
`#total`	Total number of items in the collection
`#next_cursor`	Cursor for the next page
`#prev_cursor`	Cursor for the previous page
`#has_next?`	Whether there is a next page
`#has_prev?`	Whether there is a previous page
`#links`	Hash of navigation cursors
`#metadata`	Hash with current_page, per_page, total_pages, total_count, offset
`#per_page`	Items per page
`#current_page`	Current page number (offset only)
`#offset`	Current offset (offset only)

Development

bundle install
bundle exec rspec
bundle exec rubocop

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT