backtest-kit 3.0.6 → 3.0.7

package/build/index.cjs

@@ -36307,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.
  *
@@ -36315,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
@@ -36331,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.
@@ -36382,7 +36390,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 +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
@@ -36414,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);
+                }
+            }
         };
     }
 }
@@ -36446,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.
          *
@@ -36454,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
@@ -36465,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) => {
@@ -36475,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

@@ -36287,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.
  *
@@ -36295,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
@@ -36311,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.
@@ -36362,7 +36370,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 +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
@@ -36394,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);
+                }
+            }
         };
     }
 }
@@ -36426,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.
          *
@@ -36434,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
@@ -36445,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) => {
@@ -36455,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.6",
+  "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.