first commit

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

@@ -0,0 +1,119 @@
+# @suaveplan/i18n-formatter-currency - Locale-aware currency formatting backed by Intl.NumberFormat({ style: 'currency' }). Class wrapper + standalone helper + currency-info helpers (getCurrencySymbol, getCurrencyName, getCurrencyInfo), Zod-validated ISO 4217 codes, per-(locale, currency, options-hash) cache, OTel histogram + cache-hit counter. Wave 3 of the @suaveplan/i18n modular split.
+
+## Summary
+
+Locale-aware currency formatting backed by `Intl.NumberFormat` with
+`style: "currency"`. Wave 3 of the 14-package i18n modular split.
+Provides both a class (`CurrencyFormatter`) and a standalone helper
+(`formatCurrency`) plus value-only formatting (`formatCurrencyValue`)
+and currency-info helpers (`getCurrencySymbol`, `getCurrencyName`,
+`getCurrencyInfo`) on top of a per-`(locale, currency, options-hash)`
+cache, Zod-validated ISO 4217 codes, 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 currency formatting backed by `Intl.NumberFormat({ style: "currency" })`. The package exposes both a class…
+  - [formatter](./src/formatter/formatter.md) — Locale-aware currency formatting backed by `Intl.NumberFormat({ style: "currency" })`. The package exposes both a class…
+- [helpers](./src/helpers/helpers.md) — Currency-info helpers exposing structured metadata about ISO 4217 codes via `Intl.NumberFormat.formatToParts`. Use thes…
+  - [helpers](./src/helpers/helpers.md) — Currency-info helpers exposing structured metadata about ISO 4217 codes via `Intl.NumberFormat.formatToParts`. Use thes…
+- [observability](./src/observability/observability.md) — Per-package OpenTelemetry instruments for `@suaveplan/i18n-formatter-currency`. Exposes a histogram (`i18n.format.curre…
+  - [observability](./src/observability/observability.md) — Per-package OpenTelemetry instruments for `@suaveplan/i18n-formatter-currency`. Exposes a histogram (`i18n.format.curre…
+<!-- 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
+only Wave 3 formatter with an intra-formatter dependency: it depends
+on `@suaveplan/i18n-formatter-number workspace:^` because currency
+formatting is `Intl.NumberFormat({ style: "currency" })`. The dep is
+pinned in `package.json` per the design doc §3 so the slim core
+(Wave 6) can wire `formatCurrency` and `formatNumber` consistently
+into the default `FormatBridge`.
+
+## Install
+
+```bash
+bun add @suaveplan/i18n-formatter-currency
+```
+
+## Quick Start
+
+```ts
+import {
+    CurrencyFormatter,
+    formatCurrency,
+    formatCurrencyValue,
+    getCurrencyInfo,
+    getCurrencyName,
+    getCurrencySymbol,
+} from "@suaveplan/i18n-formatter-currency";
+
+formatCurrency(1234.56, "USD", "en");           // → "$1,234.56"
+formatCurrency(1234.56, "EUR", "de");           // → "1.234,56 €"
+formatCurrency(100, "CHF", "en", { display: "code" }); // → "CHF 100.00"
+
+formatCurrencyValue(9.99, "USD", "en");         // → "9.99"
+
+getCurrencySymbol("GBP", "en");                 // → "£"
+getCurrencyName("USD", "fr");                   // → "dollar des États-Unis"
+getCurrencyInfo("EUR", "en-US");
+// → { code: "EUR", symbol: "€", name: "Euro", decimalDigits: 2 }
+
+const usd = new CurrencyFormatter("USD", { minimumFractionDigits: 2 });
+usd.format(42, "en-US");                        // → "$42.00"
+```
+
+## Modules
+
+| Subpath | Description |
+|---|---|
+| `@suaveplan/i18n-formatter-currency` | Root barrel — class + standalone + helpers + observability |
+| `@suaveplan/i18n-formatter-currency/formatter` | `CurrencyFormatter`, `formatCurrency`, `formatCurrencyValue`, types, schemas |
+| `@suaveplan/i18n-formatter-currency/helpers` | `getCurrencySymbol`, `getCurrencyName`, `getCurrencyInfo` only |
+
+## Modules Documentation
+
++ [formatter.md](src/formatter.md) — `CurrencyFormatter`, `formatCurrency`, `formatCurrencyValue`
++ [helpers.md](src/helpers.md) — `getCurrencySymbol`, `getCurrencyName`, `getCurrencyInfo`
++ [observability.md](src/observability.md) — OTel histogram + cache-hit counter
+
+## Public Surface (snapshot)
+
+| Export | Kind | Origin |
+|---|---|---|
+| `CurrencyFormatter` | class | `formatter.ts` |
+| `formatCurrency` | function | `formatter.ts` |
+| `formatCurrencyValue` | function | `formatter.ts` |
+| `clearCurrencyFormatterCache` | function | `formatter.ts` |
+| `toBcp47` | function | `formatter.ts` |
+| `CurrencyCodeSchema` | const | `formatter.schemas.ts` |
+| `CurrencyFormatterOptionsSchema` | const | `formatter.schemas.ts` |
+| `CommonCurrency` | type | `formatter.types.ts` |
+| `CurrencyDisplay` | type | `formatter.types.ts` |
+| `CurrencyFormatterOptions` | type | `formatter.types.ts` |
+| `CurrencyInfo` | type | `formatter.types.ts` |
+| `CurrencyFormatterCacheKey` | type | `formatter.types.ts` |
+| `getCurrencySymbol` | function | `helpers.ts` |
+| `getCurrencyName` | function | `helpers.ts` |
+| `getCurrencyInfo` | function | `helpers.ts` |
+| `recordCurrencyFormat` | function | `observability.ts` |
+| `recordCurrencyCacheHit` | function | `observability.ts` |
+| `getCurrencyFormatMetricsState` | function | `observability.ts` |
+| `resetCurrencyFormatMetricsState` | 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 and the only
+Wave 3 formatter with an intra-formatter dependency. Pure addition —
+`packages/i18n/i18n/src/formatting/currency/` is preserved in the
+monolith until Wave 6 deletes it.
+