dinero-best-practices

Dinero.js Best Practices

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.

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

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-

Quick Reference

1. Object Creation (CRITICAL)

• 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

2. Arithmetic (CRITICAL)

• 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

3. Precision (HIGH)

• 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

4. Imports (MEDIUM)

• 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

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