activerecord_cursor_paginate 0.1.0 → 0.2.0

checksums.yaml

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

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 ## master (unreleased)
 
+## 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

@@ -48,11 +48,11 @@ 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.cursors            # => ["MQ", "Mg", ..., "MTA"]
+                               |                 |
+                               |                 |
+page.previous_cursor    # =>  "MQ"               |
+page.next_cursor        # =>  "MTA" -------------|
 page.has_previous? # => false
 page.has_next? # => true
 ```
@@ -63,24 +63,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 +115,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 +157,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 +223,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 +245,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 +255,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 +267,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 +287,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 +309,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 +331,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 +344,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
 ```
 

data/lib/activerecord_cursor_paginate/cursor.rb

@@ -8,13 +8,12 @@ module ActiveRecordCursorPaginate
   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))
+        decoded = JSON.parse(Base64.urlsafe_decode64(cursor_string))
 
         if (columns.size == 1 && decoded.is_a?(Array)) ||
            (decoded.is_a?(Array) && decoded.size != columns.size)
@@ -48,8 +47,8 @@ module ActiveRecordCursorPaginate
     attr_reader :columns, :values
 
     def initialize(columns:, values:)
-      @columns = Array(columns)
-      @values = Array(values)
+      @columns = Array.wrap(columns)
+      @values = Array.wrap(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
@@ -64,7 +63,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,15 @@ 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)
+    def cursor_paginate(after: nil, before: nil, limit: nil, order: nil, append_primary_key: true)
       relation = (is_a?(ActiveRecord::Relation) ? self : all)
-      Paginator.new(relation, after: after, before: before, limit: limit, order: order)
+      Paginator.new(relation, after: after, before: before, limit: limit, order: order, append_primary_key: append_primary_key)
     end
     alias cursor_pagination cursor_paginate
   end

data/lib/activerecord_cursor_paginate/page.rb

@@ -78,8 +78,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)
+          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|
@@ -34,9 +34,13 @@ 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.
     # @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)
       unless relation.is_a?(ActiveRecord::Relation)
         raise ArgumentError, "relation is not an ActiveRecord::Relation"
       end
@@ -54,6 +58,7 @@ module ActiveRecordCursorPaginate
       @page_size = limit || config.default_page_size
       @page_size = [@page_size, config.max_page_size].min if config.max_page_size
 
+      @append_primary_key = append_primary_key
       order = normalize_order(order)
       @columns = order.keys
       @directions = order.values
@@ -72,11 +77,11 @@ module ActiveRecordCursorPaginate
         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}" }
+        cursor_column_names = arel_columns.map { |column| column.right.to_s }
 
         relation =
           if relation.select_values.empty?
-            relation.select(Arel.star, arel_columns)
+            relation.select(relation.arel_table[Arel.star], arel_columns)
           else
             relation.select(arel_columns)
           end
@@ -153,7 +158,13 @@ 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
 

data/lib/activerecord_cursor_paginate/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActiveRecordCursorPaginate
-  VERSION = "0.1.0"
+  VERSION = "0.2.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.2.0
 platform: ruby
 authors:
 - fatkodima
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-03-08 00:00:00.000000000 Z
+date: 2024-05-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -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.