acts_as_ranked_list 0.2.1 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bb3133201175d913d991f6b0d2184d546bf928439dee69e31b5ae0c3dc4e171b
-  data.tar.gz: 53d0271e984cc9e85004ac80a0bb25f1f6137dc4b1c3ae2dc4705146e78eed6b
+  metadata.gz: 55fb6b1014091f8df47866752d9aedc4cdac1204955852b09c84d480e2769486
+  data.tar.gz: 34bc12ea565e8fd881a6401d9b5cc3ea4e83b86106abb6ee1ec1b7d4a19c1fac
 SHA512:
-  metadata.gz: 7e93a7f60c55c2e1f9b82a8b432bbfbd52169a175d25ea6f0972704f84335e266b2e599e22209e07d8d3c13601ff3297aecae90f0b5e646b5204803e1a91afc4
-  data.tar.gz: 79bb3e16a410df16e289747c0dc2dd0e642fef50dfd745e3ec073765c2449d8ebaabaed81430b14c7b1921359ea3e4f63466db98ff8a0071d568866e7aacb878
+  metadata.gz: b283316886e10b9d469843c3814fda1143ea619feacd8f2415e8d323c1a21c41281b91b9407b53bdd43425192ccc5dd5aa29ec905030788404490dba844a8765
+  data.tar.gz: dd72d4345b6d37ee33f8f4513200c793865f52c8468949f9935962c77ab898ded2b7fffc43ad9b1616e6e3a55517dd72964bed168069de9c79c04699f61c8b9e

data/CHANGELOG.md

@@ -7,8 +7,18 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
-- Allows unranked items in list by having `nil` values. New items can also be added as unranked.
-- Allows different scopes on the items by referencing another column.
+## [0.2.3] - 2023-12-31
+
+- Updates gem dependencies.
+
+## [0.2.2] - 2023-04-24
+
+- ~~Allows unranked items in list by having `nil` values.~~ Implicitly allowed behaviour since v0.2.0, also able to add new items can also be added as unranked. Adds documentation to this feature.
+- Allows any number of different scopes on the items by referencing another column, of type:
+  - a relationship.
+  - a string, symbol, boolean or number.
+  - a custom-defined scope.
+- Fixes class method `spread_ranks` to ignore unranked items.
 
 ## [0.2.1] - 2023-04-21
 

data/README.md

@@ -22,15 +22,15 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
 This gem allows you to easily rank `::ActiveRecord` items without worrying about the underlying logic. After installing the gem, add the following `acts_as_ranked_list` to the `::ActiveRecord` model, for example:
 
-```
-class MyModelName << ::ActiveRecord::Base
+```ruby
+class MyModelName < ::ActiveRecord::Base
     acts_as_ranked_list
 end
 ```
 
 When you create a new `MyModelName` item, it will be ranked among the list of existing `MyModelName` items. You can increase/decrease the item's rank by the following methods:
 
-```
+```ruby
 item_a = MyModelName.create!
 item_a.increase_rank
 item_a.decrease_rank
@@ -38,7 +38,7 @@ item_a.decrease_rank
 
 You can get the current rank of the item by the following:
 
-```
+```ruby
 item_a = MyModelName.create! # is at the bottom of the list, highest rank item
 item_b = MyModelName.create! # is at the bottom of the list, lowest rank item
 item_a.current_rank # 1
@@ -49,7 +49,7 @@ Note that the list is viewed as ascending order of `rank, last updated at, id`.
 
 You may get the highest items in the list sorted by rank by the following methods:
 
-```
+```ruby
 my_existing_item = MyModelName.create! # placed top in the list
 my_new_item = MyModelName.create! # placed bottom in the list
 MyModelName.get_highest_items # ActiveRecord::Relation with results [my_existing_item, my_new_item]
@@ -57,7 +57,7 @@ MyModelName.get_highest_items # ActiveRecord::Relation with results [my_existing
 
 You may get the highest/lowest item by specifying a number as the first argument to the `get_highest_items`/`get_lowest_items` methods, such as:
 
-```
+```ruby
 my_existing_item = MyModelName.create! # placed top in the list
 my_new_item = MyModelName.create! # placed bottom in the list
 MyModelName.get_highest_items(1) # ActiveRecord::Relation with results [my_existing_item] # Note the result is an array
@@ -70,8 +70,8 @@ MyModelName.get_highest_items(50000) # ActiveRecord::Relation with results [my_e
 
 For the next examples, each will be initialized to the following:
 
-```
-class TodoItem << ::ApplicationRecord
+```ruby
+class TodoItem < ::ApplicationRecord
     # the rank column is named "priority" (without quotation marks) for this table
     # new items are added as highest priority
     acts_as_ranked_list column: "priority", adds_new_at: :highest, step_increment: 1.0
@@ -87,11 +87,11 @@ print_on_shirt = TodoItem.create!(title: "Print a prototype design on the shrit
 # the lowest prioritised item is "design_reusable_plastic_bag_graphic"
 ```
 
-### Query position of current item
+#### Query position of current item
 
 You can check if an item is the highest item or the lowest item in the list by using the `highest_item?` or `lowest_item?` instance methods.
 
-```
+```ruby
 design_reusable_plastic_bag_graphic.lowest_item? # true
 design_reusable_plastic_bag_graphic.highest_item? # false
 print_on_shirt.highest_item? # true
@@ -101,27 +101,66 @@ print_on_shirt.highest_item? # true
 
 You can get the higher/lower items by using the instance methods `get_higher_items` or `get_lower_items`:
 
-```
+```ruby
 exercise.get_higher_items # items and their priorities (note the order): [["health_check", 0.25], ["print_on_shirt", 0.125]]
 ```
 
 You may pass in optional arguments to control how the results are returned. If the first argument is `0`, it will return all higher/lower items.
 
-```
+```ruby
 design_reusable_plastic_bag_graphic.get_higher_items(2, "ASC") # [["health_check", 0.25], ["exercise", 0.5]]
 ```
 
+#### Scoping items
+
+You may use scopes to constrain your items to a condition. This means you can group items together, and keep them separate from irrelevant items. For example, you may have 2 todo lists, one each for personal or work related tasks. You may fetch each list of todo items separately, and interact with them separetely using scopes.
+
+We'll add a new table, and `::ActiveRecord` model to help demonstrate this feature. For possible options on `scope`, refer to the docs on `service.rb`.
+
+```ruby
+class TodoList < ::ActiveRecord::Base
+    has_many :todo_items
+end
+
+class ScopedTodoItem < ::ActiveRecord::Base
+    belongs_to :todo_list # add to table an integer foreign key column `todo_list_id`
+
+    acts_as_ranked_list scopes: { todo_list: nil }
+end
+
+work_todo_list = ::TodoList.create!(title: "Chores at work :eye_roll:")
+personal_todo_list = ::TodoList.create!(title: "Hobbies to enjoy!!! :partying_face:")
+scoped_work_todo_item = ::ScopedTodoItem.create!(title: "Create a new table to store temporary data", list: work_todo_list, rank: 1)
+scoped_personal_todo_item = ::ScopedTodoItem.create!(title: "Assemble the new couch to enjoy sitting on", list: personal_todo_list, rank: 1)
+```
+
+In the above example, `scoped_personal_todo_item` and `scoped_work_todo_item` have the same rank but are in different scopes. So they do not have colliding ranks, and can be fetched/mutated independently of each other.
+
+You may also use a string, boolean, integer, symbol, named scopes, custom scopes (via a `::Proc`) or all of them together on the same model.
+
+```ruby
+class WorkTodoItem < ScopedTodoItem # Note the parent class
+    scope :work, -> { where(todo_list: ::TodoList.find_by(...)) }
+    default_scope { :work }
+    acts_as_ranked_list scopes: { todo_list: :work } # or
+    acts_as_ranked_list scopes: { todo_list: :work, week_day: ::Proc.new { "day_of_week = 'tuesday'" } } # or
+    acts_as_ranked_list scopes: { todo_list: :work, manager: "Mr. Disney", priority_bracket: :top, related_to_a_paying_customer: true, feature_ticket_number: 42 }
+    # these scopes will require the relevant column names on the table
+    # such as `manager (string), priority_bracket (string), related_to_a_paying_customer (boolean), feature_ticket_number (integer), week_day (preferred enum on integer, or string)
+end
+```
+
 #### Check if the current item is ranked
 
 If the value of the rank column for the instance is `nil` then the item is not ranked. This item will still interact with the list when running queries such as `highest_item?` and so on. This item will be given a rank when [spreading ranks](spread-ranks).
 
-```
+```ruby
 design_reusable_plastic_bag_graphic.is_ranked? # true
 ```
 
 You may create a new item with nil rank as follows:
 
-```
+```ruby
 ## this persists the record, but skips callbacks
 ::TodoItem.with_skip_persistence { ::TodoItem.create!(rank: nil) }
 ```
@@ -130,13 +169,13 @@ You may create a new item with nil rank as follows:
 
 Instead of updating rank one or down one position at a time, you can move above/below another item, using `set_rank_above` or `set_rank_below` instance methods:
 
-```
+```ruby
 design_reusable_plastic_bag_graphic.set_rank_above(health_check)
 ```
 
 This can be used together with the `get_highest_items(1)` class method to move item to the top of the list.
 
-```
+```ruby
 design_reusable_plastic_bag_graphic.set_rank_above(TodoItem.get_highest_items(1).first)
 ```
 
@@ -148,7 +187,7 @@ Skipping persistence is useful if you want to mass update items, and persist onc
 
 You can use the class method `with_skip_persistence` as follows:
 
-```
+```ruby
 TodoItem.with_skip_persistence do
     design_reusable_plastic_bag_graphic.update(rank: 20.3)
     exercise.update(rank: 5.2)
@@ -166,7 +205,7 @@ end
 
 You may also pass in an array of classes to the `with_skip_persistence` method to skip persistence for these `::ActiveRecord` models which use the `acts_as_ranked_list` concern.
 
-```
+```ruby
 TodoItem.with_skip_persistence([FootballTeam]) do # the calling class is added by default, in this case: `TodoItem`
     design_reusable_plastic_bag_graphic.increase_rank
     exercise.increase_rank
@@ -197,7 +236,7 @@ end
 
 You can control whether to spread ranks or not on collisions by using the option `avoid_collisions: true` (by default) on using the concern in your `::ActiveRecord` model. You can change this setting on a per-block per-class basis by using the following class method:
 
-```
+```ruby
 # disallows collisions
 TodoItem.with_avoid_collisions(true) do # do spread ranks on collisions
     TodoItem.find(1).update(rank: 1)
@@ -205,7 +244,7 @@ TodoItem.with_avoid_collisions(true) do # do spread ranks on collisions
 end # items with their new ranks [["health_check", 1.0], ["exercise", 2.0], ["print_on_shirt", 3.0], ["design_reusable_plastic_bag_graphic", 4.0]]
 ```
 
-```
+```ruby
 # allows collisions
 TodoItem.with_avoid_collisions(false) do # do not spread ranks on collisions
     TodoItem.find(1).update(rank: 1)
@@ -219,21 +258,22 @@ You can spread ranks so that the difference between each rank and the next is se
 - Being able to rerank items again without overflowing column's max precision.
 - Human-readable viewing purposes. This is not recommended. The rank should be human-readable (or not viewable) at the view (presentation) layer.
 
-If `avoid_collisions = true (by default)`. Then you do not have to use spread ranks manually. If the database raises an overflow error when mutating a rank, then it could be time to recalibrate the ranks in the table. You should handle this case in your code, and spread ranks. This is very infrequent. For example, in postgres this error will be raised when using the default precision of `16_383` digits after the decimal of a `decimal` column type in postgres versions `9.1+`:
+If `avoid_collisions = true (by default)`. Then you do not have to use spread ranks manually. If the database raises an overflow error when mutating a rank, then it could be time to recalibrate the ranks in the table. You should handle this case in your code, and spread ranks. **This is very infrequent.** For example, in postgres this error will be raised when using the default precision of `16_383` digits after the decimal of a `decimal` column type in postgres versions `9.1+`:
 
-```
+```ruby
 ActiveRecord::RangeError: PG::NumericValueOutOfRange: ERROR:  value overflows numeric format
 ```
 
 Items are spread in, ascending order of each, by:
 
-1. rank
-2. time updated columns (`updated_at` for example)
-3. primary key (`id` for example)
+1. scopes
+2. rank
+3. time updated columns (`updated_at` for example)
+4. primary key (`id` for example)
 
 To spread ranks:
 
-```
+```ruby
 TodoItem.spread_ranks
 TodoItem.get_highest_items # items with their new ranks [["print_on_shirt", 1.0], ["health_check", 2.0], ["exercise", 3.0], ["design_reusable_plastic_bag_graphic", 4.0]]
 ```
@@ -246,8 +286,8 @@ Imagine the scenario where you have 199 records to rank, and you must rank them
 
 If you use a `step_increment` of 1 you will be faced with a max float/integer overflow error by the database, as some of the ranks are more than 2 digits before the decimal point. You may use a decimal `step_increment` that is less than 1, and suitable for this scenario, and ranking will work as expected, without errors.
 
-```
-class CrammedTodoItem << ::ActiveRecord::Base
+```ruby
+class CrammedTodoItem < ::ActiveRecord::Base
     acts_as_ranked_list step_increment: 0.5
 end
 

data/acts_as_ranked_list.gemspec

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "lib/acts_as_ranked_list/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "acts_as_ranked_list"
+  spec.version = ActsAsRankedList::VERSION
+  spec.authors = ["Farbafe"]
+  spec.email = ["yehyapal@gmail.com"]
+
+  spec.summary = "Orders ActiveRecord items by ranks. Influenced by gem ActsAsList."
+  spec.description = "Orders ActiveRecord items by floating ranks for spaces in-between items. Influenced by gem ActsAsList. The floating rank allows inserting items at arbitrary positions without reordering items. Thus, reducing the number of WRITE queries."
+  spec.homepage = "https://github.com/Farbafe/acts_as_ranked_list"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 2.6.0"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/Farbafe/acts_as_ranked_list/tree/main"
+  spec.metadata["changelog_uri"] = "https://github.com/Farbafe/acts_as_ranked_list/tree/main/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Uncomment to register a new dependency of your gem
+  spec.add_dependency "rails", ">= 6.0.3"
+  spec.add_dependency "rake", ">= 13.0"
+  spec.add_dependency "rspec", ">= 3.0"
+  spec.add_dependency "standard", ">= 1.3"
+  spec.add_dependency "rspec-rails", ">= 5.1.2"
+  spec.add_development_dependency "byebug", ">= 11.1.3"
+  spec.add_development_dependency "yard", ">= 0.9.34"
+  spec.add_development_dependency "redcarpet", ">= 3.6.0"
+  spec.add_development_dependency "sqlite3", ">= 1.6.2"
+
+  # For more information and examples about making a new gem, check out our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

data/lib/acts_as_ranked_list/active_record/rank_column.rb

@@ -5,11 +5,47 @@ module ActsAsRankedList #:nodoc:
     module RankColumn
       # Sets the methods to rank `::ActiveRecord` objects. Please refer to 
       # the {file:README.md} file for usage and examples.
-      def self.call(caller_class, rank_column, touch_on_update, step_increment, avoid_collisions, new_item_at)
+      def self.call(caller_class, rank_column, touch_on_update, step_increment, avoid_collisions, new_item_at, scopes)
         caller_class.class_eval do
 
           private
 
+          define_singleton_method :scope_query do
+            @scope_query ||= 
+              begin
+                @named_scopes = []
+                scopes.map do |key, value|
+                  case value
+                  when ::Symbol
+                    if respond_to?(value)
+                      @named_scopes << value
+                      next
+                    end
+                    "#{caller_class.quoted_table_name}.#{connection.quote_column_name(key)} = \"#{value}\""
+                  when ::String, ::Integer, ::TrueClass, ::FalseClass, ::Float
+                    "#{caller_class.quoted_table_name}.#{connection.quote_column_name(key)} = \"#{value}\""
+                  when nil
+                    casted_key = key.to_s
+                    key_column_name = column_names.include?(casted_key) ? casted_key : "#{casted_key}_id"
+
+                    @grouped_scopes ||= []
+                    @grouped_scopes << key_column_name.to_sym
+                    next
+                  when ::Proc
+                    called_value = value.call
+                    if called_value.is_a?(::String)
+                      next called_value
+                    else
+                      @anonymous_scopes ||= all
+                      @anonymous_scopes.merge!(called_value)
+                      next
+                    end
+                  end
+                end.compact.join(" AND ") || "1 = 1"
+              end
+          end
+          scope_query # initializes variables
+
           define_singleton_method :new_item_at do
             new_item_at
           end
@@ -28,7 +64,17 @@ module ActsAsRankedList #:nodoc:
           end
 
           define_singleton_method :acts_as_ranked_list_query do
-            default_scoped.unscope(:select, :where)
+            @acts_as_ranked_list_query ||= 
+              begin
+                query = @named_scopes.inject(default_scoped.unscope(:select, :where).where("#{scope_query}")) do |chain, scope|
+                  chain.send(*scope)
+                end
+                query.merge!(@anonymous_scopes) if @anonymous_scopes.present?
+                @named_scopes = nil
+                @anonymous_scopes = nil
+
+                query
+              end
           end
 
           define_singleton_method :quoted_rank_column do
@@ -43,28 +89,34 @@ module ActsAsRankedList #:nodoc:
             @order_by_columns ||= {}
             @order_by_columns[order] ||= <<~ORDER_BY_COLUMNS.squish
               #{
-                [ quoted_rank_column,
+                [ *@grouped_scopes,
+                  quoted_rank_column,
                   *quoted_timestamp_attributes_for_update_in_model,
                   primary_key
-                ].join(" #{order}, ")
+                ].compact.join(" #{order}, ")
               } #{order}
             ORDER_BY_COLUMNS
           end
 
           define_singleton_method :spread_ranks do
-            sql = <<~SQL.squish
-              WITH ORDERED_ROW_NUMBER_CTE AS (
-                SELECT #{caller_class.primary_key}, 
-                  ROW_NUMBER() OVER (ORDER BY #{order_by_columns("ASC")}) AS rn
-                FROM #{caller_class.quoted_table_name}
-              )
-              UPDATE #{caller_class.quoted_table_name}
-              SET #{quoted_rank_column} = ORDERED_ROW_NUMBER_CTE.rn * #{step_increment} #{with_touch}
-              FROM ORDERED_ROW_NUMBER_CTE
-              WHERE #{caller_class.quoted_table_name}.#{caller_class.primary_key} = ORDERED_ROW_NUMBER_CTE.#{caller_class.primary_key}
-            SQL
-
-            connection.execute(sql)
+            @spread_ranks_sql ||= 
+              begin
+                scope_query_presence = scope_query.present? ? "AND #{scope_query}" : ""
+                <<~SQL.squish
+                  WITH ORDERED_ROW_NUMBER_CTE AS (
+                    SELECT #{caller_class.primary_key}, 
+                      ROW_NUMBER() OVER (ORDER BY #{order_by_columns("ASC")}) AS rn
+                    FROM #{caller_class.quoted_table_name}
+                  )
+                  UPDATE #{caller_class.quoted_table_name}
+                  SET #{quoted_rank_column} = ORDERED_ROW_NUMBER_CTE.rn * #{step_increment} #{with_touch}
+                  FROM ORDERED_ROW_NUMBER_CTE
+                  WHERE #{caller_class.quoted_table_name}.#{caller_class.primary_key} = ORDERED_ROW_NUMBER_CTE.#{caller_class.primary_key}
+                  AND #{quoted_rank_column_with_table_name} IS NOT NULL #{scope_query_presence}
+                SQL
+              end
+
+            connection.execute(@spread_ranks_sql)
           end
 
           define_singleton_method :with_touch do
@@ -90,19 +142,23 @@ module ActsAsRankedList #:nodoc:
           end
 
           define_singleton_method :get_highest_items do |limit = 0|
-            query = acts_as_ranked_list_query.order(order_by_columns)
+            @get_highest_items_query ||= acts_as_ranked_list_query
+              .where("#{quoted_rank_column} IS NOT NULL")
+              .order(order_by_columns)
 
-            return query if limit == 0
-            
-            query.limit(limit)
+            return @get_highest_items_query if limit == 0
+
+            @get_highest_items_query.limit(limit)
           end
 
           define_singleton_method :get_lowest_items do |limit = 0|
-            query = acts_as_ranked_list_query.order(order_by_columns("DESC"))
+            @get_lowest_items_query ||= acts_as_ranked_list_query
+              .where("#{quoted_rank_column} IS NOT NULL")
+              .order(order_by_columns("DESC"))
 
-            return query if limit == 0
-            
-            query.limit(limit)
+            return @get_lowest_items_query if limit == 0
+
+            @get_lowest_items_query.limit(limit)
           end
         end
 
@@ -200,12 +256,19 @@ module ActsAsRankedList #:nodoc:
           end
 
           define_method :get_higher_items do |limit = 0, order = "DESC", rank = nil, distinct = false, include_self_rank = false|
+            return if current_rank.nil?
+
             operator = include_self_rank ? "<=" : "<"
             rank ||= current_rank
 
             query = self.class.acts_as_ranked_list_query
               .where("#{self.class.quoted_rank_column} #{operator} #{rank}")
-              .order(self.class.order_by_columns(order))
+
+            self.class.instance_variable_get(:@grouped_scopes)&.each do |grouped_scope|
+              query = query.where(grouped_scope => self.send(grouped_scope))
+            end
+
+            query = query.order(self.class.order_by_columns(order))
 
             query = query.distinct(self.class.quoted_rank_column) if distinct
 
@@ -215,12 +278,19 @@ module ActsAsRankedList #:nodoc:
           end
 
           define_method :get_lower_items do |limit = 0, order = "ASC", rank = nil, distinct = false, include_self_rank = false|
+            return if current_rank.nil?
+
             operator = include_self_rank ? ">=" : ">"
             rank ||= current_rank
 
             query = self.class.acts_as_ranked_list_query
               .where("#{self.class.quoted_rank_column} #{operator} #{rank}")
-              .order(self.class.order_by_columns(order))
+
+            self.class.instance_variable_get(:@grouped_scopes)&.each do |grouped_scope|
+              query = query.where(grouped_scope => self.send(grouped_scope))
+            end
+
+            query = query.order(self.class.order_by_columns(order))
 
             query = query.distinct(self.class.quoted_rank_column) if distinct
 
@@ -230,11 +300,11 @@ module ActsAsRankedList #:nodoc:
           end
 
           define_method :highest_item? do
-            self.class.get_highest_items(1).first == self
+            !get_higher_items.exists?
           end
 
           define_method :lowest_item? do
-            self.class.get_lowest_items(1).first == self
+            !get_lower_items.exists?
           end
 
           private

data/lib/acts_as_ranked_list/active_record/service.rb

@@ -17,6 +17,22 @@ module ActsAsRankedList
       #     acts_as_ranked_list column: "position", touch_on_update: false, step_increment: 0.5, avoid_collisions: false, new_item_at: :highest
       #   end
       #
+      # @example when using scope 
+      #   class TodoItem << ::ActiveRecord::Base
+      #     belongs_to :todo_list
+      #     scope :recently_added, -> { where(created_at: ::Time.now - 12.hours..) }
+      #     acts_as_ranked_list scopes: do # you may use as many scopes together
+      #       column_name_one: "work", # items that have value `work` in column `column_name_one` are scoped together
+      #       column_name_two: :personal, # using a symbol is overloaded, check parameters and example for more info
+      #       column_name_three: 0, # this could be used to sub-rank items within a rank
+      #       column_name_four: true,
+      #       column_name_five: :recently_added, # ranks items within the `recently_added` scope
+      #       column_name_six: ::Proc.new { "column_name = 'value'" }, # useful for complex scopes, you may pass any valid SQL scopes
+      #       column_name_seven: ::Proc.new { where(column_name: value) }, # anonymous scopes
+      #       todo_list(_id): nil # ranks items scoped to their respective todo lists, works with or without `(_id)`
+      #     end
+      #   end
+      #
       # @since 0.2.0
       # @scope class
       # @param [Hash] user_options options
@@ -26,6 +42,11 @@ module ActsAsRankedList
       # @option user_options [Float/Integer] :step_increment The value to use for spreading ranks
       # @option user_options [Boolean] :avoid_collisions Controls avoiding rank collisions
       # @option user_options [Symbol] :new_item_at Controls where to add new items
+      # @option user_options [Hash] :scopes Scopes ranked items based on a column, and optional value
+      #   * :any_key [String/Integer/Boolean/Float] Uses passed value in column <any_key> to scope items
+      #   * :any_key [Symbol] Uses passed value in column <any_key> to scope items, or a named scope
+      #   * :any_key [Proc] Calls passed block's value in column <any_key> to scope items, or an anonymous scope
+      #   * :any_key [NilClass] Scopes items to a relationship, by querying non-nil values in column <any_key> or <any_key_id>
       # @return [void]
       def acts_as_ranked_list(user_options = {})
         options = {
@@ -33,12 +54,13 @@ module ActsAsRankedList
           touch_on_update: true,
           step_increment: 1024,
           avoid_collisions: true,
-          new_item_at: :lowest
+          new_item_at: :lowest,
+          scopes: {}
         }
         options.update(user_options)
 
         ::ActsAsRankedList::ActiveRecord::PersistenceCallback.call(self)
-        ::ActsAsRankedList::ActiveRecord::RankColumn.call(self, options[:column], options[:touch_on_update], options[:step_increment], options[:avoid_collisions], options[:new_item_at])
+        ::ActsAsRankedList::ActiveRecord::RankColumn.call(self, options[:column], options[:touch_on_update], options[:step_increment], options[:avoid_collisions], options[:new_item_at], options[:scopes])
 
         include ::ActsAsRankedList::ActiveRecord::Service::InstanceMethods
         include ::ActsAsRankedList::ActiveRecord::SkipPersistence
@@ -82,11 +104,24 @@ module ActsAsRankedList
 
           return if rank_changed? == false
 
-          return unless current_rank && self.class.acts_as_ranked_list_query.where(
-            "#{self.class.quoted_rank_column_with_table_name} = #{current_rank}"
-          ).count >= 1
+          return unless current_rank
+
+          query_count = self.class.acts_as_ranked_list_query
+            .where("#{self.class.quoted_rank_column_with_table_name} = #{current_rank}")
+
+          self.class.instance_variable_get(:@grouped_scopes)&.each do |grouped_scope|
+            query_count = query_count.where(grouped_scope => self.send(grouped_scope))
+          end
+
+          query_count = query_count.count
 
-          self.class.spread_ranks
+          if query_count < 1
+            return
+          end
+
+          self.class.with_skip_persistence do
+            self.class.spread_ranks
+          end
         end
 
         def set_new_item_rank

data/lib/acts_as_ranked_list/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActsAsRankedList
-  VERSION = "0.2.1"
+  VERSION = "0.2.3"
 end

metadata

@@ -1,145 +1,139 @@
 --- !ruby/object:Gem::Specification
 name: acts_as_ranked_list
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.3
 platform: ruby
 authors:
 - Farbafe
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-04-21 00:00:00.000000000 Z
+date: 2023-12-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 6.0.3
     - - ">="
       - !ruby/object:Gem::Version
-        version: 6.0.3.6
+        version: 6.0.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 6.0.3
     - - ">="
       - !ruby/object:Gem::Version
-        version: 6.0.3.6
+        version: 6.0.3
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '13.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '13.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '3.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '3.0'
 - !ruby/object:Gem::Dependency
   name: standard
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.3'
 - !ruby/object:Gem::Dependency
   name: rspec-rails
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 5.1.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 5.1.2
 - !ruby/object:Gem::Dependency
   name: byebug
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 11.1.3
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 11.1.3
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 0.9.34
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 0.9.34
 - !ruby/object:Gem::Dependency
   name: redcarpet
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 3.6.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 3.6.0
 - !ruby/object:Gem::Dependency
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 1.6.2
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 1.6.2
 description: Orders ActiveRecord items by floating ranks for spaces in-between items.
@@ -159,6 +153,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- acts_as_ranked_list.gemspec
 - lib/acts_as_ranked_list.rb
 - lib/acts_as_ranked_list/active_record/active_record.rb
 - lib/acts_as_ranked_list/active_record/avoid_collisions.rb
@@ -192,7 +187,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
+rubygems_version: 3.3.7
 signing_key: 
 specification_version: 4
 summary: Orders ActiveRecord items by ranks. Influenced by gem ActsAsList.