backtest-kit 3.6.0 → 3.7.0

package/build/index.mjs

@@ -781,6 +781,11 @@ 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 PERSIST_MEASURE_UTILS_METHOD_NAME_READ_DATA = "PersistMeasureUtils.readMeasureData";
+const PERSIST_MEASURE_UTILS_METHOD_NAME_WRITE_DATA = "PersistMeasureUtils.writeMeasureData";
+const PERSIST_MEASURE_UTILS_METHOD_NAME_USE_JSON = "PersistMeasureUtils.useJson";
+const PERSIST_MEASURE_UTILS_METHOD_NAME_USE_DUMMY = "PersistMeasureUtils.useDummy";
+const PERSIST_MEASURE_UTILS_METHOD_NAME_USE_PERSIST_MEASURE_ADAPTER = "PersistMeasureUtils.usePersistMeasureAdapter";
 const BASE_WAIT_FOR_INIT_FN_METHOD_NAME = "PersistBase.waitForInitFn";
 const BASE_UNLINK_RETRY_COUNT = 5;
 const BASE_UNLINK_RETRY_DELAY = 1000;
@@ -2051,6 +2056,92 @@ class PersistLogUtils {
  * Used by LogPersistUtils for log entry persistence.
  */
 const PersistLogAdapter = new PersistLogUtils();
+/**
+ * Utility class for managing external API response cache persistence.
+ *
+ * Features:
+ * - Memoized storage instances per cache bucket (aligned timestamp + symbol)
+ * - Custom adapter support
+ * - Atomic read/write operations
+ * - Crash-safe cache state management
+ *
+ * Used by Cache.file for persistent caching of external API responses.
+ */
+class PersistMeasureUtils {
+    constructor() {
+        this.PersistMeasureFactory = PersistBase;
+        this.getMeasureStorage = memoize(([bucket]) => bucket, (bucket) => Reflect.construct(this.PersistMeasureFactory, [
+            bucket,
+            `./dump/data/measure/`,
+        ]));
+        /**
+         * Reads cached measure data for a given bucket and key.
+         *
+         * @param bucket - Storage bucket (e.g. aligned timestamp + symbol)
+         * @param key - Dynamic cache key within the bucket
+         * @returns Promise resolving to cached value or null if not found
+         */
+        this.readMeasureData = async (bucket, key) => {
+            bt.loggerService.info(PERSIST_MEASURE_UTILS_METHOD_NAME_READ_DATA, {
+                bucket,
+                key,
+            });
+            const isInitial = !this.getMeasureStorage.has(bucket);
+            const stateStorage = this.getMeasureStorage(bucket);
+            await stateStorage.waitForInit(isInitial);
+            if (await stateStorage.hasValue(key)) {
+                return await stateStorage.readValue(key);
+            }
+            return null;
+        };
+        /**
+         * Writes measure data to disk with atomic file writes.
+         *
+         * @param data - Data to cache
+         * @param bucket - Storage bucket (e.g. aligned timestamp + symbol)
+         * @param key - Dynamic cache key within the bucket
+         * @returns Promise that resolves when write is complete
+         */
+        this.writeMeasureData = async (data, bucket, key) => {
+            bt.loggerService.info(PERSIST_MEASURE_UTILS_METHOD_NAME_WRITE_DATA, {
+                bucket,
+                key,
+            });
+            const isInitial = !this.getMeasureStorage.has(bucket);
+            const stateStorage = this.getMeasureStorage(bucket);
+            await stateStorage.waitForInit(isInitial);
+            await stateStorage.writeValue(key, data);
+        };
+    }
+    /**
+     * Registers a custom persistence adapter.
+     *
+     * @param Ctor - Custom PersistBase constructor
+     */
+    usePersistMeasureAdapter(Ctor) {
+        bt.loggerService.info(PERSIST_MEASURE_UTILS_METHOD_NAME_USE_PERSIST_MEASURE_ADAPTER);
+        this.PersistMeasureFactory = Ctor;
+    }
+    /**
+     * Switches to the default JSON persist adapter.
+     */
+    useJson() {
+        bt.loggerService.log(PERSIST_MEASURE_UTILS_METHOD_NAME_USE_JSON);
+        this.usePersistMeasureAdapter(PersistBase);
+    }
+    /**
+     * Switches to a dummy persist adapter that discards all writes.
+     */
+    useDummy() {
+        bt.loggerService.log(PERSIST_MEASURE_UTILS_METHOD_NAME_USE_DUMMY);
+        this.usePersistMeasureAdapter(PersistDummy);
+    }
+}
+/**
+ * Global singleton instance of PersistMeasureUtils.
+ * Used by Cache.file for persistent caching of external API responses.
+ */
+const PersistMeasureAdapter = new PersistMeasureUtils();
 
 var _a$3, _b$3;
 const BUSY_DELAY = 100;
@@ -10351,7 +10442,7 @@ class ActionBase {
      * @example
      * ```typescript
      * pingScheduled(event: SchedulePingContract) {
-     *   const waitTime = Date.now() - event.data.timestampScheduled;
+     *   const waitTime = getTimestamp() - event.data.timestampScheduled;
      *   const waitMinutes = Math.floor(waitTime / 60000);
      *   console.log(`Scheduled signal waiting ${waitMinutes} minutes`);
      * }
@@ -10380,7 +10471,7 @@ class ActionBase {
      * @example
      * ```typescript
      * pingActive(event: ActivePingContract) {
-     *   const holdTime = Date.now() - event.data.pendingAt;
+     *   const holdTime = getTimestamp() - event.data.pendingAt;
      *   const holdMinutes = Math.floor(holdTime / 60000);
      *   console.log(`Active signal holding ${holdMinutes} minutes`);
      * }
@@ -16082,6 +16173,20 @@ const COLUMN_CONFIG = {
  */
 const DEFAULT_COLUMNS = Object.freeze({ ...COLUMN_CONFIG });
 
+/**
+ * Retrieves the current timestamp based on the execution context.
+ * If an execution context is active (e.g., during a backtest), it returns the timestamp from the context to ensure consistency with the simulated time.
+ * If no execution context is active (e.g., during live operation), it returns the current real-world timestamp.
+ * This function helps maintain accurate timing for logs, metrics, and other time-sensitive operations across both live and backtest modes.
+ * @return {number} The current timestamp in milliseconds, either from the execution context or the real-world clock.
+ */
+const getContextTimestamp = () => {
+    if (ExecutionContextService.hasContext()) {
+        return bt.executionContextService.context.when.getTime();
+    }
+    return Date.now();
+};
+
 var _a$2, _b$2;
 const MARKDOWN_METHOD_NAME_ENABLE = "MarkdownUtils.enable";
 const MARKDOWN_METHOD_NAME_DISABLE = "MarkdownUtils.disable";
@@ -16215,7 +16320,7 @@ class MarkdownFileBase {
             markdownName: this.markdownName,
             data,
             ...searchFlags,
-            timestamp: Date.now(),
+            timestamp: getContextTimestamp(),
         }) + "\n";
         const status = await this[WRITE_SAFE_SYMBOL$2](line);
         if (status === TIMEOUT_SYMBOL$1) {
@@ -16759,7 +16864,7 @@ let ReportStorage$7 = class ReportStorage {
      */
     async dump(strategyName, path = "./dump/backtest", columns = COLUMN_CONFIG.backtest_columns) {
         const markdown = await this.getReport(strategyName, columns);
-        const timestamp = Date.now();
+        const timestamp = getContextTimestamp();
         const filename = CREATE_FILE_NAME_FN$9(this.symbol, strategyName, this.exchangeName, this.frameName, timestamp);
         await Markdown.writeData("backtest", markdown, {
             path,
@@ -17094,7 +17199,7 @@ let ReportStorage$6 = class ReportStorage {
      */
     addIdleEvent(currentPrice) {
         const newEvent = {
-            timestamp: Date.now(),
+            timestamp: getContextTimestamp(),
             action: "idle",
             currentPrice,
         };
@@ -17150,7 +17255,7 @@ let ReportStorage$6 = class ReportStorage {
      */
     addActiveEvent(data) {
         const newEvent = {
-            timestamp: Date.now(),
+            timestamp: getContextTimestamp(),
             action: "active",
             symbol: data.signal.symbol,
             signalId: data.signal.id,
@@ -17252,7 +17357,7 @@ let ReportStorage$6 = class ReportStorage {
      */
     addWaitingEvent(data) {
         const newEvent = {
-            timestamp: Date.now(),
+            timestamp: getContextTimestamp(),
             action: "waiting",
             symbol: data.signal.symbol,
             signalId: data.signal.id,
@@ -17446,7 +17551,7 @@ let ReportStorage$6 = class ReportStorage {
      */
     async dump(strategyName, path = "./dump/live", columns = COLUMN_CONFIG.live_columns) {
         const markdown = await this.getReport(strategyName, columns);
-        const timestamp = Date.now();
+        const timestamp = getContextTimestamp();
         const filename = CREATE_FILE_NAME_FN$8(this.symbol, strategyName, this.exchangeName, this.frameName, timestamp);
         await Markdown.writeData("live", markdown, {
             path,
@@ -17978,7 +18083,7 @@ let ReportStorage$5 = class ReportStorage {
      */
     async dump(strategyName, path = "./dump/schedule", columns = COLUMN_CONFIG.schedule_columns) {
         const markdown = await this.getReport(strategyName, columns);
-        const timestamp = Date.now();
+        const timestamp = getContextTimestamp();
         const filename = CREATE_FILE_NAME_FN$7(this.symbol, strategyName, this.exchangeName, this.frameName, timestamp);
         await Markdown.writeData("schedule", markdown, {
             path,
@@ -18443,7 +18548,7 @@ class PerformanceStorage {
      */
     async dump(strategyName, path = "./dump/performance", columns = COLUMN_CONFIG.performance_columns) {
         const markdown = await this.getReport(strategyName, columns);
-        const timestamp = Date.now();
+        const timestamp = getContextTimestamp();
         const filename = CREATE_FILE_NAME_FN$6(this.symbol, strategyName, this.exchangeName, this.frameName, timestamp);
         await Markdown.writeData("performance", markdown, {
             path,
@@ -18894,7 +18999,7 @@ let ReportStorage$4 = class ReportStorage {
      */
     async dump(symbol, metric, context, path = "./dump/walker", strategyColumns = COLUMN_CONFIG.walker_strategy_columns, pnlColumns = COLUMN_CONFIG.walker_pnl_columns) {
         const markdown = await this.getReport(symbol, metric, context, strategyColumns, pnlColumns);
-        const timestamp = Date.now();
+        const timestamp = getContextTimestamp();
         const filename = CREATE_FILE_NAME_FN$5(this.walkerName, timestamp);
         await Markdown.writeData("walker", markdown, {
             path,
@@ -19448,7 +19553,7 @@ class HeatmapStorage {
      */
     async dump(strategyName, path = "./dump/heatmap", columns = COLUMN_CONFIG.heat_columns) {
         const markdown = await this.getReport(strategyName, columns);
-        const timestamp = Date.now();
+        const timestamp = getContextTimestamp();
         const filename = CREATE_FILE_NAME_FN$4(strategyName, this.exchangeName, this.frameName, timestamp);
         await Markdown.writeData("heat", markdown, {
             path,
@@ -21128,7 +21233,7 @@ let ReportStorage$3 = class ReportStorage {
      */
     async dump(symbol, strategyName, path = "./dump/partial", columns = COLUMN_CONFIG.partial_columns) {
         const markdown = await this.getReport(symbol, strategyName, columns);
-        const timestamp = Date.now();
+        const timestamp = getContextTimestamp();
         const filename = CREATE_FILE_NAME_FN$3(this.symbol, strategyName, this.exchangeName, this.frameName, timestamp);
         await Markdown.writeData("partial", markdown, {
             path,
@@ -22221,7 +22326,7 @@ let ReportStorage$2 = class ReportStorage {
      */
     async dump(symbol, strategyName, path = "./dump/breakeven", columns = COLUMN_CONFIG.breakeven_columns) {
         const markdown = await this.getReport(symbol, strategyName, columns);
-        const timestamp = Date.now();
+        const timestamp = getContextTimestamp();
         const filename = CREATE_FILE_NAME_FN$2(this.symbol, strategyName, this.exchangeName, this.frameName, timestamp);
         await Markdown.writeData("breakeven", markdown, {
             path,
@@ -22889,7 +22994,7 @@ let ReportStorage$1 = class ReportStorage {
      */
     async dump(symbol, strategyName, path = "./dump/risk", columns = COLUMN_CONFIG.risk_columns) {
         const markdown = await this.getReport(symbol, strategyName, columns);
-        const timestamp = Date.now();
+        const timestamp = getContextTimestamp();
         const filename = CREATE_FILE_NAME_FN$1(this.symbol, strategyName, this.exchangeName, this.frameName, timestamp);
         await Markdown.writeData("risk", markdown, {
             path,
@@ -23373,7 +23478,7 @@ class ReportBase {
             reportName: this.reportName,
             data,
             ...searchFlags,
-            timestamp: Date.now(),
+            timestamp: getContextTimestamp(),
         }) + "\n";
         const status = await this[WRITE_SAFE_SYMBOL$1](line);
         if (status === TIMEOUT_SYMBOL$1) {
@@ -23712,7 +23817,7 @@ class BacktestReportService {
         this.tick = async (data) => {
             this.loggerService.log(BACKTEST_REPORT_METHOD_NAME_TICK, { data });
             const baseEvent = {
-                timestamp: Date.now(),
+                timestamp: getContextTimestamp(),
                 action: data.action,
                 symbol: data.symbol,
                 strategyName: data.strategyName,
@@ -23891,7 +23996,7 @@ class LiveReportService {
         this.tick = async (data) => {
             this.loggerService.log(LIVE_REPORT_METHOD_NAME_TICK, { data });
             const baseEvent = {
-                timestamp: Date.now(),
+                timestamp: getContextTimestamp(),
                 action: data.action,
                 symbol: data.symbol,
                 strategyName: data.strategyName,
@@ -24414,7 +24519,7 @@ class WalkerReportService {
         this.tick = async (data) => {
             this.loggerService.log(WALKER_REPORT_METHOD_NAME_TICK, { data });
             await Report.writeData("walker", {
-                timestamp: Date.now(),
+                timestamp: getContextTimestamp(),
                 walkerName: data.walkerName,
                 symbol: data.symbol,
                 exchangeName: data.exchangeName,
@@ -24541,7 +24646,7 @@ class HeatReportService {
                 return;
             }
             await Report.writeData("heat", {
-                timestamp: Date.now(),
+                timestamp: getContextTimestamp(),
                 action: data.action,
                 symbol: data.symbol,
                 strategyName: data.strategyName,
@@ -25863,7 +25968,7 @@ class ReportStorage {
      */
     async dump(symbol, strategyName, path = "./dump/strategy", columns = COLUMN_CONFIG.strategy_columns) {
         const markdown = await this.getReport(symbol, strategyName, columns);
-        const timestamp = Date.now();
+        const timestamp = getContextTimestamp();
         const filename = CREATE_FILE_NAME_FN(this.symbol, strategyName, this.exchangeName, this.frameName, timestamp);
         await Markdown.writeData("strategy", markdown, {
             path,
@@ -28179,6 +28284,7 @@ const GET_AVERAGE_PRICE_METHOD_NAME = "exchange.getAveragePrice";
 const FORMAT_PRICE_METHOD_NAME = "exchange.formatPrice";
 const FORMAT_QUANTITY_METHOD_NAME = "exchange.formatQuantity";
 const GET_DATE_METHOD_NAME = "exchange.getDate";
+const GET_TIMESTAMP_METHOD_NAME = "exchange.getTimestamp";
 const GET_MODE_METHOD_NAME = "exchange.getMode";
 const GET_SYMBOL_METHOD_NAME = "exchange.getSymbol";
 const GET_CONTEXT_METHOD_NAME = "exchange.getContext";
@@ -28344,6 +28450,26 @@ async function getDate() {
     const { when } = bt.executionContextService.context;
     return new Date(when.getTime());
 }
+/**
+ * Gets the current timestamp from execution context.
+ *
+ * In backtest mode: returns the current timeframe timestamp being processed
+ * In live mode: returns current real-time timestamp
+ *
+ * @returns Promise resolving to current execution context timestamp in milliseconds
+ * @example
+ * ```typescript
+ * const timestamp = await getTimestamp();
+ * console.log(timestamp); // 1700000000000
+ * ```
+ */
+async function getTimestamp() {
+    bt.loggerService.info(GET_TIMESTAMP_METHOD_NAME);
+    if (!ExecutionContextService.hasContext()) {
+        throw new Error("getTimestamp requires an execution context");
+    }
+    return getContextTimestamp();
+}
 /**
  * Gets the current execution mode.
  *
@@ -32541,7 +32667,6 @@ const ADD_ACTION_METHOD_NAME = "add.addActionSchema";
  *     priceTakeProfit: 51000,
  *     priceStopLoss: 49000,
  *     minuteEstimatedTime: 60,
- *     timestamp: Date.now(),
  *   }),
  *   callbacks: {
  *     onOpen: (symbol, signal, currentPrice, backtest) => console.log("Signal opened"),
@@ -33468,8 +33593,8 @@ 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.
+ * Returns the 'when' priority from the execution context if available, otherwise returns the current time.
+ * This allows log entries to be priorityed according to the backtest timeline rather than real-world time, improving log relevance and user experience during backtest analysis.
  */
 const GET_DATE_FN = () => {
     if (ExecutionContextService.hasContext()) {
@@ -33491,7 +33616,7 @@ const GET_METHOD_CONTEXT_FN = () => {
 /**
  * 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.
+ * This allows log entries to include contextual information about the symbol, priority, 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()) {
@@ -33521,7 +33646,7 @@ class LogPersistUtils {
         this.waitForInit = 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);
+            list.sort((a, b) => a.priority - b.priority);
             this._entries = list.slice(-GLOBAL_CONFIG.CC_MAX_LOG_LINES);
         });
         /**
@@ -33537,7 +33662,8 @@ class LogPersistUtils {
             this._entries.push({
                 id: randomString(),
                 type: "log",
-                timestamp: Date.now(),
+                priority: Date.now(),
+                timestamp: getContextTimestamp(),
                 createdAt: date.toISOString(),
                 methodContext: GET_METHOD_CONTEXT_FN(),
                 executionContext: GET_EXECUTION_CONTEXT_FN(),
@@ -33560,7 +33686,8 @@ class LogPersistUtils {
             this._entries.push({
                 id: randomString(),
                 type: "debug",
-                timestamp: Date.now(),
+                priority: Date.now(),
+                timestamp: getContextTimestamp(),
                 createdAt: date.toISOString(),
                 methodContext: GET_METHOD_CONTEXT_FN(),
                 executionContext: GET_EXECUTION_CONTEXT_FN(),
@@ -33583,7 +33710,8 @@ class LogPersistUtils {
             this._entries.push({
                 id: randomString(),
                 type: "info",
-                timestamp: Date.now(),
+                priority: Date.now(),
+                timestamp: getContextTimestamp(),
                 createdAt: date.toISOString(),
                 methodContext: GET_METHOD_CONTEXT_FN(),
                 executionContext: GET_EXECUTION_CONTEXT_FN(),
@@ -33606,7 +33734,8 @@ class LogPersistUtils {
             this._entries.push({
                 id: randomString(),
                 type: "warn",
-                timestamp: Date.now(),
+                priority: Date.now(),
+                timestamp: getContextTimestamp(),
                 createdAt: date.toISOString(),
                 methodContext: GET_METHOD_CONTEXT_FN(),
                 executionContext: GET_EXECUTION_CONTEXT_FN(),
@@ -33662,7 +33791,8 @@ class LogMemoryUtils {
             this._entries.push({
                 id: randomString(),
                 type: "log",
-                timestamp: Date.now(),
+                priority: Date.now(),
+                timestamp: getContextTimestamp(),
                 createdAt: date.toISOString(),
                 methodContext: GET_METHOD_CONTEXT_FN(),
                 executionContext: GET_EXECUTION_CONTEXT_FN(),
@@ -33683,7 +33813,8 @@ class LogMemoryUtils {
             this._entries.push({
                 id: randomString(),
                 type: "debug",
-                timestamp: Date.now(),
+                priority: Date.now(),
+                timestamp: getContextTimestamp(),
                 createdAt: date.toISOString(),
                 methodContext: GET_METHOD_CONTEXT_FN(),
                 executionContext: GET_EXECUTION_CONTEXT_FN(),
@@ -33704,7 +33835,8 @@ class LogMemoryUtils {
             this._entries.push({
                 id: randomString(),
                 type: "info",
-                timestamp: Date.now(),
+                priority: Date.now(),
+                timestamp: getContextTimestamp(),
                 createdAt: date.toISOString(),
                 methodContext: GET_METHOD_CONTEXT_FN(),
                 executionContext: GET_EXECUTION_CONTEXT_FN(),
@@ -33725,7 +33857,8 @@ class LogMemoryUtils {
             this._entries.push({
                 id: randomString(),
                 type: "warn",
-                timestamp: Date.now(),
+                priority: Date.now(),
+                timestamp: getContextTimestamp(),
                 createdAt: date.toISOString(),
                 methodContext: GET_METHOD_CONTEXT_FN(),
                 executionContext: GET_EXECUTION_CONTEXT_FN(),
@@ -33839,7 +33972,8 @@ class LogJsonlUtils {
             await this._append({
                 id: randomString(),
                 type: "log",
-                timestamp: Date.now(),
+                priority: Date.now(),
+                timestamp: getContextTimestamp(),
                 createdAt: date.toISOString(),
                 methodContext: GET_METHOD_CONTEXT_FN(),
                 executionContext: GET_EXECUTION_CONTEXT_FN(),
@@ -33858,7 +33992,8 @@ class LogJsonlUtils {
             await this._append({
                 id: randomString(),
                 type: "debug",
-                timestamp: Date.now(),
+                priority: Date.now(),
+                timestamp: getContextTimestamp(),
                 createdAt: date.toISOString(),
                 methodContext: GET_METHOD_CONTEXT_FN(),
                 executionContext: GET_EXECUTION_CONTEXT_FN(),
@@ -33877,7 +34012,8 @@ class LogJsonlUtils {
             await this._append({
                 id: randomString(),
                 type: "info",
-                timestamp: Date.now(),
+                priority: Date.now(),
+                timestamp: getContextTimestamp(),
                 createdAt: date.toISOString(),
                 methodContext: GET_METHOD_CONTEXT_FN(),
                 executionContext: GET_EXECUTION_CONTEXT_FN(),
@@ -33896,7 +34032,8 @@ class LogJsonlUtils {
             await this._append({
                 id: randomString(),
                 type: "warn",
-                timestamp: Date.now(),
+                priority: Date.now(),
+                timestamp: getContextTimestamp(),
                 createdAt: date.toISOString(),
                 methodContext: GET_METHOD_CONTEXT_FN(),
                 executionContext: GET_EXECUTION_CONTEXT_FN(),
@@ -38323,6 +38460,8 @@ const CACHE_METHOD_NAME_CLEAR = "CacheInstance.clear";
 const CACHE_METHOD_NAME_RUN = "CacheInstance.run";
 const CACHE_METHOD_NAME_GC = "CacheInstance.gc";
 const CACHE_METHOD_NAME_FN = "CacheUtils.fn";
+const CACHE_METHOD_NAME_FILE = "CacheUtils.file";
+const CACHE_FILE_INSTANCE_METHOD_NAME_RUN = "CacheFileInstance.run";
 const MS_PER_MINUTE$1 = 60000;
 const INTERVAL_MINUTES$1 = {
     "1m": 1,
@@ -38544,6 +38683,95 @@ class CacheInstance {
         };
     }
 }
+/**
+ * Instance class for caching async function results in persistent file storage.
+ *
+ * Provides automatic cache invalidation based on candle intervals.
+ * Cache key = `${alignedTimestamp}_${symbol}` (bucket) + dynamic key (file within bucket).
+ * On cache hit reads from disk, on miss calls the function and writes the result.
+ *
+ * @template T - Async function type to cache
+ * @template K - Dynamic key type
+ *
+ * @example
+ * ```typescript
+ * const instance = new CacheFileInstance(fetchFromApi, "1h");
+ * const result = await instance.run("BTCUSDT", extraArg);
+ * ```
+ */
+class CacheFileInstance {
+    /**
+     * Allocates a new unique index. Called once in the constructor to give each
+     * CacheFileInstance its own namespace in the persistent key space.
+     */
+    static createIndex() {
+        return CacheFileInstance._indexCounter++;
+    }
+    /**
+     * Creates a new CacheFileInstance.
+     *
+     * @param fn - Async function to cache
+     * @param interval - Candle interval for cache invalidation
+     * @param name - Human-readable bucket name used as the directory key (replaces symbol in bucket path)
+     * @param key - Dynamic key generator; receives all args, must return a string.
+     *              Default: `([symbol, alignMs]) => \`${symbol}_${alignMs}\``
+     */
+    constructor(fn, interval, name, key = ([symbol, alignMs]) => `${symbol}_${alignMs}`) {
+        this.fn = fn;
+        this.interval = interval;
+        this.name = name;
+        this.key = key;
+        /**
+         * Execute async function with persistent file caching.
+         *
+         * Algorithm:
+         * 1. Build bucket = `${name}_${interval}_${index}` — fixed per instance, used as directory name
+         * 2. Align execution context `when` to interval boundary → `alignedTs`
+         * 3. Build entity key from the key generator (receives `[symbol, alignedTs, ...rest]`)
+         * 4. Try to read from PersistMeasureAdapter using (bucket, entityKey)
+         * 5. On hit — return cached value
+         * 6. On miss — call fn, write result to disk, return result
+         *
+         * Cache invalidation happens through the entity key: the default key embeds `alignedTs`,
+         * so each new candle interval produces a new file name while the bucket directory stays the same.
+         *
+         * Requires active execution context (symbol, when) and method context.
+         *
+         * @param args - Arguments forwarded to the wrapped function
+         * @returns Cached or freshly computed result
+         */
+        this.run = async (...args) => {
+            bt.loggerService.debug(CACHE_FILE_INSTANCE_METHOD_NAME_RUN, { args });
+            const step = INTERVAL_MINUTES$1[this.interval];
+            {
+                if (!MethodContextService.hasContext()) {
+                    throw new Error("CacheFileInstance run requires method context");
+                }
+                if (!ExecutionContextService.hasContext()) {
+                    throw new Error("CacheFileInstance run requires execution context");
+                }
+                if (!step) {
+                    throw new Error(`CacheFileInstance unknown cache ttl interval=${this.interval}`);
+                }
+            }
+            const [symbol, ...rest] = args;
+            const { when } = bt.executionContextService.context;
+            const alignedTs = align(when.getTime(), this.interval);
+            const bucket = `${this.name}_${this.interval}_${this.index}`;
+            const entityKey = this.key([symbol, alignedTs, ...rest]);
+            const cached = await PersistMeasureAdapter.readMeasureData(bucket, entityKey);
+            if (cached !== null) {
+                return cached;
+            }
+            const result = await this.fn.call(null, ...args);
+            await PersistMeasureAdapter.writeMeasureData(result, bucket, entityKey);
+            return result;
+        };
+        this.index = CacheFileInstance.createIndex();
+    }
+}
+/** Global counter — incremented once per CacheFileInstance construction */
+CacheFileInstance._indexCounter = 0;
 /**
  * Utility class for function caching with timeframe-based invalidation.
  *
@@ -38565,7 +38793,12 @@ class CacheUtils {
          * Memoized function to get or create CacheInstance for a function.
          * Each function gets its own isolated cache instance.
          */
-        this._getInstance = memoize(([run]) => run, (run, interval, key) => new CacheInstance(run, interval, key));
+        this._getFnInstance = memoize(([run]) => run, (run, interval, key) => new CacheInstance(run, interval, key));
+        /**
+         * Memoized function to get or create CacheFileInstance for an async function.
+         * Each function gets its own isolated file-cache instance.
+         */
+        this._getFileInstance = memoize(([run]) => run, (run, interval, name, key) => new CacheFileInstance(run, interval, name, key));
         /**
          * Wrap a function with caching based on timeframe intervals.
          *
@@ -38604,11 +38837,57 @@ class CacheUtils {
                 context,
             });
             const wrappedFn = (...args) => {
-                const instance = this._getInstance(run, context.interval, context.key);
+                const instance = this._getFnInstance(run, context.interval, context.key);
                 return instance.run(...args).value;
             };
             return wrappedFn;
         };
+        /**
+         * Wrap an async function with persistent file-based caching.
+         *
+         * Returns a wrapped version of the function that reads from disk on cache hit
+         * and writes the result to disk on cache miss. Files are stored under
+         * `./dump/data/measure/{name}_{interval}_{index}/`.
+         *
+         * The `run` function reference is used as the memoization key for the underlying
+         * `CacheFileInstance`, so each unique function reference gets its own isolated instance.
+         * Pass the same function reference each time to reuse the same cache.
+         *
+         * @template T - Async function type to cache
+         * @param run - Async function to wrap with file caching
+         * @param context.interval - Candle interval for cache invalidation
+         * @param context.name - Human-readable bucket name; becomes the directory prefix
+         * @param context.key - Optional entity key generator. Receives `[symbol, alignMs, ...rest]`
+         *                      where `alignMs` is the timestamp aligned to `interval`.
+         *                      Default: `([symbol, alignMs]) => \`${symbol}_${alignMs}\``
+         * @returns Wrapped async function with automatic persistent caching
+         *
+         * @example
+         * ```typescript
+         * const fetchData = async (symbol: string, period: number) => {
+         *   return await externalApi.fetch(symbol, period);
+         * };
+         *
+         * // Default key — one cache file per symbol per aligned candle
+         * const cachedFetch = Cache.file(fetchData, { interval: "1h", name: "fetchData" });
+         *
+         * // Custom key — one cache file per symbol + period combination
+         * const cachedFetch = Cache.file(fetchData, {
+         *   interval: "1h",
+         *   name: "fetchData",
+         *   key: ([symbol, alignMs, period]) => `${symbol}_${alignMs}_${period}`,
+         * });
+         * const result = await cachedFetch("BTCUSDT", 14);
+         * ```
+         */
+        this.file = (run, context) => {
+            bt.loggerService.info(CACHE_METHOD_NAME_FILE, { context });
+            const wrappedFn = (...args) => {
+                const instance = this._getFileInstance(run, context.interval, context.name, context.key);
+                return instance.run(...args);
+            };
+            return wrappedFn;
+        };
         /**
          * Flush (remove) cached CacheInstance for a specific function or all functions.
          *
@@ -38642,7 +38921,7 @@ class CacheUtils {
             bt.loggerService.info(CACHE_METHOD_NAME_FLUSH, {
                 run,
             });
-            this._getInstance.clear(run);
+            this._getFnInstance.clear(run);
         };
         /**
          * Clear cached value for current execution context of a specific function.
@@ -38685,7 +38964,7 @@ class CacheUtils {
                 console.warn(`${CACHE_METHOD_NAME_CLEAR} called without execution context, skipping clear`);
                 return;
             }
-            this._getInstance.get(run).clear();
+            this._getFnInstance.get(run).clear();
         };
         /**
          * Garbage collect expired cache entries for a specific function.
@@ -38717,7 +38996,7 @@ class CacheUtils {
                 console.warn(`${CACHE_METHOD_NAME_GC} called without execution context, skipping garbage collection`);
                 return;
             }
-            return this._getInstance.get(run).gc();
+            return this._getFnInstance.get(run).gc();
         };
     }
 }
@@ -39287,4 +39566,4 @@ const set = (object, path, value) => {
     }
 };
 
-export { ActionBase, Backtest, Breakeven, Cache, Constant, Exchange, ExecutionContextService, Heat, Live, Log, Markdown, MarkdownFileBase, MarkdownFolderBase, MethodContextService, Notification, NotificationBacktest, NotificationLive, Partial, Performance, PersistBase, PersistBreakevenAdapter, PersistCandleAdapter, PersistLogAdapter, PersistNotificationAdapter, PersistPartialAdapter, PersistRiskAdapter, PersistScheduleAdapter, PersistSignalAdapter, PersistStorageAdapter, PositionSize, Report, ReportBase, Risk, Schedule, Storage, StorageBacktest, StorageLive, Strategy, Walker, addActionSchema, addExchangeSchema, addFrameSchema, addRiskSchema, addSizingSchema, addStrategySchema, addWalkerSchema, alignToInterval, checkCandles, commitActivateScheduled, commitAverageBuy, commitBreakeven, commitCancelScheduled, commitClosePending, commitPartialLoss, commitPartialProfit, commitTrailingStop, commitTrailingTake, dumpMessages, emitters, formatPrice, formatQuantity, get, getActionSchema, getAggregatedTrades, getAveragePrice, getBacktestTimeframe, getCandles, getColumns, getConfig, getContext, getDate, getDefaultColumns, getDefaultConfig, getExchangeSchema, getFrameSchema, getMode, getNextCandles, getOrderBook, getRawCandles, getRiskSchema, getSizingSchema, getStrategySchema, getSymbol, getWalkerSchema, hasTradeContext, backtest as lib, listExchangeSchema, listFrameSchema, listRiskSchema, listSizingSchema, listStrategySchema, listWalkerSchema, listenActivePing, listenActivePingOnce, listenBacktestProgress, listenBreakevenAvailable, listenBreakevenAvailableOnce, listenDoneBacktest, listenDoneBacktestOnce, listenDoneLive, listenDoneLiveOnce, listenDoneWalker, listenDoneWalkerOnce, listenError, listenExit, listenPartialLossAvailable, listenPartialLossAvailableOnce, listenPartialProfitAvailable, listenPartialProfitAvailableOnce, listenPerformance, listenRisk, listenRiskOnce, listenSchedulePing, listenSchedulePingOnce, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, listenStrategyCommit, listenStrategyCommitOnce, listenValidation, listenWalker, listenWalkerComplete, listenWalkerOnce, listenWalkerProgress, overrideActionSchema, overrideExchangeSchema, overrideFrameSchema, overrideRiskSchema, overrideSizingSchema, overrideStrategySchema, overrideWalkerSchema, parseArgs, roundTicks, set, setColumns, setConfig, setLogger, shutdown, stopStrategy, validate, waitForCandle, warmCandles };
+export { ActionBase, Backtest, Breakeven, Cache, Constant, Exchange, ExecutionContextService, Heat, Live, Log, Markdown, MarkdownFileBase, MarkdownFolderBase, MethodContextService, Notification, NotificationBacktest, NotificationLive, Partial, Performance, PersistBase, PersistBreakevenAdapter, PersistCandleAdapter, PersistLogAdapter, PersistMeasureAdapter, PersistNotificationAdapter, PersistPartialAdapter, PersistRiskAdapter, PersistScheduleAdapter, PersistSignalAdapter, PersistStorageAdapter, PositionSize, Report, ReportBase, Risk, Schedule, Storage, StorageBacktest, StorageLive, Strategy, Walker, addActionSchema, addExchangeSchema, addFrameSchema, addRiskSchema, addSizingSchema, addStrategySchema, addWalkerSchema, alignToInterval, checkCandles, commitActivateScheduled, commitAverageBuy, commitBreakeven, commitCancelScheduled, commitClosePending, commitPartialLoss, commitPartialProfit, commitTrailingStop, commitTrailingTake, dumpMessages, emitters, formatPrice, formatQuantity, get, getActionSchema, getAggregatedTrades, getAveragePrice, getBacktestTimeframe, getCandles, getColumns, getConfig, getContext, getDate, getDefaultColumns, getDefaultConfig, getExchangeSchema, getFrameSchema, getMode, getNextCandles, getOrderBook, getRawCandles, getRiskSchema, getSizingSchema, getStrategySchema, getSymbol, getTimestamp, getWalkerSchema, hasTradeContext, backtest as lib, listExchangeSchema, listFrameSchema, listRiskSchema, listSizingSchema, listStrategySchema, listWalkerSchema, listenActivePing, listenActivePingOnce, listenBacktestProgress, listenBreakevenAvailable, listenBreakevenAvailableOnce, listenDoneBacktest, listenDoneBacktestOnce, listenDoneLive, listenDoneLiveOnce, listenDoneWalker, listenDoneWalkerOnce, listenError, listenExit, listenPartialLossAvailable, listenPartialLossAvailableOnce, listenPartialProfitAvailable, listenPartialProfitAvailableOnce, listenPerformance, listenRisk, listenRiskOnce, listenSchedulePing, listenSchedulePingOnce, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, listenStrategyCommit, listenStrategyCommitOnce, listenValidation, listenWalker, listenWalkerComplete, listenWalkerOnce, listenWalkerProgress, overrideActionSchema, overrideExchangeSchema, overrideFrameSchema, overrideRiskSchema, overrideSizingSchema, overrideStrategySchema, overrideWalkerSchema, parseArgs, roundTicks, set, setColumns, setConfig, setLogger, shutdown, stopStrategy, validate, waitForCandle, warmCandles };