@insiderfinance/totalfinance 0.1.0

package/modules/performance/src/relative.ts

@@ -0,0 +1,278 @@
+/**
+ * `@insiderfinance/totalfinance/performance/relative` — benchmark-relative performance metrics (spec §15.1).
+ *
+ * Each takes a per-period strategy return series and an aligned benchmark return series (same length,
+ * same periodicity) and reports the standard CAPM-style relationships: beta, Jensen's alpha, tracking
+ * error, the information ratio, and the Treynor ratio. Imports only `@insiderfinance/totalfinance/math` + `@insiderfinance/totalfinance/core`.
+ *
+ * Every metric here is a facade (design law #3): the plain call returns a number; `.explain()`
+ * echoes the annualization factor (and risk-free rate) where applied. `beta` applies no
+ * annualization or risk-free convention, so its envelope discloses none beyond the conventions
+ * version.
+ */
+
+import {
+  CONVENTIONS_VERSION,
+  ErrorCode,
+  InputError,
+  type Computed,
+  seriesFacade,
+  finiteOrNull,
+  ensureKnownKeys,
+} from '@totalfinance/core';
+import { covariance, mean, standardDeviation, variance } from '@totalfinance/math';
+import { annualizedReturn } from './metrics.js';
+import {
+  ANNUALIZATION_KEYS,
+  type AnnualizationExtra,
+  type AnnualizationOptions,
+  type RiskAdjustedExtra,
+  SHARPE_KEYS,
+  type SharpeOptions,
+  annualizationAssumptions,
+  degenerateAwareDiagnostics,
+  requireSeries,
+  riskAdjustedAssumptions,
+} from './sharpe.js';
+import { resolvePeriodsPerYear, resolveRiskFreeRate } from './annualization-internal.js';
+
+function requireAligned(
+  returns: ArrayLike<number>,
+  benchmark: ArrayLike<number>,
+  functionName: string,
+): void {
+  requireSeries(returns, functionName);
+  requireSeries(benchmark, functionName, 'benchmark');
+  if (returns.length !== benchmark.length) {
+    throw new InputError(
+      `${functionName}: returns length (${returns.length}) must match benchmark length (${benchmark.length}).`,
+      {
+        code: ErrorCode.InputOutOfRange,
+        context: { returns: returns.length, benchmark: benchmark.length },
+      },
+    );
+  }
+}
+
+function betaValue(returns: ArrayLike<number>, benchmark: ArrayLike<number>): number {
+  requireAligned(returns, benchmark, 'beta');
+  const varB = variance(benchmark);
+  if (varB === 0) return NaN;
+  return covariance(returns, benchmark) / varB;
+}
+
+/** Beta: sensitivity of the strategy to the benchmark, `cov(r, b) / var(b)`. */
+export const beta = seriesFacade(
+  'beta',
+  (returns: ArrayLike<number>, benchmark: ArrayLike<number>): number | null =>
+    finiteOrNull(betaValue(returns, benchmark)),
+  (returns: ArrayLike<number>, benchmark: ArrayLike<number>): Computed<number | null> => {
+    const value = betaValue(returns, benchmark);
+    return {
+      value: finiteOrNull(value),
+      assumptions: { conventionsVersion: CONVENTIONS_VERSION },
+      diagnostics: degenerateAwareDiagnostics(
+        value,
+        'beta',
+        'the benchmark has zero variance (or fewer than 2 periods), so sensitivity to it is undefined',
+        returns,
+        benchmark,
+      ),
+    };
+  },
+);
+
+function alphaValue(
+  returns: ArrayLike<number>,
+  benchmark: ArrayLike<number>,
+  options: SharpeOptions,
+): number {
+  requireAligned(returns, benchmark, 'alpha');
+  // Law 12: shared by the plain call AND `.explain()` — an unknown option teaches, never ignored.
+  ensureKnownKeys('alpha', 'options', options, SHARPE_KEYS);
+  // Resolve (and thereby VALIDATE) before any early return — an empty series must not smuggle a
+  // null periodsPerYear past the ladder (the solver-family law: never return on malformed input).
+  const ppy = resolvePeriodsPerYear('alpha', options);
+  const rfPerPeriod = resolveRiskFreeRate('alpha', options) / ppy;
+  if (returns.length === 0) return NaN;
+  const b = betaValue(returns, benchmark);
+  const perPeriod = mean(returns) - (rfPerPeriod + b * (mean(benchmark) - rfPerPeriod));
+  return perPeriod * ppy;
+}
+
+/**
+ * Annualized Jensen's alpha: the strategy's average return in excess of what its beta exposure to the
+ * benchmark would predict, `α = ppy · (r̄ − [rf_p + β·(b̄ − rf_p)])` (rf split to a per-period rate).
+ */
+export const alpha = seriesFacade(
+  'alpha',
+  (
+    returns: ArrayLike<number>,
+    benchmark: ArrayLike<number>,
+    options: SharpeOptions = {},
+  ): number | null => finiteOrNull(alphaValue(returns, benchmark, options)),
+  (
+    returns: ArrayLike<number>,
+    benchmark: ArrayLike<number>,
+    options: SharpeOptions = {},
+  ): Computed<number | null, RiskAdjustedExtra> => {
+    const value = alphaValue(returns, benchmark, options);
+    return {
+      value: finiteOrNull(value),
+      assumptions: riskAdjustedAssumptions({
+        periodsPerYear: resolvePeriodsPerYear('alpha', options),
+        riskFreeRate: resolveRiskFreeRate('alpha', options),
+      }),
+      diagnostics: degenerateAwareDiagnostics(
+        value,
+        'alpha',
+        'the series is empty or beta is undefined (zero-variance benchmark)',
+        returns,
+        benchmark,
+      ),
+    };
+  },
+);
+
+function trackingErrorValue(
+  returns: ArrayLike<number>,
+  benchmark: ArrayLike<number>,
+  options: AnnualizationOptions,
+): number {
+  requireAligned(returns, benchmark, 'trackingError');
+  ensureKnownKeys('trackingError', 'options', options, ANNUALIZATION_KEYS);
+  const n = returns.length;
+  const active = new Array<number>(n);
+  for (let i = 0; i < n; i++) active[i] = returns[i]! - benchmark[i]!;
+  return standardDeviation(active) * Math.sqrt(resolvePeriodsPerYear('trackingError', options));
+}
+
+/** Annualized tracking error: the volatility of the active (strategy − benchmark) return series. */
+export const trackingError = seriesFacade(
+  'trackingError',
+  (
+    returns: ArrayLike<number>,
+    benchmark: ArrayLike<number>,
+    options: AnnualizationOptions = {},
+  ): number | null => finiteOrNull(trackingErrorValue(returns, benchmark, options)),
+  (
+    returns: ArrayLike<number>,
+    benchmark: ArrayLike<number>,
+    options: AnnualizationOptions = {},
+  ): Computed<number | null, AnnualizationExtra> => {
+    const value = trackingErrorValue(returns, benchmark, options);
+    return {
+      value: finiteOrNull(value),
+      assumptions: annualizationAssumptions(resolvePeriodsPerYear('trackingError', options)),
+      diagnostics: degenerateAwareDiagnostics(
+        value,
+        'trackingError',
+        'the sample standard deviation of the active series needs at least 2 periods',
+        returns,
+        benchmark,
+      ),
+    };
+  },
+);
+
+function informationRatioValue(
+  returns: ArrayLike<number>,
+  benchmark: ArrayLike<number>,
+  options: AnnualizationOptions,
+): number {
+  requireAligned(returns, benchmark, 'informationRatio');
+  ensureKnownKeys('informationRatio', 'options', options, ANNUALIZATION_KEYS);
+  // Resolved before the degenerate early returns — see alphaValue.
+  const ppy = resolvePeriodsPerYear('informationRatio', options);
+  const n = returns.length;
+  if (n === 0) return NaN;
+  const active = new Array<number>(n);
+  for (let i = 0; i < n; i++) active[i] = returns[i]! - benchmark[i]!;
+  const sd = standardDeviation(active);
+  if (sd === 0) return NaN;
+  return (mean(active) / sd) * Math.sqrt(ppy);
+}
+
+/**
+ * Information ratio: annualized mean active return divided by annualized tracking error — the Sharpe
+ * ratio of the active (strategy − benchmark) return series.
+ */
+export const informationRatio = seriesFacade(
+  'informationRatio',
+  (
+    returns: ArrayLike<number>,
+    benchmark: ArrayLike<number>,
+    options: AnnualizationOptions = {},
+  ): number | null => finiteOrNull(informationRatioValue(returns, benchmark, options)),
+  (
+    returns: ArrayLike<number>,
+    benchmark: ArrayLike<number>,
+    options: AnnualizationOptions = {},
+  ): Computed<number | null, AnnualizationExtra> => {
+    const value = informationRatioValue(returns, benchmark, options);
+    return {
+      value: finiteOrNull(value),
+      assumptions: annualizationAssumptions(resolvePeriodsPerYear('informationRatio', options)),
+      diagnostics: degenerateAwareDiagnostics(
+        value,
+        'informationRatio',
+        'the active (strategy − benchmark) series is empty or has zero variance (perfect tracking)',
+        returns,
+        benchmark,
+      ),
+    };
+  },
+);
+
+function treynorRatioValue(
+  returns: ArrayLike<number>,
+  benchmark: ArrayLike<number>,
+  options: SharpeOptions,
+): number {
+  requireAligned(returns, benchmark, 'treynorRatio');
+  ensureKnownKeys('treynorRatio', 'options', options, SHARPE_KEYS);
+  // Resolved before the degenerate early returns — see alphaValue.
+  const ppy = resolvePeriodsPerYear('treynorRatio', options);
+  const riskFreeRate = resolveRiskFreeRate('treynorRatio', options);
+  const b = betaValue(returns, benchmark);
+  if (b === 0 || !Number.isFinite(b)) return NaN;
+  // Exact-shaped hand-off: annualizedReturn takes AnnualizationOptions only — a riskFreeRate here
+  // would (rightly) trip its Law 12 guard.
+  const annReturn = annualizedReturn(returns, { periodsPerYear: ppy });
+  if (annReturn === null) return NaN;
+  return (annReturn - riskFreeRate) / b;
+}
+
+/**
+ * Treynor ratio: excess (over risk-free) annualized return per unit of systematic risk (beta),
+ * `(annualizedReturn − rf) / β`. Uses the geometric annualized return for the numerator.
+ */
+export const treynor = seriesFacade(
+  'treynor',
+  (
+    returns: ArrayLike<number>,
+    benchmark: ArrayLike<number>,
+    options: SharpeOptions = {},
+  ): number | null => finiteOrNull(treynorRatioValue(returns, benchmark, options)),
+  (
+    returns: ArrayLike<number>,
+    benchmark: ArrayLike<number>,
+    options: SharpeOptions = {},
+  ): Computed<number | null, RiskAdjustedExtra> => {
+    const value = treynorRatioValue(returns, benchmark, options);
+    return {
+      value: finiteOrNull(value),
+      assumptions: riskAdjustedAssumptions({
+        periodsPerYear: resolvePeriodsPerYear('treynorRatio', options),
+        riskFreeRate: resolveRiskFreeRate('treynorRatio', options),
+      }),
+      diagnostics: degenerateAwareDiagnostics(
+        value,
+        'treynor',
+        'beta is zero or undefined, so return per unit of systematic risk is undefined',
+        returns,
+        benchmark,
+      ),
+    };
+  },
+);

package/modules/performance/src/returns.ts

@@ -0,0 +1,80 @@
+import { ErrorCode, InputError, requireArgumentArray } from '@totalfinance/core';
+/** Return calculations (spec §15.1). */
+
+/**
+ * Throw the shared "a zero level cannot be a return denominator" error. `field` is the name the
+ * CALLER typed (`prices` here, `equity` in `analyze({ equity })`, which runs the same check under
+ * its own name), so the message teaches against the actual call site rather than an internal one.
+ * Deliberately module-private: this is a guard, not a public API surface.
+ */
+function requireNonZeroLevels(
+  levels: ArrayLike<number>,
+  functionName: string,
+  field: string,
+): void {
+  // Only a level that is USED as a denominator matters: a series ending at 0 is a legitimate total
+  // loss (a −100% final return), while a 0 anywhere before the end makes that period's return
+  // `x/0` — an undefined quantity this used to emit as a silent NaN, which then surfaced hundreds
+  // of lines away as an error blaming `annualizedReturn`.
+  for (let i = 0; i < levels.length - 1; i++) {
+    if (levels[i] === 0) {
+      throw new InputError(
+        `${functionName}: ${field}[${i}] is 0 — the return over ${field}[${i}] → ${field}[${i + 1}] divides by it and is undefined. ${field} is a price/equity LEVEL series (e.g. [100, 110, 99]); drop the zero level or pass the per-period returns directly.`,
+        { code: ErrorCode.InputOutOfRange, context: { function: functionName, field, index: i } },
+      );
+    }
+  }
+}
+
+/**
+ * Simple period-over-period returns; output length is `prices.length - 1`. A zero price before the
+ * final observation throws (that period's return divides by zero) rather than emitting a NaN that
+ * poisons every downstream metric.
+ */
+export function simpleReturns(prices: ArrayLike<number>): number[] {
+  requireArgumentArray('simpleReturns', 'prices', prices);
+  requireNonZeroLevels(prices, 'simpleReturns', 'prices');
+  const out: number[] = [];
+  for (let i = 1; i < prices.length; i++) {
+    const prev = prices[i - 1]!;
+    out.push((prices[i]! - prev) / prev);
+  }
+  return out;
+}
+
+/** Continuously-compounded (log) returns; output length is `prices.length - 1`. */
+export function logReturns(prices: ArrayLike<number>): number[] {
+  requireArgumentArray('logReturns', 'prices', prices);
+  const out: number[] = [];
+  for (let i = 1; i < prices.length; i++) out.push(Math.log(prices[i]! / prices[i - 1]!));
+  return out;
+}
+
+/** Cumulative compounded return at each step from a series of simple returns. */
+export function cumulativeReturns(returns: ArrayLike<number>): number[] {
+  requireArgumentArray('cumulativeReturns', 'returns', returns);
+  const out: number[] = [];
+  let growth = 1;
+  for (let i = 0; i < returns.length; i++) {
+    growth *= 1 + returns[i]!;
+    out.push(growth - 1);
+  }
+  return out;
+}
+
+/**
+ * Equity curve (growth of `start`) from a series of simple returns. The curve begins at `start` and
+ * has length `returns.length + 1`, so `analyze({ equity: equityCurve(returns) })` recovers every
+ * return — the starting capital is the first point, not an implicit one. (`equityCurve([])` is
+ * `[start]`.)
+ */
+export function equityCurve(returns: ArrayLike<number>, start = 1): number[] {
+  requireArgumentArray('equityCurve', 'returns', returns);
+  const out: number[] = [start];
+  let value = start;
+  for (let i = 0; i < returns.length; i++) {
+    value *= 1 + returns[i]!;
+    out.push(value);
+  }
+  return out;
+}

package/modules/performance/src/rolling.ts

@@ -0,0 +1,155 @@
+/**
+ * `@insiderfinance/totalfinance/performance/rolling` — rolling-window performance metrics (spec §15.1).
+ *
+ * Each returns one value per input period, aligned to the input index: `out[i]` is the metric over the
+ * trailing `window` periods ending at `i`, and the first `window − 1` entries are `NaN` (insufficient
+ * history). This matches the `@insiderfinance/totalfinance/math` rolling primitives these build on, so a windowed
+ * Sharpe/vol lines up with the original series for plotting or merging.
+ *
+ * Each is a facade (dx §2.3): `.explain()` returns the `Computed` envelope with the resolved window
+ * and conventions in `assumptions` and the warmup count (`window − 1`) in `diagnostics.warmup` —
+ * the same envelope grammar as the TA indicators.
+ */
+
+import {
+  CONVENTIONS_VERSION,
+  type Computed,
+  ErrorCode,
+  InputError,
+  seriesFacade,
+  ensureKnownKeys,
+} from '@totalfinance/core';
+import { rollingMean, rollingStandardDeviation } from '@totalfinance/math';
+import {
+  ANNUALIZATION_KEYS,
+  type AnnualizationOptions,
+  SHARPE_KEYS,
+  type SharpeOptions,
+  requireSeries,
+  returnsDiagnostics,
+} from './sharpe.js';
+import { resolvePeriodsPerYear, resolveRiskFreeRate } from './annualization-internal.js';
+
+function requireWindow(window: number, functionName: string): void {
+  if (!Number.isSafeInteger(window) || window < 2) {
+    throw new InputError(`${functionName}: window must be an integer ≥ 2, got ${window}.`, {
+      code: ErrorCode.InputOutOfRange,
+      context: { window },
+    });
+  }
+}
+
+/** Envelope diagnostics for a rolling metric: the plausibility guard plus the window warmup. */
+function rollingDiagnostics(
+  returns: ArrayLike<number>,
+  window: number,
+): Computed<number[]>['diagnostics'] {
+  return { ...returnsDiagnostics(returns), warmup: window - 1 };
+}
+
+function rollingVolatilityValue(
+  returns: ArrayLike<number>,
+  window: number,
+  options: AnnualizationOptions,
+): number[] {
+  requireSeries(returns, 'rollingVolatility');
+  requireWindow(window, 'rollingVolatility');
+  // Law 12: shared by the plain call AND `.explain()` — an unknown option teaches, never ignored.
+  ensureKnownKeys('rollingVolatility', 'options', options, ANNUALIZATION_KEYS);
+  const scale = Math.sqrt(resolvePeriodsPerYear('rollingVolatility', options));
+  return rollingStandardDeviation(returns, window).map((sd) => sd * scale);
+}
+
+/**
+ * Rolling annualized volatility over a trailing window (leading `window − 1` entries are `NaN`).
+ * `options.periodsPerYear` defaults to 252 — matching every other `rolling*(series, window, options?)`
+ * sibling, so the annualization factor is no longer a bare positional scalar.
+ */
+export const rollingVolatility = seriesFacade(
+  'rollingVolatility',
+  (returns: ArrayLike<number>, window: number, options: AnnualizationOptions = {}): number[] =>
+    rollingVolatilityValue(returns, window, options),
+  (
+    returns: ArrayLike<number>,
+    window: number,
+    options: AnnualizationOptions = {},
+  ): Computed<number[], { window: number; periodsPerYear: number }> => ({
+    value: rollingVolatilityValue(returns, window, options),
+    assumptions: {
+      conventionsVersion: CONVENTIONS_VERSION,
+      window,
+      periodsPerYear: resolvePeriodsPerYear('rollingVolatility', options),
+    },
+    diagnostics: rollingDiagnostics(returns, window),
+  }),
+);
+
+function rollingSharpeValue(
+  returns: ArrayLike<number>,
+  window: number,
+  options: SharpeOptions,
+): number[] {
+  requireSeries(returns, 'rollingSharpe');
+  requireWindow(window, 'rollingSharpe');
+  ensureKnownKeys('rollingSharpe', 'options', options, SHARPE_KEYS);
+  const ppy = resolvePeriodsPerYear('rollingSharpe', options);
+  const rfPerPeriod = resolveRiskFreeRate('rollingSharpe', options) / ppy;
+  const n = returns.length;
+  const excess = new Array<number>(n);
+  for (let i = 0; i < n; i++) excess[i] = returns[i]! - rfPerPeriod;
+  const means = rollingMean(excess, window);
+  const sds = rollingStandardDeviation(excess, window);
+  const scale = Math.sqrt(ppy);
+  return means.map((m, i) => {
+    const sd = sds[i]!;
+    return Number.isFinite(m) && sd !== 0 ? (m / sd) * scale : NaN;
+  });
+}
+
+/** Rolling annualized Sharpe ratio over a trailing window (leading `window − 1` entries are `NaN`). */
+export const rollingSharpe = seriesFacade(
+  'rollingSharpe',
+  (returns: ArrayLike<number>, window: number, options: SharpeOptions = {}): number[] =>
+    rollingSharpeValue(returns, window, options),
+  (
+    returns: ArrayLike<number>,
+    window: number,
+    options: SharpeOptions = {},
+  ): Computed<number[], { window: number; periodsPerYear: number; riskFreeRate: number }> => ({
+    value: rollingSharpeValue(returns, window, options),
+    assumptions: {
+      conventionsVersion: CONVENTIONS_VERSION,
+      window,
+      periodsPerYear: resolvePeriodsPerYear('rollingSharpe', options),
+      riskFreeRate: resolveRiskFreeRate('rollingSharpe', options),
+    },
+    diagnostics: rollingDiagnostics(returns, window),
+  }),
+);
+
+function rollingReturnValue(returns: ArrayLike<number>, window: number): number[] {
+  requireSeries(returns, 'rollingReturn');
+  requireWindow(window, 'rollingReturn');
+  const n = returns.length;
+  const out = new Array<number>(n).fill(NaN);
+  for (let end = window; end <= n; end++) {
+    let growth = 1;
+    for (let i = end - window; i < end; i++) growth *= 1 + returns[i]!;
+    out[end - 1] = growth - 1;
+  }
+  return out;
+}
+
+/**
+ * Rolling compounded return over a trailing window (`Π(1 + r) − 1`), aligned to the input index with
+ * the leading `window − 1` entries set to `NaN`.
+ */
+export const rollingReturn = seriesFacade(
+  'rollingReturn',
+  (returns: ArrayLike<number>, window: number): number[] => rollingReturnValue(returns, window),
+  (returns: ArrayLike<number>, window: number): Computed<number[], { window: number }> => ({
+    value: rollingReturnValue(returns, window),
+    assumptions: { conventionsVersion: CONVENTIONS_VERSION, window },
+    diagnostics: rollingDiagnostics(returns, window),
+  }),
+);