Dinero.js Currency Patterns

Patterns for handling currencies with Dinero.js: type safety, conversions, custom currencies, database storage, and payment service integration.

When to Apply

Reference these guidelines when:

• Converting between currencies with convert
• Defining custom currencies (e.g., cryptocurrencies, loyalty points)
• Looking up currencies dynamically from external input
• Storing monetary values in a database
• Integrating with payment services (Stripe, PayPal, Square)

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	Type Safety	HIGH	types-
2	Conversion	HIGH	convert-
3	Storage	HIGH	storage-
4	Payment Integration	MEDIUM	payment-

Quick Reference

1. Type Safety (HIGH)

• types-as-const - Define custom currencies with as const satisfies for compile-time safety
• types-currency-mismatch - TypeScript catches currency mismatches in operations at compile time
• types-lookup-validation - Validate currency codes from external sources at runtime

2. Conversion (HIGH)

• convert-scaled-rates - Use scaled amounts for fractional exchange rates, not floats
• convert-reusable - Build reusable converter functions with higher-order patterns

3. Storage (HIGH)

• storage-database - Store amount, currency code, and scale as separate columns
• storage-no-money-type - Avoid PostgreSQL's money type for multi-currency applications

4. Payment Integration (MEDIUM)

• payment-services - Map Dinero objects to payment service formats with dedicated helpers

How to Use

Read individual rule files for detailed explanations and code examples:

rules/types-as-const.md
rules/convert-scaled-rates.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