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

每个规则文件包含：

规则重要性的简要说明
错误代码示例及解释
正确代码示例及解释
额外上下文和参考资料