backtest-kit 6.2.0 → 6.4.0

package/package.json

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

package/types.d.ts

@@ -10854,6 +10854,12 @@ declare class PersistSignalUtils {
      * @returns Promise that resolves when write is complete
      */
     writeSignalData: (signalRow: ISignalRow | null, symbol: string, strategyName: StrategyName, exchangeName: ExchangeName) => Promise<void>;
+    /**
+     * Clears the memoized storage cache.
+     * Call this when process.cwd() changes between strategy iterations
+     * so new storage instances are created with the updated base path.
+     */
+    clear(): void;
     /**
      * Switches to the default JSON persist adapter.
      * All future persistence writes will use JSON storage.
@@ -10939,6 +10945,12 @@ declare class PersistRiskUtils {
      * @returns Promise that resolves when write is complete
      */
     writePositionData: (riskRow: RiskData, riskName: RiskName, exchangeName: ExchangeName) => Promise<void>;
+    /**
+     * Clears the memoized storage cache.
+     * Call this when process.cwd() changes between strategy iterations
+     * so new storage instances are created with the updated base path.
+     */
+    clear(): void;
     /**
      * Switches to the default JSON persist adapter.
      * All future persistence writes will use JSON storage.
@@ -11026,6 +11038,12 @@ declare class PersistScheduleUtils {
      * @returns Promise that resolves when write is complete
      */
     writeScheduleData: (scheduledSignalRow: IScheduledSignalRow | null, symbol: string, strategyName: StrategyName, exchangeName: ExchangeName) => Promise<void>;
+    /**
+     * Clears the memoized storage cache.
+     * Call this when process.cwd() changes between strategy iterations
+     * so new storage instances are created with the updated base path.
+     */
+    clear(): void;
     /**
      * Switches to the default JSON persist adapter.
      * All future persistence writes will use JSON storage.
@@ -11115,6 +11133,12 @@ declare class PersistPartialUtils {
      * @returns Promise that resolves when write is complete
      */
     writePartialData: (partialData: PartialData, symbol: string, strategyName: StrategyName, signalId: string, exchangeName: ExchangeName) => Promise<void>;
+    /**
+     * Clears the memoized storage cache.
+     * Call this when process.cwd() changes between strategy iterations
+     * so new storage instances are created with the updated base path.
+     */
+    clear(): void;
     /**
      * Switches to the default JSON persist adapter.
      * All future persistence writes will use JSON storage.
@@ -11239,6 +11263,12 @@ declare class PersistBreakevenUtils {
      * @returns Promise that resolves when write is complete
      */
     writeBreakevenData: (breakevenData: BreakevenData, symbol: string, strategyName: StrategyName, signalId: string, exchangeName: ExchangeName) => Promise<void>;
+    /**
+     * Clears the memoized storage cache.
+     * Call this when process.cwd() changes between strategy iterations
+     * so new storage instances are created with the updated base path.
+     */
+    clear(): void;
     /**
      * Switches to the default JSON persist adapter.
      * All future persistence writes will use JSON storage.
@@ -11327,6 +11357,12 @@ declare class PersistCandleUtils {
      * @returns Promise that resolves when all writes are complete
      */
     writeCandlesData: (candles: CandleData[], symbol: string, interval: CandleInterval, exchangeName: ExchangeName) => Promise<void>;
+    /**
+     * Clears the memoized storage cache.
+     * Call this when process.cwd() changes between strategy iterations
+     * so new storage instances are created with the updated base path.
+     */
+    clear(): void;
     /**
      * Switches to the default JSON persist adapter.
      * All future persistence writes will use JSON storage.
@@ -11403,6 +11439,12 @@ declare class PersistStorageUtils {
      * @returns Promise that resolves when write is complete
      */
     writeStorageData: (signalData: StorageData, backtest: boolean) => Promise<void>;
+    /**
+     * Clears the memoized storage cache.
+     * Call this when process.cwd() changes between strategy iterations
+     * so new storage instances are created with the updated base path.
+     */
+    clear(): void;
     /**
      * Switches to the default JSON persist adapter.
      * All future persistence writes will use JSON storage.
@@ -11468,6 +11510,12 @@ declare class PersistNotificationUtils {
      * @returns Promise that resolves when write is complete
      */
     writeNotificationData: (notificationData: NotificationData, backtest: boolean) => Promise<void>;
+    /**
+     * Clears the memoized storage cache.
+     * Call this when process.cwd() changes between strategy iterations
+     * so new storage instances are created with the updated base path.
+     */
+    clear(): void;
     /**
      * Switches to the default JSON persist adapter.
      * All future persistence writes will use JSON storage.
@@ -11533,6 +11581,12 @@ declare class PersistLogUtils {
      * @returns Promise that resolves when write is complete
      */
     writeLogData: (logData: LogData) => Promise<void>;
+    /**
+     * Clears the cached storage instance.
+     * Call this when process.cwd() changes between strategy iterations
+     * so a new storage instance is created with the updated base path.
+     */
+    clear(): void;
     /**
      * Switches to the default JSON persist adapter.
      * All future persistence writes will use JSON storage.
@@ -11586,6 +11640,12 @@ declare class PersistMeasureUtils {
      * @returns Promise that resolves when write is complete
      */
     writeMeasureData: (data: MeasureData, bucket: string, key: string) => Promise<void>;
+    /**
+     * Clears the memoized storage cache.
+     * Call this when process.cwd() changes between strategy iterations
+     * so new storage instances are created with the updated base path.
+     */
+    clear(): void;
     /**
      * Switches to the default JSON persist adapter.
      */
@@ -11700,12 +11760,20 @@ declare class PersistMemoryUtils {
         data: MemoryData;
     }>;
     /**
-     * Dispose persist adapter to prevent memory leak
+     * Clears the memoized storage cache.
+     * Call this when process.cwd() changes between strategy iterations
+     * so new storage instances are created with the updated base path.
+     */
+    clear: () => void;
+    /**
+     * Disposes of the memory adapter and releases any resources.
+     * Call this when a signal is removed to clean up its associated storage.
      *
      * @param signalId - Signal identifier
      * @param bucketName - Bucket name
+     * @returns void
      */
-    clear: (signalId: string, bucketName: string) => void;
+    dispose: (signalId: string, bucketName: string) => void;
     /**
      * Switches to the default JSON persist adapter.
      * All future persistence writes will use JSON storage.
@@ -12004,6 +12072,12 @@ declare class ReportAdapter extends ReportUtils {
      * @internal - Automatically called by report services, not for direct use
      */
     writeData: <T = any>(reportName: ReportName, data: T, options: IReportDumpOptions) => Promise<void>;
+    /**
+     * Clears the memoized storage cache.
+     * Call this when process.cwd() changes between strategy iterations
+     * so new storage instances are created with the updated base path.
+     */
+    clear(): void;
     /**
      * Switches to a dummy report adapter that discards all writes.
      * All future report writes will be no-ops.
@@ -12344,6 +12418,12 @@ declare class MarkdownAdapter extends MarkdownUtils {
      * All dumps append to a single .jsonl file per markdown type.
      */
     useJsonl(): void;
+    /**
+     * Clears the memoized storage cache.
+     * Call this when process.cwd() changes between strategy iterations
+     * so new storage instances are created with the updated base path.
+     */
+    clear(): void;
     /**
      * Switches to a dummy markdown adapter that discards all writes.
      * All future markdown writes will be no-ops.
@@ -12447,6 +12527,12 @@ declare class LogAdapter implements ILog {
      * @param dirName - Directory for the JSONL file (default: ./dump/log)
      */
     useJsonl: (fileName?: string, dirName?: string) => void;
+    /**
+     * Clears the cached log instance by resetting to the default in-memory adapter.
+     * Call this when process.cwd() changes between strategy iterations
+     * so a new adapter instance is created with the updated base path.
+     */
+    clear: () => void;
 }
 /**
  * Global singleton instance of LogAdapter.
@@ -17965,6 +18051,12 @@ declare class StorageBacktestAdapter implements IStorageUtils {
      * Signals will be stored in memory only.
      */
     useMemory: () => void;
+    /**
+     * Clears the cached utils instance by resetting to the default in-memory adapter.
+     * Call this when process.cwd() changes between strategy iterations
+     * so a new instance is created with the updated base path.
+     */
+    clear: () => void;
 }
 /**
  * Live trading storage adapter with pluggable storage backend.
@@ -18039,6 +18131,12 @@ declare class StorageLiveAdapter implements IStorageUtils {
      * Signals will be stored in memory only.
      */
     useMemory: () => void;
+    /**
+     * Clears the cached utils instance by resetting to the default persistent adapter.
+     * Call this when process.cwd() changes between strategy iterations
+     * so a new instance is created with the updated base path.
+     */
+    clear: () => void;
 }
 /**
  * Main storage adapter that manages both backtest and live signal storage.
@@ -18165,7 +18263,7 @@ interface INotificationUtils {
     /**
      * Clears all stored notifications.
      */
-    clear(): Promise<void>;
+    dispose(): Promise<void>;
 }
 /**
  * Constructor type for notification adapters.
@@ -18254,7 +18352,7 @@ declare class NotificationBacktestAdapter implements INotificationUtils {
      * Clears all stored notifications.
      * Proxies call to the underlying notification adapter.
      */
-    clear: () => Promise<void>;
+    dispose: () => Promise<void>;
     /**
      * Sets the notification adapter constructor.
      * All future notification operations will use this adapter.
@@ -18277,6 +18375,12 @@ declare class NotificationBacktestAdapter implements INotificationUtils {
      * Notifications will be persisted to disk.
      */
     usePersist: () => void;
+    /**
+     * Resets the cached utils instance to the default in-memory adapter.
+     * Call this when process.cwd() changes between strategy iterations
+     * so a new instance is created with the updated base path.
+     */
+    clear: () => void;
 }
 /**
  * Live trading notification adapter with pluggable notification backend.
@@ -18360,7 +18464,7 @@ declare class NotificationLiveAdapter implements INotificationUtils {
      * Clears all stored notifications.
      * Proxies call to the underlying notification adapter.
      */
-    clear: () => Promise<void>;
+    dispose: () => Promise<void>;
     /**
      * Sets the notification adapter constructor.
      * All future notification operations will use this adapter.
@@ -18383,6 +18487,12 @@ declare class NotificationLiveAdapter implements INotificationUtils {
      * Notifications will be persisted to disk.
      */
     usePersist: () => void;
+    /**
+     * Resets the cached utils instance to the default in-memory adapter.
+     * Call this when process.cwd() changes between strategy iterations
+     * so a new instance is created with the updated base path.
+     */
+    clear: () => void;
 }
 /**
  * Main notification adapter that manages both backtest and live notification storage.
@@ -18418,7 +18528,7 @@ declare class NotificationAdapter {
      *
      * @throws Error if NotificationAdapter is not enabled
      */
-    clear: (isBacktest: boolean) => Promise<void>;
+    dispose: (isBacktest: boolean) => Promise<void>;
 }
 /**
  * Global singleton instance of NotificationAdapter.
@@ -18635,6 +18745,12 @@ declare class MemoryAdapter implements TMemoryInstance {
      * Switches to dummy adapter that discards all writes.
      */
     useDummy: () => void;
+    /**
+     * Clears the memoized instance cache.
+     * Call this when process.cwd() changes between strategy iterations
+     * so new instances are created with the updated base path.
+     */
+    clear: () => void;
     /**
      * Releases resources held by this adapter.
      * Delegates to disable() to unsubscribe from signal lifecycle events.
@@ -18797,6 +18913,12 @@ declare class DumpAdapter {
      * @param Ctor - Constructor for the custom dump implementation
      */
     useDumpAdapter: (Ctor: TDumpInstanceCtor) => void;
+    /**
+     * Clears the memoized instance cache.
+     * Call this when process.cwd() changes between strategy iterations
+     * so new instances are created with the updated base path.
+     */
+    clear: () => void;
 }
 declare const Dump: DumpAdapter;
 
@@ -19037,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.
      *
@@ -19080,90 +19205,34 @@ declare class CacheUtils {
         interval: CandleInterval;
         name: string;
         key?: (args: CacheFileKeyArgs<T>) => string;
-    }) => T;
-    /**
-     * 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();
-     * ```
-     */
-    flush: <T extends Function>(run?: T) => void;
+    }) => T & {
+        clear(): 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.
+     * Dispose (remove) the memoized CacheInstance for a specific function.
      *
-     * 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);
      * ```
      */
-    clear: <T extends Function>(run: T) => void;
+    dispose: <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.
@@ -21389,6 +21458,12 @@ declare class BrokerAdapter {
      * ```
      */
     disable: () => void;
+    /**
+     * Clears the cached broker instance and resets the enable singleshot.
+     * Call this when process.cwd() changes between strategy iterations
+     * so a new broker instance is created with the updated base path.
+     */
+    clear: () => void;
 }
 /**
  * Base class for custom broker adapter implementations.