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

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