narabikae 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 64ba8405e3f4412d5c417fb13a499653d883308f93aa704350eedfc3e70dc1f9
-  data.tar.gz: cc4217ce041d2db2e41af69182427fc6865dffed4329f23f5b70f0a1e8a26860
+  metadata.gz: 96e657bcc111a885f21934870ac5360490aa4999b6df0533af524f761ecd9244
+  data.tar.gz: d7eca3f77b6260eea610bb5f5dbcdd71099972f74cd88028d00c5a266bd32667
 SHA512:
-  metadata.gz: bd0676a4413917e858801f4ec5a99c210ba82a92a77fb7153b5b20e2bff2a40f8ce1c13ebc34b067c863d2d5fe56a5806a521553850295a2a62a363b1e3543bf
-  data.tar.gz: af54f6713a9f547a46c99393d6ede9198ced3ce47fdf3eb48e776482b3aa66d2b02f0bcdf218b9dbb8d478db4bee0332e9b56f6a5cb296372d0c70b203384e7f
+  metadata.gz: e0bcec0651250189dcdac6c724bccf994d98350d4668e543dab8e039cc3f5ecd2891961ba2ecaa3d9bcd198094968137d4d5fb8215f7da692a849496b310cec7
+  data.tar.gz: 90aa217d0d397c49452febff37a6153ffc10c2f309de27348482b1f28a3dac58440306001f2110eb70c3fa063e1d3e2789846b4c5fe0377750c84260b70a2e2b

data/README.md

@@ -1,28 +1,223 @@
 # Narabikae
-Short description and motivation.
 
-## Usage
-How to use my plugin.
+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 🎉.
 
 ## Installation
-Add this line to your application's Gemfile:
+
+In your Gemfile
 
 ```ruby
 gem "narabikae"
 ```
 
-And then execute:
-```bash
-$ bundle
+## Getting started
+
+### Adding a column to manage order
+
+To manage the order of records, you'll need to create a column in your database. A key feature of this gem is that it generates the order as a string!
+
+```rb
+# example
+
+create_table :tasks do |t|
+  t.string :name
+
+  # for MySQL
+  t.string :position, null: false, limit: 200, charset: 'ascii', collation: 'ascii_bin'
+
+  # for PostgreSQL
+  t.string :position, null: false, limit: 200, collation: 'C'
+
+  # for SQLite3
+  t.string :position, null: false, collation: 'binary'
+end
+add_index :tasks, :position, unique: true
+
 ```
 
-Or install it yourself as:
-```bash
-$ gem install narabikae
+#### Key points to consider when creating the column:
+
+- 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.
+
+- It is recommended to apply both NOT NULL and UNIQUE constraints.
+
+  This ensures data integrity and efficient ordering.
+
+- Explicitly set a character limit for the column.
+
+  Since this column will typically be indexed, it is important to set an appropriate length. This gem uses a base-62 numbering system to represent the order. In the example above, with a length limit of 200 characters, you can represent up to "62^200 unique order values", providing a huge range for ordered sequences.
+
+### Adding configuration to your model
+
+You only need to add one line as shown below!
+
+```rb
+class Task < ApplicationRecord
+  narabikae :position, size: 200
+
+  # arg1: optional
+  # .     Specify the field you want to use for ordering.
+  #       The default is :position.
+  #
+  # size: required
+  #       Used for validation of the internally generated order value.
+  #       This value should be equivalent to
+  #       the limit set in the DB column.
+end
 ```
 
+Once this is done, the position will be automatically set each time a Task model instance is saved!
+
+```rb
+Task.create([
+          { name: 'task-1' },
+          { name: 'task-2' },
+          { name: 'task-3' }
+     ])
+Task.order(:position).pluck(:name, :position)
+# => [["task-1", "a0"], ["task-3", "a1"], ["task-1", "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!
+
+## Usage Details
+
+### Reorder
+
+To insert an element after any specified item, use the `move_to_<field>_after` method.
+
+```ruby
+target = Task.create(name: 'target') # pos: 'a0'
+tasks  = Task.create([
+            { name: 'task-1' },      # pos: 'a1'
+            { name: 'task-2' }       # pos: 'a2'
+          ])
+
+target.move_to_position_after(tasks.last)
+# => true
+target.position
+# => 'a3'
+
+# If no argument is passed, it will be inserted at the end of the list
+tasks.first.move_to_position_after
+# => true
+
+Task.order(:position).pluck(:name, :position)
+# => [["task-2", "a2"], ["target", "a3"], ["task-1", "a4"]]
+```
+
+To insert an element before any specified item, use the `move_to_<field>_before` method.
+
+```ruby
+tasks  = Task.create([
+            { name: 'task-1' },      # pos: 'a0'
+            { name: 'task-2' }       # pos: 'a1'
+          ])
+target = Task.create(name: 'target') # pos: 'a2'
+
+target.move_to_position_before(tasks.first)
+target.position
+# => 'Zz'
+
+# If no argument is passed, it will be inserted at the start of the list
+tasks.last.move_to_position_before
+# => true
+
+Task.order(:position).pluck(:name, :position)
+# => [["task-2", "Zy"], ["target", "Zz"], ["task-1", "a0"]]
+```
+
+The method you will likely use most often is `move_to_<field>_between`, which moves an element between two others!
+
+```ruby
+tasks  = Task.create([
+            { name: 'task-1' },      # pos: 'a0'
+            { name: 'task-2' }       # pos: 'a1'
+          ])
+target = Task.create(name: 'target') # pos: 'a2'
+
+target.move_to_position_between(tasks.first, tasks.last)
+# => true
+
+target.position
+# => 'a0V'
+
+# If the first argument is nil, it behaves the same as `move_to_<field>_before`
+# ex: target.move_to_position_between(nil, tasks.last)
+
+# If the second argument is nil, it behaves the same as `move_to_<field>_after`
+# ex: target.move_to_position_between(tasks.first, nil)
+```
+
+### Scope
+
+You can use this when you want to manage independent positions within specific scopes, such as foreign keys.
+
+```ruby
+# example
+class Course < ApplicationRecord
+  has_many :chapters, dependent: :destroy
+end
+
+class Chapter < ApplicationRecord
+  belongs_to :course
+
+  narabikae :position, size: 100, scope: %i[course_id]
+end
+
+course = Course.create
+other_course = Course.create
+
+course.chapters.create
+other_course.chapters.create
+
+Chapter.pluck(:course_id, :position)
+# => [[1, "a0"], [2, "a0"]]
+```
+
+When the attribute declared in the scope is changed during an update, and there is no change in the value of the position field, the position will be automatically recalculated, and the record will move to the end of the list.
+
+```ruby
+course = Course.create
+other_course = Course.create
+
+course.chapters.create
+chapter = course.chapters.create # pos: 'a1'
+
+chapter.course = other_course
+chapter.save
+
+chapter.position
+# => 'a0'
+```
+
+### Retry generating position
+
+Imagine the drag-and-drop functionality found in GitHub Projects or Zenhub, where items can be reordered. If two users try to insert different tickets between the same two tickets at the same time, their positions may overlap. In this case, the system will internally retry generating a unique position (up to 10 times by default).
+
+If you want to increase the number of retries, you can use the "challenge" option to control the retry attempts, as shown below:
+
+```ruby
+ticket.move_to_position_between(t1, t2, challenge: 15)
+```
+
+> [!NOTE]
+> Currently, if two users write to the database at exactly the same time, the system may not detect the duplicate positions, and the process will continue without error. This issue will be revisited if there is demand for a more robust solution in the future.
+
+## Questions, Feedback
+
+Feel free to message me on Github (kazu-2020)
+
 ## Contributing
-Contribution directions go here.
+
+Please wait a moment... 🙏
 
 ## License
+
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/narabikae/active_record_extension.rb

@@ -0,0 +1,51 @@
+module Narabikae
+  class ActiveRecordExtension
+    def initialize(record, option)
+      @record = record
+      @option = option
+
+      @position_generator = Narabikae::Position.new(record, option)
+    end
+
+    def auto_set_position?
+      # 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)
+    rescue FractionalIndexer::Error
+      true
+    end
+
+    def set_position
+      record.send("#{option.field}=", position_generator.create_last_position)
+    end
+
+    def move_to_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)
+      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)
+      new_position = position_generator.find_position_between(prev_target, next_target, **args)
+      return false if new_position.blank?
+
+      record.send("#{option.field}=", new_position)
+      record.save
+    end
+
+    private
+
+    attr_reader :record, :option, :position_generator
+  end
+end

data/lib/narabikae/active_record_handler.rb

@@ -0,0 +1,31 @@
+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

data/lib/narabikae/configuration.rb

@@ -0,0 +1,19 @@
+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.
+    # @return [void]
+    def base=(int)
+      FractionalIndexer.configure do |config|
+        config.base = "base_#{int}".to_sym
+      end
+    end
+
+    # @return [Array] The string of digits configured for the FractionalIndexer.
+    # @see https://github.com/kazu-2020/fractional_indexer?tab=readme-ov-file#configure
+    def digits
+      FractionalIndexer.configuration.digits
+    end
+  end
+end

data/lib/narabikae/option.rb

@@ -0,0 +1,16 @@
+module Narabikae
+  class Option
+    attr_reader :field, :key_max_size, :scope
+
+    # 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: [])
+      @field = field.to_sym
+      @key_max_size = key_max_size.to_i
+      @scope = scope.is_a?(Array) ? scope.map(&:to_sym) : []
+    end
+  end
+end

data/lib/narabikae/option_store.rb

@@ -0,0 +1,25 @@
+module Narabikae
+  class OptionStore
+    attr_reader :store
+
+    def initialize
+      @store = {}
+    end
+
+    def register!(field, option)
+      if store.key?(field)
+        raise Narabikae::Error, "the field `#{field}` is already registered"
+      end
+      if option.scope.include?(field)
+        raise Narabikae::Error, "dependency loop detected: #{option.scope}"
+      end
+      if option.scope.any? { |s| store.key?(s) }
+        raise Narabikae::Error, "the scope `#{option.scope}` is already registered as other field"
+      end
+
+      store[field] = option
+
+      option
+    end
+  end
+end

data/lib/narabikae/position.rb

@@ -0,0 +1,151 @@
+module Narabikae
+  class Position
+    # Initializes a new instance of the Position class.
+    #
+    # @param record  [Object] Active Record object.
+    # @param option [Option]
+    def initialize(record, option)
+      @record = record
+      @option = option
+    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
+
+    # 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.
+    # @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)
+      # 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
+            )
+      return key if valid?(key)
+
+      (merged_args[:challenge] || 0).times do
+        key += random_fractional
+        return key if valid?(key)
+      end
+
+      nil
+    rescue FractionalIndexer::Error
+      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)
+    #
+    # @param target [#send(field)]
+    # @param args [Hash] Additional arguments.
+    # @option args [Integer] :challenge 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)
+      # 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
+            )
+      return key if valid?(key)
+
+      (merged_args[:challenge] || 0).times do
+        key += random_fractional
+        return key if valid?(key)
+      end
+
+      nil
+    rescue FractionalIndexer::Error
+      nil
+    end
+
+    # 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.
+    # @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)
+
+      prev_key, next_key = [ prev_target.send(option.field), next_target.send(option.field) ].minmax
+      key = FractionalIndexer.generate_key(
+              prev_key: prev_key,
+              next_key: next_key,
+            )
+      return key if valid?(key)
+
+      (merged_args[:challenge] || 0).times do
+        key += random_fractional
+        return key if valid?(key)
+      end
+
+      nil
+    rescue FractionalIndexer::Error
+      nil
+    end
+
+    private
+
+    attr_reader :record, :option
+
+    def capable?(key)
+      option.key_max_size >= key.size
+    end
+
+    def current_first_position
+      model.merge(model_scope).minimum(option.field)
+    end
+
+    def current_last_position
+      model.merge(model_scope).maximum(option.field)
+    end
+
+    def model
+      record.class.base_class
+    end
+
+    # generate a random fractional part
+    #
+    # @return [String] The random fractional part.
+    # @see https://github.com/kazu-2020/fractional_indexer?tab=readme-ov-file#fractional-part
+    def random_fractional
+      # `fractional` represents the fractional part, but to ensure that the last digit is not zero value (ex: base_62 => '0'), the range is set to [1..].
+      FractionalIndexer.configuration.digits[1..].sample
+    end
+
+    def model_scope
+      model.where(record.slice(*option.scope))
+    end
+
+    def uniq?(key)
+      model.where(option.field => key).merge(model_scope).empty?
+    end
+
+    def valid?(key)
+      return false if key.blank?
+
+      capable?(key) && uniq?(key)
+    end
+  end
+end

data/lib/narabikae/version.rb

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

data/lib/narabikae.rb

@@ -1,6 +1,75 @@
 require "narabikae/version"
-require "narabikae/railtie"
+
+require "narabikae/active_record_extension"
+require "narabikae/configuration"
+require "narabikae/option"
+require "narabikae/option_store"
+require "narabikae/position"
+
+require "fractional_indexer"
+require "active_support"
+require "active_record"
 
 module Narabikae
-  # Your code goes here...
+  class Error < StandardError; end
+
+  @configuration = Narabikae::Configuration.new
+
+  def self.configure
+    yield configuration if block_given?
+
+    configuration
+  end
+
+  def self.configuration
+    @configuration
+  end
+
+  module Extension
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def narabikae(field = :position, size:, scope: [])
+        option = narabikae_option_store.register!(
+                   field.to_sym,
+                   Narabikae::Option.new(field: field, key_max_size: size, scope: scope)
+                 )
+
+        before_create do
+          extension = Narabikae::ActiveRecordExtension.new(self, option)
+          extension.set_position
+        end
+
+        before_update do
+          extension = Narabikae::ActiveRecordExtension.new(self, option)
+          extension.set_position if extension.auto_set_position?
+        end
+
+        define_method :"move_to_#{field}_after" do |target = nil, **args|
+          extension = Narabikae::ActiveRecordExtension.new(self, option)
+          extension.move_to_after(target, **args)
+        end
+
+        define_method :"move_to_#{field}_before" do |target = nil, **args|
+          extension = Narabikae::ActiveRecordExtension.new(self, option)
+          extension.move_to_before(target, **args)
+        end
+
+        define_method :"move_to_#{field}_between" do |prev_target = nil, next_target = nil, **args|
+          extension = Narabikae::ActiveRecordExtension.new(self, option)
+          extension.move_to_between(prev_target, next_target, **args)
+        end
+      end
+
+      private
+
+      def narabikae_option_store
+        @_narabikae_option_store ||= Narabikae::OptionStore.new
+      end
+    end
+  end
+end
+
+ActiveSupport.on_load :active_record do |base|
+  base.include Narabikae::Extension
 end

metadata

@@ -1,35 +1,99 @@
 --- !ruby/object:Gem::Specification
 name: narabikae
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - matazou
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-10-01 00:00:00.000000000 Z
+date: 2024-10-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: rails
+  name: fractional_indexer
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 7.1.3.2
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.0.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: 5.0.0
+- !ruby/object:Gem::Dependency
+  name: rubocop-rails-omakase
+  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: rubocop-rspec
+  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: 7.1.3.2
+        version: '0'
 description: 'provides functionality similar to acts_as_list. However, by managing
   position using a fractional indexing system, it allows database record updates during
   reordering to be completed with only a single update (N = 1)!
@@ -44,9 +108,13 @@ files:
 - MIT-LICENSE
 - README.md
 - lib/narabikae.rb
-- lib/narabikae/railtie.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
+- lib/narabikae/position.rb
 - lib/narabikae/version.rb
-- lib/tasks/narabikae_tasks.rake
 homepage: https://github.com/kazu-2020/narabikae
 licenses:
 - MIT
@@ -72,7 +140,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.3
+rubygems_version: 3.5.9
 signing_key:
 specification_version: 4
 summary: provides simple position management and sorting functionality for Active

data/lib/narabikae/railtie.rb

@@ -1,4 +0,0 @@
-module Narabikae
-  class Railtie < ::Rails::Railtie
-  end
-end

data/lib/tasks/narabikae_tasks.rake

@@ -1,4 +0,0 @@
-# desc "Explaining what the task does"
-# task :narabikae do
-#   # Task goes here
-# end