105 lines
4.9 KiB
Markdown
105 lines
4.9 KiB
Markdown
# @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.
|
|
|
|
<!-- begin:auto-docs -->
|
|
## Documentation tree
|
|
|
|
- [formatter](./src/formatter/formatter.md) — `CollatorFormatter` and the `compareStrings` / `formatCollation` standalone helpers expose `Intl.Collator` for the `@su…
|
|
- [formatter](./src/formatter/formatter.md) — `CollatorFormatter` and the `compareStrings` / `formatCollation` standalone helpers expose `Intl.Collator` for the `@su…
|
|
- [helpers](./src/helpers/helpers.md) — The three ergonomic helpers (`compareCaseInsensitive`, `compareNumericAware`, `sortStrings`) pre-bind `compareStrings`…
|
|
- [helpers](./src/helpers/helpers.md) — The three ergonomic helpers (`compareCaseInsensitive`, `compareNumericAware`, `sortStrings`) pre-bind `compareStrings`…
|
|
- [observability](./src/observability/observability.md) — The Collator formatter exports two OpenTelemetry instruments and a small in-memory state ring so spec-conformance tests…
|
|
- [observability](./src/observability/observability.md) — The Collator formatter exports two OpenTelemetry instruments and a small in-memory state ring so spec-conformance tests…
|
|
<!-- end:auto-docs -->
|
|
|
|
## 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
|
|
|
|
```bash
|
|
bun add @suaveplan/i18n-formatter-collator
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
```ts
|
|
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](src/formatter.md) — `CollatorFormatter`, `compareStrings`, `formatCollation`, `clearCollatorCache`
|
|
- [helpers.md](src/helpers.md) — three ergonomic helpers
|
|
- [observability.md](src/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.
|
|
|