backtest-kit 9.7.0 → 9.8.1

package/package.json

@@ -1,86 +1,86 @@
-{
-  "name": "backtest-kit",
-  "version": "9.7.0",
-  "description": "A TypeScript library for trading system backtest",
-  "author": {
-    "name": "Petr Tripolsky",
-    "email": "tripolskypetr@gmail.com",
-    "url": "https://github.com/tripolskypetr"
-  },
-  "funding": {
-    "type": "individual",
-    "url": "http://paypal.me/tripolskypetr"
-  },
-  "license": "MIT",
-  "homepage": "https://backtest-kit.github.io/documents/article_07_ai_news_trading_signals.html",
-  "keywords": [
-    "backtesting",
-    "backtest",
-    "finance",
-    "trading",
-    "candles",
-    "indicators",
-    "multi value",
-    "multi symbol",
-    "framework"
-  ],
-  "files": [
-    "build",
-    "types.d.ts",
-    "README.md"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/tripolskypetr/backtest-kit",
-    "documentation": "https://github.com/tripolskypetr/backtest-kit/tree/master/docs"
-  },
-  "bugs": {
-    "url": "https://github.com/tripolskypetr/backtest-kit/issues"
-  },
-  "scripts": {
-    "build": "rollup -c",
-    "test": "npm run build && node ./test/index.mjs",
-    "build:docs": "rimraf docs && mkdir docs && node ./scripts/dts-docs.cjs ./types.d.ts ./docs",
-    "docs:gpt": "npm run build && node ./tools/gpt-docs/index.mjs",
-    "docs:uml": "npm run build && node ./scripts/uml.mjs",
-    "docs:www": "rimraf docs/wwwroot && node ./tools/typedoc-packages-docs/index.mjs && typedoc && node ./tools/typedoc-yandex-metrica/index.mjs",
-    "repl": "dotenv -e .env -- npm run build && node -e \"import('./scripts/repl.mjs')\" --interactive"
-  },
-  "main": "build/index.cjs",
-  "module": "build/index.mjs",
-  "source": "src/index.ts",
-  "types": "./types.d.ts",
-  "exports": {
-    "require": "./build/index.cjs",
-    "types": "./types.d.ts",
-    "import": "./build/index.mjs",
-    "default": "./build/index.cjs"
-  },
-  "devDependencies": {
-    "@rollup/plugin-typescript": "11.1.6",
-    "@types/node": "22.9.0",
-    "glob": "11.0.1",
-    "plantuml": "0.0.2",
-    "rimraf": "6.0.1",
-    "rollup": "3.29.5",
-    "rollup-plugin-dts": "6.1.1",
-    "rollup-plugin-peer-deps-external": "2.2.4",
-    "ts-morph": "27.0.2",
-    "tslib": "2.7.0",
-    "typedoc": "0.27.9",
-    "worker-testbed": "2.0.0"
-  },
-  "peerDependencies": {
-    "typescript": "^5.0.0"
-  },
-  "dependencies": {
-    "di-kit": "^1.1.1",
-    "di-scoped": "^1.0.21",
-    "di-singleton": "^1.0.5",
-    "functools-kit": "^2.3.0",
-    "get-moment-stamp": "^1.1.2"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "backtest-kit",
+  "version": "9.8.1",
+  "description": "A TypeScript library for trading system backtest",
+  "author": {
+    "name": "Petr Tripolsky",
+    "email": "tripolskypetr@gmail.com",
+    "url": "https://github.com/tripolskypetr"
+  },
+  "funding": {
+    "type": "individual",
+    "url": "http://paypal.me/tripolskypetr"
+  },
+  "license": "MIT",
+  "homepage": "https://backtest-kit.github.io/documents/article_07_ai_news_trading_signals.html",
+  "keywords": [
+    "backtesting",
+    "backtest",
+    "finance",
+    "trading",
+    "candles",
+    "indicators",
+    "multi value",
+    "multi symbol",
+    "framework"
+  ],
+  "files": [
+    "build",
+    "types.d.ts",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tripolskypetr/backtest-kit",
+    "documentation": "https://github.com/tripolskypetr/backtest-kit/tree/master/docs"
+  },
+  "bugs": {
+    "url": "https://github.com/tripolskypetr/backtest-kit/issues"
+  },
+  "scripts": {
+    "build": "rollup -c",
+    "test": "npm run build && node ./test/index.mjs",
+    "build:docs": "rimraf docs && mkdir docs && node ./scripts/dts-docs.cjs ./types.d.ts ./docs",
+    "docs:gpt": "npm run build && node ./tools/gpt-docs/index.mjs",
+    "docs:uml": "npm run build && node ./scripts/uml.mjs",
+    "docs:www": "rimraf docs/wwwroot && node ./tools/typedoc-packages-docs/index.mjs && typedoc && node ./tools/typedoc-yandex-metrica/index.mjs",
+    "repl": "dotenv -e .env -- npm run build && node -e \"import('./scripts/repl.mjs')\" --interactive"
+  },
+  "main": "build/index.cjs",
+  "module": "build/index.mjs",
+  "source": "src/index.ts",
+  "types": "./types.d.ts",
+  "exports": {
+    "require": "./build/index.cjs",
+    "types": "./types.d.ts",
+    "import": "./build/index.mjs",
+    "default": "./build/index.cjs"
+  },
+  "devDependencies": {
+    "@rollup/plugin-typescript": "11.1.6",
+    "@types/node": "22.9.0",
+    "glob": "11.0.1",
+    "plantuml": "0.0.2",
+    "rimraf": "6.0.1",
+    "rollup": "3.29.5",
+    "rollup-plugin-dts": "6.1.1",
+    "rollup-plugin-peer-deps-external": "2.2.4",
+    "ts-morph": "27.0.2",
+    "tslib": "2.7.0",
+    "typedoc": "0.27.9",
+    "worker-testbed": "2.0.0"
+  },
+  "peerDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "di-kit": "^1.1.1",
+    "di-scoped": "^1.0.21",
+    "di-singleton": "^1.0.5",
+    "functools-kit": "^2.3.0",
+    "get-moment-stamp": "^1.1.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/types.d.ts

@@ -4406,8 +4406,8 @@ interface ICacheCandlesParams {
     to: Date;
 }
 /**
- * Parameters for validating cached candle timestamps.
- * Reads JSON files directly from persist storage directory.
+ * Parameters for validating cached candle presence.
+ * Queries persist storage adapter without scanning files.
  */
 interface ICheckCandlesParams {
     /** Trading pair symbol (e.g., "BTCUSDT") */
@@ -4420,12 +4420,11 @@ interface ICheckCandlesParams {
     from: Date;
     /** End date of the validation range (inclusive) */
     to: Date;
-    /** Base directory of candle persist storage (default: "./dump/data/candle") */
-    baseDir?: string;
 }
 /**
- * Checks cached candle timestamps for correct interval alignment.
- * Reads JSON files directly from persist storage without using abstractions.
+ * Checks cached candle presence via the persist adapter.
+ * Issues one ranged read; adapter-side `hasValue` covers each expected timestamp,
+ * so a single missing or unaligned candle yields a miss without loading the whole dataset.
  *
  * @param params - Validation parameters
  */
@@ -16683,8 +16682,17 @@ type TLogCtor = new () => Partial<ILog>;
  * - Convenience methods: usePersist(), useMemory(), useDummy()
  */
 declare class LogAdapter implements ILog {
-    /** Internal log utils instance */
-    private _log;
+    /** Factory producing the active log utils instance */
+    private _logFactory;
+    /**
+     * Lazily constructs the log utils from the registered factory and memoizes
+     * the result via `singleshot`.
+     *
+     * The instance is built on the first call and cached for all subsequent calls.
+     * Reset via `clear()` so the next call rebuilds from the current factory
+     * (e.g. when `process.cwd()` changes between strategy iterations).
+     */
+    private getInstance;
     /**
      * Lists all stored log entries.
      * Proxies call to the underlying log adapter.
@@ -16750,7 +16758,7 @@ declare class LogAdapter implements ILog {
      */
     useJsonl: (fileName?: string, dirName?: string) => void;
     /**
-     * Clears the cached log instance by resetting to the default in-memory adapter.
+     * Clears the memoized log instance.
      * Call this when process.cwd() changes between strategy iterations
      * so a new adapter instance is created with the updated base path.
      */
@@ -23669,8 +23677,16 @@ type TStorageUtilsCtor = new () => IStorageUtils;
  * - Convenience methods: usePersist(), useMemory(), useDummy()
  */
 declare class StorageBacktestAdapter implements IStorageUtils {
-    /** Internal storage utils instance */
-    private _signalBacktestUtils;
+    /** Factory producing the active storage utils instance */
+    private _signalBacktestFactory;
+    /**
+     * Lazily constructs the storage utils from the registered factory and memoizes
+     * the result via `singleshot`.
+     *
+     * The instance is built on the first call and cached for all subsequent calls.
+     * Reset via `clear()` so the next call rebuilds from the current factory.
+     */
+    private getInstance;
     /**
      * Handles signal opened event.
      * Proxies call to the underlying storage adapter.
@@ -23733,7 +23749,7 @@ declare class StorageBacktestAdapter implements IStorageUtils {
      */
     useMemory: () => void;
     /**
-     * Clears the cached utils instance by resetting to the default in-memory adapter.
+     * Clears the memoized utils instance.
      * Call this when process.cwd() changes between strategy iterations
      * so a new instance is created with the updated base path.
      */
@@ -23749,8 +23765,16 @@ declare class StorageBacktestAdapter implements IStorageUtils {
  * - Convenience methods: usePersist(), useMemory(), useDummy()
  */
 declare class StorageLiveAdapter implements IStorageUtils {
-    /** Internal storage utils instance */
-    private _signalLiveUtils;
+    /** Factory producing the active storage utils instance */
+    private _signalLiveFactory;
+    /**
+     * Lazily constructs the storage utils from the registered factory and memoizes
+     * the result via `singleshot`.
+     *
+     * The instance is built on the first call and cached for all subsequent calls.
+     * Reset via `clear()` so the next call rebuilds from the current factory.
+     */
+    private getInstance;
     /**
      * Handles signal opened event.
      * Proxies call to the underlying storage adapter.
@@ -23813,7 +23837,7 @@ declare class StorageLiveAdapter implements IStorageUtils {
      */
     useMemory: () => void;
     /**
-     * Clears the cached utils instance by resetting to the default persistent adapter.
+     * Clears the memoized utils instance.
      * Call this when process.cwd() changes between strategy iterations
      * so a new instance is created with the updated base path.
      */
@@ -23931,8 +23955,16 @@ type TRecentUtilsCtor = new () => IRecentUtils;
  * - Convenience methods: usePersist(), useMemory()
  */
 declare class RecentBacktestAdapter implements IRecentUtils {
-    /** Internal storage utils instance */
-    private _recentBacktestUtils;
+    /** Factory producing the active storage utils instance */
+    private _recentBacktestFactory;
+    /**
+     * Lazily constructs the storage utils from the registered factory and memoizes
+     * the result via `singleshot`.
+     *
+     * The instance is built on the first call and cached for all subsequent calls.
+     * Reset via `clear()` so the next call rebuilds from the current factory.
+     */
+    private getInstance;
     /**
      * Handles active ping event.
      * Proxies call to the underlying storage adapter.
@@ -23982,7 +24014,9 @@ declare class RecentBacktestAdapter implements IRecentUtils {
      */
     useMemory: () => void;
     /**
-     * Clears the cached utils instance by resetting to the default in-memory adapter.
+     * Clears the memoized utils instance.
+     * Call this when process.cwd() changes between strategy iterations
+     * so a new instance is created with the updated base path.
      */
     clear: () => void;
 }
@@ -23996,8 +24030,16 @@ declare class RecentBacktestAdapter implements IRecentUtils {
  * - Convenience methods: usePersist(), useMemory()
  */
 declare class RecentLiveAdapter implements IRecentUtils {
-    /** Internal storage utils instance */
-    private _recentLiveUtils;
+    /** Factory producing the active storage utils instance */
+    private _recentLiveFactory;
+    /**
+     * Lazily constructs the storage utils from the registered factory and memoizes
+     * the result via `singleshot`.
+     *
+     * The instance is built on the first call and cached for all subsequent calls.
+     * Reset via `clear()` so the next call rebuilds from the current factory.
+     */
+    private getInstance;
     /**
      * Handles active ping event.
      * Proxies call to the underlying storage adapter.
@@ -24047,7 +24089,9 @@ declare class RecentLiveAdapter implements IRecentUtils {
      */
     useMemory: () => void;
     /**
-     * Clears the cached utils instance by resetting to the default persistent adapter.
+     * Clears the memoized utils instance.
+     * Call this when process.cwd() changes between strategy iterations
+     * so a new instance is created with the updated base path.
      */
     clear: () => void;
 }
@@ -24293,8 +24337,16 @@ type TNotificationUtilsCtor = new () => INotificationUtils;
  * - Convenience methods: usePersist(), useMemory(), useDummy()
  */
 declare class NotificationBacktestAdapter implements INotificationUtils {
-    /** Internal notification utils instance */
-    private _notificationBacktestUtils;
+    /** Factory producing the active notification utils instance */
+    private _notificationBacktestFactory;
+    /**
+     * Lazily constructs the notification utils from the registered factory and
+     * memoizes the result via `singleshot`.
+     *
+     * The instance is built on the first call and cached for all subsequent calls.
+     * Reset via `clear()` so the next call rebuilds from the current factory.
+     */
+    private getInstance;
     /**
      * Handles signal events.
      * Proxies call to the underlying notification adapter.
@@ -24390,7 +24442,7 @@ declare class NotificationBacktestAdapter implements INotificationUtils {
      */
     usePersist: () => void;
     /**
-     * Resets the cached utils instance to the default in-memory adapter.
+     * Clears the memoized utils instance.
      * Call this when process.cwd() changes between strategy iterations
      * so a new instance is created with the updated base path.
      */
@@ -24406,8 +24458,16 @@ declare class NotificationBacktestAdapter implements INotificationUtils {
  * - Convenience methods: usePersist(), useMemory(), useDummy()
  */
 declare class NotificationLiveAdapter implements INotificationUtils {
-    /** Internal notification utils instance */
-    private _notificationLiveUtils;
+    /** Factory producing the active notification utils instance */
+    private _notificationLiveFactory;
+    /**
+     * Lazily constructs the notification utils from the registered factory and
+     * memoizes the result via `singleshot`.
+     *
+     * The instance is built on the first call and cached for all subsequent calls.
+     * Reset via `clear()` so the next call rebuilds from the current factory.
+     */
+    private getInstance;
     /**
      * Handles signal events.
      * Proxies call to the underlying notification adapter.
@@ -24503,7 +24563,7 @@ declare class NotificationLiveAdapter implements INotificationUtils {
      */
     usePersist: () => void;
     /**
-     * Resets the cached utils instance to the default in-memory adapter.
+     * Clears the memoized utils instance.
      * Call this when process.cwd() changes between strategy iterations
      * so a new instance is created with the updated base path.
      */
@@ -27477,7 +27537,19 @@ type TBrokerCtor = new () => Partial<IBroker>;
  * ```
  */
 declare class BrokerAdapter {
-    private _brokerInstance;
+    /** Factory producing the active `BrokerProxy` instance */
+    private _brokerFactory;
+    /**
+     * Lazily constructs the `BrokerProxy` from the registered factory and
+     * memoizes the result via `singleshot`.
+     *
+     * The proxy is built on the first call and cached for all subsequent calls.
+     * Returns `null` when no adapter has been registered via `useBrokerAdapter()`.
+     *
+     * Reset via `clear()` so the next call rebuilds from the current factory
+     * (e.g. when `process.cwd()` changes between strategy iterations).
+     */
+    private getInstance;
     /**
      * Forwards a signal-open event to the registered broker adapter.
      *