feat(trading-strategies): volatility trailing-stop utils

Reusable building blocks for sizing a trailing stop to volatility:

- trailStop: percent + ATR trail-price helpers
- AtrPercent: ATR as a percent of price ("usual % move per bar")
- atrUnits: convert between a percentage stop and ATR multiples, plus a
  whippy/balanced/loose classification
- TrendFilter: price-vs-moving-average gate
- MarketRegimeFilter: risk-on/off gate driven by an index series

Author: bennycode

packages/trading-strategies/src/index.ts

@@ -37,6 +37,18 @@ export {
   type ProtectedStrategyState,
 } from './strategy-protected/ProtectedStrategy.js';
 export {suggestScalpOffset} from './strategy-scalp/suggestScalpOffset.js';
+export {atrTrailStop, percentTrailStop, trailStop, type TrailStopOptions} from './util/trailStop.js';
+export {TrendFilter} from './util/TrendFilter.js';
+export {AtrPercent, atrToPercent} from './util/AtrPercent.js';
+export {
+  ATR_TRAIL_BANDS,
+  DEFAULT_ATR_TRAIL_MULTIPLE,
+  atrMultipleToPercent,
+  classifyAtrMultiple,
+  percentToAtrMultiple,
+  type AtrRoomVerdict,
+} from './util/atrUnits.js';
+export {MarketRegimeFilter, type MarketRegimeOptions} from './util/MarketRegimeFilter.js';
 export * from './report/index.js';
 export {
   SP500HeatmapReport,

packages/trading-strategies/src/util/AtrPercent.test.ts

@@ -0,0 +1,42 @@
+import {describe, expect, it} from 'vitest';
+import {AtrPercent, atrToPercent} from './AtrPercent.js';
+
+describe('atrToPercent', () => {
+  it('expresses ATR as a percentage of price', () => {
+    expect(atrToPercent(52.64, 740.53)).toBeCloseTo(7.11, 2);
+  });
+
+  it('is scale-invariant: the same percentage for proportional price and ATR', () => {
+    expect(atrToPercent(0.7, 10)).toBeCloseTo(atrToPercent(70, 1_000), 10);
+  });
+});
+
+describe('AtrPercent', () => {
+  const candles = [
+    {close: 10, high: 11, low: 9},
+    {close: 11, high: 12, low: 10},
+    {close: 12, high: 13, low: 11},
+    {close: 13, high: 14, low: 12},
+  ] as const;
+
+  it('is not ready until the underlying ATR is stable', () => {
+    const atrPercent = new AtrPercent(3);
+
+    atrPercent.add(candles[0]);
+    atrPercent.add(candles[1]);
+
+    expect(atrPercent.isReady).toBe(false);
+    expect(atrPercent.value).toBeNull();
+    expect(atrPercent.atr).toBeNull();
+  });
+
+  it('returns the ATR as a percent of the latest close once warmed up', () => {
+    const atrPercent = new AtrPercent(3);
+
+    candles.forEach(candle => atrPercent.add(candle));
+
+    // ATR settles at 2 over these candles; latest close is 13 → 2 / 13 * 100.
+    expect(atrPercent.atr).toBe(2);
+    expect(atrPercent.value).toBeCloseTo((2 / 13) * 100, 10);
+  });
+});

packages/trading-strategies/src/util/AtrPercent.ts

@@ -0,0 +1,57 @@
+import {ATR, type HighLowClose} from 'trading-signals';
+
+/**
+ * Expresses an ATR reading as a percentage of price: `atr / price * 100`. Normalizing the raw
+ * (price-unit) ATR makes volatility comparable across instruments and timeframes — a $52 ATR
+ * means nothing without the price, but "7% per bar" is directly comparable between a $7 and a
+ * $700 stock.
+ */
+export function atrToPercent(atr: number, price: number) {
+  return (atr / price) * 100;
+}
+
+/**
+ * Average True Range expressed as a percentage of the latest close — the "usual % move per
+ * bar". Feed it `{high, low, close}` candles; once the underlying ATR is warmed up, {@link value}
+ * returns the typical bar range as a percent of price.
+ *
+ * Built on the `ATR` indicator from `trading-signals`, so it inherits Wilder's smoothing. Useful
+ * for sizing volatility-aware stops (see `atrTrailStop`) without hand-tuning a percentage per
+ * symbol, and for asking "is this dip within the instrument's normal range?".
+ */
+export class AtrPercent {
+  readonly #atr: ATR;
+  #lastClose: number | null = null;
+
+  constructor(interval: number) {
+    this.#atr = new ATR(interval);
+  }
+
+  /** Push the next candle. Both the ATR and the reference close are updated. */
+  add(candle: HighLowClose<number>): void {
+    this.#atr.add(candle);
+    this.#lastClose = candle.close;
+  }
+
+  /** `true` once the underlying ATR has enough data to produce a stable reading. */
+  get isReady() {
+    return this.#atr.isStable;
+  }
+
+  /** Raw ATR in price units, or `null` until warmed up. */
+  get atr() {
+    return this.#atr.isStable ? this.#atr.getResultOrThrow() : null;
+  }
+
+  /**
+   * ATR as a percent of the latest close (e.g. `7.1` for 7.1%), or `null` until warmed up or
+   * before any candle has been added.
+   */
+  get value() {
+    if (!this.#atr.isStable || this.#lastClose === null || this.#lastClose === 0) {
+      return null;
+    }
+
+    return atrToPercent(this.#atr.getResultOrThrow(), this.#lastClose);
+  }
+}

packages/trading-strategies/src/util/MarketRegimeFilter.test.ts

@@ -0,0 +1,57 @@
+import {SMA} from 'trading-signals';
+import {describe, expect, it} from 'vitest';
+import {MarketRegimeFilter} from './MarketRegimeFilter.js';
+
+describe('MarketRegimeFilter', () => {
+  it('is not ready, and not risk-on, until the trend average is stable', () => {
+    const filter = new MarketRegimeFilter({trendMovingAverage: new SMA(2)});
+
+    filter.addIndexClose(100);
+
+    expect(filter.isReady).toBe(false);
+    expect(filter.isRiskOn).toBe(false);
+  });
+
+  it('is risk-on while the index holds above its trend line', () => {
+    const filter = new MarketRegimeFilter({trendMovingAverage: new SMA(2)});
+
+    filter.addIndexClose(100);
+    filter.addIndexClose(102);
+
+    expect(filter.isReady).toBe(true);
+    expect(filter.isRiskOn).toBe(true);
+  });
+
+  it('is risk-off when the index closes below its trend line', () => {
+    const filter = new MarketRegimeFilter({trendMovingAverage: new SMA(2)});
+
+    filter.addIndexClose(100);
+    filter.addIndexClose(90);
+
+    expect(filter.isRiskOn).toBe(false);
+  });
+
+  it('tracks drawdown from the running peak close', () => {
+    const filter = new MarketRegimeFilter({trendMovingAverage: new SMA(2)});
+
+    filter.addIndexClose(200);
+    filter.addIndexClose(100);
+    filter.addIndexClose(101);
+
+    expect(filter.drawdown).toBeCloseTo(0.495, 3);
+  });
+
+  it('flips to risk-off on a deep drawdown even while above the trend line', () => {
+    const guarded = new MarketRegimeFilter({maxDrawdownPct: 5, trendMovingAverage: new SMA(2)});
+    const unguarded = new MarketRegimeFilter({trendMovingAverage: new SMA(2)});
+
+    // [100, 101] sits above the SMA(2) of 100.5, but 101 is ~49.5% below the 200 peak.
+    [200, 100, 101].forEach(close => {
+      guarded.addIndexClose(close);
+      unguarded.addIndexClose(close);
+    });
+
+    expect(unguarded.isRiskOn).toBe(true);
+    expect(guarded.isRiskOn).toBe(false);
+  });
+});

packages/trading-strategies/src/util/MarketRegimeFilter.ts

@@ -0,0 +1,79 @@
+import type {MovingAverage} from 'trading-signals';
+import {TrendFilter} from './TrendFilter.js';
+
+export interface MarketRegimeOptions {
+  /** Moving average over the index that defines the regime trend line (e.g. a 50-period SMA of SPY). */
+  trendMovingAverage: MovingAverage;
+  /**
+   * Optional maximum drawdown from the index's running peak close, in percent. When set, the
+   * regime flips to risk-off once the index closes more than this far below its highest close
+   * seen so far — even while it is still above the trend line. Omit to gate on the trend line
+   * alone.
+   */
+  maxDrawdownPct?: number;
+}
+
+/**
+ * Market-regime gate driven by an index series (e.g. SPY or QQQ). Pure and feed-agnostic: the
+ * caller pushes index closes from wherever it sources them, so the calculation is reusable and
+ * unit-testable without any cross-symbol plumbing in the trading session.
+ *
+ * Reports "risk-on" when the index is above its trend line and (optionally) within
+ * `maxDrawdownPct` of its running peak. This is what distinguishes a broad risk-off selloff
+ * (honor the stop, get out) from an idiosyncratic single-name dip (a stock can wobble while the
+ * index holds its trend — hold through it).
+ */
+export class MarketRegimeFilter {
+  readonly #trend: TrendFilter;
+  readonly #maxDrawdownRatio: number | null;
+  #peakClose = 0;
+  #lastClose = 0;
+  #hasData = false;
+
+  constructor(options: MarketRegimeOptions) {
+    this.#trend = new TrendFilter(options.trendMovingAverage);
+    this.#maxDrawdownRatio = options.maxDrawdownPct === undefined ? null : options.maxDrawdownPct / 100;
+  }
+
+  /** Push the next index closing price into the regime model. */
+  addIndexClose(close: number): void {
+    this.#trend.add(close);
+    this.#lastClose = close;
+    this.#hasData = true;
+
+    if (close > this.#peakClose) {
+      this.#peakClose = close;
+    }
+  }
+
+  /** `true` once the trend moving average is warmed up. */
+  get isReady() {
+    return this.#trend.isReady;
+  }
+
+  /** Drawdown from the running peak close as a positive ratio (`0` = at the peak, `0.1` = 10% below). */
+  get drawdown() {
+    if (!this.#hasData || this.#peakClose === 0) {
+      return 0;
+    }
+
+    return (this.#peakClose - this.#lastClose) / this.#peakClose;
+  }
+
+  /**
+   * `true` when the index is at or above its trend line and within the configured drawdown band.
+   * Returns `false` until the trend moving average is warmed up — an un-warmed filter makes no
+   * claim about the regime.
+   */
+  get isRiskOn() {
+    if (!this.#trend.isAbove(this.#lastClose)) {
+      return false;
+    }
+
+    if (this.#maxDrawdownRatio !== null && this.drawdown > this.#maxDrawdownRatio) {
+      return false;
+    }
+
+    return true;
+  }
+}

packages/trading-strategies/src/util/TrendFilter.test.ts

@@ -0,0 +1,51 @@
+import {SMA} from 'trading-signals';
+import {describe, expect, it} from 'vitest';
+import {TrendFilter} from './TrendFilter.js';
+
+describe('TrendFilter', () => {
+  it('is not ready until the moving average is stable', () => {
+    const filter = new TrendFilter(new SMA(3));
+
+    filter.add(10);
+    filter.add(20);
+
+    expect(filter.isReady).toBe(false);
+    expect(filter.value).toBeNull();
+  });
+
+  it('exposes the trend line value once warmed up', () => {
+    const filter = new TrendFilter(new SMA(3));
+
+    filter.add(10);
+    filter.add(20);
+    filter.add(30);
+
+    expect(filter.isReady).toBe(true);
+    expect(filter.value).toBe(20);
+  });
+
+  it('reports prices at or above the trend line as above', () => {
+    const filter = new TrendFilter(new SMA(3));
+
+    [10, 20, 30].forEach(close => filter.add(close));
+
+    expect(filter.isAbove(25)).toBe(true);
+    expect(filter.isAbove(20)).toBe(true);
+  });
+
+  it('reports prices below the trend line as not above', () => {
+    const filter = new TrendFilter(new SMA(3));
+
+    [10, 20, 30].forEach(close => filter.add(close));
+
+    expect(filter.isAbove(19)).toBe(false);
+  });
+
+  it('makes no claim before warmup, so isAbove stays false', () => {
+    const filter = new TrendFilter(new SMA(3));
+
+    filter.add(10);
+
+    expect(filter.isAbove(1_000)).toBe(false);
+  });
+});

packages/trading-strategies/src/util/TrendFilter.ts

@@ -0,0 +1,43 @@
+import type {MovingAverage} from 'trading-signals';
+
+/**
+ * Trend gate over a moving average. Feed it closing prices; once the MA is stable it reports
+ * whether the latest price sits above the trend line. Strategies use it to veto noise-level
+ * exits while the instrument is still in an uptrend — the classic fix for a percentage
+ * trailing stop getting whipsawed out on a dip that never breaks the trend.
+ *
+ * Accepts any `trading-signals` moving average (`SMA`, `EMA`, `WSMA`, …) via their shared
+ * {@link MovingAverage} base. The same primitive, fed an index series instead of the position's
+ * own price, is the building block of {@link MarketRegimeFilter}.
+ */
+export class TrendFilter {
+  readonly #ma: MovingAverage;
+
+  constructor(movingAverage: MovingAverage) {
+    this.#ma = movingAverage;
+  }
+
+  /** Push the next closing price into the underlying moving average. */
+  add(close: number): void {
+    this.#ma.add(close);
+  }
+
+  /** `true` once the moving average has enough data to produce a stable trend line. */
+  get isReady() {
+    return this.#ma.isStable;
+  }
+
+  /** Current trend line value, or `null` until the moving average is warmed up. */
+  get value(): number | null {
+    return this.#ma.isStable ? this.#ma.getResultOrThrow() : null;
+  }
+
+  /**
+   * `true` when `price` is at or above the trend line. Returns `false` until the moving average
+   * is stable — an un-warmed filter makes no claim, so callers naturally fall back to their
+   * unfiltered behavior during warmup.
+   */
+  isAbove(price: number) {
+    return this.#ma.isStable && price >= this.#ma.getResultOrThrow();
+  }
+}

packages/trading-strategies/src/util/atrUnits.test.ts

@@ -0,0 +1,41 @@
+import {describe, expect, it} from 'vitest';
+import {atrMultipleToPercent, classifyAtrMultiple, percentToAtrMultiple} from './atrUnits.js';
+
+describe('percentToAtrMultiple', () => {
+  it('reproduces the STX statement: a 10% trail at 7.11% ATR is ~1.4x ATR', () => {
+    expect(percentToAtrMultiple(10, 7.11)).toBeCloseTo(1.41, 2);
+  });
+
+  it('throws when ATR% is not positive', () => {
+    expect(() => percentToAtrMultiple(10, 0)).toThrowError('atrPercent must be greater than 0');
+  });
+});
+
+describe('atrMultipleToPercent', () => {
+  it('returns the percentage that yields the given ATR multiple', () => {
+    expect(atrMultipleToPercent(3, 7.11)).toBeCloseTo(21.33, 2);
+  });
+
+  it('is the inverse of percentToAtrMultiple', () => {
+    expect(atrMultipleToPercent(percentToAtrMultiple(10, 7.11), 7.11)).toBeCloseTo(10, 10);
+  });
+});
+
+describe('classifyAtrMultiple', () => {
+  it('flags the STX 1.4x trail as whippy', () => {
+    expect(classifyAtrMultiple(1.41)).toBe('whippy');
+  });
+
+  it('treats the Chandelier Exit 3x default as balanced', () => {
+    expect(classifyAtrMultiple(3)).toBe('balanced');
+  });
+
+  it('flags a 4x trail as loose', () => {
+    expect(classifyAtrMultiple(4)).toBe('loose');
+  });
+
+  it('includes the lower edge in balanced and the upper edge in loose', () => {
+    expect(classifyAtrMultiple(2)).toBe('balanced');
+    expect(classifyAtrMultiple(3.5)).toBe('loose');
+  });
+});