tradelab 0.5.0 → 1.0.0

package/src/engine/portfolio.js

@@ -6,6 +6,12 @@ function asWeight(value) {
   return Number.isFinite(value) && value > 0 ? value : 0;
 }
 
+function describeValue(value) {
+  if (Array.isArray(value)) return `array(length=${value.length})`;
+  if (value === null) return "null";
+  return typeof value;
+}
+
 function buildPortfolioPoint(time, equity, lockedCapital, availableCapital) {
   return {
     time,
@@ -20,6 +26,27 @@ function stableSystemOrder(left, right) {
   return left.index - right.index;
 }
 
+function hashedOrderScore(index, time, seed) {
+  let value = (Number(time) ^ Math.imul(index + 1, 0x9e3779b1) ^ (seed | 0)) >>> 0;
+  value = Math.imul(value ^ (value >>> 16), 0x85ebca6b) >>> 0;
+  value = Math.imul(value ^ (value >>> 13), 0xc2b2ae35) >>> 0;
+  return (value ^ (value >>> 16)) >>> 0;
+}
+
+function orderActiveSystems(active, nextTime, processingOrder, shuffleSeed) {
+  if (processingOrder !== "shuffle") {
+    active.sort(stableSystemOrder);
+    return;
+  }
+
+  active.sort((left, right) => {
+    const leftScore = hashedOrderScore(left.index, nextTime, shuffleSeed);
+    const rightScore = hashedOrderScore(right.index, nextTime, shuffleSeed);
+    if (leftScore !== rightScore) return leftScore - rightScore;
+    return stableSystemOrder(left, right);
+  });
+}
+
 function combineReplay(systemResults, eqSeries, collectReplay) {
   if (!collectReplay) {
     return { frames: [], events: [] };
@@ -115,7 +142,8 @@ function forceExitAll(runners, time) {
  *
  * Existing allocation weights are preserved as default per-system capital caps,
  * but capital is only locked when a fill actually occurs. Systems therefore
- * compete for the same remaining capital at fill time.
+ * compete for the same remaining capital at fill time. `processingOrder` can be
+ * set to `"shuffle"` for fairness testing when multiple systems act on the same bar.
  */
 export function backtestPortfolio({
   systems = [],
@@ -124,9 +152,18 @@ export function backtestPortfolio({
   collectEqSeries = true,
   collectReplay = false,
   maxDailyLossPct = 0,
+  processingOrder = "sequential",
+  shuffleSeed = 0,
 } = {}) {
   if (!Array.isArray(systems) || systems.length === 0) {
-    throw new Error("backtestPortfolio() requires a non-empty systems array");
+    throw new Error(
+      `backtestPortfolio() requires a non-empty systems array, got ${describeValue(systems)}`
+    );
+  }
+  if (processingOrder !== "sequential" && processingOrder !== "shuffle") {
+    throw new Error(
+      `backtestPortfolio() processingOrder must be "sequential" or "shuffle", got ${processingOrder}`
+    );
   }
 
   const weights =
@@ -136,7 +173,9 @@ export function backtestPortfolio({
   const totalWeight = weights.reduce((sumValue, weight) => sumValue + weight, 0);
 
   if (!(totalWeight > 0)) {
-    throw new Error("backtestPortfolio() requires positive allocation weights");
+    throw new Error(
+      `backtestPortfolio() requires positive allocation weights, got allocation=${allocation}`
+    );
   }
 
   const runners = systems.map((system, index) => {
@@ -178,7 +217,7 @@ export function backtestPortfolio({
   while (true) {
     const { nextTime, active } = findNextTimeAndActive(runners);
     if (!Number.isFinite(nextTime)) break;
-    active.sort(stableSystemOrder);
+    orderActiveSystems(active, nextTime, processingOrder, shuffleSeed);
 
     const dayKey = dayKeyET(nextTime);
     if (currentDay === null || dayKey !== currentDay) {
@@ -201,8 +240,10 @@ export function backtestPortfolio({
         canTrade: !portfolioHalted,
         resolveEntrySize({ desiredSize, entryPrice }) {
           const maxLeverage = Math.max(1, systemEntry.runner.options.maxLeverage || 1);
-          const byAvailable = (availableCapital * maxLeverage) / Math.max(1e-12, Math.abs(entryPrice));
-          const bySystemCap = (systemRemainingCapital * maxLeverage) / Math.max(1e-12, Math.abs(entryPrice));
+          const byAvailable =
+            (availableCapital * maxLeverage) / Math.max(1e-12, Math.abs(entryPrice));
+          const bySystemCap =
+            (systemRemainingCapital * maxLeverage) / Math.max(1e-12, Math.abs(entryPrice));
           return Math.min(desiredSize, byAvailable, bySystemCap);
         },
       });
@@ -257,6 +298,12 @@ export function backtestPortfolio({
       }))
     )
     .sort((left, right) => left.exit.time - right.exit.time);
+  const openPositions = systemResults.flatMap((run) =>
+    (run.result.openPositions || []).map((position) => ({
+      ...position,
+      symbol: position.symbol || run.symbol,
+    }))
+  );
   const replay = combineReplay(systemResults, eqSeries, collectReplay);
   const allCandles = systems.flatMap((system) => system.candles || []);
   const orderedCandles = [...allCandles].sort((left, right) => left.time - right.time);
@@ -275,6 +322,7 @@ export function backtestPortfolio({
     range: undefined,
     trades,
     positions,
+    openPositions,
     metrics,
     eqSeries,
     replay,

package/src/engine/walkForward.js

@@ -20,19 +20,19 @@ function stitchEquitySeries(target, source) {
 }
 
 function canonicalParams(params) {
-  const entries = Object.entries(params || {}).sort(([left], [right]) =>
-    left.localeCompare(right)
-  );
+  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
-  ) {
+  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;
@@ -62,8 +62,8 @@ function summarizeBestParams(windows) {
 
     if (
       index > 0 &&
-      (windows[index - 1].bestParamsSignature ??
-        canonicalParams(windows[index - 1].bestParams)) === signature
+      (windows[index - 1].bestParamsSignature ?? canonicalParams(windows[index - 1].bestParams)) ===
+        signature
     ) {
       adjacentRepeats += 1;
     }
@@ -104,13 +104,19 @@ export function walkForwardOptimize({
   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");
@@ -125,6 +131,12 @@ export function walkForwardOptimize({
   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,
@@ -135,6 +147,13 @@ export function walkForwardOptimize({
   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) {
@@ -213,10 +232,14 @@ export function walkForwardOptimize({
     windows,
     trades: allTrades,
     positions: allPositions,
+    openPositions: [],
     metrics,
     eqSeries,
     replay: { frames: [], events: [] },
-    bestParams: Object.assign(windows.map((window) => window.bestParams), bestParamsSummary),
+    bestParams: Object.assign(
+      windows.map((window) => window.bestParams),
+      bestParamsSummary
+    ),
     bestParamsSummary: bestParamsSummary.stability,
   };
 }

package/src/index.js

@@ -18,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";
@@ -38,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);
+}