backtest-kit 1.5.33 → 1.5.35

package/build/index.cjs

@@ -1438,7 +1438,7 @@ class LoggerService {
     }
 }
 
-const INTERVAL_MINUTES$3 = {
+const INTERVAL_MINUTES$4 = {
     "1m": 1,
     "3m": 3,
     "5m": 5,
@@ -1583,7 +1583,7 @@ class ClientExchange {
             interval,
             limit,
         });
-        const step = INTERVAL_MINUTES$3[interval];
+        const step = INTERVAL_MINUTES$4[interval];
         const adjust = step * limit - step;
         if (!adjust) {
             throw new Error(`ClientExchange unknown time adjust for interval=${interval}`);
@@ -1621,7 +1621,7 @@ class ClientExchange {
         const since = new Date(this.params.execution.context.when.getTime());
         const now = Date.now();
         // Вычисляем конечное время запроса
-        const step = INTERVAL_MINUTES$3[interval];
+        const step = INTERVAL_MINUTES$4[interval];
         const endTime = since.getTime() + limit * step * 60 * 1000;
         // Проверяем что запрошенный период не заходит за Date.now()
         if (endTime > now) {
@@ -2845,7 +2845,7 @@ var emitters = /*#__PURE__*/Object.freeze({
     walkerStopSubject: walkerStopSubject
 });
 
-const INTERVAL_MINUTES$2 = {
+const INTERVAL_MINUTES$3 = {
     "1m": 1,
     "3m": 3,
     "5m": 5,
@@ -3063,7 +3063,7 @@ const GET_SIGNAL_FN = functoolsKit.trycatch(async (self) => {
     }
     const currentTime = self.params.execution.context.when.getTime();
     {
-        const intervalMinutes = INTERVAL_MINUTES$2[self.params.interval];
+        const intervalMinutes = INTERVAL_MINUTES$3[self.params.interval];
         const intervalMs = intervalMinutes * 60 * 1000;
         // Проверяем что прошел нужный интервал с последнего getSignal
         if (self._lastSignalTimestamp !== null &&
@@ -4811,7 +4811,7 @@ class StrategyConnectionService {
  * Maps FrameInterval to minutes for timestamp calculation.
  * Used to generate timeframe arrays with proper spacing.
  */
-const INTERVAL_MINUTES$1 = {
+const INTERVAL_MINUTES$2 = {
     "1m": 1,
     "3m": 3,
     "5m": 5,
@@ -4840,7 +4840,7 @@ const GET_TIMEFRAME_FN = async (symbol, self) => {
         symbol,
     });
     const { interval, startDate, endDate } = self.params;
-    const intervalMinutes = INTERVAL_MINUTES$1[interval];
+    const intervalMinutes = INTERVAL_MINUTES$2[interval];
     if (!intervalMinutes) {
         throw new Error(`ClientFrame unknown interval: ${interval}`);
     }
@@ -18142,7 +18142,7 @@ const EXCHANGE_METHOD_NAME_GET_CANDLES = "ExchangeUtils.getCandles";
 const EXCHANGE_METHOD_NAME_GET_AVERAGE_PRICE = "ExchangeUtils.getAveragePrice";
 const EXCHANGE_METHOD_NAME_FORMAT_QUANTITY = "ExchangeUtils.formatQuantity";
 const EXCHANGE_METHOD_NAME_FORMAT_PRICE = "ExchangeUtils.formatPrice";
-const INTERVAL_MINUTES = {
+const INTERVAL_MINUTES$1 = {
     "1m": 1,
     "3m": 3,
     "5m": 5,
@@ -18203,7 +18203,7 @@ class ExchangeInstance {
                 interval,
                 limit,
             });
-            const step = INTERVAL_MINUTES[interval];
+            const step = INTERVAL_MINUTES$1[interval];
             const adjust = step * limit - step;
             if (!adjust) {
                 throw new Error(`ExchangeInstance unknown time adjust for interval=${interval}`);
@@ -18426,7 +18426,219 @@ class ExchangeUtils {
  */
 const Exchange = new ExchangeUtils();
 
+const CACHE_METHOD_NAME_CLEAR = "CacheUtils.clear";
+const CACHE_METHOD_NAME_RUN = "CacheInstance.run";
+const CACHE_METHOD_NAME_FN = "CacheUtils.fn";
+const INTERVAL_MINUTES = {
+    "1m": 1,
+    "3m": 3,
+    "5m": 5,
+    "15m": 15,
+    "30m": 30,
+    "1h": 60,
+    "2h": 120,
+    "4h": 240,
+    "6h": 360,
+    "8h": 480,
+};
+const createKey = (strategyName, exchangeName, backtest) => `${strategyName}:${exchangeName}:${backtest ? "backtest" : "live"}`;
+/**
+ * Instance class for caching function results with timeframe-based invalidation.
+ *
+ * Provides automatic cache invalidation based on candle intervals.
+ * Each instance maintains its own cache map keyed by strategy, exchange, and mode.
+ * Cache is invalidated when the current time moves to a different interval.
+ *
+ * @template T - Function type to cache
+ *
+ * @example
+ * ```typescript
+ * const instance = new CacheInstance(myExpensiveFunction, "1h");
+ * const result = instance.run(arg1, arg2); // Computed
+ * const result2 = instance.run(arg1, arg2); // Cached (within same hour)
+ * // After 1 hour passes
+ * const result3 = instance.run(arg1, arg2); // Recomputed
+ * ```
+ */
+class CacheInstance {
+    /**
+     * Creates a new CacheInstance for a specific function and interval.
+     *
+     * @param fn - Function to cache
+     * @param interval - Candle interval for cache invalidation (e.g., "1m", "1h")
+     */
+    constructor(fn, interval) {
+        this.fn = fn;
+        this.interval = interval;
+        /** Cache map storing results per strategy/exchange/mode combination */
+        this._cacheMap = new Map();
+        /**
+         * Execute function with caching based on timeframe intervals.
+         *
+         * This method implements intelligent time-based caching:
+         * 1. Generates cache key from strategy name, exchange name, and execution mode (backtest/live)
+         * 2. Checks if cached value exists and is still valid for current interval
+         * 3. Returns cached value if time elapsed is less than interval duration
+         * 4. Recomputes and caches new value when moving to next interval boundary
+         *
+         * Cache invalidation example with 15m interval:
+         * - 10:00 AM: First call → computes and caches result
+         * - 10:05 AM: Same interval → returns cached result
+         * - 10:15 AM: New interval → recomputes and caches new result
+         *
+         * Requires active execution context (strategy, exchange, backtest mode) and method context.
+         * Each unique combination of these contexts maintains separate cache entries.
+         *
+         * @param args - Arguments to pass to the cached function
+         * @returns Cached result object containing:
+         *   - `value`: The computed or cached function result
+         *   - `when`: Timestamp when this value was cached
+         * @throws Error if interval is unknown or required context is missing
+         *
+         * @example
+         * ```typescript
+         * const instance = new CacheInstance(calculateIndicator, "15m");
+         * const result = instance.run("BTCUSDT", 100);
+         * console.log(result.value); // Calculated value
+         * console.log(result.when); // Cache timestamp
+         * ```
+         */
+        this.run = (...args) => {
+            backtest$1.loggerService.debug(CACHE_METHOD_NAME_RUN, { args });
+            const step = INTERVAL_MINUTES[this.interval];
+            if (!step) {
+                throw new Error(`CacheInstance unknown cache ttl interval=${this.interval}`);
+            }
+            if (!MethodContextService.hasContext()) {
+                throw new Error("CacheInstance run requires method context");
+            }
+            if (!ExecutionContextService.hasContext()) {
+                throw new Error("CacheInstance run requires execution context");
+            }
+            const key = createKey(backtest$1.methodContextService.context.strategyName, backtest$1.methodContextService.context.exchangeName, backtest$1.executionContextService.context.backtest);
+            const currentWhen = backtest$1.executionContextService.context.when;
+            const cached = this._cacheMap.get(key);
+            if (cached) {
+                const stepMs = step * 60 * 1000;
+                const elapsed = currentWhen.getTime() - cached.when.getTime();
+                if (elapsed < stepMs) {
+                    return cached;
+                }
+            }
+            const newCache = {
+                when: currentWhen,
+                value: this.fn(...args),
+            };
+            this._cacheMap.set(key, newCache);
+            return newCache;
+        };
+    }
+}
+/**
+ * Utility class for function caching with timeframe-based invalidation.
+ *
+ * Provides simplified API for wrapping functions with automatic caching.
+ * Exported as singleton instance for convenient usage.
+ *
+ * @example
+ * ```typescript
+ * import { Cache } from "./classes/Cache";
+ *
+ * const cachedFn = Cache.fn(expensiveCalculation, "1h");
+ * const result = cachedFn(arg1, arg2); // Computed on first call
+ * const result2 = cachedFn(arg1, arg2); // Cached (within same hour)
+ * ```
+ */
+class CacheUtils {
+    constructor() {
+        /**
+         * Memoized function to get or create CacheInstance for a function.
+         * Each function gets its own isolated cache instance.
+         */
+        this._getInstance = functoolsKit.memoize(([run]) => run, (run, interval) => new CacheInstance(run, interval));
+        /**
+         * Wrap a function with caching based on timeframe intervals.
+         *
+         * Returns a wrapped version of the function that automatically caches results
+         * and invalidates based on the specified candle interval.
+         *
+         * @template T - Function type to cache
+         * @param run - Function to wrap with caching
+         * @param interval - Candle interval for cache invalidation (e.g., "1m", "1h")
+         * @returns Wrapped function with automatic caching
+         *
+         * @example
+         * ```typescript
+         * const calculateIndicator = (symbol: string, period: number) => {
+         *   // Expensive calculation
+         *   return result;
+         * };
+         *
+         * const cachedCalculate = Cache.fn(calculateIndicator, "15m");
+         * const result = cachedCalculate("BTCUSDT", 14); // Computed
+         * const result2 = cachedCalculate("BTCUSDT", 14); // Cached (same 15m interval)
+         * ```
+         */
+        this.fn = (run, context) => {
+            backtest$1.loggerService.debug(CACHE_METHOD_NAME_FN, {
+                context,
+            });
+            return (...args) => {
+                const instance = this._getInstance(run, context.interval);
+                return instance.run(...args).value;
+            };
+        };
+        /**
+         * Clear cached instances for specific function or all cached functions.
+         *
+         * This method delegates to the memoized `_getInstance` function's clear method,
+         * which removes cached CacheInstance objects. When a CacheInstance is removed,
+         * all cached function results for that instance are also discarded.
+         *
+         * Use cases:
+         * - Clear cache for a specific function when its implementation changes
+         * - Free memory by removing unused cached instances
+         * - Reset all caches when switching contexts (e.g., between different backtests)
+         *
+         * @param run - Optional function to clear cache for. If omitted, clears all cached instances.
+         *
+         * @example
+         * ```typescript
+         * const cachedCalc = Cache.fn(calculateIndicator, { interval: "1h" });
+         *
+         * // Clear cache for specific function
+         * Cache.clear(calculateIndicator);
+         *
+         * // Clear all cached instances
+         * Cache.clear();
+         * ```
+         */
+        this.clear = (run) => {
+            backtest$1.loggerService.debug(CACHE_METHOD_NAME_CLEAR, {
+                run,
+            });
+            this._getInstance.clear(run);
+        };
+    }
+}
+/**
+ * Singleton instance of CacheUtils for convenient function caching.
+ *
+ * @example
+ * ```typescript
+ * import { Cache } from "./classes/Cache";
+ *
+ * // Wrap expensive function with 1-hour cache
+ * const cachedFn = Cache.fn(myExpensiveFunction, "1h");
+ * const result = cachedFn(arg1, arg2);
+ *
+ * // Cache is automatically invalidated when moving to next hour interval
+ * ```
+ */
+const Cache = new CacheUtils();
+
 exports.Backtest = Backtest;
+exports.Cache = Cache;
 exports.Constant = Constant;
 exports.Exchange = Exchange;
 exports.ExecutionContextService = ExecutionContextService;

package/build/index.mjs

@@ -1436,7 +1436,7 @@ class LoggerService {
     }
 }
 
-const INTERVAL_MINUTES$3 = {
+const INTERVAL_MINUTES$4 = {
     "1m": 1,
     "3m": 3,
     "5m": 5,
@@ -1581,7 +1581,7 @@ class ClientExchange {
             interval,
             limit,
         });
-        const step = INTERVAL_MINUTES$3[interval];
+        const step = INTERVAL_MINUTES$4[interval];
         const adjust = step * limit - step;
         if (!adjust) {
             throw new Error(`ClientExchange unknown time adjust for interval=${interval}`);
@@ -1619,7 +1619,7 @@ class ClientExchange {
         const since = new Date(this.params.execution.context.when.getTime());
         const now = Date.now();
         // Вычисляем конечное время запроса
-        const step = INTERVAL_MINUTES$3[interval];
+        const step = INTERVAL_MINUTES$4[interval];
         const endTime = since.getTime() + limit * step * 60 * 1000;
         // Проверяем что запрошенный период не заходит за Date.now()
         if (endTime > now) {
@@ -2843,7 +2843,7 @@ var emitters = /*#__PURE__*/Object.freeze({
     walkerStopSubject: walkerStopSubject
 });
 
-const INTERVAL_MINUTES$2 = {
+const INTERVAL_MINUTES$3 = {
     "1m": 1,
     "3m": 3,
     "5m": 5,
@@ -3061,7 +3061,7 @@ const GET_SIGNAL_FN = trycatch(async (self) => {
     }
     const currentTime = self.params.execution.context.when.getTime();
     {
-        const intervalMinutes = INTERVAL_MINUTES$2[self.params.interval];
+        const intervalMinutes = INTERVAL_MINUTES$3[self.params.interval];
         const intervalMs = intervalMinutes * 60 * 1000;
         // Проверяем что прошел нужный интервал с последнего getSignal
         if (self._lastSignalTimestamp !== null &&
@@ -4809,7 +4809,7 @@ class StrategyConnectionService {
  * Maps FrameInterval to minutes for timestamp calculation.
  * Used to generate timeframe arrays with proper spacing.
  */
-const INTERVAL_MINUTES$1 = {
+const INTERVAL_MINUTES$2 = {
     "1m": 1,
     "3m": 3,
     "5m": 5,
@@ -4838,7 +4838,7 @@ const GET_TIMEFRAME_FN = async (symbol, self) => {
         symbol,
     });
     const { interval, startDate, endDate } = self.params;
-    const intervalMinutes = INTERVAL_MINUTES$1[interval];
+    const intervalMinutes = INTERVAL_MINUTES$2[interval];
     if (!intervalMinutes) {
         throw new Error(`ClientFrame unknown interval: ${interval}`);
     }
@@ -18140,7 +18140,7 @@ const EXCHANGE_METHOD_NAME_GET_CANDLES = "ExchangeUtils.getCandles";
 const EXCHANGE_METHOD_NAME_GET_AVERAGE_PRICE = "ExchangeUtils.getAveragePrice";
 const EXCHANGE_METHOD_NAME_FORMAT_QUANTITY = "ExchangeUtils.formatQuantity";
 const EXCHANGE_METHOD_NAME_FORMAT_PRICE = "ExchangeUtils.formatPrice";
-const INTERVAL_MINUTES = {
+const INTERVAL_MINUTES$1 = {
     "1m": 1,
     "3m": 3,
     "5m": 5,
@@ -18201,7 +18201,7 @@ class ExchangeInstance {
                 interval,
                 limit,
             });
-            const step = INTERVAL_MINUTES[interval];
+            const step = INTERVAL_MINUTES$1[interval];
             const adjust = step * limit - step;
             if (!adjust) {
                 throw new Error(`ExchangeInstance unknown time adjust for interval=${interval}`);
@@ -18424,4 +18424,215 @@ class ExchangeUtils {
  */
 const Exchange = new ExchangeUtils();
 
-export { Backtest, Constant, Exchange, ExecutionContextService, Heat, Live, MethodContextService, Optimizer, Partial, Performance, PersistBase, PersistPartialAdapter, PersistRiskAdapter, PersistScheduleAdapter, PersistSignalAdapter, PositionSize, Risk, Schedule, Walker, addExchange, addFrame, addOptimizer, addRisk, addSizing, addStrategy, addWalker, dumpSignal, emitters, formatPrice, formatQuantity, getAveragePrice, getCandles, getColumns, getConfig, getDate, getDefaultColumns, getDefaultConfig, getMode, hasTradeContext, backtest as lib, listExchanges, listFrames, listOptimizers, listRisks, listSizings, listStrategies, listWalkers, listenBacktestProgress, listenDoneBacktest, listenDoneBacktestOnce, listenDoneLive, listenDoneLiveOnce, listenDoneWalker, listenDoneWalkerOnce, listenError, listenExit, listenOptimizerProgress, listenPartialLoss, listenPartialLossOnce, listenPartialProfit, listenPartialProfitOnce, listenPerformance, listenRisk, listenRiskOnce, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, listenValidation, listenWalker, listenWalkerComplete, listenWalkerOnce, listenWalkerProgress, setColumns, setConfig, setLogger };
+const CACHE_METHOD_NAME_CLEAR = "CacheUtils.clear";
+const CACHE_METHOD_NAME_RUN = "CacheInstance.run";
+const CACHE_METHOD_NAME_FN = "CacheUtils.fn";
+const INTERVAL_MINUTES = {
+    "1m": 1,
+    "3m": 3,
+    "5m": 5,
+    "15m": 15,
+    "30m": 30,
+    "1h": 60,
+    "2h": 120,
+    "4h": 240,
+    "6h": 360,
+    "8h": 480,
+};
+const createKey = (strategyName, exchangeName, backtest) => `${strategyName}:${exchangeName}:${backtest ? "backtest" : "live"}`;
+/**
+ * Instance class for caching function results with timeframe-based invalidation.
+ *
+ * Provides automatic cache invalidation based on candle intervals.
+ * Each instance maintains its own cache map keyed by strategy, exchange, and mode.
+ * Cache is invalidated when the current time moves to a different interval.
+ *
+ * @template T - Function type to cache
+ *
+ * @example
+ * ```typescript
+ * const instance = new CacheInstance(myExpensiveFunction, "1h");
+ * const result = instance.run(arg1, arg2); // Computed
+ * const result2 = instance.run(arg1, arg2); // Cached (within same hour)
+ * // After 1 hour passes
+ * const result3 = instance.run(arg1, arg2); // Recomputed
+ * ```
+ */
+class CacheInstance {
+    /**
+     * Creates a new CacheInstance for a specific function and interval.
+     *
+     * @param fn - Function to cache
+     * @param interval - Candle interval for cache invalidation (e.g., "1m", "1h")
+     */
+    constructor(fn, interval) {
+        this.fn = fn;
+        this.interval = interval;
+        /** Cache map storing results per strategy/exchange/mode combination */
+        this._cacheMap = new Map();
+        /**
+         * Execute function with caching based on timeframe intervals.
+         *
+         * This method implements intelligent time-based caching:
+         * 1. Generates cache key from strategy name, exchange name, and execution mode (backtest/live)
+         * 2. Checks if cached value exists and is still valid for current interval
+         * 3. Returns cached value if time elapsed is less than interval duration
+         * 4. Recomputes and caches new value when moving to next interval boundary
+         *
+         * Cache invalidation example with 15m interval:
+         * - 10:00 AM: First call → computes and caches result
+         * - 10:05 AM: Same interval → returns cached result
+         * - 10:15 AM: New interval → recomputes and caches new result
+         *
+         * Requires active execution context (strategy, exchange, backtest mode) and method context.
+         * Each unique combination of these contexts maintains separate cache entries.
+         *
+         * @param args - Arguments to pass to the cached function
+         * @returns Cached result object containing:
+         *   - `value`: The computed or cached function result
+         *   - `when`: Timestamp when this value was cached
+         * @throws Error if interval is unknown or required context is missing
+         *
+         * @example
+         * ```typescript
+         * const instance = new CacheInstance(calculateIndicator, "15m");
+         * const result = instance.run("BTCUSDT", 100);
+         * console.log(result.value); // Calculated value
+         * console.log(result.when); // Cache timestamp
+         * ```
+         */
+        this.run = (...args) => {
+            backtest$1.loggerService.debug(CACHE_METHOD_NAME_RUN, { args });
+            const step = INTERVAL_MINUTES[this.interval];
+            if (!step) {
+                throw new Error(`CacheInstance unknown cache ttl interval=${this.interval}`);
+            }
+            if (!MethodContextService.hasContext()) {
+                throw new Error("CacheInstance run requires method context");
+            }
+            if (!ExecutionContextService.hasContext()) {
+                throw new Error("CacheInstance run requires execution context");
+            }
+            const key = createKey(backtest$1.methodContextService.context.strategyName, backtest$1.methodContextService.context.exchangeName, backtest$1.executionContextService.context.backtest);
+            const currentWhen = backtest$1.executionContextService.context.when;
+            const cached = this._cacheMap.get(key);
+            if (cached) {
+                const stepMs = step * 60 * 1000;
+                const elapsed = currentWhen.getTime() - cached.when.getTime();
+                if (elapsed < stepMs) {
+                    return cached;
+                }
+            }
+            const newCache = {
+                when: currentWhen,
+                value: this.fn(...args),
+            };
+            this._cacheMap.set(key, newCache);
+            return newCache;
+        };
+    }
+}
+/**
+ * Utility class for function caching with timeframe-based invalidation.
+ *
+ * Provides simplified API for wrapping functions with automatic caching.
+ * Exported as singleton instance for convenient usage.
+ *
+ * @example
+ * ```typescript
+ * import { Cache } from "./classes/Cache";
+ *
+ * const cachedFn = Cache.fn(expensiveCalculation, "1h");
+ * const result = cachedFn(arg1, arg2); // Computed on first call
+ * const result2 = cachedFn(arg1, arg2); // Cached (within same hour)
+ * ```
+ */
+class CacheUtils {
+    constructor() {
+        /**
+         * Memoized function to get or create CacheInstance for a function.
+         * Each function gets its own isolated cache instance.
+         */
+        this._getInstance = memoize(([run]) => run, (run, interval) => new CacheInstance(run, interval));
+        /**
+         * Wrap a function with caching based on timeframe intervals.
+         *
+         * Returns a wrapped version of the function that automatically caches results
+         * and invalidates based on the specified candle interval.
+         *
+         * @template T - Function type to cache
+         * @param run - Function to wrap with caching
+         * @param interval - Candle interval for cache invalidation (e.g., "1m", "1h")
+         * @returns Wrapped function with automatic caching
+         *
+         * @example
+         * ```typescript
+         * const calculateIndicator = (symbol: string, period: number) => {
+         *   // Expensive calculation
+         *   return result;
+         * };
+         *
+         * const cachedCalculate = Cache.fn(calculateIndicator, "15m");
+         * const result = cachedCalculate("BTCUSDT", 14); // Computed
+         * const result2 = cachedCalculate("BTCUSDT", 14); // Cached (same 15m interval)
+         * ```
+         */
+        this.fn = (run, context) => {
+            backtest$1.loggerService.debug(CACHE_METHOD_NAME_FN, {
+                context,
+            });
+            return (...args) => {
+                const instance = this._getInstance(run, context.interval);
+                return instance.run(...args).value;
+            };
+        };
+        /**
+         * Clear cached instances for specific function or all cached functions.
+         *
+         * This method delegates to the memoized `_getInstance` function's clear method,
+         * which removes cached CacheInstance objects. When a CacheInstance is removed,
+         * all cached function results for that instance are also discarded.
+         *
+         * Use cases:
+         * - Clear cache for a specific function when its implementation changes
+         * - Free memory by removing unused cached instances
+         * - Reset all caches when switching contexts (e.g., between different backtests)
+         *
+         * @param run - Optional function to clear cache for. If omitted, clears all cached instances.
+         *
+         * @example
+         * ```typescript
+         * const cachedCalc = Cache.fn(calculateIndicator, { interval: "1h" });
+         *
+         * // Clear cache for specific function
+         * Cache.clear(calculateIndicator);
+         *
+         * // Clear all cached instances
+         * Cache.clear();
+         * ```
+         */
+        this.clear = (run) => {
+            backtest$1.loggerService.debug(CACHE_METHOD_NAME_CLEAR, {
+                run,
+            });
+            this._getInstance.clear(run);
+        };
+    }
+}
+/**
+ * Singleton instance of CacheUtils for convenient function caching.
+ *
+ * @example
+ * ```typescript
+ * import { Cache } from "./classes/Cache";
+ *
+ * // Wrap expensive function with 1-hour cache
+ * const cachedFn = Cache.fn(myExpensiveFunction, "1h");
+ * const result = cachedFn(arg1, arg2);
+ *
+ * // Cache is automatically invalidated when moving to next hour interval
+ * ```
+ */
+const Cache = new CacheUtils();
+
+export { Backtest, Cache, Constant, Exchange, ExecutionContextService, Heat, Live, MethodContextService, Optimizer, Partial, Performance, PersistBase, PersistPartialAdapter, PersistRiskAdapter, PersistScheduleAdapter, PersistSignalAdapter, PositionSize, Risk, Schedule, Walker, addExchange, addFrame, addOptimizer, addRisk, addSizing, addStrategy, addWalker, dumpSignal, emitters, formatPrice, formatQuantity, getAveragePrice, getCandles, getColumns, getConfig, getDate, getDefaultColumns, getDefaultConfig, getMode, hasTradeContext, backtest as lib, listExchanges, listFrames, listOptimizers, listRisks, listSizings, listStrategies, listWalkers, listenBacktestProgress, listenDoneBacktest, listenDoneBacktestOnce, listenDoneLive, listenDoneLiveOnce, listenDoneWalker, listenDoneWalkerOnce, listenError, listenExit, listenOptimizerProgress, listenPartialLoss, listenPartialLossOnce, listenPartialProfit, listenPartialProfitOnce, listenPerformance, listenRisk, listenRiskOnce, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, listenValidation, listenWalker, listenWalkerComplete, listenWalkerOnce, listenWalkerProgress, setColumns, setConfig, setLogger };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backtest-kit",
-  "version": "1.5.33",
+  "version": "1.5.35",
   "description": "A TypeScript library for trading system backtest",
   "author": {
     "name": "Petr Tripolsky",

package/types.d.ts

@@ -7814,6 +7814,101 @@ declare class ExchangeUtils {
  */
 declare const Exchange: ExchangeUtils;
 
+/**
+ * Generic function type that accepts any arguments and returns any value.
+ * Used as a constraint for cached functions.
+ */
+type Function = (...args: any[]) => any;
+/**
+ * Utility class for function caching with timeframe-based invalidation.
+ *
+ * Provides simplified API for wrapping functions with automatic caching.
+ * Exported as singleton instance for convenient usage.
+ *
+ * @example
+ * ```typescript
+ * import { Cache } from "./classes/Cache";
+ *
+ * const cachedFn = Cache.fn(expensiveCalculation, "1h");
+ * const result = cachedFn(arg1, arg2); // Computed on first call
+ * const result2 = cachedFn(arg1, arg2); // Cached (within same hour)
+ * ```
+ */
+declare class CacheUtils {
+    /**
+     * Memoized function to get or create CacheInstance for a function.
+     * Each function gets its own isolated cache instance.
+     */
+    private _getInstance;
+    /**
+     * Wrap a function with caching based on timeframe intervals.
+     *
+     * Returns a wrapped version of the function that automatically caches results
+     * and invalidates based on the specified candle interval.
+     *
+     * @template T - Function type to cache
+     * @param run - Function to wrap with caching
+     * @param interval - Candle interval for cache invalidation (e.g., "1m", "1h")
+     * @returns Wrapped function with automatic caching
+     *
+     * @example
+     * ```typescript
+     * const calculateIndicator = (symbol: string, period: number) => {
+     *   // Expensive calculation
+     *   return result;
+     * };
+     *
+     * const cachedCalculate = Cache.fn(calculateIndicator, "15m");
+     * const result = cachedCalculate("BTCUSDT", 14); // Computed
+     * const result2 = cachedCalculate("BTCUSDT", 14); // Cached (same 15m interval)
+     * ```
+     */
+    fn: <T extends Function>(run: T, context: {
+        interval: CandleInterval;
+    }) => Function;
+    /**
+     * Clear cached instances for specific function or all cached functions.
+     *
+     * This method delegates to the memoized `_getInstance` function's clear method,
+     * which removes cached CacheInstance objects. When a CacheInstance is removed,
+     * all cached function results for that instance are also discarded.
+     *
+     * Use cases:
+     * - Clear cache for a specific function when its implementation changes
+     * - Free memory by removing unused cached instances
+     * - Reset all caches when switching contexts (e.g., between different backtests)
+     *
+     * @param run - Optional function to clear cache for. If omitted, clears all cached instances.
+     *
+     * @example
+     * ```typescript
+     * const cachedCalc = Cache.fn(calculateIndicator, { interval: "1h" });
+     *
+     * // Clear cache for specific function
+     * Cache.clear(calculateIndicator);
+     *
+     * // Clear all cached instances
+     * Cache.clear();
+     * ```
+     */
+    clear: <T extends Function>(run?: T) => void;
+}
+/**
+ * Singleton instance of CacheUtils for convenient function caching.
+ *
+ * @example
+ * ```typescript
+ * import { Cache } from "./classes/Cache";
+ *
+ * // Wrap expensive function with 1-hour cache
+ * const cachedFn = Cache.fn(myExpensiveFunction, "1h");
+ * const result = cachedFn(arg1, arg2);
+ *
+ * // Cache is automatically invalidated when moving to next hour interval
+ * ```
+ */
+declare const Cache: CacheUtils;
+
 /**
  * Contract for walker stop signal events.
  *
@@ -10649,4 +10744,4 @@ declare const backtest: {
     loggerService: LoggerService;
 };
 
-export { Backtest, type BacktestStatisticsModel, type CandleInterval, type ColumnConfig, type ColumnModel, Constant, type DoneContract, type EntityId, Exchange, ExecutionContextService, type FrameInterval, type GlobalConfig, Heat, type HeatmapStatisticsModel, type ICandleData, type IExchangeSchema, type IFrameSchema, type IHeatmapRow, type IOptimizerCallbacks, type IOptimizerData, type IOptimizerFetchArgs, type IOptimizerFilterArgs, type IOptimizerRange, type IOptimizerSchema, type IOptimizerSource, type IOptimizerStrategy, type IOptimizerTemplate, type IPersistBase, type IPositionSizeATRParams, type IPositionSizeFixedPercentageParams, type IPositionSizeKellyParams, type IRiskActivePosition, type IRiskCheckArgs, type IRiskSchema, type IRiskValidation, type IRiskValidationFn, type IRiskValidationPayload, type IScheduledSignalRow, type ISignalDto, type ISignalRow, type ISizingCalculateParams, type ISizingCalculateParamsATR, type ISizingCalculateParamsFixedPercentage, type ISizingCalculateParamsKelly, type ISizingSchema, type ISizingSchemaATR, type ISizingSchemaFixedPercentage, type ISizingSchemaKelly, type IStrategyPnL, type IStrategySchema, type IStrategyTickResult, type IStrategyTickResultActive, type IStrategyTickResultCancelled, type IStrategyTickResultClosed, type IStrategyTickResultIdle, type IStrategyTickResultOpened, type IStrategyTickResultScheduled, type IWalkerResults, type IWalkerSchema, type IWalkerStrategyResult, Live, type LiveStatisticsModel, type MessageModel, type MessageRole, MethodContextService, Optimizer, Partial$1 as Partial, type PartialData, type PartialLossContract, type PartialProfitContract, type PartialStatisticsModel, Performance, type PerformanceContract, type PerformanceMetricType, type PerformanceStatisticsModel, PersistBase, PersistPartialAdapter, PersistRiskAdapter, PersistScheduleAdapter, PersistSignalAdapter, PositionSize, type ProgressBacktestContract, type ProgressOptimizerContract, type ProgressWalkerContract, Risk, type RiskContract, type RiskData, type RiskStatisticsModel, Schedule, type ScheduleData, type ScheduleStatisticsModel, type SignalData, type SignalInterval, type TPersistBase, type TPersistBaseCtor, Walker, type WalkerCompleteContract, type WalkerContract, type WalkerMetric, type WalkerStatisticsModel, addExchange, addFrame, addOptimizer, addRisk, addSizing, addStrategy, addWalker, dumpSignal, emitters, formatPrice, formatQuantity, getAveragePrice, getCandles, getColumns, getConfig, getDate, getDefaultColumns, getDefaultConfig, getMode, hasTradeContext, backtest as lib, listExchanges, listFrames, listOptimizers, listRisks, listSizings, listStrategies, listWalkers, listenBacktestProgress, listenDoneBacktest, listenDoneBacktestOnce, listenDoneLive, listenDoneLiveOnce, listenDoneWalker, listenDoneWalkerOnce, listenError, listenExit, listenOptimizerProgress, listenPartialLoss, listenPartialLossOnce, listenPartialProfit, listenPartialProfitOnce, listenPerformance, listenRisk, listenRiskOnce, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, listenValidation, listenWalker, listenWalkerComplete, listenWalkerOnce, listenWalkerProgress, setColumns, setConfig, setLogger };
+export { Backtest, type BacktestStatisticsModel, Cache, type CandleInterval, type ColumnConfig, type ColumnModel, Constant, type DoneContract, type EntityId, Exchange, ExecutionContextService, type FrameInterval, type GlobalConfig, Heat, type HeatmapStatisticsModel, type ICandleData, type IExchangeSchema, type IFrameSchema, type IHeatmapRow, type IOptimizerCallbacks, type IOptimizerData, type IOptimizerFetchArgs, type IOptimizerFilterArgs, type IOptimizerRange, type IOptimizerSchema, type IOptimizerSource, type IOptimizerStrategy, type IOptimizerTemplate, type IPersistBase, type IPositionSizeATRParams, type IPositionSizeFixedPercentageParams, type IPositionSizeKellyParams, type IRiskActivePosition, type IRiskCheckArgs, type IRiskSchema, type IRiskValidation, type IRiskValidationFn, type IRiskValidationPayload, type IScheduledSignalRow, type ISignalDto, type ISignalRow, type ISizingCalculateParams, type ISizingCalculateParamsATR, type ISizingCalculateParamsFixedPercentage, type ISizingCalculateParamsKelly, type ISizingSchema, type ISizingSchemaATR, type ISizingSchemaFixedPercentage, type ISizingSchemaKelly, type IStrategyPnL, type IStrategySchema, type IStrategyTickResult, type IStrategyTickResultActive, type IStrategyTickResultCancelled, type IStrategyTickResultClosed, type IStrategyTickResultIdle, type IStrategyTickResultOpened, type IStrategyTickResultScheduled, type IWalkerResults, type IWalkerSchema, type IWalkerStrategyResult, Live, type LiveStatisticsModel, type MessageModel, type MessageRole, MethodContextService, Optimizer, Partial$1 as Partial, type PartialData, type PartialLossContract, type PartialProfitContract, type PartialStatisticsModel, Performance, type PerformanceContract, type PerformanceMetricType, type PerformanceStatisticsModel, PersistBase, PersistPartialAdapter, PersistRiskAdapter, PersistScheduleAdapter, PersistSignalAdapter, PositionSize, type ProgressBacktestContract, type ProgressOptimizerContract, type ProgressWalkerContract, Risk, type RiskContract, type RiskData, type RiskStatisticsModel, Schedule, type ScheduleData, type ScheduleStatisticsModel, type SignalData, type SignalInterval, type TPersistBase, type TPersistBaseCtor, Walker, type WalkerCompleteContract, type WalkerContract, type WalkerMetric, type WalkerStatisticsModel, addExchange, addFrame, addOptimizer, addRisk, addSizing, addStrategy, addWalker, dumpSignal, emitters, formatPrice, formatQuantity, getAveragePrice, getCandles, getColumns, getConfig, getDate, getDefaultColumns, getDefaultConfig, getMode, hasTradeContext, backtest as lib, listExchanges, listFrames, listOptimizers, listRisks, listSizings, listStrategies, listWalkers, listenBacktestProgress, listenDoneBacktest, listenDoneBacktestOnce, listenDoneLive, listenDoneLiveOnce, listenDoneWalker, listenDoneWalkerOnce, listenError, listenExit, listenOptimizerProgress, listenPartialLoss, listenPartialLossOnce, listenPartialProfit, listenPartialProfitOnce, listenPerformance, listenRisk, listenRiskOnce, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, listenValidation, listenWalker, listenWalkerComplete, listenWalkerOnce, listenWalkerProgress, setColumns, setConfig, setLogger };