narabikae 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 96e657bcc111a885f21934870ac5360490aa4999b6df0533af524f761ecd9244
-  data.tar.gz: d7eca3f77b6260eea610bb5f5dbcdd71099972f74cd88028d00c5a266bd32667
+  metadata.gz: 889a0fb05988806d1ff5ab57e02932cf4bf8a57ad788e3a4f094456e15e57902
+  data.tar.gz: 1dfb405bc128aacd6bae61b89e133af0aa40cf67b16638ba475bb1933584c855
 SHA512:
-  metadata.gz: e0bcec0651250189dcdac6c724bccf994d98350d4668e543dab8e039cc3f5ecd2891961ba2ecaa3d9bcd198094968137d4d5fb8215f7da692a849496b310cec7
-  data.tar.gz: 90aa217d0d397c49452febff37a6153ffc10c2f309de27348482b1f28a3dac58440306001f2110eb70c3fa063e1d3e2789846b4c5fe0377750c84260b70a2e2b
+  metadata.gz: 0c2e99432062adc3745d8c6641d99bbd7a2b91a021103c552f3c4f9a7d6678370c344af81adf7d10a0ba3103730070bd8f7370fcb9c99a99dd06c8d01d89e882
+  data.tar.gz: 0aed46f7bf0ed8ae057324e17b99799d132e77244382ba0d945476221d3edb0d7c2f9444f2281b0d28a9e85e17fce9da1cb0eba13c27c613e4e4fe5da629bdaa

data/README.md

@@ -1,5 +1,7 @@
 # Narabikae
 
+[![test](https://github.com/kazu-2020/narabikae/actions/workflows/ci.yaml/badge.svg?branch=main&event=push)](https://github.com/kazu-2020/narabikae/actions/workflows/ci.yaml)
+
 Narabikae(Japanese: 並び替え) means "reorder". Like [acts_as_list](https://github.com/brendon/acts_as_list), this gem provides automatic order management and reordering functionality for your records.
 
 One of the key advantages of this gem is its use of the [fractional indexing algorithm](https://www.figma.com/blog/realtime-editing-of-ordered-sequences/#fractional-indexing), which greatly enhances the efficiency of reordering operations. With Narabikae, regardless of the amount of data, "only a single record" is updated during the reordering process 🎉.
@@ -67,6 +69,10 @@ class Task < ApplicationRecord
   #       Used for validation of the internally generated order value.
   #       This value should be equivalent to
   #       the limit set in the DB column.
+  #
+  # default_position: optional
+  #       Set where new/auto-set records are inserted.
+  #       Accepts :first or :last (default).
 end
 ```
 
@@ -79,13 +85,23 @@ Task.create([
           { name: 'task-3' }
      ])
 Task.order(:position).pluck(:name, :position)
-# => [["task-1", "a0"], ["task-3", "a1"], ["task-1", "a2"]]
+# => [["task-1", "a0"], ["task-2", "a1"], ["task-3", "a2"]]
 
 ```
 
 > [!NOTE]
 > The position is set using the before_create callback. Therefore, do not define validations such as presence on the attributes managed by this gem!
 
+#### Default position
+
+By default, new/auto-set records are inserted at the end of the list. To insert at the beginning instead:
+
+```rb
+class Task < ApplicationRecord
+  narabikae :position, size: 200, default_position: :first
+end
+```
+
 ## Usage Details
 
 ### Reorder
@@ -155,6 +171,45 @@ target.position
 # ex: target.move_to_position_between(tasks.first, nil)
 ```
 
+### Set without saving
+
+If you want to set the new position value and save later (for example, in a form), use `set_<field>_after/before/between`. These methods only assign the new position value and do not persist the record.
+
+```ruby
+target.set_position_after(tasks.last)
+target.position
+# => 'a3'
+target.save
+```
+
+You can also use setter-style aliases:
+
+```ruby
+target.position_after = tasks.last
+target.position_between = [tasks.first, tasks.last]
+```
+
+#### Form-friendly setters
+
+The setter aliases can be used directly in forms or `assign_attributes`. They accept a target record or a position key (string). For `*_between=`, you can pass an array or hash. Primary key inputs are not accepted; do your own lookup and pass the record or its position.
+
+```ruby
+# position key input (e.g., from a hidden field)
+task.assign_attributes(position_after: tasks.last.position)
+
+# between using an array
+task.position_between = [tasks.first, tasks.last]
+
+# between using a hash (string or symbol keys)
+task.position_between = { prev: tasks.first.position, next: tasks.last.position }
+```
+
+If you need retries, use the method form and pass `challenge` there:
+
+```ruby
+task.set_position_between(tasks.first, tasks.last, challenge: 15)
+```
+
 ### Scope
 
 You can use this when you want to manage independent positions within specific scopes, such as foreign keys.
@@ -168,7 +223,7 @@ end
 class Chapter < ApplicationRecord
   belongs_to :course
 
-  narabikae :position, size: 100, scope: %i[course_id]
+  narabikae :position, size: 100, scope: :course_id
 end
 
 course = Course.create
@@ -214,6 +269,53 @@ ticket.move_to_position_between(t1, t2, challenge: 15)
 
 Feel free to message me on Github (kazu-2020)
 
+## Development
+
+### Supported versions (tested in CI)
+
+- Ruby 3.1, 3.2, 3.3, 3.4, 4.0
+- Rails 7.1, 7.2, 8.0, 8.1, and Rails main (via `railties` from `rails/rails`)
+
+### Test suite
+
+Tests are Minitest-based and run against a dummy Rails app located at `test/dummy`.
+
+Database targets:
+
+- `TARGET_DB=mysql` (default)
+- `TARGET_DB=postgres`
+- `TARGET_DB=sqlite`
+
+To spin up database services locally:
+
+```sh
+docker compose up -d
+```
+
+Run the full matrix locally (all databases):
+
+```sh
+bundle exec rake test
+```
+
+Run a single database:
+
+```sh
+bundle exec rake test:postgres
+```
+
+Run tests directly with Rails for a specific target:
+
+```sh
+TARGET_DB=sqlite bin/rails test
+```
+
+To test against a specific Rails version:
+
+```sh
+BUNDLE_GEMFILE=gemfiles/rails_8_1.gemfile TARGET_DB=mysql bundle exec rake test
+```
+
 ## Contributing
 
 Please wait a moment... 🙏

data/lib/narabikae/active_record_extension.rb

@@ -11,36 +11,60 @@ module Narabikae
       # check valid key for fractional_indexer
       # when invalid key, raise FractionalIndexer::Error
       FractionalIndexer.generate_key(prev_key: record.send(option.field))
-      option.scope.any? { |s| record.will_save_change_to_attribute?(s) } && !record.will_save_change_to_attribute?(option.field)
+      record.send(option.field).nil? ||
+        (option.scope.any? { |s| record.will_save_change_to_attribute?(s) } && !record.will_save_change_to_attribute?(option.field))
     rescue FractionalIndexer::Error
       true
     end
 
-    def set_position
-      record.send("#{option.field}=", position_generator.create_last_position)
+    def set_position(position = option.default_position)
+      new_position =
+        case position
+        when :first
+          position_generator.create_first_position
+        when :last
+          position_generator.create_last_position
+        end
+
+      record.send("#{option.field}=", new_position)
     end
 
-    def move_to_after(target, **args)
+    def set_after(target, **args)
       new_position = position_generator.find_position_after(target, **args)
       return false if new_position.blank?
 
       record.send("#{option.field}=", new_position)
-      record.save
     end
 
-    def move_to_before(target, **args)
+    def set_before(target, **args)
       new_position = position_generator.find_position_before(target, **args)
       return false if new_position.blank?
 
       record.send("#{option.field}=", new_position)
-      record.save
     end
 
-    def move_to_between(prev_target, next_target, **args)
+    def set_between(prev_target, next_target, **args)
       new_position = position_generator.find_position_between(prev_target, next_target, **args)
       return false if new_position.blank?
 
       record.send("#{option.field}=", new_position)
+    end
+
+    def move_to_after(target, **args)
+      return false unless set_after(target, **args)
+
+      record.save
+    end
+
+    def move_to_before(target, **args)
+      return false unless set_before(target, **args)
+
+      record.save
+    end
+
+    def move_to_between(prev_target, next_target, **args)
+      return false unless set_between(prev_target, next_target, **args)
+
       record.save
     end
 

data/lib/narabikae/configuration.rb

@@ -2,7 +2,7 @@ module Narabikae
   class Configuration
     # Sets the base value for FractionalIndexer configuration.
     #
-    # @param int [Integer] The base value can be 10, 62, 94, with the default being 94.
+    # @param int [Integer] The base value can be 10, 62, 94, with the default being 62.
     # @return [void]
     def base=(int)
       FractionalIndexer.configure do |config|

data/lib/narabikae/option.rb

@@ -1,16 +1,22 @@
 module Narabikae
   class Option
-    attr_reader :field, :key_max_size, :scope
+    attr_reader :field, :key_max_size, :scope, :default_position
 
     # Initializes a new instance of the Option class.
     #
     # @param field [Symbol]
     # @param key_max_size [Integer] The maximum size of the key.
-    # @param scope [Array<Symbol>] The scope of the option.
-    def initialize(field:, key_max_size:, scope: [])
+    # @param scope [Symbol, Array<Symbol>] The scope of the option.
+    # @param default_position [Symbol] The default position when creating or auto setting.
+    def initialize(field:, key_max_size:, scope: [], default_position: :last)
       @field = field.to_sym
       @key_max_size = key_max_size.to_i
-      @scope = scope.is_a?(Array) ? scope.map(&:to_sym) : []
+      @scope = Array.wrap(scope).map(&:to_sym)
+      @default_position = (default_position || :last).to_sym
+
+      unless %i[first last].include?(@default_position)
+        raise ArgumentError, "default_position must be :first or :last"
+      end
     end
   end
 end

data/lib/narabikae/position.rb

@@ -16,24 +16,29 @@ module Narabikae
       FractionalIndexer.generate_key(prev_key: current_last_position)
     end
 
+    # Generates a new key for the first position
+    #
+    # @return [String] The newly generated key for the first position.
+    def create_first_position
+      FractionalIndexer.generate_key(next_key: current_first_position)
+    end
+
     # Finds the position after the specified target.
     # If generated key is invalid(ex: it already exists),
     # a new key is generated until the challenge count reaches the limit.
     # challenge count is 10 by default.
     #
-    # @param target [#send(field)]
-    # @param args [Hash] Additional arguments.
-    # @option args [Integer] :challenge The number of times to attempt finding a valid position.
+    # @param target [ActiveRecord::Base, String]
+    # @param challenge [Integer] The number of times to attempt finding a valid position.
     # @return [String, nil] The generated key for the position after the target, or nil if no valid position is found.
-    def find_position_after(target, **args)
-      merged_args = { challenge: 10 }.merge(args)
+    def find_position_after(target, challenge: 10)
       # when target is nil, try to generate key from the last position
-      key = FractionalIndexer.generate_key(
-              prev_key: target&.send(option.field) || current_last_position
-            )
+      target_key = extract_target_key(target) || current_last_position
+      key = FractionalIndexer.generate_key(prev_key: target_key)
       return key if valid?(key)
 
-      (merged_args[:challenge] || 0).times do
+      (challenge || 0).times do |i|
+        key = FractionalIndexer.generate_key(prev_key: target_key, next_key: key)
         key += random_fractional
         return key if valid?(key)
       end
@@ -53,19 +58,17 @@ module Narabikae
     #   position = Position.new
     #   position.find_position_before(target, challenge: 5)
     #
-    # @param target [#send(field)]
-    # @param args [Hash] Additional arguments.
-    # @option args [Integer] :challenge The number of times to attempt finding a valid position.
+    # @param target [ActiveRecord::Base, String]
+    # @param challenge [Integer] The number of times to attempt finding a valid position.
     # @return [String, nil] The generated key for the position before the target, or nil if no valid position is found.
-    def find_position_before(target, **args)
-      merged_args = { challenge: 10 }.merge(args)
+    def find_position_before(target, challenge: 10)
       # when target is nil, try to generate key from the first position
-      key = FractionalIndexer.generate_key(
-              next_key: target&.send(option.field) || current_first_position
-            )
+      target_key = extract_target_key(target) || current_first_position
+      key = FractionalIndexer.generate_key(next_key: target_key)
       return key if valid?(key)
 
-      (merged_args[:challenge] || 0).times do
+      (challenge || 0).times do |i|
+        key = FractionalIndexer.generate_key(prev_key: key, next_key: target_key)
         key += random_fractional
         return key if valid?(key)
       end
@@ -77,25 +80,25 @@ module Narabikae
 
     # Finds the position between two targets.
     #
-    # @param prev_target [#send(field)] The previous target.
-    # @param next_target [#send(field)] The next target.
-    # @param args [Hash] Additional arguments.
-    # @option args [Integer] :challenge The number of times to attempt finding a valid position.
+    # @param prev_target [ActiveRecord::Base, String] The previous target.
+    # @param next_target [ActiveRecord::Base, String] The next target.
+    # @param challenge [Integer] The number of times to attempt finding a valid position.
     # @return [string, nil] The position between the two targets, or nil if no valid position is found.
-    def find_position_between(prev_target, next_target, **args)
-      return find_position_before(next_target, **args) if prev_target.blank?
-      return find_position_after(prev_target, **args)  if next_target.blank?
-
-      merged_args = { challenge: 10 }.merge(args)
+    def find_position_between(prev_target, next_target, challenge: 10)
+      prev_key = extract_target_key(prev_target)
+      next_key = extract_target_key(next_target)
+      return find_position_before(next_target, challenge: challenge) if prev_key.blank?
+      return find_position_after(prev_target, challenge: challenge) if next_key.blank?
 
-      prev_key, next_key = [ prev_target.send(option.field), next_target.send(option.field) ].minmax
+      prev_key, next_key = [ prev_key, next_key ].minmax
       key = FractionalIndexer.generate_key(
               prev_key: prev_key,
               next_key: next_key,
             )
       return key if valid?(key)
 
-      (merged_args[:challenge] || 0).times do
+      (challenge || 0).times do |i|
+        key = FractionalIndexer.generate_key(prev_key: key, next_key: next_key)
         key += random_fractional
         return key if valid?(key)
       end
@@ -122,7 +125,7 @@ module Narabikae
     end
 
     def model
-      record.class.base_class
+      record.class.base_class.unscoped
     end
 
     # generate a random fractional part
@@ -147,5 +150,43 @@ module Narabikae
 
       capable?(key) && uniq?(key)
     end
+
+    def extract_target_key(target)
+      return if target.nil?
+      return target if target.is_a?(String)
+      unless target.is_a?(ActiveRecord::Base)
+        raise Narabikae::Error, "target must be an ActiveRecord object or position key string"
+      end
+
+      record_table = table_name_for_class(record)
+      target_table = table_name_for_class(target)
+      unless target_table && record_table && target_table == record_table
+        raise Narabikae::Error,
+              "target model mismatch: expected table #{record_table || 'unknown'}, got #{target_table || 'unknown'}"
+      end
+
+      mismatched_columns = mismatched_scope_columns(target)
+      if mismatched_columns.any?
+        raise Narabikae::Error, "target scope mismatch for columns: #{mismatched_columns.join(', ')}"
+      end
+      raise Narabikae::Error, "target missing #{option.field} field" unless target.respond_to?(option.field)
+
+      target.send(option.field)
+    end
+
+    def table_name_for_class(value)
+      klass = value.class
+      return unless klass.respond_to?(:table_name)
+
+      klass.table_name
+    end
+
+    def mismatched_scope_columns(target)
+      option.scope.select do |column|
+        !target.respond_to?(column) ||
+          !record.respond_to?(column) ||
+          target.public_send(column) != record.public_send(column)
+      end
+    end
   end
 end

data/lib/narabikae/version.rb

@@ -1,3 +1,3 @@
 module Narabikae
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/narabikae.rb

@@ -29,20 +29,50 @@ module Narabikae
     extend ActiveSupport::Concern
 
     class_methods do
-      def narabikae(field = :position, size:, scope: [])
+      def narabikae(field = :position, size:, scope: [], default_position: :last)
         option = narabikae_option_store.register!(
                    field.to_sym,
-                   Narabikae::Option.new(field: field, key_max_size: size, scope: scope)
+                   Narabikae::Option.new(field: field, key_max_size: size, scope: scope, default_position: default_position)
                  )
 
-        before_create do
+        before_save -> {
           extension = Narabikae::ActiveRecordExtension.new(self, option)
-          extension.set_position
+          extension.set_position(option.default_position) if extension.auto_set_position?
+        }
+
+        define_method :"set_#{field}_after" do |target = nil, **args|
+          extension = Narabikae::ActiveRecordExtension.new(self, option)
+          extension.set_after(target, **args)
+        end
+        alias_method :"#{field}_after=", :"set_#{field}_after"
+
+        define_method :"set_#{field}_before" do |target = nil, **args|
+          extension = Narabikae::ActiveRecordExtension.new(self, option)
+          extension.set_before(target, **args)
+        end
+        alias_method :"#{field}_before=", :"set_#{field}_before"
+
+        define_method :"set_#{field}_between" do |prev_target = nil, next_target = nil, **args|
+          extension = Narabikae::ActiveRecordExtension.new(self, option)
+          extension.set_between(prev_target, next_target, **args)
         end
+        define_method :"#{field}_between=" do |value|
+          prev_target = nil
+          next_target = nil
+
+          case value
+          when Array
+            prev_target, next_target = value
+          when Hash
+            payload = value.with_indifferent_access
+            prev_target = payload[:prev_target] || payload[:prev]
+            next_target = payload[:next_target] || payload[:next]
+          else
+            prev_target = value
+          end
 
-        before_update do
           extension = Narabikae::ActiveRecordExtension.new(self, option)
-          extension.set_position if extension.auto_set_position?
+          extension.set_between(prev_target, next_target)
         end
 
         define_method :"move_to_#{field}_after" do |target = nil, **args|

metadata

@@ -1,37 +1,106 @@
 --- !ruby/object:Gem::Specification
 name: narabikae
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - matazou
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-10-02 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
 - !ruby/object:Gem::Dependency
   name: fractional_indexer
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.4.0
   type: :runtime
   prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.4.0
+- !ruby/object:Gem::Dependency
+  name: appraisal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: activerecord
+  name: debug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: mocha
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-  type: :runtime
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
@@ -39,13 +108,13 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: activesupport
+  name: mysql2
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-  type: :runtime
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
@@ -53,21 +122,21 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rspec-rails
+  name: pg
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 5.0.0
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 5.0.0
+        version: '0'
 - !ruby/object:Gem::Dependency
-  name: rubocop-rails-omakase
+  name: sqlite3
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -81,7 +150,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rubocop-rspec
+  name: rubocop-rails-omakase
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -109,7 +178,6 @@ files:
 - README.md
 - lib/narabikae.rb
 - lib/narabikae/active_record_extension.rb
-- lib/narabikae/active_record_handler.rb
 - lib/narabikae/configuration.rb
 - lib/narabikae/option.rb
 - lib/narabikae/option_store.rb
@@ -125,7 +193,6 @@ metadata:
   source_code_uri: https://github.com/kazu-2020/narabikae
   allowed_push_host: https://rubygems.org/
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -133,15 +200,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.9
-signing_key:
+rubygems_version: 3.6.7
 specification_version: 4
 summary: provides simple position management and sorting functionality for Active
   Record in Rails.

data/lib/narabikae/active_record_handler.rb

@@ -1,31 +0,0 @@
-module Narabikae
-  class ActiveRecordHandler
-    # Initializes a new instance of the ActiveRecordHandler class.
-    #
-    # @param record [Object] The ActiveRecord object.
-    # @param column [Symbol] The column symbol.
-    def initialize(record, column)
-      @record  = record
-      @column  = column
-    end
-
-    # Generates a new key for the last position
-    #
-    # @return [String] The newly generated key for the last position.
-    def create_last_position
-      FractionalIndexer.generate_key(prev_key: current_last_position)
-    end
-
-    private
-
-    attr_reader :record, :column
-
-    def current_last_position
-      model.maximum(column)
-    end
-
-    def model
-      record.class.base_class
-    end
-  end
-end