> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ooneex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Currencies

> Currency dataset and a typed converter for formatting and exchanging amounts between currencies.

`@ooneex/currencies` ships a curated dataset of world currencies (code, name, symbol, and flag icon) together with fully typed currency codes. It also includes a `CurrencyConverter` for managing exchange rates, converting amounts, and formatting them with the correct symbol.

## Installation

Add the package with Bun.

```bash theme={null}
bun add @ooneex/currencies
```

## Usage

Import the `CURRENCIES` dataset to look up metadata, or use `CurrencyConverter` to handle rates and conversions.

### Browse the dataset

```typescript theme={null}
import { CURRENCIES } from "@ooneex/currencies";
import type { CurrencyCodeType } from "@ooneex/currencies";

const usd = CURRENCIES.find((c) => c.code === "USD");
// { code: "USD", name: "US Dollar", icon: "🇺🇸", symbol: "$" }

const code: CurrencyCodeType = "EUR"; // typed against the dataset
```

### Convert between currencies

Create a converter with a base currency (rate `1`) and seed it with rates expressed relative to that base.

```typescript theme={null}
import { CurrencyConverter } from "@ooneex/currencies";

const converter = new CurrencyConverter("USD", {
  EUR: 0.92,
  GBP: 0.79,
});

// Add or update rates later (chainable)
converter.setRate("JPY", 157.3).setRates({ CAD: 1.36 });

const conversion = converter.convert(100, "USD", "EUR");
// { from: "USD", to: "EUR", amount: 100, result: 92, rate: 0.92 }

const rate = converter.getRate("GBP"); // 0.79
const supported = converter.getSupportedCurrencies(); // ["USD", "EUR", "GBP", "JPY", "CAD"]
```

### Format and convert in one step

`format` prefixes the amount with the currency symbol; `convertAndFormat` converts then formats.

```typescript theme={null}
import { CurrencyConverter } from "@ooneex/currencies";

const converter = new CurrencyConverter("USD", { EUR: 0.92 });

converter.format(1234.5, "USD");                  // "$1234.50"
converter.convertAndFormat(100, "USD", "EUR");    // "€92.00"
converter.convertAndFormat(100, "USD", "EUR", 0); // "€92"
```

## When to use it

* You need a ready-made, typed list of currencies (codes, names, symbols, flag icons) for dropdowns, pickers, or validation.
* You want to convert amounts between currencies using exchange rates you supply (e.g. fetched from a rates API).
* You want quick symbol-prefixed formatting without pulling in `Intl.NumberFormat` configuration.
* Not needed if you only require locale-aware number formatting with no conversion — the native `Intl.NumberFormat` already covers that.