rotulus 0.2.1 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6bc659ce794517af485f9c65dc18467b4278c21e8813e612a0b4dcdabde0b10f
-  data.tar.gz: 2dc66e54844499214cc07ae49d8ca0ad33586ba28a11d4e2a3a4366d4633525a
+  metadata.gz: 15fae43a1fc07b2c268c1604c065a12f0d2288d733219aa563348019a872d7a0
+  data.tar.gz: ca8548477eee36f6bed018d8ec20d5dd5217f74d36954f13b4e243fbaee6755e
 SHA512:
-  metadata.gz: f60f971213d39e4baa5d6fd53227971df6e09fb87f1824487e17a2972e80803db29e2b5894cc7b0be659d73ad3bf959a5944c5ed0235b754f19a80afe0cd69e1
-  data.tar.gz: f0b072563fe10c626772f2879d9533263b393452022a5e4547ea6e5413a5bfab92ef629dd3aa787328b3bda14ae89ae04e1d5c345073fe3ae2e2afc2092dae86
+  metadata.gz: f9d0e4611e800688f8c10ad7347043a07e7358f79a4254ecac6359a1f5f4101d323cfe0b21d45b363984cdc681e3ffc8b8b9587311e96553ab952eb76016792b
+  data.tar.gz: a3240e33d45cd4360c4235e94860558c584a9f1f373c9ad7451ad9d819c2616f5a2e2146bef0449b716b846144ee87c19e92596c2b39c13e34bef254f49c50af

data/CHANGELOG.md

@@ -1,7 +1,11 @@
 ## 0.2.0
-
-Initial release.
+- Initial release.
 
 ## 0.2.1
+- 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.
 
-Drop unnecessary ORDER BY columns following a non-nullable and distinct column.
+## 0.2.3
+- Replace any existing order defined on the given ar_relation

data/README.md

@@ -295,18 +295,19 @@ 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/limit 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 |
-| `Rotulus:: InvalidColumnError` | Column provided in the :order param is can't be recognized. |
+| `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::ConfigurationError` | Generic error for missing/invalid configurations. |
 
 ## 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:
 
 * Records are sorted (`ORDER BY`).
-* In case multiple records with the same column value(s) exists in the result, a unique 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.
+* 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.
 
 

data/lib/rotulus/order.rb

@@ -11,6 +11,9 @@ module Rotulus
       @definition = {}
 
       build_column_definitions
+
+      return if has_tiebreaker?
+      raise Rotulus::MissingTiebreakerError.new('A non-nullable and distinct column is required.')
     end
 
     # Returns an array of the ordered columns
@@ -137,6 +140,12 @@ module Rotulus
       )
     end
 
+    def has_tiebreaker?
+      last_column = columns_for_order.last
+
+      last_column.distinct? && !last_column.nullable?
+    end
+
     def primary_key_ordered?
       !definition["#{ar_table}.#{ar_model_primary_key}"].nil?
     end

data/lib/rotulus/page.rb

@@ -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.1'
+  VERSION = '0.2.3'
 end

data/lib/rotulus.rb

@@ -21,7 +21,8 @@ module Rotulus
   class InvalidCursorDirection < CursorError; end
   class InvalidLimit < BaseError; end
   class ConfigurationError < BaseError; end
-  class InvalidColumnError < BaseError; end
+  class MissingTiebreakerError < ConfigurationError; end
+  class InvalidColumnError < ConfigurationError; end
 
   def self.db
     @db ||= case ActiveRecord::Base.connection.adapter_name.downcase

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rotulus
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.3
 platform: ruby
 authors:
 - Uy Jayson B
@@ -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: []