tradelab 0.5.0 → 1.0.0

package/src/live/storage/jsonFileStorage.js

@@ -0,0 +1,112 @@
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+import { StorageProvider } from "./interface.js";
+
+function sanitizeNamespace(namespace) {
+  return String(namespace || "default").replace(/[^a-zA-Z0-9._-]/g, "_");
+}
+
+async function ensureDir(dirPath) {
+  await fsp.mkdir(dirPath, { recursive: true });
+}
+
+async function readJsonFile(filePath) {
+  try {
+    const raw = await fsp.readFile(filePath, "utf8");
+    return JSON.parse(raw);
+  } catch (error) {
+    if (error && error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+async function writeJsonAtomic(filePath, payload) {
+  const tmpPath = `${filePath}.${process.pid}.${Date.now()}.${Math.random()
+    .toString(16)
+    .slice(2)}.tmp`;
+  await fsp.writeFile(tmpPath, JSON.stringify(payload, null, 2), "utf8");
+  await fsp.rename(tmpPath, filePath);
+}
+
+async function appendJsonLine(filePath, payload) {
+  await ensureDir(path.dirname(filePath));
+  await fsp.appendFile(filePath, `${JSON.stringify(payload)}\n`, "utf8");
+}
+
+async function readJsonLines(filePath) {
+  try {
+    const raw = await fsp.readFile(filePath, "utf8");
+    return raw
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter(Boolean)
+      .map((line) => JSON.parse(line));
+  } catch (error) {
+    if (error && error.code === "ENOENT") return [];
+    throw error;
+  }
+}
+
+/**
+ * Zero-dependency JSON state storage.
+ */
+export class JsonFileStorage extends StorageProvider {
+  constructor({ baseDir = path.resolve(process.cwd(), "output/live-state") } = {}) {
+    super();
+    this.baseDir = baseDir;
+  }
+
+  namespaceDir(namespace) {
+    return path.join(this.baseDir, sanitizeNamespace(namespace));
+  }
+
+  statePath(namespace) {
+    return path.join(this.namespaceDir(namespace), "state.json");
+  }
+
+  tradesPath(namespace) {
+    return path.join(this.namespaceDir(namespace), "trades.jsonl");
+  }
+
+  equityPath(namespace) {
+    return path.join(this.namespaceDir(namespace), "equity.jsonl");
+  }
+
+  async load(namespace) {
+    return readJsonFile(this.statePath(namespace));
+  }
+
+  async save(namespace, state) {
+    const dir = this.namespaceDir(namespace);
+    await ensureDir(dir);
+    await writeJsonAtomic(this.statePath(namespace), state);
+  }
+
+  async appendTrade(namespace, trade) {
+    await appendJsonLine(this.tradesPath(namespace), trade);
+  }
+
+  async appendEquityPoint(namespace, point) {
+    await appendJsonLine(this.equityPath(namespace), point);
+  }
+
+  async loadTrades(namespace) {
+    return readJsonLines(this.tradesPath(namespace));
+  }
+
+  async loadEquityCurve(namespace) {
+    return readJsonLines(this.equityPath(namespace));
+  }
+
+  async clear(namespace) {
+    const dir = this.namespaceDir(namespace);
+    if (!fs.existsSync(dir)) return;
+    await fsp.rm(dir, { recursive: true, force: true });
+  }
+}
+
+export function createJsonFileStorage(options) {
+  return new JsonFileStorage(options);
+}

package/src/metrics/buildMetrics.js

@@ -16,11 +16,7 @@ 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;
+  return downsideDeviation === 0 ? (avg > 0 ? Infinity : 0) : avg / downsideDeviation;
 }
 
 function dayKeyUTC(timeMs) {
@@ -36,10 +32,7 @@ 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;
+  const perUnit = trade.side === "long" ? trade.exit.price - entry : entry - trade.exit.price;
   return perUnit / initialRisk;
 }
 
@@ -127,6 +120,15 @@ 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 / grossLoss;
+}
+
 /**
  * Build aggregate backtest metrics for completed positions and realized trade legs.
  *
@@ -134,14 +136,7 @@ function percentile(values, percentileRank) {
  * `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 }) {
   const legs = [...closed].sort((left, right) => left.exit.time - right.exit.time);
   const completedTrades = [];
   const tradeRs = [];
@@ -233,18 +228,8 @@ export function buildMetrics({
       : mean(tradeReturns) / tradeReturnStd;
   const sortinoPerTrade = sortino(tradeReturns);
 
-  const profitFactorPositions =
-    grossLossPositions === 0
-      ? grossProfitPositions > 0
-        ? Infinity
-        : 0
-      : grossProfitPositions / grossLossPositions;
-  const profitFactorLegs =
-    grossLossLegs === 0
-      ? grossProfitLegs > 0
-        ? Infinity
-        : 0
-      : grossProfitLegs / grossLossLegs;
+  const profitFactorPositions = finiteProfitFactor(grossProfitPositions, grossLossPositions);
+  const profitFactorLegs = finiteProfitFactor(grossProfitLegs, grossLossLegs);
   const returnPct = (equityFinal - equityStart) / Math.max(1e-12, equityStart);
   const calmar = maxDrawdown === 0 ? (returnPct > 0 ? Infinity : 0) : returnPct / maxDrawdown;
 
@@ -253,9 +238,7 @@ export function buildMetrics({
   const avgHoldMin = mean(holdDurationsMinutes);
 
   const equitySeries =
-    eqSeries && eqSeries.length
-      ? eqSeries
-      : buildEquitySeriesFromLegs({ legs, equityStart });
+    eqSeries && eqSeries.length ? eqSeries : buildEquitySeriesFromLegs({ legs, equityStart });
   const dailyReturnsSeries = dailyReturns(equitySeries);
   const dailyStd = stddev(dailyReturnsSeries);
   const sharpeDaily =
@@ -288,17 +271,13 @@ export function buildMetrics({
   const sideBreakdown = {
     long: {
       trades: longTradesCount,
-      winRate: longTradesCount
-        ? longTradeWins / longTradesCount
-        : 0,
+      winRate: longTradesCount ? longTradeWins / longTradesCount : 0,
       avgPnL: longTradesCount ? longPnLSum / longTradesCount : 0,
       avgR: mean(longRs),
     },
     short: {
       trades: shortTradesCount,
-      winRate: shortTradesCount
-        ? shortTradeWins / shortTradesCount
-        : 0,
+      winRate: shortTradesCount ? shortTradeWins / shortTradesCount : 0,
       avgPnL: shortTradesCount ? shortPnLSum / shortTradesCount : 0,
       avgR: mean(shortRs),
     },
@@ -328,9 +307,7 @@ export function buildMetrics({
     startEquity: equityStart,
     profitFactor_pos: profitFactorPositions,
     profitFactor_leg: profitFactorLegs,
-    winRate_pos: completedTrades.length
-      ? winningTradeCount / completedTrades.length
-      : 0,
+    winRate_pos: completedTrades.length ? winningTradeCount / completedTrades.length : 0,
     winRate_leg: legs.length ? winningLegCount / legs.length : 0,
     sharpeDaily,
     sortinoDaily,

package/src/reporting/exportBacktestArtifacts.js

@@ -24,10 +24,7 @@ export function exportBacktestArtifacts({
     metrics: null,
   };
 
-  const csvTrades =
-    csvSource === "trades"
-      ? result.trades
-      : result.positions ?? result.trades;
+  const csvTrades = csvSource === "trades" ? result.trades : (result.positions ?? result.trades);
 
   if (exportCsv) {
     outputs.csv = exportTradesCsv(csvTrades, {

package/src/reporting/exportTradesCsv.js

@@ -9,10 +9,7 @@ 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;
+  const perUnit = trade.side === "long" ? trade.exit.price - entry : entry - trade.exit.price;
   return perUnit / initialRisk;
 }
 
@@ -58,9 +55,7 @@ export function exportTradesCsv(
         (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)
-          : "",
+        trade.exit.exitATR !== undefined ? Number(trade.exit.exitATR).toFixed(6) : "",
       ].join(",")
     ),
   ].join("\n");

package/src/reporting/renderHtmlReport.js

@@ -19,7 +19,8 @@ function candidateRoots() {
 }
 
 function readTemplate(relativePath) {
-  for (const root of candidateRoots()) {
+  const roots = candidateRoots();
+  for (const root of roots) {
     const absolutePath = path.join(root, relativePath);
     if (!fs.existsSync(absolutePath)) continue;
 
@@ -29,7 +30,9 @@ function readTemplate(relativePath) {
     return templateCache.get(absolutePath);
   }
 
-  throw new Error(`Could not locate template asset: ${relativePath}`);
+  throw new Error(
+    `Could not locate template asset: ${relativePath} (searched ${roots.length} roots starting from ${roots[0]})`
+  );
 }
 
 function fmt(value, digits = 2) {
@@ -135,9 +138,7 @@ function renderPositionRows(positions) {
           <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>
+          <td>${escapeHtml(fmt(trade.mfeR ?? 0, 2))} / ${escapeHtml(fmt(trade.maeR ?? 0, 2))}</td>
         </tr>
       `;
     })
@@ -259,10 +260,7 @@ export function renderHtmlReport({
     ["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`,
+      `${fmt(metrics.holdDistMin?.p50 ?? 0, 1)} / ${fmt(metrics.holdDistMin?.p90 ?? 0, 1)} min`,
     ],
   ]);
 
@@ -306,10 +304,7 @@ export function exportHtmlReport({
   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 outputPath = path.join(outDir, `report-${safeSymbol}-${safeInterval}-${safeRange}.html`);
 
   const html = renderHtmlReport({
     symbol,

package/src/utils/indicators.js

@@ -126,8 +126,7 @@ export function atr(bars, period = 14) {
       continue;
     }
 
-    previousAtr =
-      (previousAtr * (period - 1) + trueRanges[index]) / period;
+    previousAtr = (previousAtr * (period - 1) + trueRanges[index]) / period;
     output[index] = previousAtr;
   }
 

package/src/utils/positionSizing.js

@@ -2,6 +2,16 @@ function roundStep(value, step) {
   return Math.floor(value / step) * step;
 }
 
+let warnedNonPositiveEquity = false;
+
+function warnNonPositiveEquity(equity) {
+  if (warnedNonPositiveEquity) return;
+  warnedNonPositiveEquity = true;
+  console.warn(
+    `[tradelab] calculatePositionSize() received non-positive equity (${equity}); returning size 0`
+  );
+}
+
 export function calculatePositionSize({
   equity,
   entry,
@@ -11,14 +21,18 @@ export function calculatePositionSize({
   minQty = 0.001,
   maxLeverage = 2,
 }) {
+  if (!Number.isFinite(equity) || equity <= 0) {
+    warnNonPositiveEquity(equity);
+    return 0;
+  }
+
   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));
+  const leverageCapQty = (equity * maxLeverage) / Math.max(1e-12, Math.abs(entry));
   quantity = Math.min(quantity, leverageCapQty);
   quantity = roundStep(quantity, qtyStep);
 

package/src/utils/time.js

@@ -8,20 +8,14 @@ function usDstBoundsUTC(year) {
     marchCursor = new Date(marchCursor.getTime() + 24 * 60 * 60 * 1000);
   }
 
-  const dstStart = new Date(
-    Date.UTC(year, 2, marchCursor.getUTCDate(), 7, 0, 0)
-  );
+  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
-    );
+    novemberCursor = new Date(novemberCursor.getTime() + 24 * 60 * 60 * 1000);
   }
 
-  const dstEnd = new Date(
-    Date.UTC(year, 10, novemberCursor.getUTCDate(), 6, 0, 0)
-  );
+  const dstEnd = new Date(Date.UTC(year, 10, novemberCursor.getUTCDate(), 6, 0, 0));
 
   return { dstStart, dstEnd };
 }
@@ -58,9 +52,7 @@ export function isSession(timeMs, session = "NYSE") {
   if (session === "FUT") {
     const maintenanceStart = 17 * 60;
     const maintenanceEnd = 18 * 60;
-    return !(
-      minutes >= maintenanceStart && minutes < maintenanceEnd
-    );
+    return !(minutes >= maintenanceStart && minutes < maintenanceEnd);
   }
 
   const open = 9 * 60 + 30;

package/templates/report.html

@@ -4,7 +4,9 @@
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>{{TITLE}} backtest</title>
-    <style>{{CSS}}</style>
+    <style>
+      {{CSS}}
+    </style>
   </head>
   <body>
     <main class="report-shell">
@@ -17,9 +19,7 @@
         <div class="hero-pill">{{HERO_PILL}}</div>
       </header>
 
-      <section class="metric-grid">
-        {{METRIC_CARDS}}
-      </section>
+      <section class="metric-grid">{{METRIC_CARDS}}</section>
 
       <section class="panel-grid">
         <article class="panel panel--wide">
@@ -36,7 +36,9 @@
             <p>Headline stats for completed positions.</p>
           </div>
           <table class="data-table">
-            <tbody>{{SUMMARY_ROWS}}</tbody>
+            <tbody>
+              {{SUMMARY_ROWS}}
+            </tbody>
           </table>
         </article>
 
@@ -70,7 +72,9 @@
             <p>Long/short split and distribution snapshots.</p>
           </div>
           <table class="data-table">
-            <tbody>{{BREAKDOWN_ROWS}}</tbody>
+            <tbody>
+              {{BREAKDOWN_ROWS}}
+            </tbody>
           </table>
         </article>
 
@@ -92,15 +96,25 @@
                   <th>MFE / MAE</th>
                 </tr>
               </thead>
-              <tbody>{{POSITION_ROWS}}</tbody>
+              <tbody>
+                {{POSITION_ROWS}}
+              </tbody>
             </table>
           </div>
         </article>
       </section>
     </main>
 
-    <script id="report-data" type="application/json">{{REPORT_DATA_JSON}}</script>
+    <script id="report-data" type="application/json">
+      {{REPORT_DATA_JSON}}
+    </script>
     <script src="{{PLOTLY_CDN_URL}}"></script>
-    <script>{{REPORT_JS}}</script>
+    <script>
+      {
+        {
+          REPORT_JS;
+        }
+      }
+    </script>
   </body>
 </html>

package/templates/report.js

@@ -34,87 +34,101 @@
     );
   }
 
-  plot("equity-chart", [
+  plot(
+    "equity-chart",
+    [
+      {
+        x: data.eqSeries.map((point) => point.t),
+        y: data.eqSeries.map((point) => point.equity),
+        type: "scatter",
+        mode: "lines",
+        name: "Equity",
+        line: { color: "#64e0c1", width: 2.5 },
+      },
+    ],
     {
-      x: data.eqSeries.map((point) => point.t),
-      y: data.eqSeries.map((point) => point.equity),
-      type: "scatter",
-      mode: "lines",
-      name: "Equity",
-      line: { color: "#64e0c1", width: 2.5 },
-    },
-  ], {
-    yaxis: { title: "Equity", gridcolor: "rgba(159,176,201,0.12)" },
-  });
+      yaxis: { title: "Equity", gridcolor: "rgba(159,176,201,0.12)" },
+    }
+  );
 
-  plot("drawdown-chart", [
+  plot(
+    "drawdown-chart",
+    [
+      {
+        x: data.drawdown.map((point) => point.t),
+        y: data.drawdown.map((point) => point.value),
+        type: "scatter",
+        mode: "lines",
+        name: "Drawdown",
+        line: { color: "#fb7185", width: 2.2 },
+        fill: "tozeroy",
+        fillcolor: "rgba(251,113,133,0.12)",
+      },
+    ],
     {
-      x: data.drawdown.map((point) => point.t),
-      y: data.drawdown.map((point) => point.value),
-      type: "scatter",
-      mode: "lines",
-      name: "Drawdown",
-      line: { color: "#fb7185", width: 2.2 },
-      fill: "tozeroy",
-      fillcolor: "rgba(251,113,133,0.12)",
-    },
-  ], {
-    yaxis: {
-      title: "Drawdown",
-      tickformat: ",.0%",
-      gridcolor: "rgba(159,176,201,0.12)",
-    },
-  });
+      yaxis: {
+        title: "Drawdown",
+        tickformat: ",.0%",
+        gridcolor: "rgba(159,176,201,0.12)",
+      },
+    }
+  );
 
   if (Array.isArray(data.dailyPnl) && data.dailyPnl.length) {
-    plot("daily-chart", [
-      {
-        x: data.dailyPnl.map((point) => point.date),
-        y: data.dailyPnl.map((point) => point.pnl),
-        type: "bar",
-        name: "Daily PnL",
-        marker: {
-          color: data.dailyPnl.map((point) =>
-            point.pnl >= 0 ? "#4ade80" : "#fb7185"
-          ),
+    plot(
+      "daily-chart",
+      [
+        {
+          x: data.dailyPnl.map((point) => point.date),
+          y: data.dailyPnl.map((point) => point.pnl),
+          type: "bar",
+          name: "Daily PnL",
+          marker: {
+            color: data.dailyPnl.map((point) => (point.pnl >= 0 ? "#4ade80" : "#fb7185")),
+          },
         },
-      },
-    ], {
-      yaxis: { title: "PnL", gridcolor: "rgba(159,176,201,0.12)" },
-    });
+      ],
+      {
+        yaxis: { title: "PnL", gridcolor: "rgba(159,176,201,0.12)" },
+      }
+    );
   }
 
   if (data.hasReplay && Array.isArray(data.replay.frames)) {
     const entries = data.replay.events.filter((event) => event.type === "entry");
     const exits = data.replay.events.filter((event) => event.type !== "entry");
 
-    plot("replay-chart", [
-      {
-        x: data.replay.frames.map((frame) => frame.t),
-        y: data.replay.frames.map((frame) => frame.price),
-        type: "scatter",
-        mode: "lines",
-        name: "Price",
-        line: { color: "#93c5fd", width: 2 },
-      },
-      {
-        x: entries.map((event) => event.t),
-        y: entries.map((event) => event.price),
-        type: "scatter",
-        mode: "markers",
-        name: "Entries",
-        marker: { color: "#4ade80", size: 9, symbol: "triangle-up" },
-      },
+    plot(
+      "replay-chart",
+      [
+        {
+          x: data.replay.frames.map((frame) => frame.t),
+          y: data.replay.frames.map((frame) => frame.price),
+          type: "scatter",
+          mode: "lines",
+          name: "Price",
+          line: { color: "#93c5fd", width: 2 },
+        },
+        {
+          x: entries.map((event) => event.t),
+          y: entries.map((event) => event.price),
+          type: "scatter",
+          mode: "markers",
+          name: "Entries",
+          marker: { color: "#4ade80", size: 9, symbol: "triangle-up" },
+        },
+        {
+          x: exits.map((event) => event.t),
+          y: exits.map((event) => event.price),
+          type: "scatter",
+          mode: "markers",
+          name: "Exits",
+          marker: { color: "#fb7185", size: 9, symbol: "triangle-down" },
+        },
+      ],
       {
-        x: exits.map((event) => event.t),
-        y: exits.map((event) => event.price),
-        type: "scatter",
-        mode: "markers",
-        name: "Exits",
-        marker: { color: "#fb7185", size: 9, symbol: "triangle-down" },
-      },
-    ], {
-      yaxis: { title: "Price", gridcolor: "rgba(159,176,201,0.12)" },
-    });
+        yaxis: { title: "Price", gridcolor: "rgba(159,176,201,0.12)" },
+      }
+    );
   }
 })();