tradelab 0.3.0 → 0.5.0

package/docs/data-reporting-cli.md

@@ -0,0 +1,258 @@
+# Data, reporting, and CLI
+<small>[Back to main page](README.md)</small>
+
+This page covers the parts of the package around the core engine:
+
+- historical data loading
+- local cache helpers
+- export helpers
+- command-line usage
+
+## Overview
+
+If you are not bringing your own candles yet, start here.
+
+## Choose the right entry point
+
+| Use case | Function |
+| --- | --- |
+| Load data without caring about the source-specific helper | `getHistoricalCandles()` |
+| Fetch directly from Yahoo | `fetchHistorical()` |
+| Load a local CSV file | `loadCandlesFromCSV()` |
+| Reuse saved normalized data | `loadCandlesFromCache()` |
+| Try the package from a terminal first | `tradelab` CLI |
+
+## Historical data
+
+### `getHistoricalCandles(options)`
+
+This is the main data-loading entry point.
+
+```js
+const candles = await getHistoricalCandles({
+  source: "yahoo",
+  symbol: "SPY",
+  interval: "1d",
+  period: "2y",
+  cache: true,
+});
+```
+
+### Sources
+
+- `yahoo`
+- `csv`
+- `auto`
+
+`auto` switches to CSV when `csvPath` or `csv.filePath` is present. Otherwise it uses Yahoo.
+
+If you are writing application code, prefer `getHistoricalCandles()` over calling source-specific helpers directly.
+
+### Yahoo options
+
+| Option | Purpose |
+| --- | --- |
+| `symbol` | Ticker or Yahoo symbol |
+| `interval` | Candle interval such as `1d` or `5m` |
+| `period` | Lookback period such as `6mo` or `1y` |
+| `includePrePost` | Includes premarket and postmarket data when supported |
+| `cache` | Reuses saved normalized data |
+| `refresh` | Forces a fresh download even if cache exists |
+| `cacheDir` | Overrides the default cache directory |
+
+The Yahoo layer retries transient failures with exponential backoff. If the endpoint still fails, the error message points users toward CSV or cached data.
+
+Use caching for repeatable research runs. It reduces network noise and makes failures easier to diagnose.
+
+### CSV options
+
+```js
+const candles = await getHistoricalCandles({
+  source: "csv",
+  csvPath: "./data/spy.csv",
+  csv: {
+    timeCol: "timestamp",
+    openCol: "open",
+    highCol: "high",
+    lowCol: "low",
+    closeCol: "close",
+    volumeCol: "volume",
+  },
+});
+```
+
+CSV parsing can be configured with:
+
+- delimiter
+- header presence
+- column names or indexes
+- start/end date filters
+- custom date parsing
+
+If your CSV already uses common OHLCV column names, you often do not need to pass any mapping at all.
+
+## Cache helpers
+
+Available helpers:
+
+- `saveCandlesToCache(candles, meta)`
+- `loadCandlesFromCache(symbol, interval, period, outDir)`
+- `cachedCandlesPath(symbol, interval, period, outDir)`
+
+The cache is just normalized candle JSON on disk. It is meant for research convenience, not as a durable database layer.
+
+## Common workflows
+
+### Yahoo to backtest
+
+```js
+const candles = await getHistoricalCandles({
+  source: "yahoo",
+  symbol: "SPY",
+  interval: "1d",
+  period: "1y",
+  cache: true,
+});
+```
+
+### CSV to backtest
+
+```js
+const candles = await getHistoricalCandles({
+  source: "csv",
+  csvPath: "./data/spy.csv",
+});
+```
+
+### Cached repeat run
+
+```js
+const candles = await getHistoricalCandles({
+  source: "yahoo",
+  symbol: "SPY",
+  interval: "1d",
+  period: "1y",
+  cache: true,
+  refresh: false,
+});
+```
+
+## Reporting and exports
+
+### `exportBacktestArtifacts({ result, outDir })`
+
+The main bundle export. By default it writes:
+
+- HTML report
+- trade CSV
+- metrics JSON
+
+Return value:
+
+```js
+{
+  csv,
+  html,
+  metrics
+}
+```
+
+If you only need one output type, call the narrower helper directly.
+
+### `exportMetricsJSON({ result, outDir })`
+
+Use this for dashboards, notebooks, or any machine-readable downstream pipeline.
+
+For automation, this is usually the best export format to build on.
+
+### `exportTradesCsv(trades, options)`
+
+Use this when you want a flat trade ledger for spreadsheets or pandas-style workflows.
+
+### `renderHtmlReport(options)` and `exportHtmlReport(options)`
+
+- `renderHtmlReport()` returns an HTML string
+- `exportHtmlReport()` writes the file and returns its path
+
+The report system uses the assets under `templates/`. The renderer injects the payload and keeps markup, CSS, and client script separate from the JS entrypoint.
+
+## CLI
+
+The package ships with a `tradelab` binary.
+
+The CLI is best for quick iteration, smoke tests, and trying the package before building a JS workflow around it.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `tradelab backtest` | Run a single backtest from Yahoo or CSV |
+| `tradelab portfolio` | Run a simple multi-file portfolio backtest |
+| `tradelab walk-forward` | Run rolling or anchored validation with built-in or local strategy search |
+| `tradelab prefetch` | Download and cache Yahoo data |
+| `tradelab import-csv` | Normalize and cache a CSV file |
+
+### Backtest
+
+```bash
+tradelab backtest --source yahoo --symbol SPY --interval 1d --period 1y
+tradelab backtest --source csv --csvPath ./data/btc.csv --strategy buy-hold --holdBars 3
+```
+
+Built-in strategies:
+
+- `ema-cross`
+- `buy-hold`
+
+You can also point `--strategy` at a local module. The module should export one of:
+
+- `default(args)`
+- `createSignal(args)`
+- `signal`
+
+That makes it easy to prototype a strategy file before wiring it into a larger application.
+
+### Portfolio
+
+```bash
+tradelab portfolio \
+  --csvPaths ./data/spy.csv,./data/qqq.csv \
+  --symbols SPY,QQQ \
+  --strategy buy-hold
+```
+
+This command is intentionally simple. Use it for quick combined runs, not for custom portfolio logic.
+
+### Walk-forward
+
+```bash
+tradelab walk-forward \
+  --source yahoo \
+  --symbol QQQ \
+  --interval 1d \
+  --period 2y \
+  --trainBars 180 \
+  --testBars 60 \
+  --mode anchored
+```
+
+The CLI walk-forward command defaults to the built-in `ema-cross` search, but `--strategy ./path/to/module.mjs` can now load a local module that exports `signalFactory(params, args)` and either `parameterSets` or `createParameterSets(args)`. Inline JSON grids are also accepted through `--parameterSets`.
+
+### Cache utilities
+
+```bash
+tradelab prefetch --symbol SPY --interval 1d --period 1y
+tradelab import-csv --csvPath ./data/spy.csv --symbol SPY --interval 1d
+```
+
+## Troubleshooting
+
+| Problem | Check first |
+| --- | --- |
+| Yahoo request errors | enable cache, retry later, or fall back to CSV |
+| Unexpected trade count | `warmupBars`, `flattenAtClose`, and signal frequency |
+| Empty result | candle order, signal logic, and stop/target validity |
+| Confusing CSV import | inspect normalized bars from `loadCandlesFromCSV()` before backtesting |
+| Export confusion | use metrics JSON first if you need programmatic output |
+
+<small>[Back to main page](README.md)</small>

package/docs/examples.md

@@ -0,0 +1,281 @@
+# Strategy examples
+<small>[Back to main page](README.md)</small>
+
+These are research templates. They show how to wire different kinds of data and execution assumptions into the engine without changing the output pipeline.
+
+The five examples cover:
+
+- single-symbol price research
+- tick-level fills
+- external feature overlays
+- model-derived regime filters with walk-forward validation
+- portfolio research with shared capital
+
+---
+
+## 1. Mean reversion pullback
+
+Entry when price is stretched below its 20-bar mean. Exit via stop and take-profit.
+
+```js
+import { backtest, getHistoricalCandles } from "tradelab";
+
+function sma(values, period) {
+  if (values.length < period) return null;
+  return values.slice(-period).reduce((sum, v) => sum + v, 0) / period;
+}
+
+const candles = await getHistoricalCandles({
+  source: "yahoo",
+  symbol: "SPY",
+  interval: "1d",
+  period: "2y",
+  cache: true,
+});
+
+const result = backtest({
+  candles,
+  symbol: "SPY",
+  warmupBars: 25,
+  signal({ candles: history, bar }) {
+    const closes = history.map((c) => c.close);
+    const mean = sma(closes, 20);
+    if (!mean) return null;
+
+    const stretch = (bar.close - mean) / mean;
+    if (stretch > -0.03) return null;
+
+    return {
+      side: "long",
+      entry: bar.close,
+      stop: bar.low * 0.99,
+      rr: 1.5,
+      _maxBarsInTrade: 5,
+    };
+  },
+});
+```
+
+---
+
+## 2. Opening-range breakout on ticks
+
+Breakout logic where fill order matters. `backtestTicks()` resolves fills at tick resolution instead of bar close. The result shape is identical to `backtest()`.
+
+```js
+import { backtestTicks } from "tradelab";
+
+const result = backtestTicks({
+  ticks,
+  symbol: "NQ",
+  equity: 25_000,
+  queueFillProbability: 0.4,
+  costs: {
+    spreadBps: 0.5,
+    slippageByKind: {
+      market: 2,
+      stop: 4,
+    },
+  },
+  signal({ candles: history, bar, index }) {
+    if (index < 30) return null;
+
+    const openingRange = history.slice(0, 30);
+    const rangeHigh = Math.max(...openingRange.map((t) => t.high));
+    const rangeLow = Math.min(...openingRange.map((t) => t.low));
+
+    if (bar.close > rangeHigh) {
+      return { side: "long", entry: rangeHigh, stop: rangeLow, rr: 2 };
+    }
+
+    if (bar.close < rangeLow) {
+      return { side: "short", entry: rangeLow, stop: rangeHigh, rr: 2 };
+    }
+
+    return null;
+  },
+});
+```
+
+`queueFillProbability` controls what fraction of limit touches actually fill. Set it to `1` for optimistic fills, `0` to require the price to trade through.
+
+---
+
+## 3. Sentiment overlay on a candle strategy
+
+Enrich candles with a second data source before the backtest starts. The engine does not care where extra fields come from.
+
+```js
+import { backtest, getHistoricalCandles, ema } from "tradelab";
+
+const candles = await getHistoricalCandles({
+  source: "yahoo",
+  symbol: "AAPL",
+  interval: "1d",
+  period: "2y",
+});
+
+const sentimentByDay = new Map([
+  ["2025-01-02", 0.75],
+  ["2025-01-03", -0.10],
+  // ...
+]);
+
+const enriched = candles.map((bar) => ({
+  ...bar,
+  sentiment:
+    sentimentByDay.get(new Date(bar.time).toISOString().slice(0, 10)) ?? 0,
+}));
+
+const result = backtest({
+  candles: enriched,
+  symbol: "AAPL",
+  warmupBars: 30,
+  signal({ candles: history, bar }) {
+    const closes = history.map((c) => c.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] &&
+      bar.sentiment > 0.5
+    ) {
+      return {
+        side: "long",
+        entry: bar.close,
+        stop: Math.min(...history.slice(-10).map((c) => c.low)),
+        rr: 2,
+      };
+    }
+
+    return null;
+  },
+});
+```
+
+The same pattern works for any precomputed field - regime labels, macro scores, alternative data signals. Compute it outside the engine, attach it to the candle, read it in the signal function.
+
+---
+
+## 4. Precomputed regime filter with anchored walk-forward
+
+LLM or model outputs work best as precomputed fields, not as live callers inside the signal function. Call the model once per bar outside the engine, store the result on the candle, then run a normal walk-forward on top of it.
+
+```js
+import { walkForwardOptimize, getHistoricalCandles, ema } from "tradelab";
+
+const candles = await getHistoricalCandles({
+  source: "yahoo",
+  symbol: "QQQ",
+  interval: "1d",
+  period: "3y",
+});
+
+// call model outside the engine - keep signal() synchronous
+const labeled = await Promise.all(
+  candles.map(async (bar, index) => ({
+    ...bar,
+    regime:
+      index < 20
+        ? "neutral"
+        : await classifyRegime(
+            candles.slice(index - 20, index).map((c) => c.close)
+          ),
+  }))
+);
+
+const wf = walkForwardOptimize({
+  candles: labeled,
+  mode: "anchored",
+  trainBars: 180,
+  testBars: 60,
+  stepBars: 60,
+  scoreBy: "profitFactor",
+  parameterSets: [
+    { fast: 10, slow: 30, regime: "trend" },
+    { fast: 20, slow: 50, regime: "trend" },
+    { fast: 10, slow: 30, regime: "mean-revert" },
+  ],
+  backtestOptions: {
+    warmupBars: 60,
+    flattenAtClose: false,
+  },
+  signalFactory(params) {
+    return ({ candles: history, bar }) => {
+      if (bar.regime !== params.regime) return null;
+
+      const closes = history.map((c) => c.close);
+      const fast = ema(closes, params.fast);
+      const slow = ema(closes, params.slow);
+      const last = closes.length - 1;
+
+      if (fast[last - 1] <= slow[last - 1] && fast[last] > slow[last]) {
+        return {
+          side: "long",
+          entry: bar.close,
+          stop: Math.min(...history.slice(-15).map((c) => c.low)),
+          rr: 2,
+        };
+      }
+
+      return null;
+    };
+  },
+});
+```
+
+Check `wf.bestParamsSummary` for parameter stability across windows. If the winning regime or EMA pair changes every window, the model output probably is not adding signal.
+
+---
+
+## 5. Cross-sectional momentum portfolio
+
+One signal factory across three symbols. Fills compete for the same capital pool at fill time - a position on SPY reduces what QQQ and IWM can size into on the same bar.
+
+```js
+import { backtestPortfolio, ema, getHistoricalCandles } from "tradelab";
+
+function momentumSignal() {
+  return ({ candles: history }) => {
+    if (history.length < 60) return null;
+
+    const closes = history.map((c) => c.close);
+    const fast = ema(closes, 20);
+    const slow = ema(closes, 50);
+    const last = closes.length - 1;
+
+    if (fast[last - 1] <= slow[last - 1] && fast[last] > slow[last]) {
+      return {
+        side: "long",
+        entry: closes[last],
+        stop: Math.min(...history.slice(-20).map((c) => c.low)),
+        rr: 2,
+      };
+    }
+
+    return null;
+  };
+}
+
+const [spy, qqq, iwm] = await Promise.all([
+  getHistoricalCandles({ source: "yahoo", symbol: "SPY", interval: "1d", period: "2y" }),
+  getHistoricalCandles({ source: "yahoo", symbol: "QQQ", interval: "1d", period: "2y" }),
+  getHistoricalCandles({ source: "yahoo", symbol: "IWM", interval: "1d", period: "2y" }),
+]);
+
+const result = backtestPortfolio({
+  equity: 100_000,
+  maxDailyLossPct: 3,
+  systems: [
+    { symbol: "SPY", candles: spy, signal: momentumSignal(), weight: 2, maxAllocationPct: 0.5 },
+    { symbol: "QQQ", candles: qqq, signal: momentumSignal(), weight: 2, maxAllocationPct: 0.5 },
+    { symbol: "IWM", candles: iwm, signal: momentumSignal(), weight: 1, maxAllocationPct: 0.3 },
+  ],
+});
+```
+
+`result.eqSeries` includes `lockedCapital` and `availableCapital` at each realized equity point. Use those to see how often the portfolio was fully deployed versus sitting partially idle.
+
+<small>[Back to main page](README.md)</small>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tradelab",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Backtesting toolkit for Node.js with strategy simulation, historical data loading, and report generation",
   "type": "module",
   "main": "./dist/cjs/index.cjs",
@@ -37,6 +37,7 @@
   },
   "files": [
     "bin",
+    "docs",
     "dist",
     "src",
     "types",