lending.loan-payment Unreviewed

export function loanPayment(principal: Money, annualRateBasisPoints: number, termMonths: number, paymentsPerYear: number, mode: RoundingMode): Money

import { loanPayment } from "#fune/lending.loan-payment@^1";

import { type RoundingMode, roundDiv } from "./math_round_div.ts";  ← from math.round-div ^1.0.0 · built alongside by fune
import { type Money, money } from "./money_amount.ts";  ← from money.amount ^1.0.0 · built alongside by fune

/** A hundred years of monthly payments, sixty of weekly ones. */
export const MAX_PAYMENTS = 3000;

/**
 * The number of payments a term holds, after checking the arguments every
 * lending capability shares.
 */
export function paymentCount(annualRateBasisPoints: number, termMonths: number, paymentsPerYear: number): number {
  if (!Number.isInteger(annualRateBasisPoints) || annualRateBasisPoints < 0 || annualRateBasisPoints > 100000) {
    throw new RangeError(`annualRateBasisPoints must be between 0 and 100000, received ${annualRateBasisPoints}`);
  }
  if (!Number.isInteger(paymentsPerYear) || paymentsPerYear < 1 || paymentsPerYear > 52) {
    throw new RangeError(`paymentsPerYear must be between 1 and 52, received ${paymentsPerYear}`);
  }
  if (!Number.isInteger(termMonths) || termMonths < 1) {
    throw new RangeError(`termMonths must be at least 1, received ${termMonths}`);
  }
  if ((termMonths * paymentsPerYear) % 12 !== 0) {
    throw new RangeError(`a term of ${termMonths} months is not a whole number of payments at ${paymentsPerYear} a year`);
  }
  const n = (termMonths * paymentsPerYear) / 12;
  if (n > MAX_PAYMENTS) {
    throw new RangeError(`${n} payments is more than the ${MAX_PAYMENTS} payment limit`);
  }
  return n;
}

/**
 * Round the exact quotient numerator / denominator (both positive) with a
 * math.round-div mode, however large they are. Only the integer part and
 * where the remainder sits against one half matter, so the decision is handed
 * to roundDiv as a small fraction with the same integer part and the same
 * side of the half: q, q + 1/4, q + 1/2 or q + 3/4.
 */
export function roundWide(numerator: bigint, denominator: bigint, mode: RoundingMode): number {
  const q = numerator / denominator;
  const twice = (numerator % denominator) * 2n;
  const small = Number(q);
  if (twice === 0n) return roundDiv(small, 1, mode);
  if (twice === denominator) return roundDiv(2 * small + 1, 2, mode);
  return roundDiv(4 * small + (twice < denominator ? 1 : 3), 4, mode);
}

/**
 * The level payment that repays `principal` over the term at a nominal
 * annual rate divided equally between the periods:
 *
 *   payment = P · r / (1 − (1 + r)^−n),   r = rate / paymentsPerYear
 *
 * With r = b / D (b basis points, D = 10000 × paymentsPerYear) this is the
 * exact fraction P · b · (D + b)^n / (D · ((D + b)^n − D^n)), evaluated in
 * integers of whatever size it takes and rounded once. A zero rate is P / n.
 */
export function loanPayment(
  principal: Money,
  annualRateBasisPoints: number,
  termMonths: number,
  paymentsPerYear: number,
  mode: RoundingMode,
): Money {
  if (!Number.isInteger(principal.minor) || principal.minor <= 0) {
    throw new RangeError(`principal must be greater than zero, received ${principal.minor}`);
  }
  const n = paymentCount(annualRateBasisPoints, termMonths, paymentsPerYear);
  if (annualRateBasisPoints === 0) {
    return money(roundDiv(principal.minor, n, mode), principal.currency);
  }
  const b = BigInt(annualRateBasisPoints);
  const d = 10000n * BigInt(paymentsPerYear);
  const grown = (d + b) ** BigInt(n);
  const numerator = BigInt(principal.minor) * b * grown;
  const denominator = d * (grown - d ** BigInt(n));
  return money(roundWide(numerator, denominator, mode), principal.currency);
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and its 3 dependencies, pins them in fune.lock, downloads only the TypeScript package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add lending.loan-payment

The manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./lending.loan-payment-1.0.1-typescript.fune, or fetch it from a terminal with fune pull lending.loan-payment@1.0.1:typescript.

The whole function, every language, is one file too: lending.loan-payment-1.0.1.fune, 22,812 bytes, sha256 ae3adb6e388662e058f53225156c2198c46abb159e47c6967cb931c48a9670a1. It installs into a project of any language.

// fune: before lending.loan-payment

// fune: after lending.loan-payment

// fune: replace math.big-integer in lending.loan-payment
// fune: replace math.round-div in lending.loan-payment
// fune: replace money.amount in lending.loan-payment

// fune: step lending.loan-payment after <n|label>

More from the author

With a nominal annual rate split equally between the periods, r = rate / paymentsPerYear, and n payments:

payment = P × r / (1 − (1 + r)^−n)

That is the textbook present-value-of-an-annuity formula, the same one as a spreadsheet's PMT. Here it is never evaluated in floating point. The rate is b basis points, so r = b / D with D = 10000 × paymentsPerYear, and the formula is exactly the fraction

P × b × (D + b)^n / ( D × ((D + b)^n − D^n) )

Both sides are integers. For a 25-year monthly mortgage (D + b)^n is a number of over 1,500 digits, far past what `math.rational` holds (its parts must stay within 2^53 so JavaScript numbers stay exact), so the fraction is built with arbitrary-size integers: `bigint` in TypeScript, `int` in Python and `math.big-integer` in Rust. It is then rounded exactly once, with the `math.round-div` mode you pass. A zero rate is P / n, rounded the same way.

## Rounding

- `half-up` gives the nearest penny, what most quotes show: £100,000 at 5% over 25 years is £584.59. - `up` never under-repays: every payment is at most a penny high, and the final payment (see lending.amortisation-schedule) comes out slightly smaller. - `down` or `half-even` are available where a contract says so.

The mode applies to the exact value, so there is no double rounding: a payment of exactly x.5 pence rounds by the mode's tie rule, anything else to the nearer penny.

## What it does not do

- The rate is nominal and divided equally (12% a year is 1% a month). It is not an APR or AER; lending.apr and banking.savings-aer convert. - Every period is treated as equal. Interest charged daily, or a first period of odd length, changes the payment slightly; build the schedule with lending.daily-interest when that matters. - No fees are added, and the payment is not a regulated APR disclosure.

## Limits

The rate is 0 to 100000 basis points, payments per year 1 to 52, and the term must hold a whole number of payments (13 months cannot be paid quarterly), at most 3000 of them. The principal must be positive and, for TypeScript to stay exact, below 2^51 minor units.

The module also exports `paymentCount` (the argument checks and n) and `roundWide` (round a large positive fraction with a round-div mode), which the other lending capabilities reuse.

## Before you rely on this

**Not professional advice.** This capability calculates lending figures from published rules. It is a software component for developers, not financial advice. Rules change and every rate here has an effective date. Check that the dates cover your case. Verify results against the official sources listed above, and have a consumer-credit compliance specialist review how you use it, before anyone relies on the output. Provided "as is" under its licence, without warranty.

**Unreviewed.** This capability's implementations agree in every language and pass its published test vectors, which were worked out from the official sources cited. But no qualified consumer-credit compliance specialist has yet checked those vectors, or confirmed that the capability covers the cases it claims. Treat it as a draft. Do not use it for real people, money or decisions without your own expert review. Once a qualified reviewer signs off, this notice is replaced with their name, qualification and the date. Each new version needs fresh sign-off.

1.0.1 marks it unreviewed. The code and the tests are unchanged.

Files