# @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.