# money

Build and validate monetary amounts

Canonical URL: https://docs.paradoc.dev/sdk/primitives/money/

Build and validate monetary amounts with currency. The Money primitive pairs a numeric amount with an ISO 4217 currency code.

## Examples

### Creating money values

```ts
// Object pattern
const price = p.money({ amount: 99.99, currency: 'USD' })

// Builder pattern
const price = p.money()
  .amount(99.99)
  .currency('USD')
  .build()

// Copy and modify
const discounted = p.money()
  .from(price)
  .amount(79.99)
  .build()
```

### Parsing external data

```ts
// Parse unknown input (throws on error)
const price = p.money.parse(jsonData)

// Safe parsing (returns result object)
const result = p.money.safeParse(jsonData)
if (result.success) {
  console.log(`${result.data.currency} ${result.data.amount}`)
} else {
  console.error(result.error.message)
}
```

### Using with forms

```ts
// As a field default
const form = p.form({
  name: 'product',
  fields: {
    price: {
      type: 'money',
      label: 'Price',
      default: { amount: 0, currency: 'USD' }
    }
  }
})

// When filling a form
const filled = form.fill({
  fields: {
    price: p.money({ amount: 29.99, currency: 'USD' })
  }
})
```

## API

### Object Pattern

```ts
p.money(input: Money): Money
```

Pass a Money object for validation. Returns the validated Money or throws on error.

```ts
const price = p.money({ amount: 150.00, currency: 'EUR' })
```

### Builder Pattern

Chain methods to build a Money value incrementally:

Start with `p.money()`. Each method returns `MoneyBuilder` and can be chained.

| Method | Description |
| --- | --- |
| `amount(value: number)` | Set the monetary amount |
| `currency(value: string)` | Set ISO 4217 currency code |
| `from(value: Money)` | Initialize from existing Money |

Terminal methods return `Money`.

| Method | Description |
| --- | --- |
| `build()` | Build and validate |

### Static Methods

| Method | Returns | Description |
| --- | --- | --- |
| `parse(input: unknown)` | `Money` | Parse unknown input (throws on error) |
| `safeParse(input: unknown)` | `Result<Money>` | Parse unknown input (returns result object) |

## Properties

| Name | Type | Description |
| --- | --- | --- |
| `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 exactly three uppercase letters

```ts
// Valid
p.money({ amount: 100, currency: 'USD' })
p.money({ amount: -50, currency: 'USD' })  // Negative allowed
p.money({ amount: 0, currency: 'EUR' })    // Zero allowed
p.money({ amount: 99.999, currency: 'BTC' }) // Decimals allowed

// Invalid - throws Error
p.money({ amount: NaN, currency: 'USD' })

p.money({ amount: Infinity, currency: 'USD' })

p.money({ amount: 100 })
```

## Common 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](https://en.wikipedia.org/wiki/ISO_4217) for the complete list.

## Related

* [Primitives Overview](/sdk/primitives) - All available primitives
* [Money Field](/sdk/artifacts/form/field#money) - Money field type
* [Money Schema](/schemas/primitives/money) - JSON Schema definition