tradelab 1.0.0 → 1.1.0

package/src/metrics/buildMetrics.js

@@ -1,3 +1,7 @@
+import { clampFinite, BIG_NUMBER } from "./finite.js";
+import { periodsPerYear } from "./annualize.js";
+import { benchmarkStats } from "./benchmark.js";
+
 function sum(values) {
   return values.reduce((total, value) => total + value, 0);
 }
@@ -120,11 +124,9 @@ function percentile(values, percentileRank) {
   return sorted[index];
 }
 
-const PROFIT_FACTOR_CAP = 1_000_000;
-
 function finiteProfitFactor(grossProfit, grossLoss) {
   if (grossLoss === 0) {
-    return grossProfit > 0 ? PROFIT_FACTOR_CAP : 0;
+    return grossProfit > 0 ? BIG_NUMBER : 0;
   }
   return grossProfit / grossLoss;
 }
@@ -136,7 +138,16 @@ function finiteProfitFactor(grossProfit, grossLoss) {
  * `profitFactor`, `winRate`, `expectancy`, `maxDrawdown`, `sharpe`, `avgHold`,
  * and `sideBreakdown`, while preserving the more specific legacy fields.
  */
-export function buildMetrics({ closed, equityStart, equityFinal, candles, estBarMs, eqSeries }) {
+export function buildMetrics({
+  closed,
+  equityStart,
+  equityFinal,
+  candles,
+  estBarMs,
+  eqSeries,
+  interval,
+  benchmarkReturns,
+}) {
   const legs = [...closed].sort((left, right) => left.exit.time - right.exit.time);
   const completedTrades = [];
   const tradeRs = [];
@@ -283,19 +294,28 @@ export function buildMetrics({ closed, equityStart, equityFinal, candles, estBar
     },
   };
 
+  const periods = periodsPerYear(interval, estBarMs);
+  const sqrtPeriods = Math.sqrt(periods);
+  const sharpeAnnualized = clampFinite(clampFinite(sharpeDaily) * sqrtPeriods);
+  const sortinoAnnualized = clampFinite(clampFinite(sortinoDaily) * sqrtPeriods);
+  const benchmark = benchmarkStats(dailyReturnsSeries, benchmarkReturns ?? []);
+
   return {
     trades: completedTrades.length,
     winRate: completedTrades.length ? winningTradeCount / completedTrades.length : 0,
-    profitFactor: profitFactorPositions,
+    profitFactor: clampFinite(profitFactorPositions),
     expectancy,
     totalR,
     avgR,
-    sharpe: sharpeDaily,
-    sharpePerTrade,
-    sortinoPerTrade,
+    sharpe: clampFinite(sharpeDaily),
+    sharpeAnnualized,
+    sortinoAnnualized,
+    sharpePerTrade: clampFinite(sharpePerTrade),
+    sortinoPerTrade: clampFinite(sortinoPerTrade),
+    annualizationPeriods: periods,
     maxDrawdown: maxDrawdown,
     maxDrawdownPct: maxDrawdown,
-    calmar,
+    calmar: clampFinite(calmar),
     maxConsecWins: maxWin,
     maxConsecLosses: maxLoss,
     avgHold: avgHoldMin,
@@ -305,12 +325,13 @@ export function buildMetrics({ closed, equityStart, equityFinal, candles, estBar
     returnPct,
     finalEquity: equityFinal,
     startEquity: equityStart,
-    profitFactor_pos: profitFactorPositions,
-    profitFactor_leg: profitFactorLegs,
+    profitFactor_pos: clampFinite(profitFactorPositions),
+    profitFactor_leg: clampFinite(profitFactorLegs),
     winRate_pos: completedTrades.length ? winningTradeCount / completedTrades.length : 0,
     winRate_leg: legs.length ? winningLegCount / legs.length : 0,
-    sharpeDaily,
-    sortinoDaily,
+    sharpeDaily: clampFinite(sharpeDaily),
+    sortinoDaily: clampFinite(sortinoDaily),
+    benchmark,
     sideBreakdown,
     long: sideBreakdown.long,
     short: sideBreakdown.short,

package/src/metrics/finite.js

@@ -0,0 +1,17 @@
+// src/metrics/finite.js
+
+// Sentinel for "effectively infinite" metric values (e.g. profit factor with zero
+// losses). Large enough to be unmistakable, small enough to survive JSON.stringify
+// and JSON.parse round-trips without becoming Infinity.
+export const BIG_NUMBER = 1e9;
+
+/**
+ * Coerce a metric to a finite, JSON-safe number.
+ * +/-Infinity clamp to +/-BIG_NUMBER. NaN/null/undefined become `fallback`.
+ */
+export function clampFinite(value, fallback = 0) {
+  if (value === Infinity) return BIG_NUMBER;
+  if (value === -Infinity) return -BIG_NUMBER;
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  return fallback;
+}

package/src/research/combinations.js

@@ -0,0 +1,18 @@
+/** All k-sized index combinations of [0..n). Returns arrays of indices. */
+export function combinations(n, k) {
+  const result = [];
+  const combo = [];
+  function recurse(start) {
+    if (combo.length === k) {
+      result.push([...combo]);
+      return;
+    }
+    for (let i = start; i < n; i += 1) {
+      combo.push(i);
+      recurse(i + 1);
+      combo.pop();
+    }
+  }
+  recurse(0);
+  return result;
+}

package/src/research/cpcv.js

@@ -0,0 +1,47 @@
+import { combinations } from "./combinations.js";
+
+/**
+ * Combinatorial Purged Cross-Validation index splits.
+ *
+ * Splits [0..nObservations) into `nGroups` contiguous blocks, then forms every
+ * combination choosing `nTestGroups` blocks as the test set. Training indices
+ * that fall within `embargo` observations of any test block are purged.
+ */
+export function combinatorialPurgedSplits({
+  nObservations,
+  nGroups = 6,
+  nTestGroups = 2,
+  embargo = 0,
+}) {
+  if (!(nObservations > 0)) throw new Error("nObservations must be positive");
+  if (nTestGroups >= nGroups) throw new Error("nTestGroups must be < nGroups");
+
+  const bounds = [];
+  for (let g = 0; g < nGroups; g += 1) {
+    bounds.push([
+      Math.floor((g * nObservations) / nGroups),
+      Math.floor(((g + 1) * nObservations) / nGroups),
+    ]);
+  }
+
+  const splits = [];
+  for (const testGroups of combinations(nGroups, nTestGroups)) {
+    const testSet = new Set();
+    const purgeZones = [];
+    for (const g of testGroups) {
+      const [start, end] = bounds[g];
+      for (let i = start; i < end; i += 1) testSet.add(i);
+      purgeZones.push([start - embargo, end + embargo]);
+    }
+    const inPurge = (i) => purgeZones.some(([lo, hi]) => i >= lo && i < hi);
+
+    const train = [];
+    const testIdx = [];
+    for (let i = 0; i < nObservations; i += 1) {
+      if (testSet.has(i)) testIdx.push(i);
+      else if (!inPurge(i)) train.push(i);
+    }
+    splits.push({ train, test: testIdx, testGroups });
+  }
+  return splits;
+}

package/src/research/deflatedSharpe.js

@@ -0,0 +1,35 @@
+import { normalCdf, normalPpf } from "./stats.js";
+
+const EULER_MASCHERONI = 0.5772156649015329;
+
+/**
+ * Expected maximum Sharpe under the null (no skill), given `numTrials`
+ * independent strategy trials whose Sharpe estimates have std `sharpeStd`.
+ */
+export function sweepHaircut({ numTrials, sharpeStd }) {
+  const N = Math.max(1, numTrials);
+  const a = normalPpf(1 - 1 / N);
+  const b = normalPpf(1 - 1 / (N * Math.E));
+  const expectedMaxSharpe = sharpeStd * ((1 - EULER_MASCHERONI) * a + EULER_MASCHERONI * b);
+  return { expectedMaxSharpe, numTrials: N };
+}
+
+/**
+ * Deflated Sharpe Ratio: probability the observed `sharpe` is genuinely > 0
+ * after accounting for strategy trials, non-normality, and finite sample size.
+ */
+export function deflatedSharpe({
+  sharpe,
+  sampleSize,
+  numTrials = 1,
+  sharpeStd = 0,
+  skew = 0,
+  kurtosis = 3,
+}) {
+  const sr0 = sweepHaircut({ numTrials, sharpeStd }).expectedMaxSharpe;
+  const denom = Math.sqrt(
+    Math.max(1e-12, 1 - skew * sharpe + ((kurtosis - 1) / 4) * sharpe * sharpe)
+  );
+  const z = ((sharpe - sr0) * Math.sqrt(Math.max(1, sampleSize - 1))) / denom;
+  return normalCdf(z);
+}

package/src/research/index.js

@@ -0,0 +1,6 @@
+export { monteCarlo } from "./monteCarlo.js";
+export { deflatedSharpe, sweepHaircut } from "./deflatedSharpe.js";
+export { probabilityOfBacktestOverfitting } from "./pbo.js";
+export { combinatorialPurgedSplits } from "./cpcv.js";
+export { combinations } from "./combinations.js";
+export { normalCdf, normalPpf, moments } from "./stats.js";

package/src/research/monteCarlo.js

@@ -0,0 +1,88 @@
+import { makeRng, randInt } from "../utils/random.js";
+
+function percentile(sorted, p) {
+  if (!sorted.length) return 0;
+  const idx = Math.min(sorted.length - 1, Math.max(0, Math.floor((sorted.length - 1) * p)));
+  return sorted[idx];
+}
+
+function maxDrawdownOf(equityPath) {
+  let peak = equityPath[0];
+  let maxDd = 0;
+  for (const e of equityPath) {
+    if (e > peak) peak = e;
+    const dd = peak > 0 ? (peak - e) / peak : 0;
+    if (dd > maxDd) maxDd = dd;
+  }
+  return maxDd;
+}
+
+/**
+ * Block-bootstrap the trade PnL sequence `iterations` times to produce a
+ * distribution of final equity and max drawdown. `blockSize > 1` resamples
+ * contiguous blocks to preserve short-run autocorrelation (streaks).
+ *
+ * Returns percentile bands { p5, p25, p50, p75, p95 } for finalEquity and
+ * maxDrawdown, plus pathBands (per-step p5/p50/p95 of the equity curve).
+ */
+export function monteCarlo({
+  tradePnls,
+  equityStart = 10_000,
+  iterations = 1000,
+  blockSize = 1,
+  seed = "tradelab-mc",
+}) {
+  if (!Array.isArray(tradePnls) || tradePnls.length === 0) {
+    throw new Error("monteCarlo() requires a non-empty tradePnls array");
+  }
+  const rng = makeRng(seed);
+  const n = tradePnls.length;
+  const block = Math.max(1, Math.floor(blockSize));
+
+  const finals = [];
+  const drawdowns = [];
+  const pathSamples = Array.from({ length: n + 1 }, () => []);
+
+  for (let it = 0; it < iterations; it += 1) {
+    const path = [equityStart];
+    let equity = equityStart;
+    let filled = 0;
+    while (filled < n) {
+      const start = randInt(rng, n);
+      for (let k = 0; k < block && filled < n; k += 1) {
+        equity += tradePnls[(start + k) % n];
+        path.push(equity);
+        filled += 1;
+      }
+    }
+    for (let step = 0; step < path.length; step += 1) {
+      pathSamples[step].push(path[step]);
+    }
+    finals.push(equity);
+    drawdowns.push(maxDrawdownOf(path));
+  }
+
+  const sortedFinals = [...finals].sort((a, b) => a - b);
+  const sortedDd = [...drawdowns].sort((a, b) => a - b);
+  const pathBands = pathSamples.map((samples) => {
+    const s = [...samples].sort((a, b) => a - b);
+    return { p5: percentile(s, 0.05), p50: percentile(s, 0.5), p95: percentile(s, 0.95) };
+  });
+
+  const bands = (sorted) => ({
+    p5: percentile(sorted, 0.05),
+    p25: percentile(sorted, 0.25),
+    p50: percentile(sorted, 0.5),
+    p75: percentile(sorted, 0.75),
+    p95: percentile(sorted, 0.95),
+  });
+
+  return {
+    iterations,
+    blockSize: block,
+    finalEquity: bands(sortedFinals),
+    maxDrawdown: bands(sortedDd),
+    pathBands,
+    probProfit: finals.filter((f) => f > equityStart).length / iterations,
+  };
+}

package/src/research/pbo.js

@@ -0,0 +1,69 @@
+import { combinations } from "./combinations.js";
+
+function sharpeOf(returns) {
+  const n = returns.length;
+  if (n < 2) return 0;
+  const mean = returns.reduce((a, b) => a + b, 0) / n;
+  let variance = 0;
+  for (const r of returns) variance += (r - mean) ** 2;
+  variance /= n - 1;
+  const std = Math.sqrt(variance);
+  if (std === 0) {
+    if (mean > 0) return Infinity;
+    if (mean < 0) return -Infinity;
+    return 0;
+  }
+  return mean / std;
+}
+
+/**
+ * Combinatorially-Symmetric Cross-Validation estimate of the Probability of
+ * Backtest Overfitting (Bailey, Borwein, López de Prado, Zhu 2017).
+ */
+export function probabilityOfBacktestOverfitting(performanceMatrix, { groups = 16 } = {}) {
+  const nStrategies = performanceMatrix.length;
+  if (nStrategies < 2) throw new Error("PBO needs at least 2 strategies");
+  const nObs = performanceMatrix[0].length;
+  const S = Math.min(groups, nObs);
+  if (S % 2 !== 0) throw new Error("groups must be even");
+
+  const groupIdx = Array.from({ length: S }, () => []);
+  for (let i = 0; i < nObs; i += 1) groupIdx[Math.floor((i * S) / nObs)].push(i);
+
+  const isCombos = combinations(S, S / 2);
+  const logits = [];
+  let overfitCount = 0;
+
+  for (const isGroups of isCombos) {
+    const isSet = new Set(isGroups);
+    const isIndices = [];
+    const osIndices = [];
+    for (let g = 0; g < S; g += 1) {
+      (isSet.has(g) ? isIndices : osIndices).push(...groupIdx[g]);
+    }
+
+    const isScores = performanceMatrix.map((row) => sharpeOf(isIndices.map((i) => row[i])));
+    const osScores = performanceMatrix.map((row) => sharpeOf(osIndices.map((i) => row[i])));
+
+    let bestStrategy = 0;
+    for (let s = 1; s < nStrategies; s += 1) {
+      if (isScores[s] > isScores[bestStrategy]) bestStrategy = s;
+    }
+
+    const winnerOs = osScores[bestStrategy];
+    let rank = 1;
+    for (let s = 0; s < nStrategies; s += 1) {
+      if (s !== bestStrategy && osScores[s] < winnerOs) rank += 1;
+    }
+    const relativeRank = rank / (nStrategies + 1);
+    const logit = Math.log(relativeRank / (1 - relativeRank));
+    logits.push(logit);
+    if (relativeRank <= 0.5) overfitCount += 1;
+  }
+
+  return {
+    pbo: overfitCount / isCombos.length,
+    combos: isCombos.length,
+    medianLogit: [...logits].sort((a, b) => a - b)[Math.floor(logits.length / 2)],
+  };
+}

package/src/research/stats.js

@@ -0,0 +1,78 @@
+/** Standard normal CDF via Abramowitz & Stegun 7.1.26 (error < 1.5e-7). */
+export function normalCdf(x) {
+  const sign = x < 0 ? -1 : 1;
+  const ax = Math.abs(x) / Math.SQRT2;
+  const t = 1 / (1 + 0.3275911 * ax);
+  const y =
+    1 -
+    ((((1.061405429 * t - 1.453152027) * t + 1.421413741) * t - 0.284496736) * t + 0.254829592) *
+      t *
+      Math.exp(-ax * ax);
+  return 0.5 * (1 + sign * y);
+}
+
+/** Inverse standard normal CDF (Acklam's algorithm). */
+export function normalPpf(p) {
+  if (p <= 0) return -Infinity;
+  if (p >= 1) return Infinity;
+  const a = [
+    -3.969683028665376e1, 2.209460984245205e2, -2.759285104469687e2, 1.38357751867269e2,
+    -3.066479806614716e1, 2.506628277459239,
+  ];
+  const b = [
+    -5.447609879822406e1, 1.615858368580409e2, -1.556989798598866e2, 6.680131188771972e1,
+    -1.328068155288572e1,
+  ];
+  const c = [
+    -7.784894002430293e-3, -3.223964580411365e-1, -2.400758277161838, -2.549732539343734,
+    4.374664141464968, 2.938163982698783,
+  ];
+  const d = [7.784695709041462e-3, 3.224671290700398e-1, 2.445134137142996, 3.754408661907416];
+  const plow = 0.02425;
+  const phigh = 1 - plow;
+  let q;
+  let r;
+  if (p < plow) {
+    q = Math.sqrt(-2 * Math.log(p));
+    return (
+      (((((c[0] * q + c[1]) * q + c[2]) * q + c[3]) * q + c[4]) * q + c[5]) /
+      ((((d[0] * q + d[1]) * q + d[2]) * q + d[3]) * q + 1)
+    );
+  }
+  if (p <= phigh) {
+    q = p - 0.5;
+    r = q * q;
+    return (
+      ((((((a[0] * r + a[1]) * r + a[2]) * r + a[3]) * r + a[4]) * r + a[5]) * q) /
+      (((((b[0] * r + b[1]) * r + b[2]) * r + b[3]) * r + b[4]) * r + 1)
+    );
+  }
+  q = Math.sqrt(-2 * Math.log(1 - p));
+  return (
+    -(((((c[0] * q + c[1]) * q + c[2]) * q + c[3]) * q + c[4]) * q + c[5]) /
+    ((((d[0] * q + d[1]) * q + d[2]) * q + d[3]) * q + 1)
+  );
+}
+
+/** Sample skewness and excess-aware kurtosis (Pearson, kurtosis includes the +3). */
+export function moments(values) {
+  const n = values.length;
+  if (n < 2) return { mean: values[0] ?? 0, std: 0, skew: 0, kurtosis: 3 };
+  const mean = values.reduce((a, b) => a + b, 0) / n;
+  let m2 = 0;
+  let m3 = 0;
+  let m4 = 0;
+  for (const v of values) {
+    const d = v - mean;
+    m2 += d * d;
+    m3 += d * d * d;
+    m4 += d * d * d * d;
+  }
+  m2 /= n;
+  m3 /= n;
+  m4 /= n;
+  const std = Math.sqrt(m2);
+  const skew = std === 0 ? 0 : m3 / std ** 3;
+  const kurtosis = m2 === 0 ? 3 : m4 / m2 ** 2;
+  return { mean, std, skew, kurtosis };
+}

package/src/strategies/builtins.js

@@ -0,0 +1,96 @@
+import { ema } from "../utils/indicators.js";
+import { rsi } from "../ta/oscillators.js";
+import { donchian } from "../ta/channels.js";
+
+export const BUILTINS = {
+  "ema-cross": {
+    description: "Long when fast EMA crosses above slow EMA; stop at recent swing low.",
+    params: {
+      fast: { type: "number", default: 10, description: "fast EMA period" },
+      slow: { type: "number", default: 30, description: "slow EMA period" },
+      rr: { type: "number", default: 2, description: "reward:risk target" },
+      lookback: { type: "number", default: 15, description: "swing-low lookback for stop" },
+    },
+    factory({ fast = 10, slow = 30, rr = 2, lookback = 15 } = {}) {
+      return ({ candles, bar }) => {
+        if (candles.length < slow + 2) return null;
+        const closes = candles.map((c) => c.close);
+        const f = ema(closes, fast);
+        const s = ema(closes, slow);
+        const last = closes.length - 1;
+        if (f[last - 1] <= s[last - 1] && f[last] > s[last]) {
+          const stop = Math.min(...candles.slice(-lookback).map((c) => c.low));
+          if (stop >= bar.close) return null;
+          return { side: "long", entry: bar.close, stop, rr };
+        }
+        return null;
+      };
+    },
+  },
+
+  "rsi-reversion": {
+    description: "Long when RSI dips below `oversold`; stop a fixed pct below entry.",
+    params: {
+      period: { type: "number", default: 14, description: "RSI period" },
+      oversold: { type: "number", default: 30, description: "RSI entry threshold" },
+      stopPct: { type: "number", default: 2, description: "stop distance in percent" },
+      rr: { type: "number", default: 1.5, description: "reward:risk target" },
+    },
+    factory({ period = 14, oversold = 30, stopPct = 2, rr = 1.5 } = {}) {
+      return ({ candles, bar }) => {
+        if (candles.length < period + 2) return null;
+        const values = rsi(
+          candles.map((c) => c.close),
+          period
+        );
+        const r = values[values.length - 1];
+        if (r === undefined || r > oversold) return null;
+        return { side: "long", entry: bar.close, stop: bar.close * (1 - stopPct / 100), rr };
+      };
+    },
+  },
+
+  "donchian-breakout": {
+    description: "Long on a close above the prior Donchian upper channel.",
+    params: {
+      period: { type: "number", default: 20, description: "channel lookback" },
+      rr: { type: "number", default: 2, description: "reward:risk target" },
+    },
+    factory({ period = 20, rr = 2 } = {}) {
+      return ({ candles, bar }) => {
+        if (candles.length < period + 2) return null;
+        const ch = donchian(candles, period);
+        const i = candles.length - 1;
+        const priorUpper = ch.upper[i - 1];
+        const priorLower = ch.lower[i - 1];
+        if (priorUpper === undefined) return null;
+        if (bar.close > priorUpper) {
+          return { side: "long", entry: bar.close, stop: priorLower, rr };
+        }
+        return null;
+      };
+    },
+  },
+
+  "buy-hold": {
+    description: "Enter once at the first eligible bar and hold for `holdBars`.",
+    params: {
+      holdBars: { type: "number", default: 5, description: "bars to hold before exit" },
+      stopPct: { type: "number", default: 10, description: "protective stop distance in percent" },
+    },
+    factory({ holdBars = 5, stopPct = 10 } = {}) {
+      let entered = false;
+      return ({ bar }) => {
+        if (entered) return null;
+        entered = true;
+        return {
+          side: "long",
+          entry: bar.close,
+          stop: bar.close * (1 - stopPct / 100),
+          rr: 5,
+          _maxBarsInTrade: holdBars,
+        };
+      };
+    },
+  },
+};

package/src/strategies/index.js

@@ -0,0 +1,30 @@
+import { BUILTINS } from "./builtins.js";
+
+const registry = new Map(Object.entries(BUILTINS));
+
+/** Register a custom strategy at runtime. `def` is a BUILTINS-shaped object. */
+export function registerStrategy(name, def) {
+  if (typeof def?.factory !== "function") {
+    throw new Error(`registerStrategy("${name}") requires a factory function`);
+  }
+  registry.set(name, def);
+}
+
+/** List all strategies as { name, description, params }. */
+export function listStrategies() {
+  return [...registry.entries()].map(([name, def]) => ({
+    name,
+    description: def.description,
+    params: def.params,
+  }));
+}
+
+/** Get a strategy's signalFactory(params) => signal. Throws on unknown name. */
+export function getStrategy(name) {
+  const def = registry.get(name);
+  if (!def) {
+    const available = [...registry.keys()].join(", ");
+    throw new Error(`Unknown strategy "${name}". Available: ${available}`);
+  }
+  return def.factory;
+}

package/src/ta/channels.js

@@ -0,0 +1,67 @@
+// src/ta/channels.js
+import { ema, atr } from "../utils/indicators.js";
+
+function rollingMean(values, period, i) {
+  let sum = 0;
+  for (let j = i - period + 1; j <= i; j += 1) sum += values[j];
+  return sum / period;
+}
+
+/**
+ * Bollinger Bands. `mult` standard deviations around the SMA middle band.
+ */
+export function bollinger(closes, period = 20, mult = 2) {
+  const middle = new Array(closes.length).fill(undefined);
+  const upper = new Array(closes.length).fill(undefined);
+  const lower = new Array(closes.length).fill(undefined);
+  for (let i = period - 1; i < closes.length; i += 1) {
+    const avg = rollingMean(closes, period, i);
+    let variance = 0;
+    for (let j = i - period + 1; j <= i; j += 1) variance += (closes[j] - avg) ** 2;
+    const sd = Math.sqrt(variance / period);
+    middle[i] = avg;
+    upper[i] = avg + mult * sd;
+    lower[i] = avg - mult * sd;
+  }
+  return { middle, upper, lower };
+}
+
+/**
+ * Donchian channel: rolling highest-high / lowest-low over `period` bars.
+ */
+export function donchian(bars, period = 20) {
+  const upper = new Array(bars.length).fill(undefined);
+  const lower = new Array(bars.length).fill(undefined);
+  const middle = new Array(bars.length).fill(undefined);
+  for (let i = period - 1; i < bars.length; i += 1) {
+    let hh = -Infinity;
+    let ll = Infinity;
+    for (let j = i - period + 1; j <= i; j += 1) {
+      if (bars[j].high > hh) hh = bars[j].high;
+      if (bars[j].low < ll) ll = bars[j].low;
+    }
+    upper[i] = hh;
+    lower[i] = ll;
+    middle[i] = (hh + ll) / 2;
+  }
+  return { upper, lower, middle };
+}
+
+/**
+ * Keltner channel: EMA middle, +/- mult * ATR width.
+ */
+export function keltner(bars, emaPeriod = 20, atrPeriod = 14, mult = 2) {
+  const closes = bars.map((b) => b.close);
+  const mid = ema(closes, emaPeriod);
+  const range = atr(bars, atrPeriod);
+  const upper = new Array(bars.length).fill(undefined);
+  const lower = new Array(bars.length).fill(undefined);
+  const middle = new Array(bars.length).fill(undefined);
+  for (let i = 0; i < bars.length; i += 1) {
+    if (range[i] === undefined) continue;
+    middle[i] = mid[i];
+    upper[i] = mid[i] + mult * range[i];
+    lower[i] = mid[i] - mult * range[i];
+  }
+  return { upper, lower, middle };
+}

package/src/ta/index.js

@@ -0,0 +1,16 @@
+// src/ta/index.js
+export {
+  ema,
+  atr,
+  swingHigh,
+  swingLow,
+  detectFVG,
+  lastSwing,
+  structureState,
+} from "../utils/indicators.js";
+
+export { rsi, macd, stochastic } from "./oscillators.js";
+
+export { bollinger, donchian, keltner } from "./channels.js";
+
+export { supertrend, vwap } from "./trend.js";