lending.affordability Unreviewed

export function affordability(monthlyIncome: Money, monthlyCommitments: Money, principal: Money, annualRateBasisPoints: number, stressRateBasisPoints: number, termMonths: number, maxDebtToIncomeBasisPoints: number): AffordabilityResult

/** The repayment at both rates, the ratios, and whether the stressed one fits. */
export interface AffordabilityResult {
  /** monthly repayment at the actual rate, rounded up */
  readonly payment: Money;
  /** monthly repayment at the stress rate, rounded up */
  readonly stressedPayment: Money;
  /** (commitments + payment) / income, rounded up */
  readonly debtToIncomeBasisPoints: number;
  /** (commitments + stressed payment) / income, rounded up */
  readonly stressedDebtToIncomeBasisPoints: number;
  /** the stressed ratio is within the maximum */
  readonly affordable: boolean;
  /** income × maximum − commitments − stressed payment; negative when short */
  readonly headroom: Money;
}

import { affordability } from "#fune/lending.affordability@^1";

import { 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
import { applyRate } from "./money_apply_rate.ts";  ← from money.apply-rate ^1.0.0 · built alongside by fune
import { loanPayment } from "./lending_loan_payment.ts";  ← from lending.loan-payment ^1.0.0 · built alongside by fune
import { type AffordabilityResult } from "./lending_affordability_types.ts";

/**
 * A proposed loan's monthly repayment as a share of income, at the rate it
 * will be charged and at a stress rate, and whether the stressed share fits
 * under the lender's ceiling. Everything is rounded against the borrower
 * (payments and ratios up, the allowance down), because an affordability
 * test that passes on a rounding is not a test.
 */
export function affordability(
  monthlyIncome: Money,
  monthlyCommitments: Money,
  principal: Money,
  annualRateBasisPoints: number,
  stressRateBasisPoints: number,
  termMonths: number,
  maxDebtToIncomeBasisPoints: number,
): AffordabilityResult {
  const currency = monthlyIncome.currency;
  for (const other of [monthlyCommitments, principal]) {
    if (other.currency !== currency) {
      throw new RangeError(`currency mismatch: ${currency} and ${other.currency}`);
    }
  }
  if (!Number.isInteger(monthlyIncome.minor) || monthlyIncome.minor <= 0) {
    throw new RangeError(`monthlyIncome must be greater than zero, received ${monthlyIncome.minor}`);
  }
  if (!Number.isInteger(monthlyCommitments.minor) || monthlyCommitments.minor < 0) {
    throw new RangeError(`monthlyCommitments must not be negative, received ${monthlyCommitments.minor}`);
  }
  if (!Number.isInteger(stressRateBasisPoints) || stressRateBasisPoints < annualRateBasisPoints) {
    throw new RangeError(`stressRateBasisPoints must not be below the actual rate, received ${stressRateBasisPoints}`);
  }
  if (!Number.isInteger(maxDebtToIncomeBasisPoints) || maxDebtToIncomeBasisPoints < 1 || maxDebtToIncomeBasisPoints > 10000) {
    throw new RangeError(`maxDebtToIncomeBasisPoints must be between 1 and 10000, received ${maxDebtToIncomeBasisPoints}`);
  }
  const payment = loanPayment(principal, annualRateBasisPoints, termMonths, 12, "up");
  const stressed = loanPayment(principal, stressRateBasisPoints, termMonths, 12, "up");
  const ratio = (repayment: number) =>
    roundDiv((monthlyCommitments.minor + repayment) * 10000, monthlyIncome.minor, "up");
  const stressedRatio = ratio(stressed.minor);
  const allowance = applyRate(monthlyIncome, maxDebtToIncomeBasisPoints, "down");
  return {
    payment,
    stressedPayment: stressed,
    debtToIncomeBasisPoints: ratio(payment.minor),
    stressedDebtToIncomeBasisPoints: stressedRatio,
    // The ratio is rounded up and the ceiling is whole, so this is the exact
    // comparison (commitments + payment) / income <= ceiling.
    affordable: stressedRatio <= maxDebtToIncomeBasisPoints,
    headroom: money(allowance.minor - monthlyCommitments.minor - stressed.minor, 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 4 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.affordability

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

The whole function, every language, is one file too: lending.affordability-1.0.1.fune, 23,905 bytes, sha256 6df533da587af8202f351258764764ef705d4978e30e84e333aae7ff28213787. It installs into a project of any language.

// fune: before lending.affordability

// fune: after lending.affordability

// fune: replace lending.loan-payment in lending.affordability
// fune: replace math.round-div in lending.affordability
// fune: replace money.amount in lending.affordability
// fune: replace money.apply-rate in lending.affordability

// fune: step lending.affordability after <n|label>

More from the author

It returns both repayments, both ratios, `affordable` (the stressed ratio is within `maxDebtToIncomeBasisPoints`) and `headroom`: how much monthly repayment room is left under the ceiling after the stressed repayment, which is negative when the loan does not fit.

## Rounding, all against the borrower

An affordability test that passes on a rounding is not a test, so:

- both repayments come from lending.loan-payment rounded `up`; - both ratios are rounded up to the next basis point, which makes `affordable` exactly the comparison (commitments + repayment) / income <= ceiling, with no rounding in it; - the allowance (income × ceiling) behind `headroom` is rounded down, with money.apply-rate.

## The stress rate is yours

The stress rate is an argument, not a rule in code, because there is no single published one. In the UK, MCOB 11.6.18R requires a mortgage lender to take account of likely future interest rate rises over at least the first five years (not where the rate is fixed for five years or more), having regard to market expectations. The Bank of England Financial Policy Committee's specific test (the reversion rate plus 3 percentage points) was withdrawn with effect from 1 August 2022. Sources: FCA, "Interest rate 'stress test' rule – application of MCOB 11.6.18R", https://www.fca.org.uk/firms/interest-rate-stress-test-rule ; Bank of England, "Financial Policy Committee confirms withdrawal of mortgage market affordability test" (June 2022), https://www.bankofengland.co.uk/news/2022/june/financial-policy-committee-confirms-withdrawal-of-mortgage-market-affordability-test . The ceiling is the lender's policy too.

## What it does not do

- Loan-to-income (the FPC's 4.5× income flow limit is about the loan size, not the repayment): divide the loan by annual income. - Expenditure, household size or the income the lender is willing to count: pass the income after whatever haircut the policy applies. - Interest-only or part-and-part loans: the repayment is always capital and interest.

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