invest.cagr Unreviewed

export function cagr(startValue: Money, endValue: Money, yearsNumerator: number, yearsDenominator: number): number

import { cagr } from "#fune/invest.cagr@^1";

import { type Money } from "./money_amount.ts";  ← from money.amount ^1.0.0 · built alongside by fune
import { FIXED_SCALE, fractionalPowerFixed } from "./math_fractional_power.ts";  ← from math.fractional-power ^1.0.0 · built alongside by fune

/** The largest integer every language holds exactly (2^53 − 1). */
const MAX_SAFE = 9007199254740991n;

function wholeMinor(amount: Money): bigint {
  if (!Number.isInteger(amount.minor)) {
    throw new RangeError(`amounts must be whole minor units, received ${amount.minor}`);
  }
  return BigInt(amount.minor);
}

function checkYears(name: string, value: number): void {
  if (!Number.isInteger(value) || value < 1 || value > 100000) {
    throw new RangeError(`${name} must be a whole number from 1 to 100000, received ${value}`);
  }
}

/** n / d rounded half away from zero; d > 0. */
function roundHalfAway(n: bigint, d: bigint): bigint {
  const magnitude = ((n < 0n ? -n : n) * 2n + d) / (2n * d);
  return n < 0n ? -magnitude : magnitude;
}

/**
 * Compound annual growth rate, (end / start)^(1 / years) − 1, in basis points
 * rounded half away from zero. Years are yearsNumerator / yearsDenominator so
 * no float ever enters the power.
 */
export function cagr(startValue: Money, endValue: Money, yearsNumerator: number, yearsDenominator: number): number {
  const start = wholeMinor(startValue);
  const end = wholeMinor(endValue);
  if (startValue.currency !== endValue.currency) {
    throw new RangeError(`currency mismatch: ${startValue.currency} and ${endValue.currency}`);
  }
  checkYears("yearsNumerator", yearsNumerator);
  checkYears("yearsDenominator", yearsDenominator);
  if (start <= 0n) throw new RangeError(`startValue must be greater than zero, received ${start}`);
  if (end < 0n) throw new RangeError(`endValue must not be negative, received ${end}`);
  if (end === 0n) return -10000;
  const ratio = (end * FIXED_SCALE) / start;
  // Exponent 1 / years = yearsDenominator / yearsNumerator.
  const growth = fractionalPowerFixed(ratio, yearsDenominator, yearsNumerator);
  const bp = roundHalfAway((growth - FIXED_SCALE) * 10000n, FIXED_SCALE);
  if (bp > MAX_SAFE) throw new RangeError("the growth rate is too large to express in basis points");
  return Number(bp);
}

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 invest.cagr

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

The whole function, every language, is one file too: invest.cagr-1.0.1.fune, 17,954 bytes, sha256 476f7d80d95953d3636c4dff5779c0ea3a8756b1a1913891e57d8ab87a4549cb. It installs into a project of any language.

// fune: before invest.cagr

// fune: after invest.cagr

// fune: replace math.big-integer in invest.cagr
// fune: replace math.fractional-power in invest.cagr
// fune: replace money.amount in invest.cagr

// fune: step invest.cagr after <n|label>

More from the author

returned in basis points (718 = 7.18% a year).

## Why it is shaped this way

- **Years are a fraction**, `yearsNumerator / yearsDenominator`, so 18 months is `3, 2` and 30 days is `30, 365`. A float number of years would put the platform's `pow` back into the answer, and it differs by an ulp across languages. - **Short periods are annualised by compounding**, not scaled: 5% in six months is 10.25% a year, not 10%. Whether a return under a year should be annualised at all is the caller's decision (GIPS says not to present one); this function does what it is asked. - **Exact arithmetic.** end / start is taken to 18 decimal places (floored), and raised to 1 / years with `math.fractional-power`'s 18-place fixed point, which floors every step in the same order in every language. The result is then rounded to a whole basis point, **half away from zero**: +0.5 bp is 1, −0.5 bp is −1. The fixed-point error is around 10^-16, far below the half basis point, and a power that is exact in 18 places (1.21^(1/2) = 1.1) comes out exact.

## Edge cases

- An end value of zero is a total loss, −10000 (−100%), for any period. - Equal values are 0. - The start must be greater than zero, the end must not be negative, and both must be in the same currency. - `yearsNumerator` and `yearsDenominator` are whole numbers from 1 to 100000. - A growth so large the rate cannot be held (e.g. a thousandfold rise in a week) is an error rather than an overflow.

## Before you rely on this

**Not professional advice.** This capability calculates investment 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 tax adviser 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 tax adviser 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