tradelab 1.0.0 → 1.1.0

package/src/ta/oscillators.js

@@ -0,0 +1,70 @@
+// src/ta/oscillators.js
+import { ema } from "../utils/indicators.js";
+
+/**
+ * Wilder's RSI. Returns a full-length array; warmup positions are `undefined`.
+ */
+export function rsi(closes, period = 14) {
+  const out = new Array(closes.length).fill(undefined);
+  if (closes.length <= period) return out;
+
+  let gainSum = 0;
+  let lossSum = 0;
+  for (let i = 1; i <= period; i += 1) {
+    const change = closes[i] - closes[i - 1];
+    if (change >= 0) gainSum += change;
+    else lossSum -= change;
+  }
+  let avgGain = gainSum / period;
+  let avgLoss = lossSum / period;
+  out[period] = avgLoss === 0 ? 100 : 100 - 100 / (1 + avgGain / avgLoss);
+
+  for (let i = period + 1; i < closes.length; i += 1) {
+    const change = closes[i] - closes[i - 1];
+    const gain = change > 0 ? change : 0;
+    const loss = change < 0 ? -change : 0;
+    avgGain = (avgGain * (period - 1) + gain) / period;
+    avgLoss = (avgLoss * (period - 1) + loss) / period;
+    out[i] = avgLoss === 0 ? 100 : 100 - 100 / (1 + avgGain / avgLoss);
+  }
+  return out;
+}
+
+/**
+ * MACD line, signal line, histogram. All full-length, aligned to input.
+ */
+export function macd(closes, fast = 12, slow = 26, signalPeriod = 9) {
+  const emaFast = ema(closes, fast);
+  const emaSlow = ema(closes, slow);
+  const macdLine = closes.map((_, i) => emaFast[i] - emaSlow[i]);
+  const signalLine = ema(macdLine, signalPeriod);
+  const histogram = macdLine.map((v, i) => v - signalLine[i]);
+  return { macd: macdLine, signal: signalLine, histogram };
+}
+
+/**
+ * Stochastic oscillator %K (smoothed close position in the high-low range) and
+ * %D (SMA of %K). `bars` need { high, low, close }.
+ */
+export function stochastic(bars, kPeriod = 14, dPeriod = 3) {
+  const k = new Array(bars.length).fill(undefined);
+  for (let i = kPeriod - 1; i < bars.length; i += 1) {
+    let hh = -Infinity;
+    let ll = Infinity;
+    for (let j = i - kPeriod + 1; j <= i; j += 1) {
+      if (bars[j].high > hh) hh = bars[j].high;
+      if (bars[j].low < ll) ll = bars[j].low;
+    }
+    const range = hh - ll;
+    k[i] = range === 0 ? 0 : ((bars[i].close - ll) / range) * 100;
+  }
+
+  const d = new Array(bars.length).fill(undefined);
+  for (let i = 0; i < bars.length; i += 1) {
+    if (i < kPeriod - 1 + dPeriod - 1) continue;
+    let sum = 0;
+    for (let j = i - dPeriod + 1; j <= i; j += 1) sum += k[j];
+    d[i] = sum / dPeriod;
+  }
+  return { k, d };
+}

package/src/ta/trend.js

@@ -0,0 +1,78 @@
+// src/ta/trend.js
+import { atr } from "../utils/indicators.js";
+
+/**
+ * Supertrend. Returns { line, direction } full-length.
+ * direction: 1 = uptrend (line is support below price), -1 = downtrend.
+ */
+export function supertrend(bars, period = 10, mult = 3) {
+  const range = atr(bars, period);
+  const line = new Array(bars.length).fill(undefined);
+  const direction = new Array(bars.length).fill(undefined);
+
+  let prevUpper = Infinity;
+  let prevLower = -Infinity;
+  let prevDir = 1;
+
+  for (let i = 0; i < bars.length; i += 1) {
+    if (range[i] === undefined) continue;
+    const mid = (bars[i].high + bars[i].low) / 2;
+    const basicUpper = mid + mult * range[i];
+    const basicLower = mid - mult * range[i];
+    const close = bars[i].close;
+    const prevClose = i > 0 ? bars[i - 1].close : close;
+
+    const upper = basicUpper < prevUpper || prevClose > prevUpper ? basicUpper : prevUpper;
+    const lower = basicLower > prevLower || prevClose < prevLower ? basicLower : prevLower;
+
+    let dir = prevDir;
+    if (prevDir === 1 && close < lower) dir = -1;
+    else if (prevDir === -1 && close > upper) dir = 1;
+
+    line[i] = dir === 1 ? lower : upper;
+    direction[i] = dir;
+
+    prevUpper = upper;
+    prevLower = lower;
+    prevDir = dir;
+  }
+  return { line, direction };
+}
+
+function dayKeyUTC(timeMs) {
+  const d = new Date(timeMs);
+  return d.getUTCFullYear() * 10000 + (d.getUTCMonth() + 1) * 100 + d.getUTCDate();
+}
+
+/**
+ * Session VWAP, reset on each UTC calendar day. `bars` need
+ * { time, high, low, close, volume }. When volume is missing/zero, falls back
+ * to an unweighted cumulative typical-price average for that day.
+ */
+export function vwap(bars) {
+  const out = new Array(bars.length).fill(undefined);
+  let currentDay = null;
+  let cumPV = 0;
+  let cumV = 0;
+  let cumTP = 0;
+  let count = 0;
+
+  for (let i = 0; i < bars.length; i += 1) {
+    const day = dayKeyUTC(bars[i].time);
+    if (day !== currentDay) {
+      currentDay = day;
+      cumPV = 0;
+      cumV = 0;
+      cumTP = 0;
+      count = 0;
+    }
+    const tp = (bars[i].high + bars[i].low + bars[i].close) / 3;
+    const vol = Number.isFinite(bars[i].volume) ? bars[i].volume : 0;
+    cumPV += tp * vol;
+    cumV += vol;
+    cumTP += tp;
+    count += 1;
+    out[i] = cumV > 0 ? cumPV / cumV : cumTP / count;
+  }
+  return out;
+}

package/src/utils/random.js

@@ -0,0 +1,33 @@
+function xmur3(str) {
+  let h = 1779033703 ^ str.length;
+  for (let i = 0; i < str.length; i += 1) {
+    h = Math.imul(h ^ str.charCodeAt(i), 3432918353);
+    h = (h << 13) | (h >>> 19);
+  }
+  return () => {
+    h = Math.imul(h ^ (h >>> 16), 2246822507);
+    h = Math.imul(h ^ (h >>> 13), 3266489909);
+    return (h ^= h >>> 16) >>> 0;
+  };
+}
+
+function mulberry32(seed) {
+  let state = seed >>> 0;
+  return () => {
+    state = (state + 0x6d2b79f5) >>> 0;
+    let t = Math.imul(state ^ (state >>> 15), state | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/** Returns a deterministic () => float-in-[0,1) generator seeded by `seed`. */
+export function makeRng(seed = "tradelab") {
+  const seedFn = xmur3(String(seed));
+  return mulberry32(seedFn());
+}
+
+/** Integer in [0, maxExclusive) from an rng produced by makeRng. */
+export function randInt(rng, maxExclusive) {
+  return Math.floor(rng() * maxExclusive);
+}

package/templates/dashboard.html

@@ -0,0 +1,174 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>tradelab live</title>
+    <style>
+      :root {
+        color-scheme: dark;
+      }
+
+      body {
+        margin: 0;
+        font:
+          14px/1.5 ui-monospace,
+          SFMono-Regular,
+          Menlo,
+          monospace;
+        background: #0f172a;
+        color: #e2e8f0;
+      }
+
+      header {
+        padding: 16px 24px;
+        border-bottom: 1px solid #1e293b;
+        display: flex;
+        gap: 24px;
+        align-items: baseline;
+      }
+
+      h1 {
+        font-size: 16px;
+        margin: 0;
+        color: #38bdf8;
+      }
+
+      .grid {
+        display: grid;
+        grid-template-columns: 1fr 1fr;
+        gap: 16px;
+        padding: 24px;
+      }
+
+      .card {
+        background: #111827;
+        border: 1px solid #1e293b;
+        border-radius: 8px;
+        padding: 16px;
+      }
+
+      .card h2 {
+        font-size: 12px;
+        text-transform: uppercase;
+        letter-spacing: 0.08em;
+        color: #64748b;
+        margin: 0 0 12px;
+      }
+
+      .big {
+        font-size: 28px;
+        font-weight: 600;
+      }
+
+      .pos {
+        color: #4ade80;
+      }
+
+      .neg {
+        color: #f87171;
+      }
+
+      ul {
+        list-style: none;
+        margin: 0;
+        padding: 0;
+        max-height: 320px;
+        overflow: auto;
+      }
+
+      li {
+        padding: 6px 0;
+        border-bottom: 1px solid #1e293b;
+        display: flex;
+        gap: 12px;
+      }
+
+      .halt {
+        color: #fbbf24;
+      }
+
+      time {
+        color: #475569;
+      }
+    </style>
+  </head>
+  <body>
+    <header>
+      <h1>tradelab live</h1>
+      <span id="symbol">-</span>
+      <span id="conn">connecting...</span>
+    </header>
+    <div class="grid">
+      <div class="card">
+        <h2>Equity</h2>
+        <div class="big" id="equity">-</div>
+        <div>Day PnL: <span id="dayPnl">-</span></div>
+      </div>
+      <div class="card">
+        <h2>Open position</h2>
+        <div id="position">flat</div>
+      </div>
+      <div class="card">
+        <h2>Risk</h2>
+        <div id="risk">-</div>
+      </div>
+      <div class="card">
+        <h2>Recent events</h2>
+        <ul id="events"></ul>
+      </div>
+    </div>
+    <script>
+      const fmt = (n) =>
+        typeof n === "number" ? n.toLocaleString(undefined, { maximumFractionDigits: 2 }) : "-";
+
+      function applyState(s) {
+        document.getElementById("symbol").textContent = s.symbol ?? s.id ?? "portfolio";
+        document.getElementById("equity").textContent = fmt(s.equity);
+        const dp = document.getElementById("dayPnl");
+        dp.textContent = fmt(s.dayPnl);
+        dp.className = (s.dayPnl ?? 0) >= 0 ? "pos" : "neg";
+        const p = s.openPosition;
+        document.getElementById("position").textContent = p
+          ? `${p.side} ${fmt(p.size)} @ ${fmt(p.entryFill ?? p.entry)} | uPnL ${fmt(p.unrealizedPnl)}`
+          : "flat";
+        document.getElementById("risk").textContent = s.risk ? JSON.stringify(s.risk) : "ok";
+      }
+
+      async function pollState() {
+        try {
+          applyState(await (await fetch("/state")).json());
+        } catch {}
+      }
+
+      pollState();
+      setInterval(pollState, 3000);
+
+      const list = document.getElementById("events");
+      const es = new EventSource("/events");
+      es.onopen = () => (document.getElementById("conn").textContent = "live");
+      es.onerror = () => (document.getElementById("conn").textContent = "disconnected");
+      es.onmessage = (e) => {
+        const msg = JSON.parse(e.data);
+        const li = document.createElement("li");
+        const halt = msg.event.startsWith("risk:");
+        li.innerHTML =
+          "<time>" +
+          new Date(msg.t).toLocaleTimeString() +
+          "</time>" +
+          '<span class="' +
+          (halt ? "halt" : "") +
+          '">' +
+          msg.event +
+          "</span>" +
+          "<span>" +
+          (msg.payload?.symbol ?? "") +
+          "</span>";
+        list.prepend(li);
+        while (list.children.length > 100) list.removeChild(list.lastChild);
+        if (["equity:update", "position:opened", "position:closed"].includes(msg.event))
+          pollState();
+      };
+    </script>
+  </body>
+</html>

package/types/index.d.ts

@@ -82,6 +82,7 @@ export interface TradeExit {
   time: number;
   reason: string;
   pnl: number;
+  financing?: number;
   exitATR?: number;
 }
 
@@ -238,6 +239,9 @@ export interface SignalResult {
 }
 
 export type SignalFunction = (context: SignalContext) => SignalResult | null;
+export type AsyncSignalFunction = (
+  context: SignalContext
+) => SignalResult | null | Promise<SignalResult | null>;
 
 export interface PendingOrder {
   side: Side;
@@ -268,6 +272,15 @@ export interface ExecutionCostOptions {
   commissionPerUnit?: number;
   commissionPerOrder?: number;
   minCommission?: number;
+  carry?: {
+    longAnnualBps?: number;
+    shortAnnualBps?: number;
+  };
+  funding?: {
+    rateBps?: number;
+    intervalMs?: number;
+    anchorMs?: number;
+  };
 }
 
 export interface MfeTrailOptions {
@@ -337,6 +350,11 @@ export interface BacktestOptions {
   strict?: boolean;
 }
 
+export interface BacktestAsyncOptions extends Omit<BacktestOptions, "signal"> {
+  signal: AsyncSignalFunction;
+  signalBudgetMs?: number;
+}
+
 export interface BacktestTickOptions {
   ticks: Tick[];
   symbol?: string;
@@ -357,6 +375,7 @@ export interface BacktestTickOptions {
   collectEqSeries?: boolean;
   collectReplay?: boolean;
   queueFillProbability?: number;
+  seed?: string;
   oco?: OCOOptions;
 }
 
@@ -542,6 +561,81 @@ export interface ArtifactPaths {
   metrics: string | null;
 }
 
+export interface LlmSignalOptions {
+  resolve: AsyncSignalFunction;
+  budgetMs?: number;
+  onError?: "skip" | "throw";
+}
+
+export interface LlmDecisionLogEntry {
+  index: number;
+  time?: number;
+  close?: number;
+  latencyMs: number;
+  result?: SignalResult | null;
+  error?: string;
+}
+
+export interface StrategyParamSpec {
+  type: string;
+  default?: unknown;
+  description?: string;
+  [key: string]: unknown;
+}
+
+export interface StrategyDefinition {
+  description: string;
+  params: Record<string, StrategyParamSpec>;
+  factory: (params?: Record<string, unknown>) => SignalFunction;
+}
+
+export interface StrategySummary {
+  name: string;
+  description: string;
+  params: Record<string, StrategyParamSpec>;
+}
+
+export interface ResearchPercentileBands {
+  p5: number;
+  p25?: number;
+  p50: number;
+  p75?: number;
+  p95: number;
+}
+
+export interface MonteCarloResult {
+  iterations: number;
+  blockSize: number;
+  finalEquity: Required<ResearchPercentileBands>;
+  maxDrawdown: Required<ResearchPercentileBands>;
+  pathBands: Array<Pick<ResearchPercentileBands, "p5" | "p50" | "p95">>;
+  probProfit: number;
+}
+
+export interface PboResult {
+  pbo: number;
+  combos: number;
+  medianLogit: number;
+}
+
+export interface CpcvSplit {
+  train: number[];
+  test: number[];
+  testGroups: number[];
+}
+
+export interface OptimizeResultEntry {
+  params: Record<string, unknown>;
+  metrics?: Partial<BacktestMetrics>;
+  error?: string;
+}
+
+export interface OptimizeResult {
+  results: OptimizeResultEntry[];
+  leaderboard: OptimizeResultEntry[];
+  best: OptimizeResultEntry | null;
+}
+
 /**
  * Run a candle-based backtest.
  *
@@ -550,7 +644,18 @@ export interface ArtifactPaths {
  * chart-friendly replay frames/events in `replay`.
  */
 export function backtest(options: BacktestOptions): BacktestResult;
+export function backtestAsync(options: BacktestAsyncOptions): Promise<BacktestResult>;
 export function backtestTicks(options: BacktestTickOptions): BacktestResult;
+export function grid(spec?: Record<string, unknown | unknown[]>): Array<Record<string, unknown>>;
+export function optimize(options: {
+  candles: Candle[];
+  signalModulePath: string;
+  parameterSets: Array<Record<string, unknown>>;
+  interval?: string;
+  backtestOptions?: Partial<BacktestOptions>;
+  concurrency?: number;
+  scoreBy?: keyof BacktestMetrics | string;
+}): Promise<OptimizeResult>;
 export function backtestPortfolio(options: {
   systems: PortfolioSystem[];
   equity?: number;
@@ -581,6 +686,55 @@ export function buildMetrics(input: {
   eqSeries?: EquityPoint[];
 }): BacktestMetrics;
 
+export class LlmSignal {
+  constructor(options: LlmSignalOptions);
+  resolve: AsyncSignalFunction;
+  budgetMs: number;
+  onError: "skip" | "throw";
+  log: LlmDecisionLogEntry[];
+  signal(context: SignalContext): Promise<SignalResult | null>;
+}
+
+export function registerStrategy(name: string, def: StrategyDefinition): void;
+export function listStrategies(): StrategySummary[];
+export function getStrategy(name: string): StrategyDefinition["factory"];
+
+export namespace research {
+  function monteCarlo(options: {
+    tradePnls: number[];
+    equityStart?: number;
+    iterations?: number;
+    blockSize?: number;
+    seed?: string | number;
+  }): MonteCarloResult;
+  function deflatedSharpe(options: {
+    sharpe: number;
+    sampleSize: number;
+    numTrials?: number;
+    sharpeStd?: number;
+    skew?: number;
+    kurtosis?: number;
+  }): number;
+  function sweepHaircut(options: { numTrials: number; sharpeStd: number }): {
+    expectedMaxSharpe: number;
+    numTrials: number;
+  };
+  function probabilityOfBacktestOverfitting(
+    performanceMatrix: number[][],
+    options?: { groups?: number }
+  ): PboResult;
+  function combinatorialPurgedSplits(options: {
+    nObservations: number;
+    nGroups?: number;
+    nTestGroups?: number;
+    embargo?: number;
+  }): CpcvSplit[];
+  function combinations(n: number, k: number): number[][];
+  function normalCdf(x: number): number;
+  function normalPpf(p: number): number;
+  function moments(values: number[]): { mean: number; std: number; skew: number; kurtosis: number };
+}
+
 export function getHistoricalCandles(options?: HistoricalDataOptions): Promise<Candle[]>;
 export function backtestHistorical(options: BacktestHistoricalOptions): Promise<BacktestResult>;
 export function fetchHistorical(

package/types/live.d.ts

@@ -330,6 +330,21 @@ export class LiveOrchestrator {
   getStatus(): Record<string, unknown>;
 }
 
+export interface DashboardServer {
+  start(): Promise<string>;
+  close(): Promise<void>;
+  server: import("node:http").Server;
+}
+
+export function createDashboardServer(options: {
+  source: {
+    eventBus: EventBus;
+    getStatus?: () => Record<string, unknown>;
+  };
+  port?: number;
+  maxBuffer?: number;
+}): DashboardServer;
+
 export function createEventBus(): EventBus;
 export function createLogger(options?: {
   level?: "debug" | "info" | "warn" | "error" | "silent";

package/types/ta.d.ts

@@ -0,0 +1,45 @@
+// types/ta.d.ts
+export type Candle = {
+  time: number;
+  open: number;
+  high: number;
+  low: number;
+  close: number;
+  volume?: number;
+};
+
+export function ema(values: number[], period?: number): number[];
+export function atr(bars: Candle[], period?: number): (number | undefined)[];
+export function rsi(closes: number[], period?: number): (number | undefined)[];
+export function macd(
+  closes: number[],
+  fast?: number,
+  slow?: number,
+  signalPeriod?: number
+): { macd: number[]; signal: number[]; histogram: number[] };
+export function stochastic(
+  bars: Candle[],
+  kPeriod?: number,
+  dPeriod?: number
+): { k: (number | undefined)[]; d: (number | undefined)[] };
+export function bollinger(
+  closes: number[],
+  period?: number,
+  mult?: number
+): { middle: (number | undefined)[]; upper: (number | undefined)[]; lower: (number | undefined)[] };
+export function donchian(
+  bars: Candle[],
+  period?: number
+): { upper: (number | undefined)[]; lower: (number | undefined)[]; middle: (number | undefined)[] };
+export function keltner(
+  bars: Candle[],
+  emaPeriod?: number,
+  atrPeriod?: number,
+  mult?: number
+): { upper: (number | undefined)[]; lower: (number | undefined)[]; middle: (number | undefined)[] };
+export function supertrend(
+  bars: Candle[],
+  period?: number,
+  mult?: number
+): { line: (number | undefined)[]; direction: (number | undefined)[] };
+export function vwap(bars: Candle[]): (number | undefined)[];