Suites · money-basics
Money basics
Amounts in integer minor units: add, total, apply rates, split without losing a penny, compare, format, parse and convert.
16 capabilities (8 core, 8 optional) and 2 gaps, in build order. Put each line in the file that calls it, then fune build.
TypeScript Python Rust
1. Amounts
Hold money as currency-tagged integer minor units and do plain arithmetic on it safely.
money.amount core
The Money type ({ minor, currency }) every other money capability takes and returns.
A currency-tagged monetary amount held in integer minor units.
import { money } from "#fune/money.amount@^1" ;
1.0.2
money.add core
Adds and subtracts amounts, refusing to mix currencies by accident.
Add, subtract and negate monetary amounts, refusing to mix currencies.
import { addMoney } from "#fune/money.add@^1" ;
1.0.1
money.sum core
Totals a list of amounts, with an explicit currency for an empty list.
Total a list of monetary amounts, with an explicit currency for the empty case.
import { sumMoney } from "#fune/money.sum@^1" ;
1.0.1
money.compare core
Compares, mins, maxes and clamps amounts of one currency without unwrapping them.
Compare two amounts of one currency, refusing to compare across currencies; min, max and clamp too.
import { compareMoney, minMoney, maxMoney, clampMoney } from "#fune/money.compare@^2" ;
2.0.04 functions
2. Rates and rounding
Apply percentages and divide amounts with the rounding stated, never a float.
money.apply-rate core
Applies a basis-point rate (VAT, discount, commission) to an amount with explicit rounding.
Apply a rate expressed in basis points to a monetary amount, with an explicit rounding mode.
import { applyRate } from "#fune/money.apply-rate@^1" ;
1.0.1
math.round-div core
Integer division with a named rounding mode, for any money maths the others do not cover.
Integer division with an explicit rounding mode, for money arithmetic that must not drift.
import { roundDiv } from "#fune/math.round-div@^1" ;
1.0.0
math.basis-points optional
Converts "12.5%" to and from basis points exactly, for rates typed in by users.
Convert a rate between percent, basis points and a plain ratio exactly, as decimal text or integer basis points.
import { convertRate, toBasisPoints, fromBasisPoints } from "#fune/math.basis-points@^2" ;
2.0.03 functions
math.percent-change optional
Percentage change between two figures in basis points, for "up 4.2% on last month".
Percentage change from one value to another, in basis points, with an explicit rounding mode.
import { percentChange } from "#fune/math.percent-change@^1" ;
1.0.0
math.rational optional
Exact fractions for rates that must not drift across many steps.
Exact fraction arithmetic, always reduced, for rates and ratios that must not drift.
import { calculateRational, rational, addRational, subtractRational, multiplyRational, divideRational, compareRational, rationalToInteger } from "#fune/math.rational@^2" ;
2.0.08 functions
math.round-div-big optional
Rounded division on numbers past 2^53, for very large totals.
Divide two integers of any size with an explicit rounding mode, on decimal strings, for exact money sums past 2^53.
import { roundDivBig } from "#fune/math.round-div-big@^1" ;
1.0.0
3. Splitting
Divide an amount between people, periods or lines so the parts add back to the whole.
money.allocate core
Splits an amount by ratios (60/40, by quantity) without losing or inventing a penny.
Split an amount across ratios without losing or inventing a single minor unit.
import { allocate } from "#fune/money.allocate@^1" ;
1.0.1
money.split-even optional
Splits an amount into n near-equal parts that sum exactly, for instalments or shares.
Split an amount into n near-equal parts that add back up to exactly the whole.
import { splitEven } from "#fune/money.split-even@^1" ;
1.0.0
4. Display and input
Show amounts to people and read what they type.
money.format core
Renders an amount as text with the currency's real number of decimal places.
Render a monetary amount as text, using the currency's real minor-unit precision.
import { formatMoney } from "#fune/money.format@^1" ;
1.0.0
money.parse optional
Reads "£1,234.50" or "1.234,50 €" typed by a user into minor units, strictly.
Parse "£1,234.50" or "1.234,50 €" into integer minor units, strictly: no guessing, no rounding.
import { parseMoney } from "#fune/money.parse@^1" ;
1.0.0
money.currency-digits optional
How many decimal places each ISO 4217 currency has, for input boxes and validation.
How many decimal places a currency's minor unit has, from the ISO 4217 list.
import { currencyDigits } from "#fune/money.currency-digits@^1" ;
1.0.0
5. Other currencies
Convert between currencies at a rate you hold.
money.convert optional
Converts an amount at a supplied exact rate with explicit rounding.
Convert an amount to another currency at a supplied exact rate, with an explicit rounding mode.
import { convertMoney } from "#fune/money.convert@^1" ;
1.0.0
Gaps What this kind of app usually needs that Functional Weave does not have yet: write these yourself, or use a service.
fx-rate-source Where exchange rates come from: money.convert takes a rate you supply; fetching and storing daily rates (ECB, a provider's API) is yours.money-storage Storing amounts: the database columns (integer minor units plus a currency code) and their migrations are yours.