activerecord_cursor_paginate 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a96b7bf3c40469653bf87dcf68cc159b30c389ed734047ef165b12d6ff7ef24
-  data.tar.gz: 2dea9c8b3847b5a72d6a915e9051e8b61891940e9feaa855edc822d49a393750
+  metadata.gz: 198c2d0c2e71f89e73fca64d7ab8711949cf25faa20af6297d1d6045587ec7cf
+  data.tar.gz: 6f60b98579b2dcd132c09d4f75105b5cab7219ae8841c6970df9e77df6b59722
 SHA512:
-  metadata.gz: f54a87c366b7cfd08e59530b29fab0e0d5736cc323c4bab81ba0c3873ae5faa1254a2a9c94563e7aa9751debdb8802f28454a5781ddccf6811fe912c6808afca
-  data.tar.gz: c5689804eb34fa24e4e38f80994c9e3f16f45ab2594fe1fe9482397d2260b7d6db3453168a61fcb5f7e614ad97d8dfb6d8a1a42b4e560d780cebda759fd9f26d
+  metadata.gz: 85fd85af08637f1c22e52430f51bae57c5b116af2f843703dd2ab528d36616bf323d686c53c7b059fb04aa176a01bc0ec2a3c5a2b40acb6f54cf5412e2770e10
+  data.tar.gz: be0771bacd8fbd5f110c9f90927a12792ef85d8f4e4278e46321e96d82f93f87b848ad71b86cd9150c9465c39e5d8dd3a4e2a71672e51d7d7c04f00cbb561990

data/CHANGELOG.md

@@ -1,5 +1,46 @@
 ## master (unreleased)
 
+## 0.3.0 (2025-01-06)
+
+- Allow paginating over nullable columns
+
+    Previously, the error was raised when cursor values contained `nil`s. Now, it is possible to paginate
+    over columns containing `nil` values. You need to explicitly configure which columns are nullable,
+    otherwise columns are considered as non-nullable by the gem.
+
+    ```ruby
+    paginator = users.cursor_paginate(order: [:name, :id], nullable_columns: [:name])
+    ```
+
+    Note that it is not recommended to use this feature, because the complexity of produced SQL queries can have
+    a very negative impact on the database performance. It is better to paginate using only non-nullable columns.
+
+- Fix paginating over relations with joins, includes and custom ordering
+- Add ability to incrementally configure a paginator
+
+- Add ability to get the total number of records
+
+    ```ruby
+    paginator = posts.cursor_paginate
+    paginator.total_count # => 145
+    ```
+
+## 0.2.0 (2024-05-23)
+
+- Fix prefixing selected columns when iterating over joined tables
+- Change cursor encoding to url safe base64
+- Fix `next_cursor`/`previous_cursor` for empty pages
+- Fix iterating using only a timestamp column
+
+- Add the ability to skip implicitly appending a primary key to the list of sorting columns.
+
+    It may be useful to disable it for the table with a UUID primary key or when the sorting
+    is done by a combination of columns that are already unique.
+
+    ```ruby
+    paginator = UserSettings.cursor_paginate(order: :user_id, append_primary_key: false)
+    ```
+
 ## 0.1.0 (2024-03-08)
 
 - First release

data/README.md

@@ -8,7 +8,7 @@ Where a regular limit / offset pagination would jump in results if a record on a
 
 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)
+[![Build Status](https://github.com/healthie/activerecord_cursor_paginate/actions/workflows/test.yml/badge.svg?branch=master)](https://github.com/healthie/activerecord_cursor_paginate/actions/workflows/test.yml)
 
 ## Requirements
 
@@ -44,15 +44,22 @@ And then we create our paginator to fetch the first response page:
 
 ```ruby
 paginator = posts.cursor_paginate
+
+# Total number of records to iterate by this paginator
+paginator.total_count # => 145
+
 page = paginator.fetch
 page.records # => [#<Post:0x00007fd7071b2ea8 @id=1>, #<Post:0x00007fd7071bb738 @id=2>, ..., #<Post:0x00007fd707238260 @id=10>]
+
+# Number of records in this page
 page.count # => 10
+
 page.empty? # => false
-page.cursors            # => ["MQ==", "Mg==", ..., "MTA="]
-                                |                     |
-                                |                     |
-page.previous_cursor    # => "MQ=="                   |
-page.next_cursor        # => "MTA=" ------------------|
+page.cursors            # => ["MQ", "Mg", ..., "MTA"]
+                               |                 |
+                               |                 |
+page.previous_cursor    # =>  "MQ"               |
+page.next_cursor        # =>  "MTA" -------------|
 page.has_previous? # => false
 page.has_next? # => true
 ```
@@ -63,24 +70,24 @@ Take a look at the next section _"Ordering"_ to see how you can have an order di
 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=")
+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==")
+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)
+paginator = posts.cursor_paginate(after: "MTA", limit: 2)
 ```
 
 ```ruby
-paginator = posts.cursor_paginate(before: "MQ==", limit: 2)
+paginator = posts.cursor_paginate(before: "MQ", limit: 2)
 ```
 
 You can also easily iterate over the whole relation:
@@ -115,6 +122,14 @@ paginator = posts.cursor_paginate(order: [:author, :title])
 paginator = posts.cursor_paginate(order: { author: :asc, title: :desc })
 ```
 
+The gem implicitly appends a primary key column to the list of sorting columns. It may be useful
+to disable it for the table with a UUID primary key or when the sorting is done by a combination
+of columns that are already unique.
+
+```ruby
+paginator = UserSettings.cursor_paginate(order: :user_id, append_primary_key: false)
+```
+
 **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)`.
@@ -149,7 +164,7 @@ page = paginator.fetch
 
 #### Order by more complex logic
 
-Sometimes you might not only want to oder by a column ascending or descending, but need more complex logic.
+Sometimes you might not only want to order 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.
@@ -215,15 +230,15 @@ this cursor, you can request the "n records AFTER the cursor"
 
 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   |
+| 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.
@@ -237,8 +252,8 @@ 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
+FROM posts
+ORDER BY id ASC
 LIMIT 2
 ```
 
@@ -247,11 +262,11 @@ 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
+#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==")
+paginator = relation.cursor_paginate(limit: 2, after: "Mg")
 page = paginator.fetch
 ```
 
@@ -259,18 +274,18 @@ 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
+FROM posts
+WHERE id > 2
+ORDER BY 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`):
+`"Mw"` (can get via `page.previous_cursor`):
 
 ```ruby
-paginator = relation.cursor_paginate(limit: 2, before: "Mw==")
+paginator = relation.cursor_paginate(limit: 2, before: "Mw")
 page = paginator.fetch
 ```
 
@@ -279,9 +294,9 @@ 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
+FROM posts
+WHERE id < 3
+ORDER BY id DESC
 LIMIT 2
 ```
 
@@ -301,8 +316,8 @@ This will issue the following SQL query:
 
 ```sql
 SELECT *
-FROM "posts"
-ORDER BY "posts"."author" ASC, "posts"."id" ASC
+FROM posts
+ORDER BY author ASC, id ASC
 LIMIT 2
 ```
 
@@ -323,12 +338,12 @@ 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=="`.
+this cursor: `"WyJKYW5lIiw0XQ"`.
 
 If we now want to request the next page via:
 
 ```ruby
-paginator = relation.cursor_paginate(order: :author, limit: 2, after: "WyJKYW5lIiw0XQ==")
+paginator = relation.cursor_paginate(order: :author, limit: 2, after: "WyJKYW5lIiw0XQ")
 page = paginator.fetch
 ```
 
@@ -336,9 +351,9 @@ 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
+FROM posts
+WHERE (author > 'Jane' OR (author = 'Jane') AND (id > 4))
+ORDER BY author ASC, id ASC
 LIMIT 2
 ```
 
@@ -367,7 +382,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/fatkodima/activerecord_cursor_paginate.
+Bug reports and pull requests are welcome on GitHub at https://github.com/healthie/activerecord_cursor_paginate.
 
 ## License
 

data/lib/activerecord_cursor_paginate/cursor.rb

@@ -7,14 +7,13 @@ module ActiveRecordCursorPaginate
   # @private
   class Cursor
     class << self
-      def from_record(record, columns:)
-        columns = columns.map { |column| column.to_s.split(".").last }
+      def from_record(record, columns:, nullable_columns: nil)
         values = columns.map { |column| record[column] }
-        new(columns: columns, values: values)
+        new(columns: columns, values: values, nullable_columns: nullable_columns)
       end
 
-      def decode(cursor_string:, columns:)
-        decoded = JSON.parse(Base64.strict_decode64(cursor_string))
+      def decode(cursor_string:, columns:, nullable_columns: nil)
+        decoded = JSON.parse(Base64.urlsafe_decode64(cursor_string))
 
         if (columns.size == 1 && decoded.is_a?(Array)) ||
            (decoded.is_a?(Array) && decoded.size != columns.size)
@@ -29,7 +28,7 @@ module ActiveRecordCursorPaginate
             deserialize_time_if_needed(decoded)
           end
 
-        new(columns: columns, values: decoded)
+        new(columns: columns, values: decoded, nullable_columns: nullable_columns)
       rescue ArgumentError, JSON::ParserError # ArgumentError is raised by strict_decode64
         raise InvalidCursorError, "The given cursor `#{cursor_string}` could not be decoded"
       end
@@ -47,11 +46,16 @@ module ActiveRecordCursorPaginate
 
     attr_reader :columns, :values
 
-    def initialize(columns:, values:)
-      @columns = Array(columns)
-      @values = Array(values)
+    def initialize(columns:, values:, nullable_columns: nil)
+      @columns = Array.wrap(columns)
+      @values = Array.wrap(values)
+      @nullable_columns = Array.wrap(nullable_columns)
+
+      nil_index = @values.index(nil)
+      if nil_index && !@nullable_columns.include?(@columns[nil_index])
+        raise ArgumentError, "Cursor value is nil for a column that is not in the :nullable_columns list"
+      end
 
-      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
 
@@ -64,7 +68,7 @@ module ActiveRecordCursorPaginate
         end
       end
       unencoded_cursor = (serialized_values.size == 1 ? serialized_values.first : serialized_values)
-      Base64.strict_encode64(unencoded_cursor.to_json)
+      Base64.urlsafe_encode64(unencoded_cursor.to_json, padding: false)
     end
 
     TIMESTAMP_PREFIX = "0aIX2_" # something random

data/lib/activerecord_cursor_paginate/extension.rb

@@ -4,14 +4,14 @@ module ActiveRecordCursorPaginate
   module Extension
     # Convenient method to use on ActiveRecord::Relation to get a paginator.
     # @return [ActiveRecordCursorPaginate::Paginator]
+    # @see ActiveRecordCursorPaginate::Paginator#initialize
     #
     # @example
-    #   paginator = Post.all.cursor_paginate(limit: 2, after: "Mg==")
+    #   paginator = Post.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)
+    def cursor_paginate(**options)
+      Paginator.new(all, **options)
     end
     alias cursor_pagination cursor_paginate
   end

data/lib/activerecord_cursor_paginate/page.rb

@@ -6,15 +6,16 @@ module ActiveRecordCursorPaginate
   #
   class Page
     # Records this page contains.
-    # @return [ActiveRecord::Base]
+    # @return [Array<ActiveRecord::Base>]
     #
     attr_reader :records
 
-    def initialize(records, order_columns:, has_previous: false, has_next: false)
+    def initialize(records, order_columns:, has_previous: false, has_next: false, nullable_columns: nil)
       @records = records
       @order_columns = order_columns
       @has_previous = has_previous
       @has_next = has_next
+      @nullable_columns = nullable_columns
     end
 
     # Number of records in this page.
@@ -78,8 +79,10 @@ module ActiveRecordCursorPaginate
 
     private
       def cursor_for_record(record)
-        cursor = Cursor.from_record(record, columns: @order_columns)
-        cursor.encode
+        if record
+          cursor = Cursor.from_record(record, columns: @order_columns, nullable_columns: @nullable_columns)
+          cursor.encode
+        end
       end
   end
 end

data/lib/activerecord_cursor_paginate/paginator.rb

@@ -6,12 +6,12 @@ module ActiveRecordCursorPaginate
   #
   # @example Iterating one page at a time
   #     ActiveRecordCursorPaginate::Paginator
-  #       .new(relation, order: :author, limit: 2, after: "WyJKYW5lIiw0XQ==")
+  #       .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==")
+  #                   .new(relation, order: :author, limit: 2, after: "WyJKYW5lIiw0XQ")
   #
   #     # Will lazily iterate over the pages.
   #     paginator.pages.each do |page|
@@ -19,6 +19,8 @@ module ActiveRecordCursorPaginate
   #     end
   #
   class Paginator
+    attr_reader :relation, :before, :after, :limit, :order, :append_primary_key
+
     # Create a new instance of the `ActiveRecordCursorPaginate::Paginator`
     #
     # @param relation [ActiveRecord::Relation] Relation that will be paginated.
@@ -34,29 +36,91 @@ module ActiveRecordCursorPaginate
     #   ```sql
     #     CREATE INDEX <index_name> ON <table_name> (<order_fields>..., id)
     #   ```
+    # @param append_primary_key [Boolean] (true). Specifies whether the primary column(s)
+    #   should be implicitly appended to the list of sorting columns. It may be useful
+    #   to disable it for the table with a UUID primary key or when the sorting is done by a
+    #   combination of columns that are already unique.
+    # @param nullable_columns [Symbol, String, nil, Array] Columns which are nullable.
+    #   By default, all columns are considered as non-nullable, if not in this list.
+    #   It is not recommended to use this feature, because the complexity of produced SQL
+    #   queries can have a very negative impact on the database performance. It is better
+    #   to paginate using only non-nullable columns.
+    #
     # @raise [ArgumentError] If any parameter is not valid
     #
-    def initialize(relation, before: nil, after: nil, limit: nil, order: nil)
+    def initialize(relation, before: nil, after: nil, limit: nil, order: nil, append_primary_key: true, nullable_columns: nil)
       unless relation.is_a?(ActiveRecord::Relation)
         raise ArgumentError, "relation is not an ActiveRecord::Relation"
       end
 
-      if before.present? && after.present?
+      @relation = relation
+      @primary_key = @relation.primary_key
+      @append_primary_key = append_primary_key
+
+      @cursor = @current_cursor = nil
+      @is_forward_pagination = true
+      @before = @after = nil
+      @page_size = nil
+      @limit = nil
+      @columns = []
+      @directions = []
+      @order = nil
+
+      self.before = before
+      self.after = after
+      self.limit = limit
+      self.order = order
+      self.nullable_columns = nullable_columns
+    end
+
+    def before=(value)
+      if value.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?
+      @cursor = value || after
+      @current_cursor = @cursor
+      @is_forward_pagination = value.blank?
+      @before = value
+    end
 
+    def after=(value)
+      if before.present? && value.present?
+        raise ArgumentError, "Only one of :before and :after can be provided"
+      end
+
+      @cursor = before || value
+      @current_cursor = @cursor
+      @after = value
+    end
+
+    def limit=(value)
       config = ActiveRecordCursorPaginate.config
-      @page_size = limit || config.default_page_size
+      @page_size = value || config.default_page_size
       @page_size = [@page_size, config.max_page_size].min if config.max_page_size
+      @limit = value
+    end
 
-      order = normalize_order(order)
+    def order=(value)
+      order = normalize_order(value)
       @columns = order.keys
       @directions = order.values
+      @order = value
+    end
+
+    def nullable_columns=(value)
+      value = Array.wrap(value)
+      value = value.map { |column| column.is_a?(Symbol) ? column.to_s : column }
+
+      if (value - @columns).any?
+        raise ArgumentError, ":nullable_columns should include only column names from the :order option"
+      end
+
+      if value.include?(@columns.last)
+        raise ArgumentError, "Last order column can not be nullable"
+      end
+
+      @nullable_columns = value
     end
 
     # Get the paginated result.
@@ -65,32 +129,7 @@ module ActiveRecordCursorPaginate
     # @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 = build_cursor_relation(@current_cursor)
 
       relation = relation.limit(@page_size + 1)
       records_plus_one = relation.to_a
@@ -101,9 +140,9 @@ module ActiveRecordCursorPaginate
 
       if @is_forward_pagination
         has_next_page = has_additional
-        has_previous_page = @cursor.present?
+        has_previous_page = @current_cursor.present?
       else
-        has_next_page = @cursor.present?
+        has_next_page = @current_cursor.present?
         has_previous_page = has_additional
       end
 
@@ -111,7 +150,8 @@ module ActiveRecordCursorPaginate
         records,
         order_columns: cursor_column_names,
         has_next: has_next_page,
-        has_previous: has_previous_page
+        has_previous: has_previous_page,
+        nullable_columns: nullable_cursor_column_names
       )
 
       advance_by_page(page) unless page.empty?
@@ -134,6 +174,13 @@ module ActiveRecordCursorPaginate
       end
     end
 
+    # Total number of records to iterate by this paginator.
+    # @return [Integer]
+    #
+    def total_count
+      @total_count ||= build_cursor_relation(@cursor).count(:all)
+    end
+
     private
       def normalize_order(order)
         order ||= {}
@@ -153,24 +200,91 @@ module ActiveRecordCursorPaginate
 
         result = result.with_indifferent_access
         result.transform_values! { |direction| direction.downcase.to_sym }
-        Array(@primary_key).each { |column| result[column] ||= default_direction }
+
+        if @append_primary_key
+          Array(@primary_key).each { |column| result[column] ||= default_direction }
+        end
+
+        raise ArgumentError, ":order must contain columns to order by" if result.blank?
+
         result
       end
 
+      def build_cursor_relation(cursor)
+        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
+
+          relation =
+            if relation.select_values.empty?
+              relation.select(relation.arel_table[Arel.star], arel_columns)
+            else
+              relation.select(arel_columns)
+            end
+        end
+
+        pagination_directions = @directions.map { |direction| pagination_direction(direction) }
+        relation = relation.reorder(@columns.zip(pagination_directions).to_h)
+
+        if cursor
+          decoded_cursor = Cursor.decode(cursor_string: cursor, columns: cursor_column_names, nullable_columns: nullable_cursor_column_names)
+          relation = apply_cursor(relation, decoded_cursor)
+        end
+
+        relation
+      end
+
+      def nullable_cursor_column_names
+        @nullable_columns.map do |column|
+          cursor_column_names[@columns.index(column)]
+        end
+      end
+
+      def cursor_column_names
+        if @columns.any?(/\W/)
+          @columns.size.times.map { |i| "cursor_column_#{i + 1}" }
+        else
+          @columns
+        end
+      end
+
       def apply_cursor(relation, cursor)
-        operators = @directions.map { |direction| pagination_operator(direction) }
-        cursor_positions = cursor.columns.zip(cursor.values, operators)
+        cursor_positions = @columns.zip(cursor.values, @directions)
 
         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)
+
+        cursor_positions.reverse_each.with_index do |(column, value, direction), index|
+          previous_where_clause = where_clause
+
+          operator = pagination_operator(direction)
+          arel_column = arel_column(column)
+
+          # The last column can't be nil.
+          if index == 0
+            where_clause = arel_column.public_send(operator, value)
+          elsif value.nil?
+            if nulls_at_end?(direction)
+              # We are at the section with nulls, which is at the end ([x, x, null, null, null])
+              where_clause = arel_column.eq(nil).and(previous_where_clause)
             else
-              arel_column(column).public_send(operator, value).or(
-                arel_column(column).eq(value).and(where_clause)
-              )
+              # We are at the section with nulls, which is at the beginning ([null, null, null, x, x])
+              where_clause = arel_column.not_eq(nil)
+              where_clause = arel_column.eq(nil).and(previous_where_clause).or(where_clause)
+            end
+          else
+            where_clause = arel_column.public_send(operator, value).or(
+              arel_column.eq(value).and(previous_where_clause)
+            )
+
+            if nullable_column?(column) && nulls_at_end?(direction)
+              # Since column's value is not null, nulls can only be at the end.
+              where_clause = arel_column.eq(nil).or(where_clause)
             end
+          end
         end
 
         relation.where(where_clause)
@@ -203,12 +317,27 @@ module ActiveRecordCursorPaginate
       end
 
       def advance_by_page(page)
-        @cursor =
+        @current_cursor =
           if @is_forward_pagination
             page.next_cursor
           else
             page.previous_cursor
           end
       end
+
+      def nulls_at_end?(direction)
+        (direction == :asc && !small_nulls?) || (direction == :desc && small_nulls?)
+      end
+
+      def small_nulls?
+        # PostgreSQL considers NULLs larger than any value,
+        # opposite for SQLite and MySQL.
+        db_config = @relation.klass.connection_pool.db_config
+        db_config.adapter !~ /postg/ # postgres and postgis
+      end
+
+      def nullable_column?(column)
+        @nullable_columns.include?(column)
+      end
   end
 end

data/lib/activerecord_cursor_paginate/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: activerecord_cursor_paginate
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - fatkodima
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-03-08 00:00:00.000000000 Z
+date: 2025-01-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -41,13 +41,13 @@ files:
 - 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
+homepage: https://github.com/healthie/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
+  homepage_uri: https://github.com/healthie/activerecord_cursor_paginate
+  source_code_uri: https://github.com/healthie/activerecord_cursor_paginate
+  changelog_uri: https://github.com/healthie/activerecord_cursor_paginate/blob/master/CHANGELOG.md
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -63,7 +63,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.4
+rubygems_version: 3.4.19
 signing_key:
 specification_version: 4
 summary: Cursor-based pagination for ActiveRecord.