feat(schema): add FractionalIndex type namespace (#105)

Ports the Greenspan/Figma base-62 fractional-indexing algorithm from
the horizon codebase as a clean @adobe/data namespace. Exposes
FractionalIndex.schema (usable as an ECS component), FractionalIndex.initial,
FractionalIndex.between(a, b), and FractionalIndex.betweenN(a, b, n).
Algorithm lives in per-file private helpers; 76 tests cover the full
spec including length-growth properties for bulk and sequential inserts.

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: krisnye

packages/data/src/schema/fractional-index/between-n.test.ts

@@ -0,0 +1,48 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, it, expect } from "vitest";
+import { betweenN } from "./between-n.js";
+import type { FractionalIndex } from "./fractional-index.js";
+
+const fi = (s: string) => s as FractionalIndex;
+
+describe("betweenN", () => {
+    it("returns empty array for n = 0", () => {
+        expect(betweenN(undefined, undefined, 0)).toEqual([]);
+    });
+
+    it("generates n keys between undefined bounds", () => {
+        expect(betweenN(undefined, undefined, 5).join(" ")).toBe("a0 a1 a2 a3 a4");
+    });
+
+    it("generates n keys after a lower bound", () => {
+        expect(betweenN(fi("a4"), undefined, 10).join(" ")).toBe(
+            "a5 a6 a7 a8 a9 aA aB aC aD aE",
+        );
+    });
+
+    it("generates n keys before an upper bound", () => {
+        expect(betweenN(undefined, fi("a0"), 5).join(" ")).toBe("Zv Zw Zx Zy Zz");
+    });
+
+    it("generates n keys between two bounds (shared integer part)", () => {
+        expect(betweenN(fi("a0"), fi("a2"), 20).join(" ")).toBe(
+            "a04 a08 a0G a0K a0O a0V a0Z a0d a0l a0t a1 a14 a18 a1G a1O a1V a1Z a1d a1l a1t",
+        );
+    });
+
+    it("keys are in strictly ascending order", () => {
+        const keys = betweenN(fi("a0"), fi("b00"), 50);
+        for (let i = 1; i < keys.length; i++) {
+            expect(keys[i] > keys[i - 1]).toBe(true);
+        }
+    });
+
+    it("bulk insert of 500 keys grows length by at most 2 chars", () => {
+        const start = fi("a0");
+        const end = betweenN(start, undefined, 1)[0];
+        const keys = betweenN(start, end, 500);
+        const baseline = Math.max(start.length, end.length);
+        const maxLen = keys.reduce((m, k) => Math.max(m, k.length), 0);
+        expect(maxLen).toBe(baseline + 2);
+    });
+});

packages/data/src/schema/fractional-index/between-n.ts

@@ -0,0 +1,41 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { FractionalIndex } from "./fractional-index.js";
+import { keyBetween } from "./key-between.js";
+
+export const betweenN = (
+    a: FractionalIndex | undefined,
+    b: FractionalIndex | undefined,
+    n: number,
+): FractionalIndex[] => {
+    if (n === 0) return [];
+    if (n === 1) return [keyBetween(a, b)];
+
+    if (b === undefined) {
+        let c = keyBetween(a, b);
+        const result = [c];
+        for (let i = 0; i < n - 1; i++) {
+            c = keyBetween(c, b);
+            result.push(c);
+        }
+        return result;
+    }
+
+    if (a === undefined) {
+        let c = keyBetween(a, b);
+        const result = [c];
+        for (let i = 0; i < n - 1; i++) {
+            c = keyBetween(a, c);
+            result.push(c);
+        }
+        result.reverse();
+        return result;
+    }
+
+    const mid = Math.floor(n / 2);
+    const c = keyBetween(a, b);
+    return [
+        ...betweenN(a, c, mid),
+        c,
+        ...betweenN(c, b, n - mid - 1),
+    ];
+};

packages/data/src/schema/fractional-index/between.test.ts

@@ -0,0 +1,77 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, it, expect } from "vitest";
+import { between } from "./between.js";
+import type { FractionalIndex } from "./fractional-index.js";
+
+const fi = (s: string) => s as FractionalIndex;
+
+describe("between", () => {
+    it("returns initial when both bounds are undefined", () => {
+        expect(between(undefined, undefined)).toBe("a0");
+    });
+
+    it("generates keys before an existing key", () => {
+        expect(between(undefined, fi("a0"))).toBe("Zz");
+        expect(between(undefined, fi("Y00"))).toBe("Xzzz");
+        expect(between(undefined, fi("a0V"))).toBe("a0");
+        expect(between(undefined, fi("b999"))).toBe("b99");
+        expect(between(undefined, fi("A000000000000000000000000001"))).toBe("A000000000000000000000000000V");
+    });
+
+    it("generates keys after an existing key", () => {
+        expect(between(fi("a0"), undefined)).toBe("a1");
+        expect(between(fi("bzz"), undefined)).toBe("c000");
+        expect(between(fi("zzzzzzzzzzzzzzzzzzzzzzzzzzy"), undefined)).toBe("zzzzzzzzzzzzzzzzzzzzzzzzzzz");
+        expect(between(fi("zzzzzzzzzzzzzzzzzzzzzzzzzzz"), undefined)).toBe("zzzzzzzzzzzzzzzzzzzzzzzzzzzV");
+    });
+
+    it("generates keys between two existing keys", () => {
+        expect(between(fi("a0"), fi("a1"))).toBe("a0V");
+        expect(between(fi("a0V"), fi("a1"))).toBe("a0l");
+        expect(between(fi("Zz"), fi("a0"))).toBe("ZzV");
+        expect(between(fi("Zz"), fi("a1"))).toBe("a0");
+        expect(between(fi("a0"), fi("a0V"))).toBe("a0G");
+        expect(between(fi("a0"), fi("a0G"))).toBe("a08");
+        expect(between(fi("b125"), fi("b129"))).toBe("b127");
+        expect(between(fi("a0"), fi("a1V"))).toBe("a1");
+        expect(between(fi("Zz"), fi("a01"))).toBe("a0");
+    });
+
+    it("throws for invalid key (smallest integer)", () => {
+        expect(() => between(undefined, fi("A00000000000000000000000000"))).toThrow("invalid order key");
+    });
+
+    it("throws for trailing zero in fractional part", () => {
+        expect(() => between(undefined, fi("b0"))).toThrow("invalid order key");
+        expect(() => between(fi("a00"), undefined)).toThrow("invalid order key");
+        expect(() => between(fi("a00"), fi("a1"))).toThrow("invalid order key");
+    });
+
+    it("throws when head is a digit instead of a letter", () => {
+        expect(() => between(fi("0"), fi("1"))).toThrow("Invalid order key head");
+    });
+
+    it("throws when a >= b", () => {
+        expect(() => between(fi("a1"), fi("a0"))).toThrow("Invalid key order: a >= b");
+    });
+
+    it("max length for 100k consecutive appends is 4 chars", () => {
+        let current: FractionalIndex = fi("a0");
+        let maxLen = current.length;
+        for (let i = 0; i < 100_000; i++) {
+            current = between(current, undefined);
+            if (current.length > maxLen) maxLen = current.length;
+        }
+        expect(maxLen).toBe(4);
+    });
+
+    it("max length for 500 consecutive head-inserts is 86 chars", () => {
+        let next: FractionalIndex | undefined;
+        let maxLen = 0;
+        for (let i = 0; i < 500; i++) {
+            next = between(fi("a0"), next);
+            if (next.length > maxLen) maxLen = next.length;
+        }
+        expect(maxLen).toBe(86);
+    });
+});

packages/data/src/schema/fractional-index/between.ts

@@ -0,0 +1,8 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { FractionalIndex } from "./fractional-index.js";
+import { keyBetween } from "./key-between.js";
+
+export const between = (
+    a: FractionalIndex | undefined,
+    b: FractionalIndex | undefined,
+): FractionalIndex => keyBetween(a, b);

packages/data/src/schema/fractional-index/decrement-integer.test.ts

@@ -0,0 +1,35 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, it, expect } from "vitest";
+import { decrementInteger } from "./decrement-integer.js";
+
+describe("decrementInteger", () => {
+    it("decrements simple keys", () => {
+        expect(decrementInteger("a1")).toBe("a0");
+        expect(decrementInteger("a2")).toBe("a1");
+    });
+
+    it("borrows across digit positions", () => {
+        expect(decrementInteger("b00")).toBe("az");
+        expect(decrementInteger("b10")).toBe("b0z");
+        expect(decrementInteger("b20")).toBe("b1z");
+        expect(decrementInteger("c000")).toBe("bzz");
+        expect(decrementInteger("dAC00")).toBe("dABzz");
+    });
+
+    it("crosses the positive/negative boundary", () => {
+        expect(decrementInteger("Zz")).toBe("Zy");
+        expect(decrementInteger("a0")).toBe("Zz");
+    });
+
+    it("handles transitions that lengthen the integer part (negative side)", () => {
+        expect(decrementInteger("Yzz")).toBe("Yzy");
+        expect(decrementInteger("Z0")).toBe("Yzz");
+        expect(decrementInteger("Xz00")).toBe("Xyzz");
+        expect(decrementInteger("Xz01")).toBe("Xz00");
+        expect(decrementInteger("Y00")).toBe("Xzzz");
+    });
+
+    it("returns undefined at the bottom of range", () => {
+        expect(decrementInteger("A00000000000000000000000000")).toBeUndefined();
+    });
+});

packages/data/src/schema/fractional-index/decrement-integer.ts

@@ -0,0 +1,26 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { digits } from "./digits.js";
+import { validateInteger } from "./validate-integer.js";
+
+export const decrementInteger = (x: string): string | undefined => {
+    validateInteger(x);
+    const [head, ...digs] = x.split("");
+    let borrow = true;
+    for (let i = digs.length - 1; borrow && i >= 0; i--) {
+        const d = digits.indexOf(digs[i]) - 1;
+        if (d === -1) {
+            digs[i] = digits.slice(-1);
+        } else {
+            digs[i] = digits.charAt(d);
+            borrow = false;
+        }
+    }
+    if (borrow) {
+        if (head === "a") return "Z" + digits.slice(-1);
+        if (head === "A") return undefined;
+        const h = String.fromCharCode(head.charCodeAt(0) - 1);
+        if (h < "Z") digs.push(digits.slice(-1)); else digs.pop();
+        return h + digs.join("");
+    }
+    return head + digs.join("");
+};

packages/data/src/schema/fractional-index/digits.ts

@@ -0,0 +1,2 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+export const digits = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";

packages/data/src/schema/fractional-index/fractional-index.ts

@@ -0,0 +1,6 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { ToType } from "../to-type.js";
+import { schema } from "./schema.js";
+
+export type FractionalIndex = ToType<typeof schema>;
+export * as FractionalIndex from "./public.js";

packages/data/src/schema/fractional-index/increment-integer.test.ts

@@ -0,0 +1,39 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, it, expect } from "vitest";
+import { incrementInteger } from "./increment-integer.js";
+
+describe("incrementInteger", () => {
+    it("increments simple keys", () => {
+        expect(incrementInteger("a0")).toBe("a1");
+        expect(incrementInteger("a1")).toBe("a2");
+    });
+
+    it("carries across digit positions", () => {
+        expect(incrementInteger("az")).toBe("b00");
+        expect(incrementInteger("b0z")).toBe("b10");
+        expect(incrementInteger("b1z")).toBe("b20");
+        expect(incrementInteger("bzz")).toBe("c000");
+        expect(incrementInteger("dABzz")).toBe("dAC00");
+    });
+
+    it("crosses the negative/positive boundary", () => {
+        expect(incrementInteger("Zy")).toBe("Zz");
+        expect(incrementInteger("Zz")).toBe("a0");
+    });
+
+    it("handles transitions that shorten the integer part (negative side)", () => {
+        expect(incrementInteger("Yzy")).toBe("Yzz");
+        expect(incrementInteger("Yzz")).toBe("Z0");
+        expect(incrementInteger("Xyzz")).toBe("Xz00");
+        expect(incrementInteger("Xz00")).toBe("Xz01");
+        expect(incrementInteger("Xzzz")).toBe("Y00");
+    });
+
+    it("returns undefined at the top of range", () => {
+        expect(incrementInteger("zzzzzzzzzzzzzzzzzzzzzzzzzzz")).toBeUndefined();
+    });
+
+    it("throws on invalid integer length", () => {
+        expect(() => incrementInteger("b0")).toThrow("invalid integer part of order key");
+    });
+});

packages/data/src/schema/fractional-index/increment-integer.ts

@@ -0,0 +1,26 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { digits } from "./digits.js";
+import { validateInteger } from "./validate-integer.js";
+
+export const incrementInteger = (x: string): string | undefined => {
+    validateInteger(x);
+    const [head, ...digs] = x.split("");
+    let carry = true;
+    for (let i = digs.length - 1; carry && i >= 0; i--) {
+        const d = digits.indexOf(digs[i]) + 1;
+        if (d === digits.length) {
+            digs[i] = "0";
+        } else {
+            digs[i] = digits.charAt(d);
+            carry = false;
+        }
+    }
+    if (carry) {
+        if (head === "Z") return "a0";
+        if (head === "z") return undefined;
+        const h = String.fromCharCode(head.charCodeAt(0) + 1);
+        if (h > "a") digs.push("0"); else digs.pop();
+        return h + digs.join("");
+    }
+    return head + digs.join("");
+};