Skip to content

πŸ“ˆ Get real-time stocks from TradingView

26.4 KB
Raw Blame
import { createRequire } from 'node:module';
import { timeframeSeconds } from '../chart/timeframes.js';
import type { Timeframe } from '../chart/types.js';
import { getCandles, type CandleQuery } from '../data/candles.js';
import type { MarketDataProvider } from '../data/provider.js';
import { TradingViewError } from '../errors.js';
import { defaultExits } from './exits.js';
import {
  fillPrice, simulate, splitSegments, tradeReturn,
} from './simulate.js';
import {
  freezeSnapshot, snapshotInfo, type Snapshot, type SnapshotInfo,
} from './snapshot.js';
import {
  computeMetrics, createRng, deriveSeed, percentileRank, randomBaseline,
} from './stats.js';
import type {
  Bar, Baseline, Costs, Direction, Entry, ExitModel, ExitReason, Metrics, Segment, Signal, SignalFunction, Trade,
} from './types.js';

export interface BacktestOptions {
  /** Your entry rule. See `SignalFunction`. */
  signal: SignalFunction;
  /** Exits compared on the same entries. Default: `defaultExits()` (four reference exits). */
  exits?: readonly ExitModel[];
  /** Fee per side. Default 0.001 (0.1%). */
  fee?: number;
  /** Adverse slippage per side. Default 0.0005 (0.05%). */
  slippage?: number;
  /** In-sample share of the tradable bars. Default 0.7. */
  splitRatio?: number;
  /**
   * Bars never traded, used only to warm the indicators up. Default: the largest
   * `warmupBars` of the signal and the exits, or 200 when the signal does not declare one.
   */
  warmupBars?: number;
  /** Random-entry runs per exit and split. Default 1000; 0 disables the baseline. */
  runs?: number;
  /** Base seed of the random baseline. Default 42. */
  seed?: number;
  /**
   * Maximum number of signals whose causality is checked by rerunning `signal` on the history
   * that ends at their bar (plus 8 evenly spaced cuts). Default 100; 0 disables the check.
   */
  causalityChecks?: number;
  /** Tradable history wanted, in years: only used for the warning. */
  minYears?: number;
}

export const BACKTEST_DEFAULTS = Object.freeze({
  fee: 0.001,
  slippage: 0.0005,
  splitRatio: 0.7,
  runs: 1000,
  seed: 42,
  causalityChecks: 100,
  signalWarmupBars: 200,
  minYears: 2,
});

export interface SegmentInfo extends Segment {
  bars: number;
  /** Open time of the first bar, Unix seconds. */
  startTime: number | null;
  /** Open time of the last bar, Unix seconds. */
  endTime: number | null;
  /** Buy and hold over the segment: long at the first open, out at the last close, with the same fee and slippage. */
  buyHold: number | null;
}

export interface SignalRecord {
  bar: number;
  time: number;
  direction: Direction;
  entryBar: number;
  entryTime: number | null;
  /** Segment containing both the signal and the entry, or null (warm-up, straddling the split, last bar). */
  split: 'IS' | 'OOS' | null;
  /** Times of the signal's `refs` bars. */
  refs: Record<string, number>;
  /** Bar indices of the signal's `refs` (into `snapshot.candles`). */
  refBars: Record<string, number>;
}

export interface TradeRecord {
  /** Market id, set by `backtestMany` (`<symbol>_<timeframe>`). */
  series?: string;
  exit: string;
  split: 'IS' | 'OOS';
  direction: Direction;
  signalBar: number;
  signalTime: number;
  entryBar: number;
  entryTime: number;
  /** Times of the signal's `refs` bars. */
  refs: Record<string, number>;
  /** Bar indices of the signal's `refs` (into `snapshot.candles`). */
  refBars: Record<string, number>;
  entryOpen: number;
  entryPrice: number;
  initialStop: number;
  target: number | null;
  exitBar: number;
  exitTime: number;
  exitLevel: number;
  exitPrice: number;
  reason: ExitReason;
  return: number;
}

export interface ReportRow {
  exit: string;
  split: 'IS' | 'OOS';
  metrics: Metrics;
  longs: number;
  shorts: number;
  skippedInPosition: number;
  /** Random-entry baseline without the raw returns; null without trades or with `runs: 0`. */
  baseline: Omit<Baseline, 'netReturns'> | null;
  /** 100 x share of random runs with a strictly lower net return; null without a baseline. */
  percentile: number | null;
}

export interface CausalityViolation {
  /** History length the signal function was rerun on (bars `0..cut-1`). */
  cut: number;
  bar: number;
  direction: Direction;
  /** `look_ahead`: present with full history, absent when history ends at `cut - 1`. `repaint`: the reverse. */
  kind: 'look_ahead' | 'repaint';
}

export interface CausalityCheck {
  /** Number of truncated reruns. 0 when disabled. */
  reruns: number;
  /** Signals whose own cut was checked, out of `totalSignals`. */
  checkedSignals: number;
  totalSignals: number;
}

/** Machine-readable warning; `formatReport` turns it into an English sentence. */
export type ReportWarning =
  | { code: 'short_history'; years: number; wantedYears: number }
  | { code: 'no_signals' }
  | { code: 'few_trades'; trades: number }
  | { code: 'baseline_unmatched'; exit: string; split: 'IS' | 'OOS'; matchedRuns: number; runs: number; trades: number; meanTrades: number }
  | { code: 'causality_disabled' }
  | { code: 'data_gaps'; gaps: number; missingBars: number };

/**
 * Plain JSON: save it, render it or send it as it is. It holds identifiers and numbers only
 * (exit ids, exit reasons, segment ids, warning codes); the `label` fields are English
 * descriptions for `formatReport`, not interface text.
 */
export interface BacktestReport {
  /** Run time, Unix seconds. */
  createdAt: number;
  library: { name: string; version: string };
  snapshot: SnapshotInfo;
  settings: {
    signal: { id: string; params: Record<string, number | string | boolean>; label: string };
    fee: number;
    slippage: number;
    splitRatio: number;
    warmupBars: number;
    runs: number;
    seed: number;
    exits: { id: string; kind: string | null; params: Record<string, number | null>; label: string }[];
  };
  segments: { warmup: SegmentInfo; inSample: SegmentInfo; outOfSample: SegmentInfo };
  /** Tradable years after warm-up. */
  tradableYears: number;
  signals: SignalRecord[];
  rows: ReportRow[];
  trades: TradeRecord[];
  causality: CausalityCheck;
  /** Few trades, short history, unmatched random runs, gaps... */
  warnings: ReportWarning[];
}

const pkg = createRequire(import.meta.url)('../../package.json') as { name: string; version: string };

const isNumber = (value: unknown): value is number => typeof value === 'number' && Number.isFinite(value);

function invalid(message: string): TradingViewError {
  return new TradingViewError('INVALID_ARGUMENT', message);
}

function checkOption(name: string, value: number, ok: boolean): number {
  if (!isNumber(value) || !ok) throw invalid(`${name} is out of range: ${value}`);
  return value;
}

/** Validates and sorts (stable, by bar) what the signal function returned. */
function normaliseSignals(raw: unknown, barCount: number): Signal[] {
  if (!Array.isArray(raw)) throw invalid('signal() must return an array of { bar, direction }');
  raw.forEach((s: Signal, i) => {
    if (!s || !Number.isInteger(s.bar) || s.bar < 0 || s.bar >= barCount) {
      throw invalid(`signal() returned an invalid bar at index ${i}: ${s?.bar} (expected an integer bar index from 0 to ${barCount - 1})`);
    }
    if (s.direction !== 'long' && s.direction !== 'short') throw invalid(`signal() returned an invalid direction at index ${i}: ${s.direction}`);
  });
  return [...(raw as Signal[])].sort((a, b) => a.bar - b.bar);
}

function signalCounts(signals: readonly Signal[], before: number): Map<string, number> {
  const counts = new Map<string, number>();
  for (const s of signals) {
    if (s.bar >= before) break;
    const key = `${s.bar}:${s.direction}`;
    counts.set(key, (counts.get(key) ?? 0) + 1);
  }
  return counts;
}

function violationsAt(cut: number, full: readonly Signal[], truncated: readonly Signal[]): CausalityViolation[] {
  const expected = signalCounts(full, cut);
  const actual = signalCounts(truncated, cut);
  const out: CausalityViolation[] = [];
  const diff = (a: Map<string, number>, b: Map<string, number>, kind: CausalityViolation['kind']) => {
    for (const [key, count] of a) {
      if ((b.get(key) ?? 0) < count) {
        const [bar, direction] = key.split(':');
        out.push({ cut, bar: Number(bar), direction: direction as Direction, kind });
      }
    }
  };
  diff(expected, actual, 'look_ahead');
  diff(actual, expected, 'repaint');
  return out.sort((a, b) => a.bar - b.bar);
}

/**
 * Reruns `signal` on truncated copies of the candles and compares the signals it gives up to
 * each cut with those of the full run. A signal must be identical whether or not later bars
 * exist; otherwise it used information from after its bar (look-ahead) or changes when new
 * bars arrive (repaint). Cuts: the bar right after each checked signal (at most `maxSignals`,
 * picked with a seeded draw when there are more) and 8 evenly spaced bars after `fromBar`.
 */
export function checkCausality(
  signal: SignalFunction,
  candles: readonly Readonly<Required<Bar>>[],
  options: { fullSignals?: readonly Signal[]; maxSignals?: number; fromBar?: number; seed?: number } = {},
): { violations: CausalityViolation[]; check: CausalityCheck } {
  const full = options.fullSignals ?? normaliseSignals(signal(candles), candles.length);
  const maxSignals = options.maxSignals ?? BACKTEST_DEFAULTS.causalityChecks;
  const fromBar = Math.max(1, options.fromBar ?? 0);
  const candidates = [...new Set(full.map((s) => s.bar + 1))].filter((cut) => cut < candles.length);
  let signalCuts = candidates;
  if (candidates.length > maxSignals) {
    const rng = createRng(options.seed ?? BACKTEST_DEFAULTS.seed);
    const picked = new Set<number>();
    while (picked.size < maxSignals) picked.add(candidates[Math.floor(rng() * candidates.length)]);
    signalCuts = [...picked];
  }
  const cuts = new Set(signalCuts);
  if (maxSignals > 0) {
    for (let j = 1; j <= 8; j++) {
      const cut = fromBar + Math.round(((candles.length - fromBar) * j) / 9);
      if (cut > 1 && cut < candles.length) cuts.add(cut);
    }
  }
  const violations: CausalityViolation[] = [];
  for (const cut of [...cuts].sort((a, b) => a - b)) {
    const prefix = Object.freeze(candles.slice(0, cut));
    violations.push(...violationsAt(cut, full, normaliseSignals(signal(prefix), cut)));
  }
  const checkedBars = new Set(signalCuts.map((cut) => cut - 1));
  return {
    violations,
    check: {
      reruns: cuts.size,
      checkedSignals: full.filter((s) => checkedBars.has(s.bar)).length,
      totalSignals: full.length,
    },
  };
}

function lookAheadError(violations: readonly CausalityViolation[], candles: readonly Bar[]): TradingViewError {
  const first = violations[0];
  const time = new Date(candles[first.bar].time * 1000).toISOString();
  const what = first.kind === 'look_ahead'
    ? `appears with the full history but not when the history ends at bar ${first.cut - 1}: it uses bars after its own bar`
    : `appears when the history ends at bar ${first.cut - 1} but not with the full history: it changes when later bars arrive (repaint)`;
  return new TradingViewError('LOOK_AHEAD', `The ${first.direction} signal at bar ${first.bar} (${time}) ${what}. `
    + `${violations.length} causality violation(s) found. A signal decided at the close of bar i may only use bars 0..i `
    + '(a pivot with lookback N is only known N bars later). Results would be unreliable, so the backtest stopped.', { details: violations });
}

function toSnapshot(input: Snapshot | readonly Bar[]): Snapshot {
  if (Array.isArray(input)) return freezeSnapshot(input);
  const snapshot = input as Snapshot;
  if (!snapshot || !Array.isArray(snapshot.candles) || !Object.isFrozen(snapshot.candles) || typeof snapshot.sha256 !== 'string') {
    throw invalid('runBacktest() expects candles or a snapshot from freezeSnapshot() / loadSnapshot()');
  }
  return snapshot;
}

function segmentInfo(segment: Segment, candles: readonly Bar[], costs: Costs): SegmentInfo {
  const empty = segment.end <= segment.start;
  const buyHold = () => tradeReturn(
    'long',
    fillPrice('entry', 'long', candles[segment.start].open, costs.slippage),
    fillPrice('exit', 'long', candles[segment.end - 1].close, costs.slippage),
    costs.fee,
  );
  return {
    ...segment,
    bars: Math.max(0, segment.end - segment.start),
    startTime: empty ? null : candles[segment.start].time,
    endTime: empty ? null : candles[segment.end - 1].time,
    buyHold: empty ? null : buyHold(),
  };
}

const validRefs = (refs: Readonly<Record<string, number>> | undefined, candles: readonly Bar[]) => Object.entries(refs ?? {})
  .filter(([, bar]) => Number.isInteger(bar) && candles[bar]);
const refTimes = (refs: Readonly<Record<string, number>> | undefined, candles: readonly Bar[]) => Object.fromEntries(
  validRefs(refs, candles).map(([name, bar]) => [name, candles[bar].time]),
);
const refBars = (refs: Readonly<Record<string, number>> | undefined, candles: readonly Bar[]) => Object.fromEntries(validRefs(refs, candles));

/** Resolves the warm-up: explicit option, else the largest need of the signal and exits. */
export function resolveWarmupBars(signal: SignalFunction, exits: readonly ExitModel[], warmupBars?: number): number {
  if (warmupBars !== undefined) return checkOption('warmupBars', warmupBars, Number.isInteger(warmupBars) && warmupBars >= 0);
  return Math.max(signal.warmupBars ?? BACKTEST_DEFAULTS.signalWarmupBars, ...exits.map((e) => e.warmupBars ?? 0));
}

type ResolvedOptions = Required<Omit<BacktestOptions, 'exits' | 'warmupBars'>> & { exits: readonly ExitModel[]; warmupBars: number };

function resolveOptions(options: BacktestOptions): ResolvedOptions {
  if (typeof options?.signal !== 'function') throw invalid('options.signal must be a function (candles) => [{ bar, direction }]');
  const o = { ...BACKTEST_DEFAULTS, ...options } as Required<Omit<BacktestOptions, 'exits' | 'warmupBars'>>;
  checkOption('fee', o.fee, o.fee >= 0 && o.fee < 1);
  checkOption('slippage', o.slippage, o.slippage >= 0 && o.slippage < 1);
  checkOption('splitRatio', o.splitRatio, o.splitRatio > 0 && o.splitRatio < 1);
  checkOption('runs', o.runs, Number.isInteger(o.runs) && o.runs >= 0);
  checkOption('seed', o.seed, Number.isInteger(o.seed));
  checkOption('causalityChecks', o.causalityChecks, Number.isInteger(o.causalityChecks) && o.causalityChecks >= 0);
  const exits = options.exits ?? defaultExits();
  if (!Array.isArray(exits) || exits.length === 0) throw invalid('exits must be a non-empty array');
  if (new Set(exits.map((e) => e.id)).size !== exits.length) throw invalid('exit ids must be unique');
  return { ...o, exits, warmupBars: resolveWarmupBars(options.signal, exits, options.warmupBars) };
}

/** Signals of the full history, rejected when the same rule on shorter history disagrees. */
function causalSignals(o: ResolvedOptions, candles: Snapshot['candles']): { signals: Signal[]; causality: CausalityCheck } {
  const signals = normaliseSignals(o.signal(candles), candles.length);
  if (o.causalityChecks === 0) return { signals, causality: { reruns: 0, checkedSignals: 0, totalSignals: signals.length } };
  const result = checkCausality(o.signal, candles, {
    fullSignals: signals, maxSignals: o.causalityChecks, fromBar: o.warmupBars, seed: o.seed,
  });
  if (result.violations.length) throw lookAheadError(result.violations, candles);
  return { signals, causality: result.check };
}

function tradeRecord(t: Trade, exit: string, split: 'IS' | 'OOS', candles: readonly Bar[]): TradeRecord {
  return {
    exit,
    split,
    direction: t.direction,
    signalBar: t.signalBar,
    signalTime: candles[t.signalBar].time,
    entryBar: t.entryBar,
    entryTime: candles[t.entryBar].time,
    refs: refTimes(t.refs, candles),
    refBars: refBars(t.refs, candles),
    entryOpen: t.entryOpen,
    entryPrice: t.entryPrice,
    initialStop: t.initialStop,
    target: t.target,
    exitBar: t.exitBar,
    exitTime: candles[t.exitBar].time,
    exitLevel: t.exitLevel,
    exitPrice: t.exitPrice,
    reason: t.reason,
    return: t.return,
  };
}

/** One exit on one segment: strategy trades, metrics and the random baseline. */
function evaluate(
  o: ResolvedOptions, candles: readonly Bar[], entries: readonly Entry[], exit: ExitModel, segment: Segment,
): { row: ReportRow; trades: TradeRecord[] } {
  const costs: Costs = { fee: o.fee, slippage: o.slippage };
  const result = simulate({ candles, entries, exit, costs, segment });
  const metrics = computeMetrics(result.trades);
  const longs = result.trades.filter((t) => t.direction === 'long').length;
  const baseline = metrics.trades > 0 && o.runs > 0
    ? randomBaseline({
      candles, exit, costs, segment,
      tradeCount: metrics.trades,
      longShare: longs / metrics.trades,
      runs: o.runs,
      seed: deriveSeed(o.seed, exit.id, segment.name),
    })
    : null;
  const split = segment.name as 'IS' | 'OOS';
  const row: ReportRow = {
    exit: exit.id,
    split,
    metrics,
    longs,
    shorts: metrics.trades - longs,
    skippedInPosition: result.skippedInPosition,
    baseline: baseline && {
      runs: baseline.runs, seed: baseline.seed, matchedRuns: baseline.matchedRuns, meanTrades: baseline.meanTrades,
      p5: baseline.p5, p50: baseline.p50, p95: baseline.p95,
    },
    percentile: baseline && percentileRank(metrics.netReturn, baseline.netReturns),
  };
  return { row, trades: result.trades.map((t) => tradeRecord(t, exit.id, split, candles)) };
}

function reportWarnings(
  o: ResolvedOptions, snapshot: Snapshot, tradableYears: number, signals: readonly Signal[], rows: readonly ReportRow[],
): ReportWarning[] {
  const warnings: ReportWarning[] = [];
  if (tradableYears < o.minYears) warnings.push({ code: 'short_history', years: tradableYears, wantedYears: o.minYears });
  if (signals.length === 0) warnings.push({ code: 'no_signals' });
  const fewest = Math.min(...rows.map((r) => r.metrics.trades));
  if (fewest < 30) warnings.push({ code: 'few_trades', trades: fewest });
  for (const row of rows) {
    if (row.baseline && row.baseline.matchedRuns < row.baseline.runs) {
      warnings.push({
        code: 'baseline_unmatched', exit: row.exit, split: row.split, matchedRuns: row.baseline.matchedRuns,
        runs: row.baseline.runs, trades: row.metrics.trades, meanTrades: row.baseline.meanTrades,
      });
    }
  }
  if (o.causalityChecks === 0) warnings.push({ code: 'causality_disabled' });
  if (snapshot.gaps.length) {
    warnings.push({ code: 'data_gaps', gaps: snapshot.gaps.length, missingBars: snapshot.gaps.reduce((sum, g) => sum + g.missingBars, 0) });
  }
  return warnings;
}

function signalRecord(s: Signal, candles: readonly Bar[], segments: readonly Segment[]): SignalRecord {
  const segment = segments.find((seg) => s.bar >= seg.start && s.bar + 1 < seg.end);
  return {
    bar: s.bar,
    time: candles[s.bar].time,
    direction: s.direction,
    entryBar: s.bar + 1,
    entryTime: candles[s.bar + 1]?.time ?? null,
    split: (segment?.name ?? null) as SignalRecord['split'],
    refs: refTimes(s.refs, candles),
    refBars: refBars(s.refs, candles),
  };
}

/**
 * Runs the full protocol on frozen candles, synchronously and without network:
 * causality check of the signal, warm-up, chronological IS/OOS split, every exit on the same
 * entries, costs on both sides, metrics per exit and split, seeded random-entry baseline.
 * Throws a `LOOK_AHEAD` TradingViewError when the signal uses future bars.
 *
 * @example
 * const report = runBacktest(candles, { signal: (bars) => bars.flatMap((b, i) => ...) });
 * console.log(formatReport(report));
 */
export function runBacktest(input: Snapshot | readonly Bar[], options: BacktestOptions): BacktestReport {
  const o = resolveOptions(options);
  const snapshot = toSnapshot(input);
  const { candles } = snapshot;

  // 1. Signals, then their causality: the same rule on shorter history must agree.
  const { signals, causality } = causalSignals(o, candles);

  // 2. Chronological split and entries (always the open of the bar after the signal).
  const { inSample, outOfSample } = splitSegments(candles.length, o.warmupBars, o.splitRatio);
  const entries: Entry[] = signals.map((s) => ({
    direction: s.direction, signalBar: s.bar, entryBar: s.bar + 1, ...(s.refs ? { refs: s.refs } : {}),
  }));

  // 3. Every exit on every segment, with its random baseline.
  const results = o.exits.flatMap((exit) => [inSample, outOfSample].map((segment) => evaluate(o, candles, entries, exit, segment)));
  const rows = results.map((r) => r.row);
  const tradableYears = ((candles.length - inSample.start) * snapshot.barSeconds) / (365.25 * 86_400);

  const costs: Costs = { fee: o.fee, slippage: o.slippage };
  return {
    createdAt: Math.floor(Date.now() / 1000),
    library: { name: pkg.name, version: pkg.version },
    snapshot: snapshotInfo(snapshot),
    settings: {
      signal: {
        id: o.signal.id ?? (o.signal.name || 'custom'),
        params: { ...(o.signal.params ?? {}) },
        label: o.signal.label ?? (o.signal.name || 'custom signal'),
      },
      fee: o.fee,
      slippage: o.slippage,
      splitRatio: o.splitRatio,
      warmupBars: o.warmupBars,
      runs: o.runs,
      seed: o.seed,
      exits: o.exits.map((e) => ({ id: e.id, kind: e.kind ?? null, params: { ...(e.params ?? {}) }, label: e.label })),
    },
    segments: {
      warmup: segmentInfo({ name: 'warmup', start: 0, end: inSample.start }, candles, costs),
      inSample: segmentInfo(inSample, candles, costs),
      outOfSample: segmentInfo(outOfSample, candles, costs),
    },
    tradableYears,
    signals: signals.map((s) => signalRecord(s, candles, [inSample, outOfSample])),
    rows,
    trades: results.flatMap((r) => r.trades),
    causality,
    warnings: reportWarnings(o, snapshot, tradableYears, signals, rows),
  };
}

export interface FetchSnapshotQuery {
  symbol: string;
  timeframe?: Timeframe;
  /** Tradable years wanted after warm-up. Default 2. Ignored with `count` or `from`. */
  years?: number;
  /** Warm-up bars added to the request. Default 200. */
  warmupBars?: number;
  count?: number;
  from?: number;
  to?: number;
  credentials?: CandleQuery['credentials'];
  client?: CandleQuery['client'];
  clientOptions?: CandleQuery['clientOptions'];
  /** Cancels the download. */
  abortSignal?: AbortSignal;
  /** Default 120000: deep history takes several server batches. */
  timeoutMs?: number;
  provider?: MarketDataProvider;
}

/**
 * Downloads candles once with `getCandles` and freezes them (forming bar dropped, gaps and
 * SHA-256 recorded). Save the result with `JSON.stringify` and replay it with `loadSnapshot`.
 */
export async function fetchSnapshot(query: FetchSnapshotQuery): Promise<Snapshot> {
  const timeframe = query.timeframe ?? '240';
  const barSeconds = timeframeSeconds(timeframe);
  if (!barSeconds) throw invalid(`Backtests need a time-based timeframe, got ${timeframe}`);
  const years = query.years ?? BACKTEST_DEFAULTS.minYears;
  const warmup = query.warmupBars ?? BACKTEST_DEFAULTS.signalWarmupBars;
  const range = query.from !== undefined
    ? { from: query.from, to: query.to }
    : { count: query.count ?? Math.ceil((years * 365.25 * 86_400) / barSeconds) + warmup + 1 };
  const candles = await getCandles({
    symbol: query.symbol,
    timeframe,
    ...range,
    timeoutMs: query.timeoutMs ?? 120_000,
    ...(query.credentials ? { credentials: query.credentials } : {}),
    ...(query.client ? { client: query.client } : {}),
    ...(query.clientOptions ? { clientOptions: query.clientOptions } : {}),
    ...(query.abortSignal ? { signal: query.abortSignal } : {}),
  }, query.provider);
  return freezeSnapshot(candles, { symbol: query.symbol, timeframe, barSeconds });
}

export type BacktestQuery = FetchSnapshotQuery & Omit<BacktestOptions, 'minYears'> & {
  /** Replay a saved snapshot instead of downloading candles. */
  snapshot?: Snapshot;
};

/**
 * One call: download (or replay) the candles, freeze them, run the whole protocol.
 * Returns the JSON report and the frozen snapshot (candles included, for charts and replays).
 *
 * @example
 * import { backtest, formatReport } from '@mathieuc/tradingview/backtest';
 * const { report, snapshot } = await backtest({
 *   symbol: 'BINANCE:BTCUSDT', timeframe: '240', years: 2,
 *   signal: (candles) => candles.flatMap((c, i) => (i > 0 && c.close > candles[i - 1].high ? [{ bar: i, direction: 'long' }] : [])),
 * });
 * console.log(formatReport(report));
 * writeFileSync('snapshot.json', JSON.stringify(snapshot)); // Replay later with { snapshot: loadSnapshot(...) }
 */
export async function backtest(query: BacktestQuery): Promise<{ report: BacktestReport; snapshot: Snapshot }> {
  if (typeof query?.signal !== 'function') throw invalid('signal must be a function (candles) => [{ bar, direction }]');
  const exits = query.exits ?? defaultExits();
  const warmupBars = resolveWarmupBars(query.signal, exits, query.warmupBars);
  const snapshot = query.snapshot ?? await fetchSnapshot({ ...query, warmupBars });
  const report = runBacktest(snapshot, {
    ...query, exits, warmupBars, minYears: query.years ?? BACKTEST_DEFAULTS.minYears,
  });
  return { report, snapshot };
}

export interface Market {
  symbol: string;
  timeframe: Timeframe;
  /** Replay a saved snapshot for this market instead of downloading it. */
  snapshot?: Snapshot;
}

export type BacktestManyQuery = Omit<BacktestQuery, 'symbol' | 'timeframe' | 'snapshot' | 'exits'> & {
  markets: readonly Market[];
  /** Same exits everywhere, or exits per market (a wider stop on daily bars...). */
  exits?: readonly ExitModel[] | ((market: Market) => readonly ExitModel[]);
};

export interface MarketResult {
  /** `<symbol>_<timeframe>`, also set as `series` on each trade. */
  id: string;
  symbol: string;
  timeframe: Timeframe;
  report: BacktestReport;
  snapshot: Snapshot;
}

/**
 * The same signal on several markets, one after the other (one download each, or a replay).
 * Every trade gets `series` = the market id, so `tradesToCsv(results.flatMap((r) => r.report.trades))`
 * gives one CSV for all of them.
 */
export async function backtestMany(query: BacktestManyQuery): Promise<MarketResult[]> {
  if (!Array.isArray(query?.markets) || query.markets.length === 0) throw invalid('markets must be a non-empty array of { symbol, timeframe }');
  const results: MarketResult[] = [];
  for (const market of query.markets) {
    const id = `${market.symbol}_${market.timeframe}`;
    if (results.some((r) => r.id === id)) throw invalid(`Duplicate market ${id}`);
    const exits = typeof query.exits === 'function' ? query.exits(market) : query.exits;
    const { report, snapshot } = await backtest({
      ...query, symbol: market.symbol, timeframe: market.timeframe, exits, snapshot: market.snapshot,
    });
    for (const trade of report.trades) trade.series = id;
    results.push({ id, symbol: market.symbol, timeframe: market.timeframe, report, snapshot });
  }
  return results;
}