dinero-best-practices

# Dinero.js Best Practices Core rules for working with [Dinero.js](https://v2.dinerojs.com), 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