{
  "id": "money-basics",
  "title": "Money basics",
  "summary": "Amounts in integer minor units: add, total, apply rates, split without losing a penny, compare, format, parse and convert.",
  "synonyms": [
    "money",
    "currency",
    "amounts",
    "prices",
    "pounds and pence",
    "minor units",
    "rounding money"
  ],
  "apps": [
    "any app that handles prices or payments",
    "money arithmetic for a backend"
  ],
  "language": "typescript",
  "includes": [],
  "includedBy": [
    "accounting",
    "agriculture",
    "banking",
    "charity",
    "construction",
    "ecommerce",
    "energy",
    "fleet",
    "hospitality",
    "insurance",
    "inventory",
    "investments",
    "invoicing",
    "legal",
    "lending",
    "logistics",
    "payroll",
    "professional-services",
    "property",
    "subscriptions",
    "telecoms"
  ],
  "caveats": [],
  "sections": [
    {
      "key": "amounts",
      "title": "Amounts",
      "purpose": "Hold money as currency-tagged integer minor units and do plain arithmetic on it safely.",
      "from": "money-basics",
      "members": [
        {
          "id": "money.amount",
          "tier": "core",
          "why": "The Money type ({ minor, currency }) every other money capability takes and returns.",
          "section": "amounts",
          "from": "money-basics",
          "version": "1.0.2",
          "summary": "A currency-tagged monetary amount held in integer minor units.",
          "status": "stable",
          "license": "NOASSERTION",
          "languages": [
            "typescript",
            "python",
            "rust"
          ],
          "available": true,
          "group": false,
          "functions": [
            "money"
          ],
          "signatures": [
            "export function money(minor: number, currency: string): Money"
          ],
          "reference": "import { money } from \"#fune/money.amount@^1\";",
          "url": "http://www.functionalweave.com/functions/money.amount"
        },
        {
          "id": "money.add",
          "tier": "core",
          "why": "Adds and subtracts amounts, refusing to mix currencies by accident.",
          "section": "amounts",
          "from": "money-basics",
          "version": "1.0.1",
          "summary": "Add, subtract and negate monetary amounts, refusing to mix currencies.",
          "status": "stable",
          "license": "NOASSERTION",
          "languages": [
            "typescript",
            "python",
            "rust"
          ],
          "available": true,
          "group": false,
          "functions": [
            "addMoney"
          ],
          "signatures": [
            "export function addMoney(a: Money, b: Money): Money"
          ],
          "reference": "import { addMoney } from \"#fune/money.add@^1\";",
          "url": "http://www.functionalweave.com/functions/money.add"
        },
        {
          "id": "money.sum",
          "tier": "core",
          "why": "Totals a list of amounts, with an explicit currency for an empty list.",
          "section": "amounts",
          "from": "money-basics",
          "version": "1.0.1",
          "summary": "Total a list of monetary amounts, with an explicit currency for the empty case.",
          "status": "stable",
          "license": "NOASSERTION",
          "languages": [
            "typescript",
            "python",
            "rust"
          ],
          "available": true,
          "group": false,
          "functions": [
            "sumMoney"
          ],
          "signatures": [
            "export function sumMoney(amounts: readonly Money[], currency: string): Money"
          ],
          "reference": "import { sumMoney } from \"#fune/money.sum@^1\";",
          "url": "http://www.functionalweave.com/functions/money.sum"
        },
        {
          "id": "money.compare",
          "tier": "core",
          "why": "Compares, mins, maxes and clamps amounts of one currency without unwrapping them.",
          "section": "amounts",
          "from": "money-basics",
          "version": "2.0.0",
          "summary": "Compare two amounts of one currency, refusing to compare across currencies; min, max and clamp too.",
          "status": "stable",
          "license": "NOASSERTION",
          "languages": [
            "typescript",
            "python",
            "rust"
          ],
          "available": true,
          "group": true,
          "functions": [
            "compareMoney",
            "minMoney",
            "maxMoney",
            "clampMoney"
          ],
          "signatures": [
            "export function compareMoney(a: Money, b: Money): number",
            "export function minMoney(a: Money, b: Money): Money",
            "export function maxMoney(a: Money, b: Money): Money",
            "export function clampMoney(amount: Money, min: Money, max: Money): Money"
          ],
          "reference": "import { compareMoney, minMoney, maxMoney, clampMoney } from \"#fune/money.compare@^2\";",
          "url": "http://www.functionalweave.com/functions/money.compare"
        }
      ],
      "gaps": []
    },
    {
      "key": "rates",
      "title": "Rates and rounding",
      "purpose": "Apply percentages and divide amounts with the rounding stated, never a float.",
      "from": "money-basics",
      "members": [
        {
          "id": "money.apply-rate",
          "tier": "core",
          "why": "Applies a basis-point rate (VAT, discount, commission) to an amount with explicit rounding.",
          "section": "rates",
          "from": "money-basics",
          "version": "1.0.1",
          "summary": "Apply a rate expressed in basis points to a monetary amount, with an explicit rounding mode.",
          "status": "stable",
          "license": "NOASSERTION",
          "languages": [
            "typescript",
            "python",
            "rust"
          ],
          "available": true,
          "group": false,
          "functions": [
            "applyRate"
          ],
          "signatures": [
            "export function applyRate(amount: Money, basisPoints: number, mode: RoundingMode): Money"
          ],
          "reference": "import { applyRate } from \"#fune/money.apply-rate@^1\";",
          "url": "http://www.functionalweave.com/functions/money.apply-rate"
        },
        {
          "id": "math.round-div",
          "tier": "core",
          "why": "Integer division with a named rounding mode, for any money maths the others do not cover.",
          "section": "rates",
          "from": "money-basics",
          "version": "1.0.0",
          "summary": "Integer division with an explicit rounding mode, for money arithmetic that must not drift.",
          "status": "stable",
          "license": "NOASSERTION",
          "languages": [
            "typescript",
            "python",
            "rust"
          ],
          "available": true,
          "group": false,
          "functions": [
            "roundDiv"
          ],
          "signatures": [
            "export function roundDiv(numerator: number, denominator: number, mode: RoundingMode): number"
          ],
          "reference": "import { roundDiv } from \"#fune/math.round-div@^1\";",
          "url": "http://www.functionalweave.com/functions/math.round-div"
        },
        {
          "id": "math.basis-points",
          "tier": "optional",
          "why": "Converts \"12.5%\" to and from basis points exactly, for rates typed in by users.",
          "section": "rates",
          "from": "money-basics",
          "version": "2.0.0",
          "summary": "Convert a rate between percent, basis points and a plain ratio exactly, as decimal text or integer basis points.",
          "status": "stable",
          "license": "NOASSERTION",
          "languages": [
            "typescript",
            "python",
            "rust"
          ],
          "available": true,
          "group": true,
          "functions": [
            "convertRate",
            "toBasisPoints",
            "fromBasisPoints"
          ],
          "signatures": [
            "export function convertRate(value: string, fromUnit: RateUnit, toUnit: RateUnit): string",
            "export function toBasisPoints(value: string, unit: RateUnit): number",
            "export function fromBasisPoints(basisPoints: number, unit: RateUnit): string"
          ],
          "reference": "import { convertRate, toBasisPoints, fromBasisPoints } from \"#fune/math.basis-points@^2\";",
          "url": "http://www.functionalweave.com/functions/math.basis-points"
        },
        {
          "id": "math.percent-change",
          "tier": "optional",
          "why": "Percentage change between two figures in basis points, for \"up 4.2% on last month\".",
          "section": "rates",
          "from": "money-basics",
          "version": "1.0.0",
          "summary": "Percentage change from one value to another, in basis points, with an explicit rounding mode.",
          "status": "stable",
          "license": "NOASSERTION",
          "languages": [
            "typescript",
            "python",
            "rust"
          ],
          "available": true,
          "group": false,
          "functions": [
            "percentChange"
          ],
          "signatures": [
            "export function percentChange(fromValue: number, toValue: number, mode: RoundingMode): number | null"
          ],
          "reference": "import { percentChange } from \"#fune/math.percent-change@^1\";",
          "url": "http://www.functionalweave.com/functions/math.percent-change"
        },
        {
          "id": "math.rational",
          "tier": "optional",
          "why": "Exact fractions for rates that must not drift across many steps.",
          "section": "rates",
          "from": "money-basics",
          "version": "2.0.0",
          "summary": "Exact fraction arithmetic, always reduced, for rates and ratios that must not drift.",
          "status": "stable",
          "license": "NOASSERTION",
          "languages": [
            "typescript",
            "python",
            "rust"
          ],
          "available": true,
          "group": true,
          "functions": [
            "calculateRational",
            "rational",
            "addRational",
            "subtractRational",
            "multiplyRational",
            "divideRational",
            "compareRational",
            "rationalToInteger"
          ],
          "signatures": [
            "export function calculateRational(a: Rational, op: RationalOp, b: Rational): Rational",
            "export function rational(numerator: number, denominator: number): Rational",
            "export function addRational(a: Rational, b: Rational): Rational",
            "export function subtractRational(a: Rational, b: Rational): Rational",
            "export function multiplyRational(a: Rational, b: Rational): Rational",
            "export function divideRational(a: Rational, b: Rational): Rational",
            "export function compareRational(a: Rational, b: Rational): number",
            "export function rationalToInteger(r: Rational, mode: RoundingMode): number"
          ],
          "reference": "import { calculateRational, rational, addRational, subtractRational, multiplyRational, divideRational, compareRational, rationalToInteger } from \"#fune/math.rational@^2\";",
          "url": "http://www.functionalweave.com/functions/math.rational"
        },
        {
          "id": "math.round-div-big",
          "tier": "optional",
          "why": "Rounded division on numbers past 2^53, for very large totals.",
          "section": "rates",
          "from": "money-basics",
          "version": "1.0.0",
          "summary": "Divide two integers of any size with an explicit rounding mode, on decimal strings, for exact money sums past 2^53.",
          "status": "stable",
          "license": "NOASSERTION",
          "languages": [
            "typescript",
            "python",
            "rust"
          ],
          "available": true,
          "group": false,
          "functions": [
            "roundDivBig"
          ],
          "signatures": [
            "export function roundDivBig(numerator: string, denominator: string, mode: RoundingMode): string"
          ],
          "reference": "import { roundDivBig } from \"#fune/math.round-div-big@^1\";",
          "url": "http://www.functionalweave.com/functions/math.round-div-big"
        }
      ],
      "gaps": []
    },
    {
      "key": "splitting",
      "title": "Splitting",
      "purpose": "Divide an amount between people, periods or lines so the parts add back to the whole.",
      "from": "money-basics",
      "members": [
        {
          "id": "money.allocate",
          "tier": "core",
          "why": "Splits an amount by ratios (60/40, by quantity) without losing or inventing a penny.",
          "section": "splitting",
          "from": "money-basics",
          "version": "1.0.1",
          "summary": "Split an amount across ratios without losing or inventing a single minor unit.",
          "status": "stable",
          "license": "NOASSERTION",
          "languages": [
            "typescript",
            "python",
            "rust"
          ],
          "available": true,
          "group": false,
          "functions": [
            "allocate"
          ],
          "signatures": [
            "export function allocate(amount: Money, ratios: readonly number[]): readonly Money[]"
          ],
          "reference": "import { allocate } from \"#fune/money.allocate@^1\";",
          "url": "http://www.functionalweave.com/functions/money.allocate"
        },
        {
          "id": "money.split-even",
          "tier": "optional",
          "why": "Splits an amount into n near-equal parts that sum exactly, for instalments or shares.",
          "section": "splitting",
          "from": "money-basics",
          "version": "1.0.0",
          "summary": "Split an amount into n near-equal parts that add back up to exactly the whole.",
          "status": "stable",
          "license": "NOASSERTION",
          "languages": [
            "typescript",
            "python",
            "rust"
          ],
          "available": true,
          "group": false,
          "functions": [
            "splitEven"
          ],
          "signatures": [
            "export function splitEven(amount: Money, parts: number): readonly Money[]"
          ],
          "reference": "import { splitEven } from \"#fune/money.split-even@^1\";",
          "url": "http://www.functionalweave.com/functions/money.split-even"
        }
      ],
      "gaps": []
    },
    {
      "key": "display",
      "title": "Display and input",
      "purpose": "Show amounts to people and read what they type.",
      "from": "money-basics",
      "members": [
        {
          "id": "money.format",
          "tier": "core",
          "why": "Renders an amount as text with the currency's real number of decimal places.",
          "section": "display",
          "from": "money-basics",
          "version": "1.0.0",
          "summary": "Render a monetary amount as text, using the currency's real minor-unit precision.",
          "status": "stable",
          "license": "NOASSERTION",
          "languages": [
            "typescript",
            "python",
            "rust"
          ],
          "available": true,
          "group": false,
          "functions": [
            "formatMoney"
          ],
          "signatures": [
            "export function formatMoney(amount: Money): string"
          ],
          "reference": "import { formatMoney } from \"#fune/money.format@^1\";",
          "url": "http://www.functionalweave.com/functions/money.format"
        },
        {
          "id": "money.parse",
          "tier": "optional",
          "why": "Reads \"£1,234.50\" or \"1.234,50 €\" typed by a user into minor units, strictly.",
          "section": "display",
          "from": "money-basics",
          "version": "1.0.0",
          "summary": "Parse \"£1,234.50\" or \"1.234,50 €\" into integer minor units, strictly: no guessing, no rounding.",
          "status": "stable",
          "license": "NOASSERTION",
          "languages": [
            "typescript",
            "python",
            "rust"
          ],
          "available": true,
          "group": false,
          "functions": [
            "parseMoney"
          ],
          "signatures": [
            "export function parseMoney(text: string, currency: string, style: NumberStyle): Money"
          ],
          "reference": "import { parseMoney } from \"#fune/money.parse@^1\";",
          "url": "http://www.functionalweave.com/functions/money.parse"
        },
        {
          "id": "money.currency-digits",
          "tier": "optional",
          "why": "How many decimal places each ISO 4217 currency has, for input boxes and validation.",
          "section": "display",
          "from": "money-basics",
          "version": "1.0.0",
          "summary": "How many decimal places a currency's minor unit has, from the ISO 4217 list.",
          "status": "stable",
          "license": "NOASSERTION",
          "languages": [
            "typescript",
            "python",
            "rust"
          ],
          "available": true,
          "group": false,
          "functions": [
            "currencyDigits"
          ],
          "signatures": [
            "export function currencyDigits(currency: string): number"
          ],
          "reference": "import { currencyDigits } from \"#fune/money.currency-digits@^1\";",
          "url": "http://www.functionalweave.com/functions/money.currency-digits"
        }
      ],
      "gaps": []
    },
    {
      "key": "currencies",
      "title": "Other currencies",
      "purpose": "Convert between currencies at a rate you hold.",
      "from": "money-basics",
      "members": [
        {
          "id": "money.convert",
          "tier": "optional",
          "why": "Converts an amount at a supplied exact rate with explicit rounding.",
          "section": "currencies",
          "from": "money-basics",
          "version": "1.0.0",
          "summary": "Convert an amount to another currency at a supplied exact rate, with an explicit rounding mode.",
          "status": "stable",
          "license": "NOASSERTION",
          "languages": [
            "typescript",
            "python",
            "rust"
          ],
          "available": true,
          "group": false,
          "functions": [
            "convertMoney"
          ],
          "signatures": [
            "export function convertMoney(amount: Money, rate: ExchangeRate, mode: RoundingMode): Money"
          ],
          "reference": "import { convertMoney } from \"#fune/money.convert@^1\";",
          "url": "http://www.functionalweave.com/functions/money.convert"
        }
      ],
      "gaps": []
    }
  ],
  "gaps": [
    {
      "key": "fx-rate-source",
      "text": "Where exchange rates come from: money.convert takes a rate you supply; fetching and storing daily rates (ECB, a provider's API) is yours.",
      "section": null,
      "from": "money-basics"
    },
    {
      "key": "money-storage",
      "text": "Storing amounts: the database columns (integer minor units plus a currency code) and their migrations are yours.",
      "section": null,
      "from": "money-basics"
    }
  ],
  "counts": {
    "members": 16,
    "core": 8,
    "optional": 8,
    "unreviewed": 0,
    "deprecated": [],
    "unavailable": [],
    "missing": [],
    "gaps": 2
  },
  "warnings": [],
  "url": "http://www.functionalweave.com/suites/money-basics",
  "owner": null
}