positioning 0.4.10 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ecb51b68f80bde257ed294934fd122a1fabff3acb3438767253afb614664d318
-  data.tar.gz: c688039c633220e0afb1b640375fed1dffaf312cd5e418eaa62fb4c5b60b0779
+  metadata.gz: 7677909862f7df18c0550419eeb1998e35fbf50cc0a9d6635e4d06edce088ea6
+  data.tar.gz: f5a9a1b51f11f1dd60433cb6c29e651ce29ad80cd2babaed4e4b01cde1af253d
 SHA512:
-  metadata.gz: c588024c1fb254446fd782d03c04c57363bf49cb85911ecee07d525797b31a40b7f0b7389f71a372dcd23e084f234dfdb4d613242e5f88dc3ba382abf882f028
-  data.tar.gz: 640dd4e8e75db84a9053e54f57066ea4ab5f80216b84e5754b953851056f9409d0dc979f3d6a7038245e05b35b0f1e390153e5567aab6fe9f4a10fbde964e475
+  metadata.gz: 8ad652e8ba47212719b599cee9209237a9defe9dea61b6364b8c5f501541fb17dea37e2d6476c13aa1846ee5a086dc842135f15899bc62f13acd67e874726dfc
+  data.tar.gz: 33da3275bb9b4bdceccf5c2092a8523cd9813eb3b4ef542acc801aacb4df51946f35dc83f124a2026a43bae6399c76e1b5c081806c31fdf635c1fd5d7ee96378

data/.standard.yml

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

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 ## [Unreleased]
 
+## [0.5.0] - 2026-11-11
+
+- Require Active Record 7.2+ and Ruby 3.3+, matching what's tested. Bundler will keep apps on older versions on 0.4.10.
+- `prior_*` and `subsequent_*` now return `nil` (rather than raising) for records without a position.
+- A position writer defined in the model now composes with positioning's via `super`.
+- `belongs_to` scopes are now recognised even when declared after `positioned` (e.g. in a concern included later).
+- Don't write anything when an assigned position doesn't change. `updated_at` is no longer bumped and `saved_change_to_position?` is false in that case.
+- Fix a destroy halted by a callback declared after `positioned` (e.g. `dependent: :restrict_with_error`), inside a transaction that's already open, leaving the record at position 0 and the records after it moved up.
+- Add tests for behaviour that mutation testing showed was untested.
+- Document caveats around validating the position column, halting callbacks, operations that bypass positioning, and the limits of row locking.
+
 ## [0.4.10] - 2026-11-09
 
 - Fix MySQL deadlocks when adding a record to the end of a list while another transaction holds the list's first row and then waits on the scope lock, such as a `touch: true` chain from a child. When nothing needs to move, we no longer run the query that locked that row.

data/README.md

@@ -40,6 +40,8 @@ If you have a polymorphic `belongs_to` then you'll want to add the type column t
 
 The Positioning gem uses `0` and negative integers to rearrange the lists it manages so don't add database validations to restrict the usage of these. You are also restricted from using `0` and negative integers as position values. If you try, the position value will become `1`. If you try to set an explicit position value that is greater than the next available list position, it will be rounded down to that value.
 
+Likewise, don't validate the position column in your model (e.g. `validates :position, presence: true`). A new record doesn't have a position until one is assigned in a `before_create` callback, which runs after validation.
+
 ### Declaring Positioning
 
 To declare that your model should keep track of the position of its records you can use the `positioned` method. Here are some examples:
@@ -134,6 +136,8 @@ To assign a specific position when creating or updating a record you can simply
 
 Position parameters can be strings or symbols, so you can provide them from the browser.
 
+If you define your own writer for the position column in your model (e.g. `position=`), call `super` to pass the value on to positioning.
+
 Here are some examples:
 
 ##### Creating
@@ -280,10 +284,22 @@ If you must position child models separately, scope their position by the `type`
 positioned on: [:type]
 ```
 
+#### Callbacks
+
+Positions are rearranged in `before_create` and `before_update` callbacks. Declare `positioned` after any `before_create` or `before_update` callbacks of your own that might halt the save (e.g. with `throw :abort`). Otherwise, if the save runs inside a transaction that's already open and your code carries on after `save` returns `false`, the outer transaction commits with the other records in the list already moved to make room for a change that didn't happen. Destroys don't need this, since the records after a destroyed record are only moved up once it has actually been destroyed.
+
+Other records in the list are moved with `update_all`, so their callbacks don't run and their `updated_at` doesn't change. If you cache list items, consider `belongs_to :list, touch: true` so that the parent's `updated_at` (and so its cache key) changes whenever one of its items is saved or destroyed.
+
+#### Bypassing Positioning
+
+Positioning works through model callbacks, so anything that skips them skips positioning too: `insert_all`, `upsert_all`, `update_all`, `update_column(s)`, `delete`, `delete_all`, and associations declared with `dependent: :delete_all` or `dependent: :nullify`. (`dependent: :delete_all` on the scope's parent is fine, since the whole list gets deleted with it.) If you use these to change positions or scopes, heal the position column afterwards.
+
 ## Concurrency
 
 The queries that this gem runs (especially those that seek the next position integer available) are vulnerable to race conditions. To this end, we lock the scope records to ensure that our model callbacks that determine and assign positions run sequentially. Previously we used an Advisory Lock for this purpose but this was difficult to test and a bit overkill in most situations. Where a scope doesn't exist, we lock all the records in the table.
 
+Locking a parent record takes a single row lock and works even when the list is empty, so where you can, scope on a `belongs_to` association. When we lock the records in a scope instead, there's nothing to lock in an empty list, so two transactions adding the first records to the same list at the same time can both find it empty and choose the same position. With a unique index on your scope and position columns, the second insert fails with `ActiveRecord::RecordNotUnique`. On MySQL, two transactions locking rows in the same list can also occasionally deadlock under heavy contention. MySQL then rolls back one of them and Rails raises `ActiveRecord::Deadlocked`. In either case you can retry the failed transaction. Note that `NULL` values never conflict in a unique index, so if part of your scope can be `NULL` (e.g. the root of a tree), index a generated column such as `coalesce(parent_id, 0)` instead.
+
 **Please Note SQLite Users:** Row locking isn't supported by SQLite. Since writes are non-concurrent by default, the worst you'll probably see are errors about the database being locked under high load.
 
 If you have any concerns or improvements please file a GitHub issue.

data/lib/positioning/healer.rb

@@ -17,7 +17,6 @@ module Positioning
             if associated_records.any?
               associated_records.each(&:lock!)
             else
-              # Relation#lock! only flags the relation, it doesn't run a query
               @model.where(scope_record.slice(*scope_columns)).lock.ids
             end
 
@@ -46,9 +45,6 @@ module Positioning
       @model.primary_key
     end
 
-    # Records are first parked on distinct values below anything currently in use (and below 0),
-    # then flipped into 1..n in one statement, so a unique index on the position column can't be
-    # violated part way through.
     def sequence(scope)
       ids = scope.reorder(@order).order(*Array(primary_key)).pluck(*Array(primary_key))
       return if ids.empty?

data/lib/positioning/mechanisms.rb

@@ -6,17 +6,16 @@ module Positioning
     end
 
     def prior
-      positioning_scope.where(@column => position - 1).first
+      positioning_scope.where(@column => position - 1).first unless position.nil?
     end
 
     def subsequent
-      positioning_scope.where(@column => position + 1).first
+      positioning_scope.where(@column => position + 1).first unless position.nil?
     end
 
     def create_position
       lock_positioning_scope!
 
-      # A column default isn't a requested position. Only an assigned value is.
       clear_position unless position_changed?
 
       solidify_position
@@ -28,13 +27,16 @@ module Positioning
       return unless positioning_scope_changed? || position_changed?
 
       lock_positioning_scope!
+      position_was = self.position_was
 
       clear_position if positioning_scope_changed? && !position_changed?
 
       solidify_position
+
+      return forget_position_change if staying_put?
+
       move_out_of_the_way
 
-      # A record without a position doesn't occupy a slot, so there's no gap to close
       if position_was.nil?
         expand(positioning_scope, position..)
       elsif positioning_scope_changed?
@@ -48,9 +50,13 @@ module Positioning
     end
 
     def destroy_position
-      unless destroyed_via_positioning_scope?
-        lock_positioning_scope!
+      return yield if destroyed_via_positioning_scope?
+
+      lock_positioning_scope!
+      position_was = self.position_was
+      positioning_scope = self.positioning_scope
 
+      if yield
         move_out_of_the_way
         contract(positioning_scope, (position_was + 1)..) unless position_was.nil?
       end
@@ -62,27 +68,16 @@ module Positioning
       @positioned.class.base_class
     end
 
-    def with_connection
-      if base_class.respond_to? :with_connection
-        base_class.with_connection do |connection|
-          yield connection
-        end
-      else
-        yield base_class.connection
-      end
-    end
-
     def primary_key
       base_class.primary_key
     end
 
     def quoted_column
-      with_connection do |connection|
+      base_class.with_connection do |connection|
         connection.quote_table_name_for_assignment base_class.table_name, @column
       end
     end
 
-    # The record's row as it is in the database, regardless of default scopes or in-memory key changes
     def record_scope
       base_class.unscoped.where primary_key => [@positioned.id_in_database]
     end
@@ -109,12 +104,18 @@ module Positioning
       @position_was = record_scope.pick(@column)
     end
 
+    def staying_put?
+      !positioning_scope_changed? && position == position_was
+    end
+
+    def forget_position_change
+      @positioned.clear_attribute_changes [@column]
+    end
+
     def move_out_of_the_way
-      position_was # Memoize the original position before changing it
       record_scope.update_all @column => 0
     end
 
-    # Skip the second query if nothing moved, as MySQL would still lock the scope's first row to find no matches
     def expand(scope, range)
       if scope.where(@column => range).update_all("#{quoted_column} = #{quoted_column} * -1").positive?
         scope.where(@column => ..-1).update_all "#{quoted_column} = #{quoted_column} * -1 + 1"

data/lib/positioning/version.rb

@@ -1,3 +1,3 @@
 module Positioning
-  VERSION = "0.4.10"
+  VERSION = "0.5.0"
 end

data/lib/positioning.rb

@@ -4,6 +4,7 @@ require_relative "positioning/healer"
 
 require "active_support/concern"
 require "active_support/lazy_load_hooks"
+require "json"
 
 module Positioning
   class Error < StandardError; end
@@ -15,7 +16,29 @@ module Positioning
 
     class_methods do
       def positioning_columns
-        @positioning_columns ||= {}
+        return @positioning_columns if @positioning_columns
+
+        resolved = true
+
+        scopes = (@positioning_scopes || {}).transform_values do |scope_components|
+          {scope_columns: [], scope_associations: []}.tap do |scope|
+            scope_components.each do |scope_component|
+              reflection = reflections[scope_component]
+
+              if reflection&.belongs_to?
+                scope[:scope_columns].concat Array(reflection.foreign_key)
+                scope[:scope_columns] << reflection.foreign_type if reflection.polymorphic?
+                scope[:scope_associations] << reflection.name
+              else
+                resolved &&= column_names.include?(scope_component)
+                scope[:scope_columns] << scope_component
+              end
+            end
+          end
+        end
+
+        @positioning_columns = scopes if resolved
+        scopes
       end
 
       def positioned(on: [], column: :position)
@@ -24,36 +47,29 @@ module Positioning
         end
 
         column = column.to_sym
+        @positioning_scopes ||= {}
 
-        if positioning_columns.key? column
-          raise Error.new "The column `#{column}` has already been used by the scope `#{positioning_columns[column]}`."
+        if @positioning_scopes.key? column
+          raise Error.new "The column `#{column}` has already been used by the scope `#{@positioning_scopes[column]}`."
         else
-          positioning_columns[column] = {scope_columns: [], scope_associations: []}
-
-          Array.wrap(on).each do |scope_component|
-            scope_component = scope_component.to_s
-            reflection = reflections[scope_component]
-
-            if reflection&.belongs_to?
-              positioning_columns[column][:scope_columns].concat Array(reflection.foreign_key)
-              positioning_columns[column][:scope_columns] << reflection.foreign_type if reflection.polymorphic?
-              positioning_columns[column][:scope_associations] << reflection.name
-            else
-              positioning_columns[column][:scope_columns] << scope_component
-            end
-          end
+          @positioning_scopes[column] = Array.wrap(on).map(&:to_s)
+          @positioning_columns = nil
 
           define_method(:"prior_#{column}") { Mechanisms.new(self, column).prior }
           define_method(:"subsequent_#{column}") { Mechanisms.new(self, column).subsequent }
 
-          redefine_method(:"#{column}=") do |position|
-            send :"#{column}_will_change!"
-            super(position)
+          writer = Module.new do
+            define_method(:"#{column}=") do |position|
+              attribute_will_change!(column.to_s)
+              super(position)
+            end
           end
 
+          include writer
+
           before_create { Mechanisms.new(self, column).create_position }
           before_update { Mechanisms.new(self, column).update_position }
-          before_destroy { Mechanisms.new(self, column).destroy_position }
+          around_destroy { |positioned, block| Mechanisms.new(positioned, column).destroy_position(&block) }
 
           define_singleton_method(:"heal_#{column}_column!") do |order = column|
             Healer.new(base_class, column, order).heal

data/positioning.gemspec

@@ -9,7 +9,7 @@ Gem::Specification.new do |spec|
   spec.summary = "Simple positioning for Active Record models."
   spec.homepage = "https://github.com/brendon/positioning"
   spec.license = "MIT"
-  spec.required_ruby_version = ">= 3.0.0"
+  spec.required_ruby_version = ">= 3.3.0"
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = "https://github.com/brendon/positioning"
@@ -28,8 +28,8 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   # Uncomment to register a new dependency of your gem
-  spec.add_dependency "activesupport", ">= 6.1"
-  spec.add_dependency "activerecord", ">= 6.1"
+  spec.add_dependency "activesupport", ">= 7.2"
+  spec.add_dependency "activerecord", ">= 7.2"
 
   # For more information and examples about making a new gem, check out our
   # guide at: https://bundler.io/guides/creating_gem.html

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: positioning
 version: !ruby/object:Gem::Version
-  version: 0.4.10
+  version: 0.5.0
 platform: ruby
 authors:
 - Brendon Muir
@@ -15,28 +15,28 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '7.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '7.2'
 - !ruby/object:Gem::Dependency
   name: activerecord
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '7.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '7.2'
 email:
 - brendon@spike.net.nz
 executables: []
@@ -70,7 +70,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.0.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="