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.

Documentation tree

formatter — Locale-aware currency formatting backed by Intl.NumberFormat({ style: "currency" }). The package exposes both a class…
- formatter — Locale-aware currency formatting backed by Intl.NumberFormat({ style: "currency" }). The package exposes both a class…
helpers — Currency-info helpers exposing structured metadata about ISO 4217 codes via Intl.NumberFormat.formatToParts. Use thes…
- helpers — Currency-info helpers exposing structured metadata about ISO 4217 codes via Intl.NumberFormat.formatToParts. Use thes…
observability — Per-package OpenTelemetry instruments for @suaveplan/i18n-formatter-currency. Exposes a histogram (`i18n.format.curre…
- observability — Per-package OpenTelemetry instruments for @suaveplan/i18n-formatter-currency. Exposes a histogram (`i18n.format.curre…

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

bun add @suaveplan/i18n-formatter-currency

Quick Start

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 — CurrencyFormatter, formatCurrency, formatCurrencyValue
helpers.md — getCurrencySymbol, getCurrencyName, getCurrencyInfo
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.