Bring library to parity with the JS reference v4.0.0

[lukemerrett]

What

Updates this library from its current state (equivalent to rocicorp/fractional-indexing ~v3.2.0) to parity with the JS reference v4.0.0, released June 2026.

• Breaking (matches JS v4.0.0): the head alphabet now defaults to digits itself, so custom alphabets produce self-contained keys — generate_key_between(None, None, digits='0123456789') returns '50', not 'a0'. Keys generated with the default Base62 alphabet are unchanged. The new BASE_52_DIGITS export can be passed as int_digits to restore the previous A-Z/a-z heads.
• New int_digits argument (JS v3.3.0) on generate_key_between(), generate_n_keys_between(), and validate_order_key() to customise the head alphabet; the hard-coded a-z/A-Z head logic is generalised accordingly.
• Bounds may now be passed in either order and are swapped as a convenience (JS #26), instead of raising.
• Alphabet validation (matches JS): at least 2 characters, strictly ascending character-code order, single-byte; int_digits must be even-length. Previously invalid alphabets were silently accepted and produced non-sorting keys; also, digits outside the alphabet leaked ValueError from str.index because the except IndexError guards were dead code. Everything now raises FIError.
• Two deliberate improvements over the JS reference:
  • a defaulted int_digits is validated too, so an odd-length digits with no explicit int_digits raises FIError (the JS version silently generates broken keys in that case);
  • generate_n_keys_between() rejects a negative n with FIError — previously (in both this library and the JS reference) a negative n silently returned a single key when one bound was None, and recursed until RecursionError when both bounds were set.
• Performance: cached per-alphabet digit-index dicts replace O(alphabet) str.index scans, and the midpoint uses integer arithmetic, dropping the decimal import (in the spirit of JS v3.4.0).

Testing

• tests.py is now a full port of the JS v4.0.0 test suite (default, base-10 self-headed, base-95, base-2, Latin-1, symbol alphabets, int_digits overrides, validation errors) plus 1000-insert ordering property tests and negative-n cases — 87 tests.
• Cross-language check: replayed 5 × 500-key random insertion sequences through both this branch and JS v4.0.0 — all 2,500 keys byte-for-byte identical across 5 alphabet configurations.
• CI workflow updated to a Python 3.8–3.13 matrix.

Suggested release: 0.2.0 (version already bumped in fractional_indexing.py).

🤖 Generated with Claude Code