tradelab 0.2.0 → 0.4.0

package/bin/tradelab.js

@@ -0,0 +1,384 @@
+#!/usr/bin/env node
+import path from "path";
+import { pathToFileURL } from "url";
+
+import {
+  backtest,
+  backtestPortfolio,
+  ema,
+  exportBacktestArtifacts,
+  exportMetricsJSON,
+  getHistoricalCandles,
+  loadCandlesFromCSV,
+  saveCandlesToCache,
+  walkForwardOptimize,
+} from "../src/index.js";
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith("--")) {
+      args._.push(token);
+      continue;
+    }
+
+    const key = token.slice(2);
+    const next = argv[index + 1];
+    if (next && !next.startsWith("--")) {
+      args[key] = next;
+      index += 1;
+    } else {
+      args[key] = true;
+    }
+  }
+  return args;
+}
+
+function toNumber(value, fallback) {
+  const numeric = Number(value);
+  return Number.isFinite(numeric) ? numeric : fallback;
+}
+
+function toList(value, fallback) {
+  if (!value) return fallback;
+  return String(value)
+    .split(",")
+    .map((item) => Number(item.trim()))
+    .filter((item) => Number.isFinite(item));
+}
+
+function createEmaCrossSignal({
+  fast = 10,
+  slow = 30,
+  rr = 2,
+  stopLookback = 15,
+} = {}) {
+  return ({ candles }) => {
+    if (candles.length < Math.max(fast, slow) + 2) return null;
+
+    const closes = candles.map((bar) => bar.close);
+    const fastLine = ema(closes, fast);
+    const slowLine = ema(closes, slow);
+    const last = closes.length - 1;
+
+    if (
+      fastLine[last - 1] <= slowLine[last - 1] &&
+      fastLine[last] > slowLine[last]
+    ) {
+      const entry = candles[last].close;
+      const stop = Math.min(
+        ...candles.slice(-stopLookback).map((bar) => bar.low)
+      );
+      if (entry > stop) {
+        return { side: "long", entry, stop, rr };
+      }
+    }
+
+    if (
+      fastLine[last - 1] >= slowLine[last - 1] &&
+      fastLine[last] < slowLine[last]
+    ) {
+      const entry = candles[last].close;
+      const stop = Math.max(
+        ...candles.slice(-stopLookback).map((bar) => bar.high)
+      );
+      if (entry < stop) {
+        return { side: "short", entry, stop, rr };
+      }
+    }
+
+    return null;
+  };
+}
+
+function createBuyHoldSignal({ holdBars = 5, stopPct = 0.05 } = {}) {
+  let entered = false;
+
+  return ({ bar }) => {
+    if (entered) return null;
+    entered = true;
+    return {
+      side: "long",
+      entry: bar.close,
+      stop: bar.close * (1 - stopPct),
+      rr: 100,
+      _maxBarsInTrade: holdBars,
+    };
+  };
+}
+
+async function loadStrategy(strategyArg, args) {
+  if (!strategyArg || strategyArg === "ema-cross") {
+    return createEmaCrossSignal({
+      fast: toNumber(args.fast, 10),
+      slow: toNumber(args.slow, 30),
+      rr: toNumber(args.rr, 2),
+      stopLookback: toNumber(args.stopLookback, 15),
+    });
+  }
+
+  if (strategyArg === "buy-hold") {
+    return createBuyHoldSignal({
+      holdBars: toNumber(args.holdBars, 5),
+      stopPct: toNumber(args.stopPct, 0.05),
+    });
+  }
+
+  const resolved = path.resolve(process.cwd(), strategyArg);
+  const module = await import(pathToFileURL(resolved).href);
+  if (typeof module.default === "function") return module.default(args);
+  if (typeof module.createSignal === "function") return module.createSignal(args);
+  if (typeof module.signal === "function") return module.signal;
+  throw new Error(`Strategy module "${strategyArg}" must export default, createSignal, or signal`);
+}
+
+function printHelp() {
+  console.log(`tradelab
+
+Commands:
+  backtest      Run a one-off backtest from Yahoo or CSV data
+  portfolio     Run multiple CSV datasets as an equal-weight portfolio
+  walk-forward  Run rolling train/test optimization with the built-in ema-cross strategy
+  prefetch      Download Yahoo candles into the local cache
+  import-csv    Normalize a CSV and save it into the local cache
+
+Examples:
+  tradelab backtest --source yahoo --symbol SPY --interval 1d --period 1y
+  tradelab backtest --source csv --csvPath ./data/btc.csv --strategy buy-hold --holdBars 3
+  tradelab walk-forward --source csv --csvPath ./data/spy.csv --trainBars 120 --testBars 40
+`);
+}
+
+async function commandBacktest(args) {
+  const candles = await getHistoricalCandles({
+    source: args.source || (args.csvPath ? "csv" : "yahoo"),
+    symbol: args.symbol,
+    interval: args.interval || "1d",
+    period: args.period || "1y",
+    csvPath: args.csvPath,
+    cache: args.cache !== "false",
+  });
+  const signal = await loadStrategy(args.strategy, args);
+  const result = backtest({
+    candles,
+    symbol: args.symbol || "DATA",
+    interval: args.interval || "1d",
+    range: args.period || "custom",
+    equity: toNumber(args.equity, 10_000),
+    riskPct: toNumber(args.riskPct, 1),
+    warmupBars: toNumber(args.warmupBars, 20),
+    flattenAtClose: args.flattenAtClose === true || args.flattenAtClose === "true",
+    signal,
+  });
+
+  const outputs = exportBacktestArtifacts({
+    result,
+    outDir: args.outDir || "output",
+  });
+
+  console.log(
+    JSON.stringify(
+      {
+        symbol: result.symbol,
+        trades: result.metrics.trades,
+        winRate: result.metrics.winRate,
+        profitFactor: result.metrics.profitFactor,
+        finalEquity: result.metrics.finalEquity,
+        outputs,
+      },
+      null,
+      2
+    )
+  );
+}
+
+function parsePortfolioInputs(args) {
+  const csvPaths = String(args.csvPaths || "")
+    .split(",")
+    .map((value) => value.trim())
+    .filter(Boolean);
+  const symbols = String(args.symbols || "")
+    .split(",")
+    .map((value) => value.trim())
+    .filter(Boolean);
+
+  return csvPaths.map((csvPath, index) => ({
+    symbol: symbols[index] || `asset-${index + 1}`,
+    candles: loadCandlesFromCSV(csvPath),
+  }));
+}
+
+async function commandPortfolio(args) {
+  const baseSystems = parsePortfolioInputs(args);
+  const systems = await Promise.all(
+    baseSystems.map(async (system) => ({
+      ...system,
+      signal: await loadStrategy(args.strategy || "buy-hold", args),
+      warmupBars: toNumber(args.warmupBars, 1),
+      flattenAtClose: false,
+    }))
+  );
+
+  const result = backtestPortfolio({
+    systems,
+    equity: toNumber(args.equity, 10_000),
+    collectReplay: false,
+    collectEqSeries: true,
+  });
+  const metricsPath = exportMetricsJSON({
+    result,
+    outDir: args.outDir || "output",
+    symbol: "PORTFOLIO",
+    interval: args.interval || "mixed",
+    range: args.period || "custom",
+  });
+
+  console.log(
+    JSON.stringify(
+      {
+        systems: result.systems.length,
+        positions: result.positions.length,
+        finalEquity: result.metrics.finalEquity,
+        metricsPath,
+      },
+      null,
+      2
+    )
+  );
+}
+
+async function commandWalkForward(args) {
+  const candles = await getHistoricalCandles({
+    source: args.source || (args.csvPath ? "csv" : "yahoo"),
+    symbol: args.symbol,
+    interval: args.interval || "1d",
+    period: args.period || "1y",
+    csvPath: args.csvPath,
+    cache: args.cache !== "false",
+  });
+  const fasts = toList(args.fasts, [8, 10, 12]);
+  const slows = toList(args.slows, [20, 30, 40]);
+  const rrs = toList(args.rrs, [1.5, 2, 3]);
+  const parameterSets = [];
+
+  for (const fast of fasts) {
+    for (const slow of slows) {
+      if (fast >= slow) continue;
+      for (const rr of rrs) {
+        parameterSets.push({ fast, slow, rr });
+      }
+    }
+  }
+
+  const result = walkForwardOptimize({
+    candles,
+    parameterSets,
+    trainBars: toNumber(args.trainBars, 120),
+    testBars: toNumber(args.testBars, 40),
+    stepBars: toNumber(args.stepBars, toNumber(args.testBars, 40)),
+    scoreBy: args.scoreBy || "profitFactor",
+    backtestOptions: {
+      symbol: args.symbol || "DATA",
+      interval: args.interval || "1d",
+      range: args.period || "custom",
+      equity: toNumber(args.equity, 10_000),
+      riskPct: toNumber(args.riskPct, 1),
+      warmupBars: toNumber(args.warmupBars, 20),
+    },
+    signalFactory(params) {
+      return createEmaCrossSignal({
+        fast: params.fast,
+        slow: params.slow,
+        rr: params.rr,
+        stopLookback: toNumber(args.stopLookback, 15),
+      });
+    },
+  });
+
+  const metricsPath = exportMetricsJSON({
+    result,
+    outDir: args.outDir || "output",
+    symbol: args.symbol || "DATA",
+    interval: args.interval || "1d",
+    range: `${args.trainBars || 120}-${args.testBars || 40}`,
+  });
+
+  console.log(
+    JSON.stringify(
+      {
+        windows: result.windows.length,
+        positions: result.positions.length,
+        finalEquity: result.metrics.finalEquity,
+        metricsPath,
+      },
+      null,
+      2
+    )
+  );
+}
+
+async function commandPrefetch(args) {
+  const candles = await getHistoricalCandles({
+    source: "yahoo",
+    symbol: args.symbol || "SPY",
+    interval: args.interval || "1d",
+    period: args.period || "1y",
+    cache: false,
+  });
+  const outputPath = saveCandlesToCache(candles, {
+    symbol: args.symbol || "SPY",
+    interval: args.interval || "1d",
+    period: args.period || "1y",
+    outDir: args.outDir || "output/data",
+    source: "yahoo",
+  });
+  console.log(`Saved ${candles.length} candles to ${outputPath}`);
+}
+
+async function commandImportCsv(args) {
+  const csvPath = args.csvPath || args._[1];
+  if (!csvPath) {
+    throw new Error("import-csv requires --csvPath or a positional CSV file path");
+  }
+
+  const candles = loadCandlesFromCSV(csvPath, {});
+  const outputPath = saveCandlesToCache(candles, {
+    symbol: args.symbol || "DATA",
+    interval: args.interval || "1d",
+    period: args.period || "custom",
+    outDir: args.outDir || "output/data",
+    source: "csv",
+  });
+  console.log(`Saved ${candles.length} candles to ${outputPath}`);
+}
+
+const commands = {
+  backtest: commandBacktest,
+  portfolio: commandPortfolio,
+  "walk-forward": commandWalkForward,
+  prefetch: commandPrefetch,
+  "import-csv": commandImportCsv,
+};
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const command = args._[0];
+
+  if (!command || command === "help" || args.help) {
+    printHelp();
+    return;
+  }
+
+  const handler = commands[command];
+  if (!handler) {
+    throw new Error(`Unknown command "${command}". Run "tradelab help".`);
+  }
+
+  await handler(args);
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exit(1);
+});

package/dist/cjs/data.cjs

@@ -653,14 +653,37 @@ function minutesET(timeMs) {
 }
 
 // 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;
@@ -782,6 +805,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,
@@ -882,6 +906,7 @@ function backtest(rawOptions) {
     signal,
     slippageBps,
     feeBps,
+    costs,
     scaleOutAtR,
     scaleOutFrac,
     finalTP_R,
@@ -951,12 +976,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;
@@ -1009,16 +1033,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
     });
@@ -1059,13 +1085,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 = {
@@ -1079,7 +1107,7 @@ function backtest(rawOptions) {
       size,
       openTime: bar.time,
       entryFill,
-      entryFeeTotal: entryFee * size,
+      entryFeeTotal,
       initSize: size,
       baseSize: size,
       _mfeR: 0,
@@ -1175,16 +1203,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"
             });
@@ -1204,13 +1232,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;
@@ -1225,18 +1253,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"
             });
@@ -1258,17 +1288,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
         });