activerecord_cursor_paginate 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6a96b7bf3c40469653bf87dcf68cc159b30c389ed734047ef165b12d6ff7ef24
+  data.tar.gz: 2dea9c8b3847b5a72d6a915e9051e8b61891940e9feaa855edc822d49a393750
+SHA512:
+  metadata.gz: f54a87c366b7cfd08e59530b29fab0e0d5736cc323c4bab81ba0c3873ae5faa1254a2a9c94563e7aa9751debdb8802f28454a5781ddccf6811fe912c6808afca
+  data.tar.gz: c5689804eb34fa24e4e38f80994c9e3f16f45ab2594fe1fe9482397d2260b7d6db3453168a61fcb5f7e614ad97d8dfb6d8a1a42b4e560d780cebda759fd9f26d

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## master (unreleased)
+
+## 0.1.0 (2024-03-08)
+
+- First release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 fatkodima
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,374 @@
+# ActiveRecordCursorPaginate
+
+This library allows to paginate through an `ActiveRecord` relation using cursor pagination.
+It also supports ordering by any column on the relation in either ascending or descending order.
+
+Cursor pagination allows to paginate results and gracefully deal with deletions / additions on previous pages.
+Where a regular limit / offset pagination would jump in results if a record on a previous page gets deleted or added while requesting the next page, cursor pagination just returns the records following the one identified in the request.
+
+To learn more about cursor pagination, check out the _"How does it work?"_ section below.
+
+[![Build Status](https://github.com/fatkodima/activerecord_cursor_paginate/actions/workflows/test.yml/badge.svg?branch=master)](https://github.com/fatkodima/activerecord_cursor_paginate/actions/workflows/test.yml)
+
+## Requirements
+
+- Ruby 2.7+
+- Rails (ActiveRecord) 7.0+
+
+If you need support for older ruby and rails, please open an issue.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "activerecord_cursor_paginate"
+```
+
+And then run:
+
+```sh
+$ bundle install
+```
+
+## Usage
+
+Let's assume we have a `Post` model of which we want to fetch some data and then paginate through it.
+Therefore, we first apply our scopes, `where` clauses or other functionality as usual:
+
+```ruby
+posts = Post.where(author: "Jane")
+```
+
+And then we create our paginator to fetch the first response page:
+
+```ruby
+paginator = posts.cursor_paginate
+page = paginator.fetch
+page.records # => [#<Post:0x00007fd7071b2ea8 @id=1>, #<Post:0x00007fd7071bb738 @id=2>, ..., #<Post:0x00007fd707238260 @id=10>]
+page.count # => 10
+page.empty? # => false
+page.cursors            # => ["MQ==", "Mg==", ..., "MTA="]
+                                |                     |
+                                |                     |
+page.previous_cursor    # => "MQ=="                   |
+page.next_cursor        # => "MTA=" ------------------|
+page.has_previous? # => false
+page.has_next? # => true
+```
+
+Note that any ordering of the relation at this stage will be ignored by the gem.
+Take a look at the next section _"Ordering"_ to see how you can have an order different than ascending IDs.
+
+To then get the next result page, you simply need to pass the last cursor of the returned page item via:
+
+```ruby
+paginator = posts.cursor_paginate(after: "MTA=")
+```
+
+This will then fetch the next result page.
+You can also just as easily paginate to previous pages by using `before` instead of `after` and using the first cursor of the current page.
+
+```ruby
+paginator = posts.cursor_paginate(before: "MQ==")
+```
+
+By default, this will always return up to 10 results. But you can also specify how many records should be returned via `limit` parameter.
+
+```ruby
+paginator = posts.cursor_paginate(after: "MTA=", limit: 2)
+```
+
+```ruby
+paginator = posts.cursor_paginate(before: "MQ==", limit: 2)
+```
+
+You can also easily iterate over the whole relation:
+
+```ruby
+paginator = posts.cursor_paginate
+
+# Will lazily iterate over the pages.
+paginator.pages.each do |page|
+  # do something with the page
+end
+```
+
+### Ordering
+
+As said, this gem ignores any previous ordering added to the passed relation.
+But you can still paginate through relations with an order different than by ascending IDs.
+
+You can specify a different column and direction to order the results by via an `order` parameter.
+
+```ruby
+# Order records ascending by the `:author` field.
+paginator = posts.cursor_paginate(order: :author)
+
+# Order records descending by the `:author` field.
+paginator = posts.cursor_paginate(order: { author: :desc })
+
+# Order records ascending by the `:author` and `:title` fields.
+paginator = posts.cursor_paginate(order: [:author, :title])
+
+# Order records ascending by the `:author` and descending by the `:title` fields.
+paginator = posts.cursor_paginate(order: { author: :asc, title: :desc })
+```
+
+**Important:**
+If your app regularly orders by another column, you might want to add a database index for this.
+Say that your order column is `author` then you'll want to add a compound index on `(author, id)`.
+If your table is called `posts` you can use a query like this in MySQL or PostgreSQL:
+
+```sql
+CREATE INDEX index_posts_on_author_and_id ON posts (author, id)
+```
+
+Or you can just do it via an `ActiveRecord::Migration`:
+
+```ruby
+class AddAuthorAndIdIndexToPosts < ActiveRecord::Migration[7.1]
+  def change
+    add_index :posts, [:author, :id]
+  end
+end
+```
+
+Take a look at the _"How does it work?"_ to find out more why this is necessary.
+
+#### Ordering and `JOIN`s
+
+To order by a column from the `JOIN`ed table, you need to explicitly specify and fully qualify the column name for the `:order` parameter:
+
+```ruby
+paginator = User.joins(:projects).cursor_paginate(order: [Arel.sql("projects.id"), :id])
+page = paginator.fetch
+```
+
+**Note**: Make sure to wrap custom SQL expressions by `Arel.sql`.
+
+#### Order by more complex logic
+
+Sometimes you might not only want to oder by a column ascending or descending, but need more complex logic.
+Imagine you would also store the post's `category` on the `posts` table (as a plain string for simplicity's sake).
+And the category could be `pinned`, `announcement`, or `general`.
+Then you might want to show all `pinned` posts first, followed by the `announcement` ones and lastly show the `general` posts.
+
+In MySQL you could e.g. use a `FIELD(category, 'pinned', 'announcement', 'general')` query in the `ORDER BY` clause to achieve this.
+However, you cannot add an index to such a statement. And therefore, the performance of this is pretty dismal.
+
+The gem supports ordering by custom SQL expressions, but make sure the performance will not suffer.
+
+What is recommended if you _do_ need to order by more complex logic is to have a separate column that you only use for ordering.
+You can use `ActiveRecord` hooks to automatically update this column whenever you change your data.
+Or, for example in MySQL, you can also use a [generated column](https://dev.mysql.com/doc/refman/5.7/en/create-table-generated-columns.html) that is automatically being updated by the database based on some stored logic.
+
+For example, if you want paginate `users` by a lowercased `email`, you can use the following:
+
+```ruby
+paginator = User.cursor_paginate(order: Arel.sql("lower(email)"))
+page = paginator.fetch
+```
+
+**Note**: Make sure to wrap custom SQL expressions by `Arel.sql`.
+
+### Configuration
+
+You can change the default page size to a value that better fits the needs of your application.
+So if a user doesn't request a given `:limit` value, the default amount of records is being returned.
+
+To change the default, simply add an initializer to your app that does the following:
+
+```ruby
+# config/initializers/activerecord_cursor_paginate.rb
+ActiveRecordCursorPaginate.configure do |config|
+  config.default_page_size = 50
+end
+```
+
+This would set the default page size to 50.
+
+You can also set a global `max_page_size` to prevent a client from requesting too large pages.
+
+```ruby
+ActiveRecordCursorPaginate.configure do |config|
+  config.max_page_size = 100
+end
+```
+
+## How does it work?
+
+This library allows to paginate through a passed relation using a cursor
+for before or after parameters. It also supports ordering by any column
+on the relation in either ascending or descending order.
+
+Cursor pagination allows to paginate results and gracefully deal with
+deletions / additions on previous pages. Where a regular limit / offset
+pagination would jump in results if a record on a previous page gets deleted
+or added while requesting the next page, cursor pagination just returns the
+records following the one identified in the request.
+
+How this works is that it uses a "cursor", which is an encoded value that
+uniquely identifies a given row for the requested order. Then, based on
+this cursor, you can request the "n records AFTER the cursor"
+(forward-pagination) or the "n records BEFORE the cursor" (backward-pagination).
+
+As an example, assume we have a table called "posts" with this data:
+
+    | id | author |
+    |----|--------|
+    | 1  | Jane   |
+    | 2  | John   |
+    | 3  | John   |
+    | 4  | Jane   |
+    | 5  | Jane   |
+    | 6  | John   |
+    | 7  | John   |
+
+Now if we make a basic request without any `before`, `after`, custom `order` column,
+this will just request the first page of this relation.
+
+```ruby
+paginator = relation.cursor_paginate
+page = paginator.fetch
+```
+
+Assume that our default page size here is 2 and we would get a query like this:
+
+```sql
+SELECT *
+FROM "posts"
+ORDER BY "posts"."id" ASC
+LIMIT 2
+```
+
+This will return the first page of results, containing post #1 and #2. Since
+no custom order is defined, each item in the returned collection will have a
+cursor that only encodes the record's ID.
+
+If we want to now request the next page, we can pass in the cursor of record
+#2 which would be `"Mg=="` (can get via `page.cursor`). So now we can request
+the next page by calling:
+
+```ruby
+paginator = relation.cursor_paginate(limit: 2, after: "Mg==")
+page = paginator.fetch
+```
+
+And this will decode the given cursor and issue a query like:
+
+```sql
+SELECT *
+FROM "posts"
+WHERE "posts"."id" > 2
+ORDER BY "posts"."id" ASC
+LIMIT 2
+```
+
+Which would return posts #3 and #4. If we now want to paginate back, we can
+request the posts that came before the first post, whose cursor would be
+`"Mw=="` (can get via `page.previous_cursor`):
+
+```ruby
+paginator = relation.cursor_paginate(limit: 2, before: "Mw==")
+page = paginator.fetch
+```
+
+Since we now paginate backward, the resulting SQL query needs to be flipped
+around to get the last two records that have an ID smaller than the given one:
+
+```sql
+SELECT *
+FROM "posts"
+WHERE "posts"."id" < 3
+ORDER BY "posts"."id" DESC
+LIMIT 2
+```
+
+This would return posts #2 and #1. Since we still requested them in
+ascending order, the result will be reversed before it is returned.
+
+Now, in case that the user wants to order by a column different than the ID,
+we require this information in our cursor. Therefore, when requesting the
+first page like this:
+
+```ruby
+paginator = relation.cursor_paginate(order: :author)
+page = paginator.fetch
+```
+
+This will issue the following SQL query:
+
+```sql
+SELECT *
+FROM "posts"
+ORDER BY "posts"."author" ASC, "posts"."id" ASC
+LIMIT 2
+```
+
+As you can see, this will now order by the author first, and if two records
+have the same author it will order them by ID. Ordering only the author is not
+enough since we cannot know if the custom column only has unique values.
+And we need to guarantee the correct order of ambiguous records independent
+of the direction of ordering. This unique order is the basis of being able
+to paginate forward and backward repeatedly and getting the correct records.
+
+The query will then return records #1 and #4. But the cursor for these
+records will also be different to the previous query where we ordered by ID
+only. It is important that the cursor encodes all the data we need to
+uniquely identify a row and filter based upon it. Therefore, we need to
+encode the same information as we used for the ordering in our SQL query.
+Hence, the cursor for pagination with a custom column contains a tuple of
+data, the first record being the custom order column followed by the
+record's ID.
+
+Therefore, the cursor of record #4 will encode `['Jane', 4]`, which yields
+this cursor: `"WyJKYW5lIiw0XQ=="`.
+
+If we now want to request the next page via:
+
+```ruby
+paginator = relation.cursor_paginate(order: :author, limit: 2, after: "WyJKYW5lIiw0XQ==")
+page = paginator.fetch
+```
+
+We get this SQL query:
+
+```sql
+SELECT *
+FROM "posts"
+WHERE (author > 'Jane' OR (author = 'Jane') AND ("posts"."id" > 4))
+ORDER BY "posts"."author" ASC, "posts"."id" ASC
+LIMIT 2
+```
+
+You can see how the cursor is being used by the WHERE clause to uniquely
+identify the row and properly filter based on this. We only want to get
+records that either have a name that is alphabetically after `"Jane"` or
+another `"Jane"` record with an ID that is higher than `4`. We will get the
+records #5 and #2 as response.
+
+When using a custom `order`, this affects both filtering as well as
+ordering. Therefore, it is recommended to add an index for columns that are
+frequently used for ordering. In our test case we would want to add a compound
+index for the `(author, id)` column combination. Databases like MySQL and
+PostgreSQL are able to then use the leftmost part of the index, in our case
+`author`, by its own or can use it combined with the `id` index.
+
+## Credits
+
+Thanks to [rails_cursor_pagination gem](https://github.com/xing/rails_cursor_pagination) for the original ideas.
+
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies. Then, run `bundle exec rake` to run the linter and tests. This project uses multiple Gemfiles to test against multiple versions of Active Record; you can run the tests against the specific version with `BUNDLE_GEMFILE=gemfiles/activerecord_71.gemfile bundle exec rake test`.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/fatkodima/activerecord_cursor_paginate.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/activerecord_cursor_paginate/config.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module ActiveRecordCursorPaginate
+  class Config
+    attr_accessor :default_page_size, :max_page_size
+
+    def initialize
+      @default_page_size = 10
+    end
+  end
+end

data/lib/activerecord_cursor_paginate/cursor.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+
+module ActiveRecordCursorPaginate
+  # @private
+  class Cursor
+    class << self
+      def from_record(record, columns:)
+        columns = columns.map { |column| column.to_s.split(".").last }
+        values = columns.map { |column| record[column] }
+        new(columns: columns, values: values)
+      end
+
+      def decode(cursor_string:, columns:)
+        decoded = JSON.parse(Base64.strict_decode64(cursor_string))
+
+        if (columns.size == 1 && decoded.is_a?(Array)) ||
+           (decoded.is_a?(Array) && decoded.size != columns.size)
+          raise InvalidCursorError,
+                "The given cursor `#{cursor_string}` was decoded as `#{decoded}` but could not be parsed"
+        end
+
+        decoded =
+          if decoded.is_a?(Array)
+            decoded.map { |value| deserialize_time_if_needed(value) }
+          else
+            deserialize_time_if_needed(decoded)
+          end
+
+        new(columns: columns, values: decoded)
+      rescue ArgumentError, JSON::ParserError # ArgumentError is raised by strict_decode64
+        raise InvalidCursorError, "The given cursor `#{cursor_string}` could not be decoded"
+      end
+
+      private
+        def deserialize_time_if_needed(value)
+          if value.is_a?(String) && value.start_with?(TIMESTAMP_PREFIX)
+            seconds_with_frac = value.delete_prefix(TIMESTAMP_PREFIX).to_r / (10**6)
+            Time.at(seconds_with_frac).utc
+          else
+            value
+          end
+        end
+    end
+
+    attr_reader :columns, :values
+
+    def initialize(columns:, values:)
+      @columns = Array(columns)
+      @values = Array(values)
+
+      raise ArgumentError, "Cursor values can not be nil" if @values.any?(nil)
+      raise ArgumentError, ":columns and :values have different sizes" if @columns.size != @values.size
+    end
+
+    def encode
+      serialized_values = values.map do |value|
+        if value.is_a?(Time)
+          TIMESTAMP_PREFIX + value.strftime("%s%6N")
+        else
+          value
+        end
+      end
+      unencoded_cursor = (serialized_values.size == 1 ? serialized_values.first : serialized_values)
+      Base64.strict_encode64(unencoded_cursor.to_json)
+    end
+
+    TIMESTAMP_PREFIX = "0aIX2_" # something random
+    private_constant :TIMESTAMP_PREFIX
+  end
+end

data/lib/activerecord_cursor_paginate/extension.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module ActiveRecordCursorPaginate
+  module Extension
+    # Convenient method to use on ActiveRecord::Relation to get a paginator.
+    # @return [ActiveRecordCursorPaginate::Paginator]
+    #
+    # @example
+    #   paginator = Post.all.cursor_paginate(limit: 2, after: "Mg==")
+    #   page = paginator.fetch
+    #
+    def cursor_paginate(after: nil, before: nil, limit: nil, order: nil)
+      relation = (is_a?(ActiveRecord::Relation) ? self : all)
+      Paginator.new(relation, after: after, before: before, limit: limit, order: order)
+    end
+    alias cursor_pagination cursor_paginate
+  end
+end

data/lib/activerecord_cursor_paginate/page.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module ActiveRecordCursorPaginate
+  # Represents a batch of records retrieved via a single iteration of
+  # cursor-based pagination.
+  #
+  class Page
+    # Records this page contains.
+    # @return [ActiveRecord::Base]
+    #
+    attr_reader :records
+
+    def initialize(records, order_columns:, has_previous: false, has_next: false)
+      @records = records
+      @order_columns = order_columns
+      @has_previous = has_previous
+      @has_next = has_next
+    end
+
+    # Number of records in this page.
+    # @return [Integer]
+    #
+    def count
+      records.size
+    end
+
+    # Whether this page is empty.
+    # @return [Boolean]
+    #
+    def empty?
+      count == 0
+    end
+
+    # Returns the cursor, which can be used to retrieve the next page.
+    # @return [String]
+    #
+    def next_cursor
+      cursor_for_record(records.last)
+    end
+    alias cursor next_cursor
+
+    # Returns the cursor, which can be used to retrieve the previous page.
+    # @return [String]
+    #
+    def previous_cursor
+      cursor_for_record(records.first)
+    end
+
+    # Whether this page has a previous page.
+    # @return [Boolean]
+    #
+    def has_previous?
+      @has_previous
+    end
+
+    # Whether this page has a next page.
+    # @return [Boolean]
+    #
+    def has_next?
+      @has_next
+    end
+
+    # Returns cursor for a specific record.
+    #
+    # @param record [ActiveRecord::Base]
+    # @return [String]
+    #
+    def cursor_for(record)
+      cursor_for_record(record)
+    end
+
+    # Returns cursors for all the records on this page.
+    # @return [Array<String>]
+    #
+    def cursors
+      records.map { |record| cursor_for_record(record) }
+    end
+
+    private
+      def cursor_for_record(record)
+        cursor = Cursor.from_record(record, columns: @order_columns)
+        cursor.encode
+      end
+  end
+end

data/lib/activerecord_cursor_paginate/paginator.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+module ActiveRecordCursorPaginate
+  # Use this Paginator class to effortlessly paginate through ActiveRecord
+  # relations using cursor pagination.
+  #
+  # @example Iterating one page at a time
+  #     ActiveRecordCursorPaginate::Paginator
+  #       .new(relation, order: :author, limit: 2, after: "WyJKYW5lIiw0XQ==")
+  #       .fetch
+  #
+  # @example Iterating over the whole relation
+  #     paginator = ActiveRecordCursorPaginate::Paginator
+  #                   .new(relation, order: :author, limit: 2, after: "WyJKYW5lIiw0XQ==")
+  #
+  #     # Will lazily iterate over the pages.
+  #     paginator.pages.each do |page|
+  #       # do something with the page
+  #     end
+  #
+  class Paginator
+    # Create a new instance of the `ActiveRecordCursorPaginate::Paginator`
+    #
+    # @param relation [ActiveRecord::Relation] Relation that will be paginated.
+    # @param before [String, nil] Cursor to paginate upto (excluding).
+    # @param after [String, nil] Cursor to paginate forward from.
+    # @param limit [Integer, nil] Number of records to return in pagination.
+    # @param order [Symbol, String, nil, Array<Symbol, String>, Hash]
+    #   Column(s) to order by, optionally with directions (either `:asc` or `:desc`,
+    #   defaults to `:asc`). 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_fields>..., id)
+    #   ```
+    # @raise [ArgumentError] If any parameter is not valid
+    #
+    def initialize(relation, before: nil, after: nil, limit: nil, order: nil)
+      unless relation.is_a?(ActiveRecord::Relation)
+        raise ArgumentError, "relation is not an ActiveRecord::Relation"
+      end
+
+      if before.present? && after.present?
+        raise ArgumentError, "Only one of :before and :after can be provided"
+      end
+
+      @relation = relation
+      @primary_key = @relation.primary_key
+      @cursor = before || after
+      @is_forward_pagination = before.blank?
+
+      config = ActiveRecordCursorPaginate.config
+      @page_size = limit || config.default_page_size
+      @page_size = [@page_size, config.max_page_size].min if config.max_page_size
+
+      order = normalize_order(order)
+      @columns = order.keys
+      @directions = order.values
+    end
+
+    # Get the paginated result.
+    # @return [ActiveRecordCursorPaginate::Page]
+    #
+    # @note Calling this method advances the paginator.
+    #
+    def fetch
+      relation = @relation
+
+      # Non trivial columns (expressions or joined tables columns).
+      if @columns.any?(/\W/)
+        arel_columns = @columns.map.with_index do |column, i|
+          arel_column(column).as("cursor_column_#{i + 1}")
+        end
+        cursor_column_names = 1.upto(@columns.size).map { |i| "cursor_column_#{i}" }
+
+        relation =
+          if relation.select_values.empty?
+            relation.select(Arel.star, arel_columns)
+          else
+            relation.select(arel_columns)
+          end
+      else
+        cursor_column_names = @columns
+      end
+
+      pagination_directions = @directions.map { |direction| pagination_direction(direction) }
+      relation = relation.reorder(cursor_column_names.zip(pagination_directions).to_h)
+
+      if @cursor
+        decoded_cursor = Cursor.decode(cursor_string: @cursor, columns: @columns)
+        relation = apply_cursor(relation, decoded_cursor)
+      end
+
+      relation = relation.limit(@page_size + 1)
+      records_plus_one = relation.to_a
+      has_additional = records_plus_one.size > @page_size
+
+      records = records_plus_one.take(@page_size)
+      records.reverse! unless @is_forward_pagination
+
+      if @is_forward_pagination
+        has_next_page = has_additional
+        has_previous_page = @cursor.present?
+      else
+        has_next_page = @cursor.present?
+        has_previous_page = has_additional
+      end
+
+      page = Page.new(
+        records,
+        order_columns: cursor_column_names,
+        has_next: has_next_page,
+        has_previous: has_previous_page
+      )
+
+      advance_by_page(page) unless page.empty?
+
+      page
+    end
+    alias page fetch
+
+    # Returns an enumerator that can be used to iterate over the whole relation.
+    # @return [Enumerator]
+    #
+    def pages
+      Enumerator.new do |yielder|
+        loop do
+          page = fetch
+          break if page.empty?
+
+          yielder.yield(page)
+        end
+      end
+    end
+
+    private
+      def normalize_order(order)
+        order ||= {}
+        default_direction = :asc
+
+        result =
+          case order
+          when String, Symbol
+            { order => default_direction }
+          when Hash
+            order
+          when Array
+            order.to_h { |column| [column, default_direction] }
+          else
+            raise ArgumentError, "Invalid order: #{order.inspect}"
+          end
+
+        result = result.with_indifferent_access
+        result.transform_values! { |direction| direction.downcase.to_sym }
+        Array(@primary_key).each { |column| result[column] ||= default_direction }
+        result
+      end
+
+      def apply_cursor(relation, cursor)
+        operators = @directions.map { |direction| pagination_operator(direction) }
+        cursor_positions = cursor.columns.zip(cursor.values, operators)
+
+        where_clause = nil
+        cursor_positions.reverse_each.with_index do |(column, value, operator), index|
+          where_clause =
+            if index == 0
+              arel_column(column).public_send(operator, value)
+            else
+              arel_column(column).public_send(operator, value).or(
+                arel_column(column).eq(value).and(where_clause)
+              )
+            end
+        end
+
+        relation.where(where_clause)
+      end
+
+      def arel_column(column)
+        if Arel.arel_node?(column)
+          column
+        elsif column.match?(/\A\w+\.\w+\z/)
+          Arel.sql(column)
+        else
+          @relation.arel_table[column]
+        end
+      end
+
+      def pagination_direction(direction)
+        if @is_forward_pagination
+          direction
+        else
+          direction == :asc ? :desc : :asc
+        end
+      end
+
+      def pagination_operator(direction)
+        if @is_forward_pagination
+          direction == :asc ? :gt : :lt
+        else
+          direction == :asc ? :lt : :gt
+        end
+      end
+
+      def advance_by_page(page)
+        @cursor =
+          if @is_forward_pagination
+            page.next_cursor
+          else
+            page.previous_cursor
+          end
+      end
+  end
+end

data/lib/activerecord_cursor_paginate/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ActiveRecordCursorPaginate
+  VERSION = "0.1.0"
+end

data/lib/activerecord_cursor_paginate.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "active_record"
+
+require_relative "activerecord_cursor_paginate/version"
+require_relative "activerecord_cursor_paginate/cursor"
+require_relative "activerecord_cursor_paginate/page"
+require_relative "activerecord_cursor_paginate/paginator"
+require_relative "activerecord_cursor_paginate/extension"
+require_relative "activerecord_cursor_paginate/config"
+
+module ActiveRecordCursorPaginate
+  class Error < StandardError; end
+
+  # Error that gets raised if a cursor given as `before` or `after` cannot be
+  # properly parsed.
+  class InvalidCursorError < Error; end
+
+  class << self
+    def configure
+      yield config
+    end
+
+    def config
+      @config ||= Config.new
+    end
+  end
+end
+
+ActiveSupport.on_load(:active_record) do
+  extend ActiveRecordCursorPaginate::Extension
+end

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification
+name: activerecord_cursor_paginate
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- fatkodima
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-03-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+description:
+email:
+- fatkodima123@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/activerecord_cursor_paginate.rb
+- lib/activerecord_cursor_paginate/config.rb
+- lib/activerecord_cursor_paginate/cursor.rb
+- lib/activerecord_cursor_paginate/extension.rb
+- lib/activerecord_cursor_paginate/page.rb
+- lib/activerecord_cursor_paginate/paginator.rb
+- lib/activerecord_cursor_paginate/version.rb
+homepage: https://github.com/fatkodima/activerecord_cursor_paginate
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/fatkodima/activerecord_cursor_paginate
+  source_code_uri: https://github.com/fatkodima/activerecord_cursor_paginate
+  changelog_uri: https://github.com/fatkodima/activerecord_cursor_paginate/blob/master/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.4
+signing_key:
+specification_version: 4
+summary: Cursor-based pagination for ActiveRecord.
+test_files: []