bcthomas / cursor

Simple cursor pagination

Overview

Cursor is a fork of Kaminari that has been gutted to perform cursor pagination only for Rails and ActiveRecord

It’s currently a very simple implementation that pages by the id of the primary table.

Usage

Suppose we have users with ids 1..100

> User.page(before: 50).per(5)
=> [#<User id: 49>, #<User id: 48>, #<User id: 47>, #<User id: 46>, #<User id: 45>]  
> User.page(before: 50).per(5).next_cursor
=> 45
> User.page(before: 50).per(5).prev_cursor
=> 49

The before id is NOT included in the results. The next and previous cursors are the min and max ids of the returned set, respectively.

> User.page(after: 44).per(5)
=> [#<User id: 45>, #<User id: 46>, #<User id: 47>, #<User id: 48>, #<User id: 49>]  
> User.page(before: 50).per(5).next_cursor
=> 49
> User.page(before: 50).per(5).prev_cursor
=> 45

Note that the results are reversed from the before. Before implies order desc. After implies order asc. The cursors are similarly reversed. In both before and after, the specified cursor in the request is excluded from the result.

> User.page
=> [#<User id: 100>, #<User id: 99>, ... #<User id: 77>, #<User id: 76>]  

The default direction is before and the default per_page value is 25.

Configuration Options

You can configure the following default values by overriding these values using Cursor.configure method.

default_per_page  # 25 by default
max_per_page      # nil by default
page_method_name  # :page by default
before_param_name # :before by default
after_param_name  # :after by default

There's a handy generator that generates the default configuration file into config/initializers directory. Run the following generator command, then edit the generated file.

rails g cursor:config

Contributing

To run the test suite locally against all supported frameworks:

bundle install
rake spec:all

To target the test suite against one framework:

rake spec:active_record_40

You can find a list of supported spec tasks by running rake -T. You may also find it useful to run a specific test for a specific framework. To do so, you'll have to first make sure you have bundled everything for that configuration, then you can run the specific test:

BUNDLE_GEMFILE='gemfiles/active_record_40.gemfile' bundle install
BUNDLE_GEMFILE='gemfiles/active_record_40.gemfile' bundle exec rspec