@openfinclaw/fin-strategy-engine 0.0.1

package/src/indicators.ts

@@ -0,0 +1,238 @@
+/**
+ * Pure technical indicator functions. Zero external dependencies.
+ * All functions return arrays the same length as the input, with NaN
+ * for indices where the indicator cannot yet be computed (warm-up period).
+ */
+
+/** Simple Moving Average. */
+export function sma(data: number[], period: number): number[] {
+  const len = data.length;
+  const result = new Array<number>(len);
+  if (len === 0) return [];
+
+  let sum = 0;
+  for (let i = 0; i < len; i++) {
+    sum += data[i];
+    if (i < period - 1) {
+      result[i] = NaN;
+    } else {
+      if (i >= period) sum -= data[i - period];
+      result[i] = sum / period;
+    }
+  }
+  return result;
+}
+
+/** Exponential Moving Average. Seeded with SMA of the first `period` values. */
+export function ema(data: number[], period: number): number[] {
+  const len = data.length;
+  if (len === 0) return [];
+
+  const result = new Array<number>(len);
+  if (period > len) {
+    result.fill(NaN);
+    return result;
+  }
+
+  const k = 2 / (period + 1);
+
+  // Seed: SMA of first `period` values
+  let sum = 0;
+  for (let i = 0; i < period - 1; i++) {
+    sum += data[i];
+    result[i] = NaN;
+  }
+  sum += data[period - 1];
+  result[period - 1] = sum / period;
+
+  // Subsequent values use the EMA formula
+  for (let i = period; i < len; i++) {
+    result[i] = data[i] * k + result[i - 1] * (1 - k);
+  }
+  return result;
+}
+
+/**
+ * Relative Strength Index (Wilder's smoothing).
+ * Returns values in [0, 100]. NaN during warm-up.
+ */
+export function rsi(data: number[], period: number): number[] {
+  const len = data.length;
+  if (len === 0) return [];
+
+  const result = new Array<number>(len).fill(NaN);
+
+  // Need at least period+1 data points to compute first RSI
+  if (len < period + 1) return result;
+
+  // Compute initial average gain/loss over first `period` changes
+  let avgGain = 0;
+  let avgLoss = 0;
+  for (let i = 1; i <= period; i++) {
+    const change = data[i] - data[i - 1];
+    if (change > 0) avgGain += change;
+    else avgLoss += Math.abs(change);
+  }
+  avgGain /= period;
+  avgLoss /= period;
+
+  if (avgLoss === 0) {
+    result[period] = 100;
+  } else {
+    const rs = avgGain / avgLoss;
+    result[period] = 100 - 100 / (1 + rs);
+  }
+
+  // Wilder's smoothing for subsequent values
+  for (let i = period + 1; i < len; i++) {
+    const change = data[i] - data[i - 1];
+    const gain = change > 0 ? change : 0;
+    const loss = change < 0 ? Math.abs(change) : 0;
+
+    avgGain = (avgGain * (period - 1) + gain) / period;
+    avgLoss = (avgLoss * (period - 1) + loss) / period;
+
+    if (avgLoss === 0) {
+      result[i] = 100;
+    } else {
+      const rs = avgGain / avgLoss;
+      result[i] = 100 - 100 / (1 + rs);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Moving Average Convergence Divergence.
+ * Returns MACD line, signal line, and histogram.
+ */
+export function macd(
+  data: number[],
+  fast = 12,
+  slow = 26,
+  signal = 9,
+): { macd: number[]; signal: number[]; histogram: number[] } {
+  const len = data.length;
+  if (len === 0) {
+    return { macd: [], signal: [], histogram: [] };
+  }
+
+  const fastEma = ema(data, fast);
+  const slowEma = ema(data, slow);
+
+  // MACD line = fast EMA - slow EMA
+  const macdLine = new Array<number>(len);
+  for (let i = 0; i < len; i++) {
+    if (Number.isNaN(fastEma[i]) || Number.isNaN(slowEma[i])) {
+      macdLine[i] = NaN;
+    } else {
+      macdLine[i] = fastEma[i] - slowEma[i];
+    }
+  }
+
+  // Signal line = EMA of MACD line (only over valid MACD values)
+  // Find first valid MACD index
+  let firstValid = -1;
+  for (let i = 0; i < len; i++) {
+    if (!Number.isNaN(macdLine[i])) {
+      firstValid = i;
+      break;
+    }
+  }
+
+  const signalLine = new Array<number>(len).fill(NaN);
+  const histogram = new Array<number>(len).fill(NaN);
+
+  if (firstValid === -1 || len - firstValid < signal) {
+    return { macd: macdLine, signal: signalLine, histogram };
+  }
+
+  // Compute EMA of the valid portion of MACD line
+  const validMacd = macdLine.slice(firstValid);
+  const signalEma = ema(validMacd, signal);
+
+  for (let i = 0; i < signalEma.length; i++) {
+    signalLine[firstValid + i] = signalEma[i];
+    if (!Number.isNaN(signalEma[i]) && !Number.isNaN(macdLine[firstValid + i])) {
+      histogram[firstValid + i] = macdLine[firstValid + i] - signalEma[i];
+    }
+  }
+
+  return { macd: macdLine, signal: signalLine, histogram };
+}
+
+/**
+ * Bollinger Bands: middle = SMA, upper/lower = middle +/- stdDev * multiplier.
+ */
+export function bollingerBands(
+  data: number[],
+  period = 20,
+  stdDevMultiplier = 2,
+): { upper: number[]; middle: number[]; lower: number[] } {
+  const len = data.length;
+  if (len === 0) {
+    return { upper: [], middle: [], lower: [] };
+  }
+
+  const middle = sma(data, period);
+  const upper = new Array<number>(len);
+  const lower = new Array<number>(len);
+
+  for (let i = 0; i < len; i++) {
+    if (Number.isNaN(middle[i])) {
+      upper[i] = NaN;
+      lower[i] = NaN;
+    } else {
+      // Compute standard deviation over the window
+      let sumSq = 0;
+      for (let j = i - period + 1; j <= i; j++) {
+        const diff = data[j] - middle[i];
+        sumSq += diff * diff;
+      }
+      const sd = Math.sqrt(sumSq / period);
+      upper[i] = middle[i] + stdDevMultiplier * sd;
+      lower[i] = middle[i] - stdDevMultiplier * sd;
+    }
+  }
+
+  return { upper, middle, lower };
+}
+
+/**
+ * Average True Range (Wilder's smoothing).
+ * True Range = max(H-L, |H-prevClose|, |L-prevClose|).
+ */
+export function atr(highs: number[], lows: number[], closes: number[], period = 14): number[] {
+  const len = highs.length;
+  if (len === 0) return [];
+
+  const result = new Array<number>(len).fill(NaN);
+
+  // Compute True Range array (first bar has no previous close, so TR = H - L)
+  const tr = new Array<number>(len);
+  tr[0] = highs[0] - lows[0];
+  for (let i = 1; i < len; i++) {
+    const hl = highs[i] - lows[i];
+    const hpc = Math.abs(highs[i] - closes[i - 1]);
+    const lpc = Math.abs(lows[i] - closes[i - 1]);
+    tr[i] = Math.max(hl, hpc, lpc);
+  }
+
+  // Need at least `period` TRs to compute first ATR
+  if (len < period + 1) return result;
+
+  // First ATR = simple average of first `period` TRs (starting from index 1)
+  let sum = 0;
+  for (let i = 1; i <= period; i++) {
+    sum += tr[i];
+  }
+  result[period] = sum / period;
+
+  // Wilder's smoothing
+  for (let i = period + 1; i < len; i++) {
+    result[i] = (result[i - 1] * (period - 1) + tr[i]) / period;
+  }
+
+  return result;
+}

package/src/stats.test.ts

@@ -0,0 +1,215 @@
+import { describe, it, expect } from "vitest";
+import {
+  mean,
+  stdDev,
+  sharpeRatio,
+  sortinoRatio,
+  maxDrawdown,
+  calmarRatio,
+  profitFactor,
+  winRate,
+} from "./stats.js";
+
+function expectClose(actual: number, expected: number, tolerance = 0.0001) {
+  if (expected === 0) {
+    expect(Math.abs(actual)).toBeLessThan(tolerance);
+  } else {
+    expect(Math.abs((actual - expected) / expected)).toBeLessThan(tolerance);
+  }
+}
+
+describe("mean", () => {
+  it("computes arithmetic mean", () => {
+    expectClose(mean([1, 2, 3, 4, 5]), 3);
+  });
+
+  it("returns NaN for empty array", () => {
+    expect(mean([])).toBeNaN();
+  });
+
+  it("handles single value", () => {
+    expectClose(mean([42]), 42);
+  });
+
+  it("handles negative values", () => {
+    expectClose(mean([-10, 10]), 0);
+  });
+});
+
+describe("stdDev", () => {
+  it("computes sample standard deviation by default", () => {
+    // [2, 4, 4, 4, 5, 5, 7, 9] → mean=5, sample var=4.571..., sample sd=2.138...
+    expectClose(stdDev([2, 4, 4, 4, 5, 5, 7, 9]), 2.13809, 0.001);
+  });
+
+  it("computes population standard deviation when specified", () => {
+    // Population var = 4, pop sd = 2.0
+    expectClose(stdDev([2, 4, 4, 4, 5, 5, 7, 9], true), 2.0, 0.001);
+  });
+
+  it("returns 0 for constant values", () => {
+    expectClose(stdDev([5, 5, 5, 5]), 0);
+  });
+
+  it("returns NaN for empty array", () => {
+    expect(stdDev([])).toBeNaN();
+  });
+
+  it("returns 0 for single value (population)", () => {
+    expectClose(stdDev([5], true), 0);
+  });
+});
+
+describe("sharpeRatio", () => {
+  it("positive returns → Sharpe > 0", () => {
+    const returns = [0.01, 0.02, 0.015, 0.01, 0.025, 0.02, 0.01, 0.015, 0.02, 0.01, 0.015, 0.02];
+    const sr = sharpeRatio(returns);
+    expect(sr).toBeGreaterThan(0);
+  });
+
+  it("constant returns → Infinity (zero stddev)", () => {
+    const returns = [0.01, 0.01, 0.01, 0.01];
+    const sr = sharpeRatio(returns);
+    expect(sr).toBe(Infinity);
+  });
+
+  it("negative excess returns → Sharpe < 0", () => {
+    const returns = [-0.01, -0.02, -0.015, -0.01];
+    const sr = sharpeRatio(returns, 0);
+    expect(sr).toBeLessThan(0);
+  });
+
+  it("annualizes by default (sqrt(252) factor)", () => {
+    const returns = [0.01, 0.02, 0.015, 0.01, 0.025];
+    const annualized = sharpeRatio(returns, 0, true);
+    const nonAnnualized = sharpeRatio(returns, 0, false);
+    expectClose(annualized, nonAnnualized * Math.sqrt(252), 0.001);
+  });
+
+  it("respects custom risk-free rate", () => {
+    const returns = [0.05, 0.06, 0.04, 0.05, 0.07];
+    const sr1 = sharpeRatio(returns, 0, false);
+    const sr2 = sharpeRatio(returns, 0.03, false);
+    expect(sr1).toBeGreaterThan(sr2);
+  });
+});
+
+describe("sortinoRatio", () => {
+  it("no downside deviation → Infinity", () => {
+    const returns = [0.01, 0.02, 0.03, 0.04];
+    const sr = sortinoRatio(returns, 0);
+    expect(sr).toBe(Infinity);
+  });
+
+  it("all negative → negative Sortino", () => {
+    const returns = [-0.01, -0.02, -0.03, -0.04];
+    const sr = sortinoRatio(returns, 0);
+    expect(sr).toBeLessThan(0);
+  });
+
+  it("mixed returns produce finite ratio", () => {
+    const returns = [0.02, -0.01, 0.03, -0.02, 0.01];
+    const sr = sortinoRatio(returns, 0);
+    expect(Number.isFinite(sr)).toBe(true);
+    expect(sr).toBeGreaterThan(0);
+  });
+});
+
+describe("maxDrawdown", () => {
+  it("computes drawdown from peak to trough", () => {
+    const equity = [100, 110, 90, 95];
+    const result = maxDrawdown(equity);
+    // Max drawdown: from 110 to 90 = -18.18%
+    expectClose(result.maxDD, -18.1818, 0.01);
+    expect(result.peak).toBe(110);
+    expect(result.trough).toBe(90);
+    expect(result.peakIndex).toBe(1);
+    expect(result.troughIndex).toBe(2);
+  });
+
+  it("monotonic up → maxDD = 0", () => {
+    const equity = [100, 110, 120, 130];
+    const result = maxDrawdown(equity);
+    expectClose(result.maxDD, 0);
+  });
+
+  it("monotonic down → full drawdown", () => {
+    const equity = [100, 80, 60, 40];
+    const result = maxDrawdown(equity);
+    // From 100 to 40 = -60%
+    expectClose(result.maxDD, -60, 0.01);
+    expect(result.peakIndex).toBe(0);
+    expect(result.troughIndex).toBe(3);
+  });
+
+  it("finds the worst drawdown among multiple dips", () => {
+    const equity = [100, 95, 110, 80, 120, 100];
+    const result = maxDrawdown(equity);
+    // Worst: 110 → 80 = -27.27%
+    expectClose(result.maxDD, -27.2727, 0.01);
+    expect(result.peak).toBe(110);
+    expect(result.trough).toBe(80);
+  });
+
+  it("handles single value", () => {
+    const result = maxDrawdown([100]);
+    expectClose(result.maxDD, 0);
+  });
+});
+
+describe("calmarRatio", () => {
+  it("computes annualized return / abs(maxDrawdown)", () => {
+    // 20% return, -10% drawdown → Calmar = 2.0
+    expectClose(calmarRatio(0.2, -0.1), 2.0);
+  });
+
+  it("zero drawdown → Infinity", () => {
+    expect(calmarRatio(0.15, 0)).toBe(Infinity);
+  });
+
+  it("negative return with drawdown → negative ratio", () => {
+    expect(calmarRatio(-0.1, -0.2)).toBeLessThan(0);
+  });
+});
+
+describe("profitFactor", () => {
+  it("no losses → Infinity", () => {
+    expect(profitFactor([100, 200, 50], [])).toBe(Infinity);
+  });
+
+  it("no wins → 0", () => {
+    expect(profitFactor([], [100, 200])).toBe(0);
+  });
+
+  it("equal wins and losses → 1", () => {
+    expectClose(profitFactor([100], [100]), 1);
+  });
+
+  it("computes sum(wins) / sum(abs(losses))", () => {
+    // Wins: 100+200=300, Losses: -50+-100=-150 → abs=150 → PF=2
+    expectClose(profitFactor([100, 200], [-50, -100]), 2);
+  });
+});
+
+describe("winRate", () => {
+  it("3 wins, 2 losses → 60%", () => {
+    const trades = [{ pnl: 10 }, { pnl: -5 }, { pnl: 20 }, { pnl: 15 }, { pnl: -8 }];
+    expectClose(winRate(trades), 60);
+  });
+
+  it("all wins → 100%", () => {
+    expectClose(winRate([{ pnl: 10 }, { pnl: 5 }]), 100);
+  });
+
+  it("all losses → 0%", () => {
+    expectClose(winRate([{ pnl: -10 }, { pnl: -5 }]), 0);
+  });
+
+  it("empty trades → NaN", () => {
+    expect(winRate([])).toBeNaN();
+  });
+
+  it("zero pnl counts as non-win", () => {
+    expectClose(winRate([{ pnl: 0 }, { pnl: 10 }]), 50);
+  });
+});

package/src/stats.ts

@@ -0,0 +1,115 @@
+/**
+ * Pure statistical functions for strategy performance analysis.
+ * Zero external dependencies.
+ *
+ * mean, stdDev, and sharpeRatio are canonical in @openfinclaw/fin-shared-types
+ * and re-exported here for backward compatibility within fin-strategy-engine.
+ */
+
+export { mean, stdDev, sharpeRatio } from "../../fin-shared-types/src/stats.js";
+
+import { mean } from "../../fin-shared-types/src/stats.js";
+
+/**
+ * Sortino Ratio: like Sharpe but penalizes only downside deviation.
+ * Annualized by sqrt(252).
+ */
+export function sortinoRatio(returns: number[], riskFreeRate = 0): number {
+  const excess = returns.map((r) => r - riskFreeRate);
+  const m = mean(excess);
+
+  // Downside deviation: stddev of negative excess returns only
+  const downsideSquares = excess.filter((r) => r < 0).map((r) => r * r);
+  if (downsideSquares.length === 0) {
+    return m >= 0 ? Infinity : -Infinity;
+  }
+
+  let sumSq = 0;
+  for (const sq of downsideSquares) sumSq += sq;
+  const downsideDev = Math.sqrt(sumSq / returns.length);
+
+  if (downsideDev === 0) {
+    return m >= 0 ? Infinity : -Infinity;
+  }
+
+  return (m / downsideDev) * Math.sqrt(252);
+}
+
+/**
+ * Maximum drawdown from an equity curve.
+ * Returns the worst peak-to-trough decline as a percentage.
+ */
+export function maxDrawdown(equityCurve: number[]): {
+  maxDD: number;
+  peak: number;
+  trough: number;
+  peakIndex: number;
+  troughIndex: number;
+} {
+  if (equityCurve.length <= 1) {
+    return {
+      maxDD: 0,
+      peak: equityCurve[0] ?? 0,
+      trough: equityCurve[0] ?? 0,
+      peakIndex: 0,
+      troughIndex: 0,
+    };
+  }
+
+  let peak = equityCurve[0];
+  let peakIdx = 0;
+  let worstDD = 0;
+  let worstPeak = peak;
+  let worstTrough = peak;
+  let worstPeakIdx = 0;
+  let worstTroughIdx = 0;
+
+  for (let i = 1; i < equityCurve.length; i++) {
+    const val = equityCurve[i];
+    if (val > peak) {
+      peak = val;
+      peakIdx = i;
+    }
+    const dd = ((val - peak) / peak) * 100;
+    if (dd < worstDD) {
+      worstDD = dd;
+      worstPeak = peak;
+      worstTrough = val;
+      worstPeakIdx = peakIdx;
+      worstTroughIdx = i;
+    }
+  }
+
+  return {
+    maxDD: worstDD,
+    peak: worstPeak,
+    trough: worstTrough,
+    peakIndex: worstPeakIdx,
+    troughIndex: worstTroughIdx,
+  };
+}
+
+/** Calmar Ratio: annualized return / |maxDrawdown|. */
+export function calmarRatio(annualizedReturn: number, maxDD: number): number {
+  if (maxDD === 0) return annualizedReturn >= 0 ? Infinity : -Infinity;
+  return annualizedReturn / Math.abs(maxDD);
+}
+
+/**
+ * Profit Factor: sum(wins) / sum(|losses|).
+ * Wins are positive values, losses are negative or passed as-is (abs taken).
+ */
+export function profitFactor(wins: number[], losses: number[]): number {
+  const totalWins = wins.reduce((s, v) => s + v, 0);
+  const totalLosses = losses.reduce((s, v) => s + Math.abs(v), 0);
+  if (totalLosses === 0) return totalWins > 0 ? Infinity : 0;
+  if (totalWins === 0) return 0;
+  return totalWins / totalLosses;
+}
+
+/** Win rate as a percentage (0-100). Wins = trades with pnl > 0. */
+export function winRate(trades: Array<{ pnl: number }>): number {
+  if (trades.length === 0) return NaN;
+  const wins = trades.filter((t) => t.pnl > 0).length;
+  return (wins / trades.length) * 100;
+}