backtest-kit 1.1.3 → 1.1.4

package/README.md

@@ -20,6 +20,8 @@
 - 🔌 **Flexible Architecture** - Plug your own exchanges and strategies
 - 📝 **Markdown Reports** - Auto-generated trading reports with statistics (win rate, avg PNL)
 - 🛑 **Graceful Shutdown** - Live.background() waits for open positions to close before stopping
+- 💉 **Strategy Dependency Injection** - addStrategy() enables DI pattern for trading strategies
+- 🧪 **Comprehensive Test Coverage** - 30+ unit tests covering validation, PNL, callbacks, reports, and event system
 
 ## Installation
 
@@ -829,23 +831,6 @@ src/
 
 ## Advanced Examples
 
-### Custom Persistence Adapter
-
-```typescript
-import { PersistSignalAdaper, PersistBase } from "backtest-kit";
-
-class RedisPersist extends PersistBase {
-  async readValue(entityId) {
-    return JSON.parse(await redis.get(entityId));
-  }
-  async writeValue(entityId, entity) {
-    await redis.set(entityId, JSON.stringify(entity));
-  }
-}
-
-PersistSignalAdaper.usePersistSignalAdapter(RedisPersist);
-```
-
 ### Multi-Symbol Live Trading
 
 ```typescript

package/build/index.cjs

@@ -1104,6 +1104,32 @@ class PersistSignalUtils {
  */
 const PersistSignalAdaper = new PersistSignalUtils();
 
+/**
+ * Global signal emitter for all trading events (live + backtest).
+ * Emits all signal events regardless of execution mode.
+ */
+const signalEmitter = new functoolsKit.Subject();
+/**
+ * Live trading signal emitter.
+ * Emits only signals from live trading execution.
+ */
+const signalLiveEmitter = new functoolsKit.Subject();
+/**
+ * Backtest signal emitter.
+ * Emits only signals from backtest execution.
+ */
+const signalBacktestEmitter = new functoolsKit.Subject();
+/**
+ * Error emitter for background execution errors.
+ * Emits errors caught in background tasks (Live.background, Backtest.background).
+ */
+const errorEmitter = new functoolsKit.Subject();
+/**
+ * Done emitter for background execution completion.
+ * Emits when background tasks complete (Live.background, Backtest.background).
+ */
+const doneEmitter = new functoolsKit.Subject();
+
 const INTERVAL_MINUTES$1 = {
     "1m": 1,
     "3m": 3,
@@ -1155,6 +1181,9 @@ const VALIDATE_SIGNAL_FN = (signal) => {
     }
 };
 const GET_SIGNAL_FN = functoolsKit.trycatch(async (self) => {
+    if (self._isStopped) {
+        return null;
+    }
     const currentTime = self.params.execution.context.when.getTime();
     {
         const intervalMinutes = INTERVAL_MINUTES$1[self.params.interval];
@@ -1183,6 +1212,13 @@ const GET_SIGNAL_FN = functoolsKit.trycatch(async (self) => {
     return signalRow;
 }, {
     defaultValue: null,
+    fallback: (error) => {
+        backtest$1.loggerService.warn("ClientStrategy exception thrown", {
+            error: functoolsKit.errorData(error),
+            message: functoolsKit.getErrorMessage(error),
+        });
+        errorEmitter.next(error);
+    },
 });
 const GET_AVG_PRICE_FN = (candles) => {
     const sumPriceVolume = candles.reduce((acc, c) => {
@@ -1241,6 +1277,7 @@ const WAIT_FOR_INIT_FN = async (self) => {
 class ClientStrategy {
     constructor(params) {
         this.params = params;
+        this._isStopped = false;
         this._pendingSignal = null;
         this._lastSignalTimestamp = null;
         /**
@@ -1563,34 +1600,32 @@ class ClientStrategy {
         }
         return result;
     }
+    /**
+     * Stops the strategy from generating new signals.
+     *
+     * Sets internal flag to prevent getSignal from being called.
+     * Does NOT close active pending signals - they continue monitoring until TP/SL/time_expired.
+     *
+     * Use case: Graceful shutdown in live trading without forcing position closure.
+     *
+     * @returns Promise that resolves immediately when stop flag is set
+     *
+     * @example
+     * ```typescript
+     * // In Live.background() cancellation
+     * await strategy.stop();
+     * // Existing signal will continue until natural close
+     * ```
+     */
+    stop() {
+        this.params.logger.debug("ClientStrategy stop", {
+            hasPendingSignal: this._pendingSignal !== null,
+        });
+        this._isStopped = true;
+        return Promise.resolve();
+    }
 }
 
-/**
- * Global signal emitter for all trading events (live + backtest).
- * Emits all signal events regardless of execution mode.
- */
-const signalEmitter = new functoolsKit.Subject();
-/**
- * Live trading signal emitter.
- * Emits only signals from live trading execution.
- */
-const signalLiveEmitter = new functoolsKit.Subject();
-/**
- * Backtest signal emitter.
- * Emits only signals from backtest execution.
- */
-const signalBacktestEmitter = new functoolsKit.Subject();
-/**
- * Error emitter for background execution errors.
- * Emits errors caught in background tasks (Live.background, Backtest.background).
- */
-const errorEmitter = new functoolsKit.Subject();
-/**
- * Done emitter for background execution completion.
- * Emits when background tasks complete (Live.background, Backtest.background).
- */
-const doneEmitter = new functoolsKit.Subject();
-
 /**
  * Connection service routing strategy operations to correct ClientStrategy instance.
  *
@@ -1689,6 +1724,36 @@ class StrategyConnectionService {
             }
             return tick;
         };
+        /**
+         * Stops the specified strategy from generating new signals.
+         *
+         * Delegates to ClientStrategy.stop() which sets internal flag to prevent
+         * getSignal from being called on subsequent ticks.
+         *
+         * @param strategyName - Name of strategy to stop
+         * @returns Promise that resolves when stop flag is set
+         */
+        this.stop = async (strategyName) => {
+            this.loggerService.log("strategyConnectionService stop", {
+                strategyName,
+            });
+            const strategy = this.getStrategy(strategyName);
+            await strategy.stop();
+        };
+        /**
+         * Clears the memoized ClientStrategy instance from cache.
+         *
+         * Forces re-initialization of strategy on next getStrategy call.
+         * Useful for resetting strategy state or releasing resources.
+         *
+         * @param strategyName - Name of strategy to clear from cache
+         */
+        this.clear = async (strategyName) => {
+            this.loggerService.log("strategyConnectionService clear", {
+                strategyName,
+            });
+            this.getStrategy.clear(strategyName);
+        };
     }
 }
 
@@ -2032,6 +2097,35 @@ class StrategyGlobalService {
                 backtest,
             });
         };
+        /**
+         * Stops the strategy from generating new signals.
+         *
+         * Delegates to StrategyConnectionService.stop() to set internal flag.
+         * Does not require execution context.
+         *
+         * @param strategyName - Name of strategy to stop
+         * @returns Promise that resolves when stop flag is set
+         */
+        this.stop = async (strategyName) => {
+            this.loggerService.log("strategyGlobalService stop", {
+                strategyName,
+            });
+            return await this.strategyConnectionService.stop(strategyName);
+        };
+        /**
+         * Clears the memoized ClientStrategy instance from cache.
+         *
+         * Delegates to StrategyConnectionService.clear() to remove strategy from cache.
+         * Forces re-initialization of strategy on next operation.
+         *
+         * @param strategyName - Name of strategy to clear from cache
+         */
+        this.clear = async (strategyName) => {
+            this.loggerService.log("strategyGlobalService clear", {
+                strategyName,
+            });
+            return await this.strategyConnectionService.clear(strategyName);
+        };
     }
 }
 
@@ -2262,7 +2356,7 @@ class FrameSchemaService {
     register(key, value) {
         this.loggerService.log(`frameSchemaService register`, { key });
         this.validateShallow(value);
-        this._registry.register(key, value);
+        this._registry = this._registry.register(key, value);
     }
     /**
      * Overrides an existing frame schema with partial updates.
@@ -2273,7 +2367,8 @@ class FrameSchemaService {
      */
     override(key, value) {
         this.loggerService.log(`frameSchemaService override`, { key });
-        this._registry.override(key, value);
+        this._registry = this._registry.override(key, value);
+        return this._registry.get(key);
     }
     /**
      * Retrieves a frame schema by name.
@@ -2720,10 +2815,17 @@ let ReportStorage$1 = class ReportStorage {
             return functoolsKit.str.newline(`# Backtest Report: ${strategyName}`, "", "No signals closed yet.");
         }
         const header = columns$1.map((col) => col.label);
+        const separator = columns$1.map(() => "---");
         const rows = this._signalList.map((closedSignal) => columns$1.map((col) => col.format(closedSignal)));
-        const tableData = [header, ...rows];
-        const table = functoolsKit.str.table(tableData);
-        return functoolsKit.str.newline(`# Backtest Report: ${strategyName}`, "", `Total signals: ${this._signalList.length}`, "", table, "", "", `*Generated: ${new Date().toISOString()}*`);
+        const tableData = [header, separator, ...rows];
+        const table = functoolsKit.str.newline(tableData.map(row => `| ${row.join(" | ")} |`));
+        // Calculate statistics
+        const totalSignals = this._signalList.length;
+        const winCount = this._signalList.filter((s) => s.pnl.pnlPercentage > 0).length;
+        const lossCount = this._signalList.filter((s) => s.pnl.pnlPercentage < 0).length;
+        const avgPnl = this._signalList.reduce((sum, s) => sum + s.pnl.pnlPercentage, 0) / totalSignals;
+        const totalPnl = this._signalList.reduce((sum, s) => sum + s.pnl.pnlPercentage, 0);
+        return functoolsKit.str.newline(`# Backtest Report: ${strategyName}`, "", table, "", `**Total signals:** ${totalSignals}`, `**Closed signals:** ${totalSignals}`, `**Win rate:** ${((winCount / totalSignals) * 100).toFixed(2)}% (${winCount}W / ${lossCount}L)`, `**Average PNL:** ${avgPnl > 0 ? "+" : ""}${avgPnl.toFixed(2)}%`, `**Total PNL:** ${totalPnl > 0 ? "+" : ""}${totalPnl.toFixed(2)}%`);
     }
     /**
      * Saves strategy report to disk.
@@ -3118,9 +3220,10 @@ class ReportStorage {
             return functoolsKit.str.newline(`# Live Trading Report: ${strategyName}`, "", "No events recorded yet.");
         }
         const header = columns.map((col) => col.label);
+        const separator = columns.map(() => "---");
         const rows = this._eventList.map((event) => columns.map((col) => col.format(event)));
-        const tableData = [header, ...rows];
-        const table = functoolsKit.str.table(tableData);
+        const tableData = [header, separator, ...rows];
+        const table = functoolsKit.str.newline(tableData.map(row => `| ${row.join(" | ")} |`));
         // Calculate statistics
         const closedEvents = this._eventList.filter((e) => e.action === "closed");
         const totalClosed = closedEvents.length;
@@ -3129,11 +3232,14 @@ class ReportStorage {
         const avgPnl = totalClosed > 0
             ? closedEvents.reduce((sum, e) => sum + (e.pnl || 0), 0) / totalClosed
             : 0;
-        return functoolsKit.str.newline(`# Live Trading Report: ${strategyName}`, "", `Total events: ${this._eventList.length}`, `Closed signals: ${totalClosed}`, totalClosed > 0
-            ? `Win rate: ${((winCount / totalClosed) * 100).toFixed(2)}% (${winCount}W / ${lossCount}L)`
+        const totalPnl = closedEvents.reduce((sum, e) => sum + (e.pnl || 0), 0);
+        return functoolsKit.str.newline(`# Live Trading Report: ${strategyName}`, "", table, "", `**Total events:** ${this._eventList.length}`, `**Closed signals:** ${totalClosed}`, totalClosed > 0
+            ? `**Win rate:** ${((winCount / totalClosed) * 100).toFixed(2)}% (${winCount}W / ${lossCount}L)`
             : "", totalClosed > 0
-            ? `Average PNL: ${avgPnl > 0 ? "+" : ""}${avgPnl.toFixed(2)}%`
-            : "", "", table, "", "", `*Generated: ${new Date().toISOString()}*`);
+            ? `**Average PNL:** ${avgPnl > 0 ? "+" : ""}${avgPnl.toFixed(2)}%`
+            : "", totalClosed > 0
+            ? `**Total PNL:** ${totalPnl > 0 ? "+" : ""}${totalPnl.toFixed(2)}%`
+            : "");
     }
     /**
      * Saves strategy report to disk.
@@ -4164,6 +4270,7 @@ class BacktestUtils {
                 context,
             });
             backtest$1.backtestMarkdownService.clear(context.strategyName);
+            backtest$1.strategyGlobalService.clear(context.strategyName);
             return backtest$1.backtestGlobalService.run(symbol, context);
         };
         /**
@@ -4192,14 +4299,9 @@ class BacktestUtils {
                 symbol,
                 context,
             });
-            const iterator = this.run(symbol, context);
             let isStopped = false;
             const task = async () => {
-                while (true) {
-                    const { done } = await iterator.next();
-                    if (done) {
-                        break;
-                    }
+                for await (const _ of this.run(symbol, context)) {
                     if (isStopped) {
                         break;
                     }
@@ -4213,6 +4315,7 @@ class BacktestUtils {
             };
             task().catch((error) => errorEmitter.next(new Error(functoolsKit.getErrorMessage(error))));
             return () => {
+                backtest$1.strategyGlobalService.stop(context.strategyName);
                 isStopped = true;
             };
         };
@@ -4329,6 +4432,7 @@ class LiveUtils {
                 context,
             });
             backtest$1.liveMarkdownService.clear(context.strategyName);
+            backtest$1.strategyGlobalService.clear(context.strategyName);
             return backtest$1.liveGlobalService.run(symbol, context);
         };
         /**
@@ -4357,19 +4461,10 @@ class LiveUtils {
                 symbol,
                 context,
             });
-            const iterator = this.run(symbol, context);
             let isStopped = false;
-            let lastValue = null;
             const task = async () => {
-                while (true) {
-                    const { value, done } = await iterator.next();
-                    if (value) {
-                        lastValue = value;
-                    }
-                    if (done) {
-                        break;
-                    }
-                    if (lastValue?.action === "closed" && isStopped) {
+                for await (const signal of this.run(symbol, context)) {
+                    if (signal?.action === "closed" && isStopped) {
                         break;
                     }
                 }
@@ -4382,6 +4477,7 @@ class LiveUtils {
             };
             task().catch((error) => errorEmitter.next(new Error(functoolsKit.getErrorMessage(error))));
             return () => {
+                backtest$1.strategyGlobalService.stop(context.strategyName);
                 isStopped = true;
             };
         };

package/build/index.mjs

@@ -1,6 +1,6 @@
 import { createActivator } from 'di-kit';
 import { scoped } from 'di-scoped';
-import { memoize, makeExtendable, singleshot, getErrorMessage, not, trycatch, retry, randomString, Subject, ToolRegistry, sleep, str, queued } from 'functools-kit';
+import { memoize, makeExtendable, singleshot, getErrorMessage, not, trycatch, retry, Subject, randomString, errorData, ToolRegistry, sleep, str, queued } from 'functools-kit';
 import fs, { mkdir, writeFile } from 'fs/promises';
 import path, { join } from 'path';
 import crypto from 'crypto';
@@ -1102,6 +1102,32 @@ class PersistSignalUtils {
  */
 const PersistSignalAdaper = new PersistSignalUtils();
 
+/**
+ * Global signal emitter for all trading events (live + backtest).
+ * Emits all signal events regardless of execution mode.
+ */
+const signalEmitter = new Subject();
+/**
+ * Live trading signal emitter.
+ * Emits only signals from live trading execution.
+ */
+const signalLiveEmitter = new Subject();
+/**
+ * Backtest signal emitter.
+ * Emits only signals from backtest execution.
+ */
+const signalBacktestEmitter = new Subject();
+/**
+ * Error emitter for background execution errors.
+ * Emits errors caught in background tasks (Live.background, Backtest.background).
+ */
+const errorEmitter = new Subject();
+/**
+ * Done emitter for background execution completion.
+ * Emits when background tasks complete (Live.background, Backtest.background).
+ */
+const doneEmitter = new Subject();
+
 const INTERVAL_MINUTES$1 = {
     "1m": 1,
     "3m": 3,
@@ -1153,6 +1179,9 @@ const VALIDATE_SIGNAL_FN = (signal) => {
     }
 };
 const GET_SIGNAL_FN = trycatch(async (self) => {
+    if (self._isStopped) {
+        return null;
+    }
     const currentTime = self.params.execution.context.when.getTime();
     {
         const intervalMinutes = INTERVAL_MINUTES$1[self.params.interval];
@@ -1181,6 +1210,13 @@ const GET_SIGNAL_FN = trycatch(async (self) => {
     return signalRow;
 }, {
     defaultValue: null,
+    fallback: (error) => {
+        backtest$1.loggerService.warn("ClientStrategy exception thrown", {
+            error: errorData(error),
+            message: getErrorMessage(error),
+        });
+        errorEmitter.next(error);
+    },
 });
 const GET_AVG_PRICE_FN = (candles) => {
     const sumPriceVolume = candles.reduce((acc, c) => {
@@ -1239,6 +1275,7 @@ const WAIT_FOR_INIT_FN = async (self) => {
 class ClientStrategy {
     constructor(params) {
         this.params = params;
+        this._isStopped = false;
         this._pendingSignal = null;
         this._lastSignalTimestamp = null;
         /**
@@ -1561,34 +1598,32 @@ class ClientStrategy {
         }
         return result;
     }
+    /**
+     * Stops the strategy from generating new signals.
+     *
+     * Sets internal flag to prevent getSignal from being called.
+     * Does NOT close active pending signals - they continue monitoring until TP/SL/time_expired.
+     *
+     * Use case: Graceful shutdown in live trading without forcing position closure.
+     *
+     * @returns Promise that resolves immediately when stop flag is set
+     *
+     * @example
+     * ```typescript
+     * // In Live.background() cancellation
+     * await strategy.stop();
+     * // Existing signal will continue until natural close
+     * ```
+     */
+    stop() {
+        this.params.logger.debug("ClientStrategy stop", {
+            hasPendingSignal: this._pendingSignal !== null,
+        });
+        this._isStopped = true;
+        return Promise.resolve();
+    }
 }
 
-/**
- * Global signal emitter for all trading events (live + backtest).
- * Emits all signal events regardless of execution mode.
- */
-const signalEmitter = new Subject();
-/**
- * Live trading signal emitter.
- * Emits only signals from live trading execution.
- */
-const signalLiveEmitter = new Subject();
-/**
- * Backtest signal emitter.
- * Emits only signals from backtest execution.
- */
-const signalBacktestEmitter = new Subject();
-/**
- * Error emitter for background execution errors.
- * Emits errors caught in background tasks (Live.background, Backtest.background).
- */
-const errorEmitter = new Subject();
-/**
- * Done emitter for background execution completion.
- * Emits when background tasks complete (Live.background, Backtest.background).
- */
-const doneEmitter = new Subject();
-
 /**
  * Connection service routing strategy operations to correct ClientStrategy instance.
  *
@@ -1687,6 +1722,36 @@ class StrategyConnectionService {
             }
             return tick;
         };
+        /**
+         * Stops the specified strategy from generating new signals.
+         *
+         * Delegates to ClientStrategy.stop() which sets internal flag to prevent
+         * getSignal from being called on subsequent ticks.
+         *
+         * @param strategyName - Name of strategy to stop
+         * @returns Promise that resolves when stop flag is set
+         */
+        this.stop = async (strategyName) => {
+            this.loggerService.log("strategyConnectionService stop", {
+                strategyName,
+            });
+            const strategy = this.getStrategy(strategyName);
+            await strategy.stop();
+        };
+        /**
+         * Clears the memoized ClientStrategy instance from cache.
+         *
+         * Forces re-initialization of strategy on next getStrategy call.
+         * Useful for resetting strategy state or releasing resources.
+         *
+         * @param strategyName - Name of strategy to clear from cache
+         */
+        this.clear = async (strategyName) => {
+            this.loggerService.log("strategyConnectionService clear", {
+                strategyName,
+            });
+            this.getStrategy.clear(strategyName);
+        };
     }
 }
 
@@ -2030,6 +2095,35 @@ class StrategyGlobalService {
                 backtest,
             });
         };
+        /**
+         * Stops the strategy from generating new signals.
+         *
+         * Delegates to StrategyConnectionService.stop() to set internal flag.
+         * Does not require execution context.
+         *
+         * @param strategyName - Name of strategy to stop
+         * @returns Promise that resolves when stop flag is set
+         */
+        this.stop = async (strategyName) => {
+            this.loggerService.log("strategyGlobalService stop", {
+                strategyName,
+            });
+            return await this.strategyConnectionService.stop(strategyName);
+        };
+        /**
+         * Clears the memoized ClientStrategy instance from cache.
+         *
+         * Delegates to StrategyConnectionService.clear() to remove strategy from cache.
+         * Forces re-initialization of strategy on next operation.
+         *
+         * @param strategyName - Name of strategy to clear from cache
+         */
+        this.clear = async (strategyName) => {
+            this.loggerService.log("strategyGlobalService clear", {
+                strategyName,
+            });
+            return await this.strategyConnectionService.clear(strategyName);
+        };
     }
 }
 
@@ -2260,7 +2354,7 @@ class FrameSchemaService {
     register(key, value) {
         this.loggerService.log(`frameSchemaService register`, { key });
         this.validateShallow(value);
-        this._registry.register(key, value);
+        this._registry = this._registry.register(key, value);
     }
     /**
      * Overrides an existing frame schema with partial updates.
@@ -2271,7 +2365,8 @@ class FrameSchemaService {
      */
     override(key, value) {
         this.loggerService.log(`frameSchemaService override`, { key });
-        this._registry.override(key, value);
+        this._registry = this._registry.override(key, value);
+        return this._registry.get(key);
     }
     /**
      * Retrieves a frame schema by name.
@@ -2718,10 +2813,17 @@ let ReportStorage$1 = class ReportStorage {
             return str.newline(`# Backtest Report: ${strategyName}`, "", "No signals closed yet.");
         }
         const header = columns$1.map((col) => col.label);
+        const separator = columns$1.map(() => "---");
         const rows = this._signalList.map((closedSignal) => columns$1.map((col) => col.format(closedSignal)));
-        const tableData = [header, ...rows];
-        const table = str.table(tableData);
-        return str.newline(`# Backtest Report: ${strategyName}`, "", `Total signals: ${this._signalList.length}`, "", table, "", "", `*Generated: ${new Date().toISOString()}*`);
+        const tableData = [header, separator, ...rows];
+        const table = str.newline(tableData.map(row => `| ${row.join(" | ")} |`));
+        // Calculate statistics
+        const totalSignals = this._signalList.length;
+        const winCount = this._signalList.filter((s) => s.pnl.pnlPercentage > 0).length;
+        const lossCount = this._signalList.filter((s) => s.pnl.pnlPercentage < 0).length;
+        const avgPnl = this._signalList.reduce((sum, s) => sum + s.pnl.pnlPercentage, 0) / totalSignals;
+        const totalPnl = this._signalList.reduce((sum, s) => sum + s.pnl.pnlPercentage, 0);
+        return str.newline(`# Backtest Report: ${strategyName}`, "", table, "", `**Total signals:** ${totalSignals}`, `**Closed signals:** ${totalSignals}`, `**Win rate:** ${((winCount / totalSignals) * 100).toFixed(2)}% (${winCount}W / ${lossCount}L)`, `**Average PNL:** ${avgPnl > 0 ? "+" : ""}${avgPnl.toFixed(2)}%`, `**Total PNL:** ${totalPnl > 0 ? "+" : ""}${totalPnl.toFixed(2)}%`);
     }
     /**
      * Saves strategy report to disk.
@@ -3116,9 +3218,10 @@ class ReportStorage {
             return str.newline(`# Live Trading Report: ${strategyName}`, "", "No events recorded yet.");
         }
         const header = columns.map((col) => col.label);
+        const separator = columns.map(() => "---");
         const rows = this._eventList.map((event) => columns.map((col) => col.format(event)));
-        const tableData = [header, ...rows];
-        const table = str.table(tableData);
+        const tableData = [header, separator, ...rows];
+        const table = str.newline(tableData.map(row => `| ${row.join(" | ")} |`));
         // Calculate statistics
         const closedEvents = this._eventList.filter((e) => e.action === "closed");
         const totalClosed = closedEvents.length;
@@ -3127,11 +3230,14 @@ class ReportStorage {
         const avgPnl = totalClosed > 0
             ? closedEvents.reduce((sum, e) => sum + (e.pnl || 0), 0) / totalClosed
             : 0;
-        return str.newline(`# Live Trading Report: ${strategyName}`, "", `Total events: ${this._eventList.length}`, `Closed signals: ${totalClosed}`, totalClosed > 0
-            ? `Win rate: ${((winCount / totalClosed) * 100).toFixed(2)}% (${winCount}W / ${lossCount}L)`
+        const totalPnl = closedEvents.reduce((sum, e) => sum + (e.pnl || 0), 0);
+        return str.newline(`# Live Trading Report: ${strategyName}`, "", table, "", `**Total events:** ${this._eventList.length}`, `**Closed signals:** ${totalClosed}`, totalClosed > 0
+            ? `**Win rate:** ${((winCount / totalClosed) * 100).toFixed(2)}% (${winCount}W / ${lossCount}L)`
             : "", totalClosed > 0
-            ? `Average PNL: ${avgPnl > 0 ? "+" : ""}${avgPnl.toFixed(2)}%`
-            : "", "", table, "", "", `*Generated: ${new Date().toISOString()}*`);
+            ? `**Average PNL:** ${avgPnl > 0 ? "+" : ""}${avgPnl.toFixed(2)}%`
+            : "", totalClosed > 0
+            ? `**Total PNL:** ${totalPnl > 0 ? "+" : ""}${totalPnl.toFixed(2)}%`
+            : "");
     }
     /**
      * Saves strategy report to disk.
@@ -4162,6 +4268,7 @@ class BacktestUtils {
                 context,
             });
             backtest$1.backtestMarkdownService.clear(context.strategyName);
+            backtest$1.strategyGlobalService.clear(context.strategyName);
             return backtest$1.backtestGlobalService.run(symbol, context);
         };
         /**
@@ -4190,14 +4297,9 @@ class BacktestUtils {
                 symbol,
                 context,
             });
-            const iterator = this.run(symbol, context);
             let isStopped = false;
             const task = async () => {
-                while (true) {
-                    const { done } = await iterator.next();
-                    if (done) {
-                        break;
-                    }
+                for await (const _ of this.run(symbol, context)) {
                     if (isStopped) {
                         break;
                     }
@@ -4211,6 +4313,7 @@ class BacktestUtils {
             };
             task().catch((error) => errorEmitter.next(new Error(getErrorMessage(error))));
             return () => {
+                backtest$1.strategyGlobalService.stop(context.strategyName);
                 isStopped = true;
             };
         };
@@ -4327,6 +4430,7 @@ class LiveUtils {
                 context,
             });
             backtest$1.liveMarkdownService.clear(context.strategyName);
+            backtest$1.strategyGlobalService.clear(context.strategyName);
             return backtest$1.liveGlobalService.run(symbol, context);
         };
         /**
@@ -4355,19 +4459,10 @@ class LiveUtils {
                 symbol,
                 context,
             });
-            const iterator = this.run(symbol, context);
             let isStopped = false;
-            let lastValue = null;
             const task = async () => {
-                while (true) {
-                    const { value, done } = await iterator.next();
-                    if (value) {
-                        lastValue = value;
-                    }
-                    if (done) {
-                        break;
-                    }
-                    if (lastValue?.action === "closed" && isStopped) {
+                for await (const signal of this.run(symbol, context)) {
+                    if (signal?.action === "closed" && isStopped) {
                         break;
                     }
                 }
@@ -4380,6 +4475,7 @@ class LiveUtils {
             };
             task().catch((error) => errorEmitter.next(new Error(getErrorMessage(error))));
             return () => {
+                backtest$1.strategyGlobalService.stop(context.strategyName);
                 isStopped = true;
             };
         };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backtest-kit",
-  "version": "1.1.3",
+  "version": "1.1.4",
   "description": "A TypeScript library for trading system backtest",
   "author": {
     "name": "Petr Tripolsky",
@@ -39,6 +39,7 @@
   },
   "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 ./scripts/gpt-docs.mjs",
     "docs:uml": "npm run build && node ./scripts/uml.mjs",

package/types.d.ts

@@ -536,6 +536,27 @@ interface IStrategy {
      * @returns Promise resolving to closed result (always completes signal)
      */
     backtest: (candles: ICandleData[]) => Promise<IStrategyBacktestResult>;
+    /**
+     * Stops the strategy from generating new signals.
+     *
+     * Sets internal flag to prevent getSignal from being called on subsequent ticks.
+     * Does NOT force-close active pending signals - they continue monitoring until natural closure (TP/SL/time_expired).
+     *
+     * Use case: Graceful shutdown in live trading mode without abandoning open positions.
+     *
+     * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+     * @returns Promise that resolves immediately when stop flag is set
+     *
+     * @example
+     * ```typescript
+     * // Graceful shutdown in Live.background() cancellation
+     * const cancel = await Live.background("BTCUSDT", { ... });
+     *
+     * // Later: stop new signals, let existing ones close naturally
+     * await cancel();
+     * ```
+     */
+    stop: (symbol: string) => Promise<void>;
 }
 /**
  * Unique strategy identifier.
@@ -1737,6 +1758,25 @@ declare class StrategyConnectionService implements IStrategy {
      * @returns Promise resolving to backtest result (signal or idle)
      */
     backtest: (candles: ICandleData[]) => Promise<IStrategyBacktestResult>;
+    /**
+     * Stops the specified strategy from generating new signals.
+     *
+     * Delegates to ClientStrategy.stop() which sets internal flag to prevent
+     * getSignal from being called on subsequent ticks.
+     *
+     * @param strategyName - Name of strategy to stop
+     * @returns Promise that resolves when stop flag is set
+     */
+    stop: (strategyName: StrategyName) => Promise<void>;
+    /**
+     * Clears the memoized ClientStrategy instance from cache.
+     *
+     * Forces re-initialization of strategy on next getStrategy call.
+     * Useful for resetting strategy state or releasing resources.
+     *
+     * @param strategyName - Name of strategy to clear from cache
+     */
+    clear: (strategyName: StrategyName) => Promise<void>;
 }
 
 /**
@@ -1912,6 +1952,25 @@ declare class StrategyGlobalService {
      * @returns Closed signal result with PNL
      */
     backtest: (symbol: string, candles: ICandleData[], when: Date, backtest: boolean) => Promise<IStrategyBacktestResult>;
+    /**
+     * Stops the strategy from generating new signals.
+     *
+     * Delegates to StrategyConnectionService.stop() to set internal flag.
+     * Does not require execution context.
+     *
+     * @param strategyName - Name of strategy to stop
+     * @returns Promise that resolves when stop flag is set
+     */
+    stop: (strategyName: StrategyName) => Promise<void>;
+    /**
+     * Clears the memoized ClientStrategy instance from cache.
+     *
+     * Delegates to StrategyConnectionService.clear() to remove strategy from cache.
+     * Forces re-initialization of strategy on next operation.
+     *
+     * @param strategyName - Name of strategy to clear from cache
+     */
+    clear: (strategyName: StrategyName) => Promise<void>;
 }
 
 /**
@@ -2066,7 +2125,7 @@ declare class FrameSchemaService {
      * @param value - Partial schema updates
      * @throws Error if frame name doesn't exist
      */
-    override(key: FrameName, value: Partial<IFrameSchema>): void;
+    override(key: FrameName, value: Partial<IFrameSchema>): IFrameSchema;
     /**
      * Retrieves a frame schema by name.
      *