tradelab 0.5.0 → 1.0.0

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.5.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);