rotulus 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b01279029660a73c745ba2c67c703454f54f44a160b5964523c0fd521ca973c0
-  data.tar.gz: b1479c0f2a2b8971e4d8977f4b5e4a052829d2d3f472fe1199497266d8d3cafe
+  metadata.gz: 2c74625ece0961a25549797386fa66abb146564211b4dc1640abd92ac4c0e2a0
+  data.tar.gz: 567562c553bbe914cdf5740e4262bd76b59ef04493658a68c69bd420e3109283
 SHA512:
-  metadata.gz: 12120dce0516e9823e891dea5bfe76af1148234e18a556f1d889d1b5ec68031746afbe6e0599955ced295de214d6eedfa3b560ffdce03e0c49e94561a3c5399a
-  data.tar.gz: 6b10d0bab75dffd5f1c988f09161a56cdc0688e50af403864a9b15c6d6b0b2a1191eddff5606be86e516ba3ba785a96cbbaa39dbb963593a00108fb4aee8bc23
+  metadata.gz: 9e1380f553f3a0756b36b21f2a6193ee7031fe29bc8b3478ec349f6c35d2b9292ed5afd295b6b5250b2dc4498e1d86b66d13d639ea5e3d36db78fc8868fb4e9f
+  data.tar.gz: 625359b428c792c30a2a2ee2b6b702a2c7270e495111c284c82a1d1433eddf5d0ac485d6d5ae961128006f161c4cb01b8fa76f7ab3bd14d63cb761306a9392f6

data/CHANGELOG.md

@@ -1,3 +1,8 @@
-## 0.1.0
+## 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.

data/README.md

@@ -1,6 +1,6 @@
 # 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)
 
 ### Cursor-based pagination for apps built on Rails/ActiveRecord 
 
@@ -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.
 
 
@@ -352,13 +353,13 @@ page = Rotulus::Page.new(User.all, order: { first_name: { direction: :asc, nulls
 
 ###### SQL:
 ```sql
--- if first_name value of the last record on current page is not null:
+-- if last_name value of the current page's last record  is not null:
 WHERE ((users.last_name >= ? OR users.last_name IS NULL) AND
   ((users.last_name > ? OR users.last_name IS NULL) 
   OR (users.last_name = ? AND users.id > ?)))
 ORDER BY users.last_name asc nulls last, users.id asc LIMIT 3
 
--- if first_name value of the last record on current page is null:
+-- if last_name value of the current page's last record is null:
 WHERE users.last_name IS NULL AND users.id > ?
 ORDER BY users.last_name asc nulls last, users.id asc LIMIT 3
 ```

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
@@ -62,14 +65,14 @@ module Rotulus
     #
     # @return [String] the ORDER BY clause
     def reversed_sql
-      Arel.sql(columns.map(&:reversed_order_sql).join(', '))
+      Arel.sql(columns_for_order.map(&:reversed_order_sql).join(', '))
     end
 
     # Returns the ORDER BY sort expression(s) to sort the records
     #
     # @return [String] the ORDER BY clause
     def sql
-      Arel.sql(columns.map(&:order_sql).join(', '))
+      Arel.sql(columns_for_order.map(&:order_sql).join(', '))
     end
 
     # Generate a 'state' so we can detect whether the order definition has changed.
@@ -92,6 +95,19 @@ module Rotulus
 
     attr_reader :ar_model, :definition, :raw_hash
 
+    def columns_for_order
+      return @columns_for_order if instance_variable_defined?(:@columns_for_order)
+
+      @columns_for_order = []
+      columns.each do |col|
+        @columns_for_order << col
+
+        break if col.distinct? && !col.nullable?
+      end
+
+      @columns_for_order
+    end
+
     def ar_model_primary_key
       ar_model.primary_key
     end
@@ -124,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/version.rb

@@ -1,3 +1,3 @@
 module Rotulus
-  VERSION = '0.2.0'
+  VERSION = '0.2.2'
 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.0
+  version: 0.2.2
 platform: ruby
 authors:
 - Uy Jayson B
@@ -73,7 +73,6 @@ extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
-- Gemfile
 - LICENSE
 - README.md
 - lib/rotulus.rb
@@ -97,7 +96,7 @@ metadata:
   homepage_uri: https://github.com/jsonb-uy/rotulus
   source_code_uri: https://github.com/jsonb-uy/rotulus
   changelog_uri: https://github.com/jsonb-uy/rotulus/blob/main/CHANGELOG.md
-  documentation_uri: https://rubydoc.info/github/jsonb-uy/rotulus
+  documentation_uri: https://rubydoc.info/github/jsonb-uy/rotulus/main
   bug_tracker_uri: https://github.com/jsonb-uy/rotulus/issues
 post_install_message:
 rdoc_options: []

data/Gemfile

@@ -1,46 +0,0 @@
-source 'https://rubygems.org'
-gemspec
-
-rails_version = ENV['RAILS_VERSION'] || '7-0-stable'
-
-gem 'rake'
-gem 'rspec'
-
-if ENV.fetch('COVERAGE', nil) == 'true'
-  gem 'simplecov'
-  gem 'simplecov-cobertura'
-end
-
-case rails_version
-when '4-2-stable'
-  # Ruby 2.2 or newer.
-  gem 'pg', '~> 0.15'
-  gem 'sqlite3', '~> 1.3.6'
-  gem 'mysql2', '~> 0.4.4'
-when '5-0-stable', '5-1-stable', '5-2-stable'
-  # Ruby 2.2.2 or newer.
-  gem 'pg', '~> 0.18'
-  gem 'sqlite3', '~> 1.3.6'
-  gem 'mysql2', '~> 0.4.4'
-when '6-0-stable'
-  # Ruby 2.5.0 or newer.
-  gem 'pg', '~> 0.18'
-  gem 'sqlite3', '~> 1.4'
-  gem 'mysql2', '>= 0.4.4'
-when '6-1-stable'
-  # Ruby 2.5.0 or newer.
-  gem 'pg', '~> 1.1'
-  gem 'sqlite3', '~> 1.4'
-  gem 'mysql2', '~> 0.5'
-when '7-0-stable'
-  # Ruby 2.7.0 or newer.
-  gem 'pg', '~> 1.1'
-  gem 'sqlite3', '~> 1.4'
-  gem 'mysql2', '~> 0.5'
-else
-  gem 'pg'
-  gem 'sqlite3'
-  gem 'mysql2'
-end
-
-gem 'rails', git: 'https://github.com/rails/rails', branch: rails_version