API reference

Rates in the JavaScript API are fractions; 0.05 means 5%. CLI rates are percentages. All returned amounts are integer cents. Total dollar inputs may use strings such as 450M, $1,234.56 or 1.2B.

calculateAnnuity(options)

total is required. Defaults are payments=30, growthRate=0.05, discountRate=0.04 and timing='due'. The return object contains these settings, totalCents, presentValueCents and rows. Each row contains payment (one-based), year, amountCents and presentValueCents.

annuitySchedule(totalCents, payments=30, growthRate=0.05)

Returns an integer-cent array. Its sum equals the exact input total. Payments must be 1–1000. Growth must be greater than -1 and at most 1. Zero growth gives equal unrounded payments; rounding distributes indivisible cents.

presentValue(cashFlows, discountRate=0.04, timing=’due’)

Accepts 1–1000 nonnegative integer-cent flows and returns an aggregate value rounded once. Discount must be between 0 and 1. Use due for years 0…n−1, ordinary for years 1…n. Flows may be gross or caller-computed net amounts.

parseAmount(value)

Parses dollar numbers or strings into cents. Conventional comma groups and K/M/B suffixes are allowed; scientific notation strings and fractions of a cent are rejected. Neither individual amounts nor combined flows may exceed Number.MAX_SAFE_INTEGER cents. Use strings for large inputs to preserve cents.

toCSV(result)

Exports a calculation result as LF-terminated CSV with columns payment,year,amount_usd,present_value_usd. Monetary cells use two decimal places and no thousands separators. JSON output retains integer-cent fields.

Validation errors

Invalid amounts, rates, payment counts, timing or unsafe integers throw RangeError (invalid amount input types throw TypeError). The CLI writes a concise message to stderr and exits with status 1. It does not silently replace invalid parameters with defaults.