@metamask/snap-networks-utils 1.0.0 → 2.0.0

package/dist/utils/cache/StateCache.cjs

@@ -0,0 +1,193 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StateCache = void 0;
+const utils_1 = require("@metamask/utils");
+/**
+ * A cache that wraps any implementation of a state manager to store the cache.
+ *
+ * It is intended to be used with the snap's `State` class, but can be used with any other implementation of the state manager interface. For instance it can be used with an in-memory state implementation for testing purposes.
+ *
+ * By default, it stores its data in the `__cache__default` property of the state, but you can specify any other prefix you want, provided it starts with `__cache__` to avoid collisions with other state values.
+ * This is useful if you want to have multiple independent caches in the same state.
+ *
+ * ```
+ * {
+ *    ..., // other state values
+ *    __cache__default: {
+ *      key1: value1,
+ *      key2: value2,
+ *    },
+ *    __cache__my-prefix: {
+ *      key3: value3,
+ *      key4: value4,
+ *    },
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * const state = new State({}); // Here we use the real snap's state
+ * const rootLogger = new Logger({ level: LogLevel.INFO });
+ * const cache = new StateCache(state, rootLogger, '__cache__my-prefix');
+ *
+ * // state looks like this:
+ * // {
+ * //   ..., // other state values
+ *     // no __cache__my-prefix yet
+ * // }
+ *
+ * await cache.set('key1', 'value1');
+ *
+ * // state looks like this:
+ * // {
+ * //   ..., // other state values
+ * //   __cache__my-prefix: {
+ * //     key1: value1,
+ * //   },
+ * // }
+ * ```
+ */
+class StateCache {
+    #state;
+    #logger;
+    prefix;
+    constructor(state, logger, prefix = '__cache__default') {
+        this.#state = state;
+        this.#logger = logger;
+        this.prefix = prefix;
+    }
+    async get(key) {
+        const result = await this.mget([key]);
+        return result[key];
+    }
+    async set(key, value, ttlMilliseconds = Number.MAX_SAFE_INTEGER) {
+        this.#validateTtlOrThrow(ttlMilliseconds);
+        await this.#state.setKey(`${this.prefix}.${key}`, {
+            value,
+            expiresAt: Math.min(Date.now() + ttlMilliseconds, Number.MAX_SAFE_INTEGER),
+        });
+    }
+    #validateTtlOrThrow(ttlMilliseconds) {
+        if (ttlMilliseconds === undefined) {
+            return;
+        }
+        if (typeof ttlMilliseconds !== 'number') {
+            throw new Error('TTL must be a number');
+        }
+        if (ttlMilliseconds < 0) {
+            throw new Error('TTL must be positive');
+        }
+        if (ttlMilliseconds > Number.MAX_SAFE_INTEGER) {
+            throw new Error('TTL must be less than 2^53 - 1');
+        }
+    }
+    async delete(key) {
+        const result = await this.mdelete([key]);
+        return result[key] ?? false;
+    }
+    async clear() {
+        await this.#state.setKey(this.prefix, {});
+    }
+    async has(key) {
+        const result = await this.get(key);
+        return result !== undefined;
+    }
+    async keys() {
+        const cacheStore = await this.#state.getKey(this.prefix);
+        return Object.keys(cacheStore ?? {});
+    }
+    async size() {
+        const cacheStore = await this.#state.getKey(this.prefix);
+        return Object.keys(cacheStore ?? {}).length;
+    }
+    async peek(key) {
+        const cacheStore = await this.#state.getKey(this.prefix);
+        const cacheEntry = cacheStore?.[key];
+        return cacheEntry?.value;
+    }
+    async mget(keys) {
+        const cacheStore = await this.#state.getKey(this.prefix);
+        // If cache is not initialized, return empty object
+        if (!cacheStore) {
+            return {};
+        }
+        const keysAndValues = Object.entries(cacheStore).filter(([key]) => keys.includes(key));
+        const expiredKeys = keysAndValues.filter(([_unused, cacheEntry]) => cacheEntry && cacheEntry.expiresAt < Date.now());
+        await this.mdelete(expiredKeys.map(([key]) => key));
+        const result = {};
+        // First, handle keys that exist in the cache
+        keysAndValues.forEach(([key, cacheEntry]) => {
+            if (cacheEntry === undefined) {
+                this.#logger.info(`[StateCache] ❌ Cache miss for key "${key}"`);
+                result[key] = undefined;
+                return;
+            }
+            if (cacheEntry.expiresAt < Date.now()) {
+                this.#logger.info(`[StateCache] ⌛ Cache expired for key "${key}"`);
+                result[key] = undefined;
+            }
+            else {
+                this.#logger.info(`[StateCache] 🎉 Cache hit for key "${key}"`);
+                result[key] = cacheEntry.value;
+            }
+        });
+        // Then, handle keys that don't exist in the cache
+        keys.forEach((key) => {
+            if (!Object.hasOwn(result, key)) {
+                this.#logger.info(`[StateCache] ❌ Cache miss for key "${key}"`);
+                result[key] = undefined;
+            }
+        });
+        return result;
+    }
+    async mset(entries) {
+        if (entries.length === 0) {
+            return;
+        }
+        if (entries.length === 1) {
+            (0, utils_1.assert)(entries[0]); // Enforce type narrowing as TS cannot infer that entries[0] is defined
+            const { key, value, ttlMilliseconds } = entries[0];
+            await this.set(key, value, ttlMilliseconds);
+            return;
+        }
+        entries.forEach(({ ttlMilliseconds }) => {
+            this.#validateTtlOrThrow(ttlMilliseconds);
+        });
+        // Using `state.update` is preferred for bulk `set`s, because it's more efficient and atomic.
+        await this.#state.update((stateValue) => {
+            const cacheStore = stateValue[this.prefix] ?? {};
+            entries.forEach(({ key, value, ttlMilliseconds }) => {
+                if (value === undefined) {
+                    return;
+                }
+                cacheStore[key] = {
+                    value,
+                    expiresAt: Math.min(Date.now() + (ttlMilliseconds ?? Number.MAX_SAFE_INTEGER), Number.MAX_SAFE_INTEGER),
+                };
+            });
+            stateValue[this.prefix] = cacheStore;
+            return stateValue;
+        });
+    }
+    async mdelete(keys) {
+        const result = {};
+        // Using `state.update` is preferred for bulk `delete`s, because it's more efficient and atomic.
+        await this.#state.update((stateValue) => {
+            const cacheStore = stateValue[this.prefix] ?? {};
+            keys.forEach((key) => {
+                if (cacheStore[key] === undefined) {
+                    result[key] = false;
+                }
+                else {
+                    delete cacheStore[key];
+                    result[key] = true;
+                }
+            });
+            stateValue[this.prefix] = cacheStore;
+            return stateValue;
+        });
+        return result;
+    }
+}
+exports.StateCache = StateCache;
+//# sourceMappingURL=StateCache.cjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"StateCache.cjs","sourceRoot":"","sources":["../../../src/utils/cache/StateCache.ts"],"names":[],"mappings":"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","sourcesContent":["import { assert } from '@metamask/utils';\n\nimport type { Logger } from '../logger/Logger';\nimport type { Serializable } from '../serialization/types';\nimport type { CacheEntry, ICache } from './types';\n\n/**\n * The minimal subset of a state manager that {@link StateCache} relies on.\n *\n * Any implementation whose `getKey`, `setKey` and `update` methods match these signatures\n * (such as the `IStateManager` implementations in the network snaps) satisfies this interface structurally.\n */\nexport type CacheStateManager<\n  TStateValue extends Record<string, Serializable>,\n> = {\n  getKey<TKey extends Serializable>(key: string): Promise<TKey | undefined>;\n  setKey(key: string, value: Serializable): Promise<void>;\n  update(\n    updaterFunction: (state: TStateValue) => TStateValue,\n  ): Promise<TStateValue>;\n};\n\n/**\n * The whole cache store.\n */\nexport type CacheStore = Record<string, CacheEntry> | undefined;\n\n/**\n * A prefix for the cache \"location\" in the state. Enforced to start with `__cache__` to avoid collisions with other state values.\n */\nexport type CachePrefix = `__cache__${string}`;\n\n/**\n * Describes the shape of the whole state inside which the cache is stored.\n */\nexport type StateValue = {\n  [x: string]: Serializable;\n} & {\n  [K in CachePrefix]?: CacheStore;\n};\n\n/**\n * A cache that wraps any implementation of a state manager to store the cache.\n *\n * It is intended to be used with the snap's `State` class, but can be used with any other implementation of the state manager interface. For instance it can be used with an in-memory state implementation for testing purposes.\n *\n * By default, it stores its data in the `__cache__default` property of the state, but you can specify any other prefix you want, provided it starts with `__cache__` to avoid collisions with other state values.\n * This is useful if you want to have multiple independent caches in the same state.\n *\n * ```\n * {\n *    ..., // other state values\n *    __cache__default: {\n *      key1: value1,\n *      key2: value2,\n *    },\n *    __cache__my-prefix: {\n *      key3: value3,\n *      key4: value4,\n *    },\n * }\n * ```\n *\n * @example\n * ```ts\n * const state = new State({}); // Here we use the real snap's state\n * const rootLogger = new Logger({ level: LogLevel.INFO });\n * const cache = new StateCache(state, rootLogger, '__cache__my-prefix');\n *\n * // state looks like this:\n * // {\n * //   ..., // other state values\n *     // no __cache__my-prefix yet\n * // }\n *\n * await cache.set('key1', 'value1');\n *\n * // state looks like this:\n * // {\n * //   ..., // other state values\n * //   __cache__my-prefix: {\n * //     key1: value1,\n * //   },\n * // }\n * ```\n */\nexport class StateCache implements ICache<Serializable | undefined> {\n  readonly #state: CacheStateManager<StateValue>;\n\n  readonly #logger: Logger;\n\n  public readonly prefix: CachePrefix;\n\n  constructor(\n    state: CacheStateManager<StateValue>,\n    logger: Logger,\n    prefix: CachePrefix = '__cache__default',\n  ) {\n    this.#state = state;\n    this.#logger = logger;\n    this.prefix = prefix;\n  }\n\n  async get(key: string): Promise<Serializable | undefined> {\n    const result = await this.mget([key]);\n    return result[key];\n  }\n\n  async set(\n    key: string,\n    value: Serializable,\n    ttlMilliseconds = Number.MAX_SAFE_INTEGER,\n  ): Promise<void> {\n    this.#validateTtlOrThrow(ttlMilliseconds);\n\n    await this.#state.setKey(`${this.prefix}.${key}`, {\n      value,\n      expiresAt: Math.min(\n        Date.now() + ttlMilliseconds,\n        Number.MAX_SAFE_INTEGER,\n      ),\n    });\n  }\n\n  #validateTtlOrThrow(ttlMilliseconds?: number): void {\n    if (ttlMilliseconds === undefined) {\n      return;\n    }\n\n    if (typeof ttlMilliseconds !== 'number') {\n      throw new Error('TTL must be a number');\n    }\n\n    if (ttlMilliseconds < 0) {\n      throw new Error('TTL must be positive');\n    }\n\n    if (ttlMilliseconds > Number.MAX_SAFE_INTEGER) {\n      throw new Error('TTL must be less than 2^53 - 1');\n    }\n  }\n\n  async delete(key: string): Promise<boolean> {\n    const result = await this.mdelete([key]);\n    return result[key] ?? false;\n  }\n\n  async clear(): Promise<void> {\n    await this.#state.setKey(this.prefix, {});\n  }\n\n  async has(key: string): Promise<boolean> {\n    const result = await this.get(key);\n    return result !== undefined;\n  }\n\n  async keys(): Promise<string[]> {\n    const cacheStore = await this.#state.getKey<CacheStore>(this.prefix);\n\n    return Object.keys(cacheStore ?? {});\n  }\n\n  async size(): Promise<number> {\n    const cacheStore = await this.#state.getKey<CacheStore>(this.prefix);\n\n    return Object.keys(cacheStore ?? {}).length;\n  }\n\n  async peek(key: string): Promise<Serializable | undefined> {\n    const cacheStore = await this.#state.getKey<CacheStore>(this.prefix);\n    const cacheEntry = cacheStore?.[key];\n\n    return cacheEntry?.value;\n  }\n\n  async mget(\n    keys: string[],\n  ): Promise<Record<string, Serializable | undefined>> {\n    const cacheStore = await this.#state.getKey<CacheStore>(this.prefix);\n\n    // If cache is not initialized, return empty object\n    if (!cacheStore) {\n      return {};\n    }\n\n    const keysAndValues = Object.entries(cacheStore).filter(([key]) =>\n      keys.includes(key),\n    );\n\n    const expiredKeys = keysAndValues.filter(\n      ([_unused, cacheEntry]) =>\n        cacheEntry && cacheEntry.expiresAt < Date.now(),\n    );\n\n    await this.mdelete(expiredKeys.map(([key]) => key));\n\n    const result: Record<string, Serializable | undefined> = {};\n\n    // First, handle keys that exist in the cache\n    keysAndValues.forEach(([key, cacheEntry]) => {\n      if (cacheEntry === undefined) {\n        this.#logger.info(`[StateCache] ❌ Cache miss for key \"${key}\"`);\n        result[key] = undefined;\n        return;\n      }\n\n      if (cacheEntry.expiresAt < Date.now()) {\n        this.#logger.info(`[StateCache] ⌛ Cache expired for key \"${key}\"`);\n        result[key] = undefined;\n      } else {\n        this.#logger.info(`[StateCache] 🎉 Cache hit for key \"${key}\"`);\n        result[key] = cacheEntry.value;\n      }\n    });\n\n    // Then, handle keys that don't exist in the cache\n    keys.forEach((key) => {\n      if (!Object.hasOwn(result, key)) {\n        this.#logger.info(`[StateCache] ❌ Cache miss for key \"${key}\"`);\n        result[key] = undefined;\n      }\n    });\n\n    return result;\n  }\n\n  async mset(\n    entries: { key: string; value: Serializable; ttlMilliseconds?: number }[],\n  ): Promise<void> {\n    if (entries.length === 0) {\n      return;\n    }\n\n    if (entries.length === 1) {\n      assert(entries[0]); // Enforce type narrowing as TS cannot infer that entries[0] is defined\n      const { key, value, ttlMilliseconds } = entries[0];\n      await this.set(key, value, ttlMilliseconds);\n      return;\n    }\n\n    entries.forEach(({ ttlMilliseconds }) => {\n      this.#validateTtlOrThrow(ttlMilliseconds);\n    });\n\n    // Using `state.update` is preferred for bulk `set`s, because it's more efficient and atomic.\n    await this.#state.update((stateValue) => {\n      const cacheStore = stateValue[this.prefix] ?? {};\n      entries.forEach(({ key, value, ttlMilliseconds }) => {\n        if (value === undefined) {\n          return;\n        }\n        cacheStore[key] = {\n          value,\n          expiresAt: Math.min(\n            Date.now() + (ttlMilliseconds ?? Number.MAX_SAFE_INTEGER),\n            Number.MAX_SAFE_INTEGER,\n          ),\n        };\n      });\n      stateValue[this.prefix] = cacheStore;\n      return stateValue;\n    });\n  }\n\n  async mdelete(keys: string[]): Promise<Record<string, boolean>> {\n    const result: Record<string, boolean> = {};\n\n    // Using `state.update` is preferred for bulk `delete`s, because it's more efficient and atomic.\n    await this.#state.update((stateValue) => {\n      const cacheStore = stateValue[this.prefix] ?? {};\n      keys.forEach((key) => {\n        if (cacheStore[key] === undefined) {\n          result[key] = false;\n        } else {\n          delete cacheStore[key];\n          result[key] = true;\n        }\n      });\n      stateValue[this.prefix] = cacheStore;\n      return stateValue;\n    });\n\n    return result;\n  }\n}\n"]}

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

@@ -0,0 +1,96 @@
+import type { Logger } from "../logger/Logger.cjs";
+import type { Serializable } from "../serialization/types.cjs";
+import type { CacheEntry, ICache } from "./types.cjs";
+/**
+ * The minimal subset of a state manager that {@link StateCache} relies on.
+ *
+ * Any implementation whose `getKey`, `setKey` and `update` methods match these signatures
+ * (such as the `IStateManager` implementations in the network snaps) satisfies this interface structurally.
+ */
+export type CacheStateManager<TStateValue extends Record<string, Serializable>> = {
+    getKey<TKey extends Serializable>(key: string): Promise<TKey | undefined>;
+    setKey(key: string, value: Serializable): Promise<void>;
+    update(updaterFunction: (state: TStateValue) => TStateValue): Promise<TStateValue>;
+};
+/**
+ * The whole cache store.
+ */
+export type CacheStore = Record<string, CacheEntry> | undefined;
+/**
+ * A prefix for the cache "location" in the state. Enforced to start with `__cache__` to avoid collisions with other state values.
+ */
+export type CachePrefix = `__cache__${string}`;
+/**
+ * Describes the shape of the whole state inside which the cache is stored.
+ */
+export type StateValue = {
+    [x: string]: Serializable;
+} & {
+    [K in CachePrefix]?: CacheStore;
+};
+/**
+ * A cache that wraps any implementation of a state manager to store the cache.
+ *
+ * It is intended to be used with the snap's `State` class, but can be used with any other implementation of the state manager interface. For instance it can be used with an in-memory state implementation for testing purposes.
+ *
+ * By default, it stores its data in the `__cache__default` property of the state, but you can specify any other prefix you want, provided it starts with `__cache__` to avoid collisions with other state values.
+ * This is useful if you want to have multiple independent caches in the same state.
+ *
+ * ```
+ * {
+ *    ..., // other state values
+ *    __cache__default: {
+ *      key1: value1,
+ *      key2: value2,
+ *    },
+ *    __cache__my-prefix: {
+ *      key3: value3,
+ *      key4: value4,
+ *    },
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * const state = new State({}); // Here we use the real snap's state
+ * const rootLogger = new Logger({ level: LogLevel.INFO });
+ * const cache = new StateCache(state, rootLogger, '__cache__my-prefix');
+ *
+ * // state looks like this:
+ * // {
+ * //   ..., // other state values
+ *     // no __cache__my-prefix yet
+ * // }
+ *
+ * await cache.set('key1', 'value1');
+ *
+ * // state looks like this:
+ * // {
+ * //   ..., // other state values
+ * //   __cache__my-prefix: {
+ * //     key1: value1,
+ * //   },
+ * // }
+ * ```
+ */
+export declare class StateCache implements ICache<Serializable | undefined> {
+    #private;
+    readonly prefix: CachePrefix;
+    constructor(state: CacheStateManager<StateValue>, logger: Logger, prefix?: CachePrefix);
+    get(key: string): Promise<Serializable | undefined>;
+    set(key: string, value: Serializable, ttlMilliseconds?: number): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    clear(): Promise<void>;
+    has(key: string): Promise<boolean>;
+    keys(): Promise<string[]>;
+    size(): Promise<number>;
+    peek(key: string): Promise<Serializable | undefined>;
+    mget(keys: string[]): Promise<Record<string, Serializable | undefined>>;
+    mset(entries: {
+        key: string;
+        value: Serializable;
+        ttlMilliseconds?: number;
+    }[]): Promise<void>;
+    mdelete(keys: string[]): Promise<Record<string, boolean>>;
+}
+//# sourceMappingURL=StateCache.d.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"StateCache.d.cts","sourceRoot":"","sources":["../../../src/utils/cache/StateCache.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAE,6BAAyB;AAC/C,OAAO,KAAK,EAAE,YAAY,EAAE,mCAA+B;AAC3D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,oBAAgB;AAElD;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,CAC3B,WAAW,SAAS,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,IAC9C;IACF,MAAM,CAAC,IAAI,SAAS,YAAY,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,SAAS,CAAC,CAAC;IAC1E,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,MAAM,CACJ,eAAe,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,WAAW,GACnD,OAAO,CAAC,WAAW,CAAC,CAAC;CACzB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,SAAS,CAAC;AAEhE;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,YAAY,MAAM,EAAE,CAAC;AAE/C;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,CAAC,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC;CAC3B,GAAG;KACD,CAAC,IAAI,WAAW,CAAC,CAAC,EAAE,UAAU;CAChC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,qBAAa,UAAW,YAAW,MAAM,CAAC,YAAY,GAAG,SAAS,CAAC;;IAKjE,SAAgB,MAAM,EAAE,WAAW,CAAC;gBAGlC,KAAK,EAAE,iBAAiB,CAAC,UAAU,CAAC,EACpC,MAAM,EAAE,MAAM,EACd,MAAM,GAAE,WAAgC;IAOpC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC;IAKnD,GAAG,CACP,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,YAAY,EACnB,eAAe,SAA0B,GACxC,OAAO,CAAC,IAAI,CAAC;IA8BV,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKrC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKlC,IAAI,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAMzB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;IAMvB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC;IAOpD,IAAI,CACR,IAAI,EAAE,MAAM,EAAE,GACb,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,SAAS,CAAC,CAAC;IAiD9C,IAAI,CACR,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,YAAY,CAAC;QAAC,eAAe,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,GACxE,OAAO,CAAC,IAAI,CAAC;IAoCV,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAoBhE"}

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

@@ -0,0 +1,96 @@
+import type { Logger } from "../logger/Logger.mjs";
+import type { Serializable } from "../serialization/types.mjs";
+import type { CacheEntry, ICache } from "./types.mjs";
+/**
+ * The minimal subset of a state manager that {@link StateCache} relies on.
+ *
+ * Any implementation whose `getKey`, `setKey` and `update` methods match these signatures
+ * (such as the `IStateManager` implementations in the network snaps) satisfies this interface structurally.
+ */
+export type CacheStateManager<TStateValue extends Record<string, Serializable>> = {
+    getKey<TKey extends Serializable>(key: string): Promise<TKey | undefined>;
+    setKey(key: string, value: Serializable): Promise<void>;
+    update(updaterFunction: (state: TStateValue) => TStateValue): Promise<TStateValue>;
+};
+/**
+ * The whole cache store.
+ */
+export type CacheStore = Record<string, CacheEntry> | undefined;
+/**
+ * A prefix for the cache "location" in the state. Enforced to start with `__cache__` to avoid collisions with other state values.
+ */
+export type CachePrefix = `__cache__${string}`;
+/**
+ * Describes the shape of the whole state inside which the cache is stored.
+ */
+export type StateValue = {
+    [x: string]: Serializable;
+} & {
+    [K in CachePrefix]?: CacheStore;
+};
+/**
+ * A cache that wraps any implementation of a state manager to store the cache.
+ *
+ * It is intended to be used with the snap's `State` class, but can be used with any other implementation of the state manager interface. For instance it can be used with an in-memory state implementation for testing purposes.
+ *
+ * By default, it stores its data in the `__cache__default` property of the state, but you can specify any other prefix you want, provided it starts with `__cache__` to avoid collisions with other state values.
+ * This is useful if you want to have multiple independent caches in the same state.
+ *
+ * ```
+ * {
+ *    ..., // other state values
+ *    __cache__default: {
+ *      key1: value1,
+ *      key2: value2,
+ *    },
+ *    __cache__my-prefix: {
+ *      key3: value3,
+ *      key4: value4,
+ *    },
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * const state = new State({}); // Here we use the real snap's state
+ * const rootLogger = new Logger({ level: LogLevel.INFO });
+ * const cache = new StateCache(state, rootLogger, '__cache__my-prefix');
+ *
+ * // state looks like this:
+ * // {
+ * //   ..., // other state values
+ *     // no __cache__my-prefix yet
+ * // }
+ *
+ * await cache.set('key1', 'value1');
+ *
+ * // state looks like this:
+ * // {
+ * //   ..., // other state values
+ * //   __cache__my-prefix: {
+ * //     key1: value1,
+ * //   },
+ * // }
+ * ```
+ */
+export declare class StateCache implements ICache<Serializable | undefined> {
+    #private;
+    readonly prefix: CachePrefix;
+    constructor(state: CacheStateManager<StateValue>, logger: Logger, prefix?: CachePrefix);
+    get(key: string): Promise<Serializable | undefined>;
+    set(key: string, value: Serializable, ttlMilliseconds?: number): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    clear(): Promise<void>;
+    has(key: string): Promise<boolean>;
+    keys(): Promise<string[]>;
+    size(): Promise<number>;
+    peek(key: string): Promise<Serializable | undefined>;
+    mget(keys: string[]): Promise<Record<string, Serializable | undefined>>;
+    mset(entries: {
+        key: string;
+        value: Serializable;
+        ttlMilliseconds?: number;
+    }[]): Promise<void>;
+    mdelete(keys: string[]): Promise<Record<string, boolean>>;
+}
+//# sourceMappingURL=StateCache.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"StateCache.d.mts","sourceRoot":"","sources":["../../../src/utils/cache/StateCache.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAE,6BAAyB;AAC/C,OAAO,KAAK,EAAE,YAAY,EAAE,mCAA+B;AAC3D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,oBAAgB;AAElD;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,CAC3B,WAAW,SAAS,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,IAC9C;IACF,MAAM,CAAC,IAAI,SAAS,YAAY,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,SAAS,CAAC,CAAC;IAC1E,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,MAAM,CACJ,eAAe,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,WAAW,GACnD,OAAO,CAAC,WAAW,CAAC,CAAC;CACzB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,SAAS,CAAC;AAEhE;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,YAAY,MAAM,EAAE,CAAC;AAE/C;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,CAAC,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC;CAC3B,GAAG;KACD,CAAC,IAAI,WAAW,CAAC,CAAC,EAAE,UAAU;CAChC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,qBAAa,UAAW,YAAW,MAAM,CAAC,YAAY,GAAG,SAAS,CAAC;;IAKjE,SAAgB,MAAM,EAAE,WAAW,CAAC;gBAGlC,KAAK,EAAE,iBAAiB,CAAC,UAAU,CAAC,EACpC,MAAM,EAAE,MAAM,EACd,MAAM,GAAE,WAAgC;IAOpC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC;IAKnD,GAAG,CACP,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,YAAY,EACnB,eAAe,SAA0B,GACxC,OAAO,CAAC,IAAI,CAAC;IA8BV,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKrC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKlC,IAAI,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAMzB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;IAMvB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC;IAOpD,IAAI,CACR,IAAI,EAAE,MAAM,EAAE,GACb,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,SAAS,CAAC,CAAC;IAiD9C,IAAI,CACR,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,YAAY,CAAC;QAAC,eAAe,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,GACxE,OAAO,CAAC,IAAI,CAAC;IAoCV,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAoBhE"}

package/dist/utils/cache/StateCache.mjs

@@ -0,0 +1,189 @@
+import { assert } from "@metamask/utils";
+/**
+ * A cache that wraps any implementation of a state manager to store the cache.
+ *
+ * It is intended to be used with the snap's `State` class, but can be used with any other implementation of the state manager interface. For instance it can be used with an in-memory state implementation for testing purposes.
+ *
+ * By default, it stores its data in the `__cache__default` property of the state, but you can specify any other prefix you want, provided it starts with `__cache__` to avoid collisions with other state values.
+ * This is useful if you want to have multiple independent caches in the same state.
+ *
+ * ```
+ * {
+ *    ..., // other state values
+ *    __cache__default: {
+ *      key1: value1,
+ *      key2: value2,
+ *    },
+ *    __cache__my-prefix: {
+ *      key3: value3,
+ *      key4: value4,
+ *    },
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * const state = new State({}); // Here we use the real snap's state
+ * const rootLogger = new Logger({ level: LogLevel.INFO });
+ * const cache = new StateCache(state, rootLogger, '__cache__my-prefix');
+ *
+ * // state looks like this:
+ * // {
+ * //   ..., // other state values
+ *     // no __cache__my-prefix yet
+ * // }
+ *
+ * await cache.set('key1', 'value1');
+ *
+ * // state looks like this:
+ * // {
+ * //   ..., // other state values
+ * //   __cache__my-prefix: {
+ * //     key1: value1,
+ * //   },
+ * // }
+ * ```
+ */
+export class StateCache {
+    #state;
+    #logger;
+    prefix;
+    constructor(state, logger, prefix = '__cache__default') {
+        this.#state = state;
+        this.#logger = logger;
+        this.prefix = prefix;
+    }
+    async get(key) {
+        const result = await this.mget([key]);
+        return result[key];
+    }
+    async set(key, value, ttlMilliseconds = Number.MAX_SAFE_INTEGER) {
+        this.#validateTtlOrThrow(ttlMilliseconds);
+        await this.#state.setKey(`${this.prefix}.${key}`, {
+            value,
+            expiresAt: Math.min(Date.now() + ttlMilliseconds, Number.MAX_SAFE_INTEGER),
+        });
+    }
+    #validateTtlOrThrow(ttlMilliseconds) {
+        if (ttlMilliseconds === undefined) {
+            return;
+        }
+        if (typeof ttlMilliseconds !== 'number') {
+            throw new Error('TTL must be a number');
+        }
+        if (ttlMilliseconds < 0) {
+            throw new Error('TTL must be positive');
+        }
+        if (ttlMilliseconds > Number.MAX_SAFE_INTEGER) {
+            throw new Error('TTL must be less than 2^53 - 1');
+        }
+    }
+    async delete(key) {
+        const result = await this.mdelete([key]);
+        return result[key] ?? false;
+    }
+    async clear() {
+        await this.#state.setKey(this.prefix, {});
+    }
+    async has(key) {
+        const result = await this.get(key);
+        return result !== undefined;
+    }
+    async keys() {
+        const cacheStore = await this.#state.getKey(this.prefix);
+        return Object.keys(cacheStore ?? {});
+    }
+    async size() {
+        const cacheStore = await this.#state.getKey(this.prefix);
+        return Object.keys(cacheStore ?? {}).length;
+    }
+    async peek(key) {
+        const cacheStore = await this.#state.getKey(this.prefix);
+        const cacheEntry = cacheStore?.[key];
+        return cacheEntry?.value;
+    }
+    async mget(keys) {
+        const cacheStore = await this.#state.getKey(this.prefix);
+        // If cache is not initialized, return empty object
+        if (!cacheStore) {
+            return {};
+        }
+        const keysAndValues = Object.entries(cacheStore).filter(([key]) => keys.includes(key));
+        const expiredKeys = keysAndValues.filter(([_unused, cacheEntry]) => cacheEntry && cacheEntry.expiresAt < Date.now());
+        await this.mdelete(expiredKeys.map(([key]) => key));
+        const result = {};
+        // First, handle keys that exist in the cache
+        keysAndValues.forEach(([key, cacheEntry]) => {
+            if (cacheEntry === undefined) {
+                this.#logger.info(`[StateCache] ❌ Cache miss for key "${key}"`);
+                result[key] = undefined;
+                return;
+            }
+            if (cacheEntry.expiresAt < Date.now()) {
+                this.#logger.info(`[StateCache] ⌛ Cache expired for key "${key}"`);
+                result[key] = undefined;
+            }
+            else {
+                this.#logger.info(`[StateCache] 🎉 Cache hit for key "${key}"`);
+                result[key] = cacheEntry.value;
+            }
+        });
+        // Then, handle keys that don't exist in the cache
+        keys.forEach((key) => {
+            if (!Object.hasOwn(result, key)) {
+                this.#logger.info(`[StateCache] ❌ Cache miss for key "${key}"`);
+                result[key] = undefined;
+            }
+        });
+        return result;
+    }
+    async mset(entries) {
+        if (entries.length === 0) {
+            return;
+        }
+        if (entries.length === 1) {
+            assert(entries[0]); // Enforce type narrowing as TS cannot infer that entries[0] is defined
+            const { key, value, ttlMilliseconds } = entries[0];
+            await this.set(key, value, ttlMilliseconds);
+            return;
+        }
+        entries.forEach(({ ttlMilliseconds }) => {
+            this.#validateTtlOrThrow(ttlMilliseconds);
+        });
+        // Using `state.update` is preferred for bulk `set`s, because it's more efficient and atomic.
+        await this.#state.update((stateValue) => {
+            const cacheStore = stateValue[this.prefix] ?? {};
+            entries.forEach(({ key, value, ttlMilliseconds }) => {
+                if (value === undefined) {
+                    return;
+                }
+                cacheStore[key] = {
+                    value,
+                    expiresAt: Math.min(Date.now() + (ttlMilliseconds ?? Number.MAX_SAFE_INTEGER), Number.MAX_SAFE_INTEGER),
+                };
+            });
+            stateValue[this.prefix] = cacheStore;
+            return stateValue;
+        });
+    }
+    async mdelete(keys) {
+        const result = {};
+        // Using `state.update` is preferred for bulk `delete`s, because it's more efficient and atomic.
+        await this.#state.update((stateValue) => {
+            const cacheStore = stateValue[this.prefix] ?? {};
+            keys.forEach((key) => {
+                if (cacheStore[key] === undefined) {
+                    result[key] = false;
+                }
+                else {
+                    delete cacheStore[key];
+                    result[key] = true;
+                }
+            });
+            stateValue[this.prefix] = cacheStore;
+            return stateValue;
+        });
+        return result;
+    }
+}
+//# sourceMappingURL=StateCache.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"StateCache.mjs","sourceRoot":"","sources":["../../../src/utils/cache/StateCache.ts"],"names":[],"mappings":"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","sourcesContent":["import { assert } from '@metamask/utils';\n\nimport type { Logger } from '../logger/Logger';\nimport type { Serializable } from '../serialization/types';\nimport type { CacheEntry, ICache } from './types';\n\n/**\n * The minimal subset of a state manager that {@link StateCache} relies on.\n *\n * Any implementation whose `getKey`, `setKey` and `update` methods match these signatures\n * (such as the `IStateManager` implementations in the network snaps) satisfies this interface structurally.\n */\nexport type CacheStateManager<\n  TStateValue extends Record<string, Serializable>,\n> = {\n  getKey<TKey extends Serializable>(key: string): Promise<TKey | undefined>;\n  setKey(key: string, value: Serializable): Promise<void>;\n  update(\n    updaterFunction: (state: TStateValue) => TStateValue,\n  ): Promise<TStateValue>;\n};\n\n/**\n * The whole cache store.\n */\nexport type CacheStore = Record<string, CacheEntry> | undefined;\n\n/**\n * A prefix for the cache \"location\" in the state. Enforced to start with `__cache__` to avoid collisions with other state values.\n */\nexport type CachePrefix = `__cache__${string}`;\n\n/**\n * Describes the shape of the whole state inside which the cache is stored.\n */\nexport type StateValue = {\n  [x: string]: Serializable;\n} & {\n  [K in CachePrefix]?: CacheStore;\n};\n\n/**\n * A cache that wraps any implementation of a state manager to store the cache.\n *\n * It is intended to be used with the snap's `State` class, but can be used with any other implementation of the state manager interface. For instance it can be used with an in-memory state implementation for testing purposes.\n *\n * By default, it stores its data in the `__cache__default` property of the state, but you can specify any other prefix you want, provided it starts with `__cache__` to avoid collisions with other state values.\n * This is useful if you want to have multiple independent caches in the same state.\n *\n * ```\n * {\n *    ..., // other state values\n *    __cache__default: {\n *      key1: value1,\n *      key2: value2,\n *    },\n *    __cache__my-prefix: {\n *      key3: value3,\n *      key4: value4,\n *    },\n * }\n * ```\n *\n * @example\n * ```ts\n * const state = new State({}); // Here we use the real snap's state\n * const rootLogger = new Logger({ level: LogLevel.INFO });\n * const cache = new StateCache(state, rootLogger, '__cache__my-prefix');\n *\n * // state looks like this:\n * // {\n * //   ..., // other state values\n *     // no __cache__my-prefix yet\n * // }\n *\n * await cache.set('key1', 'value1');\n *\n * // state looks like this:\n * // {\n * //   ..., // other state values\n * //   __cache__my-prefix: {\n * //     key1: value1,\n * //   },\n * // }\n * ```\n */\nexport class StateCache implements ICache<Serializable | undefined> {\n  readonly #state: CacheStateManager<StateValue>;\n\n  readonly #logger: Logger;\n\n  public readonly prefix: CachePrefix;\n\n  constructor(\n    state: CacheStateManager<StateValue>,\n    logger: Logger,\n    prefix: CachePrefix = '__cache__default',\n  ) {\n    this.#state = state;\n    this.#logger = logger;\n    this.prefix = prefix;\n  }\n\n  async get(key: string): Promise<Serializable | undefined> {\n    const result = await this.mget([key]);\n    return result[key];\n  }\n\n  async set(\n    key: string,\n    value: Serializable,\n    ttlMilliseconds = Number.MAX_SAFE_INTEGER,\n  ): Promise<void> {\n    this.#validateTtlOrThrow(ttlMilliseconds);\n\n    await this.#state.setKey(`${this.prefix}.${key}`, {\n      value,\n      expiresAt: Math.min(\n        Date.now() + ttlMilliseconds,\n        Number.MAX_SAFE_INTEGER,\n      ),\n    });\n  }\n\n  #validateTtlOrThrow(ttlMilliseconds?: number): void {\n    if (ttlMilliseconds === undefined) {\n      return;\n    }\n\n    if (typeof ttlMilliseconds !== 'number') {\n      throw new Error('TTL must be a number');\n    }\n\n    if (ttlMilliseconds < 0) {\n      throw new Error('TTL must be positive');\n    }\n\n    if (ttlMilliseconds > Number.MAX_SAFE_INTEGER) {\n      throw new Error('TTL must be less than 2^53 - 1');\n    }\n  }\n\n  async delete(key: string): Promise<boolean> {\n    const result = await this.mdelete([key]);\n    return result[key] ?? false;\n  }\n\n  async clear(): Promise<void> {\n    await this.#state.setKey(this.prefix, {});\n  }\n\n  async has(key: string): Promise<boolean> {\n    const result = await this.get(key);\n    return result !== undefined;\n  }\n\n  async keys(): Promise<string[]> {\n    const cacheStore = await this.#state.getKey<CacheStore>(this.prefix);\n\n    return Object.keys(cacheStore ?? {});\n  }\n\n  async size(): Promise<number> {\n    const cacheStore = await this.#state.getKey<CacheStore>(this.prefix);\n\n    return Object.keys(cacheStore ?? {}).length;\n  }\n\n  async peek(key: string): Promise<Serializable | undefined> {\n    const cacheStore = await this.#state.getKey<CacheStore>(this.prefix);\n    const cacheEntry = cacheStore?.[key];\n\n    return cacheEntry?.value;\n  }\n\n  async mget(\n    keys: string[],\n  ): Promise<Record<string, Serializable | undefined>> {\n    const cacheStore = await this.#state.getKey<CacheStore>(this.prefix);\n\n    // If cache is not initialized, return empty object\n    if (!cacheStore) {\n      return {};\n    }\n\n    const keysAndValues = Object.entries(cacheStore).filter(([key]) =>\n      keys.includes(key),\n    );\n\n    const expiredKeys = keysAndValues.filter(\n      ([_unused, cacheEntry]) =>\n        cacheEntry && cacheEntry.expiresAt < Date.now(),\n    );\n\n    await this.mdelete(expiredKeys.map(([key]) => key));\n\n    const result: Record<string, Serializable | undefined> = {};\n\n    // First, handle keys that exist in the cache\n    keysAndValues.forEach(([key, cacheEntry]) => {\n      if (cacheEntry === undefined) {\n        this.#logger.info(`[StateCache] ❌ Cache miss for key \"${key}\"`);\n        result[key] = undefined;\n        return;\n      }\n\n      if (cacheEntry.expiresAt < Date.now()) {\n        this.#logger.info(`[StateCache] ⌛ Cache expired for key \"${key}\"`);\n        result[key] = undefined;\n      } else {\n        this.#logger.info(`[StateCache] 🎉 Cache hit for key \"${key}\"`);\n        result[key] = cacheEntry.value;\n      }\n    });\n\n    // Then, handle keys that don't exist in the cache\n    keys.forEach((key) => {\n      if (!Object.hasOwn(result, key)) {\n        this.#logger.info(`[StateCache] ❌ Cache miss for key \"${key}\"`);\n        result[key] = undefined;\n      }\n    });\n\n    return result;\n  }\n\n  async mset(\n    entries: { key: string; value: Serializable; ttlMilliseconds?: number }[],\n  ): Promise<void> {\n    if (entries.length === 0) {\n      return;\n    }\n\n    if (entries.length === 1) {\n      assert(entries[0]); // Enforce type narrowing as TS cannot infer that entries[0] is defined\n      const { key, value, ttlMilliseconds } = entries[0];\n      await this.set(key, value, ttlMilliseconds);\n      return;\n    }\n\n    entries.forEach(({ ttlMilliseconds }) => {\n      this.#validateTtlOrThrow(ttlMilliseconds);\n    });\n\n    // Using `state.update` is preferred for bulk `set`s, because it's more efficient and atomic.\n    await this.#state.update((stateValue) => {\n      const cacheStore = stateValue[this.prefix] ?? {};\n      entries.forEach(({ key, value, ttlMilliseconds }) => {\n        if (value === undefined) {\n          return;\n        }\n        cacheStore[key] = {\n          value,\n          expiresAt: Math.min(\n            Date.now() + (ttlMilliseconds ?? Number.MAX_SAFE_INTEGER),\n            Number.MAX_SAFE_INTEGER,\n          ),\n        };\n      });\n      stateValue[this.prefix] = cacheStore;\n      return stateValue;\n    });\n  }\n\n  async mdelete(keys: string[]): Promise<Record<string, boolean>> {\n    const result: Record<string, boolean> = {};\n\n    // Using `state.update` is preferred for bulk `delete`s, because it's more efficient and atomic.\n    await this.#state.update((stateValue) => {\n      const cacheStore = stateValue[this.prefix] ?? {};\n      keys.forEach((key) => {\n        if (cacheStore[key] === undefined) {\n          result[key] = false;\n        } else {\n          delete cacheStore[key];\n          result[key] = true;\n        }\n      });\n      stateValue[this.prefix] = cacheStore;\n      return stateValue;\n    });\n\n    return result;\n  }\n}\n"]}

package/dist/utils/cache/types.cjs

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.cjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.cjs","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"]}