acts_as_ranked_list 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c52097c9da44e29678359a1ea99ff7907e3fdb549cb98997b10a9aaed3819a09
+  data.tar.gz: cc599ce31fa0547848440e7ba55f233d8324016d864d5688368dbbdbc863af93
+SHA512:
+  metadata.gz: 146bf7c4e0f9d1ba563e90f577cdd2b2c136be125fed1513f08a7d77cd250089a5d135f42dedb1bbf50ad4a40cd5385cb24b7d53c7d9cbc6071eaee8aceec3e9
+  data.tar.gz: 274ad10fc900278dc84a5ba39ffaee17fe7412b8ea16b2f227d07abeea1c095b911315d8544be2ddcf558ea039fbdc51e3dc380ef782e493184493745b73b26b

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.standard.yml

@@ -0,0 +1,3 @@
+# For available configuration options, see:
+#   https://github.com/testdouble/standard
+ruby_version: 2.6

data/.yardopts

@@ -0,0 +1,2 @@
+-M redcarpet
+-m markdown

data/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+ 
+The format is based on [Keep a Changelog](http://keepachangelog.com/)
+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.0] - 2023-04-21
+
+- Adds gem documentation
+- Adds gem tests
+- Adds gem functionality to rank `::ActiveRecord` objects.
+  - Adds AvoidsCollisions
+  - Adds SkipPersistence
+  - Adds PersistenceCallback
+  - Adds RankColumn
+  - Adds Service
+- Adds Base error
+
+## [0.1.0] - 2023-04-11
+
+- Initial release

data/Gemfile

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in acts_as_ranked_list.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 YehyaRasayel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,292 @@
+# ActsAsRankedList
+
+This gem is based off of the [ActsAsList](https://github.com/brendon/acts_as_list) gem. It rewrites the gem using floating point position (or rank) for items. The benefit of using floating point ranks is the ability to insert an item inbetween items without updating the other items' positions.
+
+Also supports having a(n) (float/integer) step between ranks that achieves the same thing. Can also use a step <1.0 to rank more items than is allowed by a database's max float/integer column restrictions.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add acts_as_ranked_list
+
+or by adding `gem "acts_as_ranked_list"` to the Gemfile and running `bundle install`.
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install acts_as_ranked_list
+
+## Usage
+
+### Basic usage
+
+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
+    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:
+
+```
+item_a = MyModelName.create!
+item_a.increase_rank
+item_a.decrease_rank
+```
+
+You can get the current rank of the item by the following:
+
+```
+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
+item_b.current_rank # 2
+```
+
+Note that the list is viewed as ascending order of `rank, last updated at, id`. So `item_b` with rank 2 is lower in the list than `item_a` with rank 1.
+
+You may get the highest items in the list sorted by rank by the following methods:
+
+```
+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]
+```
+
+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:
+
+```
+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
+MyModelName.get_lowest_items(1) # ActiveRecord::Relation with results [my_new_item]
+MyModelName.get_lowest_items(2) # ActiveRecord::Relation with results [my_new_item, my_existing_item] # Note the order of the returned results
+MyModelName.get_highest_items(50000) # ActiveRecord::Relation with results [my_existing_item, my_new_item] # Note the number of requested results
+```
+
+### Advanced Usage
+
+For the next examples, each will be initialized to the following:
+
+```
+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
+end
+
+design_reusable_plastic_bag_graphic = TodoItem.create!(title: "Design the front and back graphic on the reusable plastic bag")
+exercise = TodoItem.create!(title: "Run for 8 miles")
+health_check = TodoItem.create!(title: "Drink lemon water")
+print_on_shirt = TodoItem.create!(title: "Print a prototype design on the shrit to check quality")
+# items and their priorities in ascending order: (the actual result is an array of the items, but the variable name and rank are shown here for simplicity)
+#   [["print_on_shirt" ... , 0.125], ["health_check" ... , 0.25], ["exercise" ... , 0.5], ["design_reusable_plastic_bag_graphic" ... , 1.0]]
+# the highest prioritised item is "print_on_shirt"
+# the lowest prioritised item is "design_reusable_plastic_bag_graphic"
+```
+
+### 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.
+
+```
+design_reusable_plastic_bag_graphic.lowest_item? # true
+design_reusable_plastic_bag_graphic.highest_item? # false
+print_on_shirt.highest_item? # true
+```
+
+#### Get higher or lower items
+
+You can get the higher/lower items by using the instance methods `get_higher_items` or `get_lower_items`:
+
+```
+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.
+
+```
+design_reusable_plastic_bag_graphic.get_higher_items(2, "ASC") # [["health_check", 0.25], ["exercise", 0.5]]
+```
+
+#### 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).
+
+```
+design_reusable_plastic_bag_graphic.is_ranked? # true
+```
+
+You may create a new item with nil rank as follows:
+
+```
+## this persists the record, but skips callbacks
+::TodoItem.with_skip_persistence { ::TodoItem.create!(rank: nil) }
+```
+
+#### Move rank relative to another item
+
+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:
+
+```
+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.
+
+```
+design_reusable_plastic_bag_graphic.set_rank_above(TodoItem.get_highest_items(1).first)
+```
+
+#### Persistence and persistence callbacks
+
+Each model with the `acts_as_ranked_list` has class methods to skip persistence to the database, and persistence callbacks.
+
+Skipping persistence is useful if you want to mass update items, and persist once at the end. Persistence callbacks is useful for hooking into the life cycle of the updated item with regards to its rank, for example to send a webhook to all subscribers notifying them of an updated rank.
+
+You can use the class method `with_skip_persistence` as follows:
+
+```
+TodoItem.with_skip_persistence do
+    design_reusable_plastic_bag_graphic.update(rank: 20.3)
+    exercise.update(rank: 5.2)
+    health_check.update(rank: 7.1)
+    print_on_shirt.update(rank: 92.1)
+end
+::TodoItem.bulk_import!(
+    [design_reusable_plastic_bag_graphic, exercise, health_check, print_on_shirt],
+    on_duplicate_key_update: {
+        conflict_target: [:id],
+        columns: [:priority, :updated_at]
+    }
+) # uses the `activerecord_import` gem, or any other bulk update method to mass save changes to the database in 1 query
+```
+
+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.
+
+```
+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
+    health_check.set_rank_below(print_on_shirt)
+    print_on_shirt.set_rank_below(design_reusable_plastic_bag_graphic)
+
+    instance_of_other_model = FootballTeam.create(name: "MineerPul")
+    instance_of_other_model.decrease_rank
+end
+::TodoItem.bulk_import!(
+    [design_reusable_plastic_bag_graphic, exercise, health_check, print_on_shirt],
+    on_duplicate_key_update: {
+        conflict_target: [:id],
+        columns: [:priority, :updated_at]
+    }
+) # uses the `activerecord_import` gem, or any other bulk update method to mass save changes to the database in 1 query
+
+::FootballTeam.bulk_import!(
+    [instance_of_other_model],
+    on_duplicate_key_update: {
+        conflict_target: [:id],
+        columns: [:rank, :updated_at]
+    }
+)
+```
+
+#### Avoiding collisions
+
+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:
+
+```
+# disallows collisions
+TodoItem.with_avoid_collisions(true) do # do spread ranks on collisions
+    TodoItem.find(1).update(rank: 1)
+    ... # you may update more than one record too
+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]]
+```
+
+```
+# allows collisions
+TodoItem.with_avoid_collisions(false) do # do not spread ranks on collisions
+    TodoItem.find(1).update(rank: 1)
+end # items with their new ranks [["health_check", 0.25], ["exercise", 0.5], ["print_on_shirt", 1.0], ["design_reusable_plastic_bag_graphic", 1.0]]
+```
+
+#### Spread ranks
+
+You can spread ranks so that the difference between each rank and the next is set to the `step_increment`. This is useful for:
+
+- 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+`:
+
+```
+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)
+
+To spread ranks:
+
+```
+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]]
+```
+
+## Things to beware of
+
+### Ranking more items in a databse than the max integer column
+
+Imagine the scenario where you have 199 records to rank, and you must rank them in a `decision/numeric` column that allows 2 digits before the decimal point, and 2 digits after the decimal point. I.e the max number that can be stored is `99.99`.
+
+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
+    acts_as_ranked_list step_increment: 0.5
+end
+
+crammed_todo_items = []
+CrammedTodoItem.with_skip_persistence do
+    199.times { crammed_todo_items << CrammedTodoItem.create }
+end
+
+CrammedTodoItem.bulk_import!(crammed_todo_items) # persist 199 records in a mass insert method using gem `activerecord-import` or other method
+
+CrammedTodoItem.spread_ranks # ensures every step is 0.5
+
+CrammedTodoItem.get_highest_items.pluck(:rank) # [0.50 .. 99.50]
+```
+
+### Floating point precision and rounding, and max float/integer column overflow
+
+Not all software can handle the precision handled by the database. The weakest link will cause issues to the entire flow of ranking items using floating-point precision. You may wish to convert to string and back to float if you need to. This **must** be done by the database layer as you'd have already lost precision if you let any other layer cast the values.
+
+An alternative solution is to use a high `step_increment` to not get into rounding errors. This also brings its own problems of max integer overflow, but that is usually easier to plan in advance for, and does not fail silently. If you do this, it is best to use a large number that is a power of 2. This helps reduce the number of collisions as much as possible.
+
+Some database services do not fail loudly and will persist a rounded or incorrect value altogether. You may set up an `::ActiveRecord` validation on the model to check for the precision before saving, and raise your own validation error, and handle recalibrating ranks.
+
+### Performance
+
+For best results, it is recommended to benchmark and compare with real life scenarios. Depending on your use case, different strategies may be faster. Using a large `step_increment` that's a power of 2 in an integer-based column (i.e no decimals) may be faster. The gem will continue to work as expected, but there may be more frequent collisions, which would be handled automatically but may slow down performance. So experiment and kindly share your learnings :pray:. You should also check other ruby gems that rank and sort `::ActiveRecord` models.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rspec ./spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+You may also run `yardoc` to build the docs locally. And `yard server` to serve the built docs.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/Farbafe/acts_as_ranked_list.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "standard/rake"
+
+task default: %i[spec standard]

data/lib/acts_as_ranked_list/active_record/active_record.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+::ActiveSupport.on_load :active_record do
+  extend ::ActsAsRankedList::ActiveRecord::Service
+end

data/lib/acts_as_ranked_list/active_record/avoid_collisions.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module ActsAsRankedList #:nodoc:
+  module ActiveRecord #:nodoc:
+    module AvoidCollisions # Refer to {AvoidCollisions::ClassMethods} for docs.
+
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        # Pass a block to this method to avoid collisions to an `::ActiveRecord`
+        # model's table. You may pass a boolean argument to change the behaviour.
+        #
+        # @example with an `::ActiveRecord` model of the name `TodoItem`:
+        #   TodoItem.with_avoid_collisions do
+        #     TodoItem.find(4).update(rank: 200)
+        #     TodoItem.find(5).update(rank: 200)
+        #   end
+        # @since 0.2.0
+        # @scope class
+        # @param [Array<Class>] avoid_collisions argument to avoid or allow collisions
+        # @yield the block to execute with changes to the instances
+        # @return [void]
+        def with_avoid_collisions(avoid_collisions = true, &blk)
+          AvoidCollisions.with_applied_klasses(self, avoid_collisions) do
+            yield
+          end
+        end
+
+        private
+
+        def active_record_objects?(klasses)
+          klasses.all? { |klass| klass.ancestors.include?(::ActiveRecord::Base) }
+        end
+      end
+
+      class << self
+        def with_applied_klasses(caller_class, avoid_collisions, &blk)
+          original_avoid_collisions = caller_class.avoid_collisions
+          caller_class.avoid_collisions = avoid_collisions
+          yield
+        ensure
+          caller_class.avoid_collisions = original_avoid_collisions
+        end
+
+        def applied_to?(klass)
+          klass.avoid_collisions
+        end
+      end
+
+      private
+
+      def avoid_collisions?
+        AvoidCollisions.applied_to?(self.class)
+      end
+    end
+  end
+end

data/lib/acts_as_ranked_list/active_record/persistence_callback.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module ActsAsRankedList #:nodoc:
+  module ActiveRecord #:nodoc:
+    module PersistenceCallback
+      # @!method ranked_list_before_validation_callback
+      #   Callback on `::ActiveRecord` before validation. Skipped with {SkipPersistence}
+      #   @!scope class
+      #   @since 0.2.0
+
+      # @!method ranked_list_before_destroy_callback
+      #   Callback on `::ActiveRecord` before destroy. Skipped with {SkipPersistence}
+      #   @!scope class
+      #   @since 0.2.0
+
+      # @!method ranked_list_after_destroy_callback
+      #   Callback on `::ActiveRecord` after destroy. Skipped with {SkipPersistence}
+      #   @!scope class
+      #   @since 0.2.0
+
+      # @!method ranked_list_before_update_callback
+      #   Callback on `::ActiveRecord` before update. Skipped with {SkipPersistence}
+      #   @!scope class
+      #   @since 0.2.0
+
+      # @!method ranked_list_after_update_callback
+      #   Callback on `::ActiveRecord` after update. Skipped with {SkipPersistence}
+      #   @!scope class
+      #   @since 0.2.0
+
+      # @!method ranked_list_after_save_callback
+      #   Callback on `::ActiveRecord` after save.
+      #   @!scope class
+      #   @since 0.2.0
+
+      # @!method ranked_list_before_create_callback
+      #   Callback on `::ActiveRecord` before create. Skipped with {SkipPersistence}.
+      #   @!scope class
+      #   @since 0.2.0
+
+      # Sets the callback handlers for {ActsAsRankedList}. Used internally.
+      # You may use the callback methods if you want to add your handlers.
+      # Call super at the end of your callback handlers. Do **not** update records
+      # within an update callback.
+      def self.call(caller_class)
+        caller_class.class_eval do
+          before_validation :ranked_list_before_validation_callback, unless: :skip_persistence?
+
+          before_destroy :ranked_list_before_destroy_callback, unless: :skip_persistence?
+          after_destroy :ranked_list_after_destroy_callback, unless: :skip_persistence?
+
+          before_update :ranked_list_before_update_callback, unless: :skip_persistence?
+          after_update :ranked_list_after_update_callback, unless: :skip_persistence?
+
+          after_save :ranked_list_after_save_callback
+
+          before_create :ranked_list_before_create_callback, unless: :skip_persistence?
+        end
+      end
+    end
+  end
+end

data/lib/acts_as_ranked_list/active_record/rank_column.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+module ActsAsRankedList #:nodoc:
+  module ActiveRecord #: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)
+        caller_class.class_eval do
+
+          private
+
+          define_singleton_method :new_item_at do
+            new_item_at
+          end
+
+          define_singleton_method :step_increment do
+            step_increment
+          end
+
+          define_singleton_method :avoid_collisions= do |avoid_collisions_input|
+            @avoid_collisions = avoid_collisions_input
+          end
+          @avoid_collisions = avoid_collisions
+
+          define_singleton_method :avoid_collisions do
+            @avoid_collisions
+          end
+
+          define_singleton_method :acts_as_ranked_list_query do
+            default_scoped.unscope(:select, :where)
+          end
+
+          define_singleton_method :quoted_rank_column do
+            @_quoted_rank_column ||= connection.quote_column_name(rank_column)
+          end
+
+          define_singleton_method :quoted_rank_column_with_table_name do
+            @_quoted_rank_column_with_table_name ||= "#{caller_class.quoted_table_name}.#{quoted_rank_column}"
+          end
+
+          define_singleton_method :order_by_columns do |order = "ASC"|
+            @order_by_columns ||= {}
+            @order_by_columns[order] ||= <<~ORDER_BY_COLUMNS.squish
+              #{
+                [ quoted_rank_column,
+                  *quoted_timestamp_attributes_for_update_in_model,
+                  primary_key
+                ].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)
+          end
+
+          define_singleton_method :with_touch do
+            touch_record if touch_on_update
+          end
+
+          define_singleton_method :quoted_timestamp_attributes_for_update_in_model do
+            @_quoted_timestamp_attributes_for_update_in_model ||= timestamp_attributes_for_update_in_model.map do |attribute|
+              connection.quote_column_name(attribute)
+            end
+          end
+
+          define_singleton_method :touch_record do
+            cached_quoted_now = quoted_current_time_from_proper_timezone
+
+            quoted_timestamp_attributes_for_update_in_model.map do |attribute|
+              ", #{attribute} = #{cached_quoted_now}"
+            end.join
+          end
+
+          define_singleton_method :quoted_current_time_from_proper_timezone do
+            connection.quote(connection.quoted_date(current_time_from_proper_timezone))
+          end
+
+          define_singleton_method :get_highest_items do |limit = 0|
+            query = acts_as_ranked_list_query.order(order_by_columns)
+
+            return query if limit == 0
+            
+            query.limit(limit)
+          end
+
+          define_singleton_method :get_lowest_items do |limit = 0|
+            query = acts_as_ranked_list_query.order(order_by_columns("DESC"))
+
+            return query if limit == 0
+            
+            query.limit(limit)
+          end
+        end
+
+        caller_class.class_eval do
+          define_method :rank_column do
+            rank_column
+          end
+
+          define_method :"#{rank_column}=" do |rank|
+            self[rank_column] = rank
+            @rank_changed = true
+          end
+
+          define_method :current_rank do
+            self[rank_column]
+          end
+
+          define_method :rank_changed? do
+            @rank_changed
+          end
+
+          define_method :is_ranked? do
+            self[rank_column].present?
+          end
+
+          define_method :swap_rank_with do |item|
+            temp_rank = current_rank
+            with_persistence([self, item]) do
+              self[rank_column] = item.current_rank
+              item[rank_column] = temp_rank
+            end
+          end
+
+          define_method :set_rank_between do |item_a, item_b|
+            set_rank_below(item_a)
+          end
+
+          define_method :set_rank_above do |item|
+            higher_items = get_higher_items(2, "DESC", item.current_rank, true, true)
+            padded_array = pad_array(higher_items.pluck(rank_column), 0)
+            new_rank = padded_array.sum / 2
+
+            with_persistence do
+              self[rank_column] = new_rank
+            end
+          end
+
+          define_method :set_rank_below do |item|
+            # effectively the same as, without the padding of arrays
+            # sql = <<~SQL.squish
+            #   with CTE AS (
+            #     SELECT DISTINCT #{self.class.quoted_rank_column_with_table_name} AS dis
+            #     FROM #{caller_class.quoted_table_name}
+            #     WHERE (#{self.class.quoted_rank_column_with_table_name} >= #{item.current_rank}::numeric)
+            #     GROUP BY #{self.class.quoted_rank_column_with_table_name}
+            #     ORDER BY #{self.class.quoted_rank_column_with_table_name}
+            #     LIMIT 2
+            #   )
+            #   SELECT AVG(CTE.dis)
+            #   FROM CTE
+            # SQL
+            # new_rank = ::ActiveRecord::Base.connection.execute(sql).to_a.first.values.first
+
+            lower_items = get_lower_items(2, "ASC", item.current_rank, true, true)
+            padded_array = pad_array(lower_items.pluck(rank_column))
+            new_rank = padded_array.sum / 2
+
+            with_persistence do
+              self[rank_column] = new_rank
+            end
+          end
+
+          define_method :increase_rank do |count = 1|
+            higher_items = get_higher_items(count + 1, "DESC")
+            return if higher_items.blank?
+
+            padded_array = pad_array(higher_items.pluck(rank_column), 0)
+            new_rank = padded_array.sum / 2
+
+            with_persistence do
+              self[rank_column] = new_rank
+            end
+          end
+
+          define_method :decrease_rank do |count = 1|
+            lower_items = get_lower_items(count + 1, "ASC")
+            return if lower_items.blank?
+
+            padded_array = pad_array(lower_items.pluck(rank_column))
+            new_rank = padded_array.sum / 2
+
+            with_persistence do
+              self[rank_column] = new_rank
+            end
+          end
+
+          define_method :get_higher_items do |limit = 0, order = "DESC", rank = nil, distinct = false, include_self_rank = false|
+            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))
+
+            query = query.distinct(self.class.quoted_rank_column) if distinct
+
+            return query if limit == 0
+
+            query.limit(limit)
+          end
+
+          define_method :get_lower_items do |limit = 0, order = "ASC", rank = nil, distinct = false, include_self_rank = false|
+            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))
+
+            query = query.distinct(self.class.quoted_rank_column) if distinct
+
+            return query if limit == 0
+
+            query.limit(limit)
+          end
+
+          define_method :highest_item? do
+            self.class.get_highest_items(1).first == self
+          end
+
+          define_method :lowest_item? do
+            self.class.get_lowest_items(1).first == self
+          end
+
+          private
+
+          define_method :with_persistence do |items = [self], &blk|
+            blk.call
+
+            items.each(&:save!) unless skip_persistence?
+          end
+
+          define_method :pad_array do |array, value = nil, size = 2|
+            current_array_value = array[0] || self.class.step_increment
+            value ||= current_array_value + self.class.step_increment
+            array + ::Array.new(size - array.size, value)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/acts_as_ranked_list/active_record/service.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module ActsAsRankedList
+  module ActiveRecord #:nodoc:
+    module Service
+
+      # Add `acts_as_ranked_list` to an `::ActiveRecord` model to use this gem.
+      # Please refer to the {file:README.md} for complete usage and examples.
+      #
+      # @example with an `::ActiveRecord` model of the name `TodoItem`. Works when inheriting from `::ApplicationRecord`.
+      #   class TodoItem << ::ActiveRecord::Base
+      #     acts_as_ranked_list
+      #   end
+      #
+      # @example when changing default options
+      #   class TodoItem << ::ActiveRecord::Base
+      #     acts_as_ranked_list column: "position", touch_on_update: false, step_increment: 0.5, avoid_collisions: false, new_item_at: :highest
+      #   end
+      #
+      # @since 0.2.0
+      # @scope class
+      # @param [Hash] user_options options
+      # @option user_options [String] :column The column name to use for ranking
+      # @option user_options [Boolean] :touch_on_update Controls updating table's columns
+      #   updated fields on any write operation
+      # @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
+      # @return [void]
+      def acts_as_ranked_list(user_options = {})
+        options = {
+          column: "rank",
+          touch_on_update: true,
+          step_increment: 1024,
+          avoid_collisions: true,
+          new_item_at: :lowest
+        }
+        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])
+
+        include ::ActsAsRankedList::ActiveRecord::Service::InstanceMethods
+        include ::ActsAsRankedList::ActiveRecord::SkipPersistence
+        include ::ActsAsRankedList::ActiveRecord::AvoidCollisions
+      end
+
+      module InstanceMethods
+        def ranked_list_before_validation_callback
+          nil
+        end
+
+        def ranked_list_before_destroy_callback
+          nil
+        end
+
+        def ranked_list_after_destroy_callback
+          nil
+        end
+
+        def ranked_list_before_update_callback
+          update_ranks
+        end
+
+        def ranked_list_after_update_callback
+          nil
+        end
+
+        def ranked_list_after_save_callback
+          @rank_changed = nil
+        end
+
+        def ranked_list_before_create_callback
+          set_new_item_rank
+          update_ranks
+        end
+
+        private
+
+        def update_ranks
+          return unless avoid_collisions?
+
+          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
+
+          self.class.spread_ranks
+        end
+
+        def set_new_item_rank
+          return if current_rank.present?
+
+          case self.class.new_item_at
+          when :highest
+            highest_item_rank = self.class.get_highest_items(1).first&.current_rank || self.class.step_increment
+            self[rank_column] = [highest_item_rank, 0].sum / 2
+          when :lowest
+            lowest_item_rank = self.class.get_lowest_items(1).first&.current_rank || self.class.step_increment
+            self[rank_column] = [lowest_item_rank, lowest_item_rank + self.class.step_increment].sum / 2
+          end
+        end
+      end
+    end
+  end
+end

data/lib/acts_as_ranked_list/active_record/skip_persistence.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module ActsAsRankedList #:nodoc:
+  module ActiveRecord #:nodoc:
+    module SkipPersistence # Refer to {SkipPersistence::ClassMethods} for docs.
+
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        # Pass a block to this method to prevent persisting `::ActiveRecord` updates and 
+        # callbacks. You may pass an array of classes to prevent persisting. These
+        # `::ActiveRecord` models _must_ include the `acts_as_ranked_list` concern.
+        #
+        # @example with an `::ActiveRecord` model of the name `TodoItem`:
+        #   TodoItem.with_skip_persistence { TodoItem.find(4).increase_rank }
+        # @since 0.2.0
+        # @scope class
+        # @param [Array<Class>] klasses array of klasses to prevent persisting
+        # @yield the block to execute with changes to the instances
+        # @raise [ArgumentError] raised if optional klasses argument is not an array of
+        #   `::ActiveRecord` objects 
+        # @return [void]
+        def with_skip_persistence(klasses = [], &blk)
+          raise ::ArgumentError unless klasses.is_a?(Array)
+
+          klasses << self
+
+          raise ::ArgumentError unless active_record_objects?(klasses)
+
+          SkipPersistence.with_applied_klasses(klasses) do
+            yield
+          end
+        end
+
+        private
+
+        def active_record_objects?(klasses)
+          klasses.all? { |klass| klass.ancestors.include?(::ActiveRecord::Base) }
+        end
+      end
+
+      class << self
+        def with_applied_klasses(klasses, &blk)
+          klasses.map {|klass| add_klass(klass)}
+          yield
+        ensure
+          klasses.map {|klass| remove_klass(klass)}
+        end
+
+        def applied_to?(klass)
+          !(klass.ancestors & extracted_klasses.keys).empty?
+        end
+
+        private
+
+        def extracted_klasses
+          ::Thread.current[:acts_as_ranked_list_skip_persistence] ||= {}
+        end
+
+        def add_klass(klass)
+          extracted_klasses[klass] = 0 unless extracted_klasses.key?(klass)
+          extracted_klasses[klass] += 1
+        end
+
+        def remove_klass(klass)
+          extracted_klasses[klass] -= 1
+          extracted_klasses.delete(klass) if extracted_klasses[klass] <= 0
+        end
+      end
+
+      private
+
+      def skip_persistence?
+        SkipPersistence.applied_to?(self.class)
+      end
+    end
+  end
+end

data/lib/acts_as_ranked_list/errors/base.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module ActsAsRankedList
+  module Errors
+    class Base < ::StandardError # Any gem-specific errors will be inheriting this base error.
+    end
+  end
+end

data/lib/acts_as_ranked_list/version.rb

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

data/lib/acts_as_ranked_list.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "acts_as_ranked_list/active_record/active_record"
+require "acts_as_ranked_list/active_record/service"
+require "acts_as_ranked_list/active_record/skip_persistence"
+require "acts_as_ranked_list/active_record/persistence_callback"
+require "acts_as_ranked_list/active_record/rank_column"
+require "acts_as_ranked_list/active_record/avoid_collisions"

data/sig/acts_as_ranked_list.rbs

@@ -0,0 +1,4 @@
+module ActsAsRankedList
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,199 @@
+--- !ruby/object:Gem::Specification
+name: acts_as_ranked_list
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Farbafe
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2023-04-21 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
+  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
+- !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.
+  Influenced by gem ActsAsList. The floating rank allows inserting items at arbitrary
+  positions without reordering items. Thus, reducing the number of WRITE queries.
+email:
+- yehyapal@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".standard.yml"
+- ".yardopts"
+- CHANGELOG.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- 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
+- lib/acts_as_ranked_list/active_record/persistence_callback.rb
+- lib/acts_as_ranked_list/active_record/rank_column.rb
+- lib/acts_as_ranked_list/active_record/service.rb
+- lib/acts_as_ranked_list/active_record/skip_persistence.rb
+- lib/acts_as_ranked_list/errors/base.rb
+- lib/acts_as_ranked_list/version.rb
+- sig/acts_as_ranked_list.rbs
+homepage: https://github.com/Farbafe/acts_as_ranked_list
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/Farbafe/acts_as_ranked_list
+  source_code_uri: https://github.com/Farbafe/acts_as_ranked_list/blob/master
+  changelog_uri: https://github.com/Farbafe/acts_as_ranked_list/blob/master/CHANGELOG.md
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.6
+signing_key: 
+specification_version: 4
+summary: Orders ActiveRecord items by ranks. Influenced by gem ActsAsList.
+test_files: []