invest.money-weighted-return

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

import { type Money } from "./money_amount.ts";  ← from money.amount ^1.0.0 · built alongside by fune
import { epochDayFromIso } from "./dates_add_days.ts";  ← from dates.add-days ^1.0.0 · built alongside by fune
import { FIXED_SCALE, powFixed } from "./math_fractional_power.ts";  ← from math.fractional-power ^1.0.0 · built alongside by fune
import { type DatedFlow, type XirrResult } from "./invest_money_weighted_return_types.ts";

const MAX_SPAN_DAYS = 36500;
const NO_SINGLE_RATE = "no single rate of return solves these cash flows";

function sign(value: bigint): number {
  return value > 0n ? 1 : value < 0n ? -1 : 0;
}

/** 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;
}

/** Net flow per day, in day order, counted from the earliest date with a nonzero net flow. */
function netFlows(flows: readonly DatedFlow[]): [number, bigint][] {
  if (flows.length === 0) throw new RangeError("flows must not be empty");
  const currency = flows[0].amount.currency;
  const net = new Map<number, bigint>();
  for (const flow of flows) {
    const amount: Money = flow.amount;
    if (amount.currency !== currency) throw new RangeError(`currency mismatch: ${currency} and ${amount.currency}`);
    if (!Number.isInteger(amount.minor)) throw new RangeError(`amounts must be whole minor units, received ${amount.minor}`);
    const day = epochDayFromIso(flow.date);
    net.set(day, (net.get(day) ?? 0n) + BigInt(amount.minor));
  }
  const days = [...net.entries()].filter(([, a]) => a !== 0n).sort((a, b) => a[0] - b[0]);
  if (!days.some(([, a]) => a > 0n) || !days.some(([, a]) => a < 0n)) {
    throw new RangeError("flows need at least one payment and one receipt");
  }
  const first = days[0][0];
  if (days[days.length - 1][0] - first > MAX_SPAN_DAYS) {
    throw new RangeError(`flows must fall within ${MAX_SPAN_DAYS} days of each other`);
  }
  return days.map(([day, amount]) => [day - first, amount]);
}

/** Bisection on x in [0, FIXED_SCALE] for a change of sign of f; the two ends' signs differ. */
function bisect(f: (x: bigint) => bigint): bigint {
  let lo = 0n;
  let hi = FIXED_SCALE;
  const loSign = sign(f(lo));
  while (hi - lo > 1n) {
    const mid = (lo + hi) / 2n;
    const s = sign(f(mid));
    if (s === 0) return mid;
    if (s === loSign) lo = mid;
    else hi = mid;
  }
  return lo;
}

/**
 * XIRR: the annual rate r at which Σ amount / (1 + r)^(days / 365) = 0, days
 * counted from the earliest flow. Solved by bisection in 18-place fixed point
 * on the per-day discount factor, then settled to 12 places and rounded half
 * away from zero to 9 places and to a basis point.
 */
export function moneyWeightedReturn(flows: readonly DatedFlow[]): XirrResult {
  const net = netFlows(flows);
  const total = net.reduce((sum, [, a]) => sum + a, 0n);
  let rate = 0n;
  if (total !== 0n) {
    const last = net[net.length - 1][0];
    const positiveSide = sign(net[0][1]) !== sign(total);
    const negativeSide = sign(net[net.length - 1][1]) !== sign(total);
    if (positiveSide === negativeSide) throw new RangeError(NO_SINGLE_RATE);
    if (positiveSide) {
      // v = (1 + r)^(-1/365) in (0, 1).
      const v = bisect((x) => net.reduce((sum, [t, a]) => sum + a * powFixed(x, t), 0n));
      const growth = powFixed(v, 365);
      if (growth === 0n) throw new RangeError("the rate of return is too large to compute");
      rate = (FIXED_SCALE * FIXED_SCALE) / growth - FIXED_SCALE;
    } else {
      // u = (1 + r)^(1/365) in (0, 1); the sum is multiplied through by u^last.
      const u = bisect((x) => net.reduce((sum, [t, a]) => sum + a * powFixed(x, last - t), 0n));
      rate = powFixed(u, 365) - FIXED_SCALE;
    }
  }
  const settled = roundHalfAway(rate, 1000000n);
  const bp = roundHalfAway(settled * 10000n, 1000000000000n);
  const nine = roundHalfAway(settled, 1000n);
  const magnitude = nine < 0n ? -nine : nine;
  const fraction = (magnitude % 1000000000n).toString().padStart(9, "0");
  return {
    basisPoints: Number(bp),
    rate: `${nine < 0n ? "-" : ""}${magnitude / 1000000000n}.${fraction}`,
  };
}