CurrencyExchangeService

Defined in: packages/engine/src/uom/CurrencyExchange.ts:38

Caches exchange rates fetched from an external source.

Rates are global market data rather than per-engine configuration, which is why one instance is shared. Two engines with private copies would fetch the same endpoint twice and could disagree about one pair at one moment. See engine/EngineContext.ts.

Constructors

Constructor

new CurrencyExchangeService(): CurrencyExchangeService;

Defined in: packages/engine/src/uom/CurrencyExchange.ts:75

Returns

CurrencyExchangeService

Methods

clearRates()

clearRates(): void;

Defined in: packages/engine/src/uom/CurrencyExchange.ts:249

Drop every cached/primed rate table.

Mainly for test isolation: sharedCurrencyExchange is a module-level singleton, so a rate primed or fetched by one test can silently leak into a later test in the same file. Also usable in production if a caller ever wants to force a full re-fetch.

Returns

void

---

convert()

convert(
   value,
   from,
to): Promise<number>;

Defined in: packages/engine/src/uom/CurrencyExchange.ts:281

Convert value from from to to using a freshly-fetched live rate (see getRate).

Parameters

Parameter	Type
value	number
from	string
to	string

Returns

Promise<number>

---

convertSync()

convertSync(
   value,
   from,
   to): number | null;

Defined in: packages/engine/src/uom/CurrencyExchange.ts:315

Synchronous conversion using cached rates only Returns null if rate not in cache

Parameters

Parameter	Type
value	number
from	string
to	string

Returns

number | null

---

getAllRates()

getAllRates(): Record<string, number> | null;

Defined in: packages/engine/src/uom/CurrencyExchange.ts:290

Get all currently cached fresh rates, keyed “FROM:TO”.

Returns

Record<string, number> | null

Snapshot of fresh live rates, or null when none are cached.

---

getRate()

getRate(
   from,
   to,
signal?): Promise<number>;

Defined in: packages/engine/src/uom/CurrencyExchange.ts:101

Fetch the live exchange rate for converting 1 unit of from into to.

Routes cryptocurrency codes (see CRYPTO_IDS) to CoinGecko and everything else to Frankfurter (ECB reference rates, fiat-only). On success, caches the whole returned rate table for from so subsequent lookups, including cross-pairs via triangulation, can be served synchronously by getRateSync within the freshness window.

Parameters

Parameter	Type
from	string
to	string
signal?	AbortSignal

Returns

Promise<number>

Throws

If the currency code is unrecognized or the fetch fails/times out.

---

getRateSync()

getRateSync(from, to): number | null;

Defined in: packages/engine/src/uom/CurrencyExchange.ts:262

Synchronous rate lookup: 1 for same-currency pairs, a cached LIVE rate if one was fetched within RATE_FRESHNESS_MS, otherwise null, callers fall through to the async fetch path and the expression shows Pending until real data arrives.

There is deliberately no hardcoded fallback table: a stale made-up rate presented as a real conversion is worse than a Pending state.

Parameters

Parameter	Type
from	string
to	string

Returns

number | null

---

hasRates()

hasRates(): boolean;

Defined in: packages/engine/src/uom/CurrencyExchange.ts:307

Check whether any fresh live rates are currently cached.

Returns

boolean

---

isCurrency()

isCurrency(code): boolean;

Defined in: packages/engine/src/uom/CurrencyExchange.ts:338

Check whether code is a recognized currency code: any active ISO 4217 code, or one of the cryptocurrencies in CRYPTO_IDS.

This used to be a hand-written list of forty-six codes, which meant $100 in UAH returned an unconverted hundred dollars rather than saying it could not convert. Answering from the standard rather than from whichever codes happened to get added is what stops that class of bug.

Recognising a code is not the same as having a rate for it. That is answered later, by the exchange provider; conflating the two is what produced the silent failure.

Parameters

Parameter	Type
code	string

Returns

boolean

---

primeRates()

primeRates(base, rates): void;

Defined in: packages/engine/src/uom/CurrencyExchange.ts:233

Seed a base rate table without a network fetch.

Intended for tests and for future user-provided offline rates production live data always comes from getRate. Seeded rates obey the same freshness window as fetched ones.

Parameters

Parameter	Type	Description
base	string	Base currency code (e.g. “USD”).
rates	Record<string, number>	Map of currency code → rate relative to the base.

Returns

void