@rtorcato/js-common / currency
currency
Functions
getCurrencySymbol()
getCurrencySymbol(
currency):string|undefined
Defined in: currency/index.ts:32
Returns the currency symbol for a given ISO 4217 currency code.
Utilizes the Intl.NumberFormat API to format a number as currency and extract the symbol.
Example
getCurrencySymbol('USD') // '$'
getCurrencySymbol('EUR') // '€'
getCurrencySymbol('JPY') // '¥'
Parameters
currency
string
The ISO 4217 currency code (e.g., 'USD', 'EUR', 'JPY').
Returns
string | undefined
The currency symbol as a string (e.g., '$', '€', '¥'), or undefined if the symbol cannot be determined.
getCurrencyName()
getCurrencyName(
currency,locale?):string|undefined
Defined in: currency/index.ts:60
Returns the full display name of a currency.
Example
getCurrencyName('USD') // 'US Dollar'
getCurrencyName('EUR') // 'Euro'
getCurrencyName('JPY', 'ja') // '日本円'
Parameters
currency
string
The ISO 4217 currency code (e.g., 'USD', 'EUR').
locale?
string = 'en'
The locale to use for the display name. Defaults to 'en'.
Returns
string | undefined
The full currency name (e.g., 'US Dollar'), or undefined if invalid.
getCurrencyLocale()
getCurrencyLocale(
currency):string
Defined in: currency/index.ts:81
Returns the default locale typically associated with a currency.
Example
getCurrencyLocale('USD') // 'en-US'
getCurrencyLocale('EUR') // 'de-DE'
getCurrencyLocale('JPY') // 'ja-JP'
Parameters
currency
string
The ISO 4217 currency code.
Returns
string
The locale string (e.g., 'en-US' for USD), or 'en' as fallback.
formatPrice()
formatPrice(
price,currency?,locale?):string
Defined in: currency/index.ts:132
Formats a given price value into a localized currency string.
Example
formatPrice(1234.56, 'USD') // '$1,234.56'
formatPrice(1234.56, 'EUR') // '1.234,56 €'
formatPrice(1234.56, 'JPY') // '¥1,235'
Parameters
price
string | number
The numeric value or string representation of the price to format.
currency?
string = 'USD'
The ISO 4217 currency code. Defaults to 'USD'.
locale?
string
The locale to use for formatting. If not provided, uses the currency's default locale.
Returns
string
The formatted currency string.
formatPriceCompact()
formatPriceCompact(
price,currency?,locale?):string
Defined in: currency/index.ts:156
Formats a price in compact notation (e.g., $1.2K, $1.5M).
Example
formatPriceCompact(1234) // '$1.2K'
formatPriceCompact(1234567) // '$1.2M'
formatPriceCompact(1234567890) // '$1.2B'
formatPriceCompact(1500, 'EUR') // '1,5 Tsd. €'
Parameters
price
string | number
The numeric value to format.
currency?
string = 'USD'
The ISO 4217 currency code. Defaults to 'USD'.
locale?
string
The locale to use for formatting.
Returns
string
The formatted compact currency string.
parsePrice()
parsePrice(
value):number|null
Defined in: currency/index.ts:183
Parses a given price string and returns its numeric value.
Example
parsePrice('$1,234.56') // 1234.56
parsePrice('€1.234,56') // 1234.56
parsePrice('invalid') // null
Parameters
value
string
The price string to parse.
Returns
number | null
The numeric value of the price, or null if the value cannot be parsed.
parseCurrencyString()
parseCurrencyString(
value): {amount:number;currency:string; } |null
Defined in: currency/index.ts:214
Parses a currency string and extracts both the amount and currency code.
Example
parseCurrencyString('$1,234.56') // { amount: 1234.56, currency: 'USD' }
parseCurrencyString('€100') // { amount: 100, currency: 'EUR' }
parseCurrencyString('1000 JPY') // { amount: 1000, currency: 'JPY' }
parseCurrencyString('invalid') // null
Parameters
value
string
The currency string to parse (e.g., '$1,234.56', 'EUR 100').
Returns
{ amount: number; currency: string; } | null
An object with amount and currency, or null if parsing fails.
convertCurrency()
convertCurrency(
amount,rate,decimals?):number
Defined in: currency/index.ts:273
Converts a given amount from one currency to another using the provided exchange rate.
Example
convertCurrency(100, 0.85) // 85 (e.g., USD to EUR)
convertCurrency(100, 110.5, 0) // 11050 (e.g., USD to JPY)
Parameters
amount
number
The amount of money to convert.
rate
number
The exchange rate to use for the conversion.
decimals?
number = 2
The number of decimal places to include in the result. Defaults to 2.
Returns
number
The converted amount as a number.
isValidCurrencyCode()
isValidCurrencyCode(
code):Promise<boolean>
Defined in: currency/index.ts:291
Checks if the provided currency code is valid.
This function lazily loads the currencies list to minimize bundle size impact.
Example
await isValidCurrencyCode('USD') // true
await isValidCurrencyCode('INVALID') // false
Parameters
code
string
The currency code to validate (e.g., 'USD', 'eur').
Returns
Promise<boolean>
Promise resolving to true if the currency code is valid; otherwise, false.
isValidCurrency()
isValidCurrency(
code):boolean
Defined in: currency/index.ts:310
Synchronously checks if a currency code is valid using the Intl API.
This does not require loading the currencies list and has zero bundle size impact.
Example
isValidCurrency('USD') // true
isValidCurrency('INVALID') // false
Parameters
code
string
The currency code to validate.
Returns
boolean
true if the currency code is valid; otherwise, false.