Unicode Fold Key

A caller-policy Unicode comparison-key generator. Closes the silent duplicate-account and duplicate-row bug where two strings a human would call identical compare unequal because the comparison never accounted for canonical equivalence, case folding, or invisible characters.

THE SILENT FAILURE. Almost every system storing user-entered text eventually needs a same-or-different answer: is this username, email or product code already on file? `a.toLowerCase() === b.toLowerCase()` is the obvious implementation and it is wrong in ways that never surface as errors. A precomposed and a decomposed spelling of the same accented name are different strings. A zero-width joiner pasted from a document survives lowercasing. Turkish dotless i does not round-trip. The result is not a crash -- it is a second account, a duplicate row, a uniqueness constraint that was never really unique.

POLICY IS THE CALLER'S, AND IT IS EXPLICIT. There is no single right folding: an email local-part, a display name and a product SKU want different rules, and a library that picks for you is wrong for two of the three. You state the policy; the key is deterministic under it, and the policy travels with the key so a stored key can never be compared against one made under different rules.

VERIFICATION. An independent reviewer rebuilt this package from the README and the Unicode standard alone. Their rival implementation passed the suite UNCHANGED -- no failures, nothing relaxed -- and the same suite caught a naive implementation. That is the outcome the exercise is designed to produce and the only one of the batch that produced it cleanly: the documented contract is the real contract, complete enough to rebuild from.

VERIFIED: 156 tests, measured by running the suite, every mutation observed FAILING before restore.

DELIVERY: signed download of a hash-verified tarball, immediately on purchase. Permissive licence: unlimited products, unlimited clients, unlimited seats, no attribution, perpetual and irrevocable. One restriction, do not republish the source as source.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function foldKey(input: string, options: FoldKeyOptions): string;
  export function foldEqual(a: string, b: string, options: FoldKeyOptions): boolean;
  export function applyFullFold(input: string): string;
  export function stripInvisibles(input: string): string;
  export function hasUnpairedSurrogate(input: string): boolean;

  export type FoldWidthPolicy = 'distinguish' | 'unify';
  export type FoldLocalePolicy = 'root' | 'tr' | 'az';