Fractional indexing reference

Use the fractional-indexing package to create lexicographically sortable keys without renumbering every item after an insertion. This reference covers validateOrderKey, generateKeyBetween, and generateNKeysBetween.

API boundary

The functions accept an existing key before (a) and after (b). Use null or undefined for an open end. Keys are compared lexicographically, and the default alphabet is the package's base-62 digit set.

validateOrderKey

validateOrderKey(key: string, digits?: string): void

Validates the characters, integer part, and fractional ending of a key. It throws Error("invalid order key: ...") for an invalid key.

validateOrderKey("a0");
// returns undefined when valid
validateOrderKey("not valid!");
// throws: Error("invalid order key: not valid!")

The reserved minimum integer form A followed by 26 copies of the first digit is invalid. Use the same digits value for validation and generation.

generateKeyBetween

generateKeyBetween(
  a: string | null | undefined,
  b: string | null | undefined,
  digits?: string,
): string

Returns one key strictly between a and b. Omit a to insert before b, omit b to insert after a, and omit both to start a sequence.

const first = generateKeyBetween(null, null);
const next = generateKeyBetween(first, null);
const inserted = generateKeyBetween(first, next);

inserted sorts after first and before next. Non-null endpoints must be valid and a must sort before b. Otherwise the function throws. An integer boundary can also produce cannot increment any more or cannot decrement any more.

generateNKeysBetween

generateNKeysBetween(
  a: string | null | undefined,
  b: string | null | undefined,
  n: number,
  digits?: string,
): string[]

Returns n distinct keys in sorted order under the same endpoint preconditions.

const keys = generateNKeysBetween("a0", "aZ", 3);
// a0 < keys[0] < keys[1] < keys[2] < aZ
const empty = generateNKeysBetween(null, null, 0);
// []

With an open end, the function creates consecutive integer keys. With two endpoints, it recursively splits the interval around a midpoint and returns the combined result in order. n must be non-negative.

Custom alphabets

Pass an ascending-character digits string to all functions in one ordering domain. The package relies on character-code order for comparisons and midpoint generation.

const keys = generateNKeysBetween(null, null, 2, "0123456789");

Do not mix keys generated with different alphabets in one sorted collection.

Failure handling

Next, see the Mermaid conversion API or the ExcalidrawAPI reference.