backtest-kit 1.1.3 → 1.1.5

package/build/index.cjs

@@ -1104,6 +1104,37 @@ 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();
+/**
+ * Progress emitter for backtest execution progress.
+ * Emits progress updates during backtest execution.
+ */
+const progressEmitter = new functoolsKit.Subject();
+
 const INTERVAL_MINUTES$1 = {
     "1m": 1,
     "3m": 3,
@@ -1155,6 +1186,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 +1217,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 +1282,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 +1605,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 +1729,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 +2102,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 +2361,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 +2372,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.
@@ -2307,6 +2407,7 @@ class BacktestLogicPrivateService {
         this.strategyGlobalService = inject(TYPES.strategyGlobalService);
         this.exchangeGlobalService = inject(TYPES.exchangeGlobalService);
         this.frameGlobalService = inject(TYPES.frameGlobalService);
+        this.methodContextService = inject(TYPES.methodContextService);
     }
     /**
      * Runs backtest for a symbol, streaming closed signals as async generator.
@@ -2327,9 +2428,21 @@ class BacktestLogicPrivateService {
             symbol,
         });
         const timeframes = await this.frameGlobalService.getTimeframe(symbol);
+        const totalFrames = timeframes.length;
         let i = 0;
         while (i < timeframes.length) {
             const when = timeframes[i];
+            // Emit progress event if context is available
+            {
+                await progressEmitter.next({
+                    exchangeName: this.methodContextService.context.exchangeName,
+                    strategyName: this.methodContextService.context.strategyName,
+                    symbol,
+                    totalFrames,
+                    processedFrames: i,
+                    progress: totalFrames > 0 ? i / totalFrames : 0,
+                });
+            }
             const result = await this.strategyGlobalService.tick(symbol, when, true);
             // Если сигнал открыт, вызываем backtest
             if (result.action === "opened") {
@@ -2366,6 +2479,17 @@ class BacktestLogicPrivateService {
             }
             i++;
         }
+        // Emit final progress event (100%)
+        {
+            await progressEmitter.next({
+                exchangeName: this.methodContextService.context.exchangeName,
+                strategyName: this.methodContextService.context.strategyName,
+                symbol,
+                totalFrames,
+                processedFrames: totalFrames,
+                progress: 1.0,
+            });
+        }
     }
 }
 
@@ -2720,10 +2844,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 +3249,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 +3261,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)}%`
             : "", totalClosed > 0
-            ? `Average PNL: ${avgPnl > 0 ? "+" : ""}${avgPnl.toFixed(2)}%`
-            : "", "", table, "", "", `*Generated: ${new Date().toISOString()}*`);
+            ? `**Total PNL:** ${totalPnl > 0 ? "+" : ""}${totalPnl.toFixed(2)}%`
+            : "");
     }
     /**
      * Saves strategy report to disk.
@@ -3373,6 +3508,15 @@ class ExchangeValidationService {
             }
             return true;
         });
+        /**
+         * Returns a list of all registered exchange schemas
+         * @public
+         * @returns Array of exchange schemas with their configurations
+         */
+        this.list = async () => {
+            this.loggerService.log("exchangeValidationService list");
+            return Array.from(this._exchangeMap.values());
+        };
     }
 }
 
@@ -3425,6 +3569,15 @@ class StrategyValidationService {
             }
             return true;
         });
+        /**
+         * Returns a list of all registered strategy schemas
+         * @public
+         * @returns Array of strategy schemas with their configurations
+         */
+        this.list = async () => {
+            this.loggerService.log("strategyValidationService list");
+            return Array.from(this._strategyMap.values());
+        };
     }
 }
 
@@ -3477,6 +3630,15 @@ class FrameValidationService {
             }
             return true;
         });
+        /**
+         * Returns a list of all registered frame schemas
+         * @public
+         * @returns Array of frame schemas with their configurations
+         */
+        this.list = async () => {
+            this.loggerService.log("frameValidationService list");
+            return Array.from(this._frameMap.values());
+        };
     }
 }
 
@@ -3722,6 +3884,102 @@ function addFrame(frameSchema) {
     backtest$1.frameSchemaService.register(frameSchema.frameName, frameSchema);
 }
 
+const LIST_EXCHANGES_METHOD_NAME = "list.listExchanges";
+const LIST_STRATEGIES_METHOD_NAME = "list.listStrategies";
+const LIST_FRAMES_METHOD_NAME = "list.listFrames";
+/**
+ * Returns a list of all registered exchange schemas.
+ *
+ * Retrieves all exchanges that have been registered via addExchange().
+ * Useful for debugging, documentation, or building dynamic UIs.
+ *
+ * @returns Array of exchange schemas with their configurations
+ *
+ * @example
+ * ```typescript
+ * import { listExchanges, addExchange } from "backtest-kit";
+ *
+ * addExchange({
+ *   exchangeName: "binance",
+ *   note: "Binance cryptocurrency exchange",
+ *   getCandles: async (symbol, interval, since, limit) => [...],
+ *   formatPrice: async (symbol, price) => price.toFixed(2),
+ *   formatQuantity: async (symbol, quantity) => quantity.toFixed(8),
+ * });
+ *
+ * const exchanges = listExchanges();
+ * console.log(exchanges);
+ * // [{ exchangeName: "binance", note: "Binance cryptocurrency exchange", ... }]
+ * ```
+ */
+async function listExchanges() {
+    backtest$1.loggerService.log(LIST_EXCHANGES_METHOD_NAME);
+    return await backtest$1.exchangeValidationService.list();
+}
+/**
+ * Returns a list of all registered strategy schemas.
+ *
+ * Retrieves all strategies that have been registered via addStrategy().
+ * Useful for debugging, documentation, or building dynamic UIs.
+ *
+ * @returns Array of strategy schemas with their configurations
+ *
+ * @example
+ * ```typescript
+ * import { listStrategies, addStrategy } from "backtest-kit";
+ *
+ * addStrategy({
+ *   strategyName: "my-strategy",
+ *   note: "Simple moving average crossover strategy",
+ *   interval: "5m",
+ *   getSignal: async (symbol) => ({
+ *     position: "long",
+ *     priceOpen: 50000,
+ *     priceTakeProfit: 51000,
+ *     priceStopLoss: 49000,
+ *     minuteEstimatedTime: 60,
+ *   }),
+ * });
+ *
+ * const strategies = listStrategies();
+ * console.log(strategies);
+ * // [{ strategyName: "my-strategy", note: "Simple moving average...", ... }]
+ * ```
+ */
+async function listStrategies() {
+    backtest$1.loggerService.log(LIST_STRATEGIES_METHOD_NAME);
+    return await backtest$1.strategyValidationService.list();
+}
+/**
+ * Returns a list of all registered frame schemas.
+ *
+ * Retrieves all frames that have been registered via addFrame().
+ * Useful for debugging, documentation, or building dynamic UIs.
+ *
+ * @returns Array of frame schemas with their configurations
+ *
+ * @example
+ * ```typescript
+ * import { listFrames, addFrame } from "backtest-kit";
+ *
+ * addFrame({
+ *   frameName: "1d-backtest",
+ *   note: "One day backtest period for testing",
+ *   interval: "1m",
+ *   startDate: new Date("2024-01-01T00:00:00Z"),
+ *   endDate: new Date("2024-01-02T00:00:00Z"),
+ * });
+ *
+ * const frames = listFrames();
+ * console.log(frames);
+ * // [{ frameName: "1d-backtest", note: "One day backtest...", ... }]
+ * ```
+ */
+async function listFrames() {
+    backtest$1.loggerService.log(LIST_FRAMES_METHOD_NAME);
+    return await backtest$1.frameValidationService.list();
+}
+
 const LISTEN_SIGNAL_METHOD_NAME = "event.listenSignal";
 const LISTEN_SIGNAL_ONCE_METHOD_NAME = "event.listenSignalOnce";
 const LISTEN_SIGNAL_LIVE_METHOD_NAME = "event.listenSignalLive";
@@ -3731,6 +3989,7 @@ const LISTEN_SIGNAL_BACKTEST_ONCE_METHOD_NAME = "event.listenSignalBacktestOnce"
 const LISTEN_ERROR_METHOD_NAME = "event.listenError";
 const LISTEN_DONE_METHOD_NAME = "event.listenDone";
 const LISTEN_DONE_ONCE_METHOD_NAME = "event.listenDoneOnce";
+const LISTEN_PROGRESS_METHOD_NAME = "event.listenProgress";
 /**
  * Subscribes to all signal events with queued async processing.
  *
@@ -3986,6 +4245,40 @@ function listenDoneOnce(filterFn, fn) {
     backtest$1.loggerService.log(LISTEN_DONE_ONCE_METHOD_NAME);
     return doneEmitter.filter(filterFn).once(fn);
 }
+/**
+ * Subscribes to backtest progress events with queued async processing.
+ *
+ * Emits during Backtest.background() execution to track progress.
+ * Events are processed sequentially in order received, even if callback is async.
+ * Uses queued wrapper to prevent concurrent execution of the callback.
+ *
+ * @param fn - Callback function to handle progress events
+ * @returns Unsubscribe function to stop listening to events
+ *
+ * @example
+ * ```typescript
+ * import { listenProgress, Backtest } from "backtest-kit";
+ *
+ * const unsubscribe = listenProgress((event) => {
+ *   console.log(`Progress: ${(event.progress * 100).toFixed(2)}%`);
+ *   console.log(`${event.processedFrames} / ${event.totalFrames} frames`);
+ *   console.log(`Strategy: ${event.strategyName}, Symbol: ${event.symbol}`);
+ * });
+ *
+ * Backtest.background("BTCUSDT", {
+ *   strategyName: "my-strategy",
+ *   exchangeName: "binance",
+ *   frameName: "1d-backtest"
+ * });
+ *
+ * // Later: stop listening
+ * unsubscribe();
+ * ```
+ */
+function listenProgress(fn) {
+    backtest$1.loggerService.log(LISTEN_PROGRESS_METHOD_NAME);
+    return progressEmitter.subscribe(functoolsKit.queued(async (event) => fn(event)));
+}
 
 const GET_CANDLES_METHOD_NAME = "exchange.getCandles";
 const GET_AVERAGE_PRICE_METHOD_NAME = "exchange.getAveragePrice";
@@ -4164,6 +4457,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 +4486,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 +4502,7 @@ class BacktestUtils {
             };
             task().catch((error) => errorEmitter.next(new Error(functoolsKit.getErrorMessage(error))));
             return () => {
+                backtest$1.strategyGlobalService.stop(context.strategyName);
                 isStopped = true;
             };
         };
@@ -4329,6 +4619,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 +4648,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 +4664,7 @@ class LiveUtils {
             };
             task().catch((error) => errorEmitter.next(new Error(functoolsKit.getErrorMessage(error))));
             return () => {
+                backtest$1.strategyGlobalService.stop(context.strategyName);
                 isStopped = true;
             };
         };
@@ -4460,9 +4743,13 @@ exports.getCandles = getCandles;
 exports.getDate = getDate;
 exports.getMode = getMode;
 exports.lib = backtest;
+exports.listExchanges = listExchanges;
+exports.listFrames = listFrames;
+exports.listStrategies = listStrategies;
 exports.listenDone = listenDone;
 exports.listenDoneOnce = listenDoneOnce;
 exports.listenError = listenError;
+exports.listenProgress = listenProgress;
 exports.listenSignal = listenSignal;
 exports.listenSignalBacktest = listenSignalBacktest;
 exports.listenSignalBacktestOnce = listenSignalBacktestOnce;