rotulus 0.2.2 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c74625ece0961a25549797386fa66abb146564211b4dc1640abd92ac4c0e2a0
-  data.tar.gz: 567562c553bbe914cdf5740e4262bd76b59ef04493658a68c69bd420e3109283
+  metadata.gz: dabab916c4cd609c84cf4dea85172a337df2501f846d3747e072ddc4c2ea5995
+  data.tar.gz: acd18440bd31048eec4cc7aa7afefb4609265a6bbe6002d6e3bea65ebc331eec
 SHA512:
-  metadata.gz: 9e1380f553f3a0756b36b21f2a6193ee7031fe29bc8b3478ec349f6c35d2b9292ed5afd295b6b5250b2dc4498e1d86b66d13d639ea5e3d36db78fc8868fb4e9f
-  data.tar.gz: 625359b428c792c30a2a2ee2b6b702a2c7270e495111c284c82a1d1433eddf5d0ac485d6d5ae961128006f161c4cb01b8fa76f7ab3bd14d63cb761306a9392f6
+  metadata.gz: c951e3a06482187d8d340d1f66f67b71b8aadf955a48fa4f190fb1edeb921615c7ec47977faf57019c645ca27c3eb66dc31e9b5b4e57aac61323e0a356fdc875
+  data.tar.gz: fc5ba3d91f64aff2aa0a9594beffe646c99955ef369f590de1f538cc31e31ef6903a3321f4e7adaa1ad62f3e47db3c8a6e7450f97a7a5209d2784d5286ad5f3b

data/CHANGELOG.md

@@ -5,4 +5,10 @@
 - Drop unnecessary ORDER BY columns following a non-nullable and distinct column.
 
 ## 0.2.2
-- Raise error when there is no non-nullable and distinct column in the configured order definition.
+- Raise error when there is no non-nullable and distinct column in the configured order definition.
+
+## 0.2.3
+- Replace any existing order defined on the given ar_relation
+
+## 0.2.4
+- Allow changing limit param

data/README.md

@@ -19,7 +19,7 @@ Some advantages of this approach are:
 * `NULLS FIRST`/`NULLS LAST` handling
 * Allows custom cursor format
 * Built-in cursor token expiration
-* Built-in cursor integrity check
+* Built-in cursor integrity checking
 * Supports **MySQL**, **PostgreSQL**, and **SQLite**
 * Supports **Rails 4.2** and above
 
@@ -45,8 +45,7 @@ gem install rotulus
 ```
 
 ## Configuration
-At the very least you only need to set the environment variable `ROTULUS_SECRET` to a random string(e.g. generate via `rails secret`).
-For more configuration options:
+Setting the environment variable `ROTULUS_SECRET` to a random string value(e.g. generate via `rails secret`) is the minimum required setup needed. But for more configuration options:
 
 #### Create an initializer `config/initializers/rotulus.rb`:
 
@@ -79,20 +78,19 @@ end
 ```ruby
 users = User.where('age > ?', 16)
 
-page = Rotulus::Page.new(users, order: { first_name: :asc, last_name: :desc }, limit: 3)
+page = Rotulus::Page.new(users, order: { id: :asc })
+# OR just
+page = Rotulus::Page.new(users)
 ```
-Example above will automatically add the table's PK(`users.id`) in the generated SQL query as tie-breaker if the PK isn't included in the `:order` column config yet.
-
 
-###### Example with `ORDER BY users.id asc` only:
+###### Example when sorting with multiple columns and `:limit`:
 
 ```ruby
-page = Rotulus::Page.new(users, order: { id: :asc } limit: 3)
-
-# OR
 
-page = Rotulus::Page.new(users, limit: 3)
+page = Rotulus::Page.new(users, order: { first_name: :asc, last_name: :desc }, limit: 3)
 ```
+With the example above, the gem will automatically add the table's PK(`users.id`) in the generated SQL query as the tie-breaker column to ensure stable sorting and pagination.
+
 
 #### Access the page records
 
@@ -295,7 +293,7 @@ page = Rotulus::Page.new(items, order: order_by, limit: 2)
 
 | Class | Description |
 | ----------- | ----------- |
-| `Rotulus::InvalidCursor` | Cursor token received is invalid e.g., unrecognized token, token data has been tampered/updated, base ActiveRecord relation filter/sorting/limit is no longer consistent to the token. |
+| `Rotulus::InvalidCursor` | Cursor token received is invalid e.g., unrecognized token, token data has been tampered/updated, base ActiveRecord relation filter/sorting is no longer consistent to the token. |
 | `Rotulus::Expired` | Cursor token received has expired based on the configured `token_expires_in` |
 | `Rotulus::InvalidLimit` | Limit set to Rotulus::Page is not valid. e.g., exceeds the configured limit. see `config.page_max_limit` |
 | `Rotulus::CursorError` | Generic error for cursor related validations |
@@ -380,8 +378,8 @@ To navigate between pages, a cursor is used. The cursor token is a Base64 encode
 ```
 1. `f` - contains the record values from the last record of the current page. Only the columns included in the `ORDER BY` are included. Note also that the unique column `users.id` is included as a tie-breaker.
 2. `d` - the pagination direction. `next` or `prev` set of records from the reference values in "f".
-3. `s` - the cursor state needed for integrity check so we can detect whether the base ActiveRecord relation filter/sorting is no longer consistent(e.g. API request params changed) with the cursor token. Additionally, to restrict clients/third-parties from generating their own (unsafe)tokens or to tamper the data of an existing token. The gem requires a secret key configured for this through the `ROTULUS_SECRET` environment variable or the `config.secret` configuration. see [Configuration](#configuration) section.
-4. `c` -  the time when this cursor was generated.
+3. `s` - the cursor state needed for integrity checking so we can detect whether the base ActiveRecord relation filter(initial `WHERE` conditions) are no longer consistent with the cursor (e.g., API parameters have changed). Additionally, to restrict clients/third-parties from generating their own (unsafe)tokens or from tampering the data of an existing token. The gem requires a secret key configured for this through the `ROTULUS_SECRET` environment variable or the `config.secret` configuration. see [Configuration](#configuration) section.
+4. `c` -  cursor token issuance time.
 
 A condition generated from the cursor above would look like:
 

data/lib/rotulus/cursor.rb

@@ -10,7 +10,7 @@ module Rotulus
       #  @return [Cursor] Cursor
       #
       #  @raise [InvalidCursor] if the cursor is no longer consistent to the page's ActiveRecord
-      #    relation filters, sorting, limit, or if the encoded cursor data was tampered.
+      #    relation filters, sorting, or if the encoded cursor data was tampered.
       def for_page_and_token!(page, token)
         data = decode(token)
         reference_record = Record.new(page, data[:f])
@@ -21,7 +21,7 @@ module Rotulus
         cursor = new(reference_record, direction, created_at: created_at)
 
         if cursor.state != state
-          raise InvalidCursor.new('Invalid cursor possibly due to filter, order, or limit changed')
+          raise InvalidCursor.new('Invalid cursor possibly due to filter or sorting changed')
         end
 
         cursor
@@ -99,7 +99,7 @@ module Rotulus
     alias to_s to_token
 
     # Generate a 'state' string so we can detect whether the cursor data is no longer consistent to
-    # the AR filter, limit, or order definition. This also provides a mechanism to detect if
+    # the AR filter or order definition. This also provides a mechanism to detect if
     # any token data was tampered.
     #
     # @return [String] the hashed state

data/lib/rotulus/page.rb

@@ -176,12 +176,12 @@ module Rotulus
       }.delete_if { |_, token| token.nil? }
     end
 
-    # Return Hashed value of this page's state so we can check whether the ar_relation's filter,
-    # order definition, and limit are still consistent to the cursor. see Cursor.state_valid?.
+    # Return Hashed value of this page's state so we can check whether the ar_relation's filter and
+    # order definition are still consistent to the cursor. see Cursor.state_valid?.
     #
     # @return [String] the hashed state
     def state
-      Digest::MD5.hexdigest("#{ar_relation.to_sql}~#{order.state}~#{limit}")
+      Digest::MD5.hexdigest("#{ar_relation.to_sql}~#{order.state}")
     end
 
     # Returns a string showing the page's records in table form with the ordered columns
@@ -209,7 +209,7 @@ module Rotulus
       return @loaded_records unless @loaded_records.nil?
 
       @loaded_records = ar_relation.where(cursor&.sql)
-                                   .order(order_by_sql)
+                                   .reorder(order_by_sql)
                                    .limit(limit + 1)
                                    .select(*select_columns)
       return @loaded_records.to_a unless paged_back?

data/lib/rotulus/version.rb

@@ -1,3 +1,3 @@
 module Rotulus
-  VERSION = '0.2.2'
+  VERSION = '0.2.4'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rotulus
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.2.4
 platform: ruby
 authors:
 - Uy Jayson B
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-05-23 00:00:00.000000000 Z
+date: 2023-05-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -64,8 +64,8 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Cursor-based pagination for apps built on Rails/ActiveRecord with sort
-  by multiple columns support for a more stable and predictable pagination.
+description: Cursor-based pagination for Rails/ActiveRecord apps with multiple column
+  sort and custom cursor format support for a more stable and predictable pagination.
 email:
 - uy.json.dev@gmail.com
 executables: []
@@ -116,6 +116,6 @@ requirements: []
 rubygems_version: 3.1.4
 signing_key:
 specification_version: 4
-summary: Cursor-based pagination for apps built on Rails/ActiveRecord with sort by
-  multiple columns support.
+summary: Cursor-based Rails/ActiveRecord pagination with multiple column sort and
+  custom cursor token format support.
 test_files: []