positioning 0.2.5 → 0.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '04080c2e27b8d0545c86d69fb4a7794530971ca19c1e9db969181ff01bab2f96'
-  data.tar.gz: 3e81bbd7406e0221378d78e4404629c70eb84d82849d96c6a3506982cbfdf756
+  metadata.gz: a0ee169113edb44c11902cb1bd27fdb5f156d1c4ca4ff2a8e75b250d71bc3d52
+  data.tar.gz: 8d7ff6671fd40a3f08c33dd0c8070c427132919123925ed1d9fa28a43ca32e28
 SHA512:
-  metadata.gz: ef7cd59860371c435080925d38d994ac8b6a538de4c3a2687f602959792d7d9d1ba91c3df8c91c74ecf284f65ac432d7fc88b2d7ea3710c22c5f27641398f58e
-  data.tar.gz: 108ded7f5f7756f05dbc19b863bc723ed4e32e41737b6eecded5d0a6e0ab8a19e65a05bb330ce3625f5a61736ed0c4f816a3183efde8b7d17d0bcfbd5518ddda
+  metadata.gz: 8d2faaf09b6173c3d4c8d2a052f3377bdecfc3594a9fad426043296f8e2bc880519d528774e5481a5361414a32ee06082a6f5de55f6e15f0cf82718a6f87bda9
+  data.tar.gz: f2230cf14ee341c776f617eb1eb592013d907efbf18db02ea570f6d210363b46dd5b40be7b901a82ceef3b609f1e3a6e5fcd4a443f7350aca1150734a7ee1984

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 ## [Unreleased]
 
+## [0.2.6] - 2024-08-21
+
+- Implement list healing so that existing lists can be fixed up when implementing `positioned` or if the list somehow gets corrupted.
+- Tidy up Advisory Lock code.
+
 ## [0.2.5] - 2024-08-10
 
 - Implemented composite primary key support. Thanks @jackozi for the original PR and the nudge to get this done!

data/README.md

@@ -72,6 +72,36 @@ belongs_to :list
 positioned on: :list, advisory_lock: false
 ```
 
+### Initialising a List
+
+If you are adding `positioning` to a model with existing database records, or you're migrating from another gem like `acts_as_list` or `ranked-model` and have an existing position column, you will need to do some work to ensure you have well formed position values for your records. `positioning` has a helper method per `positioned` declaration that allows you to 'heal' the position column, ensuring that positions are positive integers starting at 1 with no gaps.
+
+For example, in the usual case:
+
+```
+belongs_to :list
+positioned on: :list
+```
+
+you'll have a method called `heal_position_column!`. You can call this method and it will cycle through every existing scope combination in your database (every list with items in this case) and reset those items' position based on their current position order by default. You can pass in a custom order if you don't trust (or don't have) an existing order column. The custom order is passed through to the Active Record `reorder` method, so you can provide anything that that method accepts:
+
+```
+Item.heal_position_column! name: :desc
+```
+
+You may need to introduce your database constraints after healing your position column:
+
+* We recommend a `null: false` constraint on the position column but if your existing column has `NULL` values, you'll need to fix those first. The heal method will heal `NULL` positions but depending on your database engine `NULL` positioned items might be placed at the start of the returned records or at the end (if positioning on the position column). Some databases allow this behaviour to be customised.
+* We also recommend a unique index on the scope columns and the position column. If you have repeated position integers per scope you'll need to use the heal method to fix these first before applying the unique index in a separate migration step.
+
+The heal method name is named after the column used to store position values. By default this is `position` but if you override it then the method name will change:
+
+```
+positioned on: :category, column: :category_position
+```
+
+will have a class method named `heal_category_position_column!`.
+
 ### Manipulating Positioning
 
 The tools for manipulating the position of records in your list have been kept intentionally terse. Priority has also been given to minimal pollution of the model namespace. Only two class methods are defined on all models (`positioning_columns` and `positioned`), and two instance methods are defined on models that call `positioned`:

data/lib/positioning/advisory_lock.rb

@@ -3,23 +3,24 @@ require "openssl"
 
 module Positioning
   class AdvisoryLock
-    Adapter = Struct.new(:initialise, :aquire, :release, keyword_init: true)
+    Adapter = Struct.new(:initialise, :acquire, :release, keyword_init: true)
 
     attr_reader :base_class
 
-    def initialize(base_class, column)
+    def initialize(base_class, column, enabled)
       @base_class = base_class
       @column = column.to_s
+      @enabled = enabled
 
       @adapters = {
         "mysql2" => Adapter.new(
           initialise: -> {},
-          aquire: -> { connection.execute "SELECT GET_LOCK(#{connection.quote(lock_name)}, -1)" },
+          acquire: -> { connection.execute "SELECT GET_LOCK(#{connection.quote(lock_name)}, -1)" },
           release: -> { connection.execute "SELECT RELEASE_LOCK(#{connection.quote(lock_name)})" }
         ),
         "postgresql" => Adapter.new(
           initialise: -> {},
-          aquire: -> { connection.execute "SELECT pg_advisory_lock(#{lock_name.hex & 0x7FFFFFFFFFFFFFFF})" },
+          acquire: -> { connection.execute "SELECT pg_advisory_lock(#{lock_name.hex & 0x7FFFFFFFFFFFFFFF})" },
           release: -> { connection.execute "SELECT pg_advisory_unlock(#{lock_name.hex & 0x7FFFFFFFFFFFFFFF})" }
         ),
         "sqlite3" => Adapter.new(
@@ -28,7 +29,7 @@ module Positioning
             filename = "#{Dir.pwd}/tmp/#{lock_name}.lock"
             @file ||= File.open filename, File::RDWR | File::CREAT, 0o644
           },
-          aquire: -> {
+          acquire: -> {
             @file.flock File::LOCK_EX
           },
           release: -> {
@@ -37,24 +38,23 @@ module Positioning
         )
       }
 
-      @adapters.default = Adapter.new(initialise: -> {}, aquire: -> {}, release: -> {})
+      @adapters.default = Adapter.new(initialise: -> {}, acquire: -> {}, release: -> {})
 
-      adapter.initialise.call
+      adapter.initialise.call if @enabled
     end
 
-    def aquire(record)
-      adapter.aquire.call
-    end
+    def acquire
+      adapter.acquire.call if @enabled
 
-    def release(record)
-      adapter.release.call
+      if block_given?
+        yield
+        adapter.release.call if @enabled
+      end
     end
 
-    alias_method :before_create, :aquire
-    alias_method :before_update, :aquire
-    alias_method :before_destroy, :aquire
-    alias_method :after_commit, :release
-    alias_method :after_rollback, :release
+    def release
+      adapter.release.call if @enabled
+    end
 
     private
 

data/lib/positioning/healer.rb

@@ -0,0 +1,31 @@
+module Positioning
+  class Healer
+    def initialize(model, column, order)
+      @model = model
+      @column = column.to_sym
+      @order = order
+    end
+
+    def heal
+      if positioning_columns.present?
+        @model.select(*positioning_columns).distinct.each do |scope_record|
+          sequence @model.where(scope_record.slice(*positioning_columns))
+        end
+      else
+        sequence @model
+      end
+    end
+
+    private
+
+    def positioning_columns
+      @model.positioning_columns[@column]
+    end
+
+    def sequence(scope)
+      scope.reorder(@order).each.with_index(1) do |record, index|
+        record.update_columns @column => index
+      end
+    end
+  end
+end

data/lib/positioning/mechanisms.rb

@@ -6,11 +6,11 @@ module Positioning
     end
 
     def prior
-      positioning_scope.where("#{@column}": position - 1).first
+      positioning_scope.where(@column => position - 1).first
     end
 
     def subsequent
-      positioning_scope.where("#{@column}": position + 1).first
+      positioning_scope.where(@column => position + 1).first
     end
 
     def create_position
@@ -84,17 +84,17 @@ module Positioning
 
     def move_out_of_the_way
       position_was # Memoize the original position before changing it
-      record_scope.update_all "#{@column}": 0
+      record_scope.update_all @column => 0
     end
 
     def expand(scope, range)
-      scope.where("#{@column}": range).update_all "#{quoted_column} = #{quoted_column} * -1"
-      scope.where("#{@column}": ..-1).update_all "#{quoted_column} = #{quoted_column} * -1 + 1"
+      scope.where(@column => range).update_all "#{quoted_column} = #{quoted_column} * -1"
+      scope.where(@column => ..-1).update_all "#{quoted_column} = #{quoted_column} * -1 + 1"
     end
 
     def contract(scope, range)
-      scope.where("#{@column}": range).update_all "#{quoted_column} = #{quoted_column} * -1"
-      scope.where("#{@column}": ..-1).update_all "#{quoted_column} = #{quoted_column} * -1 - 1"
+      scope.where(@column => range).update_all "#{quoted_column} = #{quoted_column} * -1"
+      scope.where(@column => ..-1).update_all "#{quoted_column} = #{quoted_column} * -1 - 1"
     end
 
     def solidify_position

data/lib/positioning/version.rb

@@ -1,3 +1,3 @@
 module Positioning
-  VERSION = "0.2.5"
+  VERSION = "0.2.6"
 end

data/lib/positioning.rb

@@ -1,6 +1,7 @@
 require_relative "positioning/version"
 require_relative "positioning/advisory_lock"
 require_relative "positioning/mechanisms"
+require_relative "positioning/healer"
 
 require "active_support/concern"
 require "active_support/lazy_load_hooks"
@@ -43,21 +44,23 @@ module Positioning
             super(position)
           end
 
-          if advisory_lock
-            advisory_lock_callback = AdvisoryLock.new(base_class, column)
+          advisory_locker = AdvisoryLock.new(base_class, column, advisory_lock)
 
-            before_create advisory_lock_callback
-            before_update advisory_lock_callback
-            before_destroy advisory_lock_callback
-          end
+          before_create { advisory_locker.acquire }
+          before_update { advisory_locker.acquire }
+          before_destroy { advisory_locker.acquire }
 
           before_create { Mechanisms.new(self, column).create_position }
           before_update { Mechanisms.new(self, column).update_position }
           before_destroy { Mechanisms.new(self, column).destroy_position }
 
-          if advisory_lock
-            after_commit advisory_lock_callback
-            after_rollback advisory_lock_callback
+          after_commit { advisory_locker.release }
+          after_rollback { advisory_locker.release }
+
+          define_singleton_method(:"heal_#{column}_column!") do |order = column|
+            advisory_locker.acquire do
+              Healer.new(self, column, order).heal
+            end
           end
         end
       end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: positioning
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.2.6
 platform: ruby
 authors:
 - Brendon Muir
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-08-09 00:00:00.000000000 Z
+date: 2024-08-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -123,6 +123,7 @@ files:
 - Rakefile
 - lib/positioning.rb
 - lib/positioning/advisory_lock.rb
+- lib/positioning/healer.rb
 - lib/positioning/mechanisms.rb
 - lib/positioning/version.rb
 - positioning.gemspec