fractional_indexer 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c3e15f1e2a102d07fb9fa39a650f28e959184a21bb347e8125df3c36437cfb5
-  data.tar.gz: c83b4e10bcf12bed2604dcc2b230f481c0ad46ce7bd6f2777f3cb1fad3b836ad
+  metadata.gz: 647cdf5b4ac5ad3835667390221cfb694a37be44b50f494326ecc1a4d5a75b75
+  data.tar.gz: 3496c2e7f1132bb5699a26d614e9a66999733caeddd4b4d0c463cdcf2977848b
 SHA512:
-  metadata.gz: ada9175bde75b29f21e7fe053cdcc0bb433c27c9fb9387de65d0b8816368f47a28108c410476b48f2bde9e5e4eb4855efe0aeef1fb0bce4291fd537a0403583b
-  data.tar.gz: 82ee500b85f2dd7ad0883e3fbdf7028141e335e47010e47b9d305837dd45fd6c55d7f6d2e6f12ec8e83ad01cc4790a57238e4a37e82583ee1838c11cc86ef591
+  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
 
@@ -31,135 +63,292 @@ Or install it yourself as:
 gem install fractional_indexer
 ```
 
-## Usage
+## Quick Start
+
+```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"
+
+# Step 3: Insert between two keys
+middle_key = FractionalIndexer.generate_key(prev_key: first_key, next_key: second_key)
+# => "a0V"
+
+# 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
 
-### Generate Order key
+The following diagram shows how `generate_key` determines which operation to perform:
 
-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).
+```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)"]
 
-The characters that can be used in the strings are available for review in `FractionalIndexer.configuration.digits`.
+    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
 
-### base
+```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
 
-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)
+```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
+```
 
-Note: base_10 is primarily intended for operational verification and debugging purposes.
+#### 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:
+
+```ruby
+# Repeatedly insert at the beginning
+key = FractionalIndexer.generate_key  # => "a0"
+puts "Initial: #{key}"
+
+5.times do |i|
+  key = FractionalIndexer.generate_key(prev_key: key, next_key: "a1")
+  puts "Insert #{i + 1}: #{key}"
+end
+
+# 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{|}~"
 ```
 
-## Order key
-
-This section explains the structure of the string that represents an Order Key.  
-An Order Key string is broadly divided into two parts: the integer part and the fractional part.
+## Related Projects
 
-Note: For ease of understanding, the explanation from here on will be based on the decimal system ('0' ~ '9')
+### narabikae
 
-### Integer Part
-
-The integer part of the Order Key begins with a `mandatory prefix` that indicates the number of digits. This prefix is represented by one of the letters A to Z or a to z.  
-a is 1 digit, b is 2 digits, c is 3 digits ...... and z represents 26 digits.  
-The number of characters following the prefix must match the number of digits indicated by the prefix.  
-For example, if the prefix is a, a valid key could be 'a8', and if the prefix is c, a valid key could be 'c135'.
+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
-'a9'    # Valid
-'b10'   # Valid
-'b9'    # Invalid (The prefix 'b' requires two digits)
-'c123'  # Valid
-'c12'   # Invalid (The prefix 'c' requires three digits)
-```
-
-Additionally, leveraging the characteristic that uppercase letters have a lower ASCII value than lowercase letters, a to z represent positive integers, while A to Z represent negative integers.
-
-### Fractional Part
-
-The Fractional Part refers to the portion of the string that follows the Integer Part, excluding the Integer Part itself.
+class Task < ApplicationRecord
+  narabikae :position, size: 200
+end
 
-```ruby
-'a3012'
-# 'a3' : Integer Part
-# '012': Fractional Part
-```
+# Move a task after another
+task.move_to_position_after(other_task)
 
-The Fractional Part cannot end with the first character of the base being used (e.g., '0' in base_10). This rule mirrors the mathematical principle that, for example, 0.3 and 0.30 represent the same value.
+# Move a task before another
+task.move_to_position_before(other_task)
 
-```ruby
-'a32'  # Valid
-'a320' # Invalid (The Fractional Part cannot end with '0' in base_10)
+# Move a task between two others
+task.move_to_position_between(task_a, task_b)
 ```
 
-This section clarifies the concept and rules regarding the Fractional Part of an Order Key, with examples to illustrate what constitutes a valid or invalid Fractional Part.
-
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at <https://github.com/kazu-2020/fractional_indexer>.
@@ -167,3 +356,7 @@ Bug reports and pull requests are welcome on GitHub at <https://github.com/kazu-
 ## 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
 

data/lib/fractional_indexer/version.rb

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

metadata

@@ -1,20 +1,19 @@
 --- !ruby/object:Gem::Specification
 name: fractional_indexer
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
 platform: ruby
 authors:
-- kazu
-autorequire:
-bindir: exe
+- matazou
+bindir: bin
 cert_chain: []
-date: 2024-03-10 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: []