Class: RailsCursorPagination::Paginator

Inherits:
Object
  • Object
show all
Defined in:
lib/rails_cursor_pagination/paginator.rb

Overview

Use this Paginator class to effortlessly paginate through ActiveRecord relations using cursor pagination. For more details on how this works, read the top-level documentation of the ‘RailsCursorPagination` module.

Usage:

RailsCursorPagination::Paginator
  .new(relation, order_by: :author, first: 2, after: "WyJKYW5lIiw0XQ==")
  .fetch

Instance Method Summary collapse

Constructor Details

#initialize(relation, limit: nil, first: nil, after: nil, last: nil, before: nil, order_by: nil, order: nil) ⇒ Paginator

Create a new instance of the ‘RailsCursorPagination::Paginator`

Parameters:

  • relation (ActiveRecord::Relation) —

    Relation that will be paginated.

  • limit (Integer, nil) (defaults to: nil) —

    Number of records to return in pagination. Can be combined with either ‘after` or `before` as an alternative to `first` or `last`.

  • first (Integer, nil) (defaults to: nil) —

    Number of records to return in a forward pagination. Can be combined with ‘after`.

  • after (String, nil) (defaults to: nil) —

    Cursor to paginate forward from. Can be combined with ‘first`.

  • last (Integer, nil) (defaults to: nil) —

    Number of records to return. Must be used together with ‘before`.

  • before (String, nil) (defaults to: nil) —

    Cursor to paginate upto (excluding). Can be combined with ‘last`.

  • order_by (Symbol, String, nil) (defaults to: nil) —

    Column to order by. If none is provided, will default to ID column. NOTE: this will cause the query to filter on both the given column as well as the ID column. So you might want to add a compound index to your database similar to: “‘sql

    CREATE INDEX <index_name> ON <table_name> (<order_by_field>, id)

    “‘

  • order (Symbol, nil) (defaults to: nil) —

    Ordering to apply, either ‘:asc` or `:desc`. Defaults to `:asc`.

Raises:



43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
 
# File 'lib/rails_cursor_pagination/paginator.rb', line 43

def initialize(relation, limit: nil, first: nil, after: nil, last: nil,
               before: nil, order_by: nil, order: nil)
  order_by ||= :id
  order ||= :asc

  ensure_valid_params_values!(relation, order, limit, first, last)
  ensure_valid_params_combinations!(first, last, limit, before, after)

  @order_field = order_by
  @order_direction = order
  @relation = relation

  @cursor = before || after
  @is_forward_pagination = before.blank?

  @page_size =
    first ||
    last ||
    limit ||
    RailsCursorPagination::Configuration.instance.default_page_size

  if Configuration.instance.max_page_size &&
     Configuration.instance.max_page_size < @page_size
    @page_size = Configuration.instance.max_page_size
  end

  @memos = {}
end

Instance Method Details

#fetch(with_total: false) ⇒ Hash

Get the paginated result, including the actual ‘page` with its data items and cursors as well as some meta data in `page_info` and an optional `total` of records across all pages.

Parameters:

  • with_total (TrueClass, FalseClass) (defaults to: false)

Returns:

  • (Hash) —

    with keys :page, :page_info, and optional :total



78
79
80
81
82
83
84
 
# File 'lib/rails_cursor_pagination/paginator.rb', line 78

def fetch(with_total: false)
  {
    **(with_total ? { total: total } : {}),
    page_info: page_info,
    page: page
  }
end