Money

Currency formatting, safe arithmetic, conversion, tax, discount, and exchange rates

Package: @robinpath/money | Category: Utility | Type: Utility

Authentication

No authentication required. All functions are available immediately.

Use Cases

Use the money module when you need to:

• Format number as currency -- Use money.format to perform this operation
• Parse currency string to number -- Use money.parse to perform this operation
• Safe addition -- Use money.add to perform this operation
• Safe subtraction -- Use money.subtract to perform this operation
• Safe multiplication -- Use money.multiply to perform this operation

Quick Reference

Function	Description	Returns
format	Format number as currency	Formatted string
parse	Parse currency string to number	Numeric value
add	Safe addition	Sum
subtract	Safe subtraction	Difference
multiply	Safe multiplication	Product
divide	Safe division	Quotient
round	Round to currency precision	Rounded value
convert	Convert between currencies	{amount, currency, rate}
fetchRate	Fetch live exchange rate	{rate, from, to, timestamp}
split	Split amount evenly	Array of amounts summing to total
percentage	Calculate percentage	Result
discount	Apply discount	{original, discount, final}
tax	Add tax	{subtotal, tax, total}
currencyInfo	Get currency info	{symbol, name, decimals, code}
listCurrencies	List all currency codes	Currency codes
isValidCode	Check if currency code is valid	true if valid

Functions

format

Format number as currency

Module: money | Returns: string -- Formatted string

money.format 1234.56 "USD"

Parameter	Type	Required	Description
amount	number	Yes	Amount
currency	string	No	Currency code (default USD)
locale	string	No	Locale (default en-US)

---

parse

Parse currency string to number

Module: money | Returns: number -- Numeric value

money.parse "$1,234.56"

Parameter	Type	Required	Description
str	string	Yes	Currency string

---

add

Safe addition

Module: money | Returns: number -- Sum

money.add 0.1 0.2

Parameter	Type	Required	Description
a	number	Yes	First value
b	number	Yes	Second value
decimals	number	No	Decimal places (default 2)

---

subtract

Safe subtraction

Module: money | Returns: number -- Difference

money.subtract 10.50 3.25

Parameter	Type	Required	Description
a	number	Yes	First value
b	number	Yes	Second value
decimals	number	No	Decimal places

---

multiply

Safe multiplication

Module: money | Returns: number -- Product

money.multiply 19.99 3

Parameter	Type	Required	Description
amount	number	Yes	Amount
multiplier	number	Yes	Multiplier

---

divide

Safe division

Module: money | Returns: number -- Quotient

money.divide 100 3

Parameter	Type	Required	Description
amount	number	Yes	Amount
divisor	number	Yes	Divisor

---

round

Round to currency precision

Module: money | Returns: number -- Rounded value

money.round 10.456

Parameter	Type	Required	Description
amount	number	Yes	Amount
decimals	number	No	Decimal places (default 2)

---

convert

Convert between currencies

Module: money | Returns: object -- {amount, currency, rate}

money.convert 100 "USD" "EUR" 0.85

Parameter	Type	Required	Description
amount	number	Yes	Amount
from	string	Yes	Source currency
to	string	Yes	Target currency
rate	number	Yes	Exchange rate

---

fetchRate

Fetch live exchange rate

Module: money | Returns: object -- {rate, from, to, timestamp}

money.fetchRate "USD" "EUR"

Parameter	Type	Required	Description
from	string	Yes	Source currency
to	string	Yes	Target currency

---

split

Split amount evenly

Module: money | Returns: array -- Array of amounts summing to total

money.split 100 3

Parameter	Type	Required	Description
amount	number	Yes	Total amount
ways	number	Yes	Number of splits

---

percentage

Calculate percentage

Module: money | Returns: number -- Result

money.percentage 200 15

Parameter	Type	Required	Description
amount	number	Yes	Amount
percent	number	Yes	Percentage

---

discount

Apply discount

Module: money | Returns: object -- {original, discount, final}

money.discount 99.99 20

Parameter	Type	Required	Description
amount	number	Yes	Original amount
percent	number	Yes	Discount %

---

tax

Add tax

Module: money | Returns: object -- {subtotal, tax, total}

money.tax 100 8.25

Parameter	Type	Required	Description
amount	number	Yes	Subtotal
rate	number	Yes	Tax rate %

---

currencyInfo

Get currency info

Module: money | Returns: object -- {symbol, name, decimals, code}

money.currencyInfo "EUR"

Parameter	Type	Required	Description
code	string	Yes	Currency code

---

listCurrencies

List all currency codes

Module: money | Returns: array -- Currency codes

money.listCurrencies

Parameter	Type	Required	Description
(none)		No	Call with no arguments

---

isValidCode

Check if currency code is valid

Module: money | Returns: boolean -- true if valid

money.isValidCode "USD"

Parameter	Type	Required	Description
code	string	Yes	Currency code

---

Error Handling

All functions throw on failure. Common errors:

Error	Cause
Division by zero	Check the error message for details
Rate not found for ${from} -> ${to}	Check the error message for details

@desc "Format and validate result"
do
  set $result as money.format 1234.56 "USD"
  if $result != null
    print "Success"
  else
    print "No result"
  end
enddo

Recipes

1. List and iterate Currencies

Retrieve all items and loop through them.

@desc "List currencies and iterate results"
do
  set $result as money.listCurrencies
  each $item in $result
    print $item
  end
enddo

2. Create a new item with add

Create a new resource and capture the result.

set $result as money.add 0.1 0.2
print "Created: " + $result

3. Check before creating

List existing items and only create if needed.

@desc "List currencies and add"
do
  set $existing as money.listCurrencies
  if $existing == null
    money.add 0.1 0.2
    print "Item created"
  else
    print "Item already exists"
  end
enddo

4. Multi-step Money workflow

Chain multiple money operations together.

@desc "Format, parse, and more"
do
  set $r_format as money.format 1234.56 "USD"
  set $r_parse as money.parse "$1,234.56"
  set $r_add as money.add 0.1 0.2
  print "All operations complete"
enddo

5. Safe format with validation

Check results before proceeding.

@desc "Format and validate result"
do
  set $result as money.format 1234.56 "USD"
  if $result != null
    print "Success: " + $result
  else
    print "Operation returned no data"
  end
enddo

Related Modules

• json -- JSON module for complementary functionality