tradelab 0.1.0

package/src/reporting/renderHtmlReport.js

@@ -0,0 +1,310 @@
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const packageRoot = path.join(__dirname, "..", "..");
+const templateCache = new Map();
+
+function readTemplate(relativePath) {
+  const absolutePath = path.join(packageRoot, relativePath);
+  if (!templateCache.has(absolutePath)) {
+    templateCache.set(absolutePath, fs.readFileSync(absolutePath, "utf8"));
+  }
+  return templateCache.get(absolutePath);
+}
+
+function fmt(value, digits = 2) {
+  if (value === undefined || value === null || Number.isNaN(value)) return "—";
+  if (!Number.isFinite(value)) return value > 0 ? "Inf" : "0";
+  return Number(value).toFixed(digits);
+}
+
+function fmtPct(value, digits = 2) {
+  if (value === undefined || value === null || Number.isNaN(value)) return "—";
+  if (!Number.isFinite(value)) return value > 0 ? "Inf" : "0";
+  return `${(Number(value) * 100).toFixed(digits)}%`;
+}
+
+function escapeHtml(value) {
+  return String(value)
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+function serializeJson(value) {
+  return JSON.stringify(value)
+    .replace(/</g, "\\u003c")
+    .replace(/<\/script/gi, "<\\\\/script");
+}
+
+function renderTemplate(template, replacements) {
+  return template.replace(/\{\{([A-Z0-9_]+)\}\}/g, (_, key) => replacements[key] ?? "");
+}
+
+function metricCards(metrics) {
+  const cards = [
+    {
+      label: "Net Return",
+      value: fmtPct(metrics.returnPct ?? 0, 2),
+      note: `PnL ${fmt(metrics.totalPnL ?? 0, 2)}`,
+    },
+    {
+      label: "Win Rate",
+      value: fmtPct(metrics.winRate ?? 0, 1),
+      note: `${metrics.trades ?? 0} completed positions`,
+    },
+    {
+      label: "Profit Factor",
+      value: fmt(metrics.profitFactor ?? 0, 2),
+      note: `Avg R ${fmt(metrics.avgR ?? 0, 2)}`,
+    },
+    {
+      label: "Drawdown",
+      value: fmtPct(metrics.maxDrawdownPct ?? 0, 2),
+      note: `Calmar ${fmt(metrics.calmar ?? 0, 2)}`,
+    },
+  ];
+
+  return cards
+    .map(
+      (card) => `
+        <article class="metric-card">
+          <div class="metric-card__label">${escapeHtml(card.label)}</div>
+          <div class="metric-card__value">${escapeHtml(card.value)}</div>
+          <div class="metric-card__note">${escapeHtml(card.note)}</div>
+        </article>
+      `
+    )
+    .join("");
+}
+
+function renderRows(rows, { empty = "No data available", colSpan = 2 } = {}) {
+  if (!rows.length) {
+    return `<tr><td class="table-empty" colspan="${colSpan}">${escapeHtml(empty)}</td></tr>`;
+  }
+
+  return rows
+    .map(
+      ([label, value]) => `
+        <tr>
+          <th>${escapeHtml(label)}</th>
+          <td>${escapeHtml(value)}</td>
+        </tr>
+      `
+    )
+    .join("");
+}
+
+function renderPositionRows(positions) {
+  if (!positions?.length) {
+    return '<tr><td class="table-empty" colspan="7">No completed positions</td></tr>';
+  }
+
+  return positions
+    .slice(-25)
+    .reverse()
+    .map((trade) => {
+      const exit = trade.exit || {};
+      return `
+        <tr>
+          <td>${escapeHtml(new Date(trade.openTime).toISOString())}</td>
+          <td>${escapeHtml(trade.side)}</td>
+          <td>${escapeHtml(fmt(trade.entryFill ?? trade.entry, 4))}</td>
+          <td>${escapeHtml(fmt(exit.price, 4))}</td>
+          <td>${escapeHtml(exit.reason ?? "—")}</td>
+          <td>${escapeHtml(fmt(exit.pnl, 2))}</td>
+          <td>${escapeHtml(fmt(trade.mfeR ?? 0, 2))} / ${escapeHtml(
+            fmt(trade.maeR ?? 0, 2)
+          )}</td>
+        </tr>
+      `;
+    })
+    .join("");
+}
+
+function buildDailyPnl(eqSeries) {
+  if (!eqSeries?.length) return [];
+
+  const byDay = new Map();
+  for (const point of eqSeries) {
+    const date = new Date(point.time).toISOString().slice(0, 10);
+    const record = byDay.get(date) || {
+      date,
+      open: point.equity,
+      close: point.equity,
+      firstTime: point.time,
+      lastTime: point.time,
+    };
+
+    if (point.time < record.firstTime) {
+      record.firstTime = point.time;
+      record.open = point.equity;
+    }
+
+    if (point.time >= record.lastTime) {
+      record.lastTime = point.time;
+      record.close = point.equity;
+    }
+
+    byDay.set(date, record);
+  }
+
+  return [...byDay.values()]
+    .sort((left, right) => left.date.localeCompare(right.date))
+    .map((record) => ({
+      date: record.date,
+      pnl: record.close - record.open,
+    }));
+}
+
+function buildReportPayload({ eqSeries, replay }) {
+  const normalizedEqSeries = eqSeries.map((point) => ({
+    t: new Date(point.time).toISOString(),
+    equity: point.equity,
+  }));
+
+  let peak = normalizedEqSeries[0]?.equity ?? 0;
+  const drawdown = normalizedEqSeries.map((point) => {
+    peak = Math.max(peak, point.equity);
+    return {
+      t: point.t,
+      value: peak > 0 ? (point.equity - peak) / peak : 0,
+    };
+  });
+
+  const normalizedReplay = {
+    frames: Array.isArray(replay?.frames) ? replay.frames : [],
+    events: Array.isArray(replay?.events) ? replay.events : [],
+  };
+
+  return {
+    eqSeries: normalizedEqSeries,
+    drawdown,
+    dailyPnl: buildDailyPnl(eqSeries),
+    replay: normalizedReplay,
+    hasReplay: normalizedReplay.frames.length > 0,
+  };
+}
+
+export function renderHtmlReport({
+  symbol,
+  interval,
+  range,
+  metrics,
+  eqSeries,
+  replay,
+  positions = [],
+  plotlyCdnUrl = "https://cdn.plot.ly/plotly-2.35.2.min.js",
+}) {
+  if (!eqSeries?.length) {
+    throw new Error("renderHtmlReport() requires a populated eqSeries array");
+  }
+
+  const template = readTemplate("templates/report.html");
+  const css = readTemplate("templates/report.css");
+  const clientJs = readTemplate("templates/report.js");
+
+  const title = `${symbol} ${interval} (${range})`;
+  const payload = buildReportPayload({ eqSeries, replay });
+  const summaryRows = renderRows([
+    ["Trades", String(metrics.trades ?? 0)],
+    ["Win rate", fmtPct(metrics.winRate ?? 0, 1)],
+    ["Profit factor", fmt(metrics.profitFactor ?? 0, 2)],
+    ["Expectancy / trade", fmt(metrics.expectancy ?? 0, 2)],
+    ["Total R", fmt(metrics.totalR ?? 0, 2)],
+    ["Avg R / trade", fmt(metrics.avgR ?? 0, 2)],
+    ["Max drawdown", fmtPct(metrics.maxDrawdownPct ?? 0, 2)],
+    ["Exposure", fmtPct(metrics.exposurePct ?? 0, 1)],
+    ["Avg hold (min)", fmt(metrics.avgHoldMin ?? 0, 1)],
+    ["Daily Sharpe", fmt(metrics.sharpeDaily ?? 0, 2)],
+  ]);
+
+  const breakdownRows = renderRows([
+    [
+      "Long",
+      `${metrics.long?.trades ?? 0} trades, ${fmtPct(
+        metrics.long?.winRate ?? 0,
+        1
+      )} win, avg R ${fmt(metrics.long?.avgR ?? 0, 2)}`,
+    ],
+    [
+      "Short",
+      `${metrics.short?.trades ?? 0} trades, ${fmtPct(
+        metrics.short?.winRate ?? 0,
+        1
+      )} win, avg R ${fmt(metrics.short?.avgR ?? 0, 2)}`,
+    ],
+    ["R p50 / p90", `${fmt(metrics.rDist?.p50 ?? 0, 2)} / ${fmt(metrics.rDist?.p90 ?? 0, 2)}`],
+    [
+      "Hold p50 / p90",
+      `${fmt(metrics.holdDistMin?.p50 ?? 0, 1)} / ${fmt(
+        metrics.holdDistMin?.p90 ?? 0,
+        1
+      )} min`,
+    ],
+  ]);
+
+  return renderTemplate(template, {
+    TITLE: escapeHtml(title),
+    CSS: css,
+    REPORT_JS: clientJs,
+    PLOTLY_CDN_URL: escapeHtml(plotlyCdnUrl),
+    HERO_SUBTITLE: escapeHtml(
+      `Start ${fmt(metrics.startEquity ?? 0, 2)} • End ${fmt(metrics.finalEquity ?? 0, 2)}`
+    ),
+    HERO_PILL: escapeHtml(
+      `Return ${fmtPct(metrics.returnPct ?? 0, 2)} • Max DD ${fmtPct(
+        metrics.maxDrawdownPct ?? 0,
+        2
+      )}`
+    ),
+    METRIC_CARDS: metricCards(metrics),
+    SUMMARY_ROWS: summaryRows,
+    BREAKDOWN_ROWS: breakdownRows,
+    POSITION_ROWS: renderPositionRows(positions),
+    REPLAY_VISIBILITY: payload.hasReplay ? "" : "is-hidden",
+    REPORT_DATA_JSON: serializeJson(payload),
+  });
+}
+
+export function exportHtmlReport({
+  symbol,
+  interval,
+  range,
+  metrics,
+  eqSeries,
+  replay,
+  positions,
+  outDir = "output",
+  plotlyCdnUrl,
+}) {
+  if (!eqSeries?.length) return null;
+
+  fs.mkdirSync(outDir, { recursive: true });
+  const safeSymbol = String(symbol).replace(/[^a-zA-Z0-9_.-]+/g, "_");
+  const safeInterval = String(interval).replace(/[^a-zA-Z0-9_.-]+/g, "_");
+  const safeRange = String(range).replace(/[^a-zA-Z0-9_.-]+/g, "_");
+  const outputPath = path.join(
+    outDir,
+    `report-${safeSymbol}-${safeInterval}-${safeRange}.html`
+  );
+
+  const html = renderHtmlReport({
+    symbol,
+    interval,
+    range,
+    metrics,
+    eqSeries,
+    replay,
+    positions,
+    plotlyCdnUrl,
+  });
+
+  fs.writeFileSync(outputPath, html, "utf8");
+  return outputPath;
+}

package/src/utils/indicators.js

@@ -0,0 +1,138 @@
+export function ema(values, period = 14) {
+  if (!values?.length) return [];
+
+  const lookback = Math.max(1, period | 0);
+  const output = new Array(values.length);
+  let warmupSum = 0;
+
+  for (let index = 0; index < values.length; index += 1) {
+    const value = values[index];
+
+    if (!Number.isFinite(value)) {
+      output[index] = index === 0 ? 0 : output[index - 1];
+      continue;
+    }
+
+    if (index < lookback) {
+      warmupSum += value;
+      output[index] = index === lookback - 1 ? warmupSum / lookback : value;
+      continue;
+    }
+
+    const smoothing = 2 / (lookback + 1);
+    output[index] = value * smoothing + output[index - 1] * (1 - smoothing);
+  }
+
+  return output;
+}
+
+export function swingHigh(bars, index, left = 2, right = 2) {
+  if (index < left || index + right >= bars.length) return false;
+  const high = bars[index].high;
+  for (let cursor = index - left; cursor <= index + right; cursor += 1) {
+    if (cursor !== index && bars[cursor].high >= high) return false;
+  }
+  return true;
+}
+
+export function swingLow(bars, index, left = 2, right = 2) {
+  if (index < left || index + right >= bars.length) return false;
+  const low = bars[index].low;
+  for (let cursor = index - left; cursor <= index + right; cursor += 1) {
+    if (cursor !== index && bars[cursor].low <= low) return false;
+  }
+  return true;
+}
+
+export function detectFVG(bars, index) {
+  if (index < 2) return null;
+  const first = bars[index - 2];
+  const third = bars[index];
+
+  if (first.high < third.low) {
+    return {
+      type: "bull",
+      top: first.high,
+      bottom: third.low,
+      mid: (first.high + third.low) / 2,
+    };
+  }
+
+  if (first.low > third.high) {
+    return {
+      type: "bear",
+      top: third.high,
+      bottom: first.low,
+      mid: (third.high + first.low) / 2,
+    };
+  }
+
+  return null;
+}
+
+export function lastSwing(bars, index, direction) {
+  for (let cursor = index - 1; cursor >= 0; cursor -= 1) {
+    if (direction === "up" && swingLow(bars, cursor)) {
+      return { idx: cursor, price: bars[cursor].low };
+    }
+    if (direction === "down" && swingHigh(bars, cursor)) {
+      return { idx: cursor, price: bars[cursor].high };
+    }
+  }
+  return null;
+}
+
+export function structureState(bars, index) {
+  return {
+    lastLow: lastSwing(bars, index, "up"),
+    lastHigh: lastSwing(bars, index, "down"),
+  };
+}
+
+export function atr(bars, period = 14) {
+  if (!bars?.length || period <= 0) return [];
+
+  const trueRanges = new Array(bars.length);
+  for (let index = 0; index < bars.length; index += 1) {
+    if (index === 0) {
+      trueRanges[index] = bars[index].high - bars[index].low;
+      continue;
+    }
+
+    const high = bars[index].high;
+    const low = bars[index].low;
+    const previousClose = bars[index - 1].close;
+    trueRanges[index] = Math.max(
+      high - low,
+      Math.abs(high - previousClose),
+      Math.abs(low - previousClose)
+    );
+  }
+
+  const output = new Array(trueRanges.length);
+  let previousAtr;
+
+  for (let index = 0; index < trueRanges.length; index += 1) {
+    if (index < period) {
+      output[index] = undefined;
+      if (index === period - 1) {
+        let seed = 0;
+        for (let cursor = 0; cursor < period; cursor += 1) {
+          seed += trueRanges[cursor];
+        }
+        previousAtr = seed / period;
+        output[index] = previousAtr;
+      }
+      continue;
+    }
+
+    previousAtr =
+      (previousAtr * (period - 1) + trueRanges[index]) / period;
+    output[index] = previousAtr;
+  }
+
+  return output;
+}
+
+export const bpsOf = (price, bps) => price * (bps / 10000);
+export const pct = (a, b) => (a - b) / b;

package/src/utils/positionSizing.js

@@ -0,0 +1,26 @@
+function roundStep(value, step) {
+  return Math.floor(value / step) * step;
+}
+
+export function calculatePositionSize({
+  equity,
+  entry,
+  stop,
+  riskFraction = 0.01,
+  qtyStep = 0.001,
+  minQty = 0.001,
+  maxLeverage = 2,
+}) {
+  const riskPerUnit = Math.abs(entry - stop);
+  if (!Number.isFinite(riskPerUnit) || riskPerUnit <= 0) return 0;
+
+  const maxRiskDollars = Math.max(0, equity * riskFraction);
+  let quantity = maxRiskDollars / riskPerUnit;
+
+  const leverageCapQty =
+    (equity * maxLeverage) / Math.max(1e-12, Math.abs(entry));
+  quantity = Math.min(quantity, leverageCapQty);
+  quantity = roundStep(quantity, qtyStep);
+
+  return quantity >= minQty ? quantity : 0;
+}

package/src/utils/time.js

@@ -0,0 +1,92 @@
+function usDstBoundsUTC(year) {
+  let marchCursor = new Date(Date.UTC(year, 2, 1, 7, 0, 0));
+  let sundaysSeen = 0;
+
+  while (marchCursor.getUTCMonth() === 2) {
+    if (marchCursor.getUTCDay() === 0) sundaysSeen += 1;
+    if (sundaysSeen === 2) break;
+    marchCursor = new Date(marchCursor.getTime() + 24 * 60 * 60 * 1000);
+  }
+
+  const dstStart = new Date(
+    Date.UTC(year, 2, marchCursor.getUTCDate(), 7, 0, 0)
+  );
+
+  let novemberCursor = new Date(Date.UTC(year, 10, 1, 6, 0, 0));
+  while (novemberCursor.getUTCDay() !== 0) {
+    novemberCursor = new Date(
+      novemberCursor.getTime() + 24 * 60 * 60 * 1000
+    );
+  }
+
+  const dstEnd = new Date(
+    Date.UTC(year, 10, novemberCursor.getUTCDate(), 6, 0, 0)
+  );
+
+  return { dstStart, dstEnd };
+}
+
+function isUsEasternDST(timeMs) {
+  const date = new Date(timeMs);
+  const { dstStart, dstEnd } = usDstBoundsUTC(date.getUTCFullYear());
+  return date >= dstStart && date < dstEnd;
+}
+
+export function offsetET(timeMs) {
+  return isUsEasternDST(timeMs) ? 4 : 5;
+}
+
+export function minutesET(timeMs) {
+  const date = new Date(timeMs);
+  const offset = offsetET(timeMs);
+  return ((date.getUTCHours() - offset + 24) % 24) * 60 + date.getUTCMinutes();
+}
+
+export function isSession(timeMs, session = "NYSE") {
+  const day = new Date(timeMs).getUTCDay();
+  if (day === 0 || day === 6) {
+    if (session === "FUT") {
+      const minutes = minutesET(timeMs);
+      return minutes >= 18 * 60 || minutes < 17 * 60;
+    }
+    return false;
+  }
+
+  const minutes = minutesET(timeMs);
+  if (session === "AUTO") return true;
+
+  if (session === "FUT") {
+    const maintenanceStart = 17 * 60;
+    const maintenanceEnd = 18 * 60;
+    return !(
+      minutes >= maintenanceStart && minutes < maintenanceEnd
+    );
+  }
+
+  const open = 9 * 60 + 30;
+  const close = 16 * 60;
+  return minutes >= open && minutes <= close;
+}
+
+export function parseWindowsCSV(csv) {
+  if (!csv) return null;
+  return csv
+    .split(",")
+    .map((token) => token.trim())
+    .filter(Boolean)
+    .map((windowText) => {
+      const [start, end] = windowText.split("-").map((value) => value.trim());
+      const [startHour, startMinute] = start.split(":").map(Number);
+      const [endHour, endMinute] = end.split(":").map(Number);
+      return {
+        aMin: startHour * 60 + startMinute,
+        bMin: endHour * 60 + endMinute,
+      };
+    });
+}
+
+export function inWindowsET(timeMs, windows) {
+  if (!windows?.length) return true;
+  const minutes = minutesET(timeMs);
+  return windows.some((window) => minutes >= window.aMin && minutes <= window.bMin);
+}