backtest-kit 3.0.7 → 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 = {
@@ -36438,6 +36439,38 @@ class CacheInstance {
                 }
             }
         };
+        /**
+         * 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;
+        };
     }
 }
 /**
@@ -36573,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 = {
@@ -36418,6 +36419,38 @@ class CacheInstance {
                 }
             }
         };
+        /**
+         * 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;
+        };
     }
 }
 /**
@@ -36553,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.7",
+  "version": "3.0.8",
   "description": "A TypeScript library for trading system backtest",
   "author": {
     "name": "Petr Tripolsky",

package/types.d.ts

@@ -13991,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.