finance_query/backtesting/strategy/

mod.rs

//! Strategy trait and context for building trading strategies.
//!
//! This module provides the core `Strategy` trait and `StrategyContext` for
//! implementing custom trading strategies, as well as pre-built strategies
//! and a fluent builder API.
//!
//! # Building Custom Strategies
//!
//! Use the `StrategyBuilder` for creating strategies with conditions:
//!
//! ```ignore
//! use finance_query::backtesting::strategy::StrategyBuilder;
//! use finance_query::backtesting::refs::*;
//! use finance_query::backtesting::condition::*;
//!
//! let strategy = StrategyBuilder::new("My Strategy")
//!     .entry(rsi(14).crosses_below(30.0))
//!     .exit(rsi(14).crosses_above(70.0).or(stop_loss(0.05)))
//!     .build();
//! ```

mod builder;
mod ensemble;
pub mod prebuilt;

use std::collections::HashMap;

use crate::backtesting::condition::HtfIndicatorSpec;
use crate::indicators::Indicator;
use crate::models::chart::Candle;

use super::position::{Position, PositionSide};
use super::signal::Signal;

// Re-export builder
pub use builder::{CustomStrategy, StrategyBuilder};

// Re-export ensemble
pub use ensemble::{EnsembleMode, EnsembleStrategy};

// Re-export prebuilt strategies
pub use prebuilt::{
    BollingerMeanReversion, DonchianBreakout, MacdSignal, RsiReversal, SmaCrossover,
    SuperTrendFollow,
};

/// Price extremes reached since the open position was entered.
///
/// The peak since entry belongs to the position, not to any one condition, so
/// the engine tracks it once per bar and every trailing condition reads the same
/// value instead of each keeping its own running scan.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct PositionExtremes {
    /// Highest bar high since entry.
    pub high: f64,
    /// Lowest bar low since entry.
    pub low: f64,
    /// Highest bar close since entry.
    pub close_high: f64,
    /// Lowest bar close since entry.
    pub close_low: f64,
}

impl PositionExtremes {
    /// Seed the extremes from the entry bar.
    pub(crate) fn new(candle: &Candle) -> Self {
        Self {
            high: candle.high,
            low: candle.low,
            close_high: candle.close,
            close_low: candle.close,
        }
    }

    /// Fold another bar into the running extremes.
    pub(crate) fn update(&mut self, candle: &Candle) {
        self.high = self.high.max(candle.high);
        self.low = self.low.min(candle.low);
        self.close_high = self.close_high.max(candle.close);
        self.close_low = self.close_low.min(candle.close);
    }

    /// Fold every candle in `range` into fresh extremes.
    ///
    /// Used when a context is built outside the engine's bar loop and no running
    /// value is available.
    pub(crate) fn from_candles(candles: &[Candle]) -> Option<Self> {
        let (first, rest) = candles.split_first()?;
        let mut extremes = Self::new(first);
        for c in rest {
            extremes.update(c);
        }
        Some(extremes)
    }
}

/// Context passed to strategy on each candle.
///
/// Provides access to historical data, current position, and pre-computed indicators.
#[non_exhaustive]
pub struct StrategyContext<'a> {
    /// All candles up to and including current
    pub candles: &'a [Candle],

    /// Current candle index (0-based)
    pub index: usize,

    /// Current position (if any)
    pub position: Option<&'a Position>,

    /// Current portfolio equity
    pub equity: f64,

    /// Pre-computed indicator values (keyed by indicator name)
    pub indicators: &'a HashMap<String, Vec<Option<f64>>>,

    /// Price extremes since the open position was entered.
    ///
    /// `None` when no position is open, when no condition in the strategy
    /// reads it, or when the context was built outside the engine's bar loop —
    /// conditions that need it fall back to scanning from the entry bar.
    pub extremes: Option<&'a PositionExtremes>,

    /// Index override for [`indicator`](Self::indicator) /
    /// [`indicator_prev`](Self::indicator_prev) lookups; `None` means `index`.
    ///
    /// [`htf()`](crate::backtesting::refs::htf) keeps candles in base-bar index
    /// space while its indicator map holds a per-bar `[prev, curr]` pair, so
    /// indicator lookups address slot 1 while candle lookups keep `index`.
    pub indicator_index: Option<usize>,
}

impl<'a> StrategyContext<'a> {
    /// Get current candle
    pub fn current_candle(&self) -> &Candle {
        &self.candles[self.index]
    }

    /// Get previous candle (None if at start)
    pub fn previous_candle(&self) -> Option<&Candle> {
        if self.index > 0 {
            Some(&self.candles[self.index - 1])
        } else {
            None
        }
    }

    /// Get candle at specific index (None if out of bounds)
    pub fn candle_at(&self, index: usize) -> Option<&Candle> {
        self.candles.get(index)
    }

    /// Get indicator value at current index
    pub fn indicator(&self, name: &str) -> Option<f64> {
        self.indicators
            .get(name)
            .and_then(|v| v.get(self.indicator_index.unwrap_or(self.index)))
            .and_then(|&v| v)
    }

    /// Get indicator value at specific index
    pub fn indicator_at(&self, name: &str, index: usize) -> Option<f64> {
        self.indicators
            .get(name)
            .and_then(|v| v.get(index))
            .and_then(|&v| v)
    }

    /// Get indicator value at previous index
    pub fn indicator_prev(&self, name: &str) -> Option<f64> {
        let idx = self.indicator_index.unwrap_or(self.index);
        if idx > 0 {
            self.indicator_at(name, idx - 1)
        } else {
            None
        }
    }

    /// Check if we have a position
    pub fn has_position(&self) -> bool {
        self.position.is_some()
    }

    /// Check if we have a long position
    pub fn is_long(&self) -> bool {
        self.position
            .map(|p| matches!(p.side, PositionSide::Long))
            .unwrap_or(false)
    }

    /// Check if we have a short position
    pub fn is_short(&self) -> bool {
        self.position
            .map(|p| matches!(p.side, PositionSide::Short))
            .unwrap_or(false)
    }

    /// Get current close price
    pub fn close(&self) -> f64 {
        self.current_candle().close
    }

    /// Get current open price
    pub fn open(&self) -> f64 {
        self.current_candle().open
    }

    /// Get current high price
    pub fn high(&self) -> f64 {
        self.current_candle().high
    }

    /// Get current low price
    pub fn low(&self) -> f64 {
        self.current_candle().low
    }

    /// Get current volume
    pub fn volume(&self) -> i64 {
        self.current_candle().volume
    }

    /// Get current timestamp
    pub fn timestamp(&self) -> i64 {
        self.current_candle().timestamp
    }

    /// Create a Long signal from the current candle's timestamp and close price.
    pub fn signal_long(&self) -> Signal {
        Signal::long(self.timestamp(), self.close())
    }

    /// Create a Short signal from the current candle's timestamp and close price.
    pub fn signal_short(&self) -> Signal {
        Signal::short(self.timestamp(), self.close())
    }

    /// Create an Exit signal from the current candle's timestamp and close price.
    pub fn signal_exit(&self) -> Signal {
        Signal::exit(self.timestamp(), self.close())
    }

    /// Check if crossover occurred (fast crosses above slow)
    pub fn crossed_above(&self, fast_name: &str, slow_name: &str) -> bool {
        let fast_now = self.indicator(fast_name);
        let slow_now = self.indicator(slow_name);
        let fast_prev = self.indicator_prev(fast_name);
        let slow_prev = self.indicator_prev(slow_name);

        match (fast_now, slow_now, fast_prev, slow_prev) {
            (Some(f), Some(s), Some(fp), Some(sp)) => fp <= sp && f > s,
            _ => false,
        }
    }

    /// Check if crossover occurred (fast crosses below slow)
    pub fn crossed_below(&self, fast_name: &str, slow_name: &str) -> bool {
        let fast_now = self.indicator(fast_name);
        let slow_now = self.indicator(slow_name);
        let fast_prev = self.indicator_prev(fast_name);
        let slow_prev = self.indicator_prev(slow_name);

        match (fast_now, slow_now, fast_prev, slow_prev) {
            (Some(f), Some(s), Some(fp), Some(sp)) => fp >= sp && f < s,
            _ => false,
        }
    }

    /// Check if indicator crossed above a threshold.
    ///
    /// Returns `true` when `prev <= threshold` **and** `current > threshold`.
    /// The inclusive lower bound (`<=`) means a signal fires even when the
    /// previous bar sat exactly on the threshold, the same inclusive-previous
    /// convention [`crossed_above`](Self::crossed_above) uses for
    /// indicator-vs-indicator crossings.
    pub fn indicator_crossed_above(&self, name: &str, threshold: f64) -> bool {
        let now = self.indicator(name);
        let prev = self.indicator_prev(name);

        match (now, prev) {
            (Some(n), Some(p)) => p <= threshold && n > threshold,
            _ => false,
        }
    }

    /// Check if indicator crossed below a threshold.
    ///
    /// Returns `true` when `prev >= threshold` **and** `current < threshold`.
    /// See [`indicator_crossed_above`](Self::indicator_crossed_above) for the
    /// rationale behind the inclusive/exclusive choice on each side.
    pub fn indicator_crossed_below(&self, name: &str, threshold: f64) -> bool {
        let now = self.indicator(name);
        let prev = self.indicator_prev(name);

        match (now, prev) {
            (Some(n), Some(p)) => p >= threshold && n < threshold,
            _ => false,
        }
    }
}

/// Core strategy trait - implement this for custom strategies.
///
/// # Example
///
/// ```ignore
/// use finance_query::backtesting::{Strategy, StrategyContext, Signal};
/// use finance_query::indicators::Indicator;
///
/// struct MyStrategy {
///     sma_period: usize,
/// }
///
/// impl Strategy for MyStrategy {
///     fn name(&self) -> &str {
///         "My Custom Strategy"
///     }
///
///     fn required_indicators(&self) -> Vec<(String, Indicator)> {
///         vec![
///             (format!("sma_{}", self.sma_period), Indicator::Sma(self.sma_period)),
///         ]
///     }
///
///     fn on_candle(&self, ctx: &StrategyContext) -> Signal {
///         let sma = ctx.indicator(&format!("sma_{}", self.sma_period));
///         let close = ctx.close();
///
///         match sma {
///             Some(sma_val) if close > sma_val && !ctx.has_position() => {
///                 Signal::long(ctx.timestamp(), close)
///             }
///             Some(sma_val) if close < sma_val && ctx.is_long() => {
///                 Signal::exit(ctx.timestamp(), close)
///             }
///             _ => Signal::hold(),
///         }
///     }
/// }
/// ```
pub trait Strategy: Send + Sync {
    /// Strategy name (for reporting)
    fn name(&self) -> &str;

    /// Required indicators this strategy needs.
    ///
    /// Returns list of (indicator_name, Indicator) pairs.
    /// The engine will pre-compute these and make them available via `StrategyContext::indicator()`.
    fn required_indicators(&self) -> Vec<(String, Indicator)>;

    /// Higher-timeframe indicators required by this strategy.
    ///
    /// The engine resamples candles to each unique interval, computes the
    /// listed indicators on the resampled data, and stores stretched
    /// (base-timeframe-length) arrays in `StrategyContext::indicators` under
    /// the `htf_key` names. Strategies built with [`StrategyBuilder`] implement
    /// this automatically; raw [`Strategy`] implementations that use HTF
    /// conditions should override this to avoid the O(n²) dynamic fallback.
    ///
    /// [`StrategyBuilder`]: crate::backtesting::strategy::StrategyBuilder
    fn htf_requirements(&self) -> Vec<HtfIndicatorSpec> {
        vec![]
    }

    /// Called once by the engine after indicator pre-computation, before the
    /// simulation loop.  Strategies may cache references into the indicator
    /// map here to avoid per-bar HashMap lookups.  The default implementation
    /// does nothing; pre-built strategies override this for performance.
    fn setup(&mut self, _indicators: &HashMap<String, Vec<Option<f64>>>) {}

    /// Called on each candle to generate a signal.
    ///
    /// Return `Signal::hold()` for no action, `Signal::long()` to enter long,
    /// `Signal::short()` to enter short, or `Signal::exit()` to close position.
    fn on_candle(&self, ctx: &StrategyContext) -> Signal;

    /// Optional: minimum candles required before strategy can generate signals.
    /// Default is 1 (strategy can run from first candle).
    fn warmup_period(&self) -> usize {
        1
    }

    /// Whether any of this strategy's conditions read
    /// [`StrategyContext::extremes`].
    ///
    /// The engine folds the running peak/trough per bar only when this is
    /// `true`, so a strategy with no trailing condition pays nothing for the
    /// feature. Strategies built with [`StrategyBuilder`] compute this
    /// automatically. A raw implementation that uses `TrailingStop` or
    /// `TrailingTakeProfit` still behaves correctly without overriding it —
    /// those conditions fall back to scanning from the entry bar — but should
    /// override it to avoid the O(bars²) fallback.
    ///
    /// [`StrategyBuilder`]: crate::backtesting::strategy::StrategyBuilder
    fn tracks_position_extremes(&self) -> bool {
        false
    }
}

impl Strategy for Box<dyn Strategy> {
    fn name(&self) -> &str {
        (**self).name()
    }
    fn required_indicators(&self) -> Vec<(String, Indicator)> {
        (**self).required_indicators()
    }
    fn htf_requirements(&self) -> Vec<HtfIndicatorSpec> {
        (**self).htf_requirements()
    }
    fn setup(&mut self, indicators: &HashMap<String, Vec<Option<f64>>>) {
        (**self).setup(indicators)
    }
    fn on_candle(&self, ctx: &StrategyContext) -> Signal {
        (**self).on_candle(ctx)
    }
    fn warmup_period(&self) -> usize {
        (**self).warmup_period()
    }
    fn tracks_position_extremes(&self) -> bool {
        (**self).tracks_position_extremes()
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    struct TestStrategy;

    impl Strategy for TestStrategy {
        fn name(&self) -> &str {
            "Test Strategy"
        }

        fn required_indicators(&self) -> Vec<(String, Indicator)> {
            vec![("sma_10".to_string(), Indicator::Sma(10))]
        }

        fn on_candle(&self, ctx: &StrategyContext) -> Signal {
            if ctx.index == 5 {
                Signal::long(ctx.timestamp(), ctx.close())
            } else {
                Signal::hold()
            }
        }
    }

    #[test]
    fn test_strategy_trait() {
        let strategy = TestStrategy;
        assert_eq!(strategy.name(), "Test Strategy");
        assert_eq!(strategy.required_indicators().len(), 1);
        assert_eq!(strategy.warmup_period(), 1);
    }

    #[test]
    fn test_context_crossover_detection() {
        let candles = vec![
            Candle {
                timestamp: 1,
                open: 100.0,
                high: 101.0,
                low: 99.0,
                close: 100.0,
                volume: 1000,
                adj_close: None,
                provider_id: None,
            },
            Candle {
                timestamp: 2,
                open: 100.0,
                high: 102.0,
                low: 99.0,
                close: 101.0,
                volume: 1000,
                adj_close: None,
                provider_id: None,
            },
        ];

        let mut indicators = HashMap::new();
        indicators.insert("fast".to_string(), vec![Some(9.0), Some(11.0)]);
        indicators.insert("slow".to_string(), vec![Some(10.0), Some(10.0)]);

        let ctx = StrategyContext {
            candles: &candles,
            index: 1,
            position: None,
            equity: 10000.0,
            indicators: &indicators,
            extremes: None,
            indicator_index: None,
        };

        // fast was 9 (below slow 10), now 11 (above slow 10) -> crossed above
        assert!(ctx.crossed_above("fast", "slow"));
        assert!(!ctx.crossed_below("fast", "slow"));
    }

    #[test]
    fn test_crossed_above_fires_on_touch() {
        let candles = vec![
            Candle {
                timestamp: 1,
                open: 100.0,
                high: 101.0,
                low: 99.0,
                close: 100.0,
                volume: 1000,
                adj_close: None,
                provider_id: None,
            },
            Candle {
                timestamp: 2,
                open: 100.0,
                high: 102.0,
                low: 99.0,
                close: 101.0,
                volume: 1000,
                adj_close: None,
                provider_id: None,
            },
        ];

        let mut indicators = HashMap::new();
        indicators.insert("fast".to_string(), vec![Some(10.0), Some(11.0)]);
        indicators.insert("slow".to_string(), vec![Some(10.0), Some(10.0)]);

        let ctx = StrategyContext {
            candles: &candles,
            index: 1,
            position: None,
            equity: 10000.0,
            indicators: &indicators,
            extremes: None,
            indicator_index: None,
        };

        // fast was exactly equal to slow (10 == 10), now above (11 > 10) -> crosses above
        assert!(ctx.crossed_above("fast", "slow"));
    }
}