tradelab 0.4.0 → 1.0.0

package/src/engine/walkForward.js

@@ -19,6 +19,73 @@ function stitchEquitySeries(target, source) {
   target.push(...nextPoints);
 }
 
+function canonicalParams(params) {
+  const entries = Object.entries(params || {}).sort(([left], [right]) => left.localeCompare(right));
+  return JSON.stringify(Object.fromEntries(entries));
+}
+
+function describeValue(value) {
+  if (Array.isArray(value)) return `array(length=${value.length})`;
+  if (value === null) return "null";
+  return typeof value;
+}
+
+function buildWindowRanges(length, trainBars, testBars, stepBars, mode) {
+  const ranges = [];
+  for (let start = 0; start + trainBars + testBars <= length; start += stepBars) {
+    const trainStart = mode === "anchored" ? 0 : start;
+    const trainEnd = mode === "anchored" ? trainBars + start : start + trainBars;
+    const testStart = trainEnd;
+    const testEnd = testStart + testBars;
+    if (testEnd > length) break;
+    ranges.push({ trainStart, trainEnd, testStart, testEnd });
+  }
+  return ranges;
+}
+
+function summarizeBestParams(windows) {
+  const summaryBySignature = new Map();
+  let adjacentRepeats = 0;
+
+  windows.forEach((window, index) => {
+    const signature = window.bestParamsSignature ?? canonicalParams(window.bestParams);
+    const current = summaryBySignature.get(signature) || {
+      params: window.bestParams,
+      wins: 0,
+      profitableWindows: 0,
+      oosTrades: 0,
+    };
+    current.wins += 1;
+    current.profitableWindows += window.profitable ? 1 : 0;
+    current.oosTrades += window.oosTrades;
+    summaryBySignature.set(signature, current);
+
+    if (
+      index > 0 &&
+      (windows[index - 1].bestParamsSignature ?? canonicalParams(windows[index - 1].bestParams)) ===
+        signature
+    ) {
+      adjacentRepeats += 1;
+    }
+  });
+
+  const byFrequency = [...summaryBySignature.values()].sort((left, right) => {
+    if (right.wins !== left.wins) return right.wins - left.wins;
+    return right.profitableWindows - left.profitableWindows;
+  });
+  const adjacentPairs = Math.max(0, windows.length - 1);
+
+  return {
+    winners: windows.map((window) => window.bestParams),
+    stability: {
+      adjacentRepeatRate: adjacentPairs ? adjacentRepeats / adjacentPairs : 0,
+      uniqueWinnerCount: summaryBySignature.size,
+      dominant: byFrequency[0] || null,
+      leaderboard: byFrequency,
+    },
+  };
+}
+
 /**
  * Run rolling walk-forward optimization over a single candle series.
  *
@@ -32,40 +99,66 @@ export function walkForwardOptimize({
   trainBars,
   testBars,
   stepBars = testBars,
+  mode = "rolling",
   scoreBy = "profitFactor",
   backtestOptions = {},
 } = {}) {
   if (!Array.isArray(candles) || candles.length === 0) {
-    throw new Error("walkForwardOptimize() requires a non-empty candles array");
+    throw new Error(
+      `walkForwardOptimize() requires a non-empty candles array, got ${describeValue(candles)}`
+    );
   }
   if (typeof signalFactory !== "function") {
-    throw new Error("walkForwardOptimize() requires a signalFactory function");
+    throw new Error(
+      `walkForwardOptimize() requires a signalFactory function, got ${describeValue(signalFactory)}`
+    );
   }
   if (!Array.isArray(parameterSets) || parameterSets.length === 0) {
-    throw new Error("walkForwardOptimize() requires parameterSets");
+    throw new Error(
+      `walkForwardOptimize() requires parameterSets, got ${describeValue(parameterSets)}`
+    );
   }
   if (!(trainBars > 0) || !(testBars > 0) || !(stepBars > 0)) {
     throw new Error("walkForwardOptimize() requires positive trainBars, testBars, and stepBars");
   }
+  if (mode !== "rolling" && mode !== "anchored") {
+    throw new Error('walkForwardOptimize() mode must be "rolling" or "anchored"');
+  }
 
   const windows = [];
   const allTrades = [];
   const allPositions = [];
   const eqSeries = [];
   let rollingEquity = backtestOptions.equity ?? 10_000;
+  const ranges = buildWindowRanges(candles.length, trainBars, testBars, stepBars, mode);
+  if (!ranges.length) {
+    const required = trainBars + testBars;
+    throw new Error(
+      `walkForwardOptimize() produced zero windows: need at least ${required} candles (trainBars=${trainBars} + testBars=${testBars}) but got ${candles.length}. Try reducing trainBars/testBars or adding more historical data.`
+    );
+  }
+  const trainBacktestOptions = {
+    ...backtestOptions,
+    collectEqSeries: false,
+    collectReplay: false,
+  };
+  const testBacktestOptions = { ...backtestOptions };
 
-  for (
-    let start = 0;
-    start + trainBars + testBars <= candles.length;
-    start += stepBars
-  ) {
-    const trainSlice = candles.slice(start, start + trainBars);
-    const testSlice = candles.slice(start + trainBars, start + trainBars + testBars);
+  for (const range of ranges) {
+    const trainSlice = candles.slice(range.trainStart, range.trainEnd);
+    const testSlice = candles.slice(range.testStart, range.testEnd);
+    if (!trainSlice.length || !testSlice.length) {
+      throw new Error(
+        `walkForwardOptimize() generated an empty window (train=${trainSlice.length}, test=${testSlice.length}, range=${JSON.stringify(
+          range
+        )})`
+      );
+    }
 
     let best = null;
     for (const params of parameterSets) {
       const trainResult = backtest({
-        ...backtestOptions,
+        ...trainBacktestOptions,
         candles: trainSlice,
         equity: rollingEquity,
         signal: signalFactory(params),
@@ -77,11 +170,12 @@ export function walkForwardOptimize({
     }
 
     const testResult = backtest({
-      ...backtestOptions,
+      ...testBacktestOptions,
       candles: testSlice,
       equity: rollingEquity,
       signal: signalFactory(best.params),
     });
+    const bestParamsSignature = canonicalParams(best.params);
 
     rollingEquity = testResult.metrics.finalEquity;
     allTrades.push(...testResult.trades);
@@ -101,10 +195,29 @@ export function walkForwardOptimize({
       trainScore: best.score,
       trainMetrics: best.metrics,
       testMetrics: testResult.metrics,
+      oosTrades: testResult.metrics.trades,
+      profitable: testResult.metrics.totalPnL > 0,
+      stabilityScore: 0,
+      bestParamsSignature,
       result: testResult,
     });
   }
 
+  for (let index = 0; index < windows.length; index += 1) {
+    const currentSignature = windows[index].bestParamsSignature;
+    const adjacent = [];
+    if (index > 0) {
+      adjacent.push(windows[index - 1].bestParamsSignature === currentSignature ? 1 : 0);
+    }
+    if (index + 1 < windows.length) {
+      adjacent.push(windows[index + 1].bestParamsSignature === currentSignature ? 1 : 0);
+    }
+    windows[index].stabilityScore = adjacent.length
+      ? adjacent.reduce((total, value) => total + value, 0) / adjacent.length
+      : 1;
+    delete windows[index].bestParamsSignature;
+  }
+
   const metrics = buildMetrics({
     closed: allTrades,
     equityStart: backtestOptions.equity ?? 10_000,
@@ -113,14 +226,20 @@ export function walkForwardOptimize({
     estBarMs: estimateBarMs(candles),
     eqSeries,
   });
+  const bestParamsSummary = summarizeBestParams(windows);
 
   return {
     windows,
     trades: allTrades,
     positions: allPositions,
+    openPositions: [],
     metrics,
     eqSeries,
     replay: { frames: [], events: [] },
-    bestParams: windows.map((window) => window.bestParams),
+    bestParams: Object.assign(
+      windows.map((window) => window.bestParams),
+      bestParamsSummary
+    ),
+    bestParamsSummary: bestParamsSummary.stability,
   };
 }

package/src/index.js

@@ -1,4 +1,5 @@
 export { backtest } from "./engine/backtest.js";
+export { backtestTicks } from "./engine/backtestTicks.js";
 export { backtestPortfolio } from "./engine/portfolio.js";
 export { walkForwardOptimize } from "./engine/walkForward.js";
 
@@ -17,10 +18,7 @@ export {
   saveCandlesToCache,
 } from "./data/index.js";
 
-export {
-  renderHtmlReport,
-  exportHtmlReport,
-} from "./reporting/renderHtmlReport.js";
+export { renderHtmlReport, exportHtmlReport } from "./reporting/renderHtmlReport.js";
 export { exportTradesCsv } from "./reporting/exportTradesCsv.js";
 export { exportMetricsJSON } from "./reporting/exportMetricsJson.js";
 export { exportBacktestArtifacts } from "./reporting/exportBacktestArtifacts.js";
@@ -37,10 +35,4 @@ export {
   pct,
 } from "./utils/indicators.js";
 export { calculatePositionSize } from "./utils/positionSizing.js";
-export {
-  offsetET,
-  minutesET,
-  isSession,
-  parseWindowsCSV,
-  inWindowsET,
-} from "./utils/time.js";
+export { offsetET, minutesET, isSession, parseWindowsCSV, inWindowsET } from "./utils/time.js";

package/src/live/broker/alpaca.js

@@ -0,0 +1,254 @@
+import { URL } from "node:url";
+
+import { normalizeCandles } from "../../data/csv.js";
+import { BrokerAdapter } from "./interface.js";
+
+function withQuery(url, query = {}) {
+  const target = new URL(url);
+  for (const [key, value] of Object.entries(query)) {
+    if (value === undefined || value === null) continue;
+    target.searchParams.set(key, String(value));
+  }
+  return target.toString();
+}
+
+function mapOrderStatus(status) {
+  const normalized = String(status || "").toLowerCase();
+  if (normalized === "partially_filled") return "partially_filled";
+  if (normalized === "filled") return "filled";
+  if (normalized === "canceled" || normalized === "cancelled") return "canceled";
+  if (normalized === "rejected") return "rejected";
+  if (normalized === "expired") return "expired";
+  return "new";
+}
+
+function mapOrderReceipt(order) {
+  return {
+    orderId: String(order.id),
+    clientOrderId: order.client_order_id,
+    status: mapOrderStatus(order.status),
+    filledQty: Number(order.filled_qty || 0),
+    avgFillPrice: Number.isFinite(Number(order.filled_avg_price))
+      ? Number(order.filled_avg_price)
+      : undefined,
+    filledAt: order.filled_at ? Date.parse(order.filled_at) : undefined,
+    symbol: order.symbol,
+    side: order.side,
+    type: String(order.type || "").toLowerCase(),
+    qty: Number(order.qty || 0),
+    rejectReason: order.reject_reason,
+  };
+}
+
+/**
+ * Alpaca Markets broker adapter.
+ */
+export class AlpacaBroker extends BrokerAdapter {
+  constructor({ fetchImpl = globalThis.fetch } = {}) {
+    super();
+    this.fetch = fetchImpl;
+    this.connected = false;
+    this.config = {};
+    this.subscriptions = {
+      bars: new Map(),
+      quotes: new Map(),
+      trades: new Map(),
+    };
+  }
+
+  async connect(config = {}) {
+    this.config = { ...config };
+    this.baseUrl =
+      config.baseUrl ||
+      (config.paper ? "https://paper-api.alpaca.markets" : "https://api.alpaca.markets");
+    this.dataUrl = config.dataUrl || "https://data.alpaca.markets";
+    this.connected = true;
+  }
+
+  async disconnect() {
+    this.connected = false;
+    this.subscriptions.bars.clear();
+    this.subscriptions.quotes.clear();
+    this.subscriptions.trades.clear();
+  }
+
+  isConnected() {
+    return this.connected;
+  }
+
+  supportsPaperNative() {
+    return true;
+  }
+
+  _headers(extra = {}) {
+    return {
+      "content-type": "application/json",
+      "APCA-API-KEY-ID": this.config.apiKey || "",
+      "APCA-API-SECRET-KEY": this.config.apiSecret || "",
+      ...extra,
+    };
+  }
+
+  async _request(method, path, { query = null, body = null, dataApi = false } = {}) {
+    if (!this.fetch) throw new Error("global fetch is unavailable");
+    const base = dataApi ? this.dataUrl : this.baseUrl;
+    const url = withQuery(`${base}${path}`, query || {});
+    const response = await this.fetch(url, {
+      method,
+      headers: this._headers(),
+      body: body ? JSON.stringify(body) : undefined,
+    });
+    const text = await response.text();
+    const payload = text ? JSON.parse(text) : {};
+    if (!response.ok) {
+      const message =
+        payload?.message || payload?.error || `alpaca request failed (${response.status})`;
+      throw new Error(message);
+    }
+    return payload;
+  }
+
+  async getAccount() {
+    const account = await this._request("GET", "/v2/account");
+    return {
+      equity: Number(account.equity || 0),
+      buyingPower: Number(account.buying_power || 0),
+      cash: Number(account.cash || 0),
+      currency: account.currency || "USD",
+      marginUsed: Number(account.initial_margin || 0),
+    };
+  }
+
+  async getPositions() {
+    const positions = await this._request("GET", "/v2/positions");
+    return positions.map((position) => ({
+      symbol: position.symbol,
+      side: String(position.side || "long").toLowerCase(),
+      qty: Number(position.qty || 0),
+      avgEntry: Number(position.avg_entry_price || 0),
+      marketValue: Number(position.market_value || 0),
+      unrealizedPnl: Number(position.unrealized_pl || 0),
+    }));
+  }
+
+  async getServerTime() {
+    const clock = await this._request("GET", "/v2/clock");
+    return clock.timestamp ? Date.parse(clock.timestamp) : Date.now();
+  }
+
+  async submitOrder(order) {
+    const payload = {
+      symbol: order.symbol,
+      side: order.side,
+      type: order.type,
+      qty: String(order.qty),
+      time_in_force: order.timeInForce || "day",
+      client_order_id: order.clientOrderId,
+    };
+    if (order.limitPrice !== undefined) payload.limit_price = String(order.limitPrice);
+    if (order.stopPrice !== undefined) payload.stop_price = String(order.stopPrice);
+    const response = await this._request("POST", "/v2/orders", { body: payload });
+    const receipt = mapOrderReceipt(response);
+    this.emit("order:submitted", receipt);
+    return receipt;
+  }
+
+  async cancelOrder(orderId) {
+    await this._request("DELETE", `/v2/orders/${orderId}`);
+    this.emit("order:canceled", { orderId });
+  }
+
+  async modifyOrder(orderId, changes) {
+    const payload = {};
+    if (changes.qty !== undefined) payload.qty = String(changes.qty);
+    if (changes.limitPrice !== undefined) payload.limit_price = String(changes.limitPrice);
+    if (changes.stopPrice !== undefined) payload.stop_price = String(changes.stopPrice);
+    const response = await this._request("PATCH", `/v2/orders/${orderId}`, { body: payload });
+    const receipt = mapOrderReceipt(response);
+    this.emit("order:modified", receipt);
+    return receipt;
+  }
+
+  async getOpenOrders() {
+    const orders = await this._request("GET", "/v2/orders", { query: { status: "open" } });
+    return orders.map(mapOrderReceipt);
+  }
+
+  async getOrderStatus(orderId) {
+    const order = await this._request("GET", `/v2/orders/${orderId}`);
+    return mapOrderReceipt(order);
+  }
+
+  async subscribeQuotes(symbol, handler) {
+    const key = symbol;
+    const list = this.subscriptions.quotes.get(key) || [];
+    list.push(handler);
+    this.subscriptions.quotes.set(key, list);
+    return {
+      unsubscribe: () => {
+        const current = this.subscriptions.quotes.get(key) || [];
+        this.subscriptions.quotes.set(
+          key,
+          current.filter((candidate) => candidate !== handler)
+        );
+      },
+    };
+  }
+
+  async subscribeTrades(symbol, handler) {
+    const key = symbol;
+    const list = this.subscriptions.trades.get(key) || [];
+    list.push(handler);
+    this.subscriptions.trades.set(key, list);
+    return {
+      unsubscribe: () => {
+        const current = this.subscriptions.trades.get(key) || [];
+        this.subscriptions.trades.set(
+          key,
+          current.filter((candidate) => candidate !== handler)
+        );
+      },
+    };
+  }
+
+  async subscribeBars(symbol, interval, handler) {
+    const key = `${symbol}::${interval}`;
+    const list = this.subscriptions.bars.get(key) || [];
+    list.push(handler);
+    this.subscriptions.bars.set(key, list);
+    return {
+      unsubscribe: () => {
+        const current = this.subscriptions.bars.get(key) || [];
+        this.subscriptions.bars.set(
+          key,
+          current.filter((candidate) => candidate !== handler)
+        );
+      },
+    };
+  }
+
+  async getHistoricalBars(symbol, interval, limit = 200) {
+    const response = await this._request("GET", `/v2/stocks/${symbol}/bars`, {
+      dataApi: true,
+      query: {
+        timeframe: interval,
+        limit,
+      },
+    });
+    const bars = Array.isArray(response?.bars)
+      ? response.bars.map((bar) => ({
+          time: Date.parse(bar.t),
+          open: Number(bar.o),
+          high: Number(bar.h),
+          low: Number(bar.l),
+          close: Number(bar.c),
+          volume: Number(bar.v ?? 0),
+        }))
+      : [];
+    return normalizeCandles(bars);
+  }
+}
+
+export function createAlpacaBroker(options) {
+  return new AlpacaBroker(options);
+}