skills/plugins/document-navigator/docs/localization/i18n/i18n-formatter-currency

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

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.