dinero-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Dinero.js Best Practices

Dinero.js 最佳实践

Core rules for working with Dinero.js, the JavaScript/TypeScript library for creating, calculating, and formatting money safely. Contains rules across 4 categories, prioritized by impact.

以下是使用Dinero.js的核心规则，Dinero.js是一款用于在JavaScript/TypeScript中安全创建、计算和格式化货币的库。本文包含4类按影响优先级排序的规则。

When to Apply

适用场景

Reference these guidelines when:

Creating Dinero objects from user input, API responses, or database values
Performing arithmetic on monetary values (adding, splitting, multiplying)
Choosing between
```
number
```
and
```
bigint
```
calculators

Importing from

dinero.js

dinero.js/currencies

, or

dinero.js/bigint

Working with prices, costs, taxes, or any financial calculation

在以下场景中可参考这些指南：

从用户输入、API响应或数据库值创建Dinero对象时
对货币值执行算术运算（加法、拆分、乘法）时
选择
```
number
```
和
```
bigint
```
计算器时

引入

dinero.js

、

dinero.js/currencies

或

dinero.js/bigint

模块时

处理价格、成本、税费或任何金融计算时

Rule Categories by Priority

按优先级划分的规则类别

Priority	Category	Impact	Prefix
1	Object Creation	CRITICAL	`creation-`
2	Arithmetic	CRITICAL	`arithmetic-`
3	Precision	HIGH	`precision-`
4	Imports	MEDIUM	`imports-`

优先级	分类	影响级别	前缀
1	对象创建	关键	`creation-`
2	算术运算	关键	`arithmetic-`
3	精度处理	高	`precision-`
4	模块引入	中	`imports-`

Quick Reference

快速参考

1. Object Creation (CRITICAL)

1. 对象创建（关键）

```
creation-minor-units
```
- Always pass amounts as integers in minor currency units
```
creation-from-floats
```
- Use a helper to convert float inputs to minor units
```
creation-zero-exponent
```
- Currencies with exponent 0 (e.g., JPY) take major units directly

```
creation-minor-units
```
- 始终以货币最小单位的整数形式传入金额
```
creation-from-floats
```
- 使用辅助工具将浮点数输入转换为最小单位
```
creation-zero-exponent
```
- 指数为0的货币（如日元JPY）直接传入主单位

2. Arithmetic (CRITICAL)

2. 算术运算（关键）

```
arithmetic-immutability
```
- All operations return new objects; capture the return value
```
arithmetic-allocate-not-divide
```
- Use
```
allocate
```
for splitting money, not manual division
```
arithmetic-scaled-amounts
```
- Never multiply by a raw decimal; use scaled amounts
```
arithmetic-percentages
```
- Calculate percentages with
```
allocate
```
or scaled
```
multiply
```

```
arithmetic-immutability
```
- 所有运算都会返回新对象，请捕获返回值
```
arithmetic-allocate-not-divide
```
- 使用
```
allocate
```
方法拆分货币，不要手动进行除法运算
```
arithmetic-scaled-amounts
```
- 切勿直接乘以原始小数，应使用按比例缩放的数值
```
arithmetic-percentages
```
- 使用
```
allocate
```
方法或按比例缩放的
```
multiply
```
计算百分比

3. Precision (HIGH)

3. 精度处理（高）

precision-bigint

- Use

dinero.js/bigint

for amounts exceeding

Number.MAX_SAFE_INTEGER

```
precision-crypto
```
- Cryptocurrencies require bigint due to high exponents
```
precision-trim-scale
```
- Use
```
trimScale
```
to remove trailing zeros after chained operations

precision-bigint

- 当金额超过

Number.MAX_SAFE_INTEGER

时，使用

dinero.js/bigint

```
precision-crypto
```
- 加密货币因指数较高，需使用bigint类型
```
precision-trim-scale
```
- 链式运算后使用
```
trimScale
```
移除末尾零值

4. Imports (MEDIUM)

4. 模块引入（中）

```
imports-tree-shaking
```
- Import only what you use; standalone functions enable tree-shaking

imports-bigint-currencies

- Match calculator type: use

dinero.js/bigint/currencies

with

dinero.js/bigint

```
imports-tree-shaking
```
- 仅引入所需模块；独立函数支持摇树优化（tree-shaking）

imports-bigint-currencies

- 匹配计算器类型：使用

dinero.js/bigint

时搭配

dinero.js/bigint/currencies

How to Use

使用方式

Read individual rule files for detailed explanations and code examples:

rules/creation-minor-units.md
rules/arithmetic-allocate-not-divide.md

Each rule file contains:

Brief explanation of why it matters
Incorrect code example with explanation
Correct code example with explanation
Additional context and references

请查看单个规则文件获取详细说明和代码示例：

rules/creation-minor-units.md
rules/arithmetic-allocate-not-divide.md

每个规则文件包含：

规则重要性的简要说明
错误代码示例及问题解析
正确代码示例及说明
额外背景信息和参考资料 ",