fractional_indexer 0.3.1 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0d3588d2624cbc372dd3013729e5543eeabf9ab227005bf5c7a02e59360d7dcb
-  data.tar.gz: 1b11cf313ea2e71ed55bab5f394fcab8d1797e08b7a86df7012bcfafe43d0f68
+  metadata.gz: 647cdf5b4ac5ad3835667390221cfb694a37be44b50f494326ecc1a4d5a75b75
+  data.tar.gz: 3496c2e7f1132bb5699a26d614e9a66999733caeddd4b4d0c463cdcf2977848b
 SHA512:
-  metadata.gz: d8735e7f53ea599b2a3cbfdaafd34cd2c854991c461d02b4383a7a47fb36ab956d9bbdbd80c0cf018ab668050133e0039c4e117e654cba77da2ee9fe964b70b9
-  data.tar.gz: 6b4c53291cb4fb77ebb3fb279531693a8b2c6c74dd1ad775e6bb69d19bd2e23d742a3316c9922df94dcaad24a3af0c260b14aa3caacf4b7f142844f1fb9537bc
+  metadata.gz: fdac9f7b6ebee39cdf765b81d5cb5c739632e1ad0b7de48e1b28f465a60a0b0afbdf1157ffe5df3f9ebddddca0d5b7d6c96323b5d80424e138ee36abcc1624da
+  data.tar.gz: 28bd39cf30678fed311bf1b9908ac76824b079859fa755bd8c2b181147ef3646dccbca8f257ee3ac763f0d2cff3f9f54b64bc398243d6ddcf7a3539a11da2155

data/README.md

@@ -3,13 +3,45 @@
 [![codecov](https://codecov.io/gh/kazu-2020/fractional_indexer/graph/badge.svg?token=OCCYE4EKT1)](https://codecov.io/gh/kazu-2020/fractional_indexer)
 [![test](https://github.com/kazu-2020/fractional_indexer/actions/workflows/ruby.yml/badge.svg?branch=main&event=push)](https://github.com/kazu-2020/fractional_indexer/actions/workflows/ruby.yml)
 
-> efficient data insertion and sorting through fractional indexing
+> Efficient data insertion and sorting through fractional indexing
 
-This gem is designed to achieve "[Realtime editing of ordered sequences](https://www.figma.com/blog/realtime-editing-of-ordered-sequences/#fractional-indexing)" as featured in a Figma blog post.
+## Overview
 
-Specifically, it implements Fractional Indexing as a means of managing order, realized through strings. By managing indexes as strings, it significantly delays the occurrence of index duplication that can arise when implementing Fractional Indexing with floating-point numbers. Additionally, using strings allows for the representation of a much larger range of numbers in a single digit compared to decimal numbers (by default, a single digit is represented in base-62).
+Fractional Indexer is a Ruby gem that implements **fractional indexing** for managing ordered sequences. Instead of using integer positions that require reindexing on insertion, it uses string-based keys that allow inserting items anywhere without affecting existing items.
 
-This gem was implemented based on the excellent article "[Implementing Fractional Indexing.](https://observablehq.com/@dgreensp/implementing-fractional-indexing)" I would like to express my gratitude to David Greenspan, the author of the article.
+### Why Fractional Indexing?
+
+**Traditional integer indexing** requires shifting all subsequent items when inserting:
+
+```
+Before:    [A:1] [B:2] [C:3]
+                  ↓
+Insert X between A and B
+                  ↓
+After:     [A:1] [X:2] [B:3] [C:4]  ← B and C must be updated!
+```
+
+**Fractional indexing** generates a key between existing keys without reindexing:
+
+```
+Before:    [A:"a0"] [B:"a1"] [C:"a2"]
+                      ↓
+Insert X between A and B
+                      ↓
+After:     [A:"a0"] [X:"a0V"] [B:"a1"] [C:"a2"]  ← No changes to B or C!
+```
+
+### Key Features
+
+- **No reindexing required** - Insert items between any two existing items
+- **String-based keys** - Avoids floating-point precision issues
+- **Configurable base** - Supports base-10, base-62 (default), and base-94
+- **Multiple key generation** - Generate multiple keys at once for batch operations
+
+This gem implements the concepts from "[Realtime editing of ordered sequences](https://www.figma.com/blog/realtime-editing-of-ordered-sequences/#fractional-indexing)" (Figma Engineering Blog).
+
+> [!TIP]
+> **Using Rails?** Check out [narabikae](https://github.com/kazu-2020/narabikae) - an Active Record integration that makes fractional indexing as simple as `task.move_to_position_after(other_task)`
 
 ## Installation
 
@@ -21,100 +53,310 @@ gem 'fractional_indexer'
 
 And then execute:
 
-    $ bundle
+```sh
+bundle
+```
 
 Or install it yourself as:
 
-    $ gem install fractional_indexer
+```sh
+gem install fractional_indexer
+```
+
+## Quick Start
 
-## Usage
+```ruby
+require 'fractional_indexer'
+
+# Step 1: Generate your first key
+first_key = FractionalIndexer.generate_key
+# => "a0"
+
+# Step 2: Generate the next key (for appending)
+second_key = FractionalIndexer.generate_key(prev_key: first_key)
+# => "a1"
 
-### Generate Order key
+# Step 3: Insert between two keys
+middle_key = FractionalIndexer.generate_key(prev_key: first_key, next_key: second_key)
+# => "a0V"
 
-To generate an order key, use the `FractionalIndexer.generate_key` method. This method can take two arguments: prev_key and next_key, both of which can be either nil or a string (excluding empty strings).
+# Result: first_key < middle_key < second_key
+# "a0" < "a0V" < "a1"
+```
+
+## How It Works
+
+### Order Key Structure
+
+An order key consists of two parts: an **integer part** and an optional **fractional part**.
+
+```
+"a3012"
+ │└┬┘└┬┘
+ │ │  └── Fractional Part: "012" (optional, for fine-grained positioning)
+ │ └───── Integer Digits: "3" (the numeric value)
+ └─────── Prefix: "a" (indicates 1-digit positive integer)
+```
+
+**Prefix rules:**
+- `a` to `z`: Positive integers (a=1 digit, b=2 digits, ..., z=26 digits)
+- `A` to `Z`: Negative integers (used for keys "before" zero)
+
+**Examples:**
+
+| Key | Integer Part | Fractional Part | Meaning |
+|-----|-------------|-----------------|---------|
+| `a5` | `a5` | (none) | Positive 1-digit: 5 |
+| `b12` | `b12` | (none) | Positive 2-digit: 12 |
+| `a3V` | `a3` | `V` | Between a3 and a4 |
+| `Zz` | `Zz` | (none) | Largest negative number |
+
+### Key Generation Flow
 
-The characters that can be used in the strings are available for review in `FractionalIndexer.configuration.digits`.
+The following diagram shows how `generate_key` determines which operation to perform:
+
+```mermaid
+flowchart TD
+    A[generate_key] --> B{prev_key and next_key?}
+    B -->|Both nil| C["Return 'a0'<br/>(initial key)"]
+    B -->|Only prev_key| D["Increment<br/>(next key after prev)"]
+    B -->|Only next_key| E["Decrement<br/>(key before next)"]
+    B -->|Both provided| F["Midpoint<br/>(key between both)"]
+
+    D --> G["a0 → a1 → a2 → ..."]
+    E --> H["... → Zy → Zz → a0"]
+    F --> I["a0, a2 → a1<br/>a0, a1 → a0V"]
+```
+
+## Usage
+
+### Basic Usage
+
+#### Generating a Single Key
 
 ```ruby
 require 'fractional_indexer'
 
-# create first order key
+# Create the first order key (when no keys exist)
 FractionalIndexer.generate_key
 # => "a0"
 
-# increment
+# Increment: generate key after a given key
 FractionalIndexer.generate_key(prev_key: 'a0')
 # => "a1"
 
-# decrement
+# Decrement: generate key before a given key
 FractionalIndexer.generate_key(next_key: 'a0')
 # => "Zz"
 
-# between prev_key and next_key
+# Between: generate key between two keys
 FractionalIndexer.generate_key(prev_key: 'a0', next_key: 'a2')
 # => "a1"
-
-# prev_key should be less than next_key
-FractionalIndexer.generate_key(prev_key: 'a2', next_key: 'a1')
-# => error
-FractionalIndexer.generate_key(prev_key: 'a1', next_key: 'a1')
-# => error
 ```
 
-### Generate Multiple Order keys
-
-To generate multiple order keys, use the `FractionalIndexer.generate_keys` method.
+#### Generating Multiple Keys
 
 ```ruby
-require 'fractional_indexer'
-
-# generate n order keys that sequentially follow a given prev_key.
+# Generate 5 keys after "b11"
 FractionalIndexer.generate_keys(prev_key: "b11", count: 5)
 # => ["b12", "b13", "b14", "b15", "b16"]
 
-# generate n order keys that sequentially precede a given next_key.
+# Generate 5 keys before "b11"
 FractionalIndexer.generate_keys(next_key: "b11", count: 5)
 # => ["b0w", "b0x", "b0y", "b0z", "b10"]
 
-# generate n order keys between the given prev_key and next_key.
+# Generate 5 keys between "b10" and "b11"
 FractionalIndexer.generate_keys(prev_key: "b10", next_key: "b11", count: 5)
 # => ["b108", "b10G", "b10V", "b10d", "b10l"]
 ```
 
-## Configure
+#### Error Handling
+
+```ruby
+# prev_key must be less than next_key
+FractionalIndexer.generate_key(prev_key: 'a2', next_key: 'a1')
+# => raises error
+
+# prev_key and next_key cannot be equal
+FractionalIndexer.generate_key(prev_key: 'a1', next_key: 'a1')
+# => raises error
+```
+
+### Practical Examples
+
+#### Example 1: Task List Management
+
+```ruby
+# Managing a todo list with fractional indexing
+tasks = []
+
+# Add initial tasks
+tasks << { id: 1, title: "Write code",    position: FractionalIndexer.generate_key }
+tasks << { id: 2, title: "Write tests",   position: FractionalIndexer.generate_key(prev_key: tasks.last[:position]) }
+tasks << { id: 3, title: "Deploy",        position: FractionalIndexer.generate_key(prev_key: tasks.last[:position]) }
+
+tasks.each { |t| puts "#{t[:position]}: #{t[:title]}" }
+# a0: Write code
+# a1: Write tests
+# a2: Deploy
+
+# Insert "Code review" between "Write tests" and "Deploy"
+new_position = FractionalIndexer.generate_key(
+  prev_key: tasks[1][:position],  # "a1"
+  next_key: tasks[2][:position]   # "a2"
+)
+tasks << { id: 4, title: "Code review", position: new_position }
+
+# Sort by position
+tasks.sort_by! { |t| t[:position] }
+tasks.each { |t| puts "#{t[:position]}: #{t[:title]}" }
+# a0: Write code
+# a1: Write tests
+# a1V: Code review   ← Inserted without changing other positions!
+# a2: Deploy
+```
+
+#### Example 2: Prepending and Appending
+
+```ruby
+# Start with a middle item
+items = [{ name: "B", pos: FractionalIndexer.generate_key }]
+# items[0][:pos] => "a0"
+
+# Append to the end (only prev_key)
+items << { name: "C", pos: FractionalIndexer.generate_key(prev_key: items.last[:pos]) }
+# items[1][:pos] => "a1"
+
+# Prepend to the beginning (only next_key)
+items.unshift({ name: "A", pos: FractionalIndexer.generate_key(next_key: items.first[:pos]) })
+# items[0][:pos] => "Zz"
+
+items.sort_by { |i| i[:pos] }.each { |i| puts "#{i[:pos]}: #{i[:name]}" }
+# Zz: A
+# a0: B
+# a1: C
+```
+
+#### Example 3: Batch Insertion
+
+```ruby
+# Insert 5 items between two existing items at once
+existing = [
+  { name: "First",  pos: "a0" },
+  { name: "Last",   pos: "a1" }
+]
+
+# Generate 5 keys between "a0" and "a1"
+new_positions = FractionalIndexer.generate_keys(
+  prev_key: existing[0][:pos],
+  next_key: existing[1][:pos],
+  count: 5
+)
+# => ["a08", "a0G", "a0V", "a0d", "a0l"]
+
+new_items = new_positions.map.with_index do |pos, i|
+  { name: "Item #{i + 1}", pos: pos }
+end
+
+all_items = (existing + new_items).sort_by { |i| i[:pos] }
+all_items.each { |i| puts "#{i[:pos]}: #{i[:name]}" }
+# a0: First
+# a08: Item 1
+# a0G: Item 2
+# a0V: Item 3
+# a0d: Item 4
+# a0l: Item 5
+# a1: Last
+```
+
+#### Example 4: Key Growth Over Time
+
+When repeatedly inserting at the same position, keys grow longer to maintain precision:
 
-### base
+```ruby
+# Repeatedly insert at the beginning
+key = FractionalIndexer.generate_key  # => "a0"
+puts "Initial: #{key}"
 
-You can set the base (number system) used to represent each digit. The possible values are :base_10, :base_62, and :base_94. (The default is :base_62.)
+5.times do |i|
+  key = FractionalIndexer.generate_key(prev_key: key, next_key: "a1")
+  puts "Insert #{i + 1}: #{key}"
+end
 
-Note: base_10 is primarily intended for operational verification and debugging purposes.
+# Initial: a0
+# Insert 1: a0V
+# Insert 2: a0l
+# Insert 3: a0t
+# Insert 4: a0x
+# Insert 5: a0z
+```
+
+## Configuration
+
+### Base System
+
+You can configure the base (number system) used to represent each digit. The possible values are `:base_10`, `:base_62` (default), and `:base_94`.
+
+| Base | Characters | Use Case |
+|------|-----------|----------|
+| `:base_10` | `0-9` | Debugging, human-readable |
+| `:base_62` | `0-9`, `A-Z`, `a-z` | General use (default) |
+| `:base_94` | All printable ASCII | Maximum density |
 
 ```ruby
 require 'fractional_indexer'
 
+# Base 10 (for debugging)
 FractionalIndexer.configure do |config|
   config.base = :base_10
 end
 FractionalIndexer.configuration.digits.join
 # => "0123456789"
 
+# Base 62 (default)
 FractionalIndexer.configure do |config|
   config.base = :base_62
 end
 FractionalIndexer.configuration.digits.join
 # => "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
 
+# Base 94 (maximum density)
 FractionalIndexer.configure do |config|
   config.base = :base_94
 end
 FractionalIndexer.configuration.digits.join
-# => "!\"\#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_`abcdefghijklmnopqrstuvwxyz{|}~"
+# => "!\"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_`abcdefghijklmnopqrstuvwxyz{|}~"
+```
+
+## Related Projects
+
+### narabikae
+
+If you're using **Ruby on Rails** with **Active Record**, check out [narabikae](https://github.com/kazu-2020/narabikae) - a gem that integrates Fractional Indexer directly into your models for seamless ordering.
+
+```ruby
+class Task < ApplicationRecord
+  narabikae :position, size: 200
+end
+
+# Move a task after another
+task.move_to_position_after(other_task)
+
+# Move a task before another
+task.move_to_position_before(other_task)
+
+# Move a task between two others
+task.move_to_position_between(task_a, task_b)
 ```
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/kazu-2020/fractional_indexer.
+Bug reports and pull requests are welcome on GitHub at <https://github.com/kazu-2020/fractional_indexer>.
 
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Acknowledgments
+
+This gem was implemented based on the excellent article "[Implementing Fractional Indexing](https://observablehq.com/@dgreensp/implementing-fractional-indexing)" by David Greenspan. Thank you for the clear explanation and reference implementation!

data/lib/fractional_indexer/order_key.rb

@@ -3,8 +3,8 @@
 module FractionalIndexer
   class OrderKey
     INTEGER_BASE_DIGIT = 2
-    POSITIVE_SIGNS = ("a".."z").freeze
-    NEGATIVE_SIGNS = ("A".."Z").freeze
+    POSITIVE_SIGNS = ("a".."z")
+    NEGATIVE_SIGNS = ("A".."Z")
 
     attr_reader :key
 
@@ -58,6 +58,10 @@ module FractionalIndexer
       integer == minimum_integer
     end
 
+    def minimum?
+      minimum_integer? && fractional.empty?
+    end
+
     def present?
       !(key.nil? || key.empty?)
     end
@@ -78,14 +82,14 @@ module FractionalIndexer
       "z#{digits.last * POSITIVE_SIGNS.count}"
     end
 
-    def raise_error(description = nil)
-      raise Error, "invalid order key: '#{key}' description: #{description}"
-    end
-
     def minimum_integer
       "A#{digits.first * POSITIVE_SIGNS.count}"
     end
 
+    def raise_error(description = nil)
+      raise Error, "invalid order key: '#{key}' description: #{description}"
+    end
+
     def valid_fractional?(fractional)
       !fractional.end_with?(digits.first)
     end

data/lib/fractional_indexer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FractionalIndexer
-  VERSION = "0.3.1"
+  VERSION = "0.4.1"
 end

data/lib/fractional_indexer.rb

@@ -91,9 +91,20 @@ module FractionalIndexer
   end
 
   def self.decrement(order_key)
+    # NOTE: edge case
+    # If an Order key does not have a fractional part and its integer part is equal to
+    # the minimum value (for example, in base_62: 'A00000000000000000000000000'),
+    # further decrement operations become impossible and will fail.
+    # However, this situation is typically unlikely to occur.
+    if order_key.minimum?
+      raise Error, "order key not decremented: #{order_key} is the minimum value"
+    end
     return order_key.integer + Midpointer.execute("", order_key.fractional) if order_key.minimum_integer?
 
-    order_key.integer < order_key.key ? order_key.integer : order_key.decrement
+    decremented_order_key = OrderKey.new(order_key.integer < order_key.key ? order_key.integer : order_key.decrement)
+    return decremented_order_key.integer + Midpointer.execute if decremented_order_key.minimum?
+
+    decremented_order_key.key
   end
 
   def self.increment(order_key)

metadata

@@ -1,20 +1,19 @@
 --- !ruby/object:Gem::Specification
 name: fractional_indexer
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.1
 platform: ruby
 authors:
-- kazu
-autorequire:
-bindir: exe
+- matazou
+bindir: bin
 cert_chain: []
-date: 2024-03-07 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: |
   FractionalIndexer is a Ruby gem designed to leverage fractional indexing for ordering within lists or data structures.
   it enables efficient sorting and insertion of large volumes of data.
 email:
-- matazou@gmail.com
+- 64774307+kazu-2020@users.noreply.github.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -32,9 +31,12 @@ homepage: https://github.com/kazu-2020/fractional_indexer
 licenses:
 - MIT
 metadata:
+  homepage_uri: https://github.com/kazu-2020/fractional_indexer
+  changelog_uri: https://github.com/kazu-2020/fractional_indexer/releases
+  bug_tracker_uri: https://github.com/kazu-2020/fractional_indexer/issues
   source_code_uri: https://github.com/kazu-2020/fractional_indexer
-  changelog_uri: https://github.com/kazu-2020/fractional_indexer
-post_install_message:
+  allowed_push_host: https://rubygems.org/
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -42,15 +44,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.4.10
-signing_key:
+rubygems_version: 3.6.7
 specification_version: 4
 summary: efficient data insertion and sorting through fractional indexing
 test_files: []