insurance.excess-apply Unreviewed

export function applyExcess(loss: Money, compulsoryExcess: Money, voluntaryExcess: Money, policyLimit: Money | null, excessWithinLimit: boolean): ExcessSettlement

/** What the insurer pays and what the policyholder bears. */
export interface ExcessSettlement {
  /** compulsory plus voluntary */
  readonly totalExcess: Money;
  /** the part of the excess the loss used up, never more than the loss */
  readonly excessApplied: Money;
  readonly payout: Money;
  /** true when the policy limit reduced the payout */
  readonly limitApplied: boolean;
  /** loss minus payout: what the policyholder bears */
  readonly uninsured: Money;
}

import { applyExcess } from "#fune/insurance.excess-apply@^1";

import { type Money, assertSameCurrency, money } from "./money_amount.ts";  ← from money.amount ^1.0.0 · built alongside by fune
import { type ExcessSettlement } from "./insurance_excess_apply_types.ts";

/**
 * The claim payout after the excess, capped at the policy limit.
 *
 * The excess is the compulsory and voluntary excess together, and a loss
 * smaller than it pays nothing. Where the limit sits relative to the excess is
 * a policy wording question, so the caller says which: by default the limit
 * caps what is paid after the excess; with excessWithinLimit the excess is
 * taken off the loss after the limit, so it erodes the limit.
 */
export function applyExcess(
  loss: Money,
  compulsoryExcess: Money,
  voluntaryExcess: Money,
  policyLimit: Money | null,
  excessWithinLimit: boolean
): ExcessSettlement {
  const hasLimit = policyLimit !== null && policyLimit !== undefined;
  assertSameCurrency(loss, compulsoryExcess);
  assertSameCurrency(loss, voluntaryExcess);
  if (hasLimit) assertSameCurrency(loss, policyLimit);
  if (loss.minor < 0) throw new RangeError(`loss must not be negative, received ${loss.minor}`);
  if (compulsoryExcess.minor < 0 || voluntaryExcess.minor < 0) {
    throw new RangeError("excess must not be negative");
  }
  if (hasLimit && policyLimit.minor < 0) {
    throw new RangeError(`policyLimit must not be negative, received ${policyLimit.minor}`);
  }
  const excess = compulsoryExcess.minor + voluntaryExcess.minor;
  let payout: number;
  let limitApplied = false;
  if (excessWithinLimit) {
    let covered = loss.minor;
    if (hasLimit && policyLimit.minor < covered) {
      covered = policyLimit.minor;
      limitApplied = true;
    }
    payout = Math.max(covered - excess, 0);
  } else {
    payout = Math.max(loss.minor - excess, 0);
    if (hasLimit && policyLimit.minor < payout) {
      payout = policyLimit.minor;
      limitApplied = true;
    }
  }
  const c = loss.currency;
  return {
    totalExcess: money(excess, c),
    excessApplied: money(Math.min(excess, loss.minor), c),
    payout: money(payout, c),
    limitApplied,
    uninsured: money(loss.minor - payout, c),
  };
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and its 1 dependency, 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 insurance.excess-apply

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

The whole function, every language, is one file too: insurance.excess-apply-1.0.1.fune, 22,577 bytes, sha256 7c4367145a5a64ec36e9208bdc8f7522251b18bf68a78e588c94314952f4e6b1. It installs into a project of any language.

// fune: before insurance.excess-apply

// fune: after insurance.excess-apply

// fune: replace money.amount in insurance.excess-apply

// fune: step insurance.excess-apply after <n|label>

More from the author

The excess is the compulsory excess (set by the insurer) plus the voluntary excess (chosen by the policyholder for a lower premium); UK motor and home policies quote them separately but apply them together. A loss smaller than the excess pays nothing, and `excessApplied` is only the part of the excess the loss used up.

## Where the limit sits

Policies differ on whether the limit is applied before or after the excess, so the caller says which:

- `excessWithinLimit = false` (the usual "the most we will pay" wording): the excess comes off the loss, then the payout is capped at the limit. payout = min(loss - excess, limit). - `excessWithinLimit = true` (the excess erodes the limit): the loss is capped at the limit, then the excess comes off it. payout = min(loss, limit) - excess.

They differ whenever the loss is above the limit: a 10,400.00 loss with a 500.00 excess and a 10,000.00 limit pays 9,900.00 the first way and 9,500.00 the second. `limitApplied` is true only when the limit actually reduced what is paid.

No rounding happens: every figure is a whole number of minor units already. For underinsurance, see `insurance.sum-insured-average`; whether average comes before or after the excess is a policy wording question too.

## Before you rely on this

**Not professional advice.** This capability calculates insurance 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 an actuary 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 actuary 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