tradelab 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,230 @@
+# tradelab
+
+`tradelab` is a candle-based backtesting toolkit for Node.js. It is built for two use cases:
+
+- you already have candles and want a solid execution/backtest engine
+- you want to fetch Yahoo Finance data or import CSVs and backtest with minimal setup
+
+The package stays focused on historical research. It does not try to be a broker adapter or a live trading framework.
+
+## Features
+
+- Backtest engine with pending entries, OCO exits, scale-outs, pyramiding, cooldowns, daily risk limits, and optional replay data
+- Yahoo Finance historical downloader with local caching
+- Flexible CSV import for common OHLCV layouts
+- Metrics for positions and realized legs
+- CSV trade export
+- Self-contained HTML report export
+- Utility indicators and session helpers for strategy code
+
+## Installation
+
+```bash
+npm install tradelab
+```
+
+Node `18+` is required.
+
+## Quick Start
+
+```js
+import { backtest, ema, exportBacktestArtifacts } from "tradelab";
+
+const result = backtest({
+  candles,
+  symbol: "BTC-USD",
+  interval: "5m",
+  range: "60d",
+  equity: 10_000,
+  riskPct: 1,
+  signal({ candles: history }) {
+    if (history.length < 50) return null;
+
+    const closes = history.map((bar) => bar.close);
+    const fast = ema(closes, 10);
+    const slow = ema(closes, 30);
+    const last = closes.length - 1;
+
+    if (fast[last - 1] <= slow[last - 1] && fast[last] > slow[last]) {
+      const entry = history[last].close;
+      const stop = Math.min(...history.slice(-15).map((bar) => bar.low));
+      const risk = entry - stop;
+      if (risk <= 0) return null;
+
+      return {
+        side: "long",
+        entry,
+        stop,
+        rr: 2,
+      };
+    }
+
+    return null;
+  },
+});
+
+exportBacktestArtifacts({
+  result,
+  outDir: "./output",
+});
+```
+
+## Getting Historical Data
+
+The simplest entry point is `getHistoricalCandles()`.
+
+### Yahoo Finance
+
+```js
+import { getHistoricalCandles, backtest } from "tradelab";
+
+const candles = await getHistoricalCandles({
+  source: "yahoo",
+  symbol: "SPY",
+  interval: "1d",
+  period: "2y",
+  cache: true,
+});
+
+const result = backtest({
+  candles,
+  symbol: "SPY",
+  interval: "1d",
+  range: "2y",
+  signal,
+});
+```
+
+Supported period examples: `5d`, `60d`, `6mo`, `1y`.
+
+### CSV
+
+```js
+import { getHistoricalCandles } from "tradelab";
+
+const candles = await getHistoricalCandles({
+  source: "csv",
+  symbol: "BTC-USD",
+  interval: "5m",
+  csvPath: "./data/btc-5m.csv",
+  csv: {
+    timeCol: "time",
+    openCol: "open",
+    highCol: "high",
+    lowCol: "low",
+    closeCol: "close",
+    volumeCol: "volume",
+  },
+});
+```
+
+If you pass `csvPath` and omit `source`, the loader will auto-detect CSV mode.
+
+## Signal Contract
+
+Your strategy function receives:
+
+```js
+{
+  candles,      // history through the current bar
+  index,        // current index in the original candle array
+  bar,          // current candle
+  equity,       // realized equity
+  openPosition, // null or current position
+  pendingOrder  // null or current pending entry
+}
+```
+
+Return `null` for no trade, or a signal object:
+
+```js
+{
+  side: "long" | "short",
+  entry: Number,
+  stop: Number,
+  takeProfit: Number
+}
+```
+
+Quality-of-life behavior:
+
+- `side` also accepts `buy` and `sell`
+- `entry` can be omitted and will default to the current bar close
+- `takeProfit` can be omitted if `rr` or `_rr` is provided
+- `qty` or `size` can override risk-based sizing
+- `riskPct` or `riskFraction` can override the global risk setting per signal
+
+Optional engine hints:
+
+- `_entryExpiryBars`
+- `_cooldownBars`
+- `_breakevenAtR`
+- `_trailAfterR`
+- `_maxBarsInTrade`
+- `_maxHoldMin`
+- `_rr`
+- `_initRisk`
+- `_imb`
+
+## Result Shape
+
+`backtest()` returns:
+
+- `trades`: every realized leg, including scale-outs
+- `positions`: completed positions only
+- `metrics`: aggregate performance stats
+- `eqSeries`: realized equity history
+- `replay`: chart-friendly frame and event data
+
+## Main Exports
+
+- `backtest(options)`
+- `backtestHistorical({ data, backtestOptions })`
+- `getHistoricalCandles(options)`
+- `fetchHistorical(symbol, interval, period)`
+- `loadCandlesFromCSV(filePath, options)`
+- `saveCandlesToCache(candles, meta)`
+- `loadCandlesFromCache(symbol, interval, period, outDir)`
+- `exportBacktestArtifacts({ result, outDir })`
+
+## Reports
+
+The HTML report is self-contained apart from the Plotly CDN script. Report markup, CSS, and client-side chart code live under `templates/`, not inline in the report renderer.
+
+Export helpers default CSV output to completed positions. Use `csvSource: "trades"` if you want every realized leg in the CSV.
+
+## Examples
+
+```bash
+node examples/emaCross.js
+node examples/yahooEmaCross.js SPY 1d 1y
+```
+
+## Local Scripts
+
+```bash
+npm run prefetch -- --symbol SPY --interval 1d --period 1y
+npm run import-csv -- ./data/sample.csv --symbol BTC-USD --interval 5m
+npm test
+```
+
+## Publishing
+
+Validate the package contents before publishing:
+
+```bash
+npm test
+npm pack --dry-run
+```
+
+Publish when the dry run looks correct:
+
+```bash
+npm publish
+```
+
+## Notes
+
+- Yahoo downloads can be cached under `output/data` by default.
+- The engine is intended for historical research, not brokerage execution.
+- File output only happens through the reporting and cache helpers.

package/examples/emaCross.js

@@ -0,0 +1,108 @@
+import path from "path";
+import { fileURLToPath } from "url";
+
+import { backtest, ema, exportBacktestArtifacts } from "../src/index.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+function formatNumber(value, digits = 2) {
+  if (!Number.isFinite(value)) return value > 0 ? "Inf" : "0";
+  return value.toFixed(digits);
+}
+
+function generateCandles(count = 900) {
+  const candles = [];
+  const start = Date.UTC(2025, 0, 2, 14, 30, 0);
+  let price = 100;
+
+  for (let index = 0; index < count; index += 1) {
+    const drift = Math.sin(index / 24) * 0.3 + Math.cos(index / 11) * 0.15;
+    const shock = Math.sin(index / 7) * 0.6;
+    const close = Math.max(20, price + drift + shock);
+    const open = price;
+    const high = Math.max(open, close) + 0.35 + Math.abs(Math.sin(index / 5)) * 0.2;
+    const low = Math.min(open, close) - 0.35 - Math.abs(Math.cos(index / 6)) * 0.2;
+
+    candles.push({
+      time: start + index * 5 * 60 * 1000,
+      open,
+      high,
+      low,
+      close,
+      volume: 1_000 + index,
+    });
+
+    price = close;
+  }
+
+  return candles;
+}
+
+const candles = generateCandles();
+
+const result = backtest({
+  candles,
+  symbol: "DEMO",
+  interval: "5m",
+  range: "synthetic",
+  equity: 25_000,
+  riskPct: 0.5,
+  collectEqSeries: true,
+  collectReplay: true,
+  signal({ candles: history }) {
+    if (history.length < 60) return null;
+
+    const closes = history.map((bar) => bar.close);
+    const fast = ema(closes, 12);
+    const slow = ema(closes, 26);
+    const lastIndex = closes.length - 1;
+
+    const fastNow = fast[lastIndex];
+    const slowNow = slow[lastIndex];
+    const fastPrev = fast[lastIndex - 1];
+    const slowPrev = slow[lastIndex - 1];
+
+    const crossedUp = fastPrev <= slowPrev && fastNow > slowNow;
+    const crossedDown = fastPrev >= slowPrev && fastNow < slowNow;
+    if (!crossedUp && !crossedDown) return null;
+
+    const recentBars = history.slice(-20);
+    const entry = history[lastIndex].close;
+    const stop = crossedUp
+      ? Math.min(...recentBars.map((bar) => bar.low))
+      : Math.max(...recentBars.map((bar) => bar.high));
+    const risk = Math.abs(entry - stop);
+    if (!Number.isFinite(risk) || risk <= 0) return null;
+
+    return {
+      side: crossedUp ? "long" : "short",
+      entry,
+      stop,
+      takeProfit: crossedUp ? entry + risk * 2.2 : entry - risk * 2.2,
+      _rr: 2.2,
+      _entryExpiryBars: 2,
+      _breakevenAtR: 1,
+      _trailAfterR: 1.5,
+      _cooldownBars: 6,
+    };
+  },
+});
+
+const outputDir = path.join(__dirname, "output");
+const artifacts = exportBacktestArtifacts({
+  result,
+  outDir: outputDir,
+});
+
+console.table({
+  trades: result.metrics.trades,
+  winRate: `${(result.metrics.winRate * 100).toFixed(1)}%`,
+  profitFactor: formatNumber(result.metrics.profitFactor),
+  totalPnL: formatNumber(result.metrics.totalPnL),
+  returnPct: `${(result.metrics.returnPct * 100).toFixed(2)}%`,
+  maxDrawdownPct: `${(result.metrics.maxDrawdownPct * 100).toFixed(2)}%`,
+});
+
+console.log("CSV:", artifacts.csv);
+console.log("HTML:", artifacts.html);

package/examples/yahooEmaCross.js

@@ -0,0 +1,88 @@
+import path from "path";
+import { fileURLToPath } from "url";
+
+import {
+  backtest,
+  ema,
+  exportBacktestArtifacts,
+  getHistoricalCandles,
+} from "../src/index.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+function formatNumber(value, digits = 2) {
+  if (!Number.isFinite(value)) return value > 0 ? "Inf" : "0";
+  return value.toFixed(digits);
+}
+
+const symbol = process.argv[2] || "SPY";
+const interval = process.argv[3] || "1d";
+const period = process.argv[4] || "1y";
+
+const candles = await getHistoricalCandles({
+  source: "yahoo",
+  symbol,
+  interval,
+  period,
+  cache: true,
+});
+
+const result = backtest({
+  candles,
+  symbol,
+  interval,
+  range: period,
+  equity: 25_000,
+  riskPct: 1,
+  collectEqSeries: true,
+  collectReplay: true,
+  warmupBars: 50,
+  signal({ candles: history }) {
+    if (history.length < 50) return null;
+
+    const closes = history.map((bar) => bar.close);
+    const fast = ema(closes, 10);
+    const slow = ema(closes, 20);
+    const last = closes.length - 1;
+
+    const crossedUp = fast[last - 1] <= slow[last - 1] && fast[last] > slow[last];
+    const crossedDown = fast[last - 1] >= slow[last - 1] && fast[last] < slow[last];
+    if (!crossedUp && !crossedDown) return null;
+
+    const lookback = history.slice(-12);
+    const entry = history[last].close;
+    const stop = crossedUp
+      ? Math.min(...lookback.map((bar) => bar.low))
+      : Math.max(...lookback.map((bar) => bar.high));
+    const risk = Math.abs(entry - stop);
+    if (!(risk > 0)) return null;
+
+    return {
+      side: crossedUp ? "long" : "short",
+      entry,
+      stop,
+      rr: 2,
+      _entryExpiryBars: 1,
+    };
+  },
+});
+
+const outDir = path.join(__dirname, "output");
+const artifacts = exportBacktestArtifacts({
+  result,
+  outDir,
+});
+
+console.table({
+  symbol,
+  candles: candles.length,
+  trades: result.metrics.trades,
+  winRate: `${(result.metrics.winRate * 100).toFixed(1)}%`,
+  profitFactor: formatNumber(result.metrics.profitFactor),
+  totalPnL: formatNumber(result.metrics.totalPnL),
+  returnPct: `${(result.metrics.returnPct * 100).toFixed(2)}%`,
+});
+
+console.log("CSV:", artifacts.csv);
+console.log("HTML:", artifacts.html);

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "tradelab",
+  "version": "0.1.0",
+  "description": "Reusable trading and backtesting engine for candle-based strategies",
+  "type": "module",
+  "main": "./src/index.js",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": "./src/index.js",
+    "./data": "./src/data/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "templates",
+    "examples/*.js",
+    "scripts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "prefetch": "node scripts/prefetch.js",
+    "import-csv": "node scripts/import-csv.js",
+    "example:ema": "node examples/emaCross.js",
+    "example:yahoo": "node examples/yahooEmaCross.js"
+  },
+  "keywords": [
+    "trading",
+    "backtesting",
+    "algorithmic-trading",
+    "ohlcv",
+    "quant"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/import-csv.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+
+import {
+  candleStats,
+  loadCandlesFromCSV,
+  saveCandlesToCache,
+} 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("--")) {
+      if (!args.file) args.file = 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;
+}
+
+const args = parseArgs(process.argv.slice(2));
+
+if (!args.file || !args.symbol) {
+  console.log(
+    "Usage: node scripts/import-csv.js <file.csv> --symbol BTC-USD [--interval 5m] [--period 90d]"
+  );
+  process.exit(1);
+}
+
+try {
+  const candles = loadCandlesFromCSV(args.file, {
+    delimiter: args.delimiter || ",",
+    timeCol: args.timeCol || "time",
+    openCol: args.openCol || "open",
+    highCol: args.highCol || "high",
+    lowCol: args.lowCol || "low",
+    closeCol: args.closeCol || "close",
+    volumeCol: args.volumeCol || "volume",
+    startDate: args.startDate,
+    endDate: args.endDate,
+  });
+
+  const stats = candleStats(candles);
+  const interval = args.interval || "1d";
+  const period = args.period || `${Math.max(1, Math.ceil(stats?.durationDays || 1))}d`;
+  const outputPath = saveCandlesToCache(candles, {
+    symbol: args.symbol,
+    interval,
+    period,
+    outDir: args.outDir || "output/data",
+    source: "csv",
+  });
+
+  console.log(`Loaded ${stats?.count ?? 0} candles`);
+  console.log(`Range: ${stats?.firstTime ?? "—"} -> ${stats?.lastTime ?? "—"}`);
+  console.log(`Saved cache: ${outputPath}`);
+} catch (error) {
+  console.error(error.message);
+  process.exit(1);
+}

package/scripts/prefetch.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+
+import { getHistoricalCandles, saveCandlesToCache } 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("--")) 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;
+}
+
+const args = parseArgs(process.argv.slice(2));
+const symbol = args.symbol || "SPY";
+const interval = args.interval || "1d";
+const period = args.period || "1y";
+const outDir = args.outDir || "output/data";
+
+async function main() {
+  const candles = await getHistoricalCandles({
+    source: "yahoo",
+    symbol,
+    interval,
+    period,
+    cache: false,
+  });
+
+  const outputPath = saveCandlesToCache(candles, {
+    symbol,
+    interval,
+    period,
+    outDir,
+    source: "yahoo",
+  });
+
+  console.log(`Saved ${candles.length} candles to ${outputPath}`);
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exit(1);
+});