backtest-kit 1.1.3 → 1.1.5

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,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 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();
+/**
+ * Progress emitter for backtest execution progress.
+ * Emits progress updates during backtest execution.
+ */
+const progressEmitter = new Subject();
+
 const INTERVAL_MINUTES$1 = {
     "1m": 1,
     "3m": 3,
@@ -1153,6 +1184,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 +1215,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 +1280,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 +1603,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 +1727,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 +2100,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 +2359,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 +2370,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.
@@ -2305,6 +2405,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.
@@ -2325,9 +2426,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") {
@@ -2364,6 +2477,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,
+            });
+        }
     }
 }
 
@@ -2718,10 +2842,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 +3247,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 +3259,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)}%`
             : "", 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.
@@ -3371,6 +3506,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());
+        };
     }
 }
 
@@ -3423,6 +3567,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());
+        };
     }
 }
 
@@ -3475,6 +3628,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());
+        };
     }
 }
 
@@ -3720,6 +3882,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";
@@ -3729,6 +3987,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.
  *
@@ -3984,6 +4243,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(queued(async (event) => fn(event)));
+}
 
 const GET_CANDLES_METHOD_NAME = "exchange.getCandles";
 const GET_AVERAGE_PRICE_METHOD_NAME = "exchange.getAveragePrice";
@@ -4162,6 +4455,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 +4484,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 +4500,7 @@ class BacktestUtils {
             };
             task().catch((error) => errorEmitter.next(new Error(getErrorMessage(error))));
             return () => {
+                backtest$1.strategyGlobalService.stop(context.strategyName);
                 isStopped = true;
             };
         };
@@ -4327,6 +4617,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 +4646,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 +4662,7 @@ class LiveUtils {
             };
             task().catch((error) => errorEmitter.next(new Error(getErrorMessage(error))));
             return () => {
+                backtest$1.strategyGlobalService.stop(context.strategyName);
                 isStopped = true;
             };
         };
@@ -4442,4 +4725,4 @@ class LiveUtils {
  */
 const Live = new LiveUtils();
 
-export { Backtest, ExecutionContextService, Live, MethodContextService, PersistBase, PersistSignalAdaper, addExchange, addFrame, addStrategy, formatPrice, formatQuantity, getAveragePrice, getCandles, getDate, getMode, backtest as lib, listenDone, listenDoneOnce, listenError, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, setLogger };
+export { Backtest, ExecutionContextService, Live, MethodContextService, PersistBase, PersistSignalAdaper, addExchange, addFrame, addStrategy, formatPrice, formatQuantity, getAveragePrice, getCandles, getDate, getMode, backtest as lib, listExchanges, listFrames, listStrategies, listenDone, listenDoneOnce, listenError, listenProgress, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, setLogger };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backtest-kit",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "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",