Currency Codes

Practical Snippet

Key points: (1) hand amount formatting to Intl.NumberFormat, which derives minor units per currency (JPY 0, CNY 2, BHD 3) and handles symbol placement — manual concatenation always misses zero-decimal currencies; (2) rates must be stored alongside amounts with an asOf timestamp or historical orders cannot be recomputed; (3) round at each step with an explicit mode (half-up here), since rounding after conversion versus before can differ by a whole minor unit.

// 用 Intl.NumberFormat 处理金额，别手工拼符号
const amount = 1234567.891

// ① 按币种自动取小数位（JPY=0、CNY=2、BHD=3）与符号
new Intl.NumberFormat('zh-CN', {
  style: 'currency',
  currency: 'CNY',
}).format(amount)                        // ¥1,234,567.89

new Intl.NumberFormat('ja-JP', {
  style: 'currency',
  currency: 'JPY',
}).format(amount)                        // ￥1,234,568 —— 0 位小数自动生效

// ② 换算必须带时点，并把 timestamp 一起存，否则历史无法复算
type RateSnapshot = { base: string; rates: Record<string, number>; asOf: string }

async function convert(
  amount: number,
  from: string,
  to: string,
  snapshot: RateSnapshot,
): Promise<number> {
  if (from === to) return amount
  const rate = snapshot.rates[to] / snapshot.rates[from]
  const converted = amount * rate
  // 关键：按目标币种小数位舍入，用 half-up 避免银行家舍入带来的争议
  const dp = new Intl.NumberFormat('en', {
    style: 'currency',
    currency: to,
  }).resolvedOptions().maximumFractionDigits
  return Number(converted.toFixed(dp))
}

// ③ 恒定式金额只做展示换算，记账用原币种 + 快照汇率
// 存储：{ amount: 1234.56, currency: 'USD', rateToBase: 7.1234, asOf: '2026-01-15' }
// 展示时按 asOf 选快照，不按「今天的汇率」回算历史账目