fractional-indexing

fractional-indexing implements the fractional indexing technique for generating short, lexicographically sortable string keys that fall between any two existing keys. This lets applications assign an ordering position to an item (a row, a card, a list entry) without renumbering every other item when something is inserted, moved, or reordered — a pattern originally popularized by Figma’s realtime editing of ordered sequences and now common in CRDT-based and collaborative software.

The library exposes generateKeyBetween for a single insertion and generateNKeysBetween for evenly spacing multiple new keys at once, both supporting a custom digit alphabet so keys can be tuned for a given storage backend’s collation rules. It is deliberately tiny, dependency-free, and released under CC0-1.0, making it easy to vendor or embed directly into sync engines, local-first apps, and ordered-list data models.

What You Get

• generateKeyBetween(a, b) to produce a single new ordering key between two existing keys (or at either end of a list)
• generateNKeysBetween(a, b, n) to generate multiple evenly-spaced keys in one call, producing shorter keys than repeated single calls
• Configurable digit alphabets so keys can match a target database’s or app’s sort/collation behavior
• Variable-length integer encoding plus a prepend/append optimization to keep keys short over time
• Zero runtime dependencies and a tiny, auditable ~580-line implementation

Common Use Cases

• Ordering rows in a Kanban board or task list where cards can be dragged and reordered without a full renumbering write
• Implementing CRDT-friendly, realtime collaborative list ordering (e.g. Figma-style layer lists) across multiple clients
• Assigning stable sort keys in local-first or offline-sync data models where positions must merge without conflicts
• Backing drag-and-drop reordering UIs on top of a database that sorts by a single indexed string column

Under The Hood

Architecture - The entire library is a single ESM module (src/index.js, ~580 lines) built around a midpoint(a, b, digits, lookup) function that computes a lexicographically-between string given two boundary keys and a digit alphabet, plus integer encode/decode helpers (integerToOrderKey/orderKeyToInteger-style logic) that implement the variable-length integer scheme from David Greenspan’s original Observable notebook; generateKeyBetween and generateNKeysBetween are thin public wrappers over this core.

Tech Stack - Plain, dependency-free JavaScript (ESM type: module) with TypeScript used only for generating .d.ts declaration files via tsc --emitDeclarationOnly; there are no runtime dependencies at all, and the package ships only src/index.js plus its generated types.

Code Quality - src/test.js (364 lines, run directly with node src/test.js, no test framework dependency) exercises midpoint generation, N-key generation, custom alphabets, and error cases like out-of-order or trailing-zero keys; a per-alphabet Uint8Array lookup cache (getDigitIndex) is used to keep digit-to-value lookups O(1) instead of String.indexOf, showing deliberate performance tuning for a hot-path utility.

API Design - The two-function public surface (generateKeyBetween, generateNKeysBetween) is intentionally minimal and requires no setup or configuration object for the common case, with optional digits/intDigits parameters only needed when customizing the alphabet; the README documents exact input/output examples for every function, making the learning curve very shallow despite the non-obvious underlying algorithm.