@financica/iso4217

Strictly typed, zero-dependency ISO 4217 currency dataset with O(1) lookups.

Built from SIX Group's official list-one.xml, revision 2026-01-01: alphabetic code, numeric code, minor units, name, fund flag and kind. Country associations are ISO 3166-1 alpha-2 codes, never opaque name strings. Every code is a literal union, so the compiler tells "USD" from "usd" and "US" from "USA". All exported data is Object.freezed and every array is readonly. Ships ESM + CJS and tree-shakes.

Withdrawn currencies back to the 1970s ship in an opt-in /historic subpath.

Install

npm install @financica/iso4217

Requires Node ≥ 24.

Usage

import {
    getByCode,
    getByNumericCode,
    getByCountry,
    formatAmount,
    CURRENCIES,
    PUBLISHED_AT,
} from "@financica/iso4217";

getByCode("USD");
// → {
//     alphabeticCode: "USD",
//     numericCode: "840",
//     minorUnits: 2,
//     name: "US Dollar",
//     countryCodes: ["AS", "BQ", "EC", "GU", "HT", "IO", "MH", "MP", "PA",
//                    "PR", "PW", "SV", "TC", "TL", "UM", "US", "VG", "VI"],
//     isFund: false,
//     kind: "fiat",
//   }

getByCode("usd")?.alphabeticCode; // "USD"  — case-insensitive
getByNumericCode("840")?.alphabeticCode; // "USD"
getByNumericCode(840)?.alphabeticCode; // "USD"
getByNumericCode(8)?.alphabeticCode; // "ALL" — unpadded input is normalised

getByCountry("CH").map((c) => c.alphabeticCode);
// ["CHE", "CHF", "CHW"]

formatAmount(1234.5, "USD", { locale: "en-US" }); // "$1,234.50"
formatAmount(1234.5, "JPY", { locale: "en-US" }); // "¥1,235"     (0 minor units)
formatAmount(1.5, "BHD", { locale: "en-US" }); // "BHD 1.500"  (3 minor units)

CURRENCIES.length; // 178 (as of 2026-01-01)
PUBLISHED_AT; // "2026-01-01"

Type guards

import { isAlphabeticCode, isNumericCode, isCountryCode } from "@financica/iso4217";

function logCurrency(code: string) {
    if (!isAlphabeticCode(code)) return;
    // `code` is now narrowed to AlphabeticCode.
    console.log(getByCode(code)?.name);
}

Historic currencies

Withdrawn currencies (Italian Lira, Zaire Zaïre, Netherlands Antillean Guilder, etc.) live behind a subpath import so they don't bloat the main bundle.

import { getHistoricByCode, HISTORIC_CURRENCIES } from "@financica/iso4217/historic";

getHistoricByCode("ANG").map((c) => c.withdrawalDate);
// ["2010-10", "2025-03"]  — ANG was withdrawn twice.

API

Lookups

Type guards

Formatting

Stripe's minor-unit classification is not ISO 4217 (e.g. UGX, ISK, HUF); for amounts crossing the Stripe boundary use the helpers in @financica/stripe-hosted-invoices.

Data

Types

interface Currency {
    readonly alphabeticCode: AlphabeticCode; // e.g. "USD"
    readonly numericCode: NumericCode; // e.g. "840"
    readonly minorUnits: number | null; // null for metals and N.A. codes
    readonly name: string;
    readonly countryCodes: readonly CountryCode[];
    readonly isFund: boolean;
    readonly kind: "fiat" | "fund" | "metal" | "special";
}

type CurrencyKind = "fiat" | "fund" | "metal" | "special";

kind classifies each entry:

• fiat — sovereign or supranational general-tender currency (USD, EUR, GBP, XAF, XOF, XCD, XCG, XPF, …).
• fund — accounting/investment unit (CHE, CHW, BOV, CLF, COU, MXV, USN, UYI, UYW).
• metal — precious metal commodity code (XAU, XAG, XPT, XPD).
• special — reserved codes: bond units (XBA–XBD), IMF SDR (XDR), ADB unit (XUA), Sucre (XSU), Arab Accounting Dinar (XAD), testing (XTS), no-currency sentinel (XXX).

Data provenance

Data is generated from the two official SIX Group XML lists:

• list-one.xml — active currencies
• list-three.xml — historic / withdrawn currencies

Both are downloaded into data/ by bun run fetch-data. bun run generate then re-parses the XML, normalises entity rows to ISO 3166-1 alpha-2 country codes (via the mapping in scripts/iso-3166.ts), and emits the three generated source files in src/:

• src/codes.ts
• src/data.ts
• src/historic-data.ts

The generator throws on any entity name it does not know how to map, so a new or renamed country in the upstream list fails the build rather than silently dropping an association.

Releasing a new revision

1. bun run fetch-data
2. bun run generate
3. Review git diff src/
4. bun run test
5. Publish per the repository README.

License

MIT