# Currency Semantic Examples

This document provides examples of how to use the Currency semantic with different configurations.

## Basic Usage

```typescript
import { createCurrencySemantic, CURRENCY_PRESETS } from './Currency.js'

// Simple USD decimal storage
const basicCurrency = createCurrencySemantic({
  storageFormat: 'decimal',
  defaultCurrency: 'USD',
  decimalPlaces: 2,
  allowNegative: false,
})

// Using a preset
const usdDecimal = CURRENCY_PRESETS.USD_DECIMAL
```

## Configuration Examples

### 1. Simple E-commerce Store (USD only)

```typescript
const ecommerceCurrency = createCurrencySemantic({
  storageFormat: 'decimal',
  defaultCurrency: 'USD',
  decimalPlaces: 2,
  allowNegative: false,
})
```

### 2. International E-commerce (Multi-currency)

```typescript
const internationalCurrency = createCurrencySemantic({
  storageFormat: 'complex_object',
  allowedCurrencies: ['USD', 'EUR', 'GBP', 'JPY', 'CAD', 'AUD'],
  decimalPlaces: 2,
  allowNegative: false,
})
```

### 3. Financial System (High precision, allows negatives)

```typescript
const financialCurrency = createCurrencySemantic({
  storageFormat: 'integer_cents',
  defaultCurrency: 'USD',
  decimalPlaces: 4,
  allowNegative: true,
})
```

### 4. Cryptocurrency Trading

```typescript
const cryptoCurrency = createCurrencySemantic({
  storageFormat: 'decimal',
  defaultCurrency: 'BTC',
  decimalPlaces: 8,
  allowNegative: false,
})
```

## Storage Format Details

### Decimal Format

- **Best for**: Simple single-currency applications
- **PostgreSQL Type**: DECIMAL(precision, scale)
- **Example Value**: 19.99
- **Pros**: Human-readable, direct calculations
- **Cons**: Currency must be stored separately if needed

### Integer Cents Format

- **Best for**: Financial calculations requiring precision
- **PostgreSQL Type**: BIGINT
- **Example Value**: 1999 (represents $19.99)
- **Pros**: No floating-point errors, efficient storage
- **Cons**: Requires conversion for display

### Complex Object Format

- **Best for**: Multi-currency applications
- **PostgreSQL Type**: JSONB
- **Example Value**: {"amount": 1999, "currency": "USD"}
- **Pros**: Stores amount and currency together, flexible
- **Cons**: More complex queries, larger storage

## Database Schema Generation Examples

The runtime will generate appropriate PostgreSQL schemas based on the semantic configuration:

### For Decimal Format

Based on `storageFormat: 'decimal'` configuration, the runtime should generate:

```sql
CREATE TABLE products (
  id SERIAL PRIMARY KEY,
  name VARCHAR(255),
  price DECIMAL(19, 2) NOT NULL,
  currency CHAR(3) DEFAULT 'USD'
);

CREATE INDEX idx_products_price ON products(price);
```

### For Integer Cents Format

Based on `storageFormat: 'integer_cents'` configuration, the runtime should generate:

```sql
CREATE TABLE products (
  id SERIAL PRIMARY KEY,
  name VARCHAR(255),
  price_cents BIGINT NOT NULL,
  currency CHAR(3) DEFAULT 'USD'
);

CREATE INDEX idx_products_price_cents ON products(price_cents);
```

### For Complex Object Format

Based on `storageFormat: 'complex_object'` configuration, the runtime should generate:

```sql
CREATE TABLE products (
  id SERIAL PRIMARY KEY,
  name VARCHAR(255),
  price JSONB NOT NULL
);

CREATE INDEX idx_products_price_amount ON products USING GIN ((price->>'amount'));
CREATE INDEX idx_products_price_currency ON products USING GIN ((price->>'currency'));
```

## Validation Examples

The Currency semantic includes built-in validation:

```typescript
import { validateCurrencyConfig } from './Currency.js'

const config = {
  storageFormat: 'decimal' as const,
  // Missing defaultCurrency - this will cause an error
  decimalPlaces: 2,
}

const errors = validateCurrencyConfig(config)
console.log(errors) // ['defaultCurrency is required when storageFormat is not complex_object']
```
