narabikae 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 889a0fb05988806d1ff5ab57e02932cf4bf8a57ad788e3a4f094456e15e57902
-  data.tar.gz: 1dfb405bc128aacd6bae61b89e133af0aa40cf67b16638ba475bb1933584c855
+  metadata.gz: bc30700880dd0d9d8f7e463026575efd31fe4accee18068e7481332259a035e7
+  data.tar.gz: d973c99b9a1349a2e162bb4c5574bafac62c48f5726e73426a701896d28729d9
 SHA512:
-  metadata.gz: 0c2e99432062adc3745d8c6641d99bbd7a2b91a021103c552f3c4f9a7d6678370c344af81adf7d10a0ba3103730070bd8f7370fcb9c99a99dd06c8d01d89e882
-  data.tar.gz: 0aed46f7bf0ed8ae057324e17b99799d132e77244382ba0d945476221d3edb0d7c2f9444f2281b0d28a9e85e17fce9da1cb0eba13c27c613e4e4fe5da629bdaa
+  metadata.gz: d5da939a280875622f4b373e1c6a04343803cc47e346038f509f308cfba4bfc8d5674b7824218e98c738a876ee081cc2e18f1483104b62d000337d9b845b0c4c
+  data.tar.gz: 9f0a9b5871ccc39f3e1611bcbaf8c7638afd01fdb5569cc3db8495b390873854588bc4e8e8f6d3a540ccfa2c784b1a82b8b344575f4027087fddb26e3a659c45

data/README.md

@@ -4,7 +4,76 @@
 
 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 🎉.
+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.
+
+## Why Narabikae?
+
+| Feature | acts_as_list | Narabikae |
+|---------|--------------|-----------|
+| Records updated on reorder | O(n) | O(1) |
+| Position type | Integer | String |
+| Algorithm | Sequential numbering | Fractional Indexing |
+| Best for | Small lists, infrequent reordering | Large lists, frequent reordering |
+
+**Example:** When moving an item to position 1 in a list of 10,000 items:
+- **acts_as_list**: Updates up to 10,000 records to shift positions
+- **Narabikae**: Updates only 1 record
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Installation](#installation)
+- [Getting Started](#getting-started)
+  - [Adding a column to manage order](#adding-a-column-to-manage-order)
+  - [Adding configuration to your model](#adding-configuration-to-your-model)
+- [Usage Details](#usage-details)
+  - [Methods Overview](#methods-overview)
+  - [Reorder](#reorder)
+  - [Set without saving](#set-without-saving)
+  - [Form-friendly setters](#form-friendly-setters)
+  - [Scope](#scope)
+  - [Retry generating position](#retry-generating-position)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Quick Start
+
+Get up and running in 3 steps:
+
+```ruby
+# 1. Add to Gemfile
+gem "narabikae"
+```
+
+```ruby
+# 2. Create migration
+add_column :tasks, :position, :string, null: false
+add_index :tasks, :position, unique: true
+```
+
+```ruby
+# 3. Add to your model
+class Task < ApplicationRecord
+  narabikae :position, size: 255
+end
+```
+
+That's it! Your model now has automatic position management:
+
+```ruby
+Task.create([{ name: 'Task A' }, { name: 'Task B' }, { name: 'Task C' }])
+Task.order(:position).pluck(:name)
+# => ["Task A", "Task B", "Task C"]
+
+# Move Task A after Task C
+task_a = Task.find_by(name: 'Task A')
+task_c = Task.find_by(name: 'Task C')
+task_a.move_to_position_after(task_c)
+
+Task.order(:position).pluck(:name)
+# => ["Task B", "Task C", "Task A"]
+```
 
 ## Installation
 
@@ -43,7 +112,7 @@ add_index :tasks, :position, unique: true
 
 - Set the collation to distinguish between uppercase and lowercase letters.
 
-  For example, if using MySQL 8.0’s default collation (utf8mb4_0900_ai_ci), which does not distinguish between uppercase and lowercase, the sort results may not behave as expected.
+  For example, if using MySQL 8.0's default collation (utf8mb4_0900_ai_ci), which does not distinguish between uppercase and lowercase, the sort results may not behave as expected.
 
 - It is recommended to apply both NOT NULL and UNIQUE constraints.
 
@@ -189,7 +258,7 @@ target.position_after = tasks.last
 target.position_between = [tasks.first, tasks.last]
 ```
 
-#### Form-friendly setters
+### 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.
 
@@ -273,7 +342,7 @@ Feel free to message me on Github (kazu-2020)
 
 ### Supported versions (tested in CI)
 
-- Ruby 3.1, 3.2, 3.3, 3.4, 4.0
+- Ruby 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

data/lib/narabikae/position.rb

@@ -24,9 +24,12 @@ module Narabikae
     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.
+    #
+    # Uses an optimized neighbor-aware approach: queries the database for the
+    # next record's position and generates a key between the target and its
+    # neighbor. This avoids blind key generation and reduces collision retries.
+    #
+    # Falls back to retry with random fractional for concurrent write race conditions.
     #
     # @param target [ActiveRecord::Base, String]
     # @param challenge [Integer] The number of times to attempt finding a valid position.
@@ -34,7 +37,8 @@ module Narabikae
     def find_position_after(target, challenge: 10)
       # when target is nil, try to generate key from the last position
       target_key = extract_target_key(target) || current_last_position
-      key = FractionalIndexer.generate_key(prev_key: target_key)
+      next_key = find_next_position_key(target_key)
+      key = FractionalIndexer.generate_key(prev_key: target_key, next_key: next_key)
       return key if valid?(key)
 
       (challenge || 0).times do |i|
@@ -48,15 +52,13 @@ module Narabikae
       nil
     end
 
-    #
     # Finds the position before the target position.
-    # 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.
     #
-    # @example
-    #   position = Position.new
-    #   position.find_position_before(target, challenge: 5)
+    # Uses an optimized neighbor-aware approach: queries the database for the
+    # previous record's position and generates a key between the neighbor and
+    # the target. This avoids blind key generation and reduces collision retries.
+    #
+    # Falls back to retry with random fractional for concurrent write race conditions.
     #
     # @param target [ActiveRecord::Base, String]
     # @param challenge [Integer] The number of times to attempt finding a valid position.
@@ -64,7 +66,8 @@ module Narabikae
     def find_position_before(target, challenge: 10)
       # when target is nil, try to generate key from the first position
       target_key = extract_target_key(target) || current_first_position
-      key = FractionalIndexer.generate_key(next_key: target_key)
+      prev_key = find_prev_position_key(target_key)
+      key = FractionalIndexer.generate_key(prev_key: prev_key, next_key: target_key)
       return key if valid?(key)
 
       (challenge || 0).times do |i|
@@ -124,6 +127,34 @@ module Narabikae
       model.merge(model_scope).maximum(option.field)
     end
 
+    # Finds the position key of the next record after the given key within scope.
+    # Uses an indexed query for O(log n) lookup.
+    #
+    # @param key [String] The position key to search after.
+    # @return [String, nil] The next position key, or nil if no record exists after.
+    def find_next_position_key(key)
+      return nil if key.nil?
+
+      model.merge(model_scope)
+           .where(model.arel_table[option.field].gt(key))
+           .order(option.field => :asc)
+           .pick(option.field)
+    end
+
+    # Finds the position key of the previous record before the given key within scope.
+    # Uses an indexed query for O(log n) lookup.
+    #
+    # @param key [String] The position key to search before.
+    # @return [String, nil] The previous position key, or nil if no record exists before.
+    def find_prev_position_key(key)
+      return nil if key.nil?
+
+      model.merge(model_scope)
+           .where(model.arel_table[option.field].lt(key))
+           .order(option.field => :desc)
+           .pick(option.field)
+    end
+
     def model
       record.class.base_class.unscoped
     end

data/lib/narabikae/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: narabikae
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - matazou
@@ -200,7 +200,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="