tradelab 0.1.2 → 0.3.0

package/package.json

@@ -1,9 +1,14 @@
 {
   "name": "tradelab",
-  "version": "0.1.2",
-  "description": "Reusable trading and backtesting engine for candle-based strategies",
+  "version": "0.3.0",
+  "description": "Backtesting toolkit for Node.js with strategy simulation, historical data loading, and report generation",
   "type": "module",
-  "main": "./src/index.js",
+  "main": "./dist/cjs/index.cjs",
+  "module": "./src/index.js",
+  "types": "./types/index.d.ts",
+  "bin": {
+    "tradelab": "./bin/tradelab.js"
+  },
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -18,18 +23,32 @@
   },
   "sideEffects": false,
   "exports": {
-    ".": "./src/index.js",
-    "./data": "./src/data/index.js",
+    ".": {
+      "types": "./types/index.d.ts",
+      "import": "./src/index.js",
+      "require": "./dist/cjs/index.cjs"
+    },
+    "./data": {
+      "types": "./types/data.d.ts",
+      "import": "./src/data/index.js",
+      "require": "./dist/cjs/data.cjs"
+    },
     "./package.json": "./package.json"
   },
   "files": [
+    "bin",
+    "dist",
     "src",
+    "types",
     "templates",
     "examples/*.js",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
+    "build": "node scripts/build-cjs.mjs",
+    "prepare": "npm run build",
+    "prepack": "npm run build",
     "test": "node --test"
   },
   "keywords": [
@@ -37,9 +56,16 @@
     "backtesting",
     "algorithmic-trading",
     "ohlcv",
-    "quant"
+    "quant",
+    "quantitative-finance",
+    "yahoo-finance",
+    "trading-strategy",
+    "market-data"
   ],
   "publishConfig": {
     "access": "public"
+  },
+  "devDependencies": {
+    "esbuild": "^0.27.3"
   }
 }

package/src/data/yahoo.js

@@ -174,7 +174,16 @@ async function fetchYahooChart(symbol, { period1, period2, interval, includePreP
   return candles;
 }
 
-async function fetchYahooChartWithRetry(symbol, params, maxRetries = 5) {
+function formatYahooFailureMessage(symbol, interval, period, error, attempts) {
+  const detail = String(error?.message || error || "unknown error");
+  return [
+    `Unable to reach Yahoo Finance for ${symbol} ${interval} ${period} after ${attempts} attempts.`,
+    `Last error: ${detail}`,
+    "Try again later, or fall back to a local CSV/cache workflow with getHistoricalCandles({ source: \"csv\", ... }) or loadCandlesFromCache(...).",
+  ].join(" ");
+}
+
+async function fetchYahooChartWithRetry(symbol, params, period, maxRetries = 3) {
   let lastError = null;
 
   for (let attempt = 0; attempt < maxRetries; attempt += 1) {
@@ -188,14 +197,20 @@ async function fetchYahooChartWithRetry(symbol, params, maxRetries = 5) {
 
       if (!isRetryable || attempt === maxRetries - 1) break;
 
-      const delay = isRateLimited
-        ? Math.min(30_000, 2_000 * 2 ** attempt)
-        : Math.min(10_000, 750 * (attempt + 1));
+      const delay = Math.min(12_000, 500 * 2 ** attempt);
       await sleep(delay);
     }
   }
 
-  throw lastError ?? new Error(`Failed to fetch Yahoo data for ${symbol}`);
+  throw new Error(
+    formatYahooFailureMessage(
+      symbol,
+      params.interval,
+      period,
+      lastError,
+      maxRetries
+    )
+  );
 }
 
 export async function fetchHistorical(symbol, interval = "5m", period = "60d", options = {}) {
@@ -207,12 +222,16 @@ export async function fetchHistorical(symbol, interval = "5m", period = "60d", o
   if (spanMs <= maxSpanMs) {
     const endSec = nowSec();
     const startSec = Math.max(0, endSec - msToSec(spanMs));
-    const candles = await fetchYahooChartWithRetry(symbol, {
-      period1: startSec,
-      period2: endSec,
-      interval: normalizedInterval,
-      includePrePost,
-    });
+    const candles = await fetchYahooChartWithRetry(
+      symbol,
+      {
+        period1: startSec,
+        period2: endSec,
+        interval: normalizedInterval,
+        includePrePost,
+      },
+      period
+    );
     return sanitizeBars(candles);
   }
 
@@ -223,12 +242,16 @@ export async function fetchHistorical(symbol, interval = "5m", period = "60d", o
   while (remainingMs > 0) {
     const takeMs = Math.min(remainingMs, maxSpanMs);
     const chunkStartMs = chunkEndMs - takeMs;
-    const candles = await fetchYahooChartWithRetry(symbol, {
-      period1: msToSec(chunkStartMs),
-      period2: msToSec(chunkEndMs),
-      interval: normalizedInterval,
-      includePrePost,
-    });
+    const candles = await fetchYahooChartWithRetry(
+      symbol,
+      {
+        period1: msToSec(chunkStartMs),
+        period2: msToSec(chunkEndMs),
+        interval: normalizedInterval,
+        includePrePost,
+      },
+      period
+    );
     chunks.push(...candles);
     chunkEndMs = chunkStartMs - 1000;
     remainingMs -= takeMs;

package/src/engine/backtest.js

@@ -19,6 +19,29 @@ function asNumber(value) {
   return Number.isFinite(numeric) ? numeric : null;
 }
 
+function equityPoint(time, equity) {
+  return { time, timestamp: time, equity };
+}
+
+function isArrayIndexKey(property) {
+  if (typeof property !== "string") return false;
+  const numeric = Number(property);
+  return Number.isInteger(numeric) && numeric >= 0;
+}
+
+function strictHistoryView(candles, currentIndex) {
+  return new Proxy(candles, {
+    get(target, property, receiver) {
+      if (isArrayIndexKey(property) && Number(property) >= target.length) {
+        throw new Error(
+          `strict mode: signal() tried to access candles[${property}] beyond current index ${currentIndex}`
+        );
+      }
+      return Reflect.get(target, property, receiver);
+    },
+  });
+}
+
 function mergeOptions(options) {
   const normalizedRiskPct = Number.isFinite(options.riskFraction)
     ? options.riskFraction * 100
@@ -35,6 +58,7 @@ function mergeOptions(options) {
     warmupBars: options.warmupBars ?? 200,
     slippageBps: options.slippageBps ?? 1,
     feeBps: options.feeBps ?? 0,
+    costs: options.costs ?? null,
     scaleOutAtR: options.scaleOutAtR ?? 1,
     scaleOutFrac: options.scaleOutFrac ?? 0.5,
     finalTP_R: options.finalTP_R ?? 3,
@@ -88,6 +112,7 @@ function mergeOptions(options) {
     maxSlipROnFill: options.maxSlipROnFill ?? 0.4,
     collectEqSeries: options.collectEqSeries ?? true,
     collectReplay: options.collectReplay ?? true,
+    strict: options.strict ?? false,
   };
 }
 
@@ -135,6 +160,16 @@ function normalizeSignal(signal, bar, fallbackR) {
   };
 }
 
+/**
+ * Run a candle-based backtest.
+ *
+ * Returns raw realized trade legs in `trades`, completed positions in `positions`,
+ * aggregate `metrics`, realized equity points in `eqSeries`, and chart-ready
+ * replay data in `replay`.
+ *
+ * When `strict: true` is enabled, the `candles` array passed to `signal()` throws
+ * if the strategy tries to access bars beyond the current index.
+ */
 export function backtest(rawOptions) {
   const options = mergeOptions(rawOptions || {});
   const {
@@ -145,6 +180,7 @@ export function backtest(rawOptions) {
     signal,
     slippageBps,
     feeBps,
+    costs,
     scaleOutAtR,
     scaleOutFrac,
     finalTP_R,
@@ -168,6 +204,7 @@ export function backtest(rawOptions) {
     collectEqSeries,
     collectReplay,
     warmupBars,
+    strict,
   } = options;
 
   if (!Array.isArray(candles) || candles.length === 0) {
@@ -196,7 +233,7 @@ export function backtest(rawOptions) {
   const needAtr = atrTrailMult > 0 || volScale.enabled;
   const atrValues = needAtr ? atr(candles, atrSourcePeriod) : null;
 
-  const eqSeries = wantEqSeries ? [{ time: candles[0].time, equity: currentEquity }] : [];
+  const eqSeries = wantEqSeries ? [equityPoint(candles[0].time, currentEquity)] : [];
   const replayFrames = wantReplay ? [] : [];
   const replayEvents = wantReplay ? [] : [];
   let tradeIdCounter = 0;
@@ -209,7 +246,7 @@ export function backtest(rawOptions) {
 
   function recordFrame(bar) {
     if (wantEqSeries) {
-      eqSeries.push({ time: bar.time, equity: currentEquity });
+      eqSeries.push(equityPoint(bar.time, currentEquity));
     }
 
     if (wantReplay) {
@@ -223,20 +260,19 @@ export function backtest(rawOptions) {
     }
   }
 
-  function closeLeg({ openPos, qty, exitPx, exitFeePerUnit, time, reason }) {
+  function closeLeg({ openPos, qty, exitPx, exitFeeTotal = 0, time, reason }) {
     const direction = openPos.side === "long" ? 1 : -1;
     const entryFill = openPos.entryFill;
     const grossPnl = (exitPx - entryFill) * direction * qty;
     const entryFeePortion =
       (openPos.entryFeeTotal || 0) * (qty / openPos.initSize);
-    const exitFeeTotal = exitFeePerUnit * qty;
     const pnl = grossPnl - entryFeePortion - exitFeeTotal;
 
     currentEquity += pnl;
     dayPnl += pnl;
 
     if (wantEqSeries) {
-      eqSeries.push({ time, equity: currentEquity });
+      eqSeries.push(equityPoint(time, currentEquity));
     }
 
     const remaining = openPos.size - qty;
@@ -313,17 +349,19 @@ export function backtest(rawOptions) {
     if (!open) return;
 
     const exitSide = open.side === "long" ? "short" : "long";
-    const { price: filled, fee: exitFee } = applyFill(bar.close, exitSide, {
+    const { price: filled, feeTotal: exitFeeTotal } = applyFill(bar.close, exitSide, {
       slippageBps,
       feeBps,
       kind: "market",
+      qty: open.size,
+      costs,
     });
 
     closeLeg({
       openPos: open,
       qty: open.size,
       exitPx: filled,
-      exitFeePerUnit: exitFee,
+      exitFeeTotal,
       time: bar.time,
       reason,
     });
@@ -386,13 +424,15 @@ export function backtest(rawOptions) {
     const size = roundStep(rawSize, qtyStep);
     if (size < minQty) return false;
 
-    const { price: entryFill, fee: entryFee } = applyFill(
+    const { price: entryFill, feeTotal: entryFeeTotal } = applyFill(
       entryPrice,
       pending.side,
       {
         slippageBps,
         feeBps,
         kind: fillKind,
+        qty: size,
+        costs,
       }
     );
 
@@ -407,7 +447,7 @@ export function backtest(rawOptions) {
       size,
       openTime: bar.time,
       entryFill,
-      entryFeeTotal: entryFee * size,
+      entryFeeTotal,
       initSize: size,
       baseSize: size,
       _mfeR: 0,
@@ -570,16 +610,16 @@ export function backtest(rawOptions) {
           const cutQty = roundStep(open.size * volScale.cutFrac, qtyStep);
           if (cutQty >= minQty && cutQty < open.size) {
             const exitSide = open.side === "long" ? "short" : "long";
-            const { price: filled, fee: exitFee } = applyFill(
+            const { price: filled, feeTotal: exitFeeTotal } = applyFill(
               bar.close,
               exitSide,
-              { slippageBps, feeBps, kind: "market" }
+              { slippageBps, feeBps, kind: "market", qty: cutQty, costs }
             );
             closeLeg({
               openPos: open,
               qty: cutQty,
               exitPx: filled,
-              exitFeePerUnit: exitFee,
+              exitFeeTotal,
               time: bar.time,
               reason: "SCALE",
             });
@@ -614,13 +654,13 @@ export function backtest(rawOptions) {
           const baseSize = open.baseSize || open.initSize;
           const addQty = roundStep(baseSize * pyramiding.addFrac, qtyStep);
           if (addQty >= minQty) {
-            const { price: addFill, fee: addFee } = applyFill(
+            const { price: addFill, feeTotal: addFeeTotal } = applyFill(
               triggerPrice,
               open.side,
-              { slippageBps, feeBps, kind: "limit" }
+              { slippageBps, feeBps, kind: "limit", qty: addQty, costs }
             );
             const newSize = open.size + addQty;
-            open.entryFeeTotal += addFee * addQty;
+            open.entryFeeTotal += addFeeTotal;
             open.entryFill =
               (open.entryFill * open.size + addFill * addQty) / newSize;
             open.size = newSize;
@@ -648,18 +688,20 @@ export function backtest(rawOptions) {
 
         if (touched) {
           const exitSide = open.side === "long" ? "short" : "long";
-          const { price: filled, fee: exitFee } = applyFill(triggerPrice, exitSide, {
-            slippageBps,
-            feeBps,
-            kind: "limit",
-          });
           const qty = roundStep(open.size * scaleOutFrac, qtyStep);
           if (qty >= minQty && qty < open.size) {
+            const { price: filled, feeTotal: exitFeeTotal } = applyFill(triggerPrice, exitSide, {
+              slippageBps,
+              feeBps,
+              kind: "limit",
+              qty,
+              costs,
+            });
             closeLeg({
               openPos: open,
               qty,
               exitPx: filled,
-              exitFeePerUnit: exitFee,
+              exitFeeTotal,
               time: bar.time,
               reason: "SCALE",
             });
@@ -686,17 +728,19 @@ export function backtest(rawOptions) {
 
       if (hit) {
         const exitKind = hit === "TP" ? "limit" : "stop";
-        const { price: filled, fee: exitFee } = applyFill(px, exitSide, {
+        const { price: filled, feeTotal: exitFeeTotal } = applyFill(px, exitSide, {
           slippageBps,
           feeBps,
           kind: exitKind,
+          qty: open.size,
+          costs,
         });
         const localCooldown = open._cooldownBars || 0;
         closeLeg({
           openPos: open,
           qty: open.size,
           exitPx: filled,
-          exitFeePerUnit: exitFee,
+          exitFeeTotal,
           time: bar.time,
           reason: hit,
         });
@@ -783,8 +827,15 @@ export function backtest(rawOptions) {
     }
 
     if (!pending) {
+      if (strict && history.length !== index + 1) {
+        throw new Error(
+          `strict mode: signal() received ${history.length} candles at index ${index}`
+        );
+      }
+
+      const signalCandles = strict ? strictHistoryView(history, index) : history;
       const rawSignal = signal({
-        candles: history,
+        candles: signalCandles,
         index,
         bar,
         equity: currentEquity,

package/src/engine/execution.js

@@ -1,18 +1,55 @@
 import { minutesET } from "../utils/time.js";
 
+function resolveSlippageBps(kind, slippageBps, slippageByKind) {
+  if (Number.isFinite(slippageByKind?.[kind])) {
+    return slippageByKind[kind];
+  }
+
+  let effectiveSlippageBps = slippageBps;
+  if (kind === "limit") effectiveSlippageBps *= 0.25;
+  if (kind === "stop") effectiveSlippageBps *= 1.25;
+  return effectiveSlippageBps;
+}
+
 export function applyFill(
   price,
   side,
-  { slippageBps = 0, feeBps = 0, kind = "market" } = {}
+  { slippageBps = 0, feeBps = 0, kind = "market", qty = 0, costs = {} } = {}
 ) {
-  let effectiveSlippageBps = slippageBps;
-  if (kind === "limit") effectiveSlippageBps *= 0.25;
-  if (kind === "stop") effectiveSlippageBps *= 1.25;
+  const model = costs || {};
+  const modelSlippageBps = Number.isFinite(model.slippageBps)
+    ? model.slippageBps
+    : slippageBps;
+  const modelFeeBps = Number.isFinite(model.commissionBps)
+    ? model.commissionBps
+    : feeBps;
+  const effectiveSlippageBps = resolveSlippageBps(
+    kind,
+    modelSlippageBps,
+    model.slippageByKind
+  );
+  const halfSpreadBps = Number.isFinite(model.spreadBps)
+    ? model.spreadBps / 2
+    : 0;
 
-  const slippage = (effectiveSlippageBps / 10000) * price;
+  const slippage = ((effectiveSlippageBps + halfSpreadBps) / 10000) * price;
   const filledPrice = side === "long" ? price + slippage : price - slippage;
-  const feePerUnit = (feeBps / 10000) * Math.abs(filledPrice);
-  return { price: filledPrice, fee: feePerUnit };
+  const variableFeePerUnit =
+    ((modelFeeBps || 0) / 10000) * Math.abs(filledPrice) +
+    (Number.isFinite(model.commissionPerUnit) ? model.commissionPerUnit : 0);
+  const variableFeeTotal = variableFeePerUnit * Math.max(0, qty);
+  const fixedFeeTotal = Number.isFinite(model.commissionPerOrder)
+    ? model.commissionPerOrder
+    : 0;
+  const grossFeeTotal = variableFeeTotal + fixedFeeTotal;
+  const feeTotal = Math.max(
+    Number.isFinite(model.minCommission) ? model.minCommission : 0,
+    grossFeeTotal
+  );
+  const feePerUnit =
+    qty > 0 ? feeTotal / qty : variableFeePerUnit;
+
+  return { price: filledPrice, fee: feePerUnit, feeTotal };
 }
 
 export function clampStop(marketPrice, proposedStop, side, oco) {

package/src/engine/portfolio.js

@@ -0,0 +1,160 @@
+import { buildMetrics } from "../metrics/buildMetrics.js";
+import { backtest } from "./backtest.js";
+import { estimateBarMs } from "./execution.js";
+
+function asWeight(value) {
+  return Number.isFinite(value) && value > 0 ? value : 0;
+}
+
+function combineEquitySeries(systemRuns, totalEquity) {
+  const timeline = new Set();
+  for (const run of systemRuns) {
+    for (const point of run.result.eqSeries || []) {
+      timeline.add(point.time);
+    }
+  }
+
+  const times = [...timeline].sort((left, right) => left - right);
+  if (!times.length) {
+    return [{ time: 0, timestamp: 0, equity: totalEquity }];
+  }
+
+  const states = systemRuns.map((run) => ({
+    points: run.result.eqSeries || [],
+    index: 0,
+    lastEquity: run.allocationEquity,
+  }));
+
+  return times.map((time) => {
+    let equity = 0;
+    states.forEach((state) => {
+      while (
+        state.index < state.points.length &&
+        state.points[state.index].time <= time
+      ) {
+        state.lastEquity = state.points[state.index].equity;
+        state.index += 1;
+      }
+      equity += state.lastEquity;
+    });
+
+    return { time, timestamp: time, equity };
+  });
+}
+
+function combineReplay(systemRuns, eqSeries, collectReplay) {
+  if (!collectReplay) {
+    return { frames: [], events: [] };
+  }
+
+  const events = systemRuns
+    .flatMap((run) =>
+      (run.result.replay?.events || []).map((event) => ({
+        ...event,
+        symbol: event.symbol || run.symbol,
+      }))
+    )
+    .sort((left, right) => new Date(left.t).getTime() - new Date(right.t).getTime());
+
+  const frames = eqSeries.map((point) => ({
+    t: new Date(point.time).toISOString(),
+    price: 0,
+    equity: point.equity,
+    posSide: null,
+    posSize: 0,
+  }));
+
+  return { frames, events };
+}
+
+/**
+ * Run multiple symbol/system backtests and aggregate them into a portfolio view.
+ *
+ * Capital is allocated up front per system using weights. Each system then runs
+ * through the normal single-symbol backtest engine and the portfolio result
+ * aggregates trades, positions, equity, replay events, and metrics.
+ */
+export function backtestPortfolio({
+  systems = [],
+  equity = 10_000,
+  allocation = "equal",
+  collectEqSeries = true,
+  collectReplay = false,
+} = {}) {
+  if (!Array.isArray(systems) || systems.length === 0) {
+    throw new Error("backtestPortfolio() requires a non-empty systems array");
+  }
+
+  const weights =
+    allocation === "equal"
+      ? systems.map(() => 1)
+      : systems.map((system) => asWeight(system.weight || 0));
+  const totalWeight = weights.reduce((sum, weight) => sum + weight, 0);
+
+  if (!(totalWeight > 0)) {
+    throw new Error("backtestPortfolio() requires positive allocation weights");
+  }
+
+  const systemRuns = systems.map((system, index) => {
+    const allocationEquity = equity * (weights[index] / totalWeight);
+    const result = backtest({
+      ...system,
+      equity: allocationEquity,
+      collectEqSeries,
+      collectReplay,
+    });
+
+    return {
+      symbol: system.symbol ?? result.symbol ?? `system-${index + 1}`,
+      weight: weights[index],
+      allocationEquity,
+      result,
+    };
+  });
+
+  const trades = systemRuns
+    .flatMap((run) =>
+      run.result.trades.map((trade) => ({
+        ...trade,
+        symbol: trade.symbol || run.symbol,
+      }))
+    )
+    .sort((left, right) => left.exit.time - right.exit.time);
+  const positions = systemRuns
+    .flatMap((run) =>
+      run.result.positions.map((trade) => ({
+        ...trade,
+        symbol: trade.symbol || run.symbol,
+      }))
+    )
+    .sort((left, right) => left.exit.time - right.exit.time);
+  const eqSeries = collectEqSeries ? combineEquitySeries(systemRuns, equity) : [];
+  const replay = combineReplay(systemRuns, eqSeries, collectReplay);
+  const allCandles = systems.flatMap((system) => system.candles || []);
+  const orderedCandles = [...allCandles].sort((left, right) => left.time - right.time);
+  const metrics = buildMetrics({
+    closed: trades,
+    equityStart: equity,
+    equityFinal: eqSeries.length ? eqSeries[eqSeries.length - 1].equity : equity,
+    candles: orderedCandles,
+    estBarMs: estimateBarMs(orderedCandles),
+    eqSeries,
+  });
+
+  return {
+    symbol: "PORTFOLIO",
+    interval: undefined,
+    range: undefined,
+    trades,
+    positions,
+    metrics,
+    eqSeries,
+    replay,
+    systems: systemRuns.map((run) => ({
+      symbol: run.symbol,
+      weight: run.weight / totalWeight,
+      equity: run.allocationEquity,
+      result: run.result,
+    })),
+  };
+}