backtest-kit 6.3.0 → 6.4.0

package/build/index.cjs

@@ -51140,12 +51140,14 @@ const NotificationLive = new NotificationLiveAdapter();
  */
 const NotificationBacktest = new NotificationBacktestAdapter();
 
-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 CACHE_METHOD_NAME_FN_CLEAR = "CacheUtils.fn.clear";
+const CACHE_METHOD_NAME_FN_GC = "CacheUtils.fn.gc";
 const CACHE_METHOD_NAME_FILE = "CacheUtils.file";
+const CACHE_METHOD_NAME_FILE_CLEAR = "CacheUtils.file.clear";
+const CACHE_METHOD_NAME_DISPOSE = "CacheUtils.dispose";
+const CACHE_METHOD_NAME_CLEAR = "CacheUtils.clear";
 const CACHE_FILE_INSTANCE_METHOD_NAME_RUN = "CacheFileInstance.run";
 const MS_PER_MINUTE = 60000;
 const INTERVAL_MINUTES = {
@@ -51394,6 +51396,12 @@ class CacheFileInstance {
     static createIndex() {
         return CacheFileInstance._indexCounter++;
     }
+    /**
+     * Clears the index counter.
+     */
+    static clearCounter() {
+        CacheFileInstance._indexCounter = 0;
+    }
     /**
      * Creates a new CacheFileInstance.
      *
@@ -51527,6 +51535,26 @@ class CacheUtils {
                 const instance = this._getFnInstance(run, context.interval, context.key);
                 return instance.run(...args).value;
             };
+            wrappedFn.clear = () => {
+                bt.loggerService.info(CACHE_METHOD_NAME_FN_CLEAR);
+                if (!MethodContextService.hasContext()) {
+                    bt.loggerService.warn(`${CACHE_METHOD_NAME_FN_CLEAR} called without method context, skipping`);
+                    return;
+                }
+                if (!ExecutionContextService.hasContext()) {
+                    bt.loggerService.warn(`${CACHE_METHOD_NAME_FN_CLEAR} called without execution context, skipping`);
+                    return;
+                }
+                this._getFnInstance.get(run)?.clear();
+            };
+            wrappedFn.gc = () => {
+                bt.loggerService.info(CACHE_METHOD_NAME_FN_GC);
+                if (!ExecutionContextService.hasContext()) {
+                    bt.loggerService.warn(`${CACHE_METHOD_NAME_FN_GC} called without execution context, skipping`);
+                    return;
+                }
+                return this._getFnInstance.get(run)?.gc();
+            };
             return wrappedFn;
         };
         /**
@@ -51573,117 +51601,51 @@ class CacheUtils {
                 const instance = this._getFileInstance(run, context.interval, context.name, context.key);
                 return instance.run(...args);
             };
+            wrappedFn.clear = () => {
+                bt.loggerService.info(CACHE_METHOD_NAME_FILE_CLEAR);
+                this._getFileInstance.clear(run);
+            };
             return wrappedFn;
         };
         /**
-         * Flush (remove) cached CacheInstance for a specific function or all functions.
-         *
-         * This method removes CacheInstance objects from the internal memoization cache.
-         * When a CacheInstance is flushed, all cached results across all contexts
-         * (all strategy/exchange/mode combinations) for that function are discarded.
-         *
-         * Use cases:
-         * - Remove specific function's CacheInstance when implementation changes
-         * - Free memory by removing unused CacheInstances
-         * - Reset all CacheInstances when switching between different test scenarios
-         *
-         * Note: This is different from `clear()` which only removes cached values
-         * for the current context within an existing CacheInstance.
-         *
-         * @template T - Function type
-         * @param run - Optional function to flush CacheInstance for. If omitted, flushes all CacheInstances.
-         *
-         * @example
-         * ```typescript
-         * const cachedFn = Cache.fn(calculateIndicator, { interval: "1h" });
-         *
-         * // Flush CacheInstance for specific function
-         * Cache.flush(calculateIndicator);
-         *
-         * // Flush all CacheInstances
-         * Cache.flush();
-         * ```
-         */
-        this.flush = (run) => {
-            bt.loggerService.info(CACHE_METHOD_NAME_FLUSH, {
-                run,
-            });
-            this._getFnInstance.clear(run);
-        };
-        /**
-         * Clear cached value for current execution context of a specific function.
+         * Dispose (remove) the memoized CacheInstance for a specific function.
          *
-         * Removes the cached entry for the current strategy/exchange/mode combination
-         * from the specified function's CacheInstance. The next call to the wrapped function
-         * will recompute the value for that context.
-         *
-         * This only clears the cache for the current execution context, not all contexts.
-         * Use `flush()` to remove the entire CacheInstance across all contexts.
-         *
-         * Requires active execution context (strategy, exchange, backtest mode) and method context.
+         * Removes the CacheInstance from the internal memoization cache, discarding all cached
+         * results across all contexts (all strategy/exchange/mode combinations) for that function.
+         * The next call to the wrapped function will create a fresh CacheInstance.
          *
          * @template T - Function type
-         * @param run - Function whose cache should be cleared for current context
+         * @param run - Function whose CacheInstance should be disposed.
          *
          * @example
          * ```typescript
          * const cachedFn = Cache.fn(calculateIndicator, { interval: "1h" });
          *
-         * // Within strategy execution context
-         * const result1 = cachedFn("BTCUSDT", 14); // Computed
-         * const result2 = cachedFn("BTCUSDT", 14); // Cached
-         *
-         * Cache.clear(calculateIndicator); // Clear cache for current context only
-         *
-         * const result3 = cachedFn("BTCUSDT", 14); // Recomputed for this context
-         * // Other contexts (different strategies/exchanges) remain cached
+         * // Dispose CacheInstance for a specific function
+         * Cache.dispose(calculateIndicator);
          * ```
          */
-        this.clear = (run) => {
-            bt.loggerService.info(CACHE_METHOD_NAME_CLEAR, {
+        this.dispose = (run) => {
+            bt.loggerService.info(CACHE_METHOD_NAME_DISPOSE, {
                 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._getFnInstance.clear(run);
+                this._getFileInstance.clear(run);
             }
-            this._getFnInstance.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
-         * ```
+         * Clears all memoized CacheInstance and CacheFileInstance objects.
+         * Call this when process.cwd() changes between strategy iterations
+         * so new instances are created with the updated base path.
          */
-        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;
+        this.clear = () => {
+            bt.loggerService.info(CACHE_METHOD_NAME_CLEAR);
+            {
+                this._getFnInstance.clear();
+                this._getFileInstance.clear();
             }
-            return this._getFnInstance.get(run).gc();
+            CacheFileInstance.clearCounter();
         };
     }
 }

package/build/index.mjs

@@ -51120,12 +51120,14 @@ const NotificationLive = new NotificationLiveAdapter();
  */
 const NotificationBacktest = new NotificationBacktestAdapter();
 
-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 CACHE_METHOD_NAME_FN_CLEAR = "CacheUtils.fn.clear";
+const CACHE_METHOD_NAME_FN_GC = "CacheUtils.fn.gc";
 const CACHE_METHOD_NAME_FILE = "CacheUtils.file";
+const CACHE_METHOD_NAME_FILE_CLEAR = "CacheUtils.file.clear";
+const CACHE_METHOD_NAME_DISPOSE = "CacheUtils.dispose";
+const CACHE_METHOD_NAME_CLEAR = "CacheUtils.clear";
 const CACHE_FILE_INSTANCE_METHOD_NAME_RUN = "CacheFileInstance.run";
 const MS_PER_MINUTE = 60000;
 const INTERVAL_MINUTES = {
@@ -51374,6 +51376,12 @@ class CacheFileInstance {
     static createIndex() {
         return CacheFileInstance._indexCounter++;
     }
+    /**
+     * Clears the index counter.
+     */
+    static clearCounter() {
+        CacheFileInstance._indexCounter = 0;
+    }
     /**
      * Creates a new CacheFileInstance.
      *
@@ -51507,6 +51515,26 @@ class CacheUtils {
                 const instance = this._getFnInstance(run, context.interval, context.key);
                 return instance.run(...args).value;
             };
+            wrappedFn.clear = () => {
+                bt.loggerService.info(CACHE_METHOD_NAME_FN_CLEAR);
+                if (!MethodContextService.hasContext()) {
+                    bt.loggerService.warn(`${CACHE_METHOD_NAME_FN_CLEAR} called without method context, skipping`);
+                    return;
+                }
+                if (!ExecutionContextService.hasContext()) {
+                    bt.loggerService.warn(`${CACHE_METHOD_NAME_FN_CLEAR} called without execution context, skipping`);
+                    return;
+                }
+                this._getFnInstance.get(run)?.clear();
+            };
+            wrappedFn.gc = () => {
+                bt.loggerService.info(CACHE_METHOD_NAME_FN_GC);
+                if (!ExecutionContextService.hasContext()) {
+                    bt.loggerService.warn(`${CACHE_METHOD_NAME_FN_GC} called without execution context, skipping`);
+                    return;
+                }
+                return this._getFnInstance.get(run)?.gc();
+            };
             return wrappedFn;
         };
         /**
@@ -51553,117 +51581,51 @@ class CacheUtils {
                 const instance = this._getFileInstance(run, context.interval, context.name, context.key);
                 return instance.run(...args);
             };
+            wrappedFn.clear = () => {
+                bt.loggerService.info(CACHE_METHOD_NAME_FILE_CLEAR);
+                this._getFileInstance.clear(run);
+            };
             return wrappedFn;
         };
         /**
-         * Flush (remove) cached CacheInstance for a specific function or all functions.
-         *
-         * This method removes CacheInstance objects from the internal memoization cache.
-         * When a CacheInstance is flushed, all cached results across all contexts
-         * (all strategy/exchange/mode combinations) for that function are discarded.
-         *
-         * Use cases:
-         * - Remove specific function's CacheInstance when implementation changes
-         * - Free memory by removing unused CacheInstances
-         * - Reset all CacheInstances when switching between different test scenarios
-         *
-         * Note: This is different from `clear()` which only removes cached values
-         * for the current context within an existing CacheInstance.
-         *
-         * @template T - Function type
-         * @param run - Optional function to flush CacheInstance for. If omitted, flushes all CacheInstances.
-         *
-         * @example
-         * ```typescript
-         * const cachedFn = Cache.fn(calculateIndicator, { interval: "1h" });
-         *
-         * // Flush CacheInstance for specific function
-         * Cache.flush(calculateIndicator);
-         *
-         * // Flush all CacheInstances
-         * Cache.flush();
-         * ```
-         */
-        this.flush = (run) => {
-            bt.loggerService.info(CACHE_METHOD_NAME_FLUSH, {
-                run,
-            });
-            this._getFnInstance.clear(run);
-        };
-        /**
-         * Clear cached value for current execution context of a specific function.
+         * Dispose (remove) the memoized CacheInstance for a specific function.
          *
-         * Removes the cached entry for the current strategy/exchange/mode combination
-         * from the specified function's CacheInstance. The next call to the wrapped function
-         * will recompute the value for that context.
-         *
-         * This only clears the cache for the current execution context, not all contexts.
-         * Use `flush()` to remove the entire CacheInstance across all contexts.
-         *
-         * Requires active execution context (strategy, exchange, backtest mode) and method context.
+         * Removes the CacheInstance from the internal memoization cache, discarding all cached
+         * results across all contexts (all strategy/exchange/mode combinations) for that function.
+         * The next call to the wrapped function will create a fresh CacheInstance.
          *
          * @template T - Function type
-         * @param run - Function whose cache should be cleared for current context
+         * @param run - Function whose CacheInstance should be disposed.
          *
          * @example
          * ```typescript
          * const cachedFn = Cache.fn(calculateIndicator, { interval: "1h" });
          *
-         * // Within strategy execution context
-         * const result1 = cachedFn("BTCUSDT", 14); // Computed
-         * const result2 = cachedFn("BTCUSDT", 14); // Cached
-         *
-         * Cache.clear(calculateIndicator); // Clear cache for current context only
-         *
-         * const result3 = cachedFn("BTCUSDT", 14); // Recomputed for this context
-         * // Other contexts (different strategies/exchanges) remain cached
+         * // Dispose CacheInstance for a specific function
+         * Cache.dispose(calculateIndicator);
          * ```
          */
-        this.clear = (run) => {
-            bt.loggerService.info(CACHE_METHOD_NAME_CLEAR, {
+        this.dispose = (run) => {
+            bt.loggerService.info(CACHE_METHOD_NAME_DISPOSE, {
                 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._getFnInstance.clear(run);
+                this._getFileInstance.clear(run);
             }
-            this._getFnInstance.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
-         * ```
+         * Clears all memoized CacheInstance and CacheFileInstance objects.
+         * Call this when process.cwd() changes between strategy iterations
+         * so new instances are created with the updated base path.
          */
-        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;
+        this.clear = () => {
+            bt.loggerService.info(CACHE_METHOD_NAME_CLEAR);
+            {
+                this._getFnInstance.clear();
+                this._getFileInstance.clear();
             }
-            return this._getFnInstance.get(run).gc();
+            CacheFileInstance.clearCounter();
         };
     }
 }

package/package.json

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

package/types.d.ts

@@ -19159,7 +19159,10 @@ declare class CacheUtils {
     fn: <T extends Function, K = symbol>(run: T, context: {
         interval: CandleInterval;
         key?: (args: Parameters<T>) => K;
-    }) => T;
+    }) => T & {
+        clear(): void;
+        gc(): number | undefined;
+    };
     /**
      * Wrap an async function with persistent file-based caching.
      *
@@ -19202,90 +19205,34 @@ declare class CacheUtils {
         interval: CandleInterval;
         name: string;
         key?: (args: CacheFileKeyArgs<T>) => string;
-    }) => T;
+    }) => T & {
+        clear(): void;
+    };
     /**
-     * Flush (remove) cached CacheInstance for a specific function or all functions.
-     *
-     * This method removes CacheInstance objects from the internal memoization cache.
-     * When a CacheInstance is flushed, all cached results across all contexts
-     * (all strategy/exchange/mode combinations) for that function are discarded.
+     * Dispose (remove) the memoized CacheInstance for a specific function.
      *
-     * Use cases:
-     * - Remove specific function's CacheInstance when implementation changes
-     * - Free memory by removing unused CacheInstances
-     * - Reset all CacheInstances when switching between different test scenarios
-     *
-     * Note: This is different from `clear()` which only removes cached values
-     * for the current context within an existing CacheInstance.
+     * Removes the CacheInstance from the internal memoization cache, discarding all cached
+     * results across all contexts (all strategy/exchange/mode combinations) for that function.
+     * The next call to the wrapped function will create a fresh CacheInstance.
      *
      * @template T - Function type
-     * @param run - Optional function to flush CacheInstance for. If omitted, flushes all CacheInstances.
+     * @param run - Function whose CacheInstance should be disposed.
      *
      * @example
      * ```typescript
      * const cachedFn = Cache.fn(calculateIndicator, { interval: "1h" });
      *
-     * // Flush CacheInstance for specific function
-     * Cache.flush(calculateIndicator);
-     *
-     * // Flush all CacheInstances
-     * Cache.flush();
+     * // Dispose CacheInstance for a specific function
+     * Cache.dispose(calculateIndicator);
      * ```
      */
-    flush: <T extends Function>(run?: T) => void;
+    dispose: <T extends Function>(run: T) => void;
     /**
-     * Clear cached value for current execution context of a specific function.
-     *
-     * Removes the cached entry for the current strategy/exchange/mode combination
-     * from the specified function's CacheInstance. The next call to the wrapped function
-     * will recompute the value for that context.
-     *
-     * This only clears the cache for the current execution context, not all contexts.
-     * Use `flush()` to remove the entire CacheInstance across all contexts.
-     *
-     * Requires active execution context (strategy, exchange, backtest mode) and method context.
-     *
-     * @template T - Function type
-     * @param run - Function whose cache should be cleared for current context
-     *
-     * @example
-     * ```typescript
-     * const cachedFn = Cache.fn(calculateIndicator, { interval: "1h" });
-     *
-     * // Within strategy execution context
-     * const result1 = cachedFn("BTCUSDT", 14); // Computed
-     * const result2 = cachedFn("BTCUSDT", 14); // Cached
-     *
-     * Cache.clear(calculateIndicator); // Clear cache for current context only
-     *
-     * const result3 = cachedFn("BTCUSDT", 14); // Recomputed for this context
-     * // Other contexts (different strategies/exchanges) remain cached
-     * ```
-     */
-    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
-     * ```
+     * Clears all memoized CacheInstance and CacheFileInstance objects.
+     * Call this when process.cwd() changes between strategy iterations
+     * so new instances are created with the updated base path.
      */
-    gc: <T extends Function>(run: T) => number;
+    clear: () => void;
 }
 /**
  * Singleton instance of CacheUtils for convenient function caching.