invest.fee-drag Unreviewed

export function feeDrag(startValue: Money, annualGrowthBasisPoints: number, annualFeeBasisPoints: number, years: number): FeeDrag

/** The two values at the end of one year. */
export interface FeeDragYear {
  /** 1 for the end of the first year */
  readonly year: number;
  readonly valueWithoutFee: Money;
  readonly valueWithFee: Money;
  /** the charge taken at the end of this year */
  readonly fee: Money;
}

/** The two outcomes side by side, and what the difference is made of. */
export interface FeeDrag {
  readonly valueWithoutFee: Money;
  readonly valueWithFee: Money;
  /** valueWithoutFee minus valueWithFee: the fees plus the growth they would have earned */
  readonly drag: Money;
  /** drag as a share of valueWithoutFee, half-up */
  readonly dragBasisPoints: number;
  /** the charges actually taken, less than the drag whenever growth is positive */
  readonly feesPaid: Money;
  /** one row per year */
  readonly schedule: readonly FeeDragYear[];
}

import { feeDrag } from "#fune/invest.fee-drag@^1";

import { applyRate } from "./money_apply_rate.ts";  ← from money.apply-rate ^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 FeeDrag, type FeeDragYear } from "./invest_fee_drag_types.ts";

/**
 * The same investment grown twice, with and without an annual charge taken
 * on the year-end value, rounding to minor units every year as a statement
 * would.
 */
export function feeDrag(startValue: Money, annualGrowthBasisPoints: number, annualFeeBasisPoints: number, years: number): FeeDrag {
  if (!Number.isInteger(startValue.minor) || startValue.minor < 0) {
    throw new RangeError(`startValue must be whole minor units, 0 or more; received ${startValue.minor}`);
  }
  if (!Number.isInteger(annualGrowthBasisPoints) || annualGrowthBasisPoints < -10000) {
    throw new RangeError(`annualGrowthBasisPoints must be a whole number, -10000 or more; received ${annualGrowthBasisPoints}`);
  }
  if (!Number.isInteger(annualFeeBasisPoints) || annualFeeBasisPoints < 0 || annualFeeBasisPoints > 10000) {
    throw new RangeError(`annualFeeBasisPoints must be a whole number from 0 to 10000; received ${annualFeeBasisPoints}`);
  }
  if (!Number.isInteger(years) || years < 0 || years > 100) {
    throw new RangeError(`years must be a whole number from 0 to 100; received ${years}`);
  }
  const currency = startValue.currency;
  let without = startValue.minor;
  let withFee = startValue.minor;
  let fees = 0;
  const schedule: FeeDragYear[] = [];
  for (let year = 1; year <= years; year++) {
    without += applyRate(money(without, currency), annualGrowthBasisPoints, "half-up").minor;
    const grown = withFee + applyRate(money(withFee, currency), annualGrowthBasisPoints, "half-up").minor;
    const fee = applyRate(money(grown, currency), annualFeeBasisPoints, "half-up").minor;
    withFee = grown - fee;
    fees += fee;
    schedule.push({
      year,
      valueWithoutFee: money(without, currency),
      valueWithFee: money(withFee, currency),
      fee: money(fee, currency),
    });
  }
  const drag = without - withFee;
  let dragBasisPoints = 0;
  if (without > 0) {
    const n = BigInt(drag) * 10000n;
    const d = BigInt(without);
    const a = n < 0n ? -n : n;
    let q = a / d;
    if (2n * (a - q * d) >= d) q += 1n;
    dragBasisPoints = Number(n < 0n ? -q : q);
  }
  return {
    valueWithoutFee: money(without, currency),
    valueWithFee: money(withFee, currency),
    drag: money(drag, currency),
    dragBasisPoints,
    feesPaid: money(fees, currency),
    schedule,
  };
}

Install

fune build

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

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

The whole function, every language, is one file too: invest.fee-drag-1.0.1.fune, 40,953 bytes, sha256 2e0eed6bc13576141691424f434b8f8bdf9ccba04127a58213167c7939abfdeb. It installs into a project of any language.

// fune: before invest.fee-drag

// fune: after invest.fee-drag

// fune: replace money.amount in invest.fee-drag
// fune: replace money.apply-rate in invest.fee-drag

// fune: step invest.fee-drag after <n|label>

More from the author

Each year, in this order, in whole minor units:

1. growth = value x `annualGrowthBasisPoints` / 10000, rounded half away from zero (`money.apply-rate`, half-up), and added; 2. fee = the grown value x `annualFeeBasisPoints` / 10000, rounded the same way, and taken off (the "with fee" run only).

So the fee is charged once a year on the year-end value, as an annual management charge on a statement is. Real platforms often charge monthly on the average value; the difference is small and this capability does not model it. Growth is a constant rate you choose; it is an illustration, not a forecast.

## Why the drag is more than the fees

`feesPaid` is the charges taken. `drag` is the whole difference in the final value, which also includes the growth the charged money would have earned. With no growth they are equal; with positive growth the drag is larger, and the gap widens with the years. That gap is the point of the capability, and the reason an answer computed as "fee x years" is wrong.

## Edge cases

- `years` 0 returns the start value twice and an empty schedule. - Growth of -10000 (a total loss) is allowed; anything lower is an error. - `dragBasisPoints` is 0 when the value without the fee is 0. - Errors: negative or fractional start value, years outside 0-100, a fee outside 0-10000, growth below -10000.

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