invest.portfolio-weights Unreviewed

export function portfolioWeights(holdings: readonly PortfolioHolding[]): PortfolioWeights

/** One position and the share of the portfolio it should be. */
export interface PortfolioHolding {
  /** a fund code, ticker or asset class; unique */
  readonly id: string;
  /** market value now, 0 or more */
  readonly value: Money;
  /** the intended weight, 0 to 10000 */
  readonly targetBasisPoints: number;
}

/** Where one holding stands against its target. */
export interface HoldingWeight {
  readonly id: string;
  readonly value: Money;
  /** value / total, half-up to a whole basis point */
  readonly weightBasisPoints: number;
  readonly targetBasisPoints: number;
  /** weight minus target from the exact values, half away from zero; positive is overweight */
  readonly driftBasisPoints: number;
  /** total x target, half-up to a minor unit */
  readonly targetValue: Money;
  /** value minus targetValue; positive is overweight */
  readonly driftValue: Money;
}

/** The portfolio total and every holding against its target. */
export interface PortfolioWeights {
  readonly total: Money;
  readonly holdings: readonly HoldingWeight[];
  /** the largest drift either way, for threshold rebalancing */
  readonly maxAbsDriftBasisPoints: number;
}

import { portfolioWeights } from "#fune/invest.portfolio-weights@^1";

import { type Money, money } from "./money_amount.ts";  ← from money.amount ^1.0.0 · built alongside by fune
import { type HoldingWeight, type PortfolioHolding, type PortfolioWeights } from "./invest_portfolio_weights_types.ts";

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

/**
 * Each holding's weight, target and drift. Everything is derived from the
 * integer values and rounded once at the end, so a weight is never computed
 * from another rounded figure.
 */
export function portfolioWeights(holdings: readonly PortfolioHolding[]): PortfolioWeights {
  if (holdings.length === 0) throw new RangeError("holdings must not be empty");
  const currency = holdings[0].value.currency;
  const seen = new Set<string>();
  let total = 0n;
  let targets = 0;
  for (const h of holdings) {
    if (seen.has(h.id)) throw new RangeError(`duplicate holding id "${h.id}"`);
    seen.add(h.id);
    if (h.value.currency !== currency) throw new RangeError(`currency mismatch: ${currency} and ${h.value.currency}`);
    if (!Number.isInteger(h.value.minor) || h.value.minor < 0) {
      throw new RangeError(`holding values must be whole minor units, 0 or more; received ${h.value.minor} for "${h.id}"`);
    }
    if (!Number.isInteger(h.targetBasisPoints) || h.targetBasisPoints < 0 || h.targetBasisPoints > 10000) {
      throw new RangeError(`targetBasisPoints must be a whole number from 0 to 10000; received ${h.targetBasisPoints} for "${h.id}"`);
    }
    total += BigInt(h.value.minor);
    targets += h.targetBasisPoints;
  }
  if (targets !== 10000) throw new RangeError(`targets must sum to 10000 basis points, received ${targets}`);
  if (total === 0n) throw new RangeError("the portfolio total must be greater than zero");

  let maxAbs = 0;
  const rows: HoldingWeight[] = holdings.map((h) => {
    const value = BigInt(h.value.minor);
    const target = BigInt(h.targetBasisPoints);
    const weight = Number(roundHalfAway(value * 10000n, total));
    const drift = Number(roundHalfAway(value * 10000n - target * total, total));
    const targetValue = Number(roundHalfAway(total * target, 10000n));
    maxAbs = Math.max(maxAbs, Math.abs(drift));
    return {
      id: h.id,
      value: money(h.value.minor, currency),
      weightBasisPoints: weight,
      targetBasisPoints: h.targetBasisPoints,
      driftBasisPoints: drift,
      targetValue: money(targetValue, currency),
      driftValue: money(h.value.minor - targetValue, currency),
    };
  });
  const totalMoney: Money = money(Number(total), currency);
  return { total: totalMoney, holdings: rows, maxAbsDriftBasisPoints: maxAbs };
}

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 invest.portfolio-weights

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

The whole function, every language, is one file too: invest.portfolio-weights-1.0.1.fune, 35,377 bytes, sha256 71b36d3c97468580a8343302d7f638bdd4a8437780e9831038a47dd616f9607e. It installs into a project of any language.

// fune: before invest.portfolio-weights

// fune: after invest.portfolio-weights

// fune: replace money.amount in invest.portfolio-weights

// fune: step invest.portfolio-weights after <n|label>

More from the author

- **Integer arithmetic throughout.** Values are `Money` in minor units and every ratio is computed from them exactly (with 128-bit or arbitrary-size integers inside, so a portfolio of billions does not overflow), then rounded once. - **Each weight is rounded on its own**, half-up to a whole basis point. The weights therefore need not add up to exactly 10000: three equal holdings are 3333 bp each. Forcing them to sum (largest remainder) would move one holding's weight by a basis point it does not have, and the drift of that holding would be wrong. If you need weights that sum for a pie chart, use `money.allocate` on the values. - **Drift is computed from the exact values**, (value x 10000 - target x total) / total, and rounded once, half away from zero. At an exact half basis point this can differ by one from `weightBasisPoints - targetBasisPoints`, which rounds twice. - **`driftValue` is the money to sell (positive) or buy (negative)** to hit the target exactly, before any whole-unit or minimum-trade constraint; `invest.rebalance` applies those.

## Edge cases

- Targets must sum to exactly 10000. A holding may have a target of 0 (something to sell out of) and a holding may be worth 0 (something to buy). - A portfolio worth nothing has no weights and is an error, as are negative values (short positions are out of scope), duplicate ids, mixed currencies and an empty list.

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