backtest-kit 3.0.6 → 3.0.8

package/build/index.cjs

@@ -36250,6 +36250,7 @@ const Exchange = new ExchangeUtils();
 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_GC = "CacheInstance.gc";
 const CACHE_METHOD_NAME_FN = "CacheUtils.fn";
 const MS_PER_MINUTE = 60000;
 const INTERVAL_MINUTES = {
@@ -36307,6 +36308,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.
  *
@@ -36315,6 +36321,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
@@ -36331,11 +36338,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.
@@ -36382,7 +36391,9 @@ 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) {
@@ -36400,13 +36411,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
@@ -36414,14 +36425,51 @@ 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);
+                }
+            }
+        };
+        /**
+         * Garbage collect expired cache entries.
+         *
+         * Removes all cached entries whose interval has expired (not aligned with current time).
+         * Call this periodically to free memory from stale cache entries.
+         *
+         * Requires active execution context to get current time.
+         *
+         * @returns Number of entries removed
+         *
+         * @example
+         * ```typescript
+         * const instance = new CacheInstance(calculateIndicator, "1h");
+         * instance.run("BTCUSDT", 14); // Cached at 10:00
+         * instance.run("ETHUSDT", 14); // Cached at 10:00
+         * // Time passes to 11:00
+         * const removed = instance.gc(); // Returns 2, removes both expired entries
+         * ```
+         */
+        this.gc = () => {
+            const currentWhen = bt.executionContextService.context.when;
+            const currentAligned = align(currentWhen.getTime(), this.interval);
+            let removed = 0;
+            for (const [key, cached] of this._cacheMap.entries()) {
+                const cachedAligned = align(cached.when.getTime(), this.interval);
+                if (currentAligned !== cachedAligned) {
+                    this._cacheMap.delete(key);
+                    removed++;
+                }
+            }
+            return removed;
         };
     }
 }
@@ -36446,7 +36494,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.
          *
@@ -36454,8 +36502,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
@@ -36465,9 +36515,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) => {
@@ -36475,7 +36533,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;
@@ -36548,8 +36606,48 @@ class CacheUtils {
             bt.loggerService.info(CACHE_METHOD_NAME_CLEAR, {
                 run,
             });
+            if (!MethodContextService.hasContext()) {
+                console.warn(`${CACHE_METHOD_NAME_CLEAR} called without method context, skipping clear`);
+                return;
+            }
+            if (!ExecutionContextService.hasContext()) {
+                console.warn(`${CACHE_METHOD_NAME_CLEAR} called without execution context, skipping clear`);
+                return;
+            }
             this._getInstance.get(run).clear();
         };
+        /**
+         * Garbage collect expired cache entries for a specific function.
+         *
+         * Removes all cached entries whose interval has expired (not aligned with current time).
+         * Call this periodically to free memory from stale cache entries.
+         *
+         * Requires active execution context to get current time.
+         *
+         * @template T - Function type
+         * @param run - Function whose expired cache entries should be removed
+         * @returns Number of entries removed
+         *
+         * @example
+         * ```typescript
+         * const cachedFn = Cache.fn(calculateIndicator, { interval: "1h" });
+         *
+         * cachedFn("BTCUSDT", 14); // Cached at 10:00
+         * cachedFn("ETHUSDT", 14); // Cached at 10:00
+         * // Time passes to 11:00
+         * const removed = Cache.gc(calculateIndicator); // Returns 2
+         * ```
+         */
+        this.gc = (run) => {
+            bt.loggerService.info(CACHE_METHOD_NAME_GC, {
+                run,
+            });
+            if (!ExecutionContextService.hasContext()) {
+                console.warn(`${CACHE_METHOD_NAME_GC} called without execution context, skipping garbage collection`);
+                return;
+            }
+            return this._getInstance.get(run).gc();
+        };
     }
 }
 /**

package/build/index.mjs

@@ -36230,6 +36230,7 @@ const Exchange = new ExchangeUtils();
 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_GC = "CacheInstance.gc";
 const CACHE_METHOD_NAME_FN = "CacheUtils.fn";
 const MS_PER_MINUTE = 60000;
 const INTERVAL_MINUTES = {
@@ -36287,6 +36288,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.
  *
@@ -36295,6 +36301,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
@@ -36311,11 +36318,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.
@@ -36362,7 +36371,9 @@ 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) {
@@ -36380,13 +36391,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
@@ -36394,14 +36405,51 @@ 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);
+                }
+            }
+        };
+        /**
+         * Garbage collect expired cache entries.
+         *
+         * Removes all cached entries whose interval has expired (not aligned with current time).
+         * Call this periodically to free memory from stale cache entries.
+         *
+         * Requires active execution context to get current time.
+         *
+         * @returns Number of entries removed
+         *
+         * @example
+         * ```typescript
+         * const instance = new CacheInstance(calculateIndicator, "1h");
+         * instance.run("BTCUSDT", 14); // Cached at 10:00
+         * instance.run("ETHUSDT", 14); // Cached at 10:00
+         * // Time passes to 11:00
+         * const removed = instance.gc(); // Returns 2, removes both expired entries
+         * ```
+         */
+        this.gc = () => {
+            const currentWhen = bt.executionContextService.context.when;
+            const currentAligned = align(currentWhen.getTime(), this.interval);
+            let removed = 0;
+            for (const [key, cached] of this._cacheMap.entries()) {
+                const cachedAligned = align(cached.when.getTime(), this.interval);
+                if (currentAligned !== cachedAligned) {
+                    this._cacheMap.delete(key);
+                    removed++;
+                }
+            }
+            return removed;
         };
     }
 }
@@ -36426,7 +36474,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.
          *
@@ -36434,8 +36482,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
@@ -36445,9 +36495,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) => {
@@ -36455,7 +36513,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;
@@ -36528,8 +36586,48 @@ class CacheUtils {
             bt.loggerService.info(CACHE_METHOD_NAME_CLEAR, {
                 run,
             });
+            if (!MethodContextService.hasContext()) {
+                console.warn(`${CACHE_METHOD_NAME_CLEAR} called without method context, skipping clear`);
+                return;
+            }
+            if (!ExecutionContextService.hasContext()) {
+                console.warn(`${CACHE_METHOD_NAME_CLEAR} called without execution context, skipping clear`);
+                return;
+            }
             this._getInstance.get(run).clear();
         };
+        /**
+         * Garbage collect expired cache entries for a specific function.
+         *
+         * Removes all cached entries whose interval has expired (not aligned with current time).
+         * Call this periodically to free memory from stale cache entries.
+         *
+         * Requires active execution context to get current time.
+         *
+         * @template T - Function type
+         * @param run - Function whose expired cache entries should be removed
+         * @returns Number of entries removed
+         *
+         * @example
+         * ```typescript
+         * const cachedFn = Cache.fn(calculateIndicator, { interval: "1h" });
+         *
+         * cachedFn("BTCUSDT", 14); // Cached at 10:00
+         * cachedFn("ETHUSDT", 14); // Cached at 10:00
+         * // Time passes to 11:00
+         * const removed = Cache.gc(calculateIndicator); // Returns 2
+         * ```
+         */
+        this.gc = (run) => {
+            bt.loggerService.info(CACHE_METHOD_NAME_GC, {
+                run,
+            });
+            if (!ExecutionContextService.hasContext()) {
+                console.warn(`${CACHE_METHOD_NAME_GC} called without execution context, skipping garbage collection`);
+                return;
+            }
+            return this._getInstance.get(run).gc();
+        };
     }
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backtest-kit",
-  "version": "3.0.6",
+  "version": "3.0.8",
   "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.
@@ -13980,6 +13991,29 @@ declare class CacheUtils {
      * ```
      */
     clear: <T extends Function>(run: T) => void;
+    /**
+     * Garbage collect expired cache entries for a specific function.
+     *
+     * Removes all cached entries whose interval has expired (not aligned with current time).
+     * Call this periodically to free memory from stale cache entries.
+     *
+     * Requires active execution context to get current time.
+     *
+     * @template T - Function type
+     * @param run - Function whose expired cache entries should be removed
+     * @returns Number of entries removed
+     *
+     * @example
+     * ```typescript
+     * const cachedFn = Cache.fn(calculateIndicator, { interval: "1h" });
+     *
+     * cachedFn("BTCUSDT", 14); // Cached at 10:00
+     * cachedFn("ETHUSDT", 14); // Cached at 10:00
+     * // Time passes to 11:00
+     * const removed = Cache.gc(calculateIndicator); // Returns 2
+     * ```
+     */
+    gc: <T extends Function>(run: T) => number;
 }
 /**
  * Singleton instance of CacheUtils for convenient function caching.