tradelab 0.2.0 → 0.4.0

package/dist/cjs/index.cjs

@@ -32,6 +32,7 @@ __export(index_exports, {
   atr: () => atr,
   backtest: () => backtest,
   backtestHistorical: () => backtestHistorical,
+  backtestPortfolio: () => backtestPortfolio,
   bpsOf: () => bpsOf,
   buildMetrics: () => buildMetrics,
   cachedCandlesPath: () => cachedCandlesPath,
@@ -61,7 +62,8 @@ __export(index_exports, {
   saveCandlesToCache: () => saveCandlesToCache,
   structureState: () => structureState,
   swingHigh: () => swingHigh,
-  swingLow: () => swingLow
+  swingLow: () => swingLow,
+  walkForwardOptimize: () => walkForwardOptimize
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -789,14 +791,37 @@ function inWindowsET(timeMs, windows) {
 }
 
 // src/engine/execution.js
-function applyFill(price, side, { slippageBps = 0, feeBps = 0, kind = "market" } = {}) {
+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;
-  const slippage = effectiveSlippageBps / 1e4 * price;
+  return effectiveSlippageBps;
+}
+function applyFill(price, side, { slippageBps = 0, feeBps = 0, kind = "market", qty = 0, costs = {} } = {}) {
+  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 + halfSpreadBps) / 1e4 * price;
   const filledPrice = side === "long" ? price + slippage : price - slippage;
-  const feePerUnit = feeBps / 1e4 * Math.abs(filledPrice);
-  return { price: filledPrice, fee: feePerUnit };
+  const variableFeePerUnit = (modelFeeBps || 0) / 1e4 * 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 };
 }
 function clampStop(marketPrice, proposedStop, side, oco) {
   const epsilon = (oco?.clampEpsBps ?? 0.25) / 1e4;
@@ -918,6 +943,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,
@@ -1018,6 +1044,7 @@ function backtest(rawOptions) {
     signal,
     slippageBps,
     feeBps,
+    costs,
     scaleOutAtR,
     scaleOutFrac,
     finalTP_R,
@@ -1087,12 +1114,11 @@ 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;
@@ -1145,16 +1171,18 @@ function backtest(rawOptions) {
   function forceExit(reason, bar) {
     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"
+      kind: "market",
+      qty: open.size,
+      costs
     });
     closeLeg({
       openPos: open,
       qty: open.size,
       exitPx: filled,
-      exitFeePerUnit: exitFee,
+      exitFeeTotal,
       time: bar.time,
       reason
     });
@@ -1195,13 +1223,15 @@ function backtest(rawOptions) {
     });
     const size = roundStep2(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
+        kind: fillKind,
+        qty: size,
+        costs
       }
     );
     open = {
@@ -1215,7 +1245,7 @@ function backtest(rawOptions) {
       size,
       openTime: bar.time,
       entryFill,
-      entryFeeTotal: entryFee * size,
+      entryFeeTotal,
       initSize: size,
       baseSize: size,
       _mfeR: 0,
@@ -1311,16 +1341,16 @@ function backtest(rawOptions) {
           const cutQty = roundStep2(open.size * volScale.cutFrac, qtyStep);
           if (cutQty >= minQty && cutQty < open.size) {
             const exitSide2 = open.side === "long" ? "short" : "long";
-            const { price: filled, fee: exitFee } = applyFill(
+            const { price: filled, feeTotal: exitFeeTotal } = applyFill(
               bar.close,
               exitSide2,
-              { 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"
             });
@@ -1340,13 +1370,13 @@ function backtest(rawOptions) {
           const baseSize = open.baseSize || open.initSize;
           const addQty = roundStep2(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;
             open.initSize += addQty;
@@ -1361,18 +1391,20 @@ function backtest(rawOptions) {
         const touched = open.side === "long" ? trigger === "intrabar" ? bar.high >= triggerPrice : bar.close >= triggerPrice : trigger === "intrabar" ? bar.low <= triggerPrice : bar.close <= triggerPrice;
         if (touched) {
           const exitSide2 = open.side === "long" ? "short" : "long";
-          const { price: filled, fee: exitFee } = applyFill(triggerPrice, exitSide2, {
-            slippageBps,
-            feeBps,
-            kind: "limit"
-          });
           const qty = roundStep2(open.size * scaleOutFrac, qtyStep);
           if (qty >= minQty && qty < open.size) {
+            const { price: filled, feeTotal: exitFeeTotal } = applyFill(triggerPrice, exitSide2, {
+              slippageBps,
+              feeBps,
+              kind: "limit",
+              qty,
+              costs
+            });
             closeLeg({
               openPos: open,
               qty,
               exitPx: filled,
-              exitFeePerUnit: exitFee,
+              exitFeeTotal,
               time: bar.time,
               reason: "SCALE"
             });
@@ -1394,17 +1426,19 @@ 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
+          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
         });
@@ -1542,6 +1576,232 @@ function backtest(rawOptions) {
   };
 }
 
+// src/engine/portfolio.js
+function asWeight(value) {
+  return Number.isFinite(value) && value > 0 ? value : 0;
+}
+function combineEquitySeries(systemRuns, totalEquity) {
+  const timeline = /* @__PURE__ */ 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 };
+}
+function backtestPortfolio({
+  systems = [],
+  equity = 1e4,
+  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((sum2, weight) => sum2 + 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: void 0,
+    range: void 0,
+    trades,
+    positions,
+    metrics,
+    eqSeries,
+    replay,
+    systems: systemRuns.map((run) => ({
+      symbol: run.symbol,
+      weight: run.weight / totalWeight,
+      equity: run.allocationEquity,
+      result: run.result
+    }))
+  };
+}
+
+// src/engine/walkForward.js
+function scoreOf(metrics, scoreBy) {
+  const value = metrics?.[scoreBy];
+  return Number.isFinite(value) ? value : -Infinity;
+}
+function stitchEquitySeries(target, source) {
+  if (!source?.length) return;
+  if (!target.length) {
+    target.push(...source);
+    return;
+  }
+  const lastTime = target[target.length - 1].time;
+  const nextPoints = source.filter((point) => point.time > lastTime);
+  target.push(...nextPoints);
+}
+function walkForwardOptimize({
+  candles = [],
+  signalFactory,
+  parameterSets = [],
+  trainBars,
+  testBars,
+  stepBars = testBars,
+  scoreBy = "profitFactor",
+  backtestOptions = {}
+} = {}) {
+  if (!Array.isArray(candles) || candles.length === 0) {
+    throw new Error("walkForwardOptimize() requires a non-empty candles array");
+  }
+  if (typeof signalFactory !== "function") {
+    throw new Error("walkForwardOptimize() requires a signalFactory function");
+  }
+  if (!Array.isArray(parameterSets) || parameterSets.length === 0) {
+    throw new Error("walkForwardOptimize() requires parameterSets");
+  }
+  if (!(trainBars > 0) || !(testBars > 0) || !(stepBars > 0)) {
+    throw new Error("walkForwardOptimize() requires positive trainBars, testBars, and stepBars");
+  }
+  const windows = [];
+  const allTrades = [];
+  const allPositions = [];
+  const eqSeries = [];
+  let rollingEquity = backtestOptions.equity ?? 1e4;
+  for (let start = 0; start + trainBars + testBars <= candles.length; start += stepBars) {
+    const trainSlice = candles.slice(start, start + trainBars);
+    const testSlice = candles.slice(start + trainBars, start + trainBars + testBars);
+    let best = null;
+    for (const params of parameterSets) {
+      const trainResult = backtest({
+        ...backtestOptions,
+        candles: trainSlice,
+        equity: rollingEquity,
+        signal: signalFactory(params)
+      });
+      const score = scoreOf(trainResult.metrics, scoreBy);
+      if (!best || score > best.score) {
+        best = { params, score, metrics: trainResult.metrics };
+      }
+    }
+    const testResult = backtest({
+      ...backtestOptions,
+      candles: testSlice,
+      equity: rollingEquity,
+      signal: signalFactory(best.params)
+    });
+    rollingEquity = testResult.metrics.finalEquity;
+    allTrades.push(...testResult.trades);
+    allPositions.push(...testResult.positions);
+    stitchEquitySeries(eqSeries, testResult.eqSeries);
+    windows.push({
+      train: {
+        start: trainSlice[0]?.time ?? null,
+        end: trainSlice[trainSlice.length - 1]?.time ?? null
+      },
+      test: {
+        start: testSlice[0]?.time ?? null,
+        end: testSlice[testSlice.length - 1]?.time ?? null
+      },
+      bestParams: best.params,
+      trainScore: best.score,
+      trainMetrics: best.metrics,
+      testMetrics: testResult.metrics,
+      result: testResult
+    });
+  }
+  const metrics = buildMetrics({
+    closed: allTrades,
+    equityStart: backtestOptions.equity ?? 1e4,
+    equityFinal: rollingEquity,
+    candles,
+    estBarMs: estimateBarMs(candles),
+    eqSeries
+  });
+  return {
+    windows,
+    trades: allTrades,
+    positions: allPositions,
+    metrics,
+    eqSeries,
+    replay: { frames: [], events: [] },
+    bestParams: windows.map((window) => window.bestParams)
+  };
+}
+
 // src/data/index.js
 var import_path2 = __toESM(require("path"), 1);
 
@@ -2261,6 +2521,7 @@ function exportBacktestArtifacts({
   atr,
   backtest,
   backtestHistorical,
+  backtestPortfolio,
   bpsOf,
   buildMetrics,
   cachedCandlesPath,
@@ -2290,5 +2551,6 @@ function exportBacktestArtifacts({
   saveCandlesToCache,
   structureState,
   swingHigh,
-  swingLow
+  swingLow,
+  walkForwardOptimize
 });

package/docs/README.md

@@ -0,0 +1,61 @@
+# tradelab docs
+
+## Guides
+
+- [Backtest engine](backtest-engine.md)
+- [Data, reporting, and CLI](data-reporting-cli.md)
+- [API reference](api-reference.md)
+
+## Choose a path
+
+| Goal | Start here |
+| --- | --- |
+| Run one strategy on one dataset | [Backtest engine](backtest-engine.md) |
+| Load Yahoo or CSV data | [Data, reporting, and CLI](data-reporting-cli.md) |
+| Export reports or machine-readable results | [Data, reporting, and CLI](data-reporting-cli.md) |
+| Run multiple symbols together | [Backtest engine](backtest-engine.md) |
+| Run walk-forward validation | [Backtest engine](backtest-engine.md) |
+| Check the exact public exports | [API reference](api-reference.md) |
+
+## Package scope
+
+tradelab is built for:
+
+- candle-based strategy research
+- historical backtests with configurable fills and costs
+- CSV and Yahoo-based data workflows
+- exportable outputs for review or automation
+
+tradelab is not built for:
+
+- live broker execution
+- tick-level simulation
+- exchange microstructure modeling
+
+## Common workflows
+
+### Single strategy workflow
+
+1. Load candles with `getHistoricalCandles()` or your own dataset
+2. Run `backtest()`
+3. Inspect `result.metrics` and `result.positions`
+4. Export HTML, CSV, or JSON if needed
+
+### Multi-symbol workflow
+
+1. Prepare one candle array per symbol
+2. Run `backtestPortfolio()`
+3. Review combined `metrics`, `positions`, and `eqSeries`
+
+### Validation workflow
+
+1. Build a `signalFactory(params)`
+2. Create parameter sets
+3. Run `walkForwardOptimize()`
+4. Review per-window winners before trusting the aggregate result
+
+## Documentation map
+
+- [Backtest engine](backtest-engine.md): strategy inputs, engine options, result shape, portfolio mode, walk-forward mode
+- [Data, reporting, and CLI](data-reporting-cli.md): data loading, cache behavior, exports, terminal usage
+- [API reference](api-reference.md): compact export index

package/docs/api-reference.md

@@ -0,0 +1,70 @@
+# API reference
+
+This page is the compact index of public exports.
+
+If you are learning the package, start with [backtest-engine.md](backtest-engine.md) or [data-reporting-cli.md](data-reporting-cli.md). This page is for quick lookup.
+
+## Backtesting
+
+| Export | Summary |
+| --- | --- |
+| `backtest(options)` | Run one strategy on one candle series |
+| `backtestPortfolio(options)` | Run multiple systems and merge the result |
+| `walkForwardOptimize(options)` | Run rolling train/test validation |
+| `buildMetrics(input)` | Compute metrics from realized trades and equity data |
+
+## Data
+
+| Export | Summary |
+| --- | --- |
+| `getHistoricalCandles(options)` | Load candles from Yahoo or CSV |
+| `backtestHistorical({ data, backtestOptions })` | Load candles and immediately run `backtest()` |
+| `fetchHistorical(symbol, interval, period, options)` | Call the Yahoo layer directly |
+| `fetchLatestCandle(symbol, interval, options)` | Fetch the latest Yahoo candle |
+| `loadCandlesFromCSV(filePath, options)` | Parse and normalize a CSV file |
+| `normalizeCandles(candles)` | Normalize candle field names and sort/dedupe |
+| `mergeCandles(...arrays)` | Merge multiple candle arrays |
+| `candleStats(candles)` | Return summary stats for a candle array |
+| `saveCandlesToCache(candles, meta)` | Write normalized candles to the local cache |
+| `loadCandlesFromCache(symbol, interval, period, outDir)` | Read normalized candles from the local cache |
+| `cachedCandlesPath(symbol, interval, period, outDir)` | Return the expected cache path |
+
+## Reporting
+
+| Export | Summary |
+| --- | --- |
+| `renderHtmlReport(options)` | Return the HTML report as a string |
+| `exportHtmlReport(options)` | Write the HTML report to disk |
+| `exportTradesCsv(trades, options)` | Write a CSV ledger of trades or positions |
+| `exportMetricsJSON(options)` | Write machine-readable metrics JSON |
+| `exportBacktestArtifacts(options)` | Write HTML, CSV, and metrics JSON together |
+
+## Indicators and utilities
+
+### Indicators
+
+- `ema(values, period)`
+- `atr(bars, period)`
+- `swingHigh(bars, index, left, right)`
+- `swingLow(bars, index, left, right)`
+- `detectFVG(bars, index)`
+- `lastSwing(bars, index, direction)`
+- `structureState(bars, index)`
+- `bpsOf(price, bps)`
+- `pct(a, b)`
+
+### Position sizing
+
+- `calculatePositionSize(input)`
+
+### Time helpers
+
+- `offsetET(timeMs)`
+- `minutesET(timeMs)`
+- `isSession(timeMs, session)`
+- `parseWindowsCSV(csv)`
+- `inWindowsET(timeMs, windows)`
+
+## Types
+
+The package ships declarations in [../types/index.d.ts](../types/index.d.ts). Use that file when you need the exact option and result contracts in TypeScript or editor IntelliSense.