rotulus 0.2.3 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 15fae43a1fc07b2c268c1604c065a12f0d2288d733219aa563348019a872d7a0
-  data.tar.gz: ca8548477eee36f6bed018d8ec20d5dd5217f74d36954f13b4e243fbaee6755e
+  metadata.gz: dabab916c4cd609c84cf4dea85172a337df2501f846d3747e072ddc4c2ea5995
+  data.tar.gz: acd18440bd31048eec4cc7aa7afefb4609265a6bbe6002d6e3bea65ebc331eec
 SHA512:
-  metadata.gz: f9d0e4611e800688f8c10ad7347043a07e7358f79a4254ecac6359a1f5f4101d323cfe0b21d45b363984cdc681e3ffc8b8b9587311e96553ab952eb76016792b
-  data.tar.gz: a3240e33d45cd4360c4235e94860558c584a9f1f373c9ad7451ad9d819c2616f5a2e2146bef0449b716b846144ee87c19e92596c2b39c13e34bef254f49c50af
+  metadata.gz: c951e3a06482187d8d340d1f66f67b71b8aadf955a48fa4f190fb1edeb921615c7ec47977faf57019c645ca27c3eb66dc31e9b5b4e57aac61323e0a356fdc875
+  data.tar.gz: fc5ba3d91f64aff2aa0a9594beffe646c99955ef369f590de1f538cc31e31ef6903a3321f4e7adaa1ad62f3e47db3c8a6e7450f97a7a5209d2784d5286ad5f3b

data/CHANGELOG.md

@@ -8,4 +8,7 @@
 - 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
+- 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

data/lib/rotulus/version.rb

@@ -1,3 +1,3 @@
 module Rotulus
-  VERSION = '0.2.3'
+  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.3
+  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