nhb-toolbox/dist/dts/number/Currency.d.ts

A versatile collection of smart, efficient, and reusable utility functions, classes and types for everyday development needs.

import type { Numeric } from '../types/index';
import type { ConvertOptions, CurrencyCode, FrankFurterCurrency, LocaleCode } from './types';
/**
 * * A utility class for handling currency operations like formatting and conversion.
 *
 * - Supports formatting based on locale and currency code.
 * - Converts between **fiat currencies supported by `api.frankfurter.app`**.
 * - Automatically caches conversion rates to reduce redundant API calls.
 * - Intended for use with numeric inputs (number or numeric string).
 */
export declare class Currency<Code extends CurrencyCode> {
    #private;
    /**
     * * The formatted currency string (e.g., `$1,000.00`).
     *
     * - Generated using the `en-US` locale during construction.
     * - This is a display-friendly version of the currency value.
     * - For formatting with other locales, use the `format()` method.
     */
    readonly currency: string;
    /**
     * Creates an instance of the Currency class.
     *
     * @param amount - The numeric amount of currency (e.g., `100`, `'99.99'`).
     * @param code - The ISO 4217 currency code representing the currency (e.g., `'USD'`, `'EUR'`).
     */
    constructor(amount: Numeric, code: Code);
    /** * Clears cached rates that were fetched previously. */
    static clearRateCache(): void;
    /**
     * @instance Formats the stored amount as a localized currency string.
     *
     * @param locale - Optional. A BCP 47 locale string (e.g., `'de-DE'`, `'en-US'`). Defaults to `'en-US'` if not provided.
     * @param code - Optional. An ISO 4217 currency code (e.g., `'USD'`, `'EUR'`) used solely for formatting purposes.
     *            _This does not alter the internal currency code set during instantiation._
     * @returns A string representing the formatted currency value according to the specified locale and currency code.
     */
    format(locale?: LocaleCode, code?: CurrencyCode): string;
    /**
     * @instance Converts the current currency amount to a target currency using real-time exchange rates.
     *
     * - Uses {@link https://api.frankfurter.app/latest api.frankfurter.app} to fetch live exchange rates.
     * - Supports **only the following fiat currencies**:
     *   `AUD`, `BGN`, `BRL`, `CAD`, `CHF`, `CNY`, `CZK`, `DKK`, `EUR`, `GBP`, `HKD`, `HUF`, `IDR`, `ILS`, `INR`, `ISK`, `JPY`,
     *   `KRW`, `MXN`, `MYR`, `NOK`, `NZD`, `PHP`, `PLN`, `RON`, `SEK`, `SGD`, `THB`, `TRY`, `USD`, `ZAR`.
     * - Uses cached rates unless `forceRefresh` is set to `true`.
     * - If API fails or currency not supported, falls back to `fallbackRate` if provided.
     * - Use {@link convertSync} method to convert to other currencies using custom exchange rate.
     *
     * @param to - The target currency code (must be one of the supported ones, e.g., `'EUR'`, `'USD'`).
     * @param options - Optional settings:
     *   - `fallbackRate`: A manual exchange rate to use if the API call fails or currency is not supported.
     *   - `forceRefresh`: If true, ignores cached rates and fetches fresh data.
     * @returns A new `Currency` instance with the converted amount in the target currency.
     * @throws Will throw error if the API call fails and no `fallbackRate` is provided.
     *
     * @example
     * await new Currency(100, 'USD').convert('EUR');
     */
    convert<To extends FrankFurterCurrency>(to: To, options?: ConvertOptions): Promise<Currency<To>>;
    /**
     * @instance Converts the current currency amount to a target currency using either a cached rate or a manual exchange rate.
     *
     * - This method is **synchronous** and does **not perform any network requests**.
     * - If a cached rate exists for the currency pair, it is used.
     * - If no cached rate is found, `rate` is used as a manual exchange rate.
     * - If neither are available, the original instance is returned unchanged.
     *
     * @param to - The target currency code to convert to.
     * @param rate - A manual exchange rate to use if no cached rate is available.
     * @returns A new `Currency` instance with the converted amount, or the original instance if no rate is available.
     *
     * @example
     * const usd = new Currency(100, 'USD');
     * const eur = usd.convertSync('EUR', 0.92);
     *
     * console.log(eur.currency); // €92.00
     */
    convertSync<To extends CurrencyCode>(to: To, rate: number): Currency<To>;
}