@typedly/currency/index.d.ts

A TypeScript type definitions package for currency.

/**
 * @description The options for formatting currency values.
 * @export
 * @interface CurrencyValueOptions
 */
interface CurrencyValueOptions {
    /**
     * @description Optional. The locale string (e.g., 'en-US', 'de-DE') used to format the currency value according to local conventions.
     * @type {?string}
     */
    locales?: string;
    /**
     * @description Optional. Specifies the maximum number of decimal digits to display (e.g., 2 for cents).
     * @type {?number}
     */
    maximumFractionDigits?: number;
    /**
     * @description Optional. Specifies the minimum number of decimal digits to display (e.g., 2 to always show cents, even for whole numbers).
     * @type {?number}
     */
    minimumFractionDigits?: number;
}

/**
 * @description The value with currency.
 * @export
 * @template {number | string} Value
 * @template {string} Currency
 */
type ValueWithCurrency<Value extends number | string, Currency extends string> = `${Currency} ${Value}`;

/**
 * @description
 * @export
 * @interface CurrencyValueType
 * @template {number} Value
 * @template {string} [Currency=string]
 */
interface CurrencyValueType<Value extends number, Currency extends string = string> {
    /**
     * @description The formatted string representation of the value (e.g., "$1,234.56").
     * @type {string}
     */
    formatted: string;
    /**
     * @description The raw numeric value.
     * @type {Value}
     */
    of: Value;
    /**
     * @description The value paired with its currency code, for strict typing or display.
     * @type {ValueWithCurrency<Value, Currency>}
     */
    withCurrency: ValueWithCurrency<Value, Currency>;
}

/**
 * @description
 * @export
 * @template {string} OfCurrency
 */
type ConversionRates<OfCurrency extends string> = {
    [Key in OfCurrency]?: number;
};

/**
 * Some of crypto currencies.
 */
type CryptoCurrencies = '1INCH' | 'AAVE' | 'ADA' | 'ALGO' | 'AMP' | 'ANC' | 'ANKT' | 'ANYSWAP' | 'APX' | 'AR' | 'ATOM' | 'AURORA' | 'AVA' | 'AVAX' | 'AWC' | 'AXS' | 'BAKE' | 'BAL' | 'BAND' | 'BAT' | 'BCH' | 'BIT' | 'BMX' | 'BNB' | 'BNT' | 'BORA' | 'BSV' | 'BTC' | 'BTCB' | 'BTG' | 'BTT' | 'BUSD' | 'CAKE' | 'CEL' | 'CELO' | 'CHZ' | 'CLV' | 'COMP' | 'COTI' | 'CRO' | 'CRV' | 'CUMMIES' | 'CVC' | 'CVX' | 'DAG' | 'DAI' | 'DAO' | 'DASH' | 'DCR' | 'DENT' | 'DFI' | 'DOGE' | 'DOT' | 'DUSK' | 'DYDYX' | 'EGLD' | 'ENJ' | 'EOS' | 'ETC' | 'ETH' | 'EWT' | 'FIL' | 'FLOW' | 'FLUX' | 'FRAX' | 'FTM' | 'FTT' | 'FUN' | 'FWT' | 'GALA' | 'GAS' | 'GHX' | 'GRT' | 'GTC' | 'GUSD' | 'HBAR' | 'HBTC' | 'HERO' | 'HEX' | 'HIVE' | 'HNT' | 'HOT' | 'HPT' | 'HT' | 'ICP' | 'IOTX' | 'JOE' | 'KAI' | 'KARMA' | 'KCS' | 'KDA' | 'KIN' | 'KLAY' | 'KMD' | 'KSM' | 'LEO' | 'LINK' | 'LN' | 'LRC' | 'LTC' | 'LUNA' | 'MANA' | 'MASK' | 'MATIC' | 'MDX' | 'MED' | 'META' | 'MINA' | 'MIOTA' | 'MKR' | 'MOVR' | 'MXC' | 'NEAR' | 'NEO' | 'NEXO' | 'OCEAN' | 'OKB' | 'OMG' | 'ONE' | 'ONT' | 'OSMO' | 'OXT' | 'PAXG' | 'PLA' | 'POLY' | 'PSP' | 'QNT' | 'RAD' | 'RAMP' | 'REEF' | 'REV' | 'ROSE' | 'RUNE' | 'SAFE' | 'SAND' | 'SCRT' | 'SFP' | 'SHIB' | 'SLP' | 'SOL' | 'SOUL' | 'STEEM' | 'STX' | 'SUN' | 'SUSHI' | 'SWP' | 'SXP' | 'TEL' | 'TFUEL' | 'THETA' | 'TITAN' | 'TLOS' | 'TON' | 'TRX' | 'TUSD' | 'TWT' | 'UNI' | 'USDC' | 'USDN' | 'USDP' | 'USDT' | 'UST' | 'VALOR' | 'VELO' | 'VET' | 'VRA' | 'WAVES' | 'WBNB' | 'WBTC' | 'WRX' | 'WTRX' | 'XAUT' | 'XCH' | 'XDC' | 'XEC' | 'XEM' | 'XHV' | 'XLM' | 'XNO' | 'XNR' | 'XPR' | 'XPRT' | 'XRP' | 'XTZ' | 'XYM' | 'YFI' | 'ZEC' | 'ZRX';

type FiatCurrencies = 'ADP' | 'AED' | 'AFA' | 'AFN' | 'ALK' | 'ALL' | 'AMD' | 'ANG' | 'AOA' | 'AOK' | 'AON' | 'AOR' | 'ARA' | 'ARP' | 'ARS' | 'ARY' | 'ATS' | 'AUD' | 'AWG' | 'AYM' | 'AZM' | 'AZN' | 'BAD' | 'BAM' | 'BBD' | 'BDT' | 'BEC' | 'BEF' | 'BEL' | 'BGJ' | 'BGK' | 'BGL' | 'BGN' | 'BHD' | 'BIF' | 'BMD' | 'BND' | 'BOB' | 'BOP' | 'BOV' | 'BRB' | 'BRC' | 'BRE' | 'BRL' | 'BRN' | 'BRR' | 'BSD' | 'BTN' | 'BUK' | 'BWP' | 'BYB' | 'BYN' | 'BYR' | 'BZD' | 'CAD' | 'CDF' | 'CHC' | 'CHE' | 'CHF' | 'CHF' | 'CHW' | 'CLF' | 'CLP' | 'CNY' | 'COP' | 'COU' | 'CRC' | 'CSD' | 'CSJ' | 'CSK' | 'CUC' | 'CUP' | 'CVE' | 'CYP' | 'CZK' | 'DDM' | 'DEM' | 'DJF' | 'DKK' | 'DOP' | 'DZD' | 'ECS' | 'ECV' | 'EEK' | 'EGP' | 'ERN' | 'ESA' | 'ESB' | 'ESP' | 'ETB' | 'EUR' | 'FIM' | 'FJD' | 'FKP' | 'FRF' | 'GBP' | 'GEK' | 'GEL' | 'GHC' | 'GHP' | 'GHS' | 'GIP' | 'GMD' | 'GNE' | 'GNF' | 'GNS' | 'GQE' | 'GRD' | 'GTQ' | 'GWE' | 'GWP' | 'GYD' | 'HKD' | 'HNL' | 'HRD' | 'HRK' | 'HTG' | 'HUF' | 'IDR' | 'IDR' | 'IEP' | 'ILP' | 'ILR' | 'ILS' | 'INR' | 'IQD' | 'IRR' | 'ISJ' | 'ISK' | 'ITL' | 'JMD' | 'JOD' | 'JPY' | 'KES' | 'KGS' | 'KHR' | 'KMF' | 'KPW' | 'KRW' | 'KWD' | 'KYD' | 'KZT' | 'LAJ' | 'LAK' | 'LBP' | 'LKR' | 'LRD' | 'LSL' | 'LSM' | 'LTL' | 'LTT' | 'LUC' | 'LUF' | 'LUL' | 'LVL' | 'LVR' | 'LYD' | 'MAD' | 'MDL' | 'MGA' | 'MGF' | 'MKD' | 'MLF' | 'MMK' | 'MNT' | 'MOP' | 'MRO' | 'MRU' | 'MTL' | 'MTP' | 'MUR' | 'MVQ' | 'MVR' | 'MWK' | 'MWK' | 'MXN' | 'MXP' | 'MXV' | 'MYR' | 'MZE' | 'MZM' | 'MZN' | 'NAD' | 'NGN' | 'NIC' | 'NIO' | 'NLG' | 'NOK' | 'NPR' | 'NZD' | 'OMR' | 'PAB' | 'PEH' | 'PEI' | 'PEN' | 'PES' | 'PGK' | 'PHP' | 'PKR' | 'PLN' | 'PLZ' | 'PTE' | 'PYG' | 'QAR' | 'RHD' | 'ROK' | 'ROL' | 'RON' | 'RSD' | 'RUB' | 'RUR' | 'RWF' | 'SAR' | 'SBD' | 'SCR' | 'SDD' | 'SDG' | 'SDP' | 'SEK' | 'SGD' | 'SHP' | 'SIT' | 'SKK' | 'SLL' | 'SOS' | 'SRD' | 'SRG' | 'SSP' | 'STD' | 'STN' | 'SUR' | 'SVC' | 'SYP' | 'SZL' | 'THB' | 'TJR' | 'TJS' | 'TMM' | 'TMT' | 'TND' | 'TOP' | 'TPE' | 'TRL' | 'TRY' | 'TTD' | 'TWD' | 'TZS' | 'UAH' | 'UAK' | 'UGS' | 'UGW' | 'UGX' | 'USD' | 'USN' | 'USS' | 'UYI' | 'UYN' | 'UYP' | 'UYU' | 'UYW' | 'UZS' | 'VEB' | 'VEF' | 'VES' | 'VNC' | 'VND' | 'VUV' | 'WST' | 'XAF' | 'XAG' | 'XAU' | 'XBA' | 'XBB' | 'XBC' | 'XBD' | 'XCD' | 'XDR' | 'XEU' | 'XFO' | 'XFU' | 'XOF' | 'XPD' | 'XPF' | 'XPT' | 'XRE' | 'XSU' | 'XTS' | 'XUA' | 'XXX' | 'YDD' | 'YER' | 'YUD' | 'YUM' | 'YUN' | 'ZAL' | 'ZAR' | 'ZMK' | 'ZMW' | 'ZRN' | 'ZRZ' | 'ZWC' | 'ZWD' | 'ZWL' | 'ZWN' | 'ZWR';

type AllCurrencies<Additional extends string> = CryptoCurrencies | FiatCurrencies | Additional;

type FiatCurrencySymbol = Partial<{
    AFN: '؋';
    ANG: 'ƒ';
    ARS: '$';
    AWG: 'ƒ';
    AZN: '₼';
    BBD: '$';
    BGN: 'лв';
    BND: '$';
    BRL: 'R$';
    BSD: '$';
    BYN: 'Br';
    BZD: 'BZ$';
    CAD: '$';
    CLP: '$';
    CNY: '¥';
    COP: '$';
    CRC: '₡';
    CUP: '₱';
    CZK: 'Kč';
    DKK: 'kr';
    DOP: 'RD$';
    EGP: '£';
    EUR: '€';
    FJD: '$';
    FKP: '£';
    GBP: '£';
    GGP: '£';
    GHS: '¢';
    GIP: '£';
    GTQ: 'Q';
    GYD: '$';
    HKD: '$';
    HNL: 'L';
    HRK: 'kn';
    HUF: 'Ft';
    IDR: 'Rp';
    ILS: '₪';
    IMP: '£';
    IRR: '﷼';
    ISK: 'kr';
    JEP: '£';
    JMD: 'J$';
    JPY: '¥';
    KGS: 'лв';
    KHR: '៛';
    KPW: '₩';
    KRW: '₩';
    KYD: '$';
    KZT: 'лв';
    LAK: '₭';
    LBP: '£';
    LKR: '₨';
    LRD: '$';
    MKD: 'ден';
    MNT: '₮';
    MUR: '₨';
    MXN: '$';
    MYR: 'RM';
    MZN: 'MT';
    NAD: '$';
    NGN: '₦';
    NIO: 'C$';
    NOK: 'kr';
    NPR: '₨';
    NZD: '$';
    OMR: '﷼';
    PAB: 'B/.';
    PEN: 'S/.';
    PHP: '₱';
    PKR: 'Rs';
    PLN: 'zł';
    PYG: 'Gs';
    QAR: '﷼';
    RON: 'lei';
    RSD: 'Дин.';
    RUB: '₽';
    SAR: '﷼';
    SBD: '$';
    SCR: '₨';
    SEK: 'kr';
    SGD: '$';
    SHP: '£';
    SOS: 'S';
    SRD: '$';
    SVC: '$';
    SYP: '£';
    THB: '฿';
    TTD: 'TT$';
    TVD: '$';
    TWD: 'NT$';
    UAH: '₴';
    USD: '$';
    UYU: '$U';
    UZS: 'лв';
    VEF: 'Bs';
    VND: '₫';
    XCD: '$';
    YER: '﷼';
    ZAR: 'R';
    ZWD: 'Z$';
}>;

/**
 * @description
 * @export
 * @template {keyof FiatCurrencySymbol} Currency
 */
type FiatCurrencyToSymbol<Currency extends keyof FiatCurrencySymbol> = `${FiatCurrencySymbol[Currency]}`;

export type { AllCurrencies, ConversionRates, CryptoCurrencies, CurrencyValueOptions, CurrencyValueType, FiatCurrencies, FiatCurrencySymbol, FiatCurrencyToSymbol, ValueWithCurrency };