OpenForm

money

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): Money

Pass 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:

  • amount must be a valid finite number (not NaN or Infinity)
  • currency must 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 required

Common Currency Codes

CodeCurrency
USDUS Dollar
EUREuro
GBPBritish Pound
JPYJapanese Yen
CADCanadian Dollar
AUDAustralian Dollar
CHFSwiss Franc
CNYChinese Yuan
INRIndian Rupee
MXNMexican Peso

See ISO 4217 for the complete list.

Related

On this page