lending.daily-interest Unreviewed

export function dailyInterest(balances: readonly DatedBalance[], fromIso: string, toIso: string, annualRateBasisPoints: number, convention: DayCountConvention, mode: RoundingMode): DailyInterest

/** A balance and the day it takes effect; it holds until the next one. */
export interface DatedBalance {
  readonly date: string;
  /** negative for a debt, e.g. an overdrawn account */
  readonly balance: Money;
}

/** The posted interest, the exact amount behind it, and the days counted. */
export interface DailyInterest {
  /** the exact total rounded once */
  readonly interest: Money;
  /** the exact total in minor units, before rounding */
  readonly exact: Rational;
  /** calendar days from fromIso to toIso */
  readonly days: number;
}

import { dailyInterest } from "#fune/lending.daily-interest@^1";

import { type RoundingMode } 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
import { type Rational, addRational, multiplyRational, rational, rationalToInteger } from "./math_rational.ts";  ← from math.rational ^1.0.0 · built alongside by fune
import { type DayCountConvention, dayCountFraction } from "./dates_day_count_fraction.ts";  ← from dates.day-count-fraction ^1.0.0 · built alongside by fune
import { daysBetween } from "./dates_days_between.ts";  ← from dates.days-between ^1.0.0 · built alongside by fune
import { type DailyInterest, type DatedBalance } from "./lending_daily_interest_types.ts";

/**
 * Interest on a balance that changes during the period: each balance earns
 * (or is charged) balance × rate × year fraction for the days it was held,
 * the year fractions come from dates.day-count-fraction, and the pieces are
 * added as exact fractions. Only the total is rounded, once, so splitting a
 * month into more balance changes never moves the answer by a stray penny.
 */
export function dailyInterest(
  balances: readonly DatedBalance[],
  fromIso: string,
  toIso: string,
  annualRateBasisPoints: number,
  convention: DayCountConvention,
  mode: RoundingMode,
): DailyInterest {
  if (!Number.isInteger(annualRateBasisPoints) || annualRateBasisPoints < -100000 || annualRateBasisPoints > 100000) {
    throw new RangeError(`annualRateBasisPoints must be between -100000 and 100000, received ${annualRateBasisPoints}`);
  }
  if (balances.length === 0) {
    throw new RangeError("balances must not be empty");
  }
  const days = daysBetween(fromIso, toIso);
  if (days < 0) {
    throw new RangeError(`fromIso ${fromIso} must not be after toIso ${toIso}`);
  }
  const currency = balances[0].balance.currency;
  for (let i = 0; i < balances.length; i += 1) {
    daysBetween(balances[i].date, balances[i].date);
    if (balances[i].balance.currency !== currency) {
      throw new RangeError(`currency mismatch: ${currency} and ${balances[i].balance.currency}`);
    }
    if (i > 0 && balances[i].date <= balances[i - 1].date) {
      throw new RangeError("balances must be in strictly ascending date order");
    }
  }
  if (balances[0].date > fromIso) {
    throw new RangeError(`the first balance starts on ${balances[0].date}, after fromIso ${fromIso}`);
  }
  const rate = rational(annualRateBasisPoints, 10000);
  let total: Rational = rational(0, 1);
  for (let i = 0; i < balances.length; i += 1) {
    const start = balances[i].date > fromIso ? balances[i].date : fromIso;
    const next = i + 1 < balances.length ? balances[i + 1].date : toIso;
    const end = next < toIso ? next : toIso;
    if (start >= end) continue;
    const fraction = dayCountFraction(start, end, convention);
    const amount = multiplyRational(rational(balances[i].balance.minor, 1), rate);
    total = addRational(total, multiplyRational(amount, rational(fraction.numerator, fraction.denominator)));
  }
  return { interest: money(rationalToInteger(total, mode), currency), exact: total, days };
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and its 5 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.daily-interest

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

The whole function, every language, is one file too: lending.daily-interest-1.0.1.fune, 26,958 bytes, sha256 2c05773e8a51ceee16cb0d3f7b369aaebb047265e4c8eb990b39c4186dae89ed. It installs into a project of any language.

// fune: before lending.daily-interest

// fune: after lending.daily-interest

// fune: replace dates.day-count-fraction in lending.daily-interest
// fune: replace dates.days-between in lending.daily-interest
// fune: replace math.rational in lending.daily-interest
// fune: replace math.round-div in lending.daily-interest
// fune: replace money.amount in lending.daily-interest

// fune: step lending.daily-interest after <n|label>

More from the author

- `balances` is the balance history: each entry holds from its date until the next entry's date. The first entry must start on or before `fromIso` (the opening balance); entries after `toIso` are ignored. - The period is `fromIso` included to `toIso` excluded, the usual accrual convention: 1 January to 31 January is 30 days of interest. - Each piece's year fraction comes from dates.day-count-fraction (ACT/365F, ACT/360, 30/360, 30E/360, ACT/ACT ISDA), as an exact fraction. - The pieces are summed exactly with math.rational, and the total is rounded once, with the mode you pass. `exact` is that unrounded total in minor units, for audit and for carrying fractions of a penny into the next period if your ledger does that.

Rounding once is the point. Rounding each day (or each balance change) and adding the rounded amounts drifts: three days at 0.23p each would post 0p where the true total is 0.68p, and more balance changes would mean more drift. Some ledgers do post whole pence daily; if yours does, call this once per day instead.

## Signs

A negative balance (overdrawn, or a loan held as a debt) accrues negative interest, and a negative rate charges a positive balance. The rounding modes are those of math.round-div, symmetric about zero: `down` is towards zero, `up` away from it.

## Splitting and 30/360

Under ACT/365F, ACT/360 and ACT/ACT the pieces add up to the whole period exactly. Under 30/360 each piece is measured on its own, as a contract that names 30/360 per balance period would, so a piece ending on the 31st can differ by a day from measuring the whole month at once.

## Limits

The exact running total must fit math.rational (numerator and denominator within 2^53 - 1); that holds for balances into the hundreds of millions of pounds at ordinary rates, and a larger one is an error ("rational overflow"), never a wrong answer. The rate is -100000 to 100000 basis points, and the rate is fixed for the period: for a rate change, call once per rate and add.

## 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