@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.
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.
Example
getCurrencySymbol('USD') // '$'
getCurrencySymbol('EUR') // '€'
getCurrencySymbol('JPY') // '¥'
getCurrencyName()
getCurrencyName(
currency,locale?):string|undefined
Defined in: currency/index.ts:60
Returns the full display name of a currency.
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.
Example
getCurrencyName('USD') // 'US Dollar'
getCurrencyName('EUR') // 'Euro'
getCurrencyName('JPY', 'ja') // '日本円'
getCurrencyLocale()
getCurrencyLocale(
currency):string
Defined in: currency/index.ts:81
Returns the default locale typically associated with a currency.
Parameters
currency
string
The ISO 4217 currency code.
Returns
string
The locale string (e.g., 'en-US' for USD), or 'en' as fallback.
Example
getCurrencyLocale('USD') // 'en-US'
getCurrencyLocale('EUR') // 'de-DE'
getCurrencyLocale('JPY') // 'ja-JP'
formatPrice()
formatPrice(
price,currency?,locale?):string
Defined in: currency/index.ts:132
Formats a given price value into a localized currency string.
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.
Example
formatPrice(1234.56, 'USD') // '$1,234.56'
formatPrice(1234.56, 'EUR') // '1.234,56 €'
formatPrice(1234.56, 'JPY') // '¥1,235'
formatPriceCompact()
formatPriceCompact(
price,currency?,locale?):string
Defined in: currency/index.ts:156
Formats a price in compact notation (e.g., $1.2K, $1.5M).
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.
Example
formatPriceCompact(1234) // '$1.2K'
formatPriceCompact(1234567) // '$1.2M'
formatPriceCompact(1234567890) // '$1.2B'
formatPriceCompact(1500, 'EUR') // '1,5 Tsd. €'
parsePrice()
parsePrice(
value):number|null
Defined in: currency/index.ts:183
Parses a given price string and returns its numeric value.
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.
Example
parsePrice('$1,234.56') // 1234.56
parsePrice('€1.234,56') // 1234.56
parsePrice('invalid') // null
parseCurrencyString()
parseCurrencyString(
value): {amount:number;currency:string; } |null
Defined in: currency/index.ts:212
Parses a currency string and extracts both the amount and currency code.
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.
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
convertCurrency()
convertCurrency(
amount,rate,decimals?):number
Defined in: currency/index.ts:271
Converts a given amount from one currency to another using the provided exchange rate.
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.
Example
convertCurrency(100, 0.85) // 85 (e.g., USD to EUR)
convertCurrency(100, 110.5, 0) // 11050 (e.g., USD to JPY)
isValidCurrencyCode()
isValidCurrencyCode(
code):Promise<boolean>
Defined in: currency/index.ts:289
Checks if the provided currency code is valid.
This function lazily loads the currencies list to minimize bundle size impact.
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.
Example
await isValidCurrencyCode('USD') // true
await isValidCurrencyCode('INVALID') // false
isValidCurrency()
isValidCurrency(
code):boolean
Defined in: currency/index.ts:308
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.
Parameters
code
string
The currency code to validate.
Returns
boolean
true if the currency code is valid; otherwise, false.
Example
isValidCurrency('USD') // true
isValidCurrency('INVALID') // false
roundTo()
roundTo(
value,decimals?):number
Defined in: currency/index.ts:330
Rounds a given number to a specified number of decimal places.
Parameters
value
number
The number to be rounded.
decimals?
number = 2
The number of decimal places to round to. Defaults to 2.
Returns
number
The rounded number.
Example
roundTo(3.14159, 2) // 3.14
roundTo(10.5, 0) // 11