@suaveplan/i18n-formatter-collator - Intl.Collator wrapper for the @suaveplan/i18n family — locale-aware string comparison and sorting (sensitivity, numeric-aware natural sort, case-first, ignorePunctuation, custom collation). Per-(locale, options-hash) cache, Zod-validated options, OTel histogram + cache-hit counter, structured I18nError mapping. Brand-new formatter — closes the gap from the original i18n-formatters change scope. Universal leaf package.

Summary

Wrapper around Intl.Collator for the @suaveplan/i18n family — locale-aware string comparison and sorting (sensitivity, numeric-aware natural sort, case-first, ignorePunctuation, custom collation).

This is a brand-new formatter in the i18n family — Intl.Collator was listed in the original i18n-formatters change scope but was never implemented in the monolith. This package closes that gap.

Documentation tree

formatter — CollatorFormatter and the compareStrings / formatCollation standalone helpers expose Intl.Collator for the `@su…
- formatter — CollatorFormatter and the compareStrings / formatCollation standalone helpers expose Intl.Collator for the `@su…
helpers — The three ergonomic helpers (compareCaseInsensitive, compareNumericAware, sortStrings) pre-bind compareStrings…
- helpers — The three ergonomic helpers (compareCaseInsensitive, compareNumericAware, sortStrings) pre-bind compareStrings…
observability — The Collator formatter exports two OpenTelemetry instruments and a small in-memory state ring so spec-conformance tests…
- observability — The Collator formatter exports two OpenTelemetry instruments and a small in-memory state ring so spec-conformance tests…

Why this exists

The 14-package i18n modular split (cross-cutting design 2026-05-05-i18n-modular-split.md) lifts each Intl.* wrapper into its own sibling package and adds the two formatters (Collator + Segmenter) that the original change scope listed but never shipped. Locale-aware comparison is the right primitive for sorting names and substring search, and is required by downstream consumers like @suaveplan/dedup and @suaveplan/react-data-table.

Install

bun add @suaveplan/i18n-formatter-collator

Quick Start

import {
    CollatorFormatter,
    compareStrings,
    formatCollation,
    sortStrings,
    compareCaseInsensitive,
    compareNumericAware,
} from "@suaveplan/i18n-formatter-collator";

compareStrings("apple", "banana", "en-GB"); // -1
sortStrings(["c", "a", "b"], "en-GB"); // ["a", "b", "c"]

compareCaseInsensitive("a", "A", "en-GB"); // 0
compareNumericAware("file2", "file10", "en-GB"); // -1

const f = new CollatorFormatter({ numeric: true });
f.sort(["log10.txt", "log2.txt", "log1.txt"], "en-GB");
// ["log1.txt", "log2.txt", "log10.txt"]

Modules

Subpath	Description
`@suaveplan/i18n-formatter-collator`	Root barrel — class + standalones + helpers + observability
`@suaveplan/i18n-formatter-collator/formatter`	`CollatorFormatter`, `compareStrings`, `formatCollation`, types, schema
`@suaveplan/i18n-formatter-collator/helpers`	`compareCaseInsensitive`, `compareNumericAware`, `sortStrings`

Modules Documentation

formatter.md — CollatorFormatter, compareStrings, formatCollation, clearCollatorCache
helpers.md — three ergonomic helpers
observability.md — OTel histogram + cache-hit counter

Public Surface (snapshot)

Export	Kind	Origin
`CollatorFormatter`	class	`formatter.ts`
`compareStrings`	function	`formatter.ts`
`formatCollation`	function	`formatter.ts`
`clearCollatorCache`	function	`formatter.ts`
`CollatorFormatterOptionsSchema`	Zod schema	`formatter.schemas.ts`
`CollatorFormatterOptions`	type	`formatter.types.ts`
`CollatorUsage`	type	`formatter.types.ts`
`CollatorSensitivity`	type	`formatter.types.ts`
`CollatorCaseFirst`	type	`formatter.types.ts`
`CollatorNumeric`	type	`formatter.types.ts`
`CollatorFormatterCacheKey`	type	`formatter.types.ts`
`compareCaseInsensitive`	function	`helpers.ts`
`compareNumericAware`	function	`helpers.ts`
`sortStrings`	function	`helpers.ts`
`recordCollatorFormat`	function	`observability.ts`
`recordCollatorCacheHit`	function	`observability.ts`
`getCollatorMetricsState`	function	`observability.ts`
`resetCollatorMetricsState`	function	`observability.ts`

Versioning

Part of the 14-package i18n modular-split rollout. Stays at 0.1.0 until the slim core (Wave 6) cuts the family 1.0.0 release.