TimeFrameUtils

// This Pine Script™ code is subject to the terms of the Mozilla Public License 2.0
// © Yavuz365
// TimeFrameUtils Library - Multi-Timeframe Utility Functions with Anti-Repaint Protection

//@version=5
// @description Multi-Timeframe utility functions for TradingView indicators.
// Provides optimized MTF data fetching, timeframe conversion, and signal aggregation.
// OPTIMIZED: Single request.security() calls, repaint protection with barstate.isconfirmed
library("TimeFrameUtils", overlay=true)

// ============================================================================
// TIMEFRAME CONVERSION UTILITIES
// ============================================================================

// @function Converts timeframe string to minutes
// @param tf Timeframe string (e.g., "15", "60", "D", "W")
// @returns Number of minutes in the timeframe
export tfToMinutes(simple string tf) =>
    switch tf
        "1" => 1
        "3" => 3
        "5" => 5
        "15" => 15
        "30" => 30
        "45" => 45
        "60" => 60
        "120" => 120
        "180" => 180
        "240" => 240
        "D" => 1440
        "W" => 10080
        "M" => 43200
        => 60  // Default to 1 hour

// @function Checks if target timeframe is higher than current
// @param targetTf Target timeframe to compare
// @returns True if target is higher timeframe
export isHigherTimeframe(simple string targetTf) =>
    tfToMinutes(targetTf) > tfToMinutes(timeframe.period)

// ============================================================================
// MTF DATA FETCHING (Optimized for TradingView limits - ~40 request.* calls max)
// NOTE: Each request.security() call counts toward TradingView's limit
// Current implementation uses ~15-18 calls with 3 timeframes
// ============================================================================

// @function Gets RSI value from specified timeframe (1 request.security call)
// @param src Source series
// @param length RSI period
// @param tf Target timeframe
// @param confirmOnly If true, only returns value when bar is confirmed (no repaint)
// @returns RSI value from target timeframe
export mtfRSI(series float src, simple int length, simple string tf, simple bool confirmOnly = false) =>
    rsiVal = request.security(syminfo.tickerid, tf, ta.rsi(src, length), lookahead=barmerge.lookahead_off)
    confirmOnly and not barstate.isconfirmed ? na : rsiVal

// @function Gets MACD values from specified timeframe (OPTIMIZED: 1 request.security call instead of 3)
// @param src Source series
// @param fast Fast period
// @param slow Slow period
// @param signal Signal period
// @param tf Target timeframe
// @param confirmOnly If true, only returns value when bar is confirmed (no repaint)
// @returns [macdLine, signalLine, histogram]
export mtfMACD(series float src, simple int fast, simple int slow, simple int signal, simple string tf, simple bool confirmOnly = false) =>
    [macdVal, sigVal, histVal] = request.security(syminfo.tickerid, tf, ta.macd(src, fast, slow, signal), lookahead=barmerge.lookahead_off)
    if confirmOnly and not barstate.isconfirmed
        [na, na, na]
    else
        [macdVal, sigVal, histVal]

// @function Gets Stochastic values from specified timeframe (OPTIMIZED: 1 request.security call)
// @param length Stochastic period
// @param smoothK K smoothing
// @param smoothD D smoothing
// @param tf Target timeframe
// @param confirmOnly If true, only returns value when bar is confirmed (no repaint)
// @returns [K, D]
export mtfStoch(simple int length, simple int smoothK, simple int smoothD, simple string tf, simple bool confirmOnly = false) =>
    k = ta.stoch(close, high, low, length)
    kSmoothed = ta.sma(k, smoothK)
    dSmoothed = ta.sma(kSmoothed, smoothD)
    mtfK = request.security(syminfo.tickerid, tf, kSmoothed, lookahead=barmerge.lookahead_off)
    mtfD = request.security(syminfo.tickerid, tf, dSmoothed, lookahead=barmerge.lookahead_off)
    if confirmOnly and not barstate.isconfirmed
        [na, na]
    else
        [mtfK, mtfD]

// @function Gets EMA from specified timeframe (1 request.security call)
// @param src Source series
// @param length EMA period
// @param tf Target timeframe
// @param confirmOnly If true, only returns value when bar is confirmed (no repaint)
// @returns EMA value
export mtfEMA(series float src, simple int length, simple string tf, simple bool confirmOnly = false) =>
    emaVal = request.security(syminfo.tickerid, tf, ta.ema(src, length), lookahead=barmerge.lookahead_off)
    confirmOnly and not barstate.isconfirmed ? na : emaVal

// @function Gets SMA from specified timeframe (1 request.security call)
// @param src Source series
// @param length SMA period
// @param tf Target timeframe
// @param confirmOnly If true, only returns value when bar is confirmed (no repaint)
// @returns SMA value
export mtfSMA(series float src, simple int length, simple string tf, simple bool confirmOnly = false) =>
    smaVal = request.security(syminfo.tickerid, tf, ta.sma(src, length), lookahead=barmerge.lookahead_off)
    confirmOnly and not barstate.isconfirmed ? na : smaVal

// @function Gets ATR from specified timeframe (1 request.security call)
// @param length ATR period
// @param tf Target timeframe
// @param confirmOnly If true, only returns value when bar is confirmed (no repaint)
// @returns ATR value
export mtfATR(simple int length, simple string tf, simple bool confirmOnly = false) =>
    atrVal = request.security(syminfo.tickerid, tf, ta.atr(length), lookahead=barmerge.lookahead_off)
    confirmOnly and not barstate.isconfirmed ? na : atrVal

// ============================================================================
// SIGNAL GENERATION UTILITIES
// ============================================================================

// @function Standardizes signal to -1 (Sell), 0 (Neutral), 1 (Buy)
// @param bullish Bullish condition
// @param bearish Bearish condition
// @returns Standardized signal (-1, 0, or 1)
export standardSignal(bool bullish, bool bearish) =>
    bullish ? 1 : bearish ? -1 : 0

// @function Calculates confluence score from multiple signals
// @param signals Array of signals (-1, 0, 1)
// @returns Confluence score (sum of signals)
export confluenceScore(array<int> signals) =>
    score = 0
    for sig in signals
        score += sig
    score

// @function Checks if RSI shows divergence (ANTI-REPAINT: uses confirmed bars only)
// @param rsi RSI series
// @param price Price series
// @param lookback Lookback period for comparison
// @returns [bullishDiv, bearishDiv]
export rsiDivergence(series float rsi, series float price, simple int lookback) =>
    // Only compute on confirmed bars to prevent repainting
    if not barstate.isconfirmed
        [false, false]
    else
        // Price makes lower low but RSI makes higher low = Bullish Divergence
        priceLowerLow = price < ta.lowest(price, lookback)[1]
        rsiHigherLow = rsi > ta.lowest(rsi, lookback)[1]
        bullishDiv = priceLowerLow and rsiHigherLow and rsi < 30

        // Price makes higher high but RSI makes lower high = Bearish Divergence
        priceHigherHigh = price > ta.highest(price, lookback)[1]
        rsiLowerHigh = rsi < ta.highest(rsi, lookback)[1]
        bearishDiv = priceHigherHigh and rsiLowerHigh and rsi > 70

        [bullishDiv, bearishDiv]

// @function Checks if MACD shows divergence (ANTI-REPAINT)
// @param macd MACD line series
// @param price Price series
// @param lookback Lookback period
// @returns [bullishDiv, bearishDiv]
export macdDivergence(series float macd, series float price, simple int lookback) =>
    if not barstate.isconfirmed
        [false, false]
    else
        priceLowerLow = price < ta.lowest(price, lookback)[1]
        macdHigherLow = macd > ta.lowest(macd, lookback)[1]
        bullishDiv = priceLowerLow and macdHigherLow

        priceHigherHigh = price > ta.highest(price, lookback)[1]
        macdLowerHigh = macd < ta.highest(macd, lookback)[1]
        bearishDiv = priceHigherHigh and macdLowerHigh

        [bullishDiv, bearishDiv]

// ============================================================================
// TIMEFRAME ARRAY UTILITIES
// ============================================================================

// @function Creates standard MTF array
// @returns Array of common timeframes
export getStandardTimeframes() =>
    tfs = array.new_string()
    array.push(tfs, "15")
    array.push(tfs, "60")
    array.push(tfs, "240")
    array.push(tfs, "D")
    tfs

// @function Gets timeframe display name
// @param tf Timeframe string
// @returns Human-readable timeframe name
export tfDisplayName(simple string tf) =>
    switch tf
        "1" => "1m"
        "3" => "3m"
        "5" => "5m"
        "15" => "15m"
        "30" => "30m"
        "45" => "45m"
        "60" => "1H"
        "120" => "2H"
        "180" => "3H"
        "240" => "4H"
        "D" => "1D"
        "W" => "1W"
        "M" => "1M"
        => tf