@ financica/iso4217 (英语)

严格打入,零依赖性 ISO 4217 货币数据集与 O(1)取景.

由六局集团官方制造 list-one.xml编辑 2026-01-01数字 : 字母代码,数字代码,小单位,名称,基金旗和种类. 国家 关联是ISO 3166-1 alpha-2代码,从不透明的名称字符串. 每个 代码是一个字面结合,所以编译器告诉 "USD" 从 "usd" 财务报告和审定财务报表 "US" 从 "USA"。所有导出的数据是 Object.freezed 每个阵列是 readonly. 船舶无害环境管理+CJS和树摇杆.

将货币撤回到1970年代的船上 /historic 子路径.

安装

npm install @financica/iso4217

需要24号节点.

使用量

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"

类型警卫

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);
}

历史货币

退出货币(意大利里拉、扎伊尔、荷兰安的列斯) Guilder等)生活在子路径导入后,以免被挤出主通道 捆绑.

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

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

API 密码

查询

类型警卫

格式化

Frede的小单位分类不是ISO 4217(例如. UGX, (中文(简体) ), ISK, (中文(简体) ), HUF;对于跨越斯德莱克边界的金额,请使用助手在 @financica/stripe-hosted-invoices。 。 。 .

数据

类型

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 每个条目的分类:

• fiat 主权货币或超国家一般招标货币 (美元、欧元、英镑、自动取款机、XOF、XCD、XCG、XPF、.).
• fund 会计/投资单位(CHE、CHW、BOV、CLF、COU、MXV, (原始内容存档于2017-10-10). USN, UYI, UYW.
• metal ——贵金属商品代码(XAU,XAG,XPT,XPD).
• special ——保留代码:债券单位(XBAQBD),货币基金组织特别提款权(XDR), 亚行单位(XUA)、Sucre(XSU)、阿拉伯会计第纳尔(XAD)、测试(XTS)、, 无货币信使(XXX).

数据来源

数据来自SIX Group XML的两个官方列表:

• list-one.xml 活性货币
• list-three.xml ——历史货币/已提取货币

两者都被下载到 data/ 以 bun run fetch-data。 。 。 . bun run generate 然后将 XML 重新分割, 将实体行正常化为 ISO 3166-1 alpha-2 国家 代码(通过绘图) scripts/iso-3166.ts),并释放出三个 生成源文件于 src/数字 :

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

生成器在它不知道如何映射的任何实体名称上投放, 所以新的 或者在上游列表中重新命名的国家失败了建设,而不是默默无闻 放弃协会.

重新印发新的修订本

1. bun run fetch-data
2. bun run generate
3. 审查 git diff src/
4. bun run test
5. 按 仓库读取器。 。 。 .

许可证

麻省理工学院