rotulus 0.2.4 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dabab916c4cd609c84cf4dea85172a337df2501f846d3747e072ddc4c2ea5995
-  data.tar.gz: acd18440bd31048eec4cc7aa7afefb4609265a6bbe6002d6e3bea65ebc331eec
+  metadata.gz: 07fe3f3acca52daa7170d766b516bbb39b8ad133abee1a60d635ea0c1c3521c3
+  data.tar.gz: b31d8781affc551740fe13878e8f269e73802c1b111bf5c29d94a4629850a9e7
 SHA512:
-  metadata.gz: c951e3a06482187d8d340d1f66f67b71b8aadf955a48fa4f190fb1edeb921615c7ec47977faf57019c645ca27c3eb66dc31e9b5b4e57aac61323e0a356fdc875
-  data.tar.gz: fc5ba3d91f64aff2aa0a9594beffe646c99955ef369f590de1f538cc31e31ef6903a3321f4e7adaa1ad62f3e47db3c8a6e7450f97a7a5209d2784d5286ad5f3b
+  metadata.gz: 0dc571a3bcde992068a7739c3ec482b44b5af9cbe269d33266177e30ae9c89219df5caea3b34cbe371880349148979fc6e322c23fbed01730e9ce1f391c532d0
+  data.tar.gz: 0a1fe9c87952093123df6687b9a7bb73c1f372b8d380d9d2d79be6fee2012fed0eb10f58f012242ce6a7c0e1947c76e6abfc4900fa47a021ddf3ecc579c39c7a

data/CHANGELOG.md

@@ -11,4 +11,11 @@
 - Replace any existing order defined on the given ar_relation
 
 ## 0.2.4
-- Allow changing limit param
+- Allow changing limit param.
+
+## 1.0.0
+- Allow changing of ar_relation and order by default.
+- Make error class names consistent.
+
+## 2.0.0
+- Use multi_json instead of locking clients into using Oj gem.

data/README.md

@@ -1,21 +1,22 @@
 # Rotulus
 
-[![Gem Version](https://badge.fury.io/rb/rotulus.svg)](https://badge.fury.io/rb/rotulus) [![CI](https://github.com/jsonb-uy/rotulus/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/jsonb-uy/rotulus/actions/workflows/ci.yml) [![codecov](https://codecov.io/gh/jsonb-uy/rotulus/branch/main/graph/badge.svg?token=OKGOWP4SH9)](https://codecov.io/gh/jsonb-uy/rotulus)
+[![Gem Version](https://badge.fury.io/rb/rotulus.svg)](https://badge.fury.io/rb/rotulus) [![CI](https://github.com/jsonb-uy/rotulus/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/jsonb-uy/rotulus/actions/workflows/ci.yml) [![codecov](https://codecov.io/gh/jsonb-uy/rotulus/branch/main/graph/badge.svg?token=OKGOWP4SH9)](https://codecov.io/gh/jsonb-uy/rotulus) [![Maintainability](https://api.codeclimate.com/v1/badges/1df84f690220d9e5d260/maintainability)](https://codeclimate.com/github/jsonb-uy/rotulus/maintainability)
 
 ### Cursor-based pagination for apps built on Rails/ActiveRecord 
 
-Cursor-based pagination is an alternative to OFFSET-based pagination that provides a more stable and predictable pagination behavior as records are being added, updated, and removed in the database through the use of an encoded cursor token.
+Cursor-based pagination is an alternative to OFFSET-based pagination that provides a more stable and predictable pagination behavior as records are added, updated, and removed in the database through the use of an encoded cursor token.
 
 Some advantages of this approach are:
 
 * Reduces inaccuracies such as duplicate/skipped records due to records being actively manipulated in the DB.
 * 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
 
-* Sort records by multiple/any number of columns
-* Sort records using columns from joined tables
+* Paginate records sorted by any number of columns
+* Paginate records sorted by columns from joined tables
 * `NULLS FIRST`/`NULLS LAST` handling
 * Allows custom cursor format
 * Built-in cursor token expiration
@@ -45,28 +46,36 @@ gem install rotulus
 ```
 
 ## Configuration
-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:
+Setting the environment variable `ROTULUS_SECRET` to a random string value(e.g. generate via `rails secret`) is the minimum required setup needed. 
 
+<details>
+  <summary>More configuration options</summary>
+  
 #### Create an initializer `config/initializers/rotulus.rb`:
 
-```ruby
-Rotulus.configure do |config|
-  config.page_default_limit = 5
-  config.page_max_limit = 50
-  config.secret = ENV["MY_ENV_VAR"]
-  config.token_expires_in = 10800
-  config.cursor_class = MyCursor
-end
-```
+  ```ruby
+  Rotulus.configure do |config|
+    config.page_default_limit = 5
+    config.page_max_limit = 50
+    config.secret = ENV["MY_ENV_VAR"]
+    config.token_expires_in = 10800
+    config.cursor_class = MyCursor
+    config.restrict_order_change = false
+    config.restrict_query_change = false
+  end
+  ```
 
 | Configuration | Description |
 | ----------- | ----------- |
 | `page_default_limit` | **Default: 5** <br/> Default record limit per page in case the `:limit` is not given when initializing a page `Rotulus::Page.new(...)` |
 | `page_max_limit` | **Default: 50** <br/> Maximum `:limit` value allowed when initializing a page.|
-| `secret` | **Default: ENV['ROTULUS_SECRET']** <br/> Key needed to generate the cursor state. |
+| `secret` | **Default: ENV['ROTULUS_SECRET']** <br/> Key needed to generate the cursor state needed for cursor integrity checking. |
 | `token_expires_in` | **Default: 259200**(3 days) <br/> Validity period of a cursor token (in seconds). Set to `nil` to disable token expiration. |
+| `restrict_order_change` | **Default: false** <br/> When `true`, raise an `OrderChanged` error when paginating with a token that was generated from a page instance with a different `:order`. <br/> When `false`, no error is raised and pagination is based on the new `:order` definition. |
+| `restrict_query_change` | **Default: false** <br/> When `true`, raise a `QueryChanged` error when paginating with a token that was generated from a page instance with a different `:ar_relation` filter/query. <br/> When `false`, no error is raised and pagination will query based on the new `:ar_relation`. |
 | `cursor_class` | **Default: Rotulus::Cursor** <br/> Cursor class responsible for encoding/decoding cursor data. Default uses Base64 encoding. see [Custom Token Format](#custom-token-format). |
-<br/>
+  <br/>
+</details>
 
 
 ## Usage
@@ -124,7 +133,7 @@ In case there is no next page, `nil` is returned
 page.prev_token
 => "eyI6ZiI6eyJebyI6..."
 ```
-In case there is no previous page(i.e. currently in first page), `nil` is returned
+In case there is no previous page(i.e., first page), `nil` is returned
 
 
 #### Navigate to the page given a cursor
@@ -168,6 +177,14 @@ page.reload
 page.reload.records
 ```
 
+#### Cursor tokens hash
+```ruby
+page.links
+
+=> { previous: "eyI6ZiI6efQ...", next: "eyI6ZiI6eyJ...."}
+```
+If the token is `nil`, the corresponding key(previous/next) isn't included in the hash.
+
 #### Print page in table format for debugging
 Currently, only the columns included in `ORDER BY` are shown:
 
@@ -192,10 +209,10 @@ Instead of just specifying the column sorting such as ```{ first_name: :asc }```
 | Column Configuration | Description |
 | ----------- | ----------- |
 | `direction` | **Default: :asc**. `:asc` or `:desc` |
-| `nullable`  | **Default: true** if column is defined as nullable in its table, _false_ otherwise. <br/><br />Whether a null value is expected for this column in the result set. <br /><br/>**Note:** <br/>- Not setting this to _true_ when there are possible rows with NULL values for the specific column in the DB won't return those records. <br/> - In queries with table (outer)`JOIN`s, a column in the result could have a NULL value even if the column doesn't allow nulls in its table. So set `nullable` to _true_ for such cases.
+| `nullable`  | **Default: true** if the column is defined as nullable in its table, _false_ otherwise. <br/><br />Whether a null value is expected for this column in the result set. <br /><br/>**Note:** <br/>- Not setting this to _true_ when there are possible rows with NULL values for the specific column in the DB won't return those records. <br/> - In queries with table (outer)`JOIN`s, a column in the result could have a NULL value even if the column doesn't allow nulls in its table. So set `nullable` to _true_ for such cases.
 | `nulls` | **Default:**<br/>- MySQL and SQLite: `:first` if `direction` is `:asc`, otherwise `:last`<br/>- PostgreSQL:  `:last` if `direction` is `:asc`, otherwise `:first`<br/><br/>Tells whether rows with NULL column values comes before/after the records with non-null values. Applicable only if column is `nullable`. |
 | `distinct` | **Default: true** if the column is the primary key of its table, _false_ otherwise.<br/><br /> Tells whether rows in the result are expected to have unique values for this column. <br/><br />**Note:**<br/>- In queries with table `JOIN`s, multiple rows could have the same column value even if the column has a unique index in its table. So set `distinct` to false for such cases.  |
-| `model` | **Default:**<br/> - the model of the base AR relation passed to `Rotulus::Page.new(<ar_relation>)` if column name has no prefix(e.g. `first_name`) and the AR relation model has a column matching the column name.<br/>- the model of the base AR relation passed to `Rotulus::Page.new(<ar_relation>)` if column name has a prefix(e.g. `users.first_name`) and thre prefix matches the AR relation's table name and the table has a column matching the column name. <br/><br/>Model where this column belongs. This allows the gem to infer the nullability and uniqueness from the column definition in its table instead of manually setting the `nullable` or `distinct` options and to also automatically prefix the column name with the table name. <br/>|
+| `model` | **Default:**<br/> - the model of the base AR relation passed to `Rotulus::Page.new(<ar_relation>)` if column name has no prefix(e.g. `first_name`) and the AR relation model has a column matching the column name.<br/>- the model of the base AR relation passed to `Rotulus::Page.new(<ar_relation>)` if column name has a prefix(e.g. `users.first_name`) and the prefix matches the AR relation's table name and the table has a column matching the column name. <br/><br/>Model where this column belongs. This allows the gem to infer the nullability and uniqueness from the column definition in its table instead of manually setting the `nullable` or `distinct` options and to also automatically prefix the column name with the table name. <br/>|
 
 
 ##### Example:
@@ -258,7 +275,7 @@ page = Rotulus::Page.new(items, order: order_by, limit: 2)
 ```
 
 Some notes for the example above: <br/>
-1. `oi.id` is needed to uniquely identify and serve as the tie-breaker for `Item`s that have `OrderItem`s having the same item_count and name.  The combination of `oi.item_count`, `items.name`, and `oi.id` makes those record unique in the dataset. <br/>
+1. `oi.id` is needed to uniquely identify and serve as the tie-breaker for `Item`s that have `OrderItem`s having the same item_count and name.  The combination of `oi.item_count`, `items.name`, and `oi.id` makes those records unique in the dataset. <br/>
 2. `id` is translated to `items.id` and is needed to uniquely identify and serve as the tie-breaker for `Item`s that have NO `OrderItem`s. The combination of `oi.item_count`(NULL), `items.name`, `oi.id`(NULL), and `items.id` makes those record unique in the dataset. Although, this can be removed in the configuration above as the `Item` table's primary key will be automatically added as the last `ORDER BY` column if it isn't included yet.<br/>
 3. Explicitly setting the `model: OrderItem` in joined table columns is required for now.  
 
@@ -287,19 +304,65 @@ page = Rotulus::Page.new(items, order: order_by, limit: 2)
 
 ```
 
-<br/>
+### Rails Usage
+
+##### Controller example 1:
+
+```ruby
+def index
+  page = Rotulus::Page.new(User.all, order: index_order, limit: params.dig(:page, :limit))
+                      .at!(params[:cursor]) 
+  render json: { data: page.records }.merge!(page.links)      # `page.links` contain the `cursor` value for next/prev pages.               
+end
+
+private
+
+def index_order
+  { first_name: :asc, 
+    last_name: { direction: :desc, nulls: :last },
+    email: { direction: :asc, distinct: true } }
+end
+```
+
+APIs usually allow clients to specify which columns to sort through a parameter. You may use the [sort_param](https://rubygems.org/gems/sort_param) gem to support this:
+
+##### Controller example 2:
+
+```ruby
+def index
+  page = Rotulus::Page.new(User.all, order: index_order, limit: params.dig(:page, :limit))
+                      .at!(params[:cursor])
+  render json: { data: page.records }.merge!(page.links)                     
+end
+
+private
+
+# Allow clients to sort by first_name, last_name, and/or email.
+# example sort values:
+# a. params[:sort] = +users.last_name,-users.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')
+end
+```
 
 ### Errors
 
 | Class | Description |
 | ----------- | ----------- |
-| `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::InvalidCursor` | Cursor token received is invalid e.g., unrecognized token, token data has been tampered/updated. |
 | `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 |
-| `Rotulus::InvalidColumnError` | Column provided in the :order param can't be found. |
-| `Rotulus::MissingTiebreakerError` | There is no non-nullable and distinct column in the configured order definition. |
+| `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. |
 
 ## 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:
@@ -309,7 +372,7 @@ Cursor-based pagination uses a reference point/record to fetch the previous or n
 * 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
 
 ##### Example 1: With order by `id` only
 ###### Ruby
@@ -370,18 +433,22 @@ To navigate between pages, a cursor is used. The cursor token is a Base64 encode
 
 ```json
 {
-  "f": {"users.first_name": "Jane", "users.id": 2}, 
+  "f": { "users.first_name": "Jane", "users.id": 2 }, 
   "d": "next",
-  "s": "251177d65873aa37057dba548ecba82f", 
-  "c": 1672502400
+  "c": 1672502400,
+  "cs": "fe6ac1a1d6a1fc1b7f842b388639f63b",
+  "os": "62186497a8073f9c7072389b73c6c60c",
+  "qs": "7a5053198709df924dd5ec1752ee4e6b"
 }
 ```
 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 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.
+3. `cs` - the cursor state needed for integrity checking, restricting clients/third-parties from generating their own (unsafe)tokens, or from tampering with the data of an existing token. 
+4. `os` - the order state needed to detect whether the order definition changed.
+5. `qs` - the base AR relation state needed to detect whether the ar_relation has changed (e.g. filter/query changed due to API params). 
 4. `c` -  cursor token issuance time.
 
-A condition generated from the cursor above would look like:
+A condition generated from the cursor above would look like this:
 
 ```sql
 WHERE users.first_name >= 'Jane' AND (
@@ -459,7 +526,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-stable** <br/><br/> `4-2-stable`,`5-0-stable`,`5-1-stable`,<br/>`5-2-stable`,`6-0-stable`,`6-1-stable`,<br/>`7-0-stable` |```RAILS_VERSION=5-2-stable ./bin/setup```<br/><br/>```RAILS_VERSION=5-2-stable  bundle exec rspec```<br/><br/> ```RAILS_VERSION=5-2-stable ./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```|
 
 
 <br/><br/>

data/lib/rotulus/column.rb

@@ -26,14 +26,11 @@ module Rotulus
     def initialize(model, name, direction: :asc, nullable: nil, nulls: nil, distinct: nil)
       @model = model
       @name = name.to_s
-      unless name_valid?
-        raise Rotulus::InvalidColumnError.new("Column/table name must contain letters, digits (0-9), or \
-          underscores and must begin with a letter or underscore.".squish)
-      end
+      validate_name!
 
-      @direction = direction.to_s.downcase == 'desc' ? :desc : :asc
-      @distinct = (distinct.nil? ? primary_key? : distinct).presence || false
-      @nullable = (nullable.nil? ? metadata&.null : nullable).presence || false
+      @direction = sort_direction(direction)
+      @distinct = uniqueness(distinct)
+      @nullable = nullability(nullable)
       @nulls = nulls_order(nulls)
     end
 
@@ -150,8 +147,27 @@ module Rotulus
       Rotulus.db.default_nulls_order(direction)
     end
 
+    def nullability(nullable)
+      (nullable.nil? ? metadata&.null : nullable).presence || false
+    end
+
     def primary_key?
       unprefixed_name == model.primary_key
     end
+
+    def sort_direction(direction)
+      direction.to_s.downcase == 'desc' ? :desc : :asc
+    end
+
+    def uniqueness(unique)
+      (unique.nil? ? primary_key? : unique).presence || false
+    end
+
+    def validate_name!
+      return if name_valid?
+
+      raise Rotulus::InvalidColumn.new("Column/table name must contain letters, digits (0-9), or \
+          underscores and must begin with a letter or underscore.".squish)
+    end
   end
 end

data/lib/rotulus/column_condition_builder.rb

@@ -38,18 +38,19 @@ module Rotulus
     end
 
     def nullable_filter_condition
-      if seek_to_null_direction?
-        return tie_break null_condition if value.nil?
+      return seek_to_null_direction_condition if seek_to_null_direction?
+      return filter_condition unless value.nil?
 
-        condition = "#{seek_condition} OR #{null_condition}"
-        return condition if column.distinct?
+      "#{not_null_condition} OR (#{tie_break(null_condition)})"
+    end
 
-        prefilter("(#{condition}) OR (#{tie_break(identity)})")
-      else
-        return filter_condition unless value.nil?
+    def seek_to_null_direction_condition
+      return tie_break null_condition if value.nil?
 
-        "#{not_null_condition} OR (#{tie_break(null_condition)})"
-      end
+      condition = "#{seek_condition} OR #{null_condition}"
+      return condition if column.distinct?
+
+      prefilter("(#{condition}) OR (#{tie_break(identity)})")
     end
 
     def identity

data/lib/rotulus/configuration.rb

@@ -6,8 +6,10 @@ module Rotulus
       @page_default_limit = default_limit
       @page_max_limit = default_max_limit
       @secret = ENV['ROTULUS_SECRET']
-      @token_expires_in = 259200
+      @token_expires_in = 259_200
       @cursor_class = default_cursor_class
+      @restrict_order_change = false
+      @restrict_query_change = false
     end
 
     def page_default_limit=(limit)
@@ -49,6 +51,22 @@ module Rotulus
       @cursor_class || default_cursor_class
     end
 
+    def restrict_order_change=(restrict)
+      @restrict_order_change = !!restrict
+    end
+
+    def restrict_order_change?
+      @restrict_order_change
+    end
+
+    def restrict_query_change=(restrict)
+      @restrict_query_change = !!restrict
+    end
+
+    def restrict_query_change?
+      @restrict_query_change
+    end
+
     private
 
     def default_cursor_class

data/lib/rotulus/cursor.rb

@@ -9,19 +9,32 @@ module Rotulus
       #  @param token [String] Base64-encoded string data
       #  @return [Cursor] Cursor
       #
-      #  @raise [InvalidCursor] if the cursor is no longer consistent to the page's ActiveRecord
-      #    relation filters, sorting, or if the encoded cursor data was tampered.
+      #  @raise [InvalidCursor] if the token can't be decoded or if the cursor data was tampered.
+      #  @raise [OrderChanged] if token generated from a page with a different `:order` definition.
+      #  @raise [QueryChanged] if token generated from a page with a different `:ar_relation`.
       def for_page_and_token!(page, token)
         data = decode(token)
-        reference_record = Record.new(page, data[:f])
-        direction = data[:d]
-        created_at = Time.at(data[:c]).utc
-        state = data[:s].presence
+        reference_record = Record.new(page, data['f'])
+        direction = data['d']
+        created_at = Time.at(data['c']).utc
+        cursor_state = data['cs'].presence
+        order_state = data['os'].presence
+        query_state = data['qs'].presence
 
         cursor = new(reference_record, direction, created_at: created_at)
 
-        if cursor.state != state
-          raise InvalidCursor.new('Invalid cursor possibly due to filter or sorting changed')
+        raise InvalidCursor if cursor.state != cursor_state
+
+        if page.order_state != order_state
+          raise OrderChanged if Rotulus.configuration.restrict_order_change?
+
+          return nil
+        end
+
+        if page.query_state != query_state
+          raise QueryChanged if Rotulus.configuration.restrict_query_change?
+
+          return nil
         end
 
         cursor
@@ -35,8 +48,8 @@ module Rotulus
       #    of the previous page if page direction is `:next` or the first record of the next
       #    page if page direction is `:prev`.
       def decode(token)
-        Oj.load(Base64.urlsafe_decode64(token))
-      rescue ArgumentError => e
+        MultiJson.load(Base64.urlsafe_decode64(token))
+      rescue ArgumentError, MultiJson::ParseError => e
         raise InvalidCursor.new("Invalid Cursor: #{e.message}")
       end
 
@@ -45,7 +58,7 @@ module Rotulus
       #  @param token_data [Hash] Cursor token data hash
       #  @return token [String] String token for this cursor that can be used as param to Page#at.
       def encode(token_data)
-        Base64.urlsafe_encode64(Oj.dump(token_data, symbol_keys: true))
+        Base64.urlsafe_encode64(MultiJson.dump(token_data))
       end
     end
 
@@ -91,21 +104,21 @@ module Rotulus
     #
     # @return [String] the token encoded in Base64.
     def to_token
-      @token ||= self.class.encode(f: record.values,
-                                   d: direction,
-                                   s: state,
-                                   c: created_at.to_i)
+      @token ||= self.class.encode('f' => record.values.as_json,
+                                   'd' => direction,
+                                   'c' => created_at.to_i,
+                                   'cs' => state,
+                                   'os' => page.order_state,
+                                   'qs' => page.query_state)
     end
     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 or order definition. This also provides a mechanism to detect if
-    # any token data was tampered.
+    # Generate a 'state' string for integrity checking of the reference record, direction,
+    # and created_at data from a decoded Cursor token.
     #
     # @return [String] the hashed state
     def state
-      state_data = "#{page.state}#{record.state}"
-      state_data << "#{direction}#{created_at.to_i}#{secret}"
+      state_data = "#{record.state}#{direction}#{created_at.to_i}#{secret}"
 
       Digest::MD5.hexdigest(state_data)
     end

data/lib/rotulus/order.rb

@@ -10,10 +10,11 @@ module Rotulus
       @raw_hash = raw_hash&.with_indifferent_access || {}
       @definition = {}
 
-      build_column_definitions
+      build_column_definitions!
 
       return if has_tiebreaker?
-      raise Rotulus::MissingTiebreakerError.new('A non-nullable and distinct column is required.')
+
+      raise Rotulus::MissingTiebreaker.new('A non-nullable and distinct column is required.')
     end
 
     # Returns an array of the ordered columns
@@ -79,7 +80,9 @@ module Rotulus
     #
     # @return [String] the hashed state
     def state
-      Digest::MD5.hexdigest(Oj.dump(to_h, mode: :rails))
+      data = MultiJson.dump(to_h)
+
+      Digest::MD5.hexdigest("#{data}#{Rotulus.configuration.secret}")
     end
 
     # Returns a hash containing the hash representation of the ordered columns.
@@ -123,7 +126,7 @@ module Rotulus
       unless model_override.nil?
         return model_override unless model_override.columns_hash[unprefixed_name].nil?
 
-        raise Rotulus::InvalidColumnError.new(
+        raise Rotulus::InvalidColumn.new(
           "Model '#{model_override}' doesnt have a '#{name}' column. \
           Tip: check the :model option value in the column's order configuration.".squish
         )
@@ -134,7 +137,7 @@ module Rotulus
         return ar_model
       end
 
-      raise Rotulus::InvalidColumnError.new(
+      raise Rotulus::InvalidColumn.new(
         "Unable determine which model the column '#{name}' belongs to. \
         Tip: set/check the :model option value in the column's order configuration.".squish
       )
@@ -150,39 +153,42 @@ module Rotulus
       !definition["#{ar_table}.#{ar_model_primary_key}"].nil?
     end
 
-    def build_column_definitions
+    def build_column_definitions!
       raw_hash.each do |column_name, options|
         column_name = column_name.to_s
 
-        unless options.is_a?(Hash)
-          options = if options.to_s.downcase == 'desc'
-                      { direction: :desc }
-                    else
-                      { direction: :asc }
-                    end
-        end
-
-        model = column_model(options[:model].presence, column_name)
+        options = normalize_column_options(options)
+        model = column_model(options.delete(:model), column_name)
         column = Column.new(model,
                             column_name,
                             direction: options[:direction],
                             nulls: options[:nulls],
                             nullable: options[:nullable],
                             distinct: options[:distinct])
-        next unless definition[column.prefixed_name].nil?
-
-        definition[column.prefixed_name] = column
+        definition[column.prefixed_name] ||= column
       end
 
       # Add tie-breaker using the PK
-      unless primary_key_ordered?
-        pk_column = Column.new(ar_model, ar_model_primary_key, direction: :asc)
-        definition[pk_column.prefixed_name] = pk_column
-      end
+      add_pk_tiebreaker_column!
 
       columns.first.as_leftmost!
     end
 
+    def add_pk_tiebreaker_column!
+      return if primary_key_ordered?
+
+      pk_column = Column.new(ar_model, ar_model_primary_key, direction: :asc)
+
+      definition[pk_column.prefixed_name] = pk_column
+    end
+
+    def normalize_column_options(options)
+      return options if options.is_a?(Hash)
+      return { direction: :desc } if options.to_s.downcase == 'desc'
+
+      { direction: :asc }
+    end
+
     # Returns an array of SELECT statement alias of the ordered columns
     #
     # @return [Array<String>] column SELECT aliases

data/lib/rotulus/page.rb

@@ -2,7 +2,7 @@ module Rotulus
   class Page
     attr_reader :ar_relation, :order, :limit, :cursor
 
-    delegate :columns, to: :order, prefix: true
+    delegate :columns, :state, to: :order, prefix: true
 
     # Creates a new Page instance representing a subset of the given ActiveRecord::Relation
     # records sorted using the given 'order' definition param.
@@ -77,7 +77,7 @@ module Rotulus
     # @param token [String] Base64-encoded representation of cursor
     # @return [self] page instance
     def at!(token)
-      @cursor = token.present? ? cursor_clazz.for_page_and_token!(self, token) : nil
+      @cursor = token.present? ? config.cursor_class.for_page_and_token!(self, token) : nil
 
       reload
     end
@@ -131,7 +131,7 @@ module Rotulus
       record = cursor_reference_record(:next)
       return if record.nil?
 
-      cursor_clazz.new(record, :next).to_token
+      config.cursor_class.new(record, :next).to_token
     end
 
     # Generate the cursor token to access the previous page if one exists
@@ -143,7 +143,7 @@ module Rotulus
       record = cursor_reference_record(:prev)
       return if record.nil?
 
-      cursor_clazz.new(record, :prev).to_token
+      config.cursor_class.new(record, :prev).to_token
     end
 
     # Next page instance
@@ -176,12 +176,14 @@ 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 and
-    # order definition are still consistent to the cursor. see Cursor.state_valid?.
+    # Return Hashed value of this page's state so we can check whether the base ar_relation has
+    # changed(e.g. SQL/filters from API params). see Cursor.for_page_and_token!
     #
     # @return [String] the hashed state
-    def state
-      Digest::MD5.hexdigest("#{ar_relation.to_sql}~#{order.state}")
+    def query_state
+      data = ar_relation.to_sql
+
+      Digest::MD5.hexdigest("#{data}#{Rotulus.configuration.secret}")
     end
 
     # Returns a string showing the page's records in table form with the ordered columns
@@ -200,6 +202,8 @@ module Rotulus
 
     private
 
+    delegate :model, to: :ar_relation, prefix: false
+
     # If this is the root page or when paginating forward(#paged_forward), limit+1
     # includes the first record of the next page. This lets us know whether there is a page
     # succeeding the current page. When paginating backwards(#paged_back?), the limit+1 includes the
@@ -241,15 +245,11 @@ module Rotulus
     # to filter next/prev page's records. Alias and normalize those columns so we can access
     # the values using record#slice.
     def select_columns
-      base_select_values = ar_relation.select_values.presence || [select_all_sql]
+      base_select_values = ar_relation.select_values.presence || [Rotulus.db.select_all_sql(model.table_name)]
       base_select_values << order.select_sql
       base_select_values
     end
 
-    def select_all_sql
-      Rotulus.db.select_all_sql(model.table_name)
-    end
-
     def order_by_sql
       return order.reversed_sql if paged_back?
 
@@ -263,16 +263,8 @@ module Rotulus
       limit >= 1 && limit <= config.page_max_limit
     end
 
-    def model
-      ar_relation.model
-    end
-
     def config
       @config ||= Rotulus.configuration
     end
-
-    def cursor_clazz
-      @cursor_clazz ||= config.cursor_class
-    end
   end
 end

data/lib/rotulus/version.rb

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

data/lib/rotulus.rb

@@ -1,7 +1,7 @@
 require 'active_record'
 require 'active_support'
 require 'active_support/core_ext/string/inquiry'
-require 'oj'
+require 'multi_json'
 require 'rotulus/version'
 require 'rotulus/configuration'
 require 'rotulus/db/database'
@@ -15,14 +15,16 @@ require 'rotulus/page'
 
 module Rotulus
   class BaseError < StandardError; end
+  class InvalidLimit < BaseError; end
   class CursorError < BaseError; end
   class InvalidCursor < CursorError; end
   class ExpiredCursor < CursorError; end
   class InvalidCursorDirection < CursorError; end
-  class InvalidLimit < BaseError; end
+  class OrderChanged < CursorError; end
+  class QueryChanged < CursorError; end
   class ConfigurationError < BaseError; end
-  class MissingTiebreakerError < ConfigurationError; end
-  class InvalidColumnError < ConfigurationError; end
+  class MissingTiebreaker < ConfigurationError; end
+  class InvalidColumn < ConfigurationError; end
 
   def self.db
     @db ||= case ActiveRecord::Base.connection.adapter_name.downcase

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rotulus
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 2.0.0
 platform: ruby
 authors:
 - Uy Jayson B
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-05-24 00:00:00.000000000 Z
+date: 2023-06-10 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.0.5
+        version: '7.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -29,7 +29,7 @@ dependencies:
         version: '4.2'
     - - "<"
       - !ruby/object:Gem::Version
-        version: 7.0.5
+        version: '7.1'
 - !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.0.5
+        version: '7.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -49,21 +49,21 @@ dependencies:
         version: '4.2'
     - - "<"
       - !ruby/object:Gem::Version
-        version: 7.0.5
+        version: '7.1'
 - !ruby/object:Gem::Dependency
-  name: oj
+  name: multi_json
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.15'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.15'
 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: