tradelab 0.4.0 → 1.0.0

package/docs/examples.md

@@ -0,0 +1,275 @@
+# 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.1],
+  // ...
+]);
+
+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/docs/live-trading.md

@@ -0,0 +1,186 @@
+# Live trading
+
+<small>[Back to main page](README.md)</small>
+
+This guide covers the `tradelab/live` module and the live CLI commands.
+
+## Overview
+
+The live stack is built to reuse the same signal contract as backtesting:
+
+- write and validate `signal()` with `backtest()`
+- run the same signal in `LiveEngine` or `LiveOrchestrator`
+- choose a real broker adapter or `PaperEngine`
+- persist state with `JsonFileStorage` for restart safety
+
+Import path:
+
+```js
+import { LiveEngine, LiveOrchestrator, PaperEngine } from "tradelab/live";
+```
+
+## Module components
+
+| Component                                                                        | Purpose                                                              |
+| -------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| `LiveEngine`                                                                     | Single-system live or paper execution loop                           |
+| `LiveOrchestrator`                                                               | Multi-system live execution with shared broker and aggregated status |
+| `PaperEngine`                                                                    | In-process broker simulator implementing the broker adapter contract |
+| `AlpacaBroker` / `BinanceBroker` / `CoinbaseBroker` / `InteractiveBrokersBroker` | Real broker adapters                                                 |
+| `BrokerFeed` / `PollingFeed`                                                     | Feed adapters for streaming or polling operation                     |
+| `RiskManager`                                                                    | Session windows, daily loss gates, drawdown halts, position checks   |
+| `StateManager` / `JsonFileStorage`                                               | Persisted state, trades, and equity curve                            |
+| `EventBus` / `LiveLogger`                                                        | Event fanout and structured logging                                  |
+
+## `LiveEngine` quick start
+
+```js
+import { LiveEngine, PaperEngine, JsonFileStorage } from "tradelab/live";
+
+const engine = new LiveEngine({
+  id: "aapl-1m",
+  symbol: "AAPL",
+  interval: "1m",
+  broker: new PaperEngine({ equity: 25_000 }),
+  storage: new JsonFileStorage({ baseDir: "./output/live-state" }),
+  riskPct: 1,
+  mode: "streaming",
+  signal({ bar, openPosition }) {
+    if (openPosition) return null;
+    return {
+      side: "long",
+      stop: bar.close - 1,
+      rr: 2,
+    };
+  },
+});
+
+await engine.start();
+// ... run until shutdown condition
+await engine.stop();
+```
+
+Important behavior:
+
+- `signal()` is called with the same context shape as backtesting
+- market and limit/stop order lifecycles are tracked through broker events
+- state is persisted after fills, order updates, and equity updates
+- `getStatus()` returns runtime and risk state for health checks
+
+## `LiveOrchestrator` quick start
+
+```js
+import { LiveOrchestrator, PaperEngine, JsonFileStorage } from "tradelab/live";
+
+const orchestrator = new LiveOrchestrator({
+  broker: new PaperEngine({ equity: 100_000 }),
+  storage: new JsonFileStorage({ baseDir: "./output/live-state" }),
+  allocation: "weight",
+  systems: [
+    { id: "spy", symbol: "SPY", interval: "1m", weight: 2, signal: signalA },
+    { id: "qqq", symbol: "QQQ", interval: "1m", weight: 1, signal: signalB },
+  ],
+});
+
+await orchestrator.start();
+const status = orchestrator.getStatus();
+await orchestrator.stop();
+```
+
+Use orchestrator when multiple systems should share one broker/account context.
+
+## CLI live commands
+
+| Command           | Purpose                                      |
+| ----------------- | -------------------------------------------- |
+| `tradelab live`   | Run live engine or orchestrator (`--config`) |
+| `tradelab paper`  | Shortcut for `live` with paper broker mode   |
+| `tradelab status` | Inspect persisted live state                 |
+
+### Single-system paper run
+
+```bash
+tradelab paper \
+  --id aapl-1m \
+  --symbol AAPL \
+  --interval 1m \
+  --mode polling \
+  --once true \
+  --stateDir ./output/live-state
+```
+
+### Orchestrator run from config
+
+```bash
+tradelab live \
+  --config ./live-portfolio.json \
+  --paper \
+  --mode polling \
+  --once true \
+  --stateDir ./output/live-state
+```
+
+Example config:
+
+```json
+{
+  "allocation": "weight",
+  "equity": 50000,
+  "systems": [
+    {
+      "id": "spy-system",
+      "symbol": "SPY",
+      "interval": "1m",
+      "strategy": "./strategies/spySignal.js",
+      "weight": 2
+    },
+    {
+      "id": "qqq-system",
+      "symbol": "QQQ",
+      "interval": "1m",
+      "strategy": "./strategies/qqqSignal.js",
+      "weight": 1
+    }
+  ]
+}
+```
+
+### State inspection
+
+```bash
+tradelab status --dir ./output/live-state
+tradelab status --dir ./output/live-state --namespace spy-system
+```
+
+## State and recovery
+
+Live state is namespaced and persisted as:
+
+- `state.json` (latest engine state)
+- `trades.jsonl` (append-only)
+- `equity.jsonl` (append-only)
+
+On restart, the engine loads persisted state and reconciles with broker positions.
+
+## Broker notes
+
+- Alpaca and Binance adapters support native paper modes.
+- Coinbase adapter is live API only; use `PaperEngine` for simulated Coinbase workflows.
+- Interactive Brokers adapter requires `@stoqey/ib` to be installed.
+
+For runtime compatibility and options, see [types/live.d.ts](../types/live.d.ts).
+
+## Eventing and logs
+
+`EventBus` emits lifecycle and execution events such as:
+
+- `connected`, `shutdown`
+- `signal`
+- `order:submitted`, `order:filled`, `order:rejected`, `order:canceled`
+- `position:opened`, `position:closed`
+- `equity:update`
+- `risk:warning`, `risk:halt`
+
+Attach `LiveLogger` for structured JSON logs.
+
+<small>[Back to main page](README.md)</small>

package/examples/yahooEmaCross.js

@@ -1,12 +1,7 @@
 import path from "path";
 import { fileURLToPath } from "url";
 
-import {
-  backtest,
-  ema,
-  exportBacktestArtifacts,
-  getHistoricalCandles,
-} from "../src/index.js";
+import { backtest, ema, exportBacktestArtifacts, getHistoricalCandles } from "../src/index.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tradelab",
-  "version": "0.4.0",
+  "version": "1.0.0",
   "description": "Backtesting toolkit for Node.js with strategy simulation, historical data loading, and report generation",
   "type": "module",
   "main": "./dist/cjs/index.cjs",
@@ -33,6 +33,11 @@
       "import": "./src/data/index.js",
       "require": "./dist/cjs/data.cjs"
     },
+    "./live": {
+      "types": "./types/live.d.ts",
+      "import": "./src/live/index.js",
+      "require": "./dist/cjs/live.cjs"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -48,8 +53,12 @@
   ],
   "scripts": {
     "build": "node scripts/build-cjs.mjs",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier . --write",
+    "format:check": "prettier . --check",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
     "prepare": "npm run build",
-    "prepack": "npm run build",
     "test": "node --test"
   },
   "keywords": [
@@ -67,6 +76,12 @@
     "access": "public"
   },
   "devDependencies": {
-    "esbuild": "^0.27.3"
+    "@eslint/js": "^9.25.1",
+    "@types/node": "^22.15.2",
+    "esbuild": "^0.27.3",
+    "eslint": "^9.25.1",
+    "globals": "^15.15.0",
+    "prettier": "^3.5.3",
+    "typescript": "^5.8.3"
   }
 }

package/src/data/csv.js

@@ -21,7 +21,9 @@ function resolveDate(value, customDateParser) {
     if (Number.isFinite(time)) return time;
   }
 
-  const raw = String(value).trim().replace(/^['"]|['"]$/g, "");
+  const raw = String(value)
+    .trim()
+    .replace(/^['"]|['"]$/g, "");
   const numeric = Number(raw);
   if (Number.isFinite(numeric)) {
     return numeric < 1e11 ? numeric * 1000 : numeric;
@@ -108,7 +110,7 @@ function normalizeDateBoundary(value, fallback) {
 export function normalizeCandles(candles) {
   if (!Array.isArray(candles)) return [];
 
-  const normalized = candles
+  const parsed = candles
     .map((bar) => {
       try {
         const time = resolveDate(bar?.time ?? bar?.timestamp ?? bar?.date);
@@ -140,8 +142,18 @@ export function normalizeCandles(candles) {
         return null;
       }
     })
-    .filter(Boolean)
-    .sort((left, right) => left.time - right.time);
+    .filter(Boolean);
+
+  let reordered = false;
+  let duplicateCount = 0;
+  for (let index = 1; index < parsed.length; index += 1) {
+    const prev = parsed[index - 1].time;
+    const current = parsed[index].time;
+    if (current < prev) reordered = true;
+    if (current === prev) duplicateCount += 1;
+  }
+
+  const normalized = parsed.sort((left, right) => left.time - right.time);
 
   const deduped = [];
   let lastTime = null;
@@ -150,6 +162,12 @@ export function normalizeCandles(candles) {
     deduped.push(candle);
     lastTime = candle.time;
   }
+  const removedDuplicates = normalized.length - deduped.length;
+  if (reordered || removedDuplicates > 0 || duplicateCount > 0) {
+    console.warn(
+      `[tradelab] normalizeCandles() reordered or deduplicated candles (input=${candles.length}, valid=${parsed.length}, output=${deduped.length})`
+    );
+  }
   return deduped;
 }
 
@@ -197,16 +215,8 @@ export function loadCandlesFromCSV(filePath, options = {}) {
   const closeIdx = resolveColumn(closeCol, headerIndex, ["c", "adj close"]);
   const volumeIdx = resolveColumn(volumeCol, headerIndex, ["v", "vol", "quantity"]);
 
-  if (
-    timeIdx < 0 ||
-    openIdx < 0 ||
-    highIdx < 0 ||
-    lowIdx < 0 ||
-    closeIdx < 0
-  ) {
-    throw new Error(
-      `Could not resolve required CSV columns in ${path.basename(filePath)}`
-    );
+  if (timeIdx < 0 || openIdx < 0 || highIdx < 0 || lowIdx < 0 || closeIdx < 0) {
+    throw new Error(`Could not resolve required CSV columns in ${path.basename(filePath)}`);
   }
 
   const minTime = normalizeDateBoundary(startDate, -Infinity);

package/src/data/index.js

@@ -97,11 +97,7 @@ export async function getHistoricalCandles(options = {}) {
   return candles;
 }
 
-export async function backtestHistorical({
-  backtestOptions = {},
-  data,
-  ...legacy
-} = {}) {
+export async function backtestHistorical({ backtestOptions = {}, data, ...legacy } = {}) {
   const candles = await getHistoricalCandles(data || legacy);
   return runBacktest({
     candles,

package/src/data/yahoo.js

@@ -1,7 +1,6 @@
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
 const DAY_MS = 24 * 60 * 60 * 1000;
-const DAY_SEC = 24 * 60 * 60;
 const requestQueue = {
   lastRequestAt: 0,
   minDelayMs: 400,
@@ -111,8 +110,7 @@ async function rateLimitedFetch(url, options = {}) {
   return fetch(url, {
     ...options,
     headers: {
-      "User-Agent":
-        "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
+      "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
       ...options.headers,
     },
   });
@@ -152,12 +150,7 @@ async function fetchYahooChart(symbol, { period1, period2, interval, includePreP
 
   const candles = [];
   for (let index = 0; index < timestamps.length; index += 1) {
-    if (
-      open[index] == null ||
-      high[index] == null ||
-      low[index] == null ||
-      close[index] == null
-    ) {
+    if (open[index] == null || high[index] == null || low[index] == null || close[index] == null) {
       continue;
     }
 
@@ -179,7 +172,7 @@ function formatYahooFailureMessage(symbol, interval, period, error, attempts) {
   return [
     `Unable to reach Yahoo Finance for ${symbol} ${interval} ${period} after ${attempts} attempts.`,
     `Last error: ${detail}`,
-    "Try again later, or fall back to a local CSV/cache workflow with getHistoricalCandles({ source: \"csv\", ... }) or loadCandlesFromCache(...).",
+    'Try again later, or fall back to a local CSV/cache workflow with getHistoricalCandles({ source: "csv", ... }) or loadCandlesFromCache(...).',
   ].join(" ");
 }
 
@@ -203,13 +196,7 @@ async function fetchYahooChartWithRetry(symbol, params, period, maxRetries = 3)
   }
 
   throw new Error(
-    formatYahooFailureMessage(
-      symbol,
-      params.interval,
-      period,
-      lastError,
-      maxRetries
-    )
+    formatYahooFailureMessage(symbol, params.interval, period, lastError, maxRetries)
   );
 }
 
@@ -253,10 +240,10 @@ export async function fetchHistorical(symbol, interval = "5m", period = "60d", o
       period
     );
     chunks.push(...candles);
-    chunkEndMs = chunkStartMs - 1000;
     remainingMs -= takeMs;
+    chunkEndMs = chunkStartMs - 1000;
 
-    if (chunks.length > 2_000_000) break;
+    if (chunkEndMs <= 0 || chunks.length > 2_000_000) break;
   }
 
   return sanitizeBars(chunks);