backtest-kit 3.0.5 → 3.0.7

package/README.md

@@ -1,4 +1,4 @@
-<img src="./assets/triangle.svg" height="45px" align="right">
+<img src="https://github.com/tripolskypetr/backtest-kit/raw/refs/heads/master/assets/consciousness.svg" height="45px" align="right">
 
 # 🧿 Backtest Kit
 

package/build/index.cjs

@@ -727,7 +727,7 @@ const INTERVAL_MINUTES$5 = {
     "6h": 360,
     "8h": 480,
 };
-const MS_PER_MINUTE$2 = 60000;
+const MS_PER_MINUTE$3 = 60000;
 const PERSIST_SIGNAL_UTILS_METHOD_NAME_USE_PERSIST_SIGNAL_ADAPTER = "PersistSignalUtils.usePersistSignalAdapter";
 const PERSIST_SIGNAL_UTILS_METHOD_NAME_READ_DATA = "PersistSignalUtils.readSignalData";
 const PERSIST_SIGNAL_UTILS_METHOD_NAME_WRITE_DATA = "PersistSignalUtils.writeSignalData";
@@ -1625,7 +1625,7 @@ class PersistCandleUtils {
             const isInitial = !this.getCandlesStorage.has(key);
             const stateStorage = this.getCandlesStorage(symbol, interval, exchangeName);
             await stateStorage.waitForInit(isInitial);
-            const stepMs = INTERVAL_MINUTES$5[interval] * MS_PER_MINUTE$2;
+            const stepMs = INTERVAL_MINUTES$5[interval] * MS_PER_MINUTE$3;
             // Calculate expected timestamps and fetch each candle directly
             const cachedCandles = [];
             for (let i = 0; i < limit; i++) {
@@ -1681,7 +1681,7 @@ class PersistCandleUtils {
             const stateStorage = this.getCandlesStorage(symbol, interval, exchangeName);
             await stateStorage.waitForInit(isInitial);
             // Calculate step in milliseconds to determine candle close time
-            const stepMs = INTERVAL_MINUTES$5[interval] * MS_PER_MINUTE$2;
+            const stepMs = INTERVAL_MINUTES$5[interval] * MS_PER_MINUTE$3;
             const now = Date.now();
             // Write each candle as a separate file, skipping incomplete candles
             for (const candle of candles) {
@@ -1938,7 +1938,7 @@ class PersistNotificationUtils {
  */
 const PersistNotificationAdapter = new PersistNotificationUtils();
 
-const MS_PER_MINUTE$1 = 60000;
+const MS_PER_MINUTE$2 = 60000;
 const INTERVAL_MINUTES$4 = {
     "1m": 1,
     "3m": 3,
@@ -1969,7 +1969,7 @@ const INTERVAL_MINUTES$4 = {
  * @returns Aligned timestamp rounded down to interval boundary
  */
 const ALIGN_TO_INTERVAL_FN$1 = (timestamp, intervalMinutes) => {
-    const intervalMs = intervalMinutes * MS_PER_MINUTE$1;
+    const intervalMs = intervalMinutes * MS_PER_MINUTE$2;
     return Math.floor(timestamp / intervalMs) * intervalMs;
 };
 /**
@@ -2116,7 +2116,7 @@ const WRITE_CANDLES_CACHE_FN$1 = functoolsKit.trycatch(functoolsKit.queued(async
 const GET_CANDLES_FN = async (dto, since, self) => {
     const step = INTERVAL_MINUTES$4[dto.interval];
     const sinceTimestamp = since.getTime();
-    const untilTimestamp = sinceTimestamp + dto.limit * step * MS_PER_MINUTE$1;
+    const untilTimestamp = sinceTimestamp + dto.limit * step * MS_PER_MINUTE$2;
     // Try to read from cache first
     const cachedCandles = await READ_CANDLES_CACHE_FN$1(dto, sinceTimestamp, untilTimestamp, self);
     if (cachedCandles !== null) {
@@ -2228,7 +2228,7 @@ class ClientExchange {
         if (!step) {
             throw new Error(`ClientExchange unknown interval=${interval}`);
         }
-        const stepMs = step * MS_PER_MINUTE$1;
+        const stepMs = step * MS_PER_MINUTE$2;
         // Align when down to interval boundary
         const whenTimestamp = this.params.execution.context.when.getTime();
         const alignedWhen = ALIGN_TO_INTERVAL_FN$1(whenTimestamp, step);
@@ -2309,7 +2309,7 @@ class ClientExchange {
         if (!step) {
             throw new Error(`ClientExchange getNextCandles: unknown interval=${interval}`);
         }
-        const stepMs = step * MS_PER_MINUTE$1;
+        const stepMs = step * MS_PER_MINUTE$2;
         const now = Date.now();
         // Align when down to interval boundary
         const whenTimestamp = this.params.execution.context.when.getTime();
@@ -2477,7 +2477,7 @@ class ClientExchange {
         if (!step) {
             throw new Error(`ClientExchange getRawCandles: unknown interval=${interval}`);
         }
-        const stepMs = step * MS_PER_MINUTE$1;
+        const stepMs = step * MS_PER_MINUTE$2;
         const whenTimestamp = this.params.execution.context.when.getTime();
         const alignedWhen = ALIGN_TO_INTERVAL_FN$1(whenTimestamp, step);
         let sinceTimestamp;
@@ -2604,7 +2604,7 @@ class ClientExchange {
         });
         const to = new Date(this.params.execution.context.when.getTime());
         const from = new Date(to.getTime() -
-            GLOBAL_CONFIG.CC_ORDER_BOOK_TIME_OFFSET_MINUTES * MS_PER_MINUTE$1);
+            GLOBAL_CONFIG.CC_ORDER_BOOK_TIME_OFFSET_MINUTES * MS_PER_MINUTE$2);
         return await this.params.getOrderBook(symbol, depth, from, to, this.params.execution.context.backtest);
     }
 }
@@ -35527,7 +35527,7 @@ const EXCHANGE_METHOD_NAME_FORMAT_QUANTITY = "ExchangeUtils.formatQuantity";
 const EXCHANGE_METHOD_NAME_FORMAT_PRICE = "ExchangeUtils.formatPrice";
 const EXCHANGE_METHOD_NAME_GET_ORDER_BOOK = "ExchangeUtils.getOrderBook";
 const EXCHANGE_METHOD_NAME_GET_RAW_CANDLES = "ExchangeUtils.getRawCandles";
-const MS_PER_MINUTE = 60000;
+const MS_PER_MINUTE$1 = 60000;
 /**
  * Gets current timestamp from execution context if available.
  * Returns current Date() if no execution context exists (non-trading GUI).
@@ -35612,7 +35612,7 @@ const INTERVAL_MINUTES$1 = {
  * @returns Aligned timestamp rounded down to interval boundary
  */
 const ALIGN_TO_INTERVAL_FN = (timestamp, intervalMinutes) => {
-    const intervalMs = intervalMinutes * MS_PER_MINUTE;
+    const intervalMs = intervalMinutes * MS_PER_MINUTE$1;
     return Math.floor(timestamp / intervalMs) * intervalMs;
 };
 /**
@@ -35754,7 +35754,7 @@ class ExchangeInstance {
             if (!step) {
                 throw new Error(`ExchangeInstance unknown interval=${interval}`);
             }
-            const stepMs = step * MS_PER_MINUTE;
+            const stepMs = step * MS_PER_MINUTE$1;
             // Align when down to interval boundary
             const when = await GET_TIMESTAMP_FN();
             const whenTimestamp = when.getTime();
@@ -35931,7 +35931,7 @@ class ExchangeInstance {
                 depth,
             });
             const to = await GET_TIMESTAMP_FN();
-            const from = new Date(to.getTime() - GLOBAL_CONFIG.CC_ORDER_BOOK_TIME_OFFSET_MINUTES * MS_PER_MINUTE);
+            const from = new Date(to.getTime() - GLOBAL_CONFIG.CC_ORDER_BOOK_TIME_OFFSET_MINUTES * MS_PER_MINUTE$1);
             const isBacktest = await GET_BACKTEST_FN();
             return await this._methods.getOrderBook(symbol, depth, from, to, isBacktest);
         };
@@ -35978,7 +35978,7 @@ class ExchangeInstance {
             if (!step) {
                 throw new Error(`ExchangeInstance getRawCandles: unknown interval=${interval}`);
             }
-            const stepMs = step * MS_PER_MINUTE;
+            const stepMs = step * MS_PER_MINUTE$1;
             const when = await GET_TIMESTAMP_FN();
             const nowTimestamp = when.getTime();
             const alignedNow = ALIGN_TO_INTERVAL_FN(nowTimestamp, step);
@@ -36251,6 +36251,7 @@ const CACHE_METHOD_NAME_FLUSH = "CacheUtils.flush";
 const CACHE_METHOD_NAME_CLEAR = "CacheInstance.clear";
 const CACHE_METHOD_NAME_RUN = "CacheInstance.run";
 const CACHE_METHOD_NAME_FN = "CacheUtils.fn";
+const MS_PER_MINUTE = 60000;
 const INTERVAL_MINUTES = {
     "1m": 1,
     "3m": 3,
@@ -36263,6 +36264,34 @@ const INTERVAL_MINUTES = {
     "6h": 360,
     "8h": 480,
 };
+/**
+ * Aligns timestamp down to the nearest interval boundary.
+ * For example, for 15m interval: 00:17 -> 00:15, 00:44 -> 00:30
+ *
+ * @param timestamp - Timestamp in milliseconds
+ * @param interval - Candle interval
+ * @returns Aligned timestamp rounded down to interval boundary
+ * @throws Error if interval is unknown
+ *
+ * @example
+ * ```typescript
+ * // Align to 15-minute boundary
+ * const aligned = align(new Date("2025-10-01T00:35:00Z").getTime(), "15m");
+ * // Returns timestamp for 2025-10-01T00:30:00Z
+ *
+ * // Align to 1-hour boundary
+ * const aligned = align(new Date("2025-10-01T01:47:00Z").getTime(), "1h");
+ * // Returns timestamp for 2025-10-01T01:00:00Z
+ * ```
+ */
+const align = (timestamp, interval) => {
+    const intervalMinutes = INTERVAL_MINUTES[interval];
+    if (!intervalMinutes) {
+        throw new Error(`align: unknown interval=${interval}`);
+    }
+    const intervalMs = intervalMinutes * MS_PER_MINUTE;
+    return Math.floor(timestamp / intervalMs) * intervalMs;
+};
 /**
  * Create a cache key string from strategy name, exchange name, and backtest mode.
  *
@@ -36278,6 +36307,11 @@ const CREATE_KEY_FN = (strategyName, exchangeName, frameName, backtest) => {
     parts.push(backtest ? "backtest" : "live");
     return parts.join(":");
 };
+/**
+ * A unique symbol representing a value that should never occur.
+ * Used as default key when no key function is provided.
+ */
+const NEVER_VALUE = Symbol("never");
 /**
  * Instance class for caching function results with timeframe-based invalidation.
  *
@@ -36286,6 +36320,7 @@ const CREATE_KEY_FN = (strategyName, exchangeName, frameName, backtest) => {
  * Cache is invalidated when the current time moves to a different interval.
  *
  * @template T - Function type to cache
+ * @template K - Key type for argument-based caching
  *
  * @example
  * ```typescript
@@ -36302,11 +36337,13 @@ class CacheInstance {
      *
      * @param fn - Function to cache
      * @param interval - Candle interval for cache invalidation (e.g., "1m", "1h")
+     * @param key - Optional key generator function for argument-based caching
      */
-    constructor(fn, interval) {
+    constructor(fn, interval, key = () => NEVER_VALUE) {
         this.fn = fn;
         this.interval = interval;
-        /** Cache map storing results per strategy/exchange/mode combination */
+        this.key = key;
+        /** Cache map storing results per strategy/exchange/mode/argKey combination */
         this._cacheMap = new Map();
         /**
          * Execute function with caching based on timeframe intervals.
@@ -36353,13 +36390,15 @@ class CacheInstance {
                     throw new Error(`CacheInstance unknown cache ttl interval=${this.interval}`);
                 }
             }
-            const key = CREATE_KEY_FN(bt.methodContextService.context.strategyName, bt.methodContextService.context.exchangeName, bt.methodContextService.context.frameName, bt.executionContextService.context.backtest);
+            const contextKey = CREATE_KEY_FN(bt.methodContextService.context.strategyName, bt.methodContextService.context.exchangeName, bt.methodContextService.context.frameName, bt.executionContextService.context.backtest);
+            const argKey = String(this.key(args));
+            const key = `${contextKey}:${argKey}`;
             const currentWhen = bt.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 >= 0 && elapsed < stepMs) {
+                const currentAligned = align(currentWhen.getTime(), this.interval);
+                const cachedAligned = align(cached.when.getTime(), this.interval);
+                if (currentAligned === cachedAligned) {
                     return cached;
                 }
             }
@@ -36371,13 +36410,13 @@ class CacheInstance {
             return newCache;
         };
         /**
-         * Clear cached value for current execution context.
+         * Clear cached values for current execution context.
          *
-         * Removes the cached entry for the current strategy/exchange/mode combination
+         * Removes all cached entries for the current strategy/exchange/mode combination
          * from this instance's cache map. The next `run()` call will recompute the value.
          *
          * Requires active execution context (strategy, exchange, backtest mode) and method context
-         * to determine which cache entry to clear.
+         * to determine which cache entries to clear.
          *
          * @example
          * ```typescript
@@ -36385,14 +36424,19 @@ class CacheInstance {
          * const result1 = instance.run("BTCUSDT", 14); // Computed
          * const result2 = instance.run("BTCUSDT", 14); // Cached
          *
-         * instance.clear(); // Clear cache for current context
+         * instance.clear(); // Clear all cache entries for current context
          *
          * const result3 = instance.run("BTCUSDT", 14); // Recomputed
          * ```
          */
         this.clear = () => {
-            const key = CREATE_KEY_FN(bt.methodContextService.context.strategyName, bt.methodContextService.context.exchangeName, bt.methodContextService.context.frameName, bt.executionContextService.context.backtest);
-            this._cacheMap.delete(key);
+            const contextKey = CREATE_KEY_FN(bt.methodContextService.context.strategyName, bt.methodContextService.context.exchangeName, bt.methodContextService.context.frameName, bt.executionContextService.context.backtest);
+            const prefix = `${contextKey}:`;
+            for (const key of this._cacheMap.keys()) {
+                if (key.startsWith(prefix)) {
+                    this._cacheMap.delete(key);
+                }
+            }
         };
     }
 }
@@ -36417,7 +36461,7 @@ class CacheUtils {
          * 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));
+        this._getInstance = functoolsKit.memoize(([run]) => run, (run, interval, key) => new CacheInstance(run, interval, key));
         /**
          * Wrap a function with caching based on timeframe intervals.
          *
@@ -36425,8 +36469,10 @@ class CacheUtils {
          * and invalidates based on the specified candle interval.
          *
          * @template T - Function type to cache
+         * @template K - Key type for argument-based caching
          * @param run - Function to wrap with caching
-         * @param interval - Candle interval for cache invalidation (e.g., "1m", "1h")
+         * @param context.interval - Candle interval for cache invalidation (e.g., "1m", "1h")
+         * @param context.key - Optional key generator function for argument-based caching
          * @returns Wrapped function with automatic caching
          *
          * @example
@@ -36436,9 +36482,17 @@ class CacheUtils {
          *   return result;
          * };
          *
-         * const cachedCalculate = Cache.fn(calculateIndicator, "15m");
-         * const result = cachedCalculate("BTCUSDT", 14); // Computed
-         * const result2 = cachedCalculate("BTCUSDT", 14); // Cached (same 15m interval)
+         * // Without key - single cache entry per context
+         * const cachedCalculate = Cache.fn(calculateIndicator, { interval: "15m" });
+         *
+         * // With key - separate cache entries per symbol
+         * const cachedCalculate = Cache.fn(calculateIndicator, {
+         *   interval: "15m",
+         *   key: ([symbol]) => symbol,
+         * });
+         * const result1 = cachedCalculate("BTCUSDT", 14); // Computed
+         * const result2 = cachedCalculate("ETHUSDT", 14); // Computed (different key)
+         * const result3 = cachedCalculate("BTCUSDT", 14); // Cached (same key, same interval)
          * ```
          */
         this.fn = (run, context) => {
@@ -36446,7 +36500,7 @@ class CacheUtils {
                 context,
             });
             const wrappedFn = (...args) => {
-                const instance = this._getInstance(run, context.interval);
+                const instance = this._getInstance(run, context.interval, context.key);
                 return instance.run(...args).value;
             };
             return wrappedFn;

package/build/index.mjs

@@ -707,7 +707,7 @@ const INTERVAL_MINUTES$5 = {
     "6h": 360,
     "8h": 480,
 };
-const MS_PER_MINUTE$2 = 60000;
+const MS_PER_MINUTE$3 = 60000;
 const PERSIST_SIGNAL_UTILS_METHOD_NAME_USE_PERSIST_SIGNAL_ADAPTER = "PersistSignalUtils.usePersistSignalAdapter";
 const PERSIST_SIGNAL_UTILS_METHOD_NAME_READ_DATA = "PersistSignalUtils.readSignalData";
 const PERSIST_SIGNAL_UTILS_METHOD_NAME_WRITE_DATA = "PersistSignalUtils.writeSignalData";
@@ -1605,7 +1605,7 @@ class PersistCandleUtils {
             const isInitial = !this.getCandlesStorage.has(key);
             const stateStorage = this.getCandlesStorage(symbol, interval, exchangeName);
             await stateStorage.waitForInit(isInitial);
-            const stepMs = INTERVAL_MINUTES$5[interval] * MS_PER_MINUTE$2;
+            const stepMs = INTERVAL_MINUTES$5[interval] * MS_PER_MINUTE$3;
             // Calculate expected timestamps and fetch each candle directly
             const cachedCandles = [];
             for (let i = 0; i < limit; i++) {
@@ -1661,7 +1661,7 @@ class PersistCandleUtils {
             const stateStorage = this.getCandlesStorage(symbol, interval, exchangeName);
             await stateStorage.waitForInit(isInitial);
             // Calculate step in milliseconds to determine candle close time
-            const stepMs = INTERVAL_MINUTES$5[interval] * MS_PER_MINUTE$2;
+            const stepMs = INTERVAL_MINUTES$5[interval] * MS_PER_MINUTE$3;
             const now = Date.now();
             // Write each candle as a separate file, skipping incomplete candles
             for (const candle of candles) {
@@ -1918,7 +1918,7 @@ class PersistNotificationUtils {
  */
 const PersistNotificationAdapter = new PersistNotificationUtils();
 
-const MS_PER_MINUTE$1 = 60000;
+const MS_PER_MINUTE$2 = 60000;
 const INTERVAL_MINUTES$4 = {
     "1m": 1,
     "3m": 3,
@@ -1949,7 +1949,7 @@ const INTERVAL_MINUTES$4 = {
  * @returns Aligned timestamp rounded down to interval boundary
  */
 const ALIGN_TO_INTERVAL_FN$1 = (timestamp, intervalMinutes) => {
-    const intervalMs = intervalMinutes * MS_PER_MINUTE$1;
+    const intervalMs = intervalMinutes * MS_PER_MINUTE$2;
     return Math.floor(timestamp / intervalMs) * intervalMs;
 };
 /**
@@ -2096,7 +2096,7 @@ const WRITE_CANDLES_CACHE_FN$1 = trycatch(queued(async (candles, dto, self) => {
 const GET_CANDLES_FN = async (dto, since, self) => {
     const step = INTERVAL_MINUTES$4[dto.interval];
     const sinceTimestamp = since.getTime();
-    const untilTimestamp = sinceTimestamp + dto.limit * step * MS_PER_MINUTE$1;
+    const untilTimestamp = sinceTimestamp + dto.limit * step * MS_PER_MINUTE$2;
     // Try to read from cache first
     const cachedCandles = await READ_CANDLES_CACHE_FN$1(dto, sinceTimestamp, untilTimestamp, self);
     if (cachedCandles !== null) {
@@ -2208,7 +2208,7 @@ class ClientExchange {
         if (!step) {
             throw new Error(`ClientExchange unknown interval=${interval}`);
         }
-        const stepMs = step * MS_PER_MINUTE$1;
+        const stepMs = step * MS_PER_MINUTE$2;
         // Align when down to interval boundary
         const whenTimestamp = this.params.execution.context.when.getTime();
         const alignedWhen = ALIGN_TO_INTERVAL_FN$1(whenTimestamp, step);
@@ -2289,7 +2289,7 @@ class ClientExchange {
         if (!step) {
             throw new Error(`ClientExchange getNextCandles: unknown interval=${interval}`);
         }
-        const stepMs = step * MS_PER_MINUTE$1;
+        const stepMs = step * MS_PER_MINUTE$2;
         const now = Date.now();
         // Align when down to interval boundary
         const whenTimestamp = this.params.execution.context.when.getTime();
@@ -2457,7 +2457,7 @@ class ClientExchange {
         if (!step) {
             throw new Error(`ClientExchange getRawCandles: unknown interval=${interval}`);
         }
-        const stepMs = step * MS_PER_MINUTE$1;
+        const stepMs = step * MS_PER_MINUTE$2;
         const whenTimestamp = this.params.execution.context.when.getTime();
         const alignedWhen = ALIGN_TO_INTERVAL_FN$1(whenTimestamp, step);
         let sinceTimestamp;
@@ -2584,7 +2584,7 @@ class ClientExchange {
         });
         const to = new Date(this.params.execution.context.when.getTime());
         const from = new Date(to.getTime() -
-            GLOBAL_CONFIG.CC_ORDER_BOOK_TIME_OFFSET_MINUTES * MS_PER_MINUTE$1);
+            GLOBAL_CONFIG.CC_ORDER_BOOK_TIME_OFFSET_MINUTES * MS_PER_MINUTE$2);
         return await this.params.getOrderBook(symbol, depth, from, to, this.params.execution.context.backtest);
     }
 }
@@ -35507,7 +35507,7 @@ const EXCHANGE_METHOD_NAME_FORMAT_QUANTITY = "ExchangeUtils.formatQuantity";
 const EXCHANGE_METHOD_NAME_FORMAT_PRICE = "ExchangeUtils.formatPrice";
 const EXCHANGE_METHOD_NAME_GET_ORDER_BOOK = "ExchangeUtils.getOrderBook";
 const EXCHANGE_METHOD_NAME_GET_RAW_CANDLES = "ExchangeUtils.getRawCandles";
-const MS_PER_MINUTE = 60000;
+const MS_PER_MINUTE$1 = 60000;
 /**
  * Gets current timestamp from execution context if available.
  * Returns current Date() if no execution context exists (non-trading GUI).
@@ -35592,7 +35592,7 @@ const INTERVAL_MINUTES$1 = {
  * @returns Aligned timestamp rounded down to interval boundary
  */
 const ALIGN_TO_INTERVAL_FN = (timestamp, intervalMinutes) => {
-    const intervalMs = intervalMinutes * MS_PER_MINUTE;
+    const intervalMs = intervalMinutes * MS_PER_MINUTE$1;
     return Math.floor(timestamp / intervalMs) * intervalMs;
 };
 /**
@@ -35734,7 +35734,7 @@ class ExchangeInstance {
             if (!step) {
                 throw new Error(`ExchangeInstance unknown interval=${interval}`);
             }
-            const stepMs = step * MS_PER_MINUTE;
+            const stepMs = step * MS_PER_MINUTE$1;
             // Align when down to interval boundary
             const when = await GET_TIMESTAMP_FN();
             const whenTimestamp = when.getTime();
@@ -35911,7 +35911,7 @@ class ExchangeInstance {
                 depth,
             });
             const to = await GET_TIMESTAMP_FN();
-            const from = new Date(to.getTime() - GLOBAL_CONFIG.CC_ORDER_BOOK_TIME_OFFSET_MINUTES * MS_PER_MINUTE);
+            const from = new Date(to.getTime() - GLOBAL_CONFIG.CC_ORDER_BOOK_TIME_OFFSET_MINUTES * MS_PER_MINUTE$1);
             const isBacktest = await GET_BACKTEST_FN();
             return await this._methods.getOrderBook(symbol, depth, from, to, isBacktest);
         };
@@ -35958,7 +35958,7 @@ class ExchangeInstance {
             if (!step) {
                 throw new Error(`ExchangeInstance getRawCandles: unknown interval=${interval}`);
             }
-            const stepMs = step * MS_PER_MINUTE;
+            const stepMs = step * MS_PER_MINUTE$1;
             const when = await GET_TIMESTAMP_FN();
             const nowTimestamp = when.getTime();
             const alignedNow = ALIGN_TO_INTERVAL_FN(nowTimestamp, step);
@@ -36231,6 +36231,7 @@ const CACHE_METHOD_NAME_FLUSH = "CacheUtils.flush";
 const CACHE_METHOD_NAME_CLEAR = "CacheInstance.clear";
 const CACHE_METHOD_NAME_RUN = "CacheInstance.run";
 const CACHE_METHOD_NAME_FN = "CacheUtils.fn";
+const MS_PER_MINUTE = 60000;
 const INTERVAL_MINUTES = {
     "1m": 1,
     "3m": 3,
@@ -36243,6 +36244,34 @@ const INTERVAL_MINUTES = {
     "6h": 360,
     "8h": 480,
 };
+/**
+ * Aligns timestamp down to the nearest interval boundary.
+ * For example, for 15m interval: 00:17 -> 00:15, 00:44 -> 00:30
+ *
+ * @param timestamp - Timestamp in milliseconds
+ * @param interval - Candle interval
+ * @returns Aligned timestamp rounded down to interval boundary
+ * @throws Error if interval is unknown
+ *
+ * @example
+ * ```typescript
+ * // Align to 15-minute boundary
+ * const aligned = align(new Date("2025-10-01T00:35:00Z").getTime(), "15m");
+ * // Returns timestamp for 2025-10-01T00:30:00Z
+ *
+ * // Align to 1-hour boundary
+ * const aligned = align(new Date("2025-10-01T01:47:00Z").getTime(), "1h");
+ * // Returns timestamp for 2025-10-01T01:00:00Z
+ * ```
+ */
+const align = (timestamp, interval) => {
+    const intervalMinutes = INTERVAL_MINUTES[interval];
+    if (!intervalMinutes) {
+        throw new Error(`align: unknown interval=${interval}`);
+    }
+    const intervalMs = intervalMinutes * MS_PER_MINUTE;
+    return Math.floor(timestamp / intervalMs) * intervalMs;
+};
 /**
  * Create a cache key string from strategy name, exchange name, and backtest mode.
  *
@@ -36258,6 +36287,11 @@ const CREATE_KEY_FN = (strategyName, exchangeName, frameName, backtest) => {
     parts.push(backtest ? "backtest" : "live");
     return parts.join(":");
 };
+/**
+ * A unique symbol representing a value that should never occur.
+ * Used as default key when no key function is provided.
+ */
+const NEVER_VALUE = Symbol("never");
 /**
  * Instance class for caching function results with timeframe-based invalidation.
  *
@@ -36266,6 +36300,7 @@ const CREATE_KEY_FN = (strategyName, exchangeName, frameName, backtest) => {
  * Cache is invalidated when the current time moves to a different interval.
  *
  * @template T - Function type to cache
+ * @template K - Key type for argument-based caching
  *
  * @example
  * ```typescript
@@ -36282,11 +36317,13 @@ class CacheInstance {
      *
      * @param fn - Function to cache
      * @param interval - Candle interval for cache invalidation (e.g., "1m", "1h")
+     * @param key - Optional key generator function for argument-based caching
      */
-    constructor(fn, interval) {
+    constructor(fn, interval, key = () => NEVER_VALUE) {
         this.fn = fn;
         this.interval = interval;
-        /** Cache map storing results per strategy/exchange/mode combination */
+        this.key = key;
+        /** Cache map storing results per strategy/exchange/mode/argKey combination */
         this._cacheMap = new Map();
         /**
          * Execute function with caching based on timeframe intervals.
@@ -36333,13 +36370,15 @@ class CacheInstance {
                     throw new Error(`CacheInstance unknown cache ttl interval=${this.interval}`);
                 }
             }
-            const key = CREATE_KEY_FN(bt.methodContextService.context.strategyName, bt.methodContextService.context.exchangeName, bt.methodContextService.context.frameName, bt.executionContextService.context.backtest);
+            const contextKey = CREATE_KEY_FN(bt.methodContextService.context.strategyName, bt.methodContextService.context.exchangeName, bt.methodContextService.context.frameName, bt.executionContextService.context.backtest);
+            const argKey = String(this.key(args));
+            const key = `${contextKey}:${argKey}`;
             const currentWhen = bt.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 >= 0 && elapsed < stepMs) {
+                const currentAligned = align(currentWhen.getTime(), this.interval);
+                const cachedAligned = align(cached.when.getTime(), this.interval);
+                if (currentAligned === cachedAligned) {
                     return cached;
                 }
             }
@@ -36351,13 +36390,13 @@ class CacheInstance {
             return newCache;
         };
         /**
-         * Clear cached value for current execution context.
+         * Clear cached values for current execution context.
          *
-         * Removes the cached entry for the current strategy/exchange/mode combination
+         * Removes all cached entries for the current strategy/exchange/mode combination
          * from this instance's cache map. The next `run()` call will recompute the value.
          *
          * Requires active execution context (strategy, exchange, backtest mode) and method context
-         * to determine which cache entry to clear.
+         * to determine which cache entries to clear.
          *
          * @example
          * ```typescript
@@ -36365,14 +36404,19 @@ class CacheInstance {
          * const result1 = instance.run("BTCUSDT", 14); // Computed
          * const result2 = instance.run("BTCUSDT", 14); // Cached
          *
-         * instance.clear(); // Clear cache for current context
+         * instance.clear(); // Clear all cache entries for current context
          *
          * const result3 = instance.run("BTCUSDT", 14); // Recomputed
          * ```
          */
         this.clear = () => {
-            const key = CREATE_KEY_FN(bt.methodContextService.context.strategyName, bt.methodContextService.context.exchangeName, bt.methodContextService.context.frameName, bt.executionContextService.context.backtest);
-            this._cacheMap.delete(key);
+            const contextKey = CREATE_KEY_FN(bt.methodContextService.context.strategyName, bt.methodContextService.context.exchangeName, bt.methodContextService.context.frameName, bt.executionContextService.context.backtest);
+            const prefix = `${contextKey}:`;
+            for (const key of this._cacheMap.keys()) {
+                if (key.startsWith(prefix)) {
+                    this._cacheMap.delete(key);
+                }
+            }
         };
     }
 }
@@ -36397,7 +36441,7 @@ class CacheUtils {
          * 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));
+        this._getInstance = memoize(([run]) => run, (run, interval, key) => new CacheInstance(run, interval, key));
         /**
          * Wrap a function with caching based on timeframe intervals.
          *
@@ -36405,8 +36449,10 @@ class CacheUtils {
          * and invalidates based on the specified candle interval.
          *
          * @template T - Function type to cache
+         * @template K - Key type for argument-based caching
          * @param run - Function to wrap with caching
-         * @param interval - Candle interval for cache invalidation (e.g., "1m", "1h")
+         * @param context.interval - Candle interval for cache invalidation (e.g., "1m", "1h")
+         * @param context.key - Optional key generator function for argument-based caching
          * @returns Wrapped function with automatic caching
          *
          * @example
@@ -36416,9 +36462,17 @@ class CacheUtils {
          *   return result;
          * };
          *
-         * const cachedCalculate = Cache.fn(calculateIndicator, "15m");
-         * const result = cachedCalculate("BTCUSDT", 14); // Computed
-         * const result2 = cachedCalculate("BTCUSDT", 14); // Cached (same 15m interval)
+         * // Without key - single cache entry per context
+         * const cachedCalculate = Cache.fn(calculateIndicator, { interval: "15m" });
+         *
+         * // With key - separate cache entries per symbol
+         * const cachedCalculate = Cache.fn(calculateIndicator, {
+         *   interval: "15m",
+         *   key: ([symbol]) => symbol,
+         * });
+         * const result1 = cachedCalculate("BTCUSDT", 14); // Computed
+         * const result2 = cachedCalculate("ETHUSDT", 14); // Computed (different key)
+         * const result3 = cachedCalculate("BTCUSDT", 14); // Cached (same key, same interval)
          * ```
          */
         this.fn = (run, context) => {
@@ -36426,7 +36480,7 @@ class CacheUtils {
                 context,
             });
             const wrappedFn = (...args) => {
-                const instance = this._getInstance(run, context.interval);
+                const instance = this._getInstance(run, context.interval, context.key);
                 return instance.run(...args).value;
             };
             return wrappedFn;

package/package.json

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

package/types.d.ts

@@ -13901,8 +13901,10 @@ declare class CacheUtils {
      * and invalidates based on the specified candle interval.
      *
      * @template T - Function type to cache
+     * @template K - Key type for argument-based caching
      * @param run - Function to wrap with caching
-     * @param interval - Candle interval for cache invalidation (e.g., "1m", "1h")
+     * @param context.interval - Candle interval for cache invalidation (e.g., "1m", "1h")
+     * @param context.key - Optional key generator function for argument-based caching
      * @returns Wrapped function with automatic caching
      *
      * @example
@@ -13912,13 +13914,22 @@ declare class CacheUtils {
      *   return result;
      * };
      *
-     * const cachedCalculate = Cache.fn(calculateIndicator, "15m");
-     * const result = cachedCalculate("BTCUSDT", 14); // Computed
-     * const result2 = cachedCalculate("BTCUSDT", 14); // Cached (same 15m interval)
+     * // Without key - single cache entry per context
+     * const cachedCalculate = Cache.fn(calculateIndicator, { interval: "15m" });
+     *
+     * // With key - separate cache entries per symbol
+     * const cachedCalculate = Cache.fn(calculateIndicator, {
+     *   interval: "15m",
+     *   key: ([symbol]) => symbol,
+     * });
+     * const result1 = cachedCalculate("BTCUSDT", 14); // Computed
+     * const result2 = cachedCalculate("ETHUSDT", 14); // Computed (different key)
+     * const result3 = cachedCalculate("BTCUSDT", 14); // Cached (same key, same interval)
      * ```
      */
-    fn: <T extends Function>(run: T, context: {
+    fn: <T extends Function, K = symbol>(run: T, context: {
         interval: CandleInterval;
+        key?: (args: Parameters<T>) => K;
     }) => T;
     /**
      * Flush (remove) cached CacheInstance for a specific function or all functions.