rotulus 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 07fe3f3acca52daa7170d766b516bbb39b8ad133abee1a60d635ea0c1c3521c3
-  data.tar.gz: b31d8781affc551740fe13878e8f269e73802c1b111bf5c29d94a4629850a9e7
+  metadata.gz: 7504d29a1bd4aac2f21ffb981abd98b544b8b50f80fa7f875cc73286e967e9a2
+  data.tar.gz: afbd5665291c310b0fd03e87cebd0b100da71dcfdedae7953b4844c767859ce3
 SHA512:
-  metadata.gz: 0dc571a3bcde992068a7739c3ec482b44b5af9cbe269d33266177e30ae9c89219df5caea3b34cbe371880349148979fc6e322c23fbed01730e9ce1f391c532d0
-  data.tar.gz: 0a1fe9c87952093123df6687b9a7bb73c1f372b8d380d9d2d79be6fee2012fed0eb10f58f012242ce6a7c0e1947c76e6abfc4900fa47a021ddf3ecc579c39c7a
+  metadata.gz: 19d4f2b1e1a734c78b8d63954ef66ba443591a7fc2c04364eccc6e1a0780b4f3e6346af327e53f3ba773bafca9a39b3abd5ef7efc8937b71a8fc534d7d16dc84
+  data.tar.gz: 0a739f5977b51127934658605a304f78a6be0ffe8d4e3e0ddce8fe4abc1223e6bf0c7ef1dfd39afd6b675f7006b9b3f4074fd11cf5329d9433886dd06dc18bd8

data/README.md

@@ -8,9 +8,10 @@ Cursor-based pagination is an alternative to OFFSET-based pagination that provid
 
 Some advantages of this approach are:
 
-* Reduces inaccuracies such as duplicate/skipped records due to records being actively manipulated in the DB.
+* Reduces inaccuracies such as duplicate or skipped records as records are being manipulated.
 * Can significantly improve performance(with proper DB indexing on ordered columns) especially as you move forward on large datasets. 
 
+
 **TL;DR** See [ sample usage for Rails here ](#rails-usage). 
 
 ## Features
@@ -98,7 +99,7 @@ page = Rotulus::Page.new(users)
 
 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.
+The gem will automatically add the table's PK(`users.id`) in the `ORDER BY` as the tie-breaker column to ensure stable sorting and pagination.
 
 
 #### Access the page records
@@ -204,7 +205,7 @@ puts page.as_table
 
 ### Advanced Usage
 #### Expanded order definition
-Instead of just specifying the column sorting such as ```{ first_name: :asc }``` in the :order param, one can use the expanded order config in `Hash` format for more sorting options: 
+Instead of just specifying the column sorting such as ```{ first_name: :asc }``` in the :order param, one can use the expanded order config in `Hash` format for more sorting options that would help the library to generate the optimal query: 
 
 | Column Configuration | Description |
 | ----------- | ----------- |
@@ -339,14 +340,14 @@ private
 
 # Allow clients to sort by first_name, last_name, and/or email.
 # example sort values:
-# a. params[:sort] = +users.last_name,-users.email
+# a. params[:sort] = +last_name,-email
 # b. params[:sort] = -first_name
 def index_order
   SortParam.define do
-    field 'users.first_name'
-    field 'users.last_name', nulls: :last, nullable: true
-    field 'users.email', distinct: true
-  end.load!(params[:sort].presence || '+users.first_name')
+    field 'first_name'
+    field 'last_name', nulls: :last, nullable: true
+    field 'email', distinct: true
+  end.load!(params[:sort].presence || 'first_name')
 end
 ```
 
@@ -360,19 +361,19 @@ end
 | `Rotulus::CursorError` | Generic error for cursor related validations |
 | `Rotulus::InvalidColumn` | Column provided in the :order param can't be found. |
 | `Rotulus::MissingTiebreaker` | There is no non-nullable and distinct column in the configured order definition. |
-| `Rotulus::ConfigurationError` | Generic error for missing/invalid configurations. |
-| `Rotulus::OrderChanged` | Error raised paginating with a token(i.e. calling `Page#at` or `Page#at!`) that was generated from a previous page instance with a different `:order` definition. Can be enabled by setting the `restrict_order_change` to true. |
-| `Rotulus::QueryChanged` | Error raised paginating with a token(i.e. calling `Page#at` or `Page#at!`) that was generated from a previous page instance with a different `:ar_relation` filter/query. Can be enabled by setting the `restrict_query_change` to true. |
+| `Rotulus::ConfigurationError` | Generic error for missing/invalid configuration. |
+| `Rotulus::OrderChanged` | Raised when passing a token to `Page#at` or `Page#at!` methods of a page instance, and the token was generated from a page instance with a different `:order` definition. Can be enabled by setting the `restrict_order_change` to true. |
+| `Rotulus::QueryChanged` | Raised when passing a token to `Page#at` or `Page#at!` methods of a page instance, and the token was generated from a page instance with a different `:ar_relation` filter/query. Can be enabled by setting the `restrict_query_change` to true. |
 
 ## How it works
-Cursor-based pagination uses a reference point/record to fetch the previous or next set of records. This gem takes care of the SQL query and cursor generation needed for the pagination. To ensure that the pagination results are stable, it requires that:
+Cursor-based pagination uses a reference record to fetch the relative set of previous or next records. This gem takes care of the SQL query and cursor generation needed for the pagination. To ensure that the pagination results are stable, it requires that:
 
-* Records are sorted (`ORDER BY`).
+* Records are sorted (`ORDER BY`) by columns.
 * In case multiple records with the same column value(s) exists in the result, a unique non-nullable column is needed as tie-breaker. Usually, the table PK suffices for this but for complex queries(e.g. with table joins and with nullable columns, etc.), combining and using multiple columns that would uniquely identify the row in the result is needed.
 * Columns used in `ORDER BY` would need to be indexed as they will be used in filtering.
 
 
-#### Sample SQL-generated snippets
+#### Sample SQL-generated snippets to fetch the next set of records
 
 ##### Example 1: With order by `id` only
 ###### Ruby
@@ -459,10 +460,10 @@ WHERE users.first_name >= 'Jane' AND (
 ```
 
 #### Custom Token Format
-By default, the cursor is encoded as a Base64 token. To customize how the cursor is encoded and decoded, you may just create a subclass of `Rotulus::Cursor` with `.decode` and `.encode` methods implemented.
+By default, the cursor is encoded as a Base64 token. To customize how the cursor is encoded and decoded, you may just need to subclass `Rotulus::Cursor` with the `.decode` and `.encode` methods implemented.
 
 ##### Example:
-The implementation below would generate tokens in UUID format where the actual cursor data is stored in memory:
+The implementation below would generate tokens in UUID format where the actual cursor data is stored in memory(in production, you would use a distributed data store such as Redis):
 
 ```ruby
 class MyCustomCursor < Rotulus::Cursor
@@ -526,7 +527,7 @@ end
   | Environment Variable | Values | Example |
   | ----------- | ----------- |----------- |
   | `DB_ADAPTER` | **Default: :sqlite**. `sqlite`,`mysql2`, or `postgresql` | ```DB_ADAPTER=postgresql bundle exec rspec```<br/><br/> ```DB_ADAPTER=postgresql ./bin/console``` |
-  | `RAILS_VERSION` | **Default: 7-0** <br/><br/> `4-2`,`5-0`,`5-1`,`5-2`,`6-0`,`6-1`,`7-0` |```RAILS_VERSION=5-2 ./bin/setup```<br/><br/>```RAILS_VERSION=5-2 bundle exec rspec```<br/><br/> ```RAILS_VERSION=5-2 ./bin/console```|
+  | `RAILS_VERSION` | **Default: 7-1** <br/><br/> `4-2`,`5-0`,`5-1`,`5-2`,`6-0`,`6-1`,`7-0`, `7-1` |```RAILS_VERSION=5-2 ./bin/setup```<br/><br/>```RAILS_VERSION=5-2 bundle exec rspec```<br/><br/> ```RAILS_VERSION=5-2 ./bin/console```|
 
 
 <br/><br/>

data/lib/rotulus/version.rb

@@ -1,3 +1,3 @@
 module Rotulus
-  VERSION = '2.0.0'.freeze
+  VERSION = '2.1.0'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rotulus
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Uy Jayson B
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-06-10 00:00:00.000000000 Z
+date: 2024-05-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -19,7 +19,7 @@ dependencies:
         version: '4.2'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '7.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -29,7 +29,7 @@ dependencies:
         version: '4.2'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '7.2'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
@@ -39,7 +39,7 @@ dependencies:
         version: '4.2'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '7.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -49,7 +49,7 @@ dependencies:
         version: '4.2'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '7.2'
 - !ruby/object:Gem::Dependency
   name: multi_json
   requirement: !ruby/object:Gem::Requirement