first commit

docs/localization/i18n/i18n-formatter-number/README.md

@@ -0,0 +1,113 @@
+# @suaveplan/i18n-formatter-number - Locale-aware number formatting backed by Intl.NumberFormat. Class wrapper + standalone helper + ergonomic helpers (formatPercent, formatCompact, formatUnit), Zod-validated options, per-(locale, options-hash) cache, OTel histogram + cache-hit counter. Wave 3 of the @suaveplan/i18n modular split.
+
+## Summary
+
+Locale-aware number formatting backed by `Intl.NumberFormat`. Wave 3
+of the 14-package i18n modular split. Provides both a class
+(`NumberFormatter`) and a standalone helper (`formatNumber`) plus
+ergonomic shortcuts (`formatPercent`, `formatCompact`, `formatUnit`)
+on top of a per-`(locale, options-hash)` cache, Zod-validated options,
+and the canonical OTel histogram + cache-hit counter that every Wave 3
+formatter package emits.
+
+<!-- begin:auto-docs -->
+## Documentation tree
+
+- [formatter](./src/formatter/formatter.md) — Locale-aware number formatting backed by `Intl.NumberFormat`. The package exposes both a class (`NumberFormatter` — con…
+  - [formatter](./src/formatter/formatter.md) — Locale-aware number formatting backed by `Intl.NumberFormat`. The package exposes both a class (`NumberFormatter` — con…
+- [helpers](./src/helpers/helpers.md) — Pre-bound shortcuts over `formatNumber` and `Intl.NumberFormat` for the three most-asked number-formatting shapes: perc…
+  - [helpers](./src/helpers/helpers.md) — Pre-bound shortcuts over `formatNumber` and `Intl.NumberFormat` for the three most-asked number-formatting shapes: perc…
+- [observability](./src/observability/observability.md) — Per-package OpenTelemetry instruments for `@suaveplan/i18n-formatter-number`. Exposes a histogram (`i18n.format.number.…
+  - [observability](./src/observability/observability.md) — Per-package OpenTelemetry instruments for `@suaveplan/i18n-formatter-number`. Exposes a histogram (`i18n.format.number.…
+<!-- end:auto-docs -->
+
+## Why this exists
+
+Each `Intl.*` wrapper lives in its own sibling package so consumers
+can pull only the formatters they actually use. This package is the
+canonical Wave 3 template — every other formatter package mirrors its
+layout (per-(locale, options-hash) cache, Zod schema, OTel metrics,
+helper + class twin surface). `@suaveplan/i18n-formatter-currency`
+declares a workspace dep on this package because currency formatting
+is `Intl.NumberFormat({ style: "currency", ... })`.
+
+## Install
+
+```bash
+bun add @suaveplan/i18n-formatter-number
+```
+
+## Quick Start
+
+```ts
+import {
+    formatCompact,
+    formatNumber,
+    formatPercent,
+    NumberFormatter,
+} from "@suaveplan/i18n-formatter-number";
+
+formatNumber(1234567.89, "en-GB", {
+    style: "decimal",
+    maximumFractionDigits: 2,
+}); // → "1,234,567.89"
+
+formatPercent(0.5, "en-GB"); // → "50%"
+formatCompact(1500, "en-US"); // → "1.5K"
+
+const usd = new NumberFormatter({
+    style: "currency",
+    currency: "USD",
+});
+usd.format(42.5, "en-US"); // → "$42.50"
+```
+
+## Modules
+
+| Subpath | Description |
+|---|---|
+| `@suaveplan/i18n-formatter-number` | Root barrel — class + standalone + helpers + observability |
+| `@suaveplan/i18n-formatter-number/formatter` | `NumberFormatter`, `formatNumber`, `clearNumberFormatterCache`, types, schema |
+| `@suaveplan/i18n-formatter-number/helpers` | `formatPercent`, `formatCompact`, `formatUnit` only |
+
+## Modules Documentation
+
+- [formatter.md](src/formatter.md) — `NumberFormatter` class + `formatNumber`
+- [helpers.md](src/helpers.md) — `formatPercent`, `formatCompact`, `formatUnit`
+- [observability.md](src/observability.md) — OTel histogram + cache-hit counter
+
+## Public Surface (snapshot)
+
+| Export | Kind | Origin |
+|---|---|---|
+| `NumberFormatter` | class | `formatter.ts` |
+| `formatNumber` | function | `formatter.ts` |
+| `clearNumberFormatterCache` | function | `formatter.ts` |
+| `NumberFormatterOptionsSchema` | const | `formatter.ts` |
+| `NumberFormatterStyle` | type | `formatter.types.ts` |
+| `NumberFormatterNotation` | type | `formatter.types.ts` |
+| `NumberFormatterCurrencyDisplay` | type | `formatter.types.ts` |
+| `NumberFormatterSignDisplay` | type | `formatter.types.ts` |
+| `NumberFormatterOptions` | type | `formatter.types.ts` |
+| `NumberFormatterCacheKey` | type | `formatter.types.ts` |
+| `formatPercent` | function | `helpers.ts` |
+| `formatCompact` | function | `helpers.ts` |
+| `formatUnit` | function | `helpers.ts` |
+| `recordNumberFormat` | function | `observability.ts` |
+| `recordNumberCacheHit` | function | `observability.ts` |
+| `getNumberFormatMetricsState` | function | `observability.ts` |
+| `resetNumberFormatMetricsState` | function | `observability.ts` |
+
+## Versioning
+
+This package is part of the i18n modular-split rollout. Stays at
+`0.1.0` until the slim core (Wave 6) cuts the family `1.0.0` release.
+
+## Wave 3 Scope
+
+This package is one of eight Wave 3 formatter packages. Pure
+addition — `packages/i18n/i18n/src/formatting/number/` is preserved
+in the monolith until Wave 6 deletes it. Both copies coexist during
+Waves 3–5; downstream consumers continue to import from the monolith
+and observe no behaviour change.
+