moneyLast updated on
Last updated on
Build and validate monetary amounts
Build and validate monetary amounts with currency. The Money primitive pairs a numeric amount with an ISO 4217 currency code.
Examples
Creating money values
// Object pattern
const price = open.money({ amount: 99.99, currency: 'USD' })
// Builder pattern
const price = open.money()
.amount(99.99)
.currency('USD')
.build()
// Copy and modify
const discounted = open.money()
.from(price)
.amount(79.99)
.build()Parsing external data
// Parse unknown input (throws on error)
const price = open.money.parse(jsonData)
// Safe parsing (returns result object)
const result = open.money.safeParse(jsonData)
if (result.success) {
console.log(`${result.data.currency} ${result.data.amount}`)
} else {
console.error(result.error.message)
}Using with forms
// As a field default
const form = open.form({
name: 'product',
fields: {
price: {
type: 'money',
label: 'Price',
default: { amount: 0, currency: 'USD' }
}
}
})
// When filling a form
const filled = form.fill({
fields: {
price: open.money({ amount: 29.99, currency: 'USD' })
}
})API
Object Pattern
open.money(input: Money): MoneyPass a Money object for validation. Returns the validated Money or throws on error.
const price = open.money({ amount: 150.00, currency: 'EUR' })Builder Pattern
Chain methods to build a Money value incrementally:
All methods return MoneyBuilder and are chainable.
open.money()
amount: (value: number) => MoneyBuilder
Set the monetary amount
currency: (value: string) => MoneyBuilder
Set ISO 4217 currency code
from: (value: Money) => MoneyBuilder
Initialize from existing Money
build: () => Money
Build and validate
Static Methods
parse: (input: unknown) => Money
Parse unknown input (throws on error)
safeParse: (input: unknown) => Result<Money>
Parse unknown input (returns result object)
Properties
amount: number
Amount expressed in decimal form. Supports negative values for credits/refunds.
currency: string
ISO 4217 alpha-3 currency code (e.g., USD, EUR, GBP, JPY).
Validation
The Money primitive validates:
amountmust be a valid finite number (not NaN or Infinity)currencymust be a non-empty string
// Valid
open.money({ amount: 100, currency: 'USD' })
open.money({ amount: -50, currency: 'USD' }) // Negative allowed
open.money({ amount: 0, currency: 'EUR' }) // Zero allowed
open.money({ amount: 99.999, currency: 'BTC' }) // Decimals allowed
// Invalid - throws Error
open.money({ amount: NaN, currency: 'USD' })
// Error: Invalid Money: amount must be a valid number
open.money({ amount: Infinity, currency: 'USD' })
// Error: Invalid Money: amount cannot be Infinity
open.money({ amount: 100 })
// Error: Invalid Money: currency is requiredCommon Currency Codes
| Code | Currency |
|---|---|
USD | US Dollar |
EUR | Euro |
GBP | British Pound |
JPY | Japanese Yen |
CAD | Canadian Dollar |
AUD | Australian Dollar |
CHF | Swiss Franc |
CNY | Chinese Yuan |
INR | Indian Rupee |
MXN | Mexican Peso |
See ISO 4217 for the complete list.
Related
- Primitives Overview - All available primitives
- Money Field - Money field type
- Money Schema - JSON Schema definition