invest.time-weighted-return Unreviewed

export function timeWeightedReturn(points: readonly ValuationPoint[]): TwrResult

/** The portfolio's value on a date, just before that date's external cash flow. */
export interface ValuationPoint {
  readonly date: string;
  /** the market value before the flow; 0 or more */
  readonly value: Money;
  /** money added (positive) or withdrawn (negative) straight after the valuation */
  readonly flow: Money;
}

/** The linked return, each sub-period's return, and the annualised figure when the period is a year or more. */
export interface TwrResult {
  /** the cumulative time-weighted return: 1550 = 15.5% */
  readonly basisPoints: number;
  /** one per sub-period between consecutive points */
  readonly subPeriodBasisPoints: readonly number[];
  /** first date to last date */
  readonly days: number;
  /** (1 + R)^(365 / days) − 1; null under 365 days */
  readonly annualisedBasisPoints: number | null;
}

import { timeWeightedReturn } from "#fune/invest.time-weighted-return@^1";

import { epochDayFromIso } from "./dates_add_days.ts";  ← from dates.add-days ^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
import { type TwrResult, type ValuationPoint } from "./invest_time_weighted_return_types.ts";

const MAX_SPAN_DAYS = 36500;

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

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

/**
 * True time-weighted return: each sub-period's growth, value_i over the
 * previous value plus the previous flow, linked geometrically as an exact
 * fraction and rounded once to basis points, half away from zero.
 */
export function timeWeightedReturn(points: readonly ValuationPoint[]): TwrResult {
  if (points.length < 2) throw new RangeError("at least two valuation points are needed");
  const currency = points[0].value.currency;
  const days: number[] = [];
  for (const point of points) {
    for (const amount of [point.value, point.flow]) {
      if (amount.currency !== currency) throw new RangeError(`currency mismatch: ${currency} and ${amount.currency}`);
    }
    if (whole(point.value.minor) < 0n) {
      throw new RangeError(`valuations must not be negative, received ${point.value.minor} on ${point.date}`);
    }
    whole(point.flow.minor);
    const day = epochDayFromIso(point.date);
    if (days.length > 0 && day <= days[days.length - 1]) {
      throw new RangeError("dates must be strictly increasing, one point per date");
    }
    days.push(day);
  }
  const span = days[days.length - 1] - days[0];
  if (span > MAX_SPAN_DAYS) throw new RangeError(`points must fall within ${MAX_SPAN_DAYS} days`);

  let numerator = 1n;
  let denominator = 1n;
  const subPeriodBasisPoints: number[] = [];
  for (let i = 1; i < points.length; i++) {
    const invested = BigInt(points[i - 1].value.minor) + BigInt(points[i - 1].flow.minor);
    if (invested <= 0n) {
      throw new RangeError(`nothing is invested at the start of the sub-period from ${points[i - 1].date}`);
    }
    const value = BigInt(points[i].value.minor);
    subPeriodBasisPoints.push(Number(roundHalfAway((value - invested) * 10000n, invested)));
    numerator *= value;
    denominator *= invested;
  }

  let annualisedBasisPoints: number | null = null;
  if (span >= 365) {
    if (numerator === 0n) annualisedBasisPoints = -10000;
    else {
      const growth = fractionalPowerFixed((numerator * FIXED_SCALE) / denominator, 365, span);
      annualisedBasisPoints = Number(roundHalfAway((growth - FIXED_SCALE) * 10000n, FIXED_SCALE));
    }
  }
  return {
    basisPoints: Number(roundHalfAway((numerator - denominator) * 10000n, denominator)),
    subPeriodBasisPoints,
    days: span,
    annualisedBasisPoints,
  };
}

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 invest.time-weighted-return

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

The whole function, every language, is one file too: invest.time-weighted-return-1.0.1.fune, 32,416 bytes, sha256 7d64059a234d6464f3e546ed8903c2babb7b2a1f0c1bd3df47b357d88585a42a. It installs into a project of any language.

// fune: before invest.time-weighted-return

// fune: after invest.time-weighted-return

// fune: replace dates.add-days in invest.time-weighted-return
// fune: replace math.big-integer in invest.time-weighted-return
// fune: replace math.fractional-power in invest.time-weighted-return
// fune: replace money.amount in invest.time-weighted-return

// fune: step invest.time-weighted-return after <n|label>

More from the author

The portfolio is valued on the date of every external cash flow, **just before** the flow. Between two consecutive points the sub-period return is

r_i = value_i / (value_(i−1) + flow_(i−1)) − 1

and the sub-periods are linked geometrically: 1 + R = Π (1 + r_i). This is the "true" TWR; it needs a valuation at every flow, which is what the points are. (Approximations such as Modified Dietz, which avoid the valuations, are not this capability.)

The product is formed exactly, as a fraction of big integers, and rounded once: every figure is in basis points, **half away from zero** (+0.5 bp is 1, −0.5 bp is −1). A naive "gain over opening value" gets deposits wrong: £100,000 that grows 10%, receives £50,000 and then grows 5% ends at £168,000, a TWR of 15.5%, not 18%.

## Annualised

When the first and last dates are 365 days or more apart, `annualisedBasisPoints` is (1 + R)^(365 / days) − 1, taken in `math.fractional-power`'s 18-place fixed point (actual days over 365, as XIRR does, so a leap year counts as 366/365). Under 365 days it is null: GIPS says returns for periods of less than one year must not be annualised. A total loss annualises to −100%.

## Edge cases

- The first point's value may be zero when its flow opens the account. - The last point's flow does not affect the return: nothing is measured after it. It is still checked for currency. - Errors: fewer than two points; dates not strictly increasing; a negative valuation; a sub-period that starts with nothing invested (value plus flow zero or less); mixed currencies; fractional minor units; more than 36,500 days from first to last.

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