深入解析 Dinero.js 的 `haveSameCurrency`：如何判断一组货币对象的币种是否一致

金融科技【免费下载链接】dinero.jsCreate, calculate, and format money in JavaScript and TypeScript项目地址https://gitcode.com/gh_mirrors/di/dinero.js点击查看免费下载导读haveSameCurrency是 Dinero.js 比较类 API 家族中的一员它的职责非常聚焦接收一组两个及以上Dinero货币对象返回一个布尔值判断它们是否都持有同一种货币currency。与只看金额数值的haveSameAmount互补haveSameCurrency是金额计算、比较、转换等业务正确性的前提性校验——例如在购物车汇总、费用分摊、报表聚合等场景中必须先确认所有条目币种一致再做加减乘除否则结果毫无意义。读完本文你将掌握haveSameCurrency的完整签名、调用方式、底层比较原理含多基数货币的特殊处理以及它与equal、haveSameAmount在比较语义上的分工。函数签名与参数说明haveSameCurrency属于 Dinero.js 顶层 API在 packages/dinero.js/src/api/haveSameCurrency.ts 中定义并在 packages/dinero.js/src/api/index.ts 中统一对外导出。其签名如下名称类型说明必填dineroObjectsDineroTAmount[]要检查的 Dinero 对象集合是入参一个由DineroTAmount对象组成的数组至少需要两个元素才有比较意义实现取第一个元素为基准、其余逐个比对。返回值boolean。当集合中所有对象的货币完全相同时返回true否则返回false。注意该函数接收的是对象数组而不是两个独立参数这一设计让它可以天然支持多对象同时校验你可以在一个调用里一次核对任意多个 Dinero 对象。从类型定义看货币本身由 DineroCurrency 类型 描述包含三个只读字段字段类型含义codeTCurrency extends string货币唯一代码如USD、EUR、GBPbaseTAmount \| readonly TAmount[]货币的基数/进制radix单一数值或数组多基数货币exponentTAmount货币的指数小数位数内置的 ISO 4217 货币如 packages/dinero.js/src/currencies/iso4217.ts 中的USD正是满足该类型的常量对象{ code: USD, base: 10, exponent: 2 }。基本用法两个代码示例官方文档 docs/api/comparisons/have-same-currency.md 给出了两个典型示例。同币种对象返回trueimport { dinero, haveSameCurrency } from dinero.js; import { USD } from dinero.js/currencies; const d1 dinero({ amount: 2000, currency: USD }); const d2 dinero({ amount: 1000, currency: USD }); haveSameCurrency([d1, d2]); // trued1与d2虽然金额不同2000 与 1000但都使用USD因此结果为true——这恰好说明了haveSameCurrency只看币种、不看金额与金额比较 API 职责正交。异币种对象返回falseimport { dinero, haveSameAmount } from dinero.js; import { USD, EUR } from dinero.js/currencies; const d1 dinero({ amount: 1000, currency: USD }); const d2 dinero({ amount: 1000, currency: EUR }); haveSameAmount([d1, d2]); // false需要提醒原文档此例的代码本身存在一处笔误——它导入并调用的是haveSameAmount判断金额是否相同而按示例意图比较USD与EUR两种币种应使用haveSameCurrencyimport { dinero, haveSameCurrency } from dinero.js; import { USD, EUR } from dinero.js/currencies; const d1 dinero({ amount: 1000, currency: USD }); const d2 dinero({ amount: 1000, currency: EUR }); haveSameCurrency([d1, d2]); // false两个对象金额都是 1000币种分别是USD与EUR因此haveSameCurrency返回false。这也体现了两个 API 的互补关系金额相同 ≠ 币种相同币种相同 ≠ 金额相同两者要结合使用才能做完整对象比较。底层原理一次基于计算器的三重比较haveSameCurrency的实现位于 packages/dinero.js/src/core/api/haveSameCurrency.ts顶层 API 只是对它的一层转发。其核心逻辑可以概括为取出数组中的第一个Dinero 对象作为基准comparator其余对象作为待比较项subject通过computeBase把基准与每个待比较项的货币base归一化为可比较的数值对每个待比较项执行三重条件code相等、归一化后的base相等、exponent相等用every遍历只要有一个对象不满足即返回false。对应的比较条件是subject.code comparator.code equalFn(subjectBase, comparatorBase) equalFn(subject.exponent, comparator.exponent)这里的equalFn来自 packages/dinero.js/src/core/utils/equal.ts它借助当前 Dinero 对象携带的calculator的compare方法判断两值相等——而不是用 JS 的直接比较这是 Dinero.js 支持number、bigint、Big.js 等不同数值类型的关键。为什么用 calculator 而不是原生比较每个Dinero对象都携带一个calculator见 packages/dinero.js/src/core/types/Dinero.ts它是计算器模式的实现。比较base与exponent时必须把这些值当成TAmount泛型数值来对待number计算器数值是普通numberbigint计算器数值是bigint虽可比较但乘法等运算必须走calculator.multiplyBig.js 计算器数值是Big对象两个Big实例即使数值相同也永远返回false只能通过compare判断。因此统一交给calculator处理才能保证三种数值后端的行为一致。在 packages/dinero.js/src/api/tests/haveSameCurrency.test.ts 中同一组断言分别针对number、bigint、Big.js 三种计算器各跑一遍正是对这一设计的验证。多基数货币multi-base的特殊处理DineroCurrency的base字段类型是TAmount | readonly TAmount[]允许传入数组。这在处理非十进制货币时非常有用——例如传统英镑体系曾使用 20 先令 1 镑、12 便士 1 先令的复合进制。computeBase见 packages/dinero.js/src/core/utils/computeBase.ts负责归一化export function computeBaseTAmount(calculator: DineroCalculatorTAmount) { return (base: TAmount | readonly TAmount[]) { if (isArray(base)) { return base.reduce((acc, curr) calculator.multiply(acc, curr)); } return base; }; }若base是数组则用calculator.multiply把所有元素连乘得到单一基数。例如base: [20, 12]会得到240若base是单值则原样返回。于是haveSameCurrency可以正确判定两种写法不同但实际相同的货币// 数组形式与连乘结果形式被视为同一种货币 const d1 dinero({ amount: 240, currency: { code: GBP, base: [20, 12], exponent: 1 }, }); const d2 dinero({ amount: 240, currency: { code: GBP, base: 240, exponent: 1 }, }); haveSameCurrency([d1, d2]); // true这一行为在测试文件中有明确覆盖returns true when multi-base currencies compute to the same base是haveSameCurrency区别于简单字符串比较的核心深度所在。实战场景在汇总计算前做币种守卫haveSameCurrency最常见的用途是作为聚合运算的前置校验。以购物车结算为例import { dinero, haveSameCurrency, add, toFormat } from dinero.js; import { USD } from dinero.js/currencies; function checkout(cart) { if (!haveSameCurrency(cart)) { throw new Error(购物车中的条目必须使用同一币种才能结算); } // 此时才可安全地执行加法等金额运算 const total cart.reduce((sum, item) add(sum, item)); return toFormat(total); }多币种混入时函数会第一时间返回false阻止错误的跨币种金额运算避免把美元与欧元直接相加产生伪金额。另外haveSameCurrency也是完整对象相等比较equal的组成部件之一。查看 packages/dinero.js/src/core/api/equal.ts 可以发现return ( haveSameAmount(calculator)([dineroObject, comparator]) haveSameCurrency([dineroObject, comparator]) );即equalhaveSameAmount金额归一化后相等∧haveSameCurrency币种相等。这意味着只要掌握了haveSameCurrency也就理解了大对象比较equal的一半语义。边界情况与注意事项空数组 / 单元素数组实现以第一个元素为基准、其余元素逐个比对空数组或单元素数组不会进入实质比较但业务上一般至少传入两个对象才有意义。自定义货币对象不要求必须使用内置 ISO 4217 常量只要对象满足{ code, base, exponent }结构即可haveSameCurrency对结构等价structural equality的对象同样返回true测试用例中有专门覆盖。多基数比较base数组与连乘后的单值会被正确视为等价但比较时要求连乘结果一致若数组元素顺序不同但乘积相同结果仍为true。类型泛化函数签名使用ReadonlyArrayDineroTAmount要求同一数组内对象的金额类型TAmount一致例如不要混用number与bigint构造的对象这也符合 Dinero.js 整体按金额类型选择计算器的设计约束。总结haveSameCurrency用最小的 API 表面一个数组入参、一个布尔返回解决了多对象币种一致性这一高频校验需求其实现深度体现在三点基于计算器而非原生运算符的数值比较、对多基数货币的computeBase归一化、以及与equal/haveSameAmount的组合关系。无论你使用number、bigint还是 Big.js 作为金额类型该函数都能给出一致、可靠的判定是构建多币种安全金融计算的可靠基石。想进一步验证行为可阅读 packages/dinero.js/src/api/tests/haveSameCurrency.test.ts 中覆盖三种计算器的完整测试用例。赞分享金融科技【免费下载链接】dinero.jsCreate, calculate, and format money in JavaScript and TypeScript项目地址https://gitcode.com/gh_mirrors/di/dinero.js点击查看免费下载相关推荐Dinero.js hasSubUnits 详解如何判断金额是否包含小额货币单位Minor Currency UnitsDinero.js hasSubUnits 详解如何判断金额是否包含小额货币单位Minor Currency Units hasSubUnits 是 Di金融科技Dinero.js源码解析深入理解不可变货币对象的实现原理Dinero.js源码解析深入理解不可变货币对象的实现原理 Dinero.js是一个用于在JavaScript和TypeScript中创建、计算和格式化货币的金融科技RawTherapee工作流程优化从导入到导出的高效照片处理方案RawTherapee工作流程优化从导入到导出的高效照片处理方案 RawTherapee是一款功能强大的跨平台原始照片处理程序能够帮助摄影爱好者和专业人士实桌面应用图形学上一篇3分钟掌握Python窗口美化终极自定义GUI主题指南 下一篇终极指南如何用Requests-Async实现Python异步HTTP请求的革命性突破创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考