@christtrade/depth 0.12.24 → 0.12.25

package/types/core/TypedEventBus.d.ts

@@ -1,6 +1,7 @@
 import { LiveTransformer } from '../interfaces/ICoordinateTransformer';
 import { ChartSettings } from '../lib/types/chart-settings';
 import { type SessionStatus } from './SessionUtils';
+import type { StrategyEquityPoint, StrategyPosition, StrategyStats, StrategyTrade } from './strategy-runtime';
 import { BarPreviewResponse, OhlcvBar, SymbolInfo, SymbolSearchMode, SymbolSearchRequest, TradingSession } from '../interfaces/IDataAdapter';
 import { DataLevel } from '../interfaces/IDataAdapter';
 import { IExecutionAdapter } from '../interfaces/IExecutionAdapter';
@@ -26,6 +27,12 @@ export interface ChartEvents {
     } | null;
     'chart:ready': void;
     'chart:reset-view': void;
+    'chart:goto-range': {
+        fromNs: bigint;
+        toNs?: bigint;
+        /** Fraction of the span to leave either side. Default 0.25. */
+        padding?: number;
+    };
     'chart:set-tool': {
         tool: ActiveDrawingTool;
     };
@@ -542,6 +549,129 @@ export interface ChartEvents {
     'plugin:indicator-updated': {
         id: string;
     };
+    'plugin:strategy-updated': {
+        id: string;
+        name: string;
+        stats: StrategyStats;
+        trades: StrategyTrade[];
+        equity: StrategyEquityPoint[];
+        /** Still open at the last bar, if the run ended holding something. */
+        position: StrategyPosition | null;
+        /** The parameter values that produced these numbers. */
+        params: Record<string, unknown>;
+        /**
+         * The script's parameter declarations, so a sweep UI can offer a range
+         * for each without the author declaring anything extra - a numeric
+         * ParamDef already carries min, max and step.
+         */
+        paramDefs: Record<string, unknown>;
+    };
+    'plugin:apply-params': {
+        id: string;
+        params: Record<string, unknown>;
+    };
+    'plugin:strategy-sweep': {
+        id: string;
+        grid: Array<Record<string, unknown>>;
+        /** Fraction held back from the end as out-of-sample. */
+        oosFraction?: number;
+        /**
+         * What each grid point patches over. Pass what the settings dialog
+         * currently holds, so parameters that are not being swept keep the value
+         * the user set. Omitted falls back to the script's declared defaults.
+         */
+        params?: Record<string, unknown>;
+    };
+    'plugin:strategy-sweep-cancel': {
+        id: string;
+    };
+    'plugin:strategy-sweep-progress': {
+        id: string;
+        done: number;
+        total: number;
+    };
+    'plugin:strategy-sweep-done': {
+        id: string;
+        /** One entry per grid point, in grid order. `error` instead of `stats`
+         *  for a combination that threw. */
+        results: Array<{
+            params: Record<string, unknown>;
+            stats?: StrategyStats;
+            inSample?: StrategyStats;
+            outOfSample?: StrategyStats;
+            error?: string;
+        }>;
+    };
+    'plugin:strategy-sweep-cancelled': {
+        id: string;
+        done: number;
+    };
+    'plugin:strategy-sweep-rejected': {
+        id: string;
+        name: string;
+        combos: number;
+        bars: number;
+        iterations: number;
+        reason: string;
+    };
+    'plugin:strategy-walkforward': {
+        id: string;
+        grid: Array<Record<string, unknown>>;
+        params?: Record<string, unknown>;
+        /** Out-of-sample segments to test. Default 4. */
+        windows?: number;
+        /** In-sample length as a multiple of out-of-sample. Default 3. */
+        isMultiple?: number;
+        /** Fixed in-sample start rather than a sliding window. */
+        anchored?: boolean;
+        /** Which statistic the optimiser maximises. Default 'netPnl'. */
+        objective?: string;
+        /** False for drawdown-like objectives. */
+        higherIsBetter?: boolean;
+    };
+    'plugin:strategy-walkforward-cancel': {
+        id: string;
+    };
+    'plugin:strategy-walkforward-progress': {
+        id: string;
+        done: number;
+        total: number;
+    };
+    'plugin:strategy-walkforward-done': {
+        id: string;
+        results: Array<{
+            window: {
+                index: number;
+                isFrom: number;
+                isTo: number;
+                oosFrom: number;
+                oosTo: number;
+            };
+            params?: Record<string, unknown>;
+            inSample?: StrategyStats;
+            outOfSample?: StrategyStats;
+            /** The test segment's own curve. Stitched across windows, this is the
+             *  equity of parameters never fitted to the data they run over. */
+            outOfSampleEquity?: StrategyEquityPoint[];
+            error?: string;
+        }>;
+    };
+    'plugin:strategy-walkforward-cancelled': {
+        id: string;
+        done: number;
+    };
+    'plugin:strategy-walkforward-rejected': {
+        id: string;
+        name: string;
+        reason: string;
+    };
+    'plugin:strategy-rejected': {
+        id: string;
+        name: string;
+        bars: number;
+        maxBars: number;
+        reason: string;
+    };
     'plugin:update-code': {
         id: string;
         code: string;

package/types/core/index.d.ts

@@ -25,6 +25,12 @@ export type { ChartModelInit, ChartPluginRef, ChartPaneState } from './ChartMode
 export { DrawingStore } from './DrawingStore';
 export type { ChartPlugin, PluginType, Permission, PluginManifest, PluginContext, PluginDataSnapshot, DrawingPlugin, ChartTypePlugin, ChartTypeRenderContext, DataSourcePlugin, IndicatorPlugin, IndicatorRenderContext, } from '../interfaces/plugins';
 export { createScriptedPlugin } from './ScriptedPlugin';
+export { StrategyEngine, DEFAULT_STRATEGY_CONFIG } from './strategy-runtime';
+export { axisValues, checkSweepBudget, expandGrid, splitIndex, MAX_SWEEP_COMBOS, MAX_SWEEP_BAR_ITERATIONS, } from './strategy-sweep';
+export type { SweepAxis, SweepSpec, SweepResult, SweepBudget } from './strategy-sweep';
+export { planWalkForward, walkForwardEfficiency, parameterStability, pickBest, } from './strategy-walkforward';
+export type { WalkForwardSpec, WalkForwardWindow, WalkForwardWindowResult, ParameterStability, } from './strategy-walkforward';
+export type { BrokerApi, StrategyEquityPoint, ExitReason, OrderOpts, Side, StrategyBar, StrategyConfig, StrategyOrder, StrategyPosition, StrategyResult, StrategyStats, StrategyTrade, } from './strategy-runtime';
 export { isCompatible, DATA_LEVEL_LABELS, incompatibleReason } from './processing/data-level';
 export { processL3Chunk, mergeL3Chunks } from './processing/l3-processor';
 export type { ProcessedL3Chunk, L3DataChunk } from './processing/l3-processor';

package/types/core/script-dsl.d.ts

@@ -4,6 +4,7 @@ export declare const PluginType: Readonly<{
     readonly chartType: "chart-type";
     readonly dataSource: "data-source";
     readonly extension: "extension";
+    readonly strategy: "strategy";
 }>;
 export declare const DataLevel: Readonly<{
     readonly mbo: "l3";
@@ -16,5 +17,13 @@ export declare const Layout: Readonly<{
     readonly overlay: "overlay";
     readonly pane: "pane";
 }>;
+/** Why a strategy position closed. Mirrors ExitReason in strategy-runtime.ts. */
+export declare const ExitReason: Readonly<{
+    readonly signal: "signal";
+    readonly stop: "stop";
+    readonly target: "target";
+    readonly reverse: "reverse";
+    readonly endOfData: "end-of-data";
+}>;
 /** The DSL globals as one bag, for splatting into an eval scope. */
 export declare const SCRIPT_DSL: Record<string, unknown>;

package/types/core/script-runtime.d.ts

@@ -1,7 +1,13 @@
 import { STDLIB } from '../lib/indicator-stdlib';
-import { PluginType, DataLevel, Layout, SCRIPT_DSL } from './script-dsl';
-export { STDLIB, SCRIPT_DSL, PluginType, DataLevel, Layout };
+import { PluginType, DataLevel, Layout, ExitReason, SCRIPT_DSL } from './script-dsl';
+export { STDLIB, SCRIPT_DSL, PluginType, DataLevel, Layout, ExitReason };
 export type { OhlcvBar, DrawCommand } from '../lib/indicator-stdlib';
+export { StrategyEngine, DEFAULT_STRATEGY_CONFIG } from './strategy-runtime';
+export { axisValues, checkSweepBudget, expandGrid, splitIndex } from './strategy-sweep';
+export type { SweepAxis, SweepSpec, SweepResult, SweepBudget } from './strategy-sweep';
+export { planWalkForward, walkForwardEfficiency, parameterStability, pickBest, } from './strategy-walkforward';
+export type { WalkForwardSpec, WalkForwardWindow, WalkForwardWindowResult, ParameterStability, } from './strategy-walkforward';
+export type { BrokerApi, StrategyEquityPoint, OrderOpts, Side, StrategyBar, StrategyConfig, StrategyOrder, StrategyPosition, StrategyResult, StrategyStats, StrategyTrade, } from './strategy-runtime';
 export interface ScriptScopeOptions {
     /** What the script's `plugin({...})` call resolves to. */
     plugin: (decl: unknown) => unknown;
@@ -38,6 +44,7 @@ export declare function buildScriptScope(opts: ScriptScopeOptions): Record<strin
  * script makes while evaluating.
  */
 export declare function evalScriptInScope(src: string, opts: ScriptScopeOptions): void;
+export declare function defaultStrategyDraw(state: unknown, layout: 'overlay' | 'pane'): unknown[];
 /**
  * Identifies the stdlib surface this build exposes, for a client and a server
  * runner to agree they are talking about the same one.

package/types/core/strategy-runtime.d.ts

@@ -0,0 +1,325 @@
+/** Which way a position or fill points. */
+export type Side = 'long' | 'short' | 'flat';
+export type OrderKind = 'market' | 'limit' | 'stop';
+/** Why a position closed, for the trade log and the markers on the chart. */
+export type ExitReason = 'signal' | 'stop' | 'target' | 'reverse' | 'end-of-data';
+export interface StrategyOrder {
+    id: number;
+    side: 'buy' | 'sell';
+    qty: number;
+    kind: OrderKind;
+    /** Trigger price for limit/stop. Ignored for market. */
+    price?: number;
+    /** Protective stop attached to the position this order opens. */
+    sl?: number;
+    /** Profit target attached to the position this order opens. */
+    tp?: number;
+    tag?: string;
+    /** Bar index the order was placed on. It becomes eligible on the next one. */
+    placedIndex: number;
+}
+export interface StrategyPosition {
+    side: Side;
+    qty: number;
+    avgPrice: number;
+    entryTs: bigint;
+    entryIndex: number;
+    sl?: number;
+    tp?: number;
+    tag?: string;
+    /**
+     * Best and worst price reached while this position has been open.
+     *
+     * Tracked from the bar the position opened, over that bar's full range. A
+     * market order fills at the open so the whole range is fair; a limit or stop
+     * filling mid-bar makes the entry bar's contribution an upper bound. Every
+     * later bar is exact. Worth knowing before reading MAE as gospel on
+     * one-bar trades.
+     */
+    highWatermark: number;
+    lowWatermark: number;
+    /** Bar index and timestamp of the best excursion, for efficiency analysis. */
+    mfeIndex: number;
+    mfeTs: bigint;
+    maeIndex: number;
+    maeTs: bigint;
+    /**
+     * |entry - stop| per unit, locked at entry. Undefined when the position
+     * opened without a stop, which makes every R-multiple on it meaningless
+     * rather than zero - the difference matters, so it stays undefined.
+     */
+    initialRiskPerUnit?: number;
+    /** Fills that have gone into this position. Checked against `pyramiding`. */
+    entries: number;
+    /**
+     * Commission already paid to open the quantity still held. Carried on the
+     * position so the trade log can report a round-trip fee: equity is charged
+     * at entry, but nothing is logged until the exit, and a trade whose pnl
+     * omitted the entry side would not sum to the equity curve.
+     */
+    entryFees: number;
+}
+export interface StrategyTrade {
+    id: number;
+    side: Exclude<Side, 'flat'>;
+    qty: number;
+    entryTs: bigint;
+    entryPrice: number;
+    exitTs: bigint;
+    exitPrice: number;
+    /** Net of fees, in account currency. */
+    pnl: number;
+    /** Before fees. */
+    pnlGross: number;
+    /** Net return on the notional put at risk, as a fraction. */
+    pnlPct: number;
+    fees: number;
+    /** The fee split, because a strategy killed by commission and one killed by
+     *  slippage need different fixes. */
+    commission: number;
+    slippage: number;
+    /** How many bars the position was held. */
+    bars: number;
+    /** Wall-clock time held, in nanoseconds. */
+    durationNs: bigint;
+    tag?: string;
+    reason: ExitReason;
+    /** Worst the price went against this position before it closed. */
+    maeAbs: number;
+    /** Best the price went in favour of it. */
+    mfeAbs: number;
+    /** The same two, in account currency. */
+    maePnl: number;
+    mfePnl: number;
+    /** When the best and worst excursions happened. */
+    mfeTs: bigint;
+    maeTs: bigint;
+    /** Bars from entry to the best excursion. Tells you if you exit too late. */
+    barsToMfe: number;
+    /** |entry - stop| per unit at entry. */
+    initialRiskPerUnit?: number;
+    /** Total risk taken: initialRiskPerUnit x qty x contractSize. */
+    initialRiskTotal?: number;
+    /** Result in R. */
+    realizedR?: number;
+    /** Best and worst R reached while open. */
+    maxFavorableR?: number;
+    maxAdverseR?: number;
+    /**
+     * How much of the favourable excursion the exit actually captured, 0..1.
+     * A strategy averaging 0.2 here is right about direction and wrong about
+     * exits, which is a different problem from one that is simply wrong.
+     */
+    efficiency?: number;
+    /** Peak-to-exit give-back within this position, in account currency. */
+    maxDrawdownAbs: number;
+    maxDrawdownPct: number;
+    /** The protective levels this position opened with, if any. */
+    sl?: number;
+    tp?: number;
+}
+export interface StrategyEquityPoint {
+    ts: bigint;
+    /** Mark-to-market account value at this bar's close. */
+    equity: number;
+    /** Fraction below the running peak, 0 at a new high. */
+    drawdown: number;
+}
+export interface StrategyStats {
+    netPnl: number;
+    grossProfit: number;
+    grossLoss: number;
+    /** grossProfit / |grossLoss|. Infinity with no losers, 0 with no winners. */
+    profitFactor: number;
+    totalTrades: number;
+    wins: number;
+    losses: number;
+    /** Fraction, not percent. */
+    winRate: number;
+    avgWin: number;
+    avgLoss: number;
+    /** Expected P&L per trade. */
+    expectancy: number;
+    maxDrawdown: number;
+    maxDrawdownPct: number;
+    /** Annualised, from per-bar returns and the bar period. 0 without one. */
+    sharpe: number;
+    returnPct: number;
+    /** Fraction of bars holding a position. */
+    exposure: number;
+    finalEquity: number;
+    largestWin: number;
+    largestLoss: number;
+    /** Median trade P&L. The mean is what one outlier moves; this is not. */
+    medianPnl: number;
+    /** avgWin / |avgLoss|. How much bigger a winner is than a loser. */
+    payoffRatio: number;
+    /** Trades that closed exactly flat, counted separately from wins and losses. */
+    breakEvens: number;
+    maxWinStreak: number;
+    maxLossStreak: number;
+    /** Signed: positive means the run ended on N wins, negative on N losses. */
+    currentStreak: number;
+    avgBarsHeld: number;
+    avgWinBarsHeld: number;
+    avgLossBarsHeld: number;
+    /** Total bars in the run, for anything wanting to re-derive a rate. */
+    totalBars: number;
+    /** Like Sharpe but only downside deviation is punished. */
+    sortino: number;
+    /** Annualised return over max drawdown. */
+    calmar: number;
+    /** Net profit over max drawdown - how much the strategy makes per unit of pain. */
+    recoveryFactor: number;
+    /** RMS of the drawdown series. Punishes long shallow drawdowns Sharpe ignores. */
+    ulcerIndex: number;
+    /** System Quality Number: sqrt(n) x mean / stdev of trade P&L. */
+    sqn: number;
+    /** Kelly fraction from win rate and payoff. Negative means no edge. */
+    kelly: number;
+    /** Compound annual growth rate, from the run's wall-clock span. */
+    cagr: number;
+    /** How many trades carried a stop, and so have an R at all. */
+    tradesWithRisk: number;
+    avgR: number;
+    /** Sum of R. The expectancy curve most people actually track. */
+    totalR: number;
+    /** Mean of realizedR / maxFavorableR - how much of the move exits capture. */
+    avgEfficiency: number;
+    avgMae: number;
+    avgMfe: number;
+    longTrades: number;
+    shortTrades: number;
+    longWinRate: number;
+    shortWinRate: number;
+    longPnl: number;
+    shortPnl: number;
+    totalFees: number;
+    totalCommission: number;
+    /**
+     * What slippage cost, in account currency.
+     *
+     * Not a separate deduction - slippage is already inside every fill price and
+     * so already inside netPnl. This reports what that was worth, so a strategy
+     * that only loses to slippage is distinguishable from one that is simply
+     * wrong. Subtracting it again would double-count it.
+     */
+    totalSlippage: number;
+    /** What the run would have made with no commission at all. */
+    grossPnlBeforeCosts: number;
+}
+export interface StrategyConfig {
+    initialCapital: number;
+    /** Charged per contract per side. */
+    commission: number;
+    /** Applied against the trader, in ticks, on market and stop fills. */
+    slippageTicks: number;
+    tickSize: number;
+    /** Account-currency value of one point of price movement, per contract. */
+    contractSize: number;
+    /** How many entries may stack in the same direction. */
+    pyramiding: number;
+    /**
+     * Whether an opposite-side order flips an open position or merely closes it.
+     *
+     * True matches how most scripts read: sell() while long means "get out and go
+     * short". False means sell() can only ever flatten, and opening the other way
+     * takes a second, separate order.
+     */
+    allowReverse: boolean;
+    /**
+     * Smallest tradable quantity increment. Order sizes floor to it.
+     *
+     * 1 for a listed future, where a third of a contract does not exist; spot
+     * venues are the other case entirely, so this comes from the instrument
+     * rather than being assumed.
+     */
+    qtyStep: number;
+}
+export declare const DEFAULT_STRATEGY_CONFIG: StrategyConfig;
+export interface StrategyResult {
+    trades: StrategyTrade[];
+    equity: StrategyEquityPoint[];
+    stats: StrategyStats;
+    position: StrategyPosition | null;
+    openOrders: StrategyOrder[];
+}
+/** One OHLCV bar, structurally what the stdlib and the data engine already use. */
+export interface StrategyBar {
+    ts: bigint;
+    open: number;
+    high: number;
+    low: number;
+    close: number;
+    volume: number;
+}
+export interface OrderOpts {
+    /** Place a limit instead of a market order. */
+    limit?: number;
+    /** Place a stop instead of a market order. */
+    stop?: number;
+    /** Protective stop for the resulting position, as an absolute price. */
+    sl?: number;
+    /** Profit target for the resulting position, as an absolute price. */
+    tp?: number;
+    /** Free label, carried onto the trade and shown on the chart marker. */
+    tag?: string;
+}
+/** What a strategy script sees as `broker`. */
+export interface BrokerApi {
+    buy(qty?: number, opts?: OrderOpts): number;
+    sell(qty?: number, opts?: OrderOpts): number;
+    /** Flatten at the next bar's open. No-op when already flat. */
+    close(): void;
+    cancelAll(): void;
+    readonly position: Readonly<StrategyPosition> | null;
+    readonly equity: number;
+    readonly cash: number;
+    readonly openOrders: readonly StrategyOrder[];
+}
+export declare class StrategyEngine {
+    private cfg;
+    private pending;
+    private pos;
+    private trades;
+    private equityCurve;
+    private realized;
+    private peak;
+    private nextOrderId;
+    private index;
+    private barsInPosition;
+    private barCount;
+    private markPrice;
+    private closeRequested;
+    private barNs;
+    private slippagePaid;
+    constructor(cfg?: Partial<StrategyConfig>);
+    setBarNs(ns: bigint): void;
+    beginBar(bar: StrategyBar, index: number): void;
+    endBar(bar: StrategyBar): void;
+    finish(lastBar: StrategyBar | undefined): void;
+    get equity(): number;
+    get result(): StrategyResult;
+    api(): BrokerApi;
+    private place;
+    private processPending;
+    private fillPrice;
+    private execute;
+    private maxEntries;
+    private roundQty;
+    private enter;
+    private slippageCost;
+    private exit;
+    private checkBrackets;
+    private trackExcursion;
+    private commissionFor;
+    private unrealized;
+    private computeStats;
+    private runYears;
+    private cagr;
+    private sortino;
+    private barReturns;
+    private peakAt;
+    private barsInPositionTotal;
+    private sharpe;
+}

package/types/core/strategy-sweep.d.ts

@@ -0,0 +1,75 @@
+import type { StrategyStats } from './strategy-runtime';
+/**
+ * One axis of a sweep: a parameter and the values to try for it.
+ *
+ * Explicit `values` for anything discrete (a boolean, a select, a handful of
+ * lengths worth testing). `from`/`to`/`step` for a numeric range, which is what
+ * a ParamDef with min/max/step already describes - so the UI can offer a sweep
+ * over a parameter without the author declaring anything extra.
+ */
+export type SweepAxis = {
+    param: string;
+    values: unknown[];
+} | {
+    param: string;
+    from: number;
+    to: number;
+    step: number;
+};
+export interface SweepSpec {
+    axes: SweepAxis[];
+    /**
+     * Fraction of the run held back from the end as out-of-sample, 0 to 0.9.
+     *
+     * Optional but strongly encouraged, and the reason it is here rather than in
+     * some later "advanced" feature: a sweep is a machine for overfitting. Report
+     * only the best in-sample result and you have found the parameters that best
+     * describe noise you already have. The out-of-sample column is what tells you
+     * whether you found anything at all.
+     */
+    oosFraction?: number;
+}
+/** What one point of the grid produced. */
+export interface SweepResult {
+    /** The parameter values this run used - only the swept ones. */
+    params: Record<string, unknown>;
+    /** Over the whole window. */
+    stats: StrategyStats;
+    /** The leading portion, when a split was requested. */
+    inSample?: StrategyStats;
+    /** The held-back tail. The number that actually means something. */
+    outOfSample?: StrategyStats;
+}
+export declare const MAX_SWEEP_BAR_ITERATIONS = 200000000;
+export declare const MAX_SWEEP_COMBOS = 20000;
+export declare function axisValues(axis: SweepAxis): unknown[];
+/**
+ * The cartesian product of every axis, as parameter patches.
+ *
+ * Ordered so the first axis varies slowest. That makes the result array read as
+ * rows of the first parameter when laid out as a grid, which is what a heatmap
+ * wants without having to sort anything.
+*/
+export declare function expandGrid(axes: SweepAxis[]): Array<Record<string, unknown>>;
+export interface SweepBudget {
+    combos: number;
+    bars: number;
+    iterations: number;
+    ok: boolean;
+    /** Populated when ok is false. Written for a user, not a log. */
+    reason?: string;
+}
+/** Whether a sweep is worth attempting here, and what to say when it is not. */
+export declare function checkSweepBudget(combos: number, bars: number): SweepBudget;
+/**
+ * Where to cut a run into in-sample and out-of-sample halves.
+ *
+ * The tail is held back, never the head: the point is to test on data that comes
+ * *after* what the parameters were chosen on, because that is the only ordering
+ * that resembles trading them.
+ *
+ * Returns null when there is no meaningful split - too few bars, or a fraction
+ * that would leave one side empty. A missing OOS column is honest; a two-bar one
+ * is worse than none.
+ */
+export declare function splitIndex(barCount: number, oosFraction: number | undefined): number | null;