Narabikae

Narabikae(Japanese: δΈ¦γ³ζ›Ώγˆ) means "reorder". Like 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, 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

In your Gemfile

gem "narabikae"

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!

# 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

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!

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!

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.

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.

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!

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.

# 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.

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:

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

Please wait a moment... πŸ™

License

The gem is available as open source under the terms of the MIT License.