currency-code-symbol-kit

Resolve ISO currency codes to locale-aware symbols with a tiny, browser-friendly TypeScript API.

It does not ship a currency table. It asks the platform Intl.NumberFormat implementation for the display symbol, then returns structured diagnostics so callers can decide what to do with invalid codes, unsupported locales, or ambiguous symbols like $.

import { getCurrencySymbol, inspectCurrencySymbol } from "currency-code-symbol-kit";

getCurrencySymbol("eur");
// "€"

inspectCurrencySymbol("USD", { locale: "en-US", compareWith: ["CAD", "AUD"] });
// {
//   ok: true,
//   code: "USD",
//   symbol: "$",
//   locale: "en-US",
//   diagnostics: [{ code: "symbol_collision", ... }]
// }

Demo

Try the browser preview: packages.wasta-wocket.fr/currency-code-symbol-kit.

Package quality

• TypeScript types are generated from the source.
• ESM-only package with no runtime dependencies.
• Marked as side-effect free for bundlers.
• CI runs npm ci, typecheck, build, and test.
• Tested on Node.js 20 and 22 with GitHub Actions.
• Browser-friendly implementation with no Node-only APIs.

API

getCurrencySymbol(code, options?)

Returns the symbol string, or undefined when the code or locale cannot be resolved.

getCurrencySymbol("GBP"); // "£"
getCurrencySymbol("not valid"); // undefined

inspectCurrencySymbol(code, options?)

Returns a structured result:

const result = inspectCurrencySymbol("JPY", {
  locale: "fr-FR",
  compareWith: ["CNY", "KRW"]
});

if (result.ok) {
  result.symbol;
  result.diagnostics;
}

Options:

• locale: BCP 47 locale passed to Intl.NumberFormat. Defaults to "en-US".
• fallbackLocale: locale used when locale is invalid. Defaults to "en-US".
• narrow: use currencyDisplay: "narrowSymbol" instead of "symbol".
• compareWith: additional currency codes checked for same-symbol collisions in the resolved locale.
• maxComparisons: maximum compareWith entries checked. Defaults to 100.

The API is intentionally safe for untrusted form values: non-string currency codes, runtime-invalid options, invalid locales, and oversized comparison lists return diagnostics instead of throwing.

Browser compatibility

The core uses only strings, arrays, objects, regular expressions, and Intl.NumberFormat. There is no fs, path, Buffer, process, network access, or runtime dependency.

CLI

No CLI is included in this draft. Currency symbol lookup is usually embedded in UI, formatting, import, or validation code; a CLI would add Node-specific packaging without improving the core use case.