decimal-js

decimal.js

此技能适用于 decimal.js v10 任意精度十进制算术：构造、配置、舍入、金额安全模式、序列化和高级数学运算。

工作流

1. 修改代码前，先检查本地情况：
   • 包：decimal.js（以及存在时的同系列包 decimal.js-light、bignumber.js、big.js）。
   • 版本：目标为 v10（当前版本为 10.6.0）；查看内置的 decimal.d.ts（自 10.6.0 起，类型中包含 BigInt）。
   • 领域：金额/货币、科学计算或通用计算——这决定了 clone 配置，以及仅使用有效数字位数 precision 是否足够。
   • 导入方式：从 "decimal.js" 默认导入或按名称导入 Decimal。
2. 版本不明确，或工作涉及舍入、金额、三角函数或库隔离时，请更新文档。先查看 source-map.md。
3. 按需查阅更深入的内容：
   • 安装、构造函数、不可变性、值类型：setup-core.md。
   • 算术、比较、格式化、静态辅助方法：arithmetic-api.md。
   • set/config/clone、舍入模式、取模：config-rounding.md。
   • 金额、JSON/SSR/存储传输：money-serialization.md。
   • 三角函数、随机数/加密随机数、light 与 full 的区别、MikeMcl 生态：advanced-ecosystem.md。
   • 反模式和升级：pitfalls.md。
4. 遵循项目的构造方式（Decimal 或领域专用的 clone）。不要在已发布的库中调用全局 Decimal.set。
5. 使用类型检查和测试进行验证，测试内容包括字符串构造、舍入模式、toDP/toFixed 以及序列化往返。

库选择决策树

Need trig / ln / exp / non-integer pow / wide exponents?
  → decimal.js (this skill)

Exact add/mul until division, finance-first, smaller API?
  → consider bignumber.js (author guidance) — or stay on decimal.js with Money clone + toDP

Tiny bundle, basic DP only?
  → big.js or decimal.js-light

Using decimal.js for money anyway?
  → Decimal.clone({ precision: 28, rounding: … }) + construct from strings + round once with toDP/toFixed

核心判断

• 金额和多位数值应使用字符串（或 BigInt / Decimal）构造。绝不要先执行 new Decimal(0.1 + 0.2) 或先进行 Number 算术运算。
• 实例是不可变的。可以链式调用方法；不要期待原地修改。
• 几乎所有算术结果的 precision 都表示有效数字位数，而非货币小数位数。固定小数位数应使用 toDecimalPlaces / toDP（字符串结果则使用 toFixed）。
• 库和多领域应用优先使用 Decimal.clone({…})。仅在应用级启动配置中使用 Decimal.set。
• 值相等性：使用 .eq / .cmp，绝不要用 === / ==。
• 序列化为字符串（使用 toJSON / toFixed / toString）。金额或持久化值应避免使用 toNumber()。
• 默认舍入方式为 ROUND_HALF_UP (4)。金融场景应明确选择舍入方式（HALF_UP / HALF_EVEN / 按司法管辖区规定）。
• 使用 set/config/clone 进行配置——绝不要直接赋值 Decimal.precision = …（这会跳过校验）。

验证

优先使用仓库自带的命令。覆盖相关子集：

• bun pm ls decimal.js（迁移时也检查 light / big / bignumber）。
• 对 Decimal.Value、Decimal.Config 和 clone 构造函数进行类型检查。
• 测试：字符串与数字构造、eq 与 ===、toDP/toFixed 舍入模式、分币分配/税务边界情况、JSON 还原（new Decimal(dto.amount)），以及相关时的带符号零。
• 仅在选择 light 或 full 时检查打包结果/体积。

报告已运行和未运行的检查，以及仍未确定的版本/配置假设。