backtest-kit 10.1.0 → 10.2.0

package/package.json

@@ -1,86 +1,86 @@
-{
-  "name": "backtest-kit",
-  "version": "10.1.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": "^2.0.0"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "backtest-kit",
+  "version": "10.2.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": "^2.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/types.d.ts

@@ -4618,7 +4618,7 @@ interface BacktestStatisticsModel {
     stdDev: number | null;
     /** Sharpe Ratio (risk-adjusted return = avgPnl / stdDev), null if unsafe. Higher is better. */
     sharpeRatio: number | null;
-    /** Annualized Sharpe Ratio (sharpeRatio × √365), null if unsafe. Higher is better. */
+    /** Annualized Sharpe Ratio (sharpeRatio × √tradesPerYear), null if unsafe. Higher is better. */
     annualizedSharpeRatio: number | null;
     /** Certainty Ratio (avgWin / |avgLoss|), null if unsafe. Higher is better. */
     certaintyRatio: number | null;
@@ -4628,7 +4628,7 @@ interface BacktestStatisticsModel {
     avgPeakPnl: number | null;
     /** Average fall PNL percentage across all signals (_fall.pnlPercentage), null if unsafe. Lower (more negative) means deeper drawdowns. */
     avgFallPnl: number | null;
-    /** Sortino Ratio (avgPnl / downside deviation — stdDev of losses only), null if unsafe. Higher is better. */
+    /** Sortino Ratio (avgPnl / downside deviation — RMS of losing trades only), null if unsafe. Higher is better. */
     sortinoRatio: number | null;
     /** Calmar Ratio (annualized expected return / max drawdown), null if unsafe. Higher is better. */
     calmarRatio: number | null;
@@ -10693,7 +10693,7 @@ interface IHeatmapRow {
     symbol: string;
     /** Total profit/loss percentage across all closed trades */
     totalPnl: number | null;
-    /** Risk-adjusted return (Sharpe Ratio) */
+    /** Risk-adjusted return per trade (Sharpe Ratio = avgPnl / stdDev) */
     sharpeRatio: number | null;
     /** Maximum drawdown percentage (largest peak-to-trough decline) */
     maxDrawdown: number | null;
@@ -10725,7 +10725,7 @@ interface IHeatmapRow {
     avgPeakPnl: number | null;
     /** Average fall PNL percentage across all trades (_fall.pnlPercentage). Closer to 0 is better. */
     avgFallPnl: number | null;
-    /** Sortino Ratio (avgPnl / downside deviation — stdDev of losses only). Higher is better. */
+    /** Sortino Ratio (avgPnl / downside deviation — RMS of losing trades only). Higher is better. */
     sortinoRatio: number | null;
     /** Calmar Ratio (totalPnl / maxDrawdown). Higher is better. */
     calmarRatio: number | null;
@@ -12593,7 +12593,7 @@ interface LiveStatisticsModel {
     stdDev: number | null;
     /** Sharpe Ratio (risk-adjusted return = avgPnl / stdDev), null if unsafe. Higher is better. */
     sharpeRatio: number | null;
-    /** Annualized Sharpe Ratio (sharpeRatio × √365), null if unsafe. Higher is better. */
+    /** Annualized Sharpe Ratio (sharpeRatio × √tradesPerYear), null if unsafe. Higher is better. */
     annualizedSharpeRatio: number | null;
     /** Certainty Ratio (avgWin / |avgLoss|), null if unsafe. Higher is better. */
     certaintyRatio: number | null;
@@ -12603,7 +12603,7 @@ interface LiveStatisticsModel {
     avgPeakPnl: number | null;
     /** Average fall PNL percentage across all closed signals (_fall.pnlPercentage), null if unsafe. Closer to 0 is better. */
     avgFallPnl: number | null;
-    /** Sortino Ratio (avgPnl / downside deviation — stdDev of losses only), null if unsafe. Higher is better. */
+    /** Sortino Ratio (avgPnl / downside deviation — RMS of losing trades only), null if unsafe. Higher is better. */
     sortinoRatio: number | null;
     /** Calmar Ratio (annualized expected return / max drawdown), null if unsafe. Higher is better. */
     calmarRatio: number | null;
@@ -21480,7 +21480,7 @@ declare class HeatMarkdownService {
      * console.log(markdown);
      * // # Portfolio Heatmap: my-strategy
      * //
-     * // **Total Symbols:** 5 | **Portfolio PNL:** +45.3% | **Portfolio Sharpe:** 1.85 | **Total Trades:** 120
+     * // **Total Symbols:** 5 | **Portfolio PNL:** +45.3% | **Pooled Sharpe:** 1.85 | **Total Trades:** 120
      * //
      * // | Symbol | Total PNL | Sharpe | Max DD | Trades |
      * // | ---    | ---       | ---    | ---    | ---    |
@@ -26529,6 +26529,33 @@ declare class CronUtils {
      * `clear()` for those).
      */
     disable: () => void;
+    /**
+     * Hard-reset the entire `Cron` state.
+     *
+     * Performs in order:
+     * 1. {@link disable} — tears down lifecycle subscriptions and resets the
+     *    `enable` singleshot so a future `enable()` re-subscribes cleanly.
+     * 2. Wipes `_entries` — every {@link register}'ed entry is forgotten.
+     *    Disposers returned by previous `register()` calls become no-ops
+     *    (their `unregister(name)` will not find anything to remove).
+     * 3. Wipes `_firedOnce` — all fire-once marks are dropped, so any future
+     *    re-registration of the same `name` fires again on the next matching
+     *    tick.
+     * 4. Does **not** touch `_inFlight` — in-flight handlers continue to
+     *    settle in the background and clear their own slots via `.finally()`.
+     *    Their final `_firedOnce.add(firedKey)` writes carry old-generation
+     *    keys and are harmless (lookup uses the post-dispose generation).
+     *
+     * Use from a CLI/session teardown when you want to throw away every
+     * registration along with the lifecycle wiring — e.g. between two
+     * independent runner scopes. For "just snap the subscriptions but keep
+     * registrations" use {@link disable} instead; for "just re-arm fire-once
+     * marks" use {@link clear}.
+     *
+     * Idempotent. Safe to call multiple times and safe to call before
+     * `enable()` / without any registrations.
+     */
+    dispose: () => void;
 }
 /**
  * Singleton instance of {@link CronUtils} for registering periodic tasks