tradelab 0.1.0

package/src/engine/execution.js

@@ -0,0 +1,120 @@
+import { minutesET } from "../utils/time.js";
+
+export function applyFill(
+  price,
+  side,
+  { slippageBps = 0, feeBps = 0, kind = "market" } = {}
+) {
+  let effectiveSlippageBps = slippageBps;
+  if (kind === "limit") effectiveSlippageBps *= 0.25;
+  if (kind === "stop") effectiveSlippageBps *= 1.25;
+
+  const slippage = (effectiveSlippageBps / 10000) * price;
+  const filledPrice = side === "long" ? price + slippage : price - slippage;
+  const feePerUnit = (feeBps / 10000) * Math.abs(filledPrice);
+  return { price: filledPrice, fee: feePerUnit };
+}
+
+export function clampStop(marketPrice, proposedStop, side, oco) {
+  const epsilon = (oco?.clampEpsBps ?? 0.25) / 10000;
+  const epsilonAbs = marketPrice * epsilon;
+  return side === "long"
+    ? Math.min(proposedStop, marketPrice - epsilonAbs)
+    : Math.max(proposedStop, marketPrice + epsilonAbs);
+}
+
+export function touchedLimit(side, limitPrice, bar, mode = "intrabar") {
+  if (!bar || limitPrice === undefined || limitPrice === null) return false;
+  if (mode === "close") {
+    return side === "long"
+      ? bar.close <= limitPrice
+      : bar.close >= limitPrice;
+  }
+  return side === "long" ? bar.low <= limitPrice : bar.high >= limitPrice;
+}
+
+export function ocoExitCheck({
+  side,
+  stop,
+  tp,
+  bar,
+  mode = "intrabar",
+  tieBreak = "pessimistic",
+}) {
+  if (mode === "close") {
+    const close = bar.close;
+    if (side === "long") {
+      if (close <= stop) return { hit: "SL", px: stop };
+      if (close >= tp) return { hit: "TP", px: tp };
+    } else {
+      if (close >= stop) return { hit: "SL", px: stop };
+      if (close <= tp) return { hit: "TP", px: tp };
+    }
+    return { hit: null, px: null };
+  }
+
+  const hitStop = side === "long" ? bar.low <= stop : bar.high >= stop;
+  const hitTarget = side === "long" ? bar.high >= tp : bar.low <= tp;
+
+  if (hitStop && hitTarget) {
+    return tieBreak === "optimistic"
+      ? { hit: "TP", px: tp }
+      : { hit: "SL", px: stop };
+  }
+
+  if (hitStop) return { hit: "SL", px: stop };
+  if (hitTarget) return { hit: "TP", px: tp };
+  return { hit: null, px: null };
+}
+
+export function isEODBar(timeMs) {
+  return minutesET(timeMs) >= 16 * 60;
+}
+
+export function roundStep(value, step = 0.001) {
+  return Math.floor(value / step) * step;
+}
+
+export function estimateBarMs(candles) {
+  if (candles.length >= 2) {
+    const deltas = [];
+    for (let index = 1; index < Math.min(candles.length, 500); index += 1) {
+      const delta = candles[index].time - candles[index - 1].time;
+      if (Number.isFinite(delta) && delta > 0) deltas.push(delta);
+    }
+
+    if (deltas.length) {
+      deltas.sort((a, b) => a - b);
+      const middle = Math.floor(deltas.length / 2);
+      const median =
+        deltas.length % 2
+          ? deltas[middle]
+          : (deltas[middle - 1] + deltas[middle]) / 2;
+      return Math.max(60e3, Math.min(median, 60 * 60e3));
+    }
+  }
+  return 5 * 60 * 1000;
+}
+
+export function dayKeyUTC(timeMs) {
+  const date = new Date(timeMs);
+  return [
+    date.getUTCFullYear(),
+    String(date.getUTCMonth() + 1).padStart(2, "0"),
+    String(date.getUTCDate()).padStart(2, "0"),
+  ].join("-");
+}
+
+export function dayKeyET(timeMs) {
+  const date = new Date(timeMs);
+  const minutes = minutesET(timeMs);
+  const hoursET = Math.floor(minutes / 60);
+  const minutesETDay = minutes % 60;
+
+  const anchor = new Date(
+    Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate(), 0, 0, 0)
+  );
+  const pseudoEtTime =
+    anchor.getTime() + hoursET * 60 * 60 * 1000 + minutesETDay * 60 * 1000;
+  return dayKeyUTC(pseudoEtTime);
+}

package/src/index.js

@@ -0,0 +1,43 @@
+export { backtest } from "./engine/backtest.js";
+
+export { buildMetrics } from "./metrics/buildMetrics.js";
+export {
+  backtestHistorical,
+  cachedCandlesPath,
+  candleStats,
+  fetchHistorical,
+  fetchLatestCandle,
+  getHistoricalCandles,
+  loadCandlesFromCache,
+  loadCandlesFromCSV,
+  mergeCandles,
+  normalizeCandles,
+  saveCandlesToCache,
+} from "./data/index.js";
+
+export {
+  renderHtmlReport,
+  exportHtmlReport,
+} from "./reporting/renderHtmlReport.js";
+export { exportTradesCsv } from "./reporting/exportTradesCsv.js";
+export { exportBacktestArtifacts } from "./reporting/exportBacktestArtifacts.js";
+
+export {
+  ema,
+  atr,
+  swingHigh,
+  swingLow,
+  detectFVG,
+  lastSwing,
+  structureState,
+  bpsOf,
+  pct,
+} from "./utils/indicators.js";
+export { calculatePositionSize } from "./utils/positionSizing.js";
+export {
+  offsetET,
+  minutesET,
+  isSession,
+  parseWindowsCSV,
+  inWindowsET,
+} from "./utils/time.js";

package/src/metrics/buildMetrics.js

@@ -0,0 +1,306 @@
+function sum(values) {
+  return values.reduce((total, value) => total + value, 0);
+}
+
+function mean(values) {
+  return values.length ? sum(values) / values.length : 0;
+}
+
+function stddev(values) {
+  if (values.length <= 1) return 0;
+  const avg = mean(values);
+  return Math.sqrt(mean(values.map((value) => (value - avg) ** 2)));
+}
+
+function sortino(values) {
+  const losses = values.filter((value) => value < 0);
+  const downsideDeviation = stddev(losses.length ? losses : [0]);
+  const avg = mean(values);
+  return downsideDeviation === 0
+    ? avg > 0
+      ? Infinity
+      : 0
+    : avg / downsideDeviation;
+}
+
+function dayKeyUTC(timeMs) {
+  const date = new Date(timeMs);
+  return [
+    date.getUTCFullYear(),
+    String(date.getUTCMonth() + 1).padStart(2, "0"),
+    String(date.getUTCDate()).padStart(2, "0"),
+  ].join("-");
+}
+
+function tradeRMultiple(trade) {
+  const initialRisk = trade._initRisk || 0;
+  if (initialRisk <= 0) return 0;
+  const entry = trade.entryFill ?? trade.entry;
+  const perUnit =
+    trade.side === "long"
+      ? trade.exit.price - entry
+      : entry - trade.exit.price;
+  return perUnit / initialRisk;
+}
+
+function streaks(labels) {
+  let wins = 0;
+  let losses = 0;
+  let maxWins = 0;
+  let maxLosses = 0;
+
+  for (const label of labels) {
+    if (label === "win") {
+      wins += 1;
+      losses = 0;
+      if (wins > maxWins) maxWins = wins;
+      continue;
+    }
+
+    if (label === "loss") {
+      losses += 1;
+      wins = 0;
+      if (losses > maxLosses) maxLosses = losses;
+      continue;
+    }
+
+    wins = 0;
+    losses = 0;
+  }
+
+  return { maxWin: maxWins, maxLoss: maxLosses };
+}
+
+function buildEquitySeriesFromLegs({ legs, equityStart }) {
+  const firstTime = legs.length ? legs[0].exit.time : Date.now();
+  const series = [{ time: firstTime, equity: equityStart }];
+  let equity = equityStart;
+
+  for (const leg of legs) {
+    equity += leg.exit.pnl;
+    series.push({ time: leg.exit.time, equity });
+  }
+
+  return series;
+}
+
+function dailyReturns(eqSeries) {
+  if (!eqSeries?.length) return [];
+
+  const byDay = new Map();
+  for (const point of eqSeries) {
+    const day = dayKeyUTC(point.time);
+    const record = byDay.get(day) || {
+      open: point.equity,
+      close: point.equity,
+      first: point.time,
+      last: point.time,
+    };
+
+    if (point.time < record.first) {
+      record.first = point.time;
+      record.open = point.equity;
+    }
+
+    if (point.time >= record.last) {
+      record.last = point.time;
+      record.close = point.equity;
+    }
+
+    byDay.set(day, record);
+  }
+
+  const returns = [];
+  for (const { open, close } of byDay.values()) {
+    if (open > 0 && Number.isFinite(open) && Number.isFinite(close)) {
+      returns.push((close - open) / open);
+    }
+  }
+
+  return returns;
+}
+
+function percentile(values, percentileRank) {
+  if (!values.length) return 0;
+  const sorted = [...values].sort((a, b) => a - b);
+  const index = Math.floor((sorted.length - 1) * percentileRank);
+  return sorted[index];
+}
+
+export function buildMetrics({
+  closed,
+  equityStart,
+  equityFinal,
+  candles,
+  estBarMs,
+  eqSeries,
+}) {
+  const completedTrades = closed.filter((trade) => trade.exit.reason !== "SCALE");
+  const winningTrades = completedTrades.filter((trade) => trade.exit.pnl > 0);
+  const losingTrades = completedTrades.filter((trade) => trade.exit.pnl < 0);
+
+  const tradeRs = completedTrades.map(tradeRMultiple);
+  const totalR = sum(tradeRs);
+  const avgR = mean(tradeRs);
+
+  const labels = completedTrades.map((trade) =>
+    trade.exit.pnl > 0 ? "win" : trade.exit.pnl < 0 ? "loss" : "flat"
+  );
+  const { maxWin, maxLoss } = streaks(labels);
+
+  const tradePnls = completedTrades.map((trade) => trade.exit.pnl);
+  const expectancy = mean(tradePnls);
+  const tradeReturns = completedTrades.map(
+    (trade) => trade.exit.pnl / Math.max(1e-12, equityStart)
+  );
+  const tradeReturnStd = stddev(tradeReturns);
+  const sharpePerTrade =
+    tradeReturnStd === 0
+      ? tradeReturns.length
+        ? Infinity
+        : 0
+      : mean(tradeReturns) / tradeReturnStd;
+  const sortinoPerTrade = sortino(tradeReturns);
+
+  const grossProfitPositions = sum(winningTrades.map((trade) => trade.exit.pnl));
+  const grossLossPositions = Math.abs(
+    sum(losingTrades.map((trade) => trade.exit.pnl))
+  );
+  const profitFactorPositions =
+    grossLossPositions === 0
+      ? grossProfitPositions > 0
+        ? Infinity
+        : 0
+      : grossProfitPositions / grossLossPositions;
+
+  const legs = [...closed].sort((left, right) => left.exit.time - right.exit.time);
+  const winningLegs = legs.filter((trade) => trade.exit.pnl > 0);
+  const losingLegs = legs.filter((trade) => trade.exit.pnl < 0);
+  const grossProfitLegs = sum(winningLegs.map((trade) => trade.exit.pnl));
+  const grossLossLegs = Math.abs(sum(losingLegs.map((trade) => trade.exit.pnl)));
+  const profitFactorLegs =
+    grossLossLegs === 0
+      ? grossProfitLegs > 0
+        ? Infinity
+        : 0
+      : grossProfitLegs / grossLossLegs;
+
+  let peakEquity = equityStart;
+  let currentEquity = equityStart;
+  let maxDrawdown = 0;
+
+  for (const leg of legs) {
+    currentEquity += leg.exit.pnl;
+    if (currentEquity > peakEquity) peakEquity = currentEquity;
+    const drawdown = (peakEquity - currentEquity) / Math.max(1e-12, peakEquity);
+    if (drawdown > maxDrawdown) maxDrawdown = drawdown;
+  }
+
+  const realizedPnL = sum(closed.map((trade) => trade.exit.pnl));
+  const returnPct = (equityFinal - equityStart) / Math.max(1e-12, equityStart);
+  const calmar = maxDrawdown === 0 ? (returnPct > 0 ? Infinity : 0) : returnPct / maxDrawdown;
+
+  const totalBars = Math.max(1, candles.length);
+  const openBars = completedTrades.reduce((total, trade) => {
+    const barsHeld = Math.max(1, Math.round((trade.exit.time - trade.openTime) / estBarMs));
+    return total + barsHeld;
+  }, 0);
+  const exposurePct = openBars / totalBars;
+
+  const holdDurationsMinutes = completedTrades.map(
+    (trade) => (trade.exit.time - trade.openTime) / (1000 * 60)
+  );
+  const avgHoldMin = mean(holdDurationsMinutes);
+
+  const equitySeries =
+    eqSeries && eqSeries.length
+      ? eqSeries
+      : buildEquitySeriesFromLegs({ legs, equityStart });
+  const dailyReturnsSeries = dailyReturns(equitySeries);
+  const dailyStd = stddev(dailyReturnsSeries);
+  const sharpeDaily =
+    dailyStd === 0
+      ? dailyReturnsSeries.length
+        ? Infinity
+        : 0
+      : mean(dailyReturnsSeries) / dailyStd;
+  const sortinoDaily = sortino(dailyReturnsSeries);
+  const dailyWinRate = dailyReturnsSeries.length
+    ? dailyReturnsSeries.filter((value) => value > 0).length / dailyReturnsSeries.length
+    : 0;
+
+  const longTrades = completedTrades.filter((trade) => trade.side === "long");
+  const shortTrades = completedTrades.filter((trade) => trade.side === "short");
+  const longRs = longTrades.map(tradeRMultiple);
+  const shortRs = shortTrades.map(tradeRMultiple);
+  const longPnls = longTrades.map((trade) => trade.exit.pnl);
+  const shortPnls = shortTrades.map((trade) => trade.exit.pnl);
+
+  const rDistribution = {
+    p10: percentile(tradeRs, 0.1),
+    p25: percentile(tradeRs, 0.25),
+    p50: percentile(tradeRs, 0.5),
+    p75: percentile(tradeRs, 0.75),
+    p90: percentile(tradeRs, 0.9),
+  };
+
+  const holdDistribution = {
+    p10: percentile(holdDurationsMinutes, 0.1),
+    p25: percentile(holdDurationsMinutes, 0.25),
+    p50: percentile(holdDurationsMinutes, 0.5),
+    p75: percentile(holdDurationsMinutes, 0.75),
+    p90: percentile(holdDurationsMinutes, 0.9),
+  };
+
+  return {
+    trades: completedTrades.length,
+    winRate: completedTrades.length ? winningTrades.length / completedTrades.length : 0,
+    profitFactor: profitFactorPositions,
+    expectancy,
+    totalR,
+    avgR,
+    sharpePerTrade,
+    sortinoPerTrade,
+    maxDrawdownPct: maxDrawdown,
+    calmar,
+    maxConsecWins: maxWin,
+    maxConsecLosses: maxLoss,
+    avgHoldMin,
+    exposurePct,
+    totalPnL: realizedPnL,
+    returnPct,
+    finalEquity: equityFinal,
+    startEquity: equityStart,
+    profitFactor_pos: profitFactorPositions,
+    profitFactor_leg: profitFactorLegs,
+    winRate_pos: completedTrades.length
+      ? winningTrades.length / completedTrades.length
+      : 0,
+    winRate_leg: legs.length ? winningLegs.length / legs.length : 0,
+    sharpeDaily,
+    sortinoDaily,
+    long: {
+      trades: longTrades.length,
+      winRate: longTrades.length
+        ? longTrades.filter((trade) => trade.exit.pnl > 0).length / longTrades.length
+        : 0,
+      avgPnL: mean(longPnls),
+      avgR: mean(longRs),
+    },
+    short: {
+      trades: shortTrades.length,
+      winRate: shortTrades.length
+        ? shortTrades.filter((trade) => trade.exit.pnl > 0).length / shortTrades.length
+        : 0,
+      avgPnL: mean(shortPnls),
+      avgR: mean(shortRs),
+    },
+    rDist: rDistribution,
+    holdDistMin: holdDistribution,
+    daily: {
+      count: dailyReturnsSeries.length,
+      winRate: dailyWinRate,
+      avgReturn: mean(dailyReturnsSeries),
+    },
+  };
+}

package/src/reporting/exportBacktestArtifacts.js

@@ -0,0 +1,53 @@
+import { exportHtmlReport } from "./renderHtmlReport.js";
+import { exportTradesCsv } from "./exportTradesCsv.js";
+
+export function exportBacktestArtifacts({
+  result,
+  symbol = result?.symbol,
+  interval = result?.interval ?? "tf",
+  range = result?.range ?? "range",
+  outDir = "output",
+  exportCsv = true,
+  exportHtml = true,
+  csvSource = "positions",
+  plotlyCdnUrl,
+} = {}) {
+  if (!result) {
+    throw new Error("exportBacktestArtifacts() requires a backtest result");
+  }
+
+  const outputs = {
+    csv: null,
+    html: null,
+  };
+
+  const csvTrades =
+    csvSource === "trades"
+      ? result.trades
+      : result.positions ?? result.trades;
+
+  if (exportCsv) {
+    outputs.csv = exportTradesCsv(csvTrades, {
+      symbol,
+      interval,
+      range,
+      outDir,
+    });
+  }
+
+  if (exportHtml) {
+    outputs.html = exportHtmlReport({
+      symbol,
+      interval,
+      range,
+      metrics: result.metrics,
+      eqSeries: result.eqSeries,
+      replay: result.replay,
+      positions: result.positions ?? [],
+      outDir,
+      plotlyCdnUrl,
+    });
+  }
+
+  return outputs;
+}

package/src/reporting/exportTradesCsv.js

@@ -0,0 +1,73 @@
+import fs from "fs";
+import path from "path";
+
+function safeSegment(value) {
+  return String(value).replace(/[^-_.A-Za-z0-9]/g, "_");
+}
+
+function tradeRMultiple(trade) {
+  const initialRisk = trade._initRisk || 0;
+  if (initialRisk <= 0) return 0;
+  const entry = trade.entryFill ?? trade.entry;
+  const perUnit =
+    trade.side === "long"
+      ? trade.exit.price - entry
+      : entry - trade.exit.price;
+  return perUnit / initialRisk;
+}
+
+export function exportTradesCsv(
+  closedTrades,
+  { symbol = "UNKNOWN", interval = "tf", range = "range", outDir = "output" } = {}
+) {
+  if (!closedTrades?.length) return null;
+
+  const rows = [
+    [
+      "time_open",
+      "time_close",
+      "side",
+      "entry",
+      "stop",
+      "takeProfit",
+      "exit",
+      "reason",
+      "size",
+      "pnl",
+      "R",
+      "mfeR",
+      "maeR",
+      "adds",
+      "entryATR",
+      "exitATR",
+    ].join(","),
+    ...closedTrades.map((trade) =>
+      [
+        new Date(trade.openTime).toISOString(),
+        new Date(trade.exit.time).toISOString(),
+        trade.side,
+        Number(trade.entry).toFixed(6),
+        Number(trade.stop).toFixed(6),
+        Number(trade.takeProfit).toFixed(6),
+        Number(trade.exit.price).toFixed(6),
+        trade.exit.reason,
+        trade.size,
+        trade.exit.pnl.toFixed(2),
+        tradeRMultiple(trade).toFixed(3),
+        (trade.mfeR ?? 0).toFixed(3),
+        (trade.maeR ?? 0).toFixed(3),
+        trade.adds ?? 0,
+        trade.entryATR !== undefined ? Number(trade.entryATR).toFixed(6) : "",
+        trade.exit.exitATR !== undefined
+          ? Number(trade.exit.exitATR).toFixed(6)
+          : "",
+      ].join(",")
+    ),
+  ].join("\n");
+
+  fs.mkdirSync(outDir, { recursive: true });
+  const filename = `trades-${safeSegment(symbol)}-${safeSegment(interval)}-${safeSegment(range)}.csv`;
+  const outputPath = path.join(outDir, filename);
+  fs.writeFileSync(outputPath, rows, "utf8");
+  return outputPath;
+}