rotulus 1.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 149f276bc80e599488039c9858f817000766d74d6a494c1447ec58167a83c424
-  data.tar.gz: dad1c9cad5c214e88ede97573c18fbff1b65ed4a21e46b045a388910b325b5a7
+  metadata.gz: 7504d29a1bd4aac2f21ffb981abd98b544b8b50f80fa7f875cc73286e967e9a2
+  data.tar.gz: afbd5665291c310b0fd03e87cebd0b100da71dcfdedae7953b4844c767859ce3
 SHA512:
-  metadata.gz: aab89cbb1f43d71ceddfe8cb1bb60d2d343f3d114109cb3d97d8650bca138d31893a1d803d7563b01ec51cca5eb3d227878f1fe2569d521edf6b9fc12ac2d364
-  data.tar.gz: 73e0d95ca8771ca86517f6fcf3def575b5536b269f3d6cdb65c7be887f633fa872bb0d8bc479c7932a592ba0bd204f29d5ba7ba2a43acb54546981c65c62c102
+  metadata.gz: 19d4f2b1e1a734c78b8d63954ef66ba443591a7fc2c04364eccc6e1a0780b4f3e6346af327e53f3ba773bafca9a39b3abd5ef7efc8937b71a8fc534d7d16dc84
+  data.tar.gz: 0a739f5977b51127934658605a304f78a6be0ffe8d4e3e0ddce8fe4abc1223e6bf0c7ef1dfd39afd6b675f7006b9b3f4074fd11cf5329d9433886dd06dc18bd8

data/CHANGELOG.md

@@ -15,4 +15,7 @@
 
 ## 1.0.0
 - Allow changing of ar_relation and order by default.
-- Make error class names consistent.
+- 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,23 @@
 # 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.
+* 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
 
-* 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,21 +47,24 @@ 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
-  config.restrict_order_change = false
-  config.restrict_query_change = false
-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 |
 | ----------- | ----------- |
@@ -70,7 +75,8 @@ end
 | `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
@@ -93,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
@@ -128,7 +134,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
@@ -172,6 +178,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:
 
@@ -191,15 +205,15 @@ 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 |
 | ----------- | ----------- |
 | `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:
@@ -262,7 +276,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.  
 
@@ -291,7 +305,51 @@ 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] = +last_name,-email
+# b. params[:sort] = -first_name
+def index_order
+  SortParam.define do
+    field 'first_name'
+    field 'last_name', nulls: :last, nullable: true
+    field 'email', distinct: true
+  end.load!(params[:sort].presence || 'first_name')
+end
+```
 
 ### Errors
 
@@ -303,19 +361,19 @@ page = Rotulus::Page.new(items, order: order_by, limit: 2)
 | `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
@@ -376,20 +434,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. `cs` - the cursor state needed for integrity checking, restrict clients/third-parties from generating their own (unsafe)tokens, or from tampering the data of an existing token. 
+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 neede to detect whether the ar_relation has changed (e.g. filter/query changed due to API params). 
+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 (
@@ -400,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
@@ -467,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/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::InvalidColumn.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/cursor.rb

@@ -14,12 +14,12 @@ module Rotulus
       #  @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
-        cursor_state = data[:cs].presence
-        order_state = data[:os].presence
-        query_state = data[:qs].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)
 
@@ -48,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, Oj::ParseError => e
+        MultiJson.load(Base64.urlsafe_decode64(token))
+      rescue ArgumentError, MultiJson::ParseError => e
         raise InvalidCursor.new("Invalid Cursor: #{e.message}")
       end
 
@@ -58,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
 
@@ -104,12 +104,12 @@ module Rotulus
     #
     # @return [String] the token encoded in Base64.
     def to_token
-      @token ||= self.class.encode(f: record.values,
-                                   d: direction,
-                                   c: created_at.to_i,
-                                   cs: state,
-                                   os: page.order_state,
-                                   qs: page.query_state)
+      @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
 

data/lib/rotulus/order.rb

@@ -10,7 +10,7 @@ module Rotulus
       @raw_hash = raw_hash&.with_indifferent_access || {}
       @definition = {}
 
-      build_column_definitions
+      build_column_definitions!
 
       return if has_tiebreaker?
 
@@ -80,7 +80,7 @@ module Rotulus
     #
     # @return [String] the hashed state
     def state
-      data = Oj.dump(to_h, mode: :rails)
+      data = MultiJson.dump(to_h)
 
       Digest::MD5.hexdigest("#{data}#{Rotulus.configuration.secret}")
     end
@@ -153,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

@@ -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
@@ -202,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
@@ -243,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?
 
@@ -265,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 = '1.0.0'.freeze
+  VERSION = '2.1.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'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rotulus
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Uy Jayson B
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-05-25 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,21 +49,21 @@ dependencies:
         version: '4.2'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '7.2'
 - !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: