CurrencyConverterService
katanakit-js / CurrencyConverterService
Class: CurrencyConverterService
Section titled “Class: CurrencyConverterService”Defined in: core/services/currency.service.ts:82
CurrencyConverterService — Singleton facade for currency conversion against external exchange rates.
Applies four patterns at once:
- Singleton — one shared instance via CurrencyConverterService.getInstance.
- Facade — one call converts an amount; rate fetching, caching and math stay behind it.
- Observer — subscribers get
onRatesUpdate/onRatesErrorcallbacks whenever rates change. Those handlers are the onlyon*surface in the kit:on*marks a callback the service invokes, never a method you call. - Dependency Injection — the rate source is an ICurrencyRateProvider
port, injected through CurrencyConverterService.create or
CurrencyConverterService.useSetProvider. The default implementation
lives in
src/infrastructure/(runtime I/O stays out of the core), and theuseCurrencyConverter()helper wires it for you.
Every fallible call returns a SafeResult — this service never throws.
converted is money: rounded to exactly 2 decimals with Intl’s symmetric
half-expand rule. rate keeps the full precision the source reported, so
chained arithmetic multiplies instead of re-fetching.
This service converts and never formats. Presentation is a separate
responsibility owned by FormatterService; compose the two when you
need a string (useFormatCurrency({ amount: converted, currency: to })).
Example
Section titled “Example”import { useCurrencyConverter, useConvertCurrency } from "katanakit-js";
// One-shot helper (wires the Frankfurter provider on first call):const result = await useConvertCurrency({ amount: 100, from: "USD", to: "EUR",});if (result.ok) console.log(result.data.converted, result.data.rate);
// Or hold the facade and subscribe to rate updates (Observer):const currency = useCurrencyConverter();const unsubscribe = currency.useSubscribe({ onRatesUpdate: (snapshot) => console.log("rates for", snapshot.date),});Implements
Section titled “Implements”Methods
Section titled “Methods”useClearCache()
Section titled “useClearCache()”useClearCache(): void;Defined in: core/services/currency.service.ts:300
Drops every cached snapshot. In-flight responses are discarded too: they were requested before the drop and must not repopulate the cache.
Returns
Section titled “Returns”void
useConvert()
Section titled “useConvert()”useConvert(options): Promise<SafeResult<{ amount: number; converted: number; date: string; from: | "USD" | "EUR" | "GBP" | "JPY" | "CHF" | "CAD" | "AUD" | "NZD" | "MXN" | "BRL" | "ARS" | "COP" | "CLP" | "SEK" | "NOK" | "DKK" | "PLN" | "CZK" | "HUF" | "RON" | "TRY" | "ISK" | "CNY" | "HKD" | "SGD" | "INR" | "KRW" | "THB" | "IDR" | "MYR" | "PHP" | "ILS" | "ZAR"; rate: number; to: | "USD" | "EUR" | "GBP" | "JPY" | "CHF" | "CAD" | "AUD" | "NZD" | "MXN" | "BRL" | "ARS" | "COP" | "CLP" | "SEK" | "NOK" | "DKK" | "PLN" | "CZK" | "HUF" | "RON" | "TRY" | "ISK" | "CNY" | "HKD" | "SGD" | "INR" | "KRW" | "THB" | "IDR" | "MYR" | "PHP" | "ILS" | "ZAR";}>>;Defined in: core/services/currency.service.ts:207
Converts an amount between two currencies.
Uses cached rates when fresh (see ttlMs); otherwise fetches them first.
rate keeps the full precision the source reported, while converted is
rounded to exactly 2 decimals (money). date is the ISO date the rate
belongs to.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
options |
{ amount: number; from: | "USD" | "EUR" | "GBP" | "JPY" | "CHF" | "CAD" | "AUD" | "NZD" | "MXN" | "BRL" | "ARS" | "COP" | "CLP" | "SEK" | "NOK" | "DKK" | "PLN" | "CZK" | "HUF" | "RON" | "TRY" | "ISK" | "CNY" | "HKD" | "SGD" | "INR" | "KRW" | "THB" | "IDR" | "MYR" | "PHP" | "ILS" | "ZAR"; to: | "USD" | "EUR" | "GBP" | "JPY" | "CHF" | "CAD" | "AUD" | "NZD" | "MXN" | "BRL" | "ARS" | "COP" | "CLP" | "SEK" | "NOK" | "DKK" | "PLN" | "CZK" | "HUF" | "RON" | "TRY" | "ISK" | "CNY" | "HKD" | "SGD" | "INR" | "KRW" | "THB" | "IDR" | "MYR" | "PHP" | "ILS" | "ZAR"; } |
Amount, source and target currency. |
options.amount? |
number |
Amount to convert, in units of from. |
options.from? |
| "USD" | "EUR" | "GBP" | "JPY" | "CHF" | "CAD" | "AUD" | "NZD" | "MXN" | "BRL" | "ARS" | "COP" | "CLP" | "SEK" | "NOK" | "DKK" | "PLN" | "CZK" | "HUF" | "RON" | "TRY" | "ISK" | "CNY" | "HKD" | "SGD" | "INR" | "KRW" | "THB" | "IDR" | "MYR" | "PHP" | "ILS" | "ZAR" |
Source currency. |
options.to? |
| "USD" | "EUR" | "GBP" | "JPY" | "CHF" | "CAD" | "AUD" | "NZD" | "MXN" | "BRL" | "ARS" | "COP" | "CLP" | "SEK" | "NOK" | "DKK" | "PLN" | "CZK" | "HUF" | "RON" | "TRY" | "ISK" | "CNY" | "HKD" | "SGD" | "INR" | "KRW" | "THB" | "IDR" | "MYR" | "PHP" | "ILS" | "ZAR" |
Target currency. |
Returns
Section titled “Returns”Promise<SafeResult<{
amount: number;
converted: number;
date: string;
from: | "USD"
| "EUR"
| "GBP"
| "JPY"
| "CHF"
| "CAD"
| "AUD"
| "NZD"
| "MXN"
| "BRL"
| "ARS"
| "COP"
| "CLP"
| "SEK"
| "NOK"
| "DKK"
| "PLN"
| "CZK"
| "HUF"
| "RON"
| "TRY"
| "ISK"
| "CNY"
| "HKD"
| "SGD"
| "INR"
| "KRW"
| "THB"
| "IDR"
| "MYR"
| "PHP"
| "ILS"
| "ZAR";
rate: number;
to: | "USD"
| "EUR"
| "GBP"
| "JPY"
| "CHF"
| "CAD"
| "AUD"
| "NZD"
| "MXN"
| "BRL"
| "ARS"
| "COP"
| "CLP"
| "SEK"
| "NOK"
| "DKK"
| "PLN"
| "CZK"
| "HUF"
| "RON"
| "TRY"
| "ISK"
| "CNY"
| "HKD"
| "SGD"
| "INR"
| "KRW"
| "THB"
| "IDR"
| "MYR"
| "PHP"
| "ILS"
| "ZAR";
}>>
{ data, error, ok } — never throws.
Example
Section titled “Example”const result = await useConvertCurrency({ amount: 100, from: "USD", to: "EUR",});// result.ok → { amount: 100, from: "USD", to: "EUR", rate: 0.88865, converted: 88.87, date: "2026-10-16" }Implementation of
Section titled “Implementation of”ICurrencyConverterService.useConvert
useGetRate()
Section titled “useGetRate()”useGetRate(from, to): Promise<SafeResult<number>>;Defined in: core/services/currency.service.ts:267
Returns the exchange rate between two currencies.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
from |
| "USD" | "EUR" | "GBP" | "JPY" | "CHF" | "CAD" | "AUD" | "NZD" | "MXN" | "BRL" | "ARS" | "COP" | "CLP" | "SEK" | "NOK" | "DKK" | "PLN" | "CZK" | "HUF" | "RON" | "TRY" | "ISK" | "CNY" | "HKD" | "SGD" | "INR" | "KRW" | "THB" | "IDR" | "MYR" | "PHP" | "ILS" | "ZAR" |
Source currency. |
to |
| "USD" | "EUR" | "GBP" | "JPY" | "CHF" | "CAD" | "AUD" | "NZD" | "MXN" | "BRL" | "ARS" | "COP" | "CLP" | "SEK" | "NOK" | "DKK" | "PLN" | "CZK" | "HUF" | "RON" | "TRY" | "ISK" | "CNY" | "HKD" | "SGD" | "INR" | "KRW" | "THB" | "IDR" | "MYR" | "PHP" | "ILS" | "ZAR" |
Target currency. |
Returns
Section titled “Returns”Promise<SafeResult<number>>
{ data, error, ok } — never throws.
Example
Section titled “Example”const rate = await useGetExchangeRate("USD", "EUR");// rate.ok → 0.92Implementation of
Section titled “Implementation of”ICurrencyConverterService.useGetRate
useGetSnapshot()
Section titled “useGetSnapshot()”useGetSnapshot(): | { base: | "USD" | "EUR" | "GBP" | "JPY" | "CHF" | "CAD" | "AUD" | "NZD" | "MXN" | "BRL" | "ARS" | "COP" | "CLP" | "SEK" | "NOK" | "DKK" | "PLN" | "CZK" | "HUF" | "RON" | "TRY" | "ISK" | "CNY" | "HKD" | "SGD" | "INR" | "KRW" | "THB" | "IDR" | "MYR" | "PHP" | "ILS" | "ZAR"; date: string; rates: Record<string, number>;} | null;Defined in: core/services/currency.service.ts:292
Returns the cached snapshot without fetching — every rate quoted against the pivot currency.
Returns
Section titled “Returns”The cached snapshot, or null when nothing was fetched yet.
Type Literal
Section titled “Type Literal”{ base: | "USD" | "EUR" | "GBP" | "JPY" | "CHF" | "CAD" | "AUD" | "NZD" | "MXN" | "BRL" | "ARS" | "COP" | "CLP" | "SEK" | "NOK" | "DKK" | "PLN" | "CZK" | "HUF" | "RON" | "TRY" | "ISK" | "CNY" | "HKD" | "SGD" | "INR" | "KRW" | "THB" | "IDR" | "MYR" | "PHP" | "ILS" | "ZAR"; date: string; rates: Record<string, number>;}base: | "USD" | "EUR" | "GBP" | "JPY" | "CHF" | "CAD" | "AUD" | "NZD" | "MXN" | "BRL" | "ARS" | "COP" | "CLP" | "SEK" | "NOK" | "DKK" | "PLN" | "CZK" | "HUF" | "RON" | "TRY" | "ISK" | "CNY" | "HKD" | "SGD" | "INR" | "KRW" | "THB" | "IDR" | "MYR" | "PHP" | "ILS" | "ZAR" = CurrencySchema;Base currency the rates are quoted against.
date: string;ISO date (YYYY-MM-DD) the rates belong to.
rates: Record<string, number>;Quote currency → units of quote per 1 unit of base. Keys are the source’s
own vocabulary (loose on purpose: providers know currencies this kit does
not, and an unknown key must not invalidate the snapshot).
null
Implementation of
Section titled “Implementation of”ICurrencyConverterService.useGetSnapshot
useHasProvider()
Section titled “useHasProvider()”useHasProvider(): boolean;Defined in: core/services/currency.service.ts:158
Whether a rate source is already injected.
Wiring helpers use it to install a default provider only when none is configured, so a custom one is never clobbered.
Returns
Section titled “Returns”boolean
useRefreshRates()
Section titled “useRefreshRates()”useRefreshRates(): Promise<SafeResult<{ base: | "USD" | "EUR" | "GBP" | "JPY" | "CHF" | "CAD" | "AUD" | "NZD" | "MXN" | "BRL" | "ARS" | "COP" | "CLP" | "SEK" | "NOK" | "DKK" | "PLN" | "CZK" | "HUF" | "RON" | "TRY" | "ISK" | "CNY" | "HKD" | "SGD" | "INR" | "KRW" | "THB" | "IDR" | "MYR" | "PHP" | "ILS" | "ZAR"; date: string; rates: Record<string, number>;}>>;Defined in: core/services/currency.service.ts:282
Forces a rate refresh, bypassing the cache (Observer fires onRatesUpdate
when it succeeds).
Returns
Section titled “Returns”Promise<SafeResult<{
base: | "USD"
| "EUR"
| "GBP"
| "JPY"
| "CHF"
| "CAD"
| "AUD"
| "NZD"
| "MXN"
| "BRL"
| "ARS"
| "COP"
| "CLP"
| "SEK"
| "NOK"
| "DKK"
| "PLN"
| "CZK"
| "HUF"
| "RON"
| "TRY"
| "ISK"
| "CNY"
| "HKD"
| "SGD"
| "INR"
| "KRW"
| "THB"
| "IDR"
| "MYR"
| "PHP"
| "ILS"
| "ZAR";
date: string;
rates: Record<string, number>;
}>>
{ data, error, ok } with the snapshot quoted against the pivot.
Never throws.
Implementation of
Section titled “Implementation of”ICurrencyConverterService.useRefreshRates
useSetProvider()
Section titled “useSetProvider()”useSetProvider(provider): void;Defined in: core/services/currency.service.ts:146
Swaps the rate source at runtime (DI).
Drops the cache: every stored snapshot came from the previous source, so keeping it would silently serve rates the new provider never confirmed. Re-setting the same provider is a no-op, so a per-call wiring helper cannot defeat the cache. In-flight responses from the previous provider are discarded instead of written.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
provider |
ICurrencyRateProvider |
The new ICurrencyRateProvider. |
Returns
Section titled “Returns”void
useSetTtlMs()
Section titled “useSetTtlMs()”useSetTtlMs(ttlMs): void;Defined in: core/services/currency.service.ts:167
Changes the cache time-to-live at runtime.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
ttlMs |
number |
New TTL in milliseconds. 0 caches until useClearCache(). |
Returns
Section titled “Returns”void
useSubscribe()
Section titled “useSubscribe()”useSubscribe(events): () => void;Defined in: core/services/currency.service.ts:183
Subscribes to rate events (Observer).
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
events |
CurrencyRateEvents |
Handlers; onRatesUpdate and/or onRatesError. |
Returns
Section titled “Returns”An unsubscribe function.
() => void
Example
Section titled “Example”const off = currency.useSubscribe({ onRatesUpdate: (s) => render(s) });off();Implementation of
Section titled “Implementation of”ICurrencyConverterService.useSubscribe
create()
Section titled “create()”static create(options?): CurrencyConverterService;Defined in: core/services/currency.service.ts:131
Creates a NO-singleton instance with injected dependencies (DI). Useful for tests and for custom rate sources.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
options? |
CurrencyConverterServiceOptions |
Provider, formatter and cache TTL to inject. |
Returns
Section titled “Returns”CurrencyConverterService
A new CurrencyConverterService.
Example
Section titled “Example”const currency = CurrencyConverterService.create({ provider: fakeRates });getInstance()
Section titled “getInstance()”static getInstance(): CurrencyConverterService;Defined in: core/services/currency.service.ts:112
Returns the shared instance (Singleton).
Returns
Section titled “Returns”CurrencyConverterService