Skip to content

CurrencyConverterService

katanakit-js / 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 / onRatesError callbacks whenever rates change. Those handlers are the only on* 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 the useCurrencyConverter() 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 })).

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),
});
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.

void


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.

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.

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.

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" }

ICurrencyConverterService.useConvert


useGetRate(from, to): Promise<SafeResult<number>>;

Defined in: core/services/currency.service.ts:267

Returns the exchange rate between two currencies.

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.

Promise<SafeResult<number>>

{ data, error, ok } — never throws.

const rate = await useGetExchangeRate("USD", "EUR");
// rate.ok → 0.92

ICurrencyConverterService.useGetRate


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.

The cached snapshot, or null when nothing was fetched yet.

{
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

ICurrencyConverterService.useGetSnapshot


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.

boolean


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).

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.

ICurrencyConverterService.useRefreshRates


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.

Parameter Type Description
provider ICurrencyRateProvider The new ICurrencyRateProvider.

void


useSetTtlMs(ttlMs): void;

Defined in: core/services/currency.service.ts:167

Changes the cache time-to-live at runtime.

Parameter Type Description
ttlMs number New TTL in milliseconds. 0 caches until useClearCache().

void


useSubscribe(events): () => void;

Defined in: core/services/currency.service.ts:183

Subscribes to rate events (Observer).

Parameter Type Description
events CurrencyRateEvents Handlers; onRatesUpdate and/or onRatesError.

An unsubscribe function.

() => void

const off = currency.useSubscribe({ onRatesUpdate: (s) => render(s) });
off();

ICurrencyConverterService.useSubscribe


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.

Parameter Type Description
options? CurrencyConverterServiceOptions Provider, formatter and cache TTL to inject.

CurrencyConverterService

A new CurrencyConverterService.

const currency = CurrencyConverterService.create({ provider: fakeRates });

static getInstance(): CurrencyConverterService;

Defined in: core/services/currency.service.ts:112

Returns the shared instance (Singleton).

CurrencyConverterService