backtest-kit 3.3.2 → 3.4.1

package/README.md

@@ -487,6 +487,28 @@ npm install @backtest-kit/pinets pinets backtest-kit
 ```
 
 
+### @backtest-kit/graph
+
+> **[Explore on NPM](https://www.npmjs.com/package/@backtest-kit/graph)** 🔗
+
+The **@backtest-kit/graph** package lets you compose backtest-kit computations as a typed directed acyclic graph (DAG). Define source nodes that fetch market data and output nodes that compute derived values — then resolve the whole graph in topological order with automatic parallelism.
+
+#### Key Features
+- 🔌 **DAG Execution**: Nodes are resolved bottom-up in topological order with `Promise.all` parallelism
+- 🔒 **Type-Safe Values**: TypeScript infers the return type of every node through the graph via generics
+- 🧱 **Two APIs**: Low-level `INode` for runtime/storage, high-level `sourceNode` + `outputNode` builders for authoring
+- 💾 **DB-Ready Serialization**: `serialize` / `deserialize` convert the graph to a flat `IFlatNode[]` list with `id` / `nodeIds`
+- 🌐 **Context-Aware Fetch**: `sourceNode` receives `(symbol, when, exchangeName)` from the execution context automatically
+
+#### Use Case
+Perfect for multi-timeframe strategies where multiple Pine Script or indicator computations must be combined. Instead of manually chaining async calls, define each computation as a node and let the graph resolve dependencies in parallel. Adding a new filter or timeframe requires no changes to the existing wiring.
+
+#### Get Started
+```bash
+npm install @backtest-kit/graph backtest-kit
+```
+
+
 ### @backtest-kit/ui
 
 > **[Explore on NPM](https://www.npmjs.com/package/@backtest-kit/ui)** 📊
@@ -556,28 +578,6 @@ npm install @backtest-kit/signals backtest-kit
 
 
 
-### @backtest-kit/graph
-
-> **[Explore on NPM](https://www.npmjs.com/package/@backtest-kit/graph)** 🔗
-
-The **@backtest-kit/graph** package lets you compose backtest-kit computations as a typed directed acyclic graph (DAG). Define source nodes that fetch market data and output nodes that compute derived values — then resolve the whole graph in topological order with automatic parallelism.
-
-#### Key Features
-- 🔌 **DAG Execution**: Nodes are resolved bottom-up in topological order with `Promise.all` parallelism
-- 🔒 **Type-Safe Values**: TypeScript infers the return type of every node through the graph via generics
-- 🧱 **Two APIs**: Low-level `INode` for runtime/storage, high-level `sourceNode` + `outputNode` builders for authoring
-- 💾 **DB-Ready Serialization**: `serialize` / `deserialize` convert the graph to a flat `IFlatNode[]` list with `id` / `nodeIds`
-- 🌐 **Context-Aware Fetch**: `sourceNode` receives `(symbol, when, exchangeName)` from the execution context automatically
-
-#### Use Case
-Perfect for multi-timeframe strategies where multiple Pine Script or indicator computations must be combined. Instead of manually chaining async calls, define each computation as a node and let the graph resolve dependencies in parallel. Adding a new filter or timeframe requires no changes to the existing wiring.
-
-#### Get Started
-```bash
-npm install @backtest-kit/graph backtest-kit
-```
-
-
 ### @backtest-kit/sidekick
 
 > **[Explore on NPM](https://www.npmjs.com/package/@backtest-kit/sidekick)** 🚀

package/build/index.cjs

@@ -442,6 +442,14 @@ const GLOBAL_CONFIG = {
      * Default: 50 signals
      */
     CC_MAX_SIGNALS: 50,
+    /**
+     * Maximum number of log lines to keep in storage.
+     * Older log lines are removed when this limit is exceeded.
+     * This helps prevent unbounded log growth which can consume memory and degrade performance over time.
+     *
+     * Default: 1000 log lines
+     */
+    CC_MAX_LOG_LINES: 1000,
     /**
      * Enables mutex locking for candle fetching to prevent concurrent fetches of the same candles.
      * This can help avoid redundant API calls and ensure data consistency when multiple processes/threads attempt to fetch candles simultaneously.
@@ -776,6 +784,11 @@ const PERSIST_NOTIFICATION_UTILS_METHOD_NAME_WRITE_DATA = "PersistNotificationUt
 const PERSIST_NOTIFICATION_UTILS_METHOD_NAME_USE_JSON = "PersistNotificationUtils.useJson";
 const PERSIST_NOTIFICATION_UTILS_METHOD_NAME_USE_DUMMY = "PersistNotificationUtils.useDummy";
 const PERSIST_NOTIFICATION_UTILS_METHOD_NAME_USE_PERSIST_NOTIFICATION_ADAPTER = "PersistNotificationUtils.usePersistNotificationAdapter";
+const PERSIST_LOG_UTILS_METHOD_NAME_READ_DATA = "PersistLogUtils.readLogData";
+const PERSIST_LOG_UTILS_METHOD_NAME_WRITE_DATA = "PersistLogUtils.writeLogData";
+const PERSIST_LOG_UTILS_METHOD_NAME_USE_JSON = "PersistLogUtils.useJson";
+const PERSIST_LOG_UTILS_METHOD_NAME_USE_DUMMY = "PersistLogUtils.useDummy";
+const PERSIST_LOG_UTILS_METHOD_NAME_USE_PERSIST_LOG_ADAPTER = "PersistLogUtils.usePersistLogAdapter";
 const BASE_WAIT_FOR_INIT_FN_METHOD_NAME = "PersistBase.waitForInitFn";
 const BASE_UNLINK_RETRY_COUNT = 5;
 const BASE_UNLINK_RETRY_DELAY = 1000;
@@ -1946,6 +1959,106 @@ class PersistNotificationUtils {
  * Used by NotificationPersistLiveUtils/NotificationPersistBacktestUtils for notification persistence.
  */
 const PersistNotificationAdapter = new PersistNotificationUtils();
+/**
+ * Utility class for managing log entry persistence.
+ *
+ * Features:
+ * - Memoized storage instance
+ * - Custom adapter support
+ * - Atomic read/write operations for LogData
+ * - Each log entry stored as separate file keyed by id
+ * - Crash-safe log state management
+ *
+ * Used by LogPersistUtils for log entry persistence.
+ */
+class PersistLogUtils {
+    constructor() {
+        this.PersistLogFactory = PersistBase;
+        this._logStorage = null;
+        /**
+         * Reads persisted log entries.
+         *
+         * Called by LogPersistUtils.waitForInit() to restore state.
+         * Uses keys() from PersistBase to iterate over all stored entries.
+         * Returns empty array if no entries exist.
+         *
+         * @returns Promise resolving to array of log entries
+         */
+        this.readLogData = async () => {
+            bt.loggerService.info(PERSIST_LOG_UTILS_METHOD_NAME_READ_DATA);
+            const isInitial = !this._logStorage;
+            const stateStorage = this.getLogStorage();
+            await stateStorage.waitForInit(isInitial);
+            const entries = [];
+            for await (const entryId of stateStorage.keys()) {
+                const entry = await stateStorage.readValue(entryId);
+                entries.push(entry);
+            }
+            return entries;
+        };
+        /**
+         * Writes log entries to disk with atomic file writes.
+         *
+         * Called by LogPersistUtils after each log call to persist state.
+         * Uses entry.id as the storage key for individual file storage.
+         * Uses atomic writes to prevent corruption on crashes.
+         *
+         * @param logData - Log entries to persist
+         * @returns Promise that resolves when write is complete
+         */
+        this.writeLogData = async (logData) => {
+            bt.loggerService.info(PERSIST_LOG_UTILS_METHOD_NAME_WRITE_DATA);
+            const isInitial = !this._logStorage;
+            const stateStorage = this.getLogStorage();
+            await stateStorage.waitForInit(isInitial);
+            for (const entry of logData) {
+                if (await stateStorage.hasValue(entry.id)) {
+                    continue;
+                }
+                await stateStorage.writeValue(entry.id, entry);
+            }
+        };
+    }
+    getLogStorage() {
+        if (!this._logStorage) {
+            this._logStorage = Reflect.construct(this.PersistLogFactory, [
+                `log`,
+                `./dump/data/log/`,
+            ]);
+        }
+        return this._logStorage;
+    }
+    /**
+     * Registers a custom persistence adapter.
+     *
+     * @param Ctor - Custom PersistBase constructor
+     */
+    usePersistLogAdapter(Ctor) {
+        bt.loggerService.info(PERSIST_LOG_UTILS_METHOD_NAME_USE_PERSIST_LOG_ADAPTER);
+        this.PersistLogFactory = Ctor;
+    }
+    /**
+     * Switches to the default JSON persist adapter.
+     * All future persistence writes will use JSON storage.
+     */
+    useJson() {
+        bt.loggerService.log(PERSIST_LOG_UTILS_METHOD_NAME_USE_JSON);
+        this.usePersistLogAdapter(PersistBase);
+    }
+    /**
+     * Switches to a dummy persist adapter that discards all writes.
+     * All future persistence writes will be no-ops.
+     */
+    useDummy() {
+        bt.loggerService.log(PERSIST_LOG_UTILS_METHOD_NAME_USE_DUMMY);
+        this.usePersistLogAdapter(PersistDummy);
+    }
+}
+/**
+ * Global singleton instance of PersistLogUtils.
+ * Used by LogPersistUtils for log entry persistence.
+ */
+const PersistLogAdapter = new PersistLogUtils();
 
 var _a$2, _b$2;
 const BUSY_DELAY = 100;
@@ -30882,6 +30995,416 @@ async function dumpMessages(resultId, history, result, outputDir = "./dump/strat
     }
 }
 
+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";
+const LOG_PERSIST_METHOD_NAME_INFO = "LogPersistUtils.info";
+const LOG_PERSIST_METHOD_NAME_WARN = "LogPersistUtils.warn";
+const LOG_PERSIST_METHOD_NAME_GET_LIST = "LogPersistUtils.getList";
+const LOG_MEMORY_METHOD_NAME_LOG = "LogMemoryUtils.log";
+const LOG_MEMORY_METHOD_NAME_DEBUG = "LogMemoryUtils.debug";
+const LOG_MEMORY_METHOD_NAME_INFO = "LogMemoryUtils.info";
+const LOG_MEMORY_METHOD_NAME_WARN = "LogMemoryUtils.warn";
+const LOG_MEMORY_METHOD_NAME_GET_LIST = "LogMemoryUtils.getList";
+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";
+/**
+ * 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 () => {
+    if (ExecutionContextService.hasContext()) {
+        return new Date(bt.executionContextService.context.when);
+    }
+    return new Date();
+};
+/**
+ * Persistent log adapter.
+ *
+ * Features:
+ * - Persists log entries to disk using PersistLogAdapter
+ * - Lazy initialization with singleshot pattern
+ * - Maintains up to CC_MAX_LOG_LINES most recent entries
+ * - Each entry stored individually keyed by its id
+ *
+ * Use this adapter (default) for log persistence across sessions.
+ */
+class LogPersistUtils {
+    constructor() {
+        /** Array of log entries */
+        this._entries = [];
+        /**
+         * Singleshot initialization function that loads entries from disk.
+         * Protected by singleshot to ensure one-time execution.
+         */
+        this.waitForInit = functoolsKit.singleshot(async () => {
+            bt.loggerService.info(LOG_PERSIST_METHOD_NAME_WAIT_FOR_INIT);
+            const list = await PersistLogAdapter.readLogData();
+            list.sort((a, b) => a.timestamp - b.timestamp);
+            this._entries = list.slice(-GLOBAL_CONFIG.CC_MAX_LOG_LINES);
+        });
+        /**
+         * Logs a general-purpose message.
+         * Persists entry to disk after appending.
+         * @param topic - The log topic / method name
+         * @param args - Additional arguments
+         */
+        this.log = async (topic, ...args) => {
+            bt.loggerService.info(LOG_PERSIST_METHOD_NAME_LOG, { topic });
+            await this.waitForInit();
+            const date = await GET_DATE_FN();
+            this._entries.push({
+                id: functoolsKit.randomString(),
+                type: "log",
+                timestamp: Date.now(),
+                createdAt: date.toISOString(),
+                topic,
+                args,
+            });
+            this._enforceLimit();
+            await PersistLogAdapter.writeLogData(this._entries);
+        };
+        /**
+         * Logs a debug-level message.
+         * Persists entry to disk after appending.
+         * @param topic - The log topic / method name
+         * @param args - Additional arguments
+         */
+        this.debug = async (topic, ...args) => {
+            bt.loggerService.info(LOG_PERSIST_METHOD_NAME_DEBUG, { topic });
+            await this.waitForInit();
+            const date = await GET_DATE_FN();
+            this._entries.push({
+                id: functoolsKit.randomString(),
+                type: "debug",
+                timestamp: Date.now(),
+                createdAt: date.toISOString(),
+                topic,
+                args,
+            });
+            this._enforceLimit();
+            await PersistLogAdapter.writeLogData(this._entries);
+        };
+        /**
+         * Logs an info-level message.
+         * Persists entry to disk after appending.
+         * @param topic - The log topic / method name
+         * @param args - Additional arguments
+         */
+        this.info = async (topic, ...args) => {
+            bt.loggerService.info(LOG_PERSIST_METHOD_NAME_INFO, { topic });
+            await this.waitForInit();
+            const date = await GET_DATE_FN();
+            this._entries.push({
+                id: functoolsKit.randomString(),
+                type: "info",
+                timestamp: Date.now(),
+                createdAt: date.toISOString(),
+                topic,
+                args,
+            });
+            this._enforceLimit();
+            await PersistLogAdapter.writeLogData(this._entries);
+        };
+        /**
+         * Logs a warning-level message.
+         * Persists entry to disk after appending.
+         * @param topic - The log topic / method name
+         * @param args - Additional arguments
+         */
+        this.warn = async (topic, ...args) => {
+            bt.loggerService.info(LOG_PERSIST_METHOD_NAME_WARN, { topic });
+            await this.waitForInit();
+            const date = await GET_DATE_FN();
+            this._entries.push({
+                id: functoolsKit.randomString(),
+                type: "warn",
+                timestamp: Date.now(),
+                createdAt: date.toISOString(),
+                topic,
+                args,
+            });
+            this._enforceLimit();
+            await PersistLogAdapter.writeLogData(this._entries);
+        };
+        /**
+         * Lists all stored log entries.
+         * @returns Array of all log entries
+         */
+        this.getList = async () => {
+            bt.loggerService.info(LOG_PERSIST_METHOD_NAME_GET_LIST);
+            await this.waitForInit();
+            return [...this._entries];
+        };
+    }
+    /**
+     * Removes oldest entries if limit is exceeded.
+     */
+    _enforceLimit() {
+        if (this._entries.length > GLOBAL_CONFIG.CC_MAX_LOG_LINES) {
+            this._entries.splice(0, this._entries.length - GLOBAL_CONFIG.CC_MAX_LOG_LINES);
+        }
+    }
+}
+/**
+ * In-memory log adapter.
+ *
+ * Features:
+ * - Stores log entries in memory only (no persistence)
+ * - Maintains up to CC_MAX_LOG_LINES most recent entries
+ * - Data is lost when application restarts
+ * - Handles all log levels (log, debug, info, warn)
+ *
+ * Use this adapter for testing or when persistence is not required.
+ */
+class LogMemoryUtils {
+    constructor() {
+        /** Array of log entries */
+        this._entries = [];
+        /**
+         * Logs a general-purpose message.
+         * Appends entry to in-memory array.
+         * @param topic - The log topic / method name
+         * @param args - Additional arguments
+         */
+        this.log = async (topic, ...args) => {
+            bt.loggerService.info(LOG_MEMORY_METHOD_NAME_LOG, { topic });
+            const date = await GET_DATE_FN();
+            this._entries.push({
+                id: functoolsKit.randomString(),
+                type: "log",
+                timestamp: Date.now(),
+                createdAt: date.toISOString(),
+                topic,
+                args,
+            });
+            this._enforceLimit();
+        };
+        /**
+         * Logs a debug-level message.
+         * Appends entry to in-memory array.
+         * @param topic - The log topic / method name
+         * @param args - Additional arguments
+         */
+        this.debug = async (topic, ...args) => {
+            bt.loggerService.info(LOG_MEMORY_METHOD_NAME_DEBUG, { topic });
+            const date = await GET_DATE_FN();
+            this._entries.push({
+                id: functoolsKit.randomString(),
+                type: "debug",
+                timestamp: Date.now(),
+                createdAt: date.toISOString(),
+                topic,
+                args,
+            });
+            this._enforceLimit();
+        };
+        /**
+         * Logs an info-level message.
+         * Appends entry to in-memory array.
+         * @param topic - The log topic / method name
+         * @param args - Additional arguments
+         */
+        this.info = async (topic, ...args) => {
+            bt.loggerService.info(LOG_MEMORY_METHOD_NAME_INFO, { topic });
+            const date = await GET_DATE_FN();
+            this._entries.push({
+                id: functoolsKit.randomString(),
+                type: "info",
+                timestamp: Date.now(),
+                createdAt: date.toISOString(),
+                topic,
+                args,
+            });
+            this._enforceLimit();
+        };
+        /**
+         * Logs a warning-level message.
+         * Appends entry to in-memory array.
+         * @param topic - The log topic / method name
+         * @param args - Additional arguments
+         */
+        this.warn = async (topic, ...args) => {
+            bt.loggerService.info(LOG_MEMORY_METHOD_NAME_WARN, { topic });
+            const date = await GET_DATE_FN();
+            this._entries.push({
+                id: functoolsKit.randomString(),
+                type: "warn",
+                timestamp: Date.now(),
+                createdAt: date.toISOString(),
+                topic,
+                args,
+            });
+            this._enforceLimit();
+        };
+        /**
+         * Lists all stored log entries.
+         * @returns Array of all log entries
+         */
+        this.getList = async () => {
+            bt.loggerService.info(LOG_MEMORY_METHOD_NAME_GET_LIST);
+            return [...this._entries];
+        };
+    }
+    /**
+     * Removes oldest entries if limit is exceeded.
+     */
+    _enforceLimit() {
+        if (this._entries.length > GLOBAL_CONFIG.CC_MAX_LOG_LINES) {
+            this._entries.splice(0, this._entries.length - GLOBAL_CONFIG.CC_MAX_LOG_LINES);
+        }
+    }
+}
+/**
+ * Dummy log adapter that discards all writes.
+ *
+ * Features:
+ * - No-op implementation for all methods
+ * - getList always returns empty array
+ *
+ * Use this adapter to disable log storage completely.
+ */
+class LogDummyUtils {
+    /**
+     * Always returns empty array (no storage).
+     * @returns Empty array
+     */
+    async getList() {
+        return [];
+    }
+    /**
+     * No-op handler for general-purpose log.
+     */
+    log() {
+    }
+    /**
+     * No-op handler for debug-level log.
+     */
+    debug() {
+    }
+    /**
+     * No-op handler for info-level log.
+     */
+    info() {
+    }
+    /**
+     * No-op handler for warning-level log.
+     */
+    warn() {
+    }
+}
+/**
+ * Log adapter with pluggable storage backend.
+ *
+ * Features:
+ * - Adapter pattern for swappable log implementations
+ * - Default adapter: LogMemoryUtils (in-memory storage)
+ * - Alternative adapters: LogPersistUtils, LogDummyUtils
+ * - Convenience methods: usePersist(), useMemory(), useDummy()
+ */
+class LogAdapter {
+    constructor() {
+        /** Internal log utils instance */
+        this._log = new LogMemoryUtils();
+        /**
+         * Lists all stored log entries.
+         * Proxies call to the underlying log adapter.
+         * @returns Array of all log entries
+         */
+        this.getList = async () => {
+            if (this._log.getList) {
+                return await this._log.getList();
+            }
+            return [];
+        };
+        /**
+         * Logs a general-purpose message.
+         * Proxies call to the underlying log adapter.
+         * @param topic - The log topic / method name
+         * @param args - Additional arguments
+         */
+        this.log = (topic, ...args) => {
+            if (this._log.log) {
+                this._log.log(topic, ...args);
+            }
+        };
+        /**
+         * Logs a debug-level message.
+         * Proxies call to the underlying log adapter.
+         * @param topic - The log topic / method name
+         * @param args - Additional arguments
+         */
+        this.debug = (topic, ...args) => {
+            if (this._log.debug) {
+                this._log.debug(topic, ...args);
+            }
+        };
+        /**
+         * Logs an info-level message.
+         * Proxies call to the underlying log adapter.
+         * @param topic - The log topic / method name
+         * @param args - Additional arguments
+         */
+        this.info = (topic, ...args) => {
+            if (this._log.info) {
+                this._log.info(topic, ...args);
+            }
+        };
+        /**
+         * Logs a warning-level message.
+         * Proxies call to the underlying log adapter.
+         * @param topic - The log topic / method name
+         * @param args - Additional arguments
+         */
+        this.warn = (topic, ...args) => {
+            if (this._log.warn) {
+                this._log.warn(topic, ...args);
+            }
+        };
+        /**
+         * Sets the log adapter constructor.
+         * All future log operations will use this adapter.
+         * @param Ctor - Constructor for log adapter
+         */
+        this.useLogger = (Ctor) => {
+            bt.loggerService.info(LOG_ADAPTER_METHOD_NAME_USE_LOGGER);
+            this._log = Reflect.construct(Ctor, []);
+        };
+        /**
+         * Switches to persistent log adapter.
+         * Log entries will be persisted to disk.
+         */
+        this.usePersist = () => {
+            bt.loggerService.info(LOG_ADAPTER_METHOD_NAME_USE_PERSIST);
+            this._log = new LogPersistUtils();
+        };
+        /**
+         * Switches to in-memory log adapter (default).
+         * Log entries will be stored in memory only.
+         */
+        this.useMemory = () => {
+            bt.loggerService.info(LOG_ADAPTER_METHOD_NAME_USE_MEMORY);
+            this._log = new LogMemoryUtils();
+        };
+        /**
+         * Switches to dummy log adapter.
+         * All future log writes will be no-ops.
+         */
+        this.useDummy = () => {
+            bt.loggerService.info(LOG_ADAPTER_METHOD_NAME_USE_DUMMY);
+            this._log = new LogDummyUtils();
+        };
+    }
+}
+/**
+ * Global singleton instance of LogAdapter.
+ * Provides unified log management with pluggable backends.
+ */
+const Log = new LogAdapter();
+
 const BACKTEST_METHOD_NAME_RUN = "BacktestUtils.run";
 const BACKTEST_METHOD_NAME_BACKGROUND = "BacktestUtils.background";
 const BACKTEST_METHOD_NAME_STOP = "BacktestUtils.stop";
@@ -38289,6 +38812,7 @@ exports.Exchange = Exchange;
 exports.ExecutionContextService = ExecutionContextService;
 exports.Heat = Heat;
 exports.Live = Live;
+exports.Log = Log;
 exports.Markdown = Markdown;
 exports.MarkdownFileBase = MarkdownFileBase;
 exports.MarkdownFolderBase = MarkdownFolderBase;
@@ -38301,6 +38825,7 @@ exports.Performance = Performance;
 exports.PersistBase = PersistBase;
 exports.PersistBreakevenAdapter = PersistBreakevenAdapter;
 exports.PersistCandleAdapter = PersistCandleAdapter;
+exports.PersistLogAdapter = PersistLogAdapter;
 exports.PersistNotificationAdapter = PersistNotificationAdapter;
 exports.PersistPartialAdapter = PersistPartialAdapter;
 exports.PersistRiskAdapter = PersistRiskAdapter;