positioning 0.2.5 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '04080c2e27b8d0545c86d69fb4a7794530971ca19c1e9db969181ff01bab2f96'
-  data.tar.gz: 3e81bbd7406e0221378d78e4404629c70eb84d82849d96c6a3506982cbfdf756
+  metadata.gz: 2b3dd60b08d2b1488b5fd6c88681f83cd37b46dd2eb0f27557ca4fb131928c9b
+  data.tar.gz: 442d3030455cadbcaa2e4fe0f97bc4631d9081194aff31c67242ec5675bc5f8e
 SHA512:
-  metadata.gz: ef7cd59860371c435080925d38d994ac8b6a538de4c3a2687f602959792d7d9d1ba91c3df8c91c74ecf284f65ac432d7fc88b2d7ea3710c22c5f27641398f58e
-  data.tar.gz: 108ded7f5f7756f05dbc19b863bc723ed4e32e41737b6eecded5d0a6e0ab8a19e65a05bb330ce3625f5a61736ed0c4f816a3183efde8b7d17d0bcfbd5518ddda
+  metadata.gz: 2c199c7f7d79ca57833593e3bfbe2e47161875943aabef8247c9cabb7b35e5c22297b6b69f298fc2c3df8ee0e9c5f1d99dc6c41e8e90b979cddd205c2d4b91b6
+  data.tar.gz: f6e070723c2178c5b7e4907e43ae8fcf2a9f50611b37179fc618ffa220205382f01f8aaa907a0a0cea1bd2aa0e14baf623401678bebc5e7b5ccbc80f2f3f31eb

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 ## [Unreleased]
 
+## [0.3.0] - 2024-08-21
+
+- POSSIBLY BREAKING: Clear all position columns on a duplicate created with `dup`.
+
+## [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`:
@@ -155,6 +185,10 @@ other_item.id # => 11
 item.update position: {after: 11}
 ```
 
+##### Duplicating (`dup`)
+
+When you call `dup` on an instance in the list, all position columns on the duplicate will be set to `nil` so that when this duplicate is saved it will be added either to the end of the current scopes (if unchanged) or to the end of any new scopes. Of course you can then override the position of the duplicate before you save it if necessary.
+
 ##### Relative Positioning in Forms
 
 It can be tricky to provide the hash forms of relative positioning using Rails form helpers, but it is possible. We've declared a special `Struct` for you to use for this purpose.

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.3.0"
 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,25 +44,35 @@ 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
     end
+
+    def initialize_dup(other)
+      super
+
+      self.class.positioning_columns.keys.each do |positioning_column|
+        send :"#{positioning_column}=", nil
+      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.3.0
 platform: ruby
 authors:
 - Brendon Muir
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-08-09 00:00:00.000000000 Z
+date: 2024-10-11 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