backtest-kit 3.4.2 → 3.5.1

package/build/index.cjs

@@ -733,7 +733,7 @@ async function writeFileAtomic(file, data, options = {}) {
     }
 }
 
-var _a$3;
+var _a$4;
 const BASE_WAIT_FOR_INIT_SYMBOL = Symbol("wait-for-init");
 // Calculate step in milliseconds for candle close time validation
 const INTERVAL_MINUTES$8 = {
@@ -856,7 +856,7 @@ class PersistBase {
     constructor(entityName, baseDir = path.join(process.cwd(), "logs/data")) {
         this.entityName = entityName;
         this.baseDir = baseDir;
-        this[_a$3] = functoolsKit.singleshot(async () => await BASE_WAIT_FOR_INIT_FN(this));
+        this[_a$4] = functoolsKit.singleshot(async () => await BASE_WAIT_FOR_INIT_FN(this));
         bt.loggerService.debug(PERSIST_BASE_METHOD_NAME_CTOR, {
             entityName: this.entityName,
             baseDir,
@@ -959,7 +959,7 @@ class PersistBase {
         }
     }
 }
-_a$3 = BASE_WAIT_FOR_INIT_SYMBOL;
+_a$4 = BASE_WAIT_FOR_INIT_SYMBOL;
 // @ts-ignore
 PersistBase = functoolsKit.makeExtendable(PersistBase);
 /**
@@ -2066,7 +2066,7 @@ class PersistLogUtils {
  */
 const PersistLogAdapter = new PersistLogUtils();
 
-var _a$2, _b$2;
+var _a$3, _b$3;
 const BUSY_DELAY = 100;
 const SET_BUSY_SYMBOL = Symbol("setBusy");
 const GET_BUSY_SYMBOL = Symbol("getBusy");
@@ -2081,8 +2081,8 @@ const ACQUIRE_LOCK_FN = async (self) => {
 class Lock {
     constructor() {
         this._isBusy = 0;
-        this[_a$2] = functoolsKit.queued(ACQUIRE_LOCK_FN);
-        this[_b$2] = () => this[SET_BUSY_SYMBOL](false);
+        this[_a$3] = functoolsKit.queued(ACQUIRE_LOCK_FN);
+        this[_b$3] = () => this[SET_BUSY_SYMBOL](false);
         this.acquireLock = async () => {
             await this[ACQUIRE_LOCK_SYMBOL](this);
         };
@@ -2100,7 +2100,7 @@ class Lock {
         return !!this._isBusy;
     }
 }
-_a$2 = ACQUIRE_LOCK_SYMBOL, _b$2 = RELEASE_LOCK_SYMBOL;
+_a$3 = ACQUIRE_LOCK_SYMBOL, _b$3 = RELEASE_LOCK_SYMBOL;
 
 const METHOD_NAME_ACQUIRE_LOCK = "CandleUtils.acquireLock";
 const METHOD_NAME_RELEASE_LOCK = "CandleUtils.releaseLock";
@@ -16096,7 +16096,7 @@ const COLUMN_CONFIG = {
  */
 const DEFAULT_COLUMNS = Object.freeze({ ...COLUMN_CONFIG });
 
-var _a$1, _b$1;
+var _a$2, _b$2;
 const MARKDOWN_METHOD_NAME_ENABLE = "MarkdownUtils.enable";
 const MARKDOWN_METHOD_NAME_DISABLE = "MarkdownUtils.disable";
 const MARKDOWN_METHOD_NAME_USE_ADAPTER = "MarkdownAdapter.useMarkdownAdapter";
@@ -16106,8 +16106,8 @@ const MARKDOWN_METHOD_NAME_WRITE_DATA = "MarkdownAdapter.writeData";
 const MARKDOWN_METHOD_NAME_USE_MD = "MarkdownAdapter.useMd";
 const MARKDOWN_METHOD_NAME_USE_JSONL = "MarkdownAdapter.useJsonl";
 const MARKDOWN_METHOD_NAME_USE_DUMMY = "MarkdownAdapter.useDummy";
-const WAIT_FOR_INIT_SYMBOL$1 = Symbol("wait-for-init");
-const WRITE_SAFE_SYMBOL$1 = Symbol("write-safe");
+const WAIT_FOR_INIT_SYMBOL$2 = Symbol("wait-for-init");
+const WRITE_SAFE_SYMBOL$2 = Symbol("write-safe");
 /**
  * Default configuration that enables all markdown services.
  * Used when no specific configuration is provided to `enable()`.
@@ -16157,7 +16157,7 @@ class MarkdownFileBase {
          * Protected by singleshot to ensure one-time execution.
          * Sets up error handler that emits to exitEmitter.
          */
-        this[_a$1] = functoolsKit.singleshot(async () => {
+        this[_a$2] = functoolsKit.singleshot(async () => {
             await fs__namespace.mkdir(this._baseDir, { recursive: true });
             this._stream = fs$1.createWriteStream(this._filePath, { flags: "a" });
             this._stream.on("error", (err) => {
@@ -16169,7 +16169,7 @@ class MarkdownFileBase {
          * Waits for drain event if write buffer is full.
          * Times out after 15 seconds and returns TIMEOUT_SYMBOL.
          */
-        this[_b$1] = functoolsKit.timeout(async (line) => {
+        this[_b$2] = functoolsKit.timeout(async (line) => {
             if (!this._stream.write(line)) {
                 await new Promise((resolve) => {
                     this._stream.once("drain", resolve);
@@ -16185,7 +16185,7 @@ class MarkdownFileBase {
      * @returns Promise that resolves when initialization is complete
      */
     async waitForInit() {
-        await this[WAIT_FOR_INIT_SYMBOL$1]();
+        await this[WAIT_FOR_INIT_SYMBOL$2]();
     }
     /**
      * Writes markdown content to JSONL file with metadata.
@@ -16231,13 +16231,13 @@ class MarkdownFileBase {
             ...searchFlags,
             timestamp: Date.now(),
         }) + "\n";
-        const status = await this[WRITE_SAFE_SYMBOL$1](line);
+        const status = await this[WRITE_SAFE_SYMBOL$2](line);
         if (status === functoolsKit.TIMEOUT_SYMBOL) {
             throw new Error(`Timeout writing to markdown ${this.markdownName}`);
         }
     }
 }
-_a$1 = WAIT_FOR_INIT_SYMBOL$1, _b$1 = WRITE_SAFE_SYMBOL$1;
+_a$2 = WAIT_FOR_INIT_SYMBOL$2, _b$2 = WRITE_SAFE_SYMBOL$2;
 //@ts-ignore
 MarkdownFileBase = functoolsKit.makeExtendable(MarkdownFileBase);
 /**
@@ -23256,7 +23256,7 @@ class ColumnValidationService {
     }
 }
 
-var _a, _b;
+var _a$1, _b$1;
 const REPORT_BASE_METHOD_NAME_CTOR = "ReportBase.CTOR";
 const REPORT_BASE_METHOD_NAME_WAIT_FOR_INIT = "ReportBase.waitForInit";
 const REPORT_BASE_METHOD_NAME_WRITE = "ReportBase.write";
@@ -23266,8 +23266,8 @@ const REPORT_UTILS_METHOD_NAME_ENABLE = "ReportUtils.enable";
 const REPORT_UTILS_METHOD_NAME_DISABLE = "ReportUtils.disable";
 const REPORT_UTILS_METHOD_NAME_USE_DUMMY = "ReportUtils.useDummy";
 const REPORT_UTILS_METHOD_NAME_USE_JSONL = "ReportUtils.useJsonl";
-const WAIT_FOR_INIT_SYMBOL = Symbol("wait-for-init");
-const WRITE_SAFE_SYMBOL = Symbol("write-safe");
+const WAIT_FOR_INIT_SYMBOL$1 = Symbol("wait-for-init");
+const WRITE_SAFE_SYMBOL$1 = Symbol("write-safe");
 /**
  * JSONL-based report adapter with append-only writes.
  *
@@ -23301,7 +23301,7 @@ class ReportBase {
          * Protected by singleshot to ensure one-time execution.
          * Sets up error handler that emits to exitEmitter.
          */
-        this[_a] = functoolsKit.singleshot(async () => {
+        this[_a$1] = functoolsKit.singleshot(async () => {
             await fs__namespace.mkdir(this.baseDir, { recursive: true });
             this._stream = fs$1.createWriteStream(this._filePath, { flags: "a" });
             this._stream.on("error", (err) => {
@@ -23313,7 +23313,7 @@ class ReportBase {
          * Waits for drain event if write buffer is full.
          * Times out after 15 seconds and returns TIMEOUT_SYMBOL.
          */
-        this[_b] = functoolsKit.timeout(async (line) => {
+        this[_b$1] = functoolsKit.timeout(async (line) => {
             if (!this._stream.write(line)) {
                 await new Promise((resolve) => {
                     this._stream.once("drain", resolve);
@@ -23338,7 +23338,7 @@ class ReportBase {
             reportName: this.reportName,
             initial,
         });
-        await this[WAIT_FOR_INIT_SYMBOL]();
+        await this[WAIT_FOR_INIT_SYMBOL$1]();
     }
     /**
      * Writes event data to JSONL file with metadata.
@@ -23385,13 +23385,13 @@ class ReportBase {
             ...searchFlags,
             timestamp: Date.now(),
         }) + "\n";
-        const status = await this[WRITE_SAFE_SYMBOL](line);
+        const status = await this[WRITE_SAFE_SYMBOL$1](line);
         if (status === functoolsKit.TIMEOUT_SYMBOL) {
             throw new Error(`Timeout writing to report ${this.reportName}`);
         }
     }
 }
-_a = WAIT_FOR_INIT_SYMBOL, _b = WRITE_SAFE_SYMBOL;
+_a$1 = WAIT_FOR_INIT_SYMBOL$1, _b$1 = WRITE_SAFE_SYMBOL$1;
 // @ts-ignore
 ReportBase = functoolsKit.makeExtendable(ReportBase);
 /**
@@ -31223,6 +31223,7 @@ async function dumpMessages(resultId, history, result, outputDir = "./dump/strat
     }
 }
 
+var _a, _b;
 const LOG_PERSIST_METHOD_NAME_WAIT_FOR_INIT = "LogPersistUtils.waitForInit";
 const LOG_PERSIST_METHOD_NAME_LOG = "LogPersistUtils.log";
 const LOG_PERSIST_METHOD_NAME_DEBUG = "LogPersistUtils.debug";
@@ -31238,17 +31239,47 @@ const LOG_ADAPTER_METHOD_NAME_USE_LOGGER = "LogAdapter.useLogger";
 const LOG_ADAPTER_METHOD_NAME_USE_PERSIST = "LogAdapter.usePersist";
 const LOG_ADAPTER_METHOD_NAME_USE_MEMORY = "LogAdapter.useMemory";
 const LOG_ADAPTER_METHOD_NAME_USE_DUMMY = "LogAdapter.useDummy";
+const LOG_ADAPTER_METHOD_NAME_USE_JSONL = "LogAdapter.useJsonl";
+const LOG_JSONL_METHOD_NAME_LOG = "LogJsonlUtils.log";
+const LOG_JSONL_METHOD_NAME_DEBUG = "LogJsonlUtils.debug";
+const LOG_JSONL_METHOD_NAME_INFO = "LogJsonlUtils.info";
+const LOG_JSONL_METHOD_NAME_WARN = "LogJsonlUtils.warn";
+const LOG_JSONL_METHOD_NAME_GET_LIST = "LogJsonlUtils.getList";
+const WAIT_FOR_INIT_SYMBOL = Symbol("wait-for-init");
+const WRITE_SAFE_SYMBOL = Symbol("write-safe");
 /**
  * Backtest execution time retrieval function.
  * Returns the 'when' timestamp from the execution context if available, otherwise returns the current time.
  * This allows log entries to be timestamped according to the backtest timeline rather than real-world time, improving log relevance and user experience during backtest analysis.
  */
-const GET_DATE_FN = async () => {
+const GET_DATE_FN = () => {
     if (ExecutionContextService.hasContext()) {
         return new Date(bt.executionContextService.context.when);
     }
     return new Date();
 };
+/**
+ * Method context retrieval function.
+ * Returns the current method context from MethodContextService if available, otherwise returns null.
+ * This allows log entries to include contextual information about the strategy, exchange, and frame associated with the log event, enhancing the ability to trace and analyze logs in relation to specific execution contexts within the backtest framework.
+ */
+const GET_METHOD_CONTEXT_FN = () => {
+    if (MethodContextService.hasContext()) {
+        return bt.methodContextService.context;
+    }
+    return null;
+};
+/**
+ * Execution context retrieval function.
+ * Returns the current execution context from ExecutionContextService if available, otherwise returns null.
+ * This allows log entries to include contextual information about the symbol, timestamp, and backtest mode associated with the log event, providing additional insights into the execution environment when analyzing logs.
+ */
+const GET_EXECUTION_CONTEXT_FN = () => {
+    if (ExecutionContextService.hasContext()) {
+        return bt.executionContextService.context;
+    }
+    return null;
+};
 /**
  * Persistent log adapter.
  *
@@ -31283,12 +31314,14 @@ class LogPersistUtils {
         this.log = async (topic, ...args) => {
             bt.loggerService.info(LOG_PERSIST_METHOD_NAME_LOG, { topic });
             await this.waitForInit();
-            const date = await GET_DATE_FN();
+            const date = GET_DATE_FN();
             this._entries.push({
                 id: functoolsKit.randomString(),
                 type: "log",
                 timestamp: Date.now(),
                 createdAt: date.toISOString(),
+                methodContext: GET_METHOD_CONTEXT_FN(),
+                executionContext: GET_EXECUTION_CONTEXT_FN(),
                 topic,
                 args,
             });
@@ -31304,12 +31337,14 @@ class LogPersistUtils {
         this.debug = async (topic, ...args) => {
             bt.loggerService.info(LOG_PERSIST_METHOD_NAME_DEBUG, { topic });
             await this.waitForInit();
-            const date = await GET_DATE_FN();
+            const date = GET_DATE_FN();
             this._entries.push({
                 id: functoolsKit.randomString(),
                 type: "debug",
                 timestamp: Date.now(),
                 createdAt: date.toISOString(),
+                methodContext: GET_METHOD_CONTEXT_FN(),
+                executionContext: GET_EXECUTION_CONTEXT_FN(),
                 topic,
                 args,
             });
@@ -31325,12 +31360,14 @@ class LogPersistUtils {
         this.info = async (topic, ...args) => {
             bt.loggerService.info(LOG_PERSIST_METHOD_NAME_INFO, { topic });
             await this.waitForInit();
-            const date = await GET_DATE_FN();
+            const date = GET_DATE_FN();
             this._entries.push({
                 id: functoolsKit.randomString(),
                 type: "info",
                 timestamp: Date.now(),
                 createdAt: date.toISOString(),
+                methodContext: GET_METHOD_CONTEXT_FN(),
+                executionContext: GET_EXECUTION_CONTEXT_FN(),
                 topic,
                 args,
             });
@@ -31346,12 +31383,14 @@ class LogPersistUtils {
         this.warn = async (topic, ...args) => {
             bt.loggerService.info(LOG_PERSIST_METHOD_NAME_WARN, { topic });
             await this.waitForInit();
-            const date = await GET_DATE_FN();
+            const date = GET_DATE_FN();
             this._entries.push({
                 id: functoolsKit.randomString(),
                 type: "warn",
                 timestamp: Date.now(),
                 createdAt: date.toISOString(),
+                methodContext: GET_METHOD_CONTEXT_FN(),
+                executionContext: GET_EXECUTION_CONTEXT_FN(),
                 topic,
                 args,
             });
@@ -31400,12 +31439,14 @@ class LogMemoryUtils {
          */
         this.log = async (topic, ...args) => {
             bt.loggerService.info(LOG_MEMORY_METHOD_NAME_LOG, { topic });
-            const date = await GET_DATE_FN();
+            const date = GET_DATE_FN();
             this._entries.push({
                 id: functoolsKit.randomString(),
                 type: "log",
                 timestamp: Date.now(),
                 createdAt: date.toISOString(),
+                methodContext: GET_METHOD_CONTEXT_FN(),
+                executionContext: GET_EXECUTION_CONTEXT_FN(),
                 topic,
                 args,
             });
@@ -31419,12 +31460,14 @@ class LogMemoryUtils {
          */
         this.debug = async (topic, ...args) => {
             bt.loggerService.info(LOG_MEMORY_METHOD_NAME_DEBUG, { topic });
-            const date = await GET_DATE_FN();
+            const date = GET_DATE_FN();
             this._entries.push({
                 id: functoolsKit.randomString(),
                 type: "debug",
                 timestamp: Date.now(),
                 createdAt: date.toISOString(),
+                methodContext: GET_METHOD_CONTEXT_FN(),
+                executionContext: GET_EXECUTION_CONTEXT_FN(),
                 topic,
                 args,
             });
@@ -31438,12 +31481,14 @@ class LogMemoryUtils {
          */
         this.info = async (topic, ...args) => {
             bt.loggerService.info(LOG_MEMORY_METHOD_NAME_INFO, { topic });
-            const date = await GET_DATE_FN();
+            const date = GET_DATE_FN();
             this._entries.push({
                 id: functoolsKit.randomString(),
                 type: "info",
                 timestamp: Date.now(),
                 createdAt: date.toISOString(),
+                methodContext: GET_METHOD_CONTEXT_FN(),
+                executionContext: GET_EXECUTION_CONTEXT_FN(),
                 topic,
                 args,
             });
@@ -31457,12 +31502,14 @@ class LogMemoryUtils {
          */
         this.warn = async (topic, ...args) => {
             bt.loggerService.info(LOG_MEMORY_METHOD_NAME_WARN, { topic });
-            const date = await GET_DATE_FN();
+            const date = GET_DATE_FN();
             this._entries.push({
                 id: functoolsKit.randomString(),
                 type: "warn",
                 timestamp: Date.now(),
                 createdAt: date.toISOString(),
+                methodContext: GET_METHOD_CONTEXT_FN(),
+                executionContext: GET_EXECUTION_CONTEXT_FN(),
                 topic,
                 args,
             });
@@ -31486,6 +31533,165 @@ class LogMemoryUtils {
         }
     }
 }
+/**
+ * JSONL-based log adapter with append-only writes and file-based reads.
+ *
+ * Features:
+ * - Writes log entries as JSONL lines via WriteStream (append-only)
+ * - Stream-based writes with backpressure handling
+ * - 15-second timeout protection for write operations
+ * - Automatic directory creation on first write
+ * - Error handling via exitEmitter
+ * - getList reads and parses all lines from the JSONL file
+ *
+ * File format: {dirName}/{fileName}.jsonl
+ * Each line contains a full ILogEntry object.
+ */
+class LogJsonlUtils {
+    /**
+     * Creates a new JSONL log adapter instance.
+     *
+     * @param fileName - Base file name (without extension)
+     * @param dirName - Directory path for the JSONL file
+     */
+    constructor(fileName, dirName) {
+        this.fileName = fileName;
+        this.dirName = dirName;
+        /** WriteStream instance for append-only writes, null until initialized */
+        this._stream = null;
+        /**
+         * Singleshot initialization: creates directory and opens append stream.
+         * Sets up error handler that emits to exitEmitter.
+         */
+        this[_a] = functoolsKit.singleshot(async () => {
+            await fs__namespace.mkdir(this.dirName, { recursive: true });
+            this._stream = fs$1.createWriteStream(this._filePath, { flags: "a" });
+            this._stream.on("error", (err) => {
+                exitEmitter.next(new Error(`LogJsonlUtils stream error for file=${this._filePath} message=${functoolsKit.getErrorMessage(err)}`));
+            });
+        });
+        /**
+         * Timeout-protected write with backpressure handling.
+         * Waits for drain event if write buffer is full.
+         * Times out after 15 seconds and returns TIMEOUT_SYMBOL.
+         */
+        this[_b] = functoolsKit.timeout(async (line) => {
+            if (!this._stream.write(line)) {
+                await new Promise((resolve) => {
+                    this._stream.once("drain", resolve);
+                });
+            }
+        }, 15000);
+        /**
+         * Appends a log entry as a JSONL line.
+         */
+        this._append = async (entry) => {
+            await this[WAIT_FOR_INIT_SYMBOL]();
+            const line = JSON.stringify(entry) + "\n";
+            const status = await this[WRITE_SAFE_SYMBOL](line);
+            if (status === functoolsKit.TIMEOUT_SYMBOL) {
+                throw new Error(`LogJsonlUtils timeout writing to file=${this._filePath}`);
+            }
+        };
+        /**
+         * Logs a general-purpose message.
+         * @param topic - The log topic / method name
+         * @param args - Additional arguments
+         */
+        this.log = async (topic, ...args) => {
+            bt.loggerService.info(LOG_JSONL_METHOD_NAME_LOG, { topic });
+            const date = GET_DATE_FN();
+            await this._append({
+                id: functoolsKit.randomString(),
+                type: "log",
+                timestamp: Date.now(),
+                createdAt: date.toISOString(),
+                methodContext: GET_METHOD_CONTEXT_FN(),
+                executionContext: GET_EXECUTION_CONTEXT_FN(),
+                topic,
+                args,
+            });
+        };
+        /**
+         * Logs a debug-level message.
+         * @param topic - The log topic / method name
+         * @param args - Additional arguments
+         */
+        this.debug = async (topic, ...args) => {
+            bt.loggerService.info(LOG_JSONL_METHOD_NAME_DEBUG, { topic });
+            const date = GET_DATE_FN();
+            await this._append({
+                id: functoolsKit.randomString(),
+                type: "debug",
+                timestamp: Date.now(),
+                createdAt: date.toISOString(),
+                methodContext: GET_METHOD_CONTEXT_FN(),
+                executionContext: GET_EXECUTION_CONTEXT_FN(),
+                topic,
+                args,
+            });
+        };
+        /**
+         * Logs an info-level message.
+         * @param topic - The log topic / method name
+         * @param args - Additional arguments
+         */
+        this.info = async (topic, ...args) => {
+            bt.loggerService.info(LOG_JSONL_METHOD_NAME_INFO, { topic });
+            const date = GET_DATE_FN();
+            await this._append({
+                id: functoolsKit.randomString(),
+                type: "info",
+                timestamp: Date.now(),
+                createdAt: date.toISOString(),
+                methodContext: GET_METHOD_CONTEXT_FN(),
+                executionContext: GET_EXECUTION_CONTEXT_FN(),
+                topic,
+                args,
+            });
+        };
+        /**
+         * Logs a warning-level message.
+         * @param topic - The log topic / method name
+         * @param args - Additional arguments
+         */
+        this.warn = async (topic, ...args) => {
+            bt.loggerService.info(LOG_JSONL_METHOD_NAME_WARN, { topic });
+            const date = GET_DATE_FN();
+            await this._append({
+                id: functoolsKit.randomString(),
+                type: "warn",
+                timestamp: Date.now(),
+                createdAt: date.toISOString(),
+                methodContext: GET_METHOD_CONTEXT_FN(),
+                executionContext: GET_EXECUTION_CONTEXT_FN(),
+                topic,
+                args,
+            });
+        };
+        /**
+         * Reads all log entries from the JSONL file.
+         * Returns empty array if file does not exist.
+         * @returns Array of all log entries
+         */
+        this.getList = async () => {
+            bt.loggerService.info(LOG_JSONL_METHOD_NAME_GET_LIST);
+            let raw;
+            try {
+                raw = await fs__namespace.readFile(this._filePath, "utf-8");
+            }
+            catch {
+                return [];
+            }
+            return raw
+                .split("\n")
+                .filter((line) => line.trim().length > 0)
+                .map((line) => JSON.parse(line));
+        };
+        this._filePath = path.join(this.dirName, this.fileName);
+    }
+}
+_a = WAIT_FOR_INIT_SYMBOL, _b = WRITE_SAFE_SYMBOL;
 /**
  * Dummy log adapter that discards all writes.
  *
@@ -31625,6 +31831,18 @@ class LogAdapter {
             bt.loggerService.info(LOG_ADAPTER_METHOD_NAME_USE_DUMMY);
             this._log = new LogDummyUtils();
         };
+        /**
+         * Switches to JSONL file log adapter.
+         * Log entries will be appended to {dirName}/{fileName}.jsonl.
+         * Reads are performed by parsing all lines from the file.
+         *
+         * @param fileName - Base file name without extension (default: "log")
+         * @param dirName - Directory for the JSONL file (default: ./dump/log)
+         */
+        this.useJsonl = (fileName = "log.jsonl", dirName = path.join(process.cwd(), "./dump/log")) => {
+            bt.loggerService.info(LOG_ADAPTER_METHOD_NAME_USE_JSONL);
+            this._log = new LogJsonlUtils(fileName, dirName);
+        };
     }
 }
 /**