@metamask/snap-networks-utils 1.0.0 → 2.0.0

package/dist/utils/cache/types.d.cts

@@ -0,0 +1,99 @@
+import type { Serializable } from "../serialization/types.cjs";
+export type TimestampMilliseconds = number;
+/**
+ * A single cache entry.
+ */
+export type CacheEntry = {
+    value: Serializable;
+    expiresAt: TimestampMilliseconds;
+};
+/**
+ * Interface for a generic cache implementation.
+ *
+ * @template TValue - The type of values stored in the cache
+ */
+export type ICache<TValue> = {
+    /**
+     * Retrieves a value from the cache by key.
+     *
+     * @param key - The key to retrieve
+     * @returns The value if found, undefined if not found
+     */
+    get(key: string): Promise<TValue | undefined>;
+    /**
+     * Stores a value in the cache with an optional TTL.
+     * - If a value is undefined, it will not be stored in the cache.
+     * - If a value is null, it will be stored in the cache.
+     *
+     * @param key - The key to store the value under
+     * @param value - The value to store
+     * @param ttlMilliseconds - Optional time-to-live in milliseconds. If not provided, the value will not expire.
+     * @throws Error if any entry's ttlMilliseconds is not a number, is negative, or is greater than 2^53 - 1
+     */
+    set(key: string, value: TValue, ttlMilliseconds?: number): Promise<void>;
+    /**
+     * Removes a value from the cache.
+     *
+     * @param key - The key to remove
+     * @returns true if the key was found and removed, false otherwise
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Removes all values from the cache.
+     */
+    clear(): Promise<void>;
+    /**
+     * Checks if a key exists in the cache.
+     *
+     * @param key - The key to check
+     * @returns true if the key exists, false otherwise
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Returns all keys currently in the cache.
+     *
+     * @returns Array of keys
+     */
+    keys(): Promise<string[]>;
+    /**
+     * Returns the number of items in the cache.
+     *
+     * @returns The number of items
+     */
+    size(): Promise<number>;
+    /**
+     * Retrieves a value from the cache without affecting its TTL or last accessed time.
+     *
+     * @param key - The key to peek at
+     * @returns The value if found, undefined if not found
+     */
+    peek(key: string): Promise<TValue | undefined>;
+    /**
+     * Retrieves multiple values from the cache in a single operation.
+     *
+     * @param keys - Array of keys to retrieve
+     * @returns Object mapping keys to their values (or undefined if not found)
+     */
+    mget(keys: string[]): Promise<Record<string, TValue | undefined>>;
+    /**
+     * Stores multiple values in the cache in a single operation.
+     * - If a value is undefined, it will not be stored in the cache.
+     * - If a value is null, it will be stored in the cache.
+     *
+     * @param entries - Array of entries to store, each with key, value, and optional TTL (if not provided, the value will not expire)
+     * @throws Error if any entry's ttlMilliseconds is not a number, is negative, or is greater than 2^53 - 1
+     */
+    mset(entries: {
+        key: string;
+        value: TValue;
+        ttlMilliseconds?: number;
+    }[]): Promise<void>;
+    /**
+     * Removes multiple values from the cache.
+     *
+     * @param keys - Array of keys to remove
+     * @returns An object mapping each key to a boolean indicating whether it was found and removed
+     */
+    mdelete(keys: string[]): Promise<Record<string, boolean>>;
+};
+//# sourceMappingURL=types.d.cts.map

package/dist/utils/cache/types.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.cts","sourceRoot":"","sources":["../../../src/utils/cache/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,mCAA+B;AAE3D,MAAM,MAAM,qBAAqB,GAAG,MAAM,CAAC;AAE3C;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,KAAK,EAAE,YAAY,CAAC;IACpB,SAAS,EAAE,qBAAqB,CAAC;CAClC,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,MAAM,CAAC,MAAM,IAAI;IAC3B;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAE9C;;;;;;;;;OASG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzE;;;;;OAKG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEtC;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEnC;;;;OAIG;IACH,IAAI,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAE1B;;;;OAIG;IACH,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAExB;;;;;OAKG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAE/C;;;;;OAKG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IAElE;;;;;;;OAOG;IACH,IAAI,CACF,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,eAAe,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,GAClE,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;;;OAKG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC3D,CAAC"}

package/dist/utils/cache/types.d.mts

@@ -0,0 +1,99 @@
+import type { Serializable } from "../serialization/types.mjs";
+export type TimestampMilliseconds = number;
+/**
+ * A single cache entry.
+ */
+export type CacheEntry = {
+    value: Serializable;
+    expiresAt: TimestampMilliseconds;
+};
+/**
+ * Interface for a generic cache implementation.
+ *
+ * @template TValue - The type of values stored in the cache
+ */
+export type ICache<TValue> = {
+    /**
+     * Retrieves a value from the cache by key.
+     *
+     * @param key - The key to retrieve
+     * @returns The value if found, undefined if not found
+     */
+    get(key: string): Promise<TValue | undefined>;
+    /**
+     * Stores a value in the cache with an optional TTL.
+     * - If a value is undefined, it will not be stored in the cache.
+     * - If a value is null, it will be stored in the cache.
+     *
+     * @param key - The key to store the value under
+     * @param value - The value to store
+     * @param ttlMilliseconds - Optional time-to-live in milliseconds. If not provided, the value will not expire.
+     * @throws Error if any entry's ttlMilliseconds is not a number, is negative, or is greater than 2^53 - 1
+     */
+    set(key: string, value: TValue, ttlMilliseconds?: number): Promise<void>;
+    /**
+     * Removes a value from the cache.
+     *
+     * @param key - The key to remove
+     * @returns true if the key was found and removed, false otherwise
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Removes all values from the cache.
+     */
+    clear(): Promise<void>;
+    /**
+     * Checks if a key exists in the cache.
+     *
+     * @param key - The key to check
+     * @returns true if the key exists, false otherwise
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Returns all keys currently in the cache.
+     *
+     * @returns Array of keys
+     */
+    keys(): Promise<string[]>;
+    /**
+     * Returns the number of items in the cache.
+     *
+     * @returns The number of items
+     */
+    size(): Promise<number>;
+    /**
+     * Retrieves a value from the cache without affecting its TTL or last accessed time.
+     *
+     * @param key - The key to peek at
+     * @returns The value if found, undefined if not found
+     */
+    peek(key: string): Promise<TValue | undefined>;
+    /**
+     * Retrieves multiple values from the cache in a single operation.
+     *
+     * @param keys - Array of keys to retrieve
+     * @returns Object mapping keys to their values (or undefined if not found)
+     */
+    mget(keys: string[]): Promise<Record<string, TValue | undefined>>;
+    /**
+     * Stores multiple values in the cache in a single operation.
+     * - If a value is undefined, it will not be stored in the cache.
+     * - If a value is null, it will be stored in the cache.
+     *
+     * @param entries - Array of entries to store, each with key, value, and optional TTL (if not provided, the value will not expire)
+     * @throws Error if any entry's ttlMilliseconds is not a number, is negative, or is greater than 2^53 - 1
+     */
+    mset(entries: {
+        key: string;
+        value: TValue;
+        ttlMilliseconds?: number;
+    }[]): Promise<void>;
+    /**
+     * Removes multiple values from the cache.
+     *
+     * @param keys - Array of keys to remove
+     * @returns An object mapping each key to a boolean indicating whether it was found and removed
+     */
+    mdelete(keys: string[]): Promise<Record<string, boolean>>;
+};
+//# sourceMappingURL=types.d.mts.map

package/dist/utils/cache/types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.mts","sourceRoot":"","sources":["../../../src/utils/cache/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,mCAA+B;AAE3D,MAAM,MAAM,qBAAqB,GAAG,MAAM,CAAC;AAE3C;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,KAAK,EAAE,YAAY,CAAC;IACpB,SAAS,EAAE,qBAAqB,CAAC;CAClC,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,MAAM,CAAC,MAAM,IAAI;IAC3B;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAE9C;;;;;;;;;OASG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzE;;;;;OAKG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEtC;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEnC;;;;OAIG;IACH,IAAI,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAE1B;;;;OAIG;IACH,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAExB;;;;;OAKG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAE/C;;;;;OAKG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IAElE;;;;;;;OAOG;IACH,IAAI,CACF,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,eAAe,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,GAClE,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;;;OAKG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC3D,CAAC"}

package/dist/utils/cache/types.mjs

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.mjs.map

package/dist/utils/cache/types.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.mjs","sourceRoot":"","sources":["../../../src/utils/cache/types.ts"],"names":[],"mappings":"","sourcesContent":["import type { Serializable } from '../serialization/types';\n\nexport type TimestampMilliseconds = number;\n\n/**\n * A single cache entry.\n */\nexport type CacheEntry = {\n  value: Serializable;\n  expiresAt: TimestampMilliseconds;\n};\n\n/**\n * Interface for a generic cache implementation.\n *\n * @template TValue - The type of values stored in the cache\n */\nexport type ICache<TValue> = {\n  /**\n   * Retrieves a value from the cache by key.\n   *\n   * @param key - The key to retrieve\n   * @returns The value if found, undefined if not found\n   */\n  get(key: string): Promise<TValue | undefined>;\n\n  /**\n   * Stores a value in the cache with an optional TTL.\n   * - If a value is undefined, it will not be stored in the cache.\n   * - If a value is null, it will be stored in the cache.\n   *\n   * @param key - The key to store the value under\n   * @param value - The value to store\n   * @param ttlMilliseconds - Optional time-to-live in milliseconds. If not provided, the value will not expire.\n   * @throws Error if any entry's ttlMilliseconds is not a number, is negative, or is greater than 2^53 - 1\n   */\n  set(key: string, value: TValue, ttlMilliseconds?: number): Promise<void>;\n\n  /**\n   * Removes a value from the cache.\n   *\n   * @param key - The key to remove\n   * @returns true if the key was found and removed, false otherwise\n   */\n  delete(key: string): Promise<boolean>;\n\n  /**\n   * Removes all values from the cache.\n   */\n  clear(): Promise<void>;\n\n  /**\n   * Checks if a key exists in the cache.\n   *\n   * @param key - The key to check\n   * @returns true if the key exists, false otherwise\n   */\n  has(key: string): Promise<boolean>;\n\n  /**\n   * Returns all keys currently in the cache.\n   *\n   * @returns Array of keys\n   */\n  keys(): Promise<string[]>;\n\n  /**\n   * Returns the number of items in the cache.\n   *\n   * @returns The number of items\n   */\n  size(): Promise<number>;\n\n  /**\n   * Retrieves a value from the cache without affecting its TTL or last accessed time.\n   *\n   * @param key - The key to peek at\n   * @returns The value if found, undefined if not found\n   */\n  peek(key: string): Promise<TValue | undefined>;\n\n  /**\n   * Retrieves multiple values from the cache in a single operation.\n   *\n   * @param keys - Array of keys to retrieve\n   * @returns Object mapping keys to their values (or undefined if not found)\n   */\n  mget(keys: string[]): Promise<Record<string, TValue | undefined>>;\n\n  /**\n   * Stores multiple values in the cache in a single operation.\n   * - If a value is undefined, it will not be stored in the cache.\n   * - If a value is null, it will be stored in the cache.\n   *\n   * @param entries - Array of entries to store, each with key, value, and optional TTL (if not provided, the value will not expire)\n   * @throws Error if any entry's ttlMilliseconds is not a number, is negative, or is greater than 2^53 - 1\n   */\n  mset(\n    entries: { key: string; value: TValue; ttlMilliseconds?: number }[],\n  ): Promise<void>;\n\n  /**\n   * Removes multiple values from the cache.\n   *\n   * @param keys - Array of keys to remove\n   * @returns An object mapping each key to a boolean indicating whether it was found and removed\n   */\n  mdelete(keys: string[]): Promise<Record<string, boolean>>;\n};\n"]}

package/dist/utils/cache/useCache.cjs

@@ -0,0 +1,82 @@
+"use strict";
+/* eslint-disable no-void */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useCache = void 0;
+const Logger_1 = require("../logger/Logger.cjs");
+const serialization_1 = require("../serialization/serialization.cjs");
+/**
+ * A logger that discards all messages, used when no logger is provided.
+ */
+const silentLogger = new Logger_1.Logger({ level: Logger_1.LogLevel.SILENT });
+/**
+ * Default function to generate the cache key for a function call.
+ *
+ * @param functionName - The name of the function.
+ * @param args - The arguments of the function call.
+ * @returns The cache key.
+ */
+const defaultGenerateCacheKey = (functionName, args) => `${functionName}:${args.map((arg) => JSON.stringify((0, serialization_1.serialize)(arg))).join(':')}`;
+/**
+ * Wraps a function with caching behavior.
+ *
+ * WARNINGS:
+ * - The cache write is fire-and-forget (not awaited). This is only safe with
+ *   caches whose writes are effectively instantaneous, such as
+ *   `InMemoryCache`. Do not pair this wrapper with a mutex-guarded, persisted
+ *   cache such as `StateCache`: unawaited state writes accumulate without
+ *   backpressure, the state mutex queue grows without bound under sustained
+ *   traffic, and foreground state operations eventually hit the snap's RPC
+ *   timeout. Use `useCacheUntil` (which awaits its write) with a persisted
+ *   cache instead.
+ *
+ * @template TArgs - Tuple type representing the arguments of the function.
+ * @template TResult - The return type of the function, must be Serializable.
+ * @param fn - The asynchronous function to wrap. Must return a Promise<Serializable>.
+ * @param cache - The cache instance to use.
+ * @param options - The caching options.
+ * @param options.ttlMilliseconds - The time to live for the cache in milliseconds.
+ * @param options.refreshCache - Whether to refresh the cache.
+ * @param options.functionName - The name of the function.
+ * @param options.generateCacheKey - Optional function to generate the cache key.
+ * @param options.logger - Optional logger for cache errors.
+ * @returns A new asynchronous function with caching behavior.
+ */
+const useCache = (fn, cache, { ttlMilliseconds, functionName, generateCacheKey, refreshCache = false, logger = silentLogger, }) => {
+    // Use provided key generator or default, adapting the default to use the function's name
+    const _generateCacheKey = generateCacheKey ?? defaultGenerateCacheKey;
+    // Get the function name for the default key generator, handle anonymous functions
+    const _functionName = functionName ?? fn.name ?? 'anonymousFunction';
+    return async (...args) => {
+        const cacheKey = _generateCacheKey(_functionName, args);
+        // Check if the data is cached
+        if (!refreshCache) {
+            try {
+                const cached = await cache.get(cacheKey);
+                // Check explicitly for undefined, as null or other falsy values might be valid cache results
+                if (cached !== undefined) {
+                    // Type assertion because cache stores Serializable, but we expect TResult
+                    return cached;
+                }
+            }
+            catch (error) {
+                // Log cache get errors but proceed to execute the function
+                logger.error(`Cache get error for key "${cacheKey}":`, error);
+            }
+        }
+        // Execute the original function
+        const result = await fn(...args);
+        // Cache the result, handling potential errors silently.
+        // Fire-and-forget: we don't await this, allowing it to happen in the
+        // background. This is safe only because the snaps pair this wrapper with
+        // `InMemoryCache` (writes resolve in a microtask). With a mutex-guarded
+        // persisted cache such as `StateCache`, unawaited writes would accumulate
+        // without backpressure and starve foreground state operations — see the
+        // warnings in this function's documentation.
+        void cache.set(cacheKey, result, ttlMilliseconds).catch((error) => {
+            logger.error(`Cache set error for key "${cacheKey}":`, error);
+        });
+        return result;
+    };
+};
+exports.useCache = useCache;
+//# sourceMappingURL=useCache.cjs.map

package/dist/utils/cache/useCache.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCache.cjs","sourceRoot":"","sources":["../../../src/utils/cache/useCache.ts"],"names":[],"mappings":";AAAA,4BAA4B;;;AAE5B,iDAAoD;AACpD,sEAA2D;AAI3D;;GAEG;AACH,MAAM,YAAY,GAAG,IAAI,eAAM,CAAC,EAAE,KAAK,EAAE,iBAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;AA8B5D;;;;;;GAMG;AACH,MAAM,uBAAuB,GAAG,CAC9B,YAAoB,EACpB,IAAoB,EACZ,EAAE,CACV,GAAG,YAAY,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,IAAA,yBAAS,EAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;AAEnF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACI,MAAM,QAAQ,GAAG,CAItB,EAAwC,EACxC,KAA2B,EAC3B,EACE,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,YAAY,GAAG,KAAK,EACpB,MAAM,GAAG,YAAY,GACR,EACyB,EAAE;IAC1C,yFAAyF;IACzF,MAAM,iBAAiB,GAAG,gBAAgB,IAAI,uBAAuB,CAAC;IAEtE,kFAAkF;IAClF,MAAM,aAAa,GAAG,YAAY,IAAI,EAAE,CAAC,IAAI,IAAI,mBAAmB,CAAC;IAErE,OAAO,KAAK,EAAE,GAAG,IAAW,EAAoB,EAAE;QAChD,MAAM,QAAQ,GAAG,iBAAiB,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;QACxD,8BAA8B;QAC9B,IAAI,CAAC,YAAY,EAAE,CAAC;YAClB,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;gBACzC,6FAA6F;gBAC7F,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;oBACzB,0EAA0E;oBAC1E,OAAO,MAAiB,CAAC;gBAC3B,CAAC;YACH,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,2DAA2D;gBAC3D,MAAM,CAAC,KAAK,CAAC,4BAA4B,QAAQ,IAAI,EAAE,KAAK,CAAC,CAAC;YAChE,CAAC;QACH,CAAC;QAED,gCAAgC;QAChC,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;QAEjC,wDAAwD;QACxD,qEAAqE;QACrE,yEAAyE;QACzE,wEAAwE;QACxE,0EAA0E;QAC1E,wEAAwE;QACxE,6CAA6C;QAC7C,KAAK,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,eAAe,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;YAChE,MAAM,CAAC,KAAK,CAAC,4BAA4B,QAAQ,IAAI,EAAE,KAAK,CAAC,CAAC;QAChE,CAAC,CAAC,CAAC;QAEH,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC,CAAC;AArDW,QAAA,QAAQ,YAqDnB","sourcesContent":["/* eslint-disable no-void */\n\nimport { Logger, LogLevel } from '../logger/Logger';\nimport { serialize } from '../serialization/serialization';\nimport type { Serializable } from '../serialization/types';\nimport type { ICache } from './types';\n\n/**\n * A logger that discards all messages, used when no logger is provided.\n */\nconst silentLogger = new Logger({ level: LogLevel.SILENT });\n\n/**\n * Options for configuring the caching behavior of a function.\n */\nexport type CacheOptions = {\n  /**\n   * The time to live for the cache in milliseconds.\n   */\n  ttlMilliseconds: number;\n  /**\n   * Set this if you want to use a custom function name for the cache key.\n   */\n  functionName?: string;\n  /**\n   * Optional function to generate the cache key for the function call.\n   * Defaults to a function that generates the key based on function name and JSON stringified args separated by colons.\n   */\n  generateCacheKey?: (functionName: string, args: Serializable[]) => string;\n  /**\n   * Whether to refresh the cache.\n   * Defaults to false.\n   */\n  refreshCache?: boolean;\n  /**\n   * Optional logger for cache errors. Defaults to a silent logger.\n   */\n  logger?: Logger;\n};\n\n/**\n * Default function to generate the cache key for a function call.\n *\n * @param functionName - The name of the function.\n * @param args - The arguments of the function call.\n * @returns The cache key.\n */\nconst defaultGenerateCacheKey = (\n  functionName: string,\n  args: Serializable[],\n): string =>\n  `${functionName}:${args.map((arg) => JSON.stringify(serialize(arg))).join(':')}`;\n\n/**\n * Wraps a function with caching behavior.\n *\n * WARNINGS:\n * - The cache write is fire-and-forget (not awaited). This is only safe with\n *   caches whose writes are effectively instantaneous, such as\n *   `InMemoryCache`. Do not pair this wrapper with a mutex-guarded, persisted\n *   cache such as `StateCache`: unawaited state writes accumulate without\n *   backpressure, the state mutex queue grows without bound under sustained\n *   traffic, and foreground state operations eventually hit the snap's RPC\n *   timeout. Use `useCacheUntil` (which awaits its write) with a persisted\n *   cache instead.\n *\n * @template TArgs - Tuple type representing the arguments of the function.\n * @template TResult - The return type of the function, must be Serializable.\n * @param fn - The asynchronous function to wrap. Must return a Promise<Serializable>.\n * @param cache - The cache instance to use.\n * @param options - The caching options.\n * @param options.ttlMilliseconds - The time to live for the cache in milliseconds.\n * @param options.refreshCache - Whether to refresh the cache.\n * @param options.functionName - The name of the function.\n * @param options.generateCacheKey - Optional function to generate the cache key.\n * @param options.logger - Optional logger for cache errors.\n * @returns A new asynchronous function with caching behavior.\n */\nexport const useCache = <\n  TArgs extends Serializable[],\n  TResult extends Serializable,\n>(\n  fn: (...args: TArgs) => Promise<TResult>,\n  cache: ICache<Serializable>,\n  {\n    ttlMilliseconds,\n    functionName,\n    generateCacheKey,\n    refreshCache = false,\n    logger = silentLogger,\n  }: CacheOptions,\n): ((...args: TArgs) => Promise<TResult>) => {\n  // Use provided key generator or default, adapting the default to use the function's name\n  const _generateCacheKey = generateCacheKey ?? defaultGenerateCacheKey;\n\n  // Get the function name for the default key generator, handle anonymous functions\n  const _functionName = functionName ?? fn.name ?? 'anonymousFunction';\n\n  return async (...args: TArgs): Promise<TResult> => {\n    const cacheKey = _generateCacheKey(_functionName, args);\n    // Check if the data is cached\n    if (!refreshCache) {\n      try {\n        const cached = await cache.get(cacheKey);\n        // Check explicitly for undefined, as null or other falsy values might be valid cache results\n        if (cached !== undefined) {\n          // Type assertion because cache stores Serializable, but we expect TResult\n          return cached as TResult;\n        }\n      } catch (error) {\n        // Log cache get errors but proceed to execute the function\n        logger.error(`Cache get error for key \"${cacheKey}\":`, error);\n      }\n    }\n\n    // Execute the original function\n    const result = await fn(...args);\n\n    // Cache the result, handling potential errors silently.\n    // Fire-and-forget: we don't await this, allowing it to happen in the\n    // background. This is safe only because the snaps pair this wrapper with\n    // `InMemoryCache` (writes resolve in a microtask). With a mutex-guarded\n    // persisted cache such as `StateCache`, unawaited writes would accumulate\n    // without backpressure and starve foreground state operations — see the\n    // warnings in this function's documentation.\n    void cache.set(cacheKey, result, ttlMilliseconds).catch((error) => {\n      logger.error(`Cache set error for key \"${cacheKey}\":`, error);\n    });\n\n    return result;\n  };\n};\n"]}

package/dist/utils/cache/useCache.d.cts

@@ -0,0 +1,57 @@
+import { Logger } from "../logger/Logger.cjs";
+import type { Serializable } from "../serialization/types.cjs";
+import type { ICache } from "./types.cjs";
+/**
+ * Options for configuring the caching behavior of a function.
+ */
+export type CacheOptions = {
+    /**
+     * The time to live for the cache in milliseconds.
+     */
+    ttlMilliseconds: number;
+    /**
+     * Set this if you want to use a custom function name for the cache key.
+     */
+    functionName?: string;
+    /**
+     * Optional function to generate the cache key for the function call.
+     * Defaults to a function that generates the key based on function name and JSON stringified args separated by colons.
+     */
+    generateCacheKey?: (functionName: string, args: Serializable[]) => string;
+    /**
+     * Whether to refresh the cache.
+     * Defaults to false.
+     */
+    refreshCache?: boolean;
+    /**
+     * Optional logger for cache errors. Defaults to a silent logger.
+     */
+    logger?: Logger;
+};
+/**
+ * Wraps a function with caching behavior.
+ *
+ * WARNINGS:
+ * - The cache write is fire-and-forget (not awaited). This is only safe with
+ *   caches whose writes are effectively instantaneous, such as
+ *   `InMemoryCache`. Do not pair this wrapper with a mutex-guarded, persisted
+ *   cache such as `StateCache`: unawaited state writes accumulate without
+ *   backpressure, the state mutex queue grows without bound under sustained
+ *   traffic, and foreground state operations eventually hit the snap's RPC
+ *   timeout. Use `useCacheUntil` (which awaits its write) with a persisted
+ *   cache instead.
+ *
+ * @template TArgs - Tuple type representing the arguments of the function.
+ * @template TResult - The return type of the function, must be Serializable.
+ * @param fn - The asynchronous function to wrap. Must return a Promise<Serializable>.
+ * @param cache - The cache instance to use.
+ * @param options - The caching options.
+ * @param options.ttlMilliseconds - The time to live for the cache in milliseconds.
+ * @param options.refreshCache - Whether to refresh the cache.
+ * @param options.functionName - The name of the function.
+ * @param options.generateCacheKey - Optional function to generate the cache key.
+ * @param options.logger - Optional logger for cache errors.
+ * @returns A new asynchronous function with caching behavior.
+ */
+export declare const useCache: <TArgs extends Serializable[], TResult extends Serializable>(fn: (...args: TArgs) => Promise<TResult>, cache: ICache<Serializable>, { ttlMilliseconds, functionName, generateCacheKey, refreshCache, logger, }: CacheOptions) => ((...args: TArgs) => Promise<TResult>);
+//# sourceMappingURL=useCache.d.cts.map

package/dist/utils/cache/useCache.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCache.d.cts","sourceRoot":"","sources":["../../../src/utils/cache/useCache.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAY,6BAAyB;AAEpD,OAAO,KAAK,EAAE,YAAY,EAAE,mCAA+B;AAC3D,OAAO,KAAK,EAAE,MAAM,EAAE,oBAAgB;AAOtC;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB;;OAEG;IACH,eAAe,EAAE,MAAM,CAAC;IACxB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,MAAM,CAAC;IAC1E;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAeF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,QAAQ,GACnB,KAAK,SAAS,YAAY,EAAE,EAC5B,OAAO,SAAS,YAAY,EAE5B,IAAI,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,OAAO,CAAC,EACxC,OAAO,MAAM,CAAC,YAAY,CAAC,EAC3B,4EAMG,YAAY,KACd,CAAC,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,OAAO,CAAC,CAwCvC,CAAC"}

package/dist/utils/cache/useCache.d.mts

@@ -0,0 +1,57 @@
+import { Logger } from "../logger/Logger.mjs";
+import type { Serializable } from "../serialization/types.mjs";
+import type { ICache } from "./types.mjs";
+/**
+ * Options for configuring the caching behavior of a function.
+ */
+export type CacheOptions = {
+    /**
+     * The time to live for the cache in milliseconds.
+     */
+    ttlMilliseconds: number;
+    /**
+     * Set this if you want to use a custom function name for the cache key.
+     */
+    functionName?: string;
+    /**
+     * Optional function to generate the cache key for the function call.
+     * Defaults to a function that generates the key based on function name and JSON stringified args separated by colons.
+     */
+    generateCacheKey?: (functionName: string, args: Serializable[]) => string;
+    /**
+     * Whether to refresh the cache.
+     * Defaults to false.
+     */
+    refreshCache?: boolean;
+    /**
+     * Optional logger for cache errors. Defaults to a silent logger.
+     */
+    logger?: Logger;
+};
+/**
+ * Wraps a function with caching behavior.
+ *
+ * WARNINGS:
+ * - The cache write is fire-and-forget (not awaited). This is only safe with
+ *   caches whose writes are effectively instantaneous, such as
+ *   `InMemoryCache`. Do not pair this wrapper with a mutex-guarded, persisted
+ *   cache such as `StateCache`: unawaited state writes accumulate without
+ *   backpressure, the state mutex queue grows without bound under sustained
+ *   traffic, and foreground state operations eventually hit the snap's RPC
+ *   timeout. Use `useCacheUntil` (which awaits its write) with a persisted
+ *   cache instead.
+ *
+ * @template TArgs - Tuple type representing the arguments of the function.
+ * @template TResult - The return type of the function, must be Serializable.
+ * @param fn - The asynchronous function to wrap. Must return a Promise<Serializable>.
+ * @param cache - The cache instance to use.
+ * @param options - The caching options.
+ * @param options.ttlMilliseconds - The time to live for the cache in milliseconds.
+ * @param options.refreshCache - Whether to refresh the cache.
+ * @param options.functionName - The name of the function.
+ * @param options.generateCacheKey - Optional function to generate the cache key.
+ * @param options.logger - Optional logger for cache errors.
+ * @returns A new asynchronous function with caching behavior.
+ */
+export declare const useCache: <TArgs extends Serializable[], TResult extends Serializable>(fn: (...args: TArgs) => Promise<TResult>, cache: ICache<Serializable>, { ttlMilliseconds, functionName, generateCacheKey, refreshCache, logger, }: CacheOptions) => ((...args: TArgs) => Promise<TResult>);
+//# sourceMappingURL=useCache.d.mts.map

package/dist/utils/cache/useCache.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCache.d.mts","sourceRoot":"","sources":["../../../src/utils/cache/useCache.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAY,6BAAyB;AAEpD,OAAO,KAAK,EAAE,YAAY,EAAE,mCAA+B;AAC3D,OAAO,KAAK,EAAE,MAAM,EAAE,oBAAgB;AAOtC;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB;;OAEG;IACH,eAAe,EAAE,MAAM,CAAC;IACxB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,MAAM,CAAC;IAC1E;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAeF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,QAAQ,GACnB,KAAK,SAAS,YAAY,EAAE,EAC5B,OAAO,SAAS,YAAY,EAE5B,IAAI,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,OAAO,CAAC,EACxC,OAAO,MAAM,CAAC,YAAY,CAAC,EAC3B,4EAMG,YAAY,KACd,CAAC,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,OAAO,CAAC,CAwCvC,CAAC"}

package/dist/utils/cache/useCache.mjs

@@ -0,0 +1,78 @@
+/* eslint-disable no-void */
+import { Logger, LogLevel } from "../logger/Logger.mjs";
+import { serialize } from "../serialization/serialization.mjs";
+/**
+ * A logger that discards all messages, used when no logger is provided.
+ */
+const silentLogger = new Logger({ level: LogLevel.SILENT });
+/**
+ * Default function to generate the cache key for a function call.
+ *
+ * @param functionName - The name of the function.
+ * @param args - The arguments of the function call.
+ * @returns The cache key.
+ */
+const defaultGenerateCacheKey = (functionName, args) => `${functionName}:${args.map((arg) => JSON.stringify(serialize(arg))).join(':')}`;
+/**
+ * Wraps a function with caching behavior.
+ *
+ * WARNINGS:
+ * - The cache write is fire-and-forget (not awaited). This is only safe with
+ *   caches whose writes are effectively instantaneous, such as
+ *   `InMemoryCache`. Do not pair this wrapper with a mutex-guarded, persisted
+ *   cache such as `StateCache`: unawaited state writes accumulate without
+ *   backpressure, the state mutex queue grows without bound under sustained
+ *   traffic, and foreground state operations eventually hit the snap's RPC
+ *   timeout. Use `useCacheUntil` (which awaits its write) with a persisted
+ *   cache instead.
+ *
+ * @template TArgs - Tuple type representing the arguments of the function.
+ * @template TResult - The return type of the function, must be Serializable.
+ * @param fn - The asynchronous function to wrap. Must return a Promise<Serializable>.
+ * @param cache - The cache instance to use.
+ * @param options - The caching options.
+ * @param options.ttlMilliseconds - The time to live for the cache in milliseconds.
+ * @param options.refreshCache - Whether to refresh the cache.
+ * @param options.functionName - The name of the function.
+ * @param options.generateCacheKey - Optional function to generate the cache key.
+ * @param options.logger - Optional logger for cache errors.
+ * @returns A new asynchronous function with caching behavior.
+ */
+export const useCache = (fn, cache, { ttlMilliseconds, functionName, generateCacheKey, refreshCache = false, logger = silentLogger, }) => {
+    // Use provided key generator or default, adapting the default to use the function's name
+    const _generateCacheKey = generateCacheKey ?? defaultGenerateCacheKey;
+    // Get the function name for the default key generator, handle anonymous functions
+    const _functionName = functionName ?? fn.name ?? 'anonymousFunction';
+    return async (...args) => {
+        const cacheKey = _generateCacheKey(_functionName, args);
+        // Check if the data is cached
+        if (!refreshCache) {
+            try {
+                const cached = await cache.get(cacheKey);
+                // Check explicitly for undefined, as null or other falsy values might be valid cache results
+                if (cached !== undefined) {
+                    // Type assertion because cache stores Serializable, but we expect TResult
+                    return cached;
+                }
+            }
+            catch (error) {
+                // Log cache get errors but proceed to execute the function
+                logger.error(`Cache get error for key "${cacheKey}":`, error);
+            }
+        }
+        // Execute the original function
+        const result = await fn(...args);
+        // Cache the result, handling potential errors silently.
+        // Fire-and-forget: we don't await this, allowing it to happen in the
+        // background. This is safe only because the snaps pair this wrapper with
+        // `InMemoryCache` (writes resolve in a microtask). With a mutex-guarded
+        // persisted cache such as `StateCache`, unawaited writes would accumulate
+        // without backpressure and starve foreground state operations — see the
+        // warnings in this function's documentation.
+        void cache.set(cacheKey, result, ttlMilliseconds).catch((error) => {
+            logger.error(`Cache set error for key "${cacheKey}":`, error);
+        });
+        return result;
+    };
+};
+//# sourceMappingURL=useCache.mjs.map

package/dist/utils/cache/useCache.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCache.mjs","sourceRoot":"","sources":["../../../src/utils/cache/useCache.ts"],"names":[],"mappings":"AAAA,4BAA4B;AAE5B,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,6BAAyB;AACpD,OAAO,EAAE,SAAS,EAAE,2CAAuC;AAI3D;;GAEG;AACH,MAAM,YAAY,GAAG,IAAI,MAAM,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;AA8B5D;;;;;;GAMG;AACH,MAAM,uBAAuB,GAAG,CAC9B,YAAoB,EACpB,IAAoB,EACZ,EAAE,CACV,GAAG,YAAY,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;AAEnF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAItB,EAAwC,EACxC,KAA2B,EAC3B,EACE,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,YAAY,GAAG,KAAK,EACpB,MAAM,GAAG,YAAY,GACR,EACyB,EAAE;IAC1C,yFAAyF;IACzF,MAAM,iBAAiB,GAAG,gBAAgB,IAAI,uBAAuB,CAAC;IAEtE,kFAAkF;IAClF,MAAM,aAAa,GAAG,YAAY,IAAI,EAAE,CAAC,IAAI,IAAI,mBAAmB,CAAC;IAErE,OAAO,KAAK,EAAE,GAAG,IAAW,EAAoB,EAAE;QAChD,MAAM,QAAQ,GAAG,iBAAiB,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;QACxD,8BAA8B;QAC9B,IAAI,CAAC,YAAY,EAAE,CAAC;YAClB,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;gBACzC,6FAA6F;gBAC7F,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;oBACzB,0EAA0E;oBAC1E,OAAO,MAAiB,CAAC;gBAC3B,CAAC;YACH,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,2DAA2D;gBAC3D,MAAM,CAAC,KAAK,CAAC,4BAA4B,QAAQ,IAAI,EAAE,KAAK,CAAC,CAAC;YAChE,CAAC;QACH,CAAC;QAED,gCAAgC;QAChC,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;QAEjC,wDAAwD;QACxD,qEAAqE;QACrE,yEAAyE;QACzE,wEAAwE;QACxE,0EAA0E;QAC1E,wEAAwE;QACxE,6CAA6C;QAC7C,KAAK,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,eAAe,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;YAChE,MAAM,CAAC,KAAK,CAAC,4BAA4B,QAAQ,IAAI,EAAE,KAAK,CAAC,CAAC;QAChE,CAAC,CAAC,CAAC;QAEH,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC,CAAC","sourcesContent":["/* eslint-disable no-void */\n\nimport { Logger, LogLevel } from '../logger/Logger';\nimport { serialize } from '../serialization/serialization';\nimport type { Serializable } from '../serialization/types';\nimport type { ICache } from './types';\n\n/**\n * A logger that discards all messages, used when no logger is provided.\n */\nconst silentLogger = new Logger({ level: LogLevel.SILENT });\n\n/**\n * Options for configuring the caching behavior of a function.\n */\nexport type CacheOptions = {\n  /**\n   * The time to live for the cache in milliseconds.\n   */\n  ttlMilliseconds: number;\n  /**\n   * Set this if you want to use a custom function name for the cache key.\n   */\n  functionName?: string;\n  /**\n   * Optional function to generate the cache key for the function call.\n   * Defaults to a function that generates the key based on function name and JSON stringified args separated by colons.\n   */\n  generateCacheKey?: (functionName: string, args: Serializable[]) => string;\n  /**\n   * Whether to refresh the cache.\n   * Defaults to false.\n   */\n  refreshCache?: boolean;\n  /**\n   * Optional logger for cache errors. Defaults to a silent logger.\n   */\n  logger?: Logger;\n};\n\n/**\n * Default function to generate the cache key for a function call.\n *\n * @param functionName - The name of the function.\n * @param args - The arguments of the function call.\n * @returns The cache key.\n */\nconst defaultGenerateCacheKey = (\n  functionName: string,\n  args: Serializable[],\n): string =>\n  `${functionName}:${args.map((arg) => JSON.stringify(serialize(arg))).join(':')}`;\n\n/**\n * Wraps a function with caching behavior.\n *\n * WARNINGS:\n * - The cache write is fire-and-forget (not awaited). This is only safe with\n *   caches whose writes are effectively instantaneous, such as\n *   `InMemoryCache`. Do not pair this wrapper with a mutex-guarded, persisted\n *   cache such as `StateCache`: unawaited state writes accumulate without\n *   backpressure, the state mutex queue grows without bound under sustained\n *   traffic, and foreground state operations eventually hit the snap's RPC\n *   timeout. Use `useCacheUntil` (which awaits its write) with a persisted\n *   cache instead.\n *\n * @template TArgs - Tuple type representing the arguments of the function.\n * @template TResult - The return type of the function, must be Serializable.\n * @param fn - The asynchronous function to wrap. Must return a Promise<Serializable>.\n * @param cache - The cache instance to use.\n * @param options - The caching options.\n * @param options.ttlMilliseconds - The time to live for the cache in milliseconds.\n * @param options.refreshCache - Whether to refresh the cache.\n * @param options.functionName - The name of the function.\n * @param options.generateCacheKey - Optional function to generate the cache key.\n * @param options.logger - Optional logger for cache errors.\n * @returns A new asynchronous function with caching behavior.\n */\nexport const useCache = <\n  TArgs extends Serializable[],\n  TResult extends Serializable,\n>(\n  fn: (...args: TArgs) => Promise<TResult>,\n  cache: ICache<Serializable>,\n  {\n    ttlMilliseconds,\n    functionName,\n    generateCacheKey,\n    refreshCache = false,\n    logger = silentLogger,\n  }: CacheOptions,\n): ((...args: TArgs) => Promise<TResult>) => {\n  // Use provided key generator or default, adapting the default to use the function's name\n  const _generateCacheKey = generateCacheKey ?? defaultGenerateCacheKey;\n\n  // Get the function name for the default key generator, handle anonymous functions\n  const _functionName = functionName ?? fn.name ?? 'anonymousFunction';\n\n  return async (...args: TArgs): Promise<TResult> => {\n    const cacheKey = _generateCacheKey(_functionName, args);\n    // Check if the data is cached\n    if (!refreshCache) {\n      try {\n        const cached = await cache.get(cacheKey);\n        // Check explicitly for undefined, as null or other falsy values might be valid cache results\n        if (cached !== undefined) {\n          // Type assertion because cache stores Serializable, but we expect TResult\n          return cached as TResult;\n        }\n      } catch (error) {\n        // Log cache get errors but proceed to execute the function\n        logger.error(`Cache get error for key \"${cacheKey}\":`, error);\n      }\n    }\n\n    // Execute the original function\n    const result = await fn(...args);\n\n    // Cache the result, handling potential errors silently.\n    // Fire-and-forget: we don't await this, allowing it to happen in the\n    // background. This is safe only because the snaps pair this wrapper with\n    // `InMemoryCache` (writes resolve in a microtask). With a mutex-guarded\n    // persisted cache such as `StateCache`, unawaited writes would accumulate\n    // without backpressure and starve foreground state operations — see the\n    // warnings in this function's documentation.\n    void cache.set(cacheKey, result, ttlMilliseconds).catch((error) => {\n      logger.error(`Cache set error for key \"${cacheKey}\":`, error);\n    });\n\n    return result;\n  };\n};\n"]}

package/dist/utils/cache/useCacheUntil.cjs

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useCacheUntil = void 0;
+const Logger_1 = require("../logger/Logger.cjs");
+const serialization_1 = require("../serialization/serialization.cjs");
+/**
+ * A logger that discards all messages, used when no logger is provided.
+ */
+const silentLogger = new Logger_1.Logger({ level: Logger_1.LogLevel.SILENT });
+/**
+ * Default function to generate the cache key for a function call.
+ *
+ * @param functionName - The name of the function.
+ * @param args - The arguments of the function call.
+ * @returns The cache key.
+ */
+const defaultGenerateCacheKey = (functionName, args) => `${functionName}:${args.map((arg) => JSON.stringify((0, serialization_1.serialize)(arg))).join(':')}`;
+/**
+ * Wraps an async function with caching behavior where expiry is determined
+ * by the function result itself (dynamic TTL).
+ *
+ * Unlike `useCache` which uses a fixed TTL, this utility allows the wrapped
+ * function to specify when its result expires. This is useful for caching
+ * data that has known invalidation points (e.g., blockchain maintenance periods).
+ *
+ * @template TArgs - Tuple type representing the arguments of the function.
+ * @template TResult - The return type of the function, must be Serializable.
+ * @param fn - The asynchronous function to wrap. Must return a Promise<ResultWithExpiry<TResult>>.
+ * @param cache - The cache instance to use.
+ * @param options - The caching options.
+ * @param options.refreshCache - Whether to refresh the cache.
+ * @param options.functionName - The name of the function.
+ * @param options.generateCacheKey - Optional function to generate the cache key.
+ * @param options.logger - Optional logger for cache errors.
+ * @returns A new asynchronous function with caching behavior.
+ */
+const useCacheUntil = (fn, cache, { functionName, generateCacheKey, refreshCache = false, logger = silentLogger, }) => {
+    // Use provided key generator or default, adapting the default to use the function's name
+    const _generateCacheKey = generateCacheKey ?? defaultGenerateCacheKey;
+    // Get the function name for the default key generator, handle anonymous functions
+    const _functionName = functionName ?? fn.name ?? 'anonymousFunction';
+    // Map to track expiry timestamps for each cache key
+    const expiryMap = new Map();
+    return async (...args) => {
+        const cacheKey = _generateCacheKey(_functionName, args);
+        const now = Date.now();
+        // Check if cached and not expired.
+        // The cache owns the persisted TTL. When this wrapper is recreated after a
+        // Snap restart, expiryMap is empty, so consult the cache to hydrate a still
+        // valid entry instead of fetching it again.
+        const expiresAt = expiryMap.get(cacheKey);
+        if (!refreshCache && (expiresAt === undefined || now < expiresAt)) {
+            try {
+                const cached = await cache.get(cacheKey);
+                // Check explicitly for undefined, as null or other falsy values might be valid cache results
+                if (cached !== undefined) {
+                    // Type assertion because cache stores Serializable, but we expect TResult
+                    return cached;
+                }
+            }
+            catch (error) {
+                // Log cache get errors but proceed to execute the function
+                logger.error(`Cache get error for key "${cacheKey}":`, error);
+            }
+        }
+        // Execute the original function to get result and new expiry
+        const { result, expiresAt: newExpiresAt } = await fn(...args);
+        // Calculate TTL from expiry timestamp
+        const ttlMilliseconds = Math.max(0, newExpiresAt - now);
+        // Store result in cache with calculated TTL
+        await cache.set(cacheKey, result, ttlMilliseconds).catch((error) => {
+            logger.error(`Cache set error for key "${cacheKey}":`, error);
+        });
+        // Store expiry timestamp
+        expiryMap.set(cacheKey, newExpiresAt);
+        return result;
+    };
+};
+exports.useCacheUntil = useCacheUntil;
+//# sourceMappingURL=useCacheUntil.cjs.map

package/dist/utils/cache/useCacheUntil.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCacheUntil.cjs","sourceRoot":"","sources":["../../../src/utils/cache/useCacheUntil.ts"],"names":[],"mappings":";;;AAAA,iDAAoD;AACpD,sEAA2D;AAI3D;;GAEG;AACH,MAAM,YAAY,GAAG,IAAI,eAAM,CAAC,EAAE,KAAK,EAAE,iBAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;AAkC5D;;;;;;GAMG;AACH,MAAM,uBAAuB,GAAG,CAC9B,YAAoB,EACpB,IAAoB,EACZ,EAAE,CACV,GAAG,YAAY,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,IAAA,yBAAS,EAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;AAEnF;;;;;;;;;;;;;;;;;;GAkBG;AACI,MAAM,aAAa,GAAG,CAI3B,EAA0D,EAC1D,KAA2B,EAC3B,EACE,YAAY,EACZ,gBAAgB,EAChB,YAAY,GAAG,KAAK,EACpB,MAAM,GAAG,YAAY,GACH,EACoB,EAAE;IAC1C,yFAAyF;IACzF,MAAM,iBAAiB,GAAG,gBAAgB,IAAI,uBAAuB,CAAC;IAEtE,kFAAkF;IAClF,MAAM,aAAa,GAAG,YAAY,IAAI,EAAE,CAAC,IAAI,IAAI,mBAAmB,CAAC;IAErE,oDAAoD;IACpD,MAAM,SAAS,GAAG,IAAI,GAAG,EAAkB,CAAC;IAE5C,OAAO,KAAK,EAAE,GAAG,IAAW,EAAoB,EAAE;QAChD,MAAM,QAAQ,GAAG,iBAAiB,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;QACxD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAEvB,mCAAmC;QACnC,2EAA2E;QAC3E,4EAA4E;QAC5E,4CAA4C;QAC5C,MAAM,SAAS,GAAG,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC1C,IAAI,CAAC,YAAY,IAAI,CAAC,SAAS,KAAK,SAAS,IAAI,GAAG,GAAG,SAAS,CAAC,EAAE,CAAC;YAClE,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;gBACzC,6FAA6F;gBAC7F,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;oBACzB,0EAA0E;oBAC1E,OAAO,MAAiB,CAAC;gBAC3B,CAAC;YACH,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,2DAA2D;gBAC3D,MAAM,CAAC,KAAK,CAAC,4BAA4B,QAAQ,IAAI,EAAE,KAAK,CAAC,CAAC;YAChE,CAAC;QACH,CAAC;QAED,6DAA6D;QAC7D,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,GAAG,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;QAE9D,sCAAsC;QACtC,MAAM,eAAe,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,YAAY,GAAG,GAAG,CAAC,CAAC;QAExD,4CAA4C;QAC5C,MAAM,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,eAAe,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;YACjE,MAAM,CAAC,KAAK,CAAC,4BAA4B,QAAQ,IAAI,EAAE,KAAK,CAAC,CAAC;QAChE,CAAC,CAAC,CAAC;QAEH,yBAAyB;QACzB,SAAS,CAAC,GAAG,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC;QAEtC,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC,CAAC;AA7DW,QAAA,aAAa,iBA6DxB","sourcesContent":["import { Logger, LogLevel } from '../logger/Logger';\nimport { serialize } from '../serialization/serialization';\nimport type { Serializable } from '../serialization/types';\nimport type { ICache } from './types';\n\n/**\n * A logger that discards all messages, used when no logger is provided.\n */\nconst silentLogger = new Logger({ level: LogLevel.SILENT });\n\n/**\n * Result type for functions that provide their own expiry time.\n */\nexport type ResultWithExpiry<TResult> = {\n  result: TResult;\n  expiresAt: number; // Unix timestamp in milliseconds\n};\n\n/**\n * Options for configuring the caching behavior of a function with dynamic expiry.\n */\nexport type CacheUntilOptions = {\n  /**\n   * Set this if you want to use a custom function name for the cache key.\n   */\n  functionName?: string;\n  /**\n   * Optional function to generate the cache key for the function call.\n   * Defaults to a function that generates the key based on function name and JSON stringified args separated by colons.\n   */\n  generateCacheKey?: (functionName: string, args: Serializable[]) => string;\n  /**\n   * Whether to refresh the cache.\n   * Defaults to false.\n   */\n  refreshCache?: boolean;\n  /**\n   * Optional logger for cache errors. Defaults to a silent logger.\n   */\n  logger?: Logger;\n};\n\n/**\n * Default function to generate the cache key for a function call.\n *\n * @param functionName - The name of the function.\n * @param args - The arguments of the function call.\n * @returns The cache key.\n */\nconst defaultGenerateCacheKey = (\n  functionName: string,\n  args: Serializable[],\n): string =>\n  `${functionName}:${args.map((arg) => JSON.stringify(serialize(arg))).join(':')}`;\n\n/**\n * Wraps an async function with caching behavior where expiry is determined\n * by the function result itself (dynamic TTL).\n *\n * Unlike `useCache` which uses a fixed TTL, this utility allows the wrapped\n * function to specify when its result expires. This is useful for caching\n * data that has known invalidation points (e.g., blockchain maintenance periods).\n *\n * @template TArgs - Tuple type representing the arguments of the function.\n * @template TResult - The return type of the function, must be Serializable.\n * @param fn - The asynchronous function to wrap. Must return a Promise<ResultWithExpiry<TResult>>.\n * @param cache - The cache instance to use.\n * @param options - The caching options.\n * @param options.refreshCache - Whether to refresh the cache.\n * @param options.functionName - The name of the function.\n * @param options.generateCacheKey - Optional function to generate the cache key.\n * @param options.logger - Optional logger for cache errors.\n * @returns A new asynchronous function with caching behavior.\n */\nexport const useCacheUntil = <\n  TArgs extends Serializable[],\n  TResult extends Serializable,\n>(\n  fn: (...args: TArgs) => Promise<ResultWithExpiry<TResult>>,\n  cache: ICache<Serializable>,\n  {\n    functionName,\n    generateCacheKey,\n    refreshCache = false,\n    logger = silentLogger,\n  }: CacheUntilOptions,\n): ((...args: TArgs) => Promise<TResult>) => {\n  // Use provided key generator or default, adapting the default to use the function's name\n  const _generateCacheKey = generateCacheKey ?? defaultGenerateCacheKey;\n\n  // Get the function name for the default key generator, handle anonymous functions\n  const _functionName = functionName ?? fn.name ?? 'anonymousFunction';\n\n  // Map to track expiry timestamps for each cache key\n  const expiryMap = new Map<string, number>();\n\n  return async (...args: TArgs): Promise<TResult> => {\n    const cacheKey = _generateCacheKey(_functionName, args);\n    const now = Date.now();\n\n    // Check if cached and not expired.\n    // The cache owns the persisted TTL. When this wrapper is recreated after a\n    // Snap restart, expiryMap is empty, so consult the cache to hydrate a still\n    // valid entry instead of fetching it again.\n    const expiresAt = expiryMap.get(cacheKey);\n    if (!refreshCache && (expiresAt === undefined || now < expiresAt)) {\n      try {\n        const cached = await cache.get(cacheKey);\n        // Check explicitly for undefined, as null or other falsy values might be valid cache results\n        if (cached !== undefined) {\n          // Type assertion because cache stores Serializable, but we expect TResult\n          return cached as TResult;\n        }\n      } catch (error) {\n        // Log cache get errors but proceed to execute the function\n        logger.error(`Cache get error for key \"${cacheKey}\":`, error);\n      }\n    }\n\n    // Execute the original function to get result and new expiry\n    const { result, expiresAt: newExpiresAt } = await fn(...args);\n\n    // Calculate TTL from expiry timestamp\n    const ttlMilliseconds = Math.max(0, newExpiresAt - now);\n\n    // Store result in cache with calculated TTL\n    await cache.set(cacheKey, result, ttlMilliseconds).catch((error) => {\n      logger.error(`Cache set error for key \"${cacheKey}\":`, error);\n    });\n\n    // Store expiry timestamp\n    expiryMap.set(cacheKey, newExpiresAt);\n\n    return result;\n  };\n};\n"]}