tradelab 0.2.0 → 0.3.0

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,
+    })),
+  };
+}

package/src/engine/walkForward.js

@@ -0,0 +1,126 @@
+import { buildMetrics } from "../metrics/buildMetrics.js";
+import { backtest } from "./backtest.js";
+import { estimateBarMs } from "./execution.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);
+}
+
+/**
+ * Run rolling walk-forward optimization over a single candle series.
+ *
+ * Each window selects the best parameter set on the training segment and then
+ * evaluates that parameter set on the following out-of-sample segment.
+ */
+export 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 ?? 10_000;
+
+  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 ?? 10_000,
+    equityFinal: rollingEquity,
+    candles,
+    estBarMs: estimateBarMs(candles),
+    eqSeries,
+  });
+
+  return {
+    windows,
+    trades: allTrades,
+    positions: allPositions,
+    metrics,
+    eqSeries,
+    replay: { frames: [], events: [] },
+    bestParams: windows.map((window) => window.bestParams),
+  };
+}

package/src/index.js

@@ -1,4 +1,6 @@
 export { backtest } from "./engine/backtest.js";
+export { backtestPortfolio } from "./engine/portfolio.js";
+export { walkForwardOptimize } from "./engine/walkForward.js";
 
 export { buildMetrics } from "./metrics/buildMetrics.js";
 export {

package/types/index.d.ts

@@ -224,6 +224,16 @@ export interface OCOOptions {
   clampEpsBps?: number;
 }
 
+export interface ExecutionCostOptions {
+  slippageBps?: number;
+  spreadBps?: number;
+  slippageByKind?: Partial<Record<"market" | "limit" | "stop", number>>;
+  commissionBps?: number;
+  commissionPerUnit?: number;
+  commissionPerOrder?: number;
+  minCommission?: number;
+}
+
 export interface MfeTrailOptions {
   enabled?: boolean;
   armR?: number;
@@ -265,6 +275,7 @@ export interface BacktestOptions {
   warmupBars?: number;
   slippageBps?: number;
   feeBps?: number;
+  costs?: ExecutionCostOptions;
   scaleOutAtR?: number;
   scaleOutFrac?: number;
   finalTP_R?: number;
@@ -307,6 +318,36 @@ export interface BacktestResult {
   replay: ReplayPayload;
 }
 
+export interface PortfolioSystem extends Omit<BacktestOptions, "equity"> {
+  weight?: number;
+}
+
+export interface PortfolioSystemResult {
+  symbol: string;
+  weight: number;
+  equity: number;
+  result: BacktestResult;
+}
+
+export interface PortfolioBacktestResult extends BacktestResult {
+  systems: PortfolioSystemResult[];
+}
+
+export interface WalkForwardWindow {
+  train: { start: number | null; end: number | null };
+  test: { start: number | null; end: number | null };
+  bestParams: Record<string, unknown>;
+  trainScore: number;
+  trainMetrics: BacktestMetrics;
+  testMetrics: BacktestMetrics;
+  result: BacktestResult;
+}
+
+export interface WalkForwardResult extends BacktestResult {
+  windows: WalkForwardWindow[];
+  bestParams: Array<Record<string, unknown>>;
+}
+
 export interface CsvLoadOptions {
   delimiter?: string;
   skipRows?: number;
@@ -418,6 +459,23 @@ export interface ArtifactPaths {
  * chart-friendly replay frames/events in `replay`.
  */
 export function backtest(options: BacktestOptions): BacktestResult;
+export function backtestPortfolio(options: {
+  systems: PortfolioSystem[];
+  equity?: number;
+  allocation?: "equal" | "weight";
+  collectEqSeries?: boolean;
+  collectReplay?: boolean;
+}): PortfolioBacktestResult;
+export function walkForwardOptimize(options: {
+  candles: Candle[];
+  signalFactory: (params: Record<string, unknown>) => SignalFunction;
+  parameterSets: Array<Record<string, unknown>>;
+  trainBars: number;
+  testBars: number;
+  stepBars?: number;
+  scoreBy?: keyof BacktestMetrics;
+  backtestOptions?: Omit<BacktestOptions, "candles" | "signal">;
+}): WalkForwardResult;
 export function buildMetrics(input: {
   closed: BacktestTrade[];
   equityStart: number;