@metamask-previews/storage-service 0.0.0-preview-d6fe4594 → 0.0.0-preview-2b2b3f4d

package/CHANGELOG.md

@@ -9,6 +9,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- Initial release of `@metamask/storage-service`
+- Initial release of `@metamask/storage-service` ([#7192](https://github.com/MetaMask/core/pull/7192))
 
 [Unreleased]: https://github.com/MetaMask/core/

package/README.md

@@ -50,12 +50,17 @@ class MyController extends BaseController<...> {
     );
   }
 
-  async getData(id: string): Promise<unknown> {
-    return await this.messenger.call(
+  async getData(id: string): Promise<string | undefined> {
+    const { result, error } = await this.messenger.call(
       'StorageService:getItem',
       'MyController',
       `${id}:data`,
     );
+    if (error) {
+      throw error;
+    }
+    // result is undefined if key doesn't exist
+    return result as string | undefined;
   }
 }
 ```
@@ -98,9 +103,17 @@ this.messenger.subscribe(
 Implement this interface to provide platform-specific storage:
 
 ```typescript
+import type { Json } from '@metamask/utils';
+
+// Response type for getItem - distinguishes found, not found, and error
+type StorageGetResult =
+  | { result: Json; error?: never } // Data found
+  | { result?: never; error: Error } // Error occurred
+  | Record<string, never>; // Key doesn't exist (empty object)
+
 export type StorageAdapter = {
-  getItem(namespace: string, key: string): Promise<unknown>;
-  setItem(namespace: string, key: string, value: unknown): Promise<void>;
+  getItem(namespace: string, key: string): Promise<StorageGetResult>;
+  setItem(namespace: string, key: string, value: Json): Promise<void>;
   removeItem(namespace: string, key: string): Promise<void>;
   getAllKeys(namespace: string): Promise<string[]>;
   clear(namespace: string): Promise<void>;
@@ -110,8 +123,8 @@ export type StorageAdapter = {
 Adapters are responsible for:
 
 - Building the full storage key (e.g., `storageService:namespace:key`)
-- Wrapping data with metadata before serialization
-- Serializing/deserializing data
+- Serializing/deserializing JSON data
+- Returning the correct response format for getItem
 
 ## Contributing
 

package/dist/InMemoryStorageAdapter.cjs

@@ -55,22 +55,22 @@ class InMemoryStorageAdapter {
      *
      * @param namespace - The controller namespace.
      * @param key - The data key.
-     * @returns The parsed JSON data, or null if not found.
+     * @returns StorageGetResult: { result } if found, {} if not found, { error } on failure.
      */
     async getItem(namespace, key) {
         const fullKey = `${types_1.STORAGE_KEY_PREFIX}${namespace}:${key}`;
         const serialized = __classPrivateFieldGet(this, _InMemoryStorageAdapter_storage, "f").get(fullKey);
-        if (!serialized) {
-            return null;
+        // Key not found - return empty object
+        if (serialized === undefined) {
+            return {};
         }
         try {
-            return JSON.parse(serialized);
+            const result = JSON.parse(serialized);
+            return { result };
         }
         catch (error) {
-            // istanbul ignore next - defensive error handling for corrupted data
             console.error(`Failed to parse stored data for ${fullKey}:`, error);
-            // istanbul ignore next
-            return null;
+            return { error: error };
         }
     }
     /**

package/dist/InMemoryStorageAdapter.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"InMemoryStorageAdapter.cjs","sourceRoot":"","sources":["../src/InMemoryStorageAdapter.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAGA,uCAA6C;AAE7C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAa,sBAAsB;IAOjC;;OAEG;IACH;QATA,gDAAgD;QAChD;;WAEG;QACM,kDAA8B;QAMrC,uBAAA,IAAI,mCAAY,IAAI,GAAG,EAAE,MAAA,CAAC;IAC5B,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,OAAO,CAAC,SAAiB,EAAE,GAAW;QAC1C,MAAM,OAAO,GAAG,GAAG,0BAAkB,GAAG,SAAS,IAAI,GAAG,EAAE,CAAC;QAC3D,MAAM,UAAU,GAAG,uBAAA,IAAI,uCAAS,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAE9C,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,KAAK,CAAC,UAAU,CAAS,CAAC;QACxC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,qEAAqE;YACrE,OAAO,CAAC,KAAK,CAAC,mCAAmC,OAAO,GAAG,EAAE,KAAK,CAAC,CAAC;YACpE,uBAAuB;YACvB,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,OAAO,CAAC,SAAiB,EAAE,GAAW,EAAE,KAAW;QACvD,MAAM,OAAO,GAAG,GAAG,0BAAkB,GAAG,SAAS,IAAI,GAAG,EAAE,CAAC;QAC3D,uBAAA,IAAI,uCAAS,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;IACpD,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,UAAU,CAAC,SAAiB,EAAE,GAAW;QAC7C,MAAM,OAAO,GAAG,GAAG,0BAAkB,GAAG,SAAS,IAAI,GAAG,EAAE,CAAC;QAC3D,uBAAA,IAAI,uCAAS,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAChC,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,UAAU,CAAC,SAAiB;QAChC,MAAM,MAAM,GAAG,GAAG,0BAAkB,GAAG,SAAS,GAAG,CAAC;QACpD,OAAO,KAAK,CAAC,IAAI,CAAC,uBAAA,IAAI,uCAAS,CAAC,IAAI,EAAE,CAAC;aACpC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;aACvC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IAC5C,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,KAAK,CAAC,SAAiB;QAC3B,MAAM,MAAM,GAAG,GAAG,0BAAkB,GAAG,SAAS,GAAG,CAAC;QACpD,MAAM,YAAY,GAAG,KAAK,CAAC,IAAI,CAAC,uBAAA,IAAI,uCAAS,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CACnE,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,CACvB,CAAC;QACF,YAAY,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,uBAAA,IAAI,uCAAS,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3D,CAAC;CACF;AA1FD,wDA0FC","sourcesContent":["import type { Json } from '@metamask/utils';\n\nimport type { StorageAdapter } from './types';\nimport { STORAGE_KEY_PREFIX } from './types';\n\n/**\n * In-memory storage adapter (default fallback).\n * Implements the {@link StorageAdapter} interface using a Map.\n *\n * ⚠️ **Warning**: Data is NOT persisted - lost on restart.\n *\n * **Suitable for:**\n * - Testing (isolated, no mocking needed)\n * - Development (quick start, zero config)\n * - Temporary/ephemeral data\n *\n * **Not suitable for:**\n * - Production (unless data is truly ephemeral)\n * - Data that needs to persist across restarts\n *\n * @example\n * ```typescript\n * const adapter = new InMemoryStorageAdapter();\n * await adapter.setItem('SnapController', 'snap-id:sourceCode', 'const x = 1;');\n * const value = await adapter.getItem('SnapController', 'snap-id:sourceCode'); // 'const x = 1;'\n * // After restart: data is lost\n * ```\n */\nexport class InMemoryStorageAdapter implements StorageAdapter {\n  // Explicitly implement StorageAdapter interface\n  /**\n   * Internal storage map.\n   */\n  readonly #storage: Map<string, string>;\n\n  /**\n   * Constructs a new InMemoryStorageAdapter.\n   */\n  constructor() {\n    this.#storage = new Map();\n  }\n\n  /**\n   * Retrieve an item from in-memory storage.\n   * Deserializes JSON data from storage.\n   *\n   * @param namespace - The controller namespace.\n   * @param key - The data key.\n   * @returns The parsed JSON data, or null if not found.\n   */\n  async getItem(namespace: string, key: string): Promise<Json | null> {\n    const fullKey = `${STORAGE_KEY_PREFIX}${namespace}:${key}`;\n    const serialized = this.#storage.get(fullKey);\n\n    if (!serialized) {\n      return null;\n    }\n\n    try {\n      return JSON.parse(serialized) as Json;\n    } catch (error) {\n      // istanbul ignore next - defensive error handling for corrupted data\n      console.error(`Failed to parse stored data for ${fullKey}:`, error);\n      // istanbul ignore next\n      return null;\n    }\n  }\n\n  /**\n   * Store an item in in-memory storage.\n   * Serializes JSON data to string.\n   *\n   * @param namespace - The controller namespace.\n   * @param key - The data key.\n   * @param value - The JSON value to store.\n   */\n  async setItem(namespace: string, key: string, value: Json): Promise<void> {\n    const fullKey = `${STORAGE_KEY_PREFIX}${namespace}:${key}`;\n    this.#storage.set(fullKey, JSON.stringify(value));\n  }\n\n  /**\n   * Remove an item from in-memory storage.\n   *\n   * @param namespace - The controller namespace.\n   * @param key - The data key.\n   */\n  async removeItem(namespace: string, key: string): Promise<void> {\n    const fullKey = `${STORAGE_KEY_PREFIX}${namespace}:${key}`;\n    this.#storage.delete(fullKey);\n  }\n\n  /**\n   * Get all keys for a namespace.\n   * Returns keys without the 'storage:namespace:' prefix.\n   *\n   * @param namespace - The namespace to get keys for.\n   * @returns Array of keys (without prefix) for this namespace.\n   */\n  async getAllKeys(namespace: string): Promise<string[]> {\n    const prefix = `${STORAGE_KEY_PREFIX}${namespace}:`;\n    return Array.from(this.#storage.keys())\n      .filter((key) => key.startsWith(prefix))\n      .map((key) => key.slice(prefix.length));\n  }\n\n  /**\n   * Clear all items for a namespace.\n   *\n   * @param namespace - The namespace to clear.\n   */\n  async clear(namespace: string): Promise<void> {\n    const prefix = `${STORAGE_KEY_PREFIX}${namespace}:`;\n    const keysToDelete = Array.from(this.#storage.keys()).filter((key) =>\n      key.startsWith(prefix),\n    );\n    keysToDelete.forEach((key) => this.#storage.delete(key));\n  }\n}\n"]}
+{"version":3,"file":"InMemoryStorageAdapter.cjs","sourceRoot":"","sources":["../src/InMemoryStorageAdapter.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAGA,uCAA6C;AAE7C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAa,sBAAsB;IAOjC;;OAEG;IACH;QATA,gDAAgD;QAChD;;WAEG;QACM,kDAA8B;QAMrC,uBAAA,IAAI,mCAAY,IAAI,GAAG,EAAE,MAAA,CAAC;IAC5B,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,OAAO,CAAC,SAAiB,EAAE,GAAW;QAC1C,MAAM,OAAO,GAAG,GAAG,0BAAkB,GAAG,SAAS,IAAI,GAAG,EAAE,CAAC;QAC3D,MAAM,UAAU,GAAG,uBAAA,IAAI,uCAAS,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAE9C,sCAAsC;QACtC,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC7B,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;YACtC,OAAO,EAAE,MAAM,EAAE,CAAC;QACpB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,CAAC,mCAAmC,OAAO,GAAG,EAAE,KAAK,CAAC,CAAC;YACpE,OAAO,EAAE,KAAK,EAAE,KAAc,EAAE,CAAC;QACnC,CAAC;IACH,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,OAAO,CAAC,SAAiB,EAAE,GAAW,EAAE,KAAW;QACvD,MAAM,OAAO,GAAG,GAAG,0BAAkB,GAAG,SAAS,IAAI,GAAG,EAAE,CAAC;QAC3D,uBAAA,IAAI,uCAAS,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;IACpD,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,UAAU,CAAC,SAAiB,EAAE,GAAW;QAC7C,MAAM,OAAO,GAAG,GAAG,0BAAkB,GAAG,SAAS,IAAI,GAAG,EAAE,CAAC;QAC3D,uBAAA,IAAI,uCAAS,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAChC,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,UAAU,CAAC,SAAiB;QAChC,MAAM,MAAM,GAAG,GAAG,0BAAkB,GAAG,SAAS,GAAG,CAAC;QACpD,OAAO,KAAK,CAAC,IAAI,CAAC,uBAAA,IAAI,uCAAS,CAAC,IAAI,EAAE,CAAC;aACpC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;aACvC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IAC5C,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,KAAK,CAAC,SAAiB;QAC3B,MAAM,MAAM,GAAG,GAAG,0BAAkB,GAAG,SAAS,GAAG,CAAC;QACpD,MAAM,YAAY,GAAG,KAAK,CAAC,IAAI,CAAC,uBAAA,IAAI,uCAAS,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CACnE,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,CACvB,CAAC;QACF,YAAY,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,uBAAA,IAAI,uCAAS,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3D,CAAC;CACF;AA1FD,wDA0FC","sourcesContent":["import type { Json } from '@metamask/utils';\n\nimport type { StorageAdapter, StorageGetResult } from './types';\nimport { STORAGE_KEY_PREFIX } from './types';\n\n/**\n * In-memory storage adapter (default fallback).\n * Implements the {@link StorageAdapter} interface using a Map.\n *\n * ⚠️ **Warning**: Data is NOT persisted - lost on restart.\n *\n * **Suitable for:**\n * - Testing (isolated, no mocking needed)\n * - Development (quick start, zero config)\n * - Temporary/ephemeral data\n *\n * **Not suitable for:**\n * - Production (unless data is truly ephemeral)\n * - Data that needs to persist across restarts\n *\n * @example\n * ```typescript\n * const adapter = new InMemoryStorageAdapter();\n * await adapter.setItem('SnapController', 'snap-id:sourceCode', 'const x = 1;');\n * const value = await adapter.getItem('SnapController', 'snap-id:sourceCode'); // 'const x = 1;'\n * // After restart: data is lost\n * ```\n */\nexport class InMemoryStorageAdapter implements StorageAdapter {\n  // Explicitly implement StorageAdapter interface\n  /**\n   * Internal storage map.\n   */\n  readonly #storage: Map<string, string>;\n\n  /**\n   * Constructs a new InMemoryStorageAdapter.\n   */\n  constructor() {\n    this.#storage = new Map();\n  }\n\n  /**\n   * Retrieve an item from in-memory storage.\n   * Deserializes JSON data from storage.\n   *\n   * @param namespace - The controller namespace.\n   * @param key - The data key.\n   * @returns StorageGetResult: { result } if found, {} if not found, { error } on failure.\n   */\n  async getItem(namespace: string, key: string): Promise<StorageGetResult> {\n    const fullKey = `${STORAGE_KEY_PREFIX}${namespace}:${key}`;\n    const serialized = this.#storage.get(fullKey);\n\n    // Key not found - return empty object\n    if (serialized === undefined) {\n      return {};\n    }\n\n    try {\n      const result = JSON.parse(serialized);\n      return { result };\n    } catch (error) {\n      console.error(`Failed to parse stored data for ${fullKey}:`, error);\n      return { error: error as Error };\n    }\n  }\n\n  /**\n   * Store an item in in-memory storage.\n   * Serializes JSON data to string.\n   *\n   * @param namespace - The controller namespace.\n   * @param key - The data key.\n   * @param value - The JSON value to store.\n   */\n  async setItem(namespace: string, key: string, value: Json): Promise<void> {\n    const fullKey = `${STORAGE_KEY_PREFIX}${namespace}:${key}`;\n    this.#storage.set(fullKey, JSON.stringify(value));\n  }\n\n  /**\n   * Remove an item from in-memory storage.\n   *\n   * @param namespace - The controller namespace.\n   * @param key - The data key.\n   */\n  async removeItem(namespace: string, key: string): Promise<void> {\n    const fullKey = `${STORAGE_KEY_PREFIX}${namespace}:${key}`;\n    this.#storage.delete(fullKey);\n  }\n\n  /**\n   * Get all keys for a namespace.\n   * Returns keys without the 'storage:namespace:' prefix.\n   *\n   * @param namespace - The namespace to get keys for.\n   * @returns Array of keys (without prefix) for this namespace.\n   */\n  async getAllKeys(namespace: string): Promise<string[]> {\n    const prefix = `${STORAGE_KEY_PREFIX}${namespace}:`;\n    return Array.from(this.#storage.keys())\n      .filter((key) => key.startsWith(prefix))\n      .map((key) => key.slice(prefix.length));\n  }\n\n  /**\n   * Clear all items for a namespace.\n   *\n   * @param namespace - The namespace to clear.\n   */\n  async clear(namespace: string): Promise<void> {\n    const prefix = `${STORAGE_KEY_PREFIX}${namespace}:`;\n    const keysToDelete = Array.from(this.#storage.keys()).filter((key) =>\n      key.startsWith(prefix),\n    );\n    keysToDelete.forEach((key) => this.#storage.delete(key));\n  }\n}\n"]}

package/dist/InMemoryStorageAdapter.d.cts

@@ -1,5 +1,5 @@
 import type { Json } from "@metamask/utils";
-import type { StorageAdapter } from "./types.cjs";
+import type { StorageAdapter, StorageGetResult } from "./types.cjs";
 /**
  * In-memory storage adapter (default fallback).
  * Implements the {@link StorageAdapter} interface using a Map.
@@ -35,9 +35,9 @@ export declare class InMemoryStorageAdapter implements StorageAdapter {
      *
      * @param namespace - The controller namespace.
      * @param key - The data key.
-     * @returns The parsed JSON data, or null if not found.
+     * @returns StorageGetResult: { result } if found, {} if not found, { error } on failure.
      */
-    getItem(namespace: string, key: string): Promise<Json | null>;
+    getItem(namespace: string, key: string): Promise<StorageGetResult>;
     /**
      * Store an item in in-memory storage.
      * Serializes JSON data to string.

package/dist/InMemoryStorageAdapter.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"InMemoryStorageAdapter.d.cts","sourceRoot":"","sources":["../src/InMemoryStorageAdapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,wBAAwB;AAE5C,OAAO,KAAK,EAAE,cAAc,EAAE,oBAAgB;AAG9C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,sBAAuB,YAAW,cAAc;;IAO3D;;OAEG;;IAKH;;;;;;;OAOG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;IAkBnE;;;;;;;OAOG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAKzE;;;;;OAKG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK/D;;;;;;OAMG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAOtD;;;;OAIG;IACG,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAO9C"}
+{"version":3,"file":"InMemoryStorageAdapter.d.cts","sourceRoot":"","sources":["../src/InMemoryStorageAdapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,wBAAwB;AAE5C,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,oBAAgB;AAGhE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,sBAAuB,YAAW,cAAc;;IAO3D;;OAEG;;IAKH;;;;;;;OAOG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAkBxE;;;;;;;OAOG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAKzE;;;;;OAKG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK/D;;;;;;OAMG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAOtD;;;;OAIG;IACG,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAO9C"}

package/dist/InMemoryStorageAdapter.d.mts

@@ -1,5 +1,5 @@
 import type { Json } from "@metamask/utils";
-import type { StorageAdapter } from "./types.mjs";
+import type { StorageAdapter, StorageGetResult } from "./types.mjs";
 /**
  * In-memory storage adapter (default fallback).
  * Implements the {@link StorageAdapter} interface using a Map.
@@ -35,9 +35,9 @@ export declare class InMemoryStorageAdapter implements StorageAdapter {
      *
      * @param namespace - The controller namespace.
      * @param key - The data key.
-     * @returns The parsed JSON data, or null if not found.
+     * @returns StorageGetResult: { result } if found, {} if not found, { error } on failure.
      */
-    getItem(namespace: string, key: string): Promise<Json | null>;
+    getItem(namespace: string, key: string): Promise<StorageGetResult>;
     /**
      * Store an item in in-memory storage.
      * Serializes JSON data to string.

package/dist/InMemoryStorageAdapter.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"InMemoryStorageAdapter.d.mts","sourceRoot":"","sources":["../src/InMemoryStorageAdapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,wBAAwB;AAE5C,OAAO,KAAK,EAAE,cAAc,EAAE,oBAAgB;AAG9C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,sBAAuB,YAAW,cAAc;;IAO3D;;OAEG;;IAKH;;;;;;;OAOG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;IAkBnE;;;;;;;OAOG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAKzE;;;;;OAKG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK/D;;;;;;OAMG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAOtD;;;;OAIG;IACG,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAO9C"}
+{"version":3,"file":"InMemoryStorageAdapter.d.mts","sourceRoot":"","sources":["../src/InMemoryStorageAdapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,wBAAwB;AAE5C,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,oBAAgB;AAGhE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,sBAAuB,YAAW,cAAc;;IAO3D;;OAEG;;IAKH;;;;;;;OAOG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAkBxE;;;;;;;OAOG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAKzE;;;;;OAKG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK/D;;;;;;OAMG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAOtD;;;;OAIG;IACG,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAO9C"}

package/dist/InMemoryStorageAdapter.mjs

@@ -52,22 +52,22 @@ export class InMemoryStorageAdapter {
      *
      * @param namespace - The controller namespace.
      * @param key - The data key.
-     * @returns The parsed JSON data, or null if not found.
+     * @returns StorageGetResult: { result } if found, {} if not found, { error } on failure.
      */
     async getItem(namespace, key) {
         const fullKey = `${STORAGE_KEY_PREFIX}${namespace}:${key}`;
         const serialized = __classPrivateFieldGet(this, _InMemoryStorageAdapter_storage, "f").get(fullKey);
-        if (!serialized) {
-            return null;
+        // Key not found - return empty object
+        if (serialized === undefined) {
+            return {};
         }
         try {
-            return JSON.parse(serialized);
+            const result = JSON.parse(serialized);
+            return { result };
         }
         catch (error) {
-            // istanbul ignore next - defensive error handling for corrupted data
             console.error(`Failed to parse stored data for ${fullKey}:`, error);
-            // istanbul ignore next
-            return null;
+            return { error: error };
         }
     }
     /**

package/dist/InMemoryStorageAdapter.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"InMemoryStorageAdapter.mjs","sourceRoot":"","sources":["../src/InMemoryStorageAdapter.ts"],"names":[],"mappings":";;;;;;;;;;;;AAGA,OAAO,EAAE,kBAAkB,EAAE,oBAAgB;AAE7C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,OAAO,sBAAsB;IAOjC;;OAEG;IACH;QATA,gDAAgD;QAChD;;WAEG;QACM,kDAA8B;QAMrC,uBAAA,IAAI,mCAAY,IAAI,GAAG,EAAE,MAAA,CAAC;IAC5B,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,OAAO,CAAC,SAAiB,EAAE,GAAW;QAC1C,MAAM,OAAO,GAAG,GAAG,kBAAkB,GAAG,SAAS,IAAI,GAAG,EAAE,CAAC;QAC3D,MAAM,UAAU,GAAG,uBAAA,IAAI,uCAAS,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAE9C,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,KAAK,CAAC,UAAU,CAAS,CAAC;QACxC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,qEAAqE;YACrE,OAAO,CAAC,KAAK,CAAC,mCAAmC,OAAO,GAAG,EAAE,KAAK,CAAC,CAAC;YACpE,uBAAuB;YACvB,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,OAAO,CAAC,SAAiB,EAAE,GAAW,EAAE,KAAW;QACvD,MAAM,OAAO,GAAG,GAAG,kBAAkB,GAAG,SAAS,IAAI,GAAG,EAAE,CAAC;QAC3D,uBAAA,IAAI,uCAAS,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;IACpD,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,UAAU,CAAC,SAAiB,EAAE,GAAW;QAC7C,MAAM,OAAO,GAAG,GAAG,kBAAkB,GAAG,SAAS,IAAI,GAAG,EAAE,CAAC;QAC3D,uBAAA,IAAI,uCAAS,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAChC,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,UAAU,CAAC,SAAiB;QAChC,MAAM,MAAM,GAAG,GAAG,kBAAkB,GAAG,SAAS,GAAG,CAAC;QACpD,OAAO,KAAK,CAAC,IAAI,CAAC,uBAAA,IAAI,uCAAS,CAAC,IAAI,EAAE,CAAC;aACpC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;aACvC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IAC5C,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,KAAK,CAAC,SAAiB;QAC3B,MAAM,MAAM,GAAG,GAAG,kBAAkB,GAAG,SAAS,GAAG,CAAC;QACpD,MAAM,YAAY,GAAG,KAAK,CAAC,IAAI,CAAC,uBAAA,IAAI,uCAAS,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CACnE,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,CACvB,CAAC;QACF,YAAY,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,uBAAA,IAAI,uCAAS,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3D,CAAC;CACF","sourcesContent":["import type { Json } from '@metamask/utils';\n\nimport type { StorageAdapter } from './types';\nimport { STORAGE_KEY_PREFIX } from './types';\n\n/**\n * In-memory storage adapter (default fallback).\n * Implements the {@link StorageAdapter} interface using a Map.\n *\n * ⚠️ **Warning**: Data is NOT persisted - lost on restart.\n *\n * **Suitable for:**\n * - Testing (isolated, no mocking needed)\n * - Development (quick start, zero config)\n * - Temporary/ephemeral data\n *\n * **Not suitable for:**\n * - Production (unless data is truly ephemeral)\n * - Data that needs to persist across restarts\n *\n * @example\n * ```typescript\n * const adapter = new InMemoryStorageAdapter();\n * await adapter.setItem('SnapController', 'snap-id:sourceCode', 'const x = 1;');\n * const value = await adapter.getItem('SnapController', 'snap-id:sourceCode'); // 'const x = 1;'\n * // After restart: data is lost\n * ```\n */\nexport class InMemoryStorageAdapter implements StorageAdapter {\n  // Explicitly implement StorageAdapter interface\n  /**\n   * Internal storage map.\n   */\n  readonly #storage: Map<string, string>;\n\n  /**\n   * Constructs a new InMemoryStorageAdapter.\n   */\n  constructor() {\n    this.#storage = new Map();\n  }\n\n  /**\n   * Retrieve an item from in-memory storage.\n   * Deserializes JSON data from storage.\n   *\n   * @param namespace - The controller namespace.\n   * @param key - The data key.\n   * @returns The parsed JSON data, or null if not found.\n   */\n  async getItem(namespace: string, key: string): Promise<Json | null> {\n    const fullKey = `${STORAGE_KEY_PREFIX}${namespace}:${key}`;\n    const serialized = this.#storage.get(fullKey);\n\n    if (!serialized) {\n      return null;\n    }\n\n    try {\n      return JSON.parse(serialized) as Json;\n    } catch (error) {\n      // istanbul ignore next - defensive error handling for corrupted data\n      console.error(`Failed to parse stored data for ${fullKey}:`, error);\n      // istanbul ignore next\n      return null;\n    }\n  }\n\n  /**\n   * Store an item in in-memory storage.\n   * Serializes JSON data to string.\n   *\n   * @param namespace - The controller namespace.\n   * @param key - The data key.\n   * @param value - The JSON value to store.\n   */\n  async setItem(namespace: string, key: string, value: Json): Promise<void> {\n    const fullKey = `${STORAGE_KEY_PREFIX}${namespace}:${key}`;\n    this.#storage.set(fullKey, JSON.stringify(value));\n  }\n\n  /**\n   * Remove an item from in-memory storage.\n   *\n   * @param namespace - The controller namespace.\n   * @param key - The data key.\n   */\n  async removeItem(namespace: string, key: string): Promise<void> {\n    const fullKey = `${STORAGE_KEY_PREFIX}${namespace}:${key}`;\n    this.#storage.delete(fullKey);\n  }\n\n  /**\n   * Get all keys for a namespace.\n   * Returns keys without the 'storage:namespace:' prefix.\n   *\n   * @param namespace - The namespace to get keys for.\n   * @returns Array of keys (without prefix) for this namespace.\n   */\n  async getAllKeys(namespace: string): Promise<string[]> {\n    const prefix = `${STORAGE_KEY_PREFIX}${namespace}:`;\n    return Array.from(this.#storage.keys())\n      .filter((key) => key.startsWith(prefix))\n      .map((key) => key.slice(prefix.length));\n  }\n\n  /**\n   * Clear all items for a namespace.\n   *\n   * @param namespace - The namespace to clear.\n   */\n  async clear(namespace: string): Promise<void> {\n    const prefix = `${STORAGE_KEY_PREFIX}${namespace}:`;\n    const keysToDelete = Array.from(this.#storage.keys()).filter((key) =>\n      key.startsWith(prefix),\n    );\n    keysToDelete.forEach((key) => this.#storage.delete(key));\n  }\n}\n"]}
+{"version":3,"file":"InMemoryStorageAdapter.mjs","sourceRoot":"","sources":["../src/InMemoryStorageAdapter.ts"],"names":[],"mappings":";;;;;;;;;;;;AAGA,OAAO,EAAE,kBAAkB,EAAE,oBAAgB;AAE7C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,OAAO,sBAAsB;IAOjC;;OAEG;IACH;QATA,gDAAgD;QAChD;;WAEG;QACM,kDAA8B;QAMrC,uBAAA,IAAI,mCAAY,IAAI,GAAG,EAAE,MAAA,CAAC;IAC5B,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,OAAO,CAAC,SAAiB,EAAE,GAAW;QAC1C,MAAM,OAAO,GAAG,GAAG,kBAAkB,GAAG,SAAS,IAAI,GAAG,EAAE,CAAC;QAC3D,MAAM,UAAU,GAAG,uBAAA,IAAI,uCAAS,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAE9C,sCAAsC;QACtC,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC7B,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;YACtC,OAAO,EAAE,MAAM,EAAE,CAAC;QACpB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,CAAC,mCAAmC,OAAO,GAAG,EAAE,KAAK,CAAC,CAAC;YACpE,OAAO,EAAE,KAAK,EAAE,KAAc,EAAE,CAAC;QACnC,CAAC;IACH,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,OAAO,CAAC,SAAiB,EAAE,GAAW,EAAE,KAAW;QACvD,MAAM,OAAO,GAAG,GAAG,kBAAkB,GAAG,SAAS,IAAI,GAAG,EAAE,CAAC;QAC3D,uBAAA,IAAI,uCAAS,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;IACpD,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,UAAU,CAAC,SAAiB,EAAE,GAAW;QAC7C,MAAM,OAAO,GAAG,GAAG,kBAAkB,GAAG,SAAS,IAAI,GAAG,EAAE,CAAC;QAC3D,uBAAA,IAAI,uCAAS,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAChC,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,UAAU,CAAC,SAAiB;QAChC,MAAM,MAAM,GAAG,GAAG,kBAAkB,GAAG,SAAS,GAAG,CAAC;QACpD,OAAO,KAAK,CAAC,IAAI,CAAC,uBAAA,IAAI,uCAAS,CAAC,IAAI,EAAE,CAAC;aACpC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;aACvC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IAC5C,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,KAAK,CAAC,SAAiB;QAC3B,MAAM,MAAM,GAAG,GAAG,kBAAkB,GAAG,SAAS,GAAG,CAAC;QACpD,MAAM,YAAY,GAAG,KAAK,CAAC,IAAI,CAAC,uBAAA,IAAI,uCAAS,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CACnE,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,CACvB,CAAC;QACF,YAAY,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,uBAAA,IAAI,uCAAS,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3D,CAAC;CACF","sourcesContent":["import type { Json } from '@metamask/utils';\n\nimport type { StorageAdapter, StorageGetResult } from './types';\nimport { STORAGE_KEY_PREFIX } from './types';\n\n/**\n * In-memory storage adapter (default fallback).\n * Implements the {@link StorageAdapter} interface using a Map.\n *\n * ⚠️ **Warning**: Data is NOT persisted - lost on restart.\n *\n * **Suitable for:**\n * - Testing (isolated, no mocking needed)\n * - Development (quick start, zero config)\n * - Temporary/ephemeral data\n *\n * **Not suitable for:**\n * - Production (unless data is truly ephemeral)\n * - Data that needs to persist across restarts\n *\n * @example\n * ```typescript\n * const adapter = new InMemoryStorageAdapter();\n * await adapter.setItem('SnapController', 'snap-id:sourceCode', 'const x = 1;');\n * const value = await adapter.getItem('SnapController', 'snap-id:sourceCode'); // 'const x = 1;'\n * // After restart: data is lost\n * ```\n */\nexport class InMemoryStorageAdapter implements StorageAdapter {\n  // Explicitly implement StorageAdapter interface\n  /**\n   * Internal storage map.\n   */\n  readonly #storage: Map<string, string>;\n\n  /**\n   * Constructs a new InMemoryStorageAdapter.\n   */\n  constructor() {\n    this.#storage = new Map();\n  }\n\n  /**\n   * Retrieve an item from in-memory storage.\n   * Deserializes JSON data from storage.\n   *\n   * @param namespace - The controller namespace.\n   * @param key - The data key.\n   * @returns StorageGetResult: { result } if found, {} if not found, { error } on failure.\n   */\n  async getItem(namespace: string, key: string): Promise<StorageGetResult> {\n    const fullKey = `${STORAGE_KEY_PREFIX}${namespace}:${key}`;\n    const serialized = this.#storage.get(fullKey);\n\n    // Key not found - return empty object\n    if (serialized === undefined) {\n      return {};\n    }\n\n    try {\n      const result = JSON.parse(serialized);\n      return { result };\n    } catch (error) {\n      console.error(`Failed to parse stored data for ${fullKey}:`, error);\n      return { error: error as Error };\n    }\n  }\n\n  /**\n   * Store an item in in-memory storage.\n   * Serializes JSON data to string.\n   *\n   * @param namespace - The controller namespace.\n   * @param key - The data key.\n   * @param value - The JSON value to store.\n   */\n  async setItem(namespace: string, key: string, value: Json): Promise<void> {\n    const fullKey = `${STORAGE_KEY_PREFIX}${namespace}:${key}`;\n    this.#storage.set(fullKey, JSON.stringify(value));\n  }\n\n  /**\n   * Remove an item from in-memory storage.\n   *\n   * @param namespace - The controller namespace.\n   * @param key - The data key.\n   */\n  async removeItem(namespace: string, key: string): Promise<void> {\n    const fullKey = `${STORAGE_KEY_PREFIX}${namespace}:${key}`;\n    this.#storage.delete(fullKey);\n  }\n\n  /**\n   * Get all keys for a namespace.\n   * Returns keys without the 'storage:namespace:' prefix.\n   *\n   * @param namespace - The namespace to get keys for.\n   * @returns Array of keys (without prefix) for this namespace.\n   */\n  async getAllKeys(namespace: string): Promise<string[]> {\n    const prefix = `${STORAGE_KEY_PREFIX}${namespace}:`;\n    return Array.from(this.#storage.keys())\n      .filter((key) => key.startsWith(prefix))\n      .map((key) => key.slice(prefix.length));\n  }\n\n  /**\n   * Clear all items for a namespace.\n   *\n   * @param namespace - The namespace to clear.\n   */\n  async clear(namespace: string): Promise<void> {\n    const prefix = `${STORAGE_KEY_PREFIX}${namespace}:`;\n    const keysToDelete = Array.from(this.#storage.keys()).filter((key) =>\n      key.startsWith(prefix),\n    );\n    keysToDelete.forEach((key) => this.#storage.delete(key));\n  }\n}\n"]}

package/dist/StorageService-method-action-types.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"StorageService-method-action-types.cjs","sourceRoot":"","sources":["../src/StorageService-method-action-types.ts"],"names":[],"mappings":";AAAA;;;GAGG","sourcesContent":["/**\n * This file is auto generated by `scripts/generate-method-action-types.ts`.\n * Do not edit manually.\n */\n\nimport type { StorageService } from './StorageService';\n\n/**\n * Store large JSON data in storage.\n *\n * ⚠️ **Designed for large values (100KB+), not many small ones.**\n * Each storage operation has I/O overhead. For best performance,\n * store one large object rather than many small key-value pairs.\n *\n * @example Good: Store entire cache as one value\n * ```typescript\n * await service.setItem('TokenList', 'cache', { '0x1': [...], '0x38': [...] });\n * ```\n *\n * @example Avoid: Many small values\n * ```typescript\n * // ❌ Don't do this - too many small writes\n * await service.setItem('TokenList', 'cache:0x1', [...]);\n * await service.setItem('TokenList', 'cache:0x38', [...]);\n * ```\n *\n * @param namespace - Controller namespace (e.g., 'SnapController').\n * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').\n * @param value - JSON data to store (should be 100KB+ for optimal use).\n */\nexport type StorageServiceSetItemAction = {\n  type: `StorageService:setItem`;\n  handler: StorageService['setItem'];\n};\n\n/**\n * Retrieve JSON data from storage.\n *\n * @param namespace - Controller namespace (e.g., 'SnapController').\n * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').\n * @returns Parsed JSON data or null if not found.\n */\nexport type StorageServiceGetItemAction = {\n  type: `StorageService:getItem`;\n  handler: StorageService['getItem'];\n};\n\n/**\n * Remove data from storage.\n *\n * @param namespace - Controller namespace (e.g., 'SnapController').\n * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').\n */\nexport type StorageServiceRemoveItemAction = {\n  type: `StorageService:removeItem`;\n  handler: StorageService['removeItem'];\n};\n\n/**\n * Get all keys for a namespace.\n * Delegates to storage adapter which handles filtering.\n *\n * @param namespace - Controller namespace (e.g., 'SnapController').\n * @returns Array of keys (without prefix) for this namespace.\n */\nexport type StorageServiceGetAllKeysAction = {\n  type: `StorageService:getAllKeys`;\n  handler: StorageService['getAllKeys'];\n};\n\n/**\n * Clear all data for a namespace.\n *\n * @param namespace - Controller namespace (e.g., 'SnapController').\n */\nexport type StorageServiceClearAction = {\n  type: `StorageService:clear`;\n  handler: StorageService['clear'];\n};\n\n/**\n * Union of all StorageService action types.\n */\nexport type StorageServiceMethodActions =\n  | StorageServiceSetItemAction\n  | StorageServiceGetItemAction\n  | StorageServiceRemoveItemAction\n  | StorageServiceGetAllKeysAction\n  | StorageServiceClearAction;\n"]}
+{"version":3,"file":"StorageService-method-action-types.cjs","sourceRoot":"","sources":["../src/StorageService-method-action-types.ts"],"names":[],"mappings":";AAAA;;;GAGG","sourcesContent":["/**\n * This file is auto generated by `scripts/generate-method-action-types.ts`.\n * Do not edit manually.\n */\n\nimport type { StorageService } from './StorageService';\n\n/**\n * Store large JSON data in storage.\n *\n * ⚠️ **Designed for large values (100KB+), not many small ones.**\n * Each storage operation has I/O overhead. For best performance,\n * store one large object rather than many small key-value pairs.\n *\n * @example Good: Store entire cache as one value\n * ```typescript\n * await service.setItem('TokenList', 'cache', { '0x1': [...], '0x38': [...] });\n * ```\n *\n * @example Avoid: Many small values\n * ```typescript\n * // ❌ Don't do this - too many small writes\n * await service.setItem('TokenList', 'cache:0x1', [...]);\n * await service.setItem('TokenList', 'cache:0x38', [...]);\n * ```\n *\n * @param namespace - Controller namespace (e.g., 'SnapController').\n * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').\n * @param value - JSON data to store (should be 100KB+ for optimal use).\n */\nexport type StorageServiceSetItemAction = {\n  type: `StorageService:setItem`;\n  handler: StorageService['setItem'];\n};\n\n/**\n * Retrieve JSON data from storage.\n *\n * @param namespace - Controller namespace (e.g., 'SnapController').\n * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').\n * @returns StorageGetResult: { result } if found, {} if not found, { error } on failure.\n */\nexport type StorageServiceGetItemAction = {\n  type: `StorageService:getItem`;\n  handler: StorageService['getItem'];\n};\n\n/**\n * Remove data from storage.\n *\n * @param namespace - Controller namespace (e.g., 'SnapController').\n * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').\n */\nexport type StorageServiceRemoveItemAction = {\n  type: `StorageService:removeItem`;\n  handler: StorageService['removeItem'];\n};\n\n/**\n * Get all keys for a namespace.\n * Delegates to storage adapter which handles filtering.\n *\n * @param namespace - Controller namespace (e.g., 'SnapController').\n * @returns Array of keys (without prefix) for this namespace.\n */\nexport type StorageServiceGetAllKeysAction = {\n  type: `StorageService:getAllKeys`;\n  handler: StorageService['getAllKeys'];\n};\n\n/**\n * Clear all data for a namespace.\n *\n * @param namespace - Controller namespace (e.g., 'SnapController').\n */\nexport type StorageServiceClearAction = {\n  type: `StorageService:clear`;\n  handler: StorageService['clear'];\n};\n\n/**\n * Union of all StorageService action types.\n */\nexport type StorageServiceMethodActions =\n  | StorageServiceSetItemAction\n  | StorageServiceGetItemAction\n  | StorageServiceRemoveItemAction\n  | StorageServiceGetAllKeysAction\n  | StorageServiceClearAction;\n"]}

package/dist/StorageService-method-action-types.d.cts

@@ -35,7 +35,7 @@ export type StorageServiceSetItemAction = {
  *
  * @param namespace - Controller namespace (e.g., 'SnapController').
  * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').
- * @returns Parsed JSON data or null if not found.
+ * @returns StorageGetResult: { result } if found, {} if not found, { error } on failure.
  */
 export type StorageServiceGetItemAction = {
     type: `StorageService:getItem`;

package/dist/StorageService-method-action-types.d.mts

@@ -35,7 +35,7 @@ export type StorageServiceSetItemAction = {
  *
  * @param namespace - Controller namespace (e.g., 'SnapController').
  * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').
- * @returns Parsed JSON data or null if not found.
+ * @returns StorageGetResult: { result } if found, {} if not found, { error } on failure.
  */
 export type StorageServiceGetItemAction = {
     type: `StorageService:getItem`;

package/dist/StorageService-method-action-types.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"StorageService-method-action-types.mjs","sourceRoot":"","sources":["../src/StorageService-method-action-types.ts"],"names":[],"mappings":"AAAA;;;GAGG","sourcesContent":["/**\n * This file is auto generated by `scripts/generate-method-action-types.ts`.\n * Do not edit manually.\n */\n\nimport type { StorageService } from './StorageService';\n\n/**\n * Store large JSON data in storage.\n *\n * ⚠️ **Designed for large values (100KB+), not many small ones.**\n * Each storage operation has I/O overhead. For best performance,\n * store one large object rather than many small key-value pairs.\n *\n * @example Good: Store entire cache as one value\n * ```typescript\n * await service.setItem('TokenList', 'cache', { '0x1': [...], '0x38': [...] });\n * ```\n *\n * @example Avoid: Many small values\n * ```typescript\n * // ❌ Don't do this - too many small writes\n * await service.setItem('TokenList', 'cache:0x1', [...]);\n * await service.setItem('TokenList', 'cache:0x38', [...]);\n * ```\n *\n * @param namespace - Controller namespace (e.g., 'SnapController').\n * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').\n * @param value - JSON data to store (should be 100KB+ for optimal use).\n */\nexport type StorageServiceSetItemAction = {\n  type: `StorageService:setItem`;\n  handler: StorageService['setItem'];\n};\n\n/**\n * Retrieve JSON data from storage.\n *\n * @param namespace - Controller namespace (e.g., 'SnapController').\n * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').\n * @returns Parsed JSON data or null if not found.\n */\nexport type StorageServiceGetItemAction = {\n  type: `StorageService:getItem`;\n  handler: StorageService['getItem'];\n};\n\n/**\n * Remove data from storage.\n *\n * @param namespace - Controller namespace (e.g., 'SnapController').\n * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').\n */\nexport type StorageServiceRemoveItemAction = {\n  type: `StorageService:removeItem`;\n  handler: StorageService['removeItem'];\n};\n\n/**\n * Get all keys for a namespace.\n * Delegates to storage adapter which handles filtering.\n *\n * @param namespace - Controller namespace (e.g., 'SnapController').\n * @returns Array of keys (without prefix) for this namespace.\n */\nexport type StorageServiceGetAllKeysAction = {\n  type: `StorageService:getAllKeys`;\n  handler: StorageService['getAllKeys'];\n};\n\n/**\n * Clear all data for a namespace.\n *\n * @param namespace - Controller namespace (e.g., 'SnapController').\n */\nexport type StorageServiceClearAction = {\n  type: `StorageService:clear`;\n  handler: StorageService['clear'];\n};\n\n/**\n * Union of all StorageService action types.\n */\nexport type StorageServiceMethodActions =\n  | StorageServiceSetItemAction\n  | StorageServiceGetItemAction\n  | StorageServiceRemoveItemAction\n  | StorageServiceGetAllKeysAction\n  | StorageServiceClearAction;\n"]}
+{"version":3,"file":"StorageService-method-action-types.mjs","sourceRoot":"","sources":["../src/StorageService-method-action-types.ts"],"names":[],"mappings":"AAAA;;;GAGG","sourcesContent":["/**\n * This file is auto generated by `scripts/generate-method-action-types.ts`.\n * Do not edit manually.\n */\n\nimport type { StorageService } from './StorageService';\n\n/**\n * Store large JSON data in storage.\n *\n * ⚠️ **Designed for large values (100KB+), not many small ones.**\n * Each storage operation has I/O overhead. For best performance,\n * store one large object rather than many small key-value pairs.\n *\n * @example Good: Store entire cache as one value\n * ```typescript\n * await service.setItem('TokenList', 'cache', { '0x1': [...], '0x38': [...] });\n * ```\n *\n * @example Avoid: Many small values\n * ```typescript\n * // ❌ Don't do this - too many small writes\n * await service.setItem('TokenList', 'cache:0x1', [...]);\n * await service.setItem('TokenList', 'cache:0x38', [...]);\n * ```\n *\n * @param namespace - Controller namespace (e.g., 'SnapController').\n * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').\n * @param value - JSON data to store (should be 100KB+ for optimal use).\n */\nexport type StorageServiceSetItemAction = {\n  type: `StorageService:setItem`;\n  handler: StorageService['setItem'];\n};\n\n/**\n * Retrieve JSON data from storage.\n *\n * @param namespace - Controller namespace (e.g., 'SnapController').\n * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').\n * @returns StorageGetResult: { result } if found, {} if not found, { error } on failure.\n */\nexport type StorageServiceGetItemAction = {\n  type: `StorageService:getItem`;\n  handler: StorageService['getItem'];\n};\n\n/**\n * Remove data from storage.\n *\n * @param namespace - Controller namespace (e.g., 'SnapController').\n * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').\n */\nexport type StorageServiceRemoveItemAction = {\n  type: `StorageService:removeItem`;\n  handler: StorageService['removeItem'];\n};\n\n/**\n * Get all keys for a namespace.\n * Delegates to storage adapter which handles filtering.\n *\n * @param namespace - Controller namespace (e.g., 'SnapController').\n * @returns Array of keys (without prefix) for this namespace.\n */\nexport type StorageServiceGetAllKeysAction = {\n  type: `StorageService:getAllKeys`;\n  handler: StorageService['getAllKeys'];\n};\n\n/**\n * Clear all data for a namespace.\n *\n * @param namespace - Controller namespace (e.g., 'SnapController').\n */\nexport type StorageServiceClearAction = {\n  type: `StorageService:clear`;\n  handler: StorageService['clear'];\n};\n\n/**\n * Union of all StorageService action types.\n */\nexport type StorageServiceMethodActions =\n  | StorageServiceSetItemAction\n  | StorageServiceGetItemAction\n  | StorageServiceRemoveItemAction\n  | StorageServiceGetAllKeysAction\n  | StorageServiceClearAction;\n"]}

package/dist/StorageService.cjs

@@ -62,13 +62,16 @@ const MESSENGER_EXPOSED_METHODS = [
  *     );
  *   }
  *
- *   async getSnapSourceCode(snapId: string): Promise<string | null> {
- *     const result = await this.messenger.call(
+ *   async getSnapSourceCode(snapId: string): Promise<string | undefined> {
+ *     const { result, error } = await this.messenger.call(
  *       'StorageService:getItem',
  *       'SnapController',
  *       `${snapId}:sourceCode`,
  *     );
- *     return result as string | null; // Caller must validate/cast
+ *     if (error) {
+ *       throw error; // Handle error
+ *     }
+ *     return result as string | undefined; // undefined if not found
  *   }
  * }
  * ```
@@ -160,7 +163,7 @@ class StorageService {
      *
      * @param namespace - Controller namespace (e.g., 'SnapController').
      * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').
-     * @returns Parsed JSON data or null if not found.
+     * @returns StorageGetResult: { result } if found, {} if not found, { error } on failure.
      */
     async getItem(namespace, key) {
         // Adapter handles deserialization and unwrapping

package/dist/StorageService.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"StorageService.cjs","sourceRoot":"","sources":["../src/StorageService.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAEA,yEAAkE;AAMlE,uCAAuC;AAEvC,oBAAoB;AAEpB,MAAM,yBAAyB,GAAG;IAChC,SAAS;IACT,SAAS;IACT,YAAY;IACZ,YAAY;IACZ,OAAO;CACC,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AACH,MAAa,cAAc;IAgBzB;;;;;;;OAOG;IACH,YAAY,EAAE,SAAS,EAAE,OAAO,EAAyB;QAlBzD;;WAEG;QACM,4CAAoC;QAE7C;;WAEG;QACM,0CAAyB;QAWhC,IAAI,CAAC,IAAI,GAAG,oBAAY,CAAC;QACzB,uBAAA,IAAI,6BAAc,SAAS,MAAA,CAAC;QAC5B,uBAAA,IAAI,2BAAY,OAAO,IAAI,IAAI,+CAAsB,EAAE,MAAA,CAAC;QAExD,uDAAuD;QACvD,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,CAAC,IAAI,CACV,GAAG,oBAAY,0DAA0D;gBACvE,0EAA0E,CAC7E,CAAC;QACJ,CAAC;QAED,6BAA6B;QAC7B,uBAAA,IAAI,iCAAW,CAAC,4BAA4B,CAC1C,IAAI,EACJ,yBAAyB,CAC1B,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,KAAK,CAAC,OAAO,CAAC,SAAiB,EAAE,GAAW,EAAE,KAAW;QACvD,2DAA2D;QAC3D,MAAM,uBAAA,IAAI,+BAAS,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;QAEnD,0DAA0D;QAC1D,+CAA+C;QAC/C,wBAAwB;QACxB,uBAAA,IAAI,iCAAW,CAAC,OAAO,CACrB,GAAG,oBAAY,YAAY,SAAS,EAAW,EAC/C,GAAG,EACH,KAAK,CACN,CAAC;IACJ,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,CAAC,SAAiB,EAAE,GAAW;QAC1C,iDAAiD;QACjD,OAAO,MAAM,uBAAA,IAAI,+BAAS,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IACrD,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,UAAU,CAAC,SAAiB,EAAE,GAAW;QAC7C,iFAAiF;QACjF,MAAM,uBAAA,IAAI,+BAAS,CAAC,UAAU,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IACjD,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,UAAU,CAAC,SAAiB;QAChC,OAAO,MAAM,uBAAA,IAAI,+BAAS,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;IACnD,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,KAAK,CAAC,SAAiB;QAC3B,MAAM,uBAAA,IAAI,+BAAS,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IACvC,CAAC;CACF;AA3HD,wCA2HC","sourcesContent":["import type { Json } from '@metamask/utils';\n\nimport { InMemoryStorageAdapter } from './InMemoryStorageAdapter';\nimport type {\n  StorageAdapter,\n  StorageServiceMessenger,\n  StorageServiceOptions,\n} from './types';\nimport { SERVICE_NAME } from './types';\n\n// === MESSENGER ===\n\nconst MESSENGER_EXPOSED_METHODS = [\n  'setItem',\n  'getItem',\n  'removeItem',\n  'getAllKeys',\n  'clear',\n] as const;\n\n/**\n * StorageService provides a platform-agnostic way for controllers to store\n * large, infrequently accessed data outside of memory/Redux state.\n *\n * **Use cases:**\n * - Snap source code (6+ MB that's rarely accessed)\n * - Token metadata caches (4+ MB of cached data)\n * - Large cached responses from APIs\n * - Any data > 100 KB that's not frequently accessed\n *\n * **Benefits:**\n * - Reduces memory usage (data stays on disk)\n * - Faster Redux persist (less data to serialize)\n * - Faster app startup (less data to parse)\n * - Lazy loading (data loaded only when needed)\n *\n * **Platform Support:**\n * - Mobile: FilesystemStorage adapter\n * - Extension: IndexedDB adapter\n * - Tests/Dev: InMemoryStorageAdapter (default)\n *\n * @example Using the service via messenger\n *\n * ```typescript\n * // In a controller\n * type AllowedActions =\n *   | StorageServiceSetItemAction\n *   | StorageServiceGetItemAction;\n *\n * class SnapController extends BaseController {\n *   async storeSnapSourceCode(snapId: string, sourceCode: string) {\n *     await this.messenger.call(\n *       'StorageService:setItem',\n *       'SnapController',\n *       `${snapId}:sourceCode`,\n *       sourceCode,\n *     );\n *   }\n *\n *   async getSnapSourceCode(snapId: string): Promise<string | null> {\n *     const result = await this.messenger.call(\n *       'StorageService:getItem',\n *       'SnapController',\n *       `${snapId}:sourceCode`,\n *     );\n *     return result as string | null; // Caller must validate/cast\n *   }\n * }\n * ```\n *\n * @example Initializing in a client\n *\n * ```typescript\n * // Mobile\n * const service = new StorageService({\n *   messenger: storageServiceMessenger,\n *   storage: filesystemStorageAdapter, // Platform-specific\n * });\n *\n * // Extension\n * const service = new StorageService({\n *   messenger: storageServiceMessenger,\n *   storage: indexedDBAdapter, // Platform-specific\n * });\n *\n * // Tests (uses in-memory by default)\n * const service = new StorageService({\n *   messenger: storageServiceMessenger,\n *   // No storage - uses InMemoryStorageAdapter\n * });\n * ```\n */\nexport class StorageService {\n  /**\n   * The name of the service.\n   */\n  readonly name: typeof SERVICE_NAME;\n\n  /**\n   * The messenger suited for this service.\n   */\n  readonly #messenger: StorageServiceMessenger;\n\n  /**\n   * The storage adapter for persisting data.\n   */\n  readonly #storage: StorageAdapter;\n\n  /**\n   * Constructs a new StorageService.\n   *\n   * @param options - The options.\n   * @param options.messenger - The messenger suited for this service.\n   * @param options.storage - Storage adapter for persisting data.\n   * If not provided, uses InMemoryStorageAdapter (data lost on restart).\n   */\n  constructor({ messenger, storage }: StorageServiceOptions) {\n    this.name = SERVICE_NAME;\n    this.#messenger = messenger;\n    this.#storage = storage ?? new InMemoryStorageAdapter();\n\n    // Warn if using in-memory storage (data won't persist)\n    if (!storage) {\n      console.warn(\n        `${SERVICE_NAME}: No storage adapter provided. Using in-memory storage. ` +\n          'Data will be lost on restart. Provide a storage adapter for persistence.',\n      );\n    }\n\n    // Register messenger actions\n    this.#messenger.registerMethodActionHandlers(\n      this,\n      MESSENGER_EXPOSED_METHODS,\n    );\n  }\n\n  /**\n   * Store large JSON data in storage.\n   *\n   * ⚠️ **Designed for large values (100KB+), not many small ones.**\n   * Each storage operation has I/O overhead. For best performance,\n   * store one large object rather than many small key-value pairs.\n   *\n   * @example Good: Store entire cache as one value\n   * ```typescript\n   * await service.setItem('TokenList', 'cache', { '0x1': [...], '0x38': [...] });\n   * ```\n   *\n   * @example Avoid: Many small values\n   * ```typescript\n   * // ❌ Don't do this - too many small writes\n   * await service.setItem('TokenList', 'cache:0x1', [...]);\n   * await service.setItem('TokenList', 'cache:0x38', [...]);\n   * ```\n   *\n   * @param namespace - Controller namespace (e.g., 'SnapController').\n   * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').\n   * @param value - JSON data to store (should be 100KB+ for optimal use).\n   */\n  async setItem(namespace: string, key: string, value: Json): Promise<void> {\n    // Adapter handles serialization and wrapping with metadata\n    await this.#storage.setItem(namespace, key, value);\n\n    // Publish event so other controllers can react to changes\n    // Event type: StorageService:itemSet:namespace\n    // Payload: [key, value]\n    this.#messenger.publish(\n      `${SERVICE_NAME}:itemSet:${namespace}` as const,\n      key,\n      value,\n    );\n  }\n\n  /**\n   * Retrieve JSON data from storage.\n   *\n   * @param namespace - Controller namespace (e.g., 'SnapController').\n   * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').\n   * @returns Parsed JSON data or null if not found.\n   */\n  async getItem(namespace: string, key: string): Promise<Json | null> {\n    // Adapter handles deserialization and unwrapping\n    return await this.#storage.getItem(namespace, key);\n  }\n\n  /**\n   * Remove data from storage.\n   *\n   * @param namespace - Controller namespace (e.g., 'SnapController').\n   * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').\n   */\n  async removeItem(namespace: string, key: string): Promise<void> {\n    // Adapter builds full storage key (e.g., mobile: 'storageService:namespace:key')\n    await this.#storage.removeItem(namespace, key);\n  }\n\n  /**\n   * Get all keys for a namespace.\n   * Delegates to storage adapter which handles filtering.\n   *\n   * @param namespace - Controller namespace (e.g., 'SnapController').\n   * @returns Array of keys (without prefix) for this namespace.\n   */\n  async getAllKeys(namespace: string): Promise<string[]> {\n    return await this.#storage.getAllKeys(namespace);\n  }\n\n  /**\n   * Clear all data for a namespace.\n   *\n   * @param namespace - Controller namespace (e.g., 'SnapController').\n   */\n  async clear(namespace: string): Promise<void> {\n    await this.#storage.clear(namespace);\n  }\n}\n"]}
+{"version":3,"file":"StorageService.cjs","sourceRoot":"","sources":["../src/StorageService.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAEA,yEAAkE;AAOlE,uCAAuC;AAEvC,oBAAoB;AAEpB,MAAM,yBAAyB,GAAG;IAChC,SAAS;IACT,SAAS;IACT,YAAY;IACZ,YAAY;IACZ,OAAO;CACC,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG;AACH,MAAa,cAAc;IAgBzB;;;;;;;OAOG;IACH,YAAY,EAAE,SAAS,EAAE,OAAO,EAAyB;QAlBzD;;WAEG;QACM,4CAAoC;QAE7C;;WAEG;QACM,0CAAyB;QAWhC,IAAI,CAAC,IAAI,GAAG,oBAAY,CAAC;QACzB,uBAAA,IAAI,6BAAc,SAAS,MAAA,CAAC;QAC5B,uBAAA,IAAI,2BAAY,OAAO,IAAI,IAAI,+CAAsB,EAAE,MAAA,CAAC;QAExD,uDAAuD;QACvD,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,CAAC,IAAI,CACV,GAAG,oBAAY,0DAA0D;gBACvE,0EAA0E,CAC7E,CAAC;QACJ,CAAC;QAED,6BAA6B;QAC7B,uBAAA,IAAI,iCAAW,CAAC,4BAA4B,CAC1C,IAAI,EACJ,yBAAyB,CAC1B,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,KAAK,CAAC,OAAO,CAAC,SAAiB,EAAE,GAAW,EAAE,KAAW;QACvD,2DAA2D;QAC3D,MAAM,uBAAA,IAAI,+BAAS,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;QAEnD,0DAA0D;QAC1D,+CAA+C;QAC/C,wBAAwB;QACxB,uBAAA,IAAI,iCAAW,CAAC,OAAO,CACrB,GAAG,oBAAY,YAAY,SAAS,EAAW,EAC/C,GAAG,EACH,KAAK,CACN,CAAC;IACJ,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,CAAC,SAAiB,EAAE,GAAW;QAC1C,iDAAiD;QACjD,OAAO,MAAM,uBAAA,IAAI,+BAAS,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IACrD,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,UAAU,CAAC,SAAiB,EAAE,GAAW;QAC7C,iFAAiF;QACjF,MAAM,uBAAA,IAAI,+BAAS,CAAC,UAAU,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IACjD,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,UAAU,CAAC,SAAiB;QAChC,OAAO,MAAM,uBAAA,IAAI,+BAAS,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;IACnD,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,KAAK,CAAC,SAAiB;QAC3B,MAAM,uBAAA,IAAI,+BAAS,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IACvC,CAAC;CACF;AA3HD,wCA2HC","sourcesContent":["import type { Json } from '@metamask/utils';\n\nimport { InMemoryStorageAdapter } from './InMemoryStorageAdapter';\nimport type {\n  StorageAdapter,\n  StorageGetResult,\n  StorageServiceMessenger,\n  StorageServiceOptions,\n} from './types';\nimport { SERVICE_NAME } from './types';\n\n// === MESSENGER ===\n\nconst MESSENGER_EXPOSED_METHODS = [\n  'setItem',\n  'getItem',\n  'removeItem',\n  'getAllKeys',\n  'clear',\n] as const;\n\n/**\n * StorageService provides a platform-agnostic way for controllers to store\n * large, infrequently accessed data outside of memory/Redux state.\n *\n * **Use cases:**\n * - Snap source code (6+ MB that's rarely accessed)\n * - Token metadata caches (4+ MB of cached data)\n * - Large cached responses from APIs\n * - Any data > 100 KB that's not frequently accessed\n *\n * **Benefits:**\n * - Reduces memory usage (data stays on disk)\n * - Faster Redux persist (less data to serialize)\n * - Faster app startup (less data to parse)\n * - Lazy loading (data loaded only when needed)\n *\n * **Platform Support:**\n * - Mobile: FilesystemStorage adapter\n * - Extension: IndexedDB adapter\n * - Tests/Dev: InMemoryStorageAdapter (default)\n *\n * @example Using the service via messenger\n *\n * ```typescript\n * // In a controller\n * type AllowedActions =\n *   | StorageServiceSetItemAction\n *   | StorageServiceGetItemAction;\n *\n * class SnapController extends BaseController {\n *   async storeSnapSourceCode(snapId: string, sourceCode: string) {\n *     await this.messenger.call(\n *       'StorageService:setItem',\n *       'SnapController',\n *       `${snapId}:sourceCode`,\n *       sourceCode,\n *     );\n *   }\n *\n *   async getSnapSourceCode(snapId: string): Promise<string | undefined> {\n *     const { result, error } = await this.messenger.call(\n *       'StorageService:getItem',\n *       'SnapController',\n *       `${snapId}:sourceCode`,\n *     );\n *     if (error) {\n *       throw error; // Handle error\n *     }\n *     return result as string | undefined; // undefined if not found\n *   }\n * }\n * ```\n *\n * @example Initializing in a client\n *\n * ```typescript\n * // Mobile\n * const service = new StorageService({\n *   messenger: storageServiceMessenger,\n *   storage: filesystemStorageAdapter, // Platform-specific\n * });\n *\n * // Extension\n * const service = new StorageService({\n *   messenger: storageServiceMessenger,\n *   storage: indexedDBAdapter, // Platform-specific\n * });\n *\n * // Tests (uses in-memory by default)\n * const service = new StorageService({\n *   messenger: storageServiceMessenger,\n *   // No storage - uses InMemoryStorageAdapter\n * });\n * ```\n */\nexport class StorageService {\n  /**\n   * The name of the service.\n   */\n  readonly name: typeof SERVICE_NAME;\n\n  /**\n   * The messenger suited for this service.\n   */\n  readonly #messenger: StorageServiceMessenger;\n\n  /**\n   * The storage adapter for persisting data.\n   */\n  readonly #storage: StorageAdapter;\n\n  /**\n   * Constructs a new StorageService.\n   *\n   * @param options - The options.\n   * @param options.messenger - The messenger suited for this service.\n   * @param options.storage - Storage adapter for persisting data.\n   * If not provided, uses InMemoryStorageAdapter (data lost on restart).\n   */\n  constructor({ messenger, storage }: StorageServiceOptions) {\n    this.name = SERVICE_NAME;\n    this.#messenger = messenger;\n    this.#storage = storage ?? new InMemoryStorageAdapter();\n\n    // Warn if using in-memory storage (data won't persist)\n    if (!storage) {\n      console.warn(\n        `${SERVICE_NAME}: No storage adapter provided. Using in-memory storage. ` +\n          'Data will be lost on restart. Provide a storage adapter for persistence.',\n      );\n    }\n\n    // Register messenger actions\n    this.#messenger.registerMethodActionHandlers(\n      this,\n      MESSENGER_EXPOSED_METHODS,\n    );\n  }\n\n  /**\n   * Store large JSON data in storage.\n   *\n   * ⚠️ **Designed for large values (100KB+), not many small ones.**\n   * Each storage operation has I/O overhead. For best performance,\n   * store one large object rather than many small key-value pairs.\n   *\n   * @example Good: Store entire cache as one value\n   * ```typescript\n   * await service.setItem('TokenList', 'cache', { '0x1': [...], '0x38': [...] });\n   * ```\n   *\n   * @example Avoid: Many small values\n   * ```typescript\n   * // ❌ Don't do this - too many small writes\n   * await service.setItem('TokenList', 'cache:0x1', [...]);\n   * await service.setItem('TokenList', 'cache:0x38', [...]);\n   * ```\n   *\n   * @param namespace - Controller namespace (e.g., 'SnapController').\n   * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').\n   * @param value - JSON data to store (should be 100KB+ for optimal use).\n   */\n  async setItem(namespace: string, key: string, value: Json): Promise<void> {\n    // Adapter handles serialization and wrapping with metadata\n    await this.#storage.setItem(namespace, key, value);\n\n    // Publish event so other controllers can react to changes\n    // Event type: StorageService:itemSet:namespace\n    // Payload: [key, value]\n    this.#messenger.publish(\n      `${SERVICE_NAME}:itemSet:${namespace}` as const,\n      key,\n      value,\n    );\n  }\n\n  /**\n   * Retrieve JSON data from storage.\n   *\n   * @param namespace - Controller namespace (e.g., 'SnapController').\n   * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').\n   * @returns StorageGetResult: { result } if found, {} if not found, { error } on failure.\n   */\n  async getItem(namespace: string, key: string): Promise<StorageGetResult> {\n    // Adapter handles deserialization and unwrapping\n    return await this.#storage.getItem(namespace, key);\n  }\n\n  /**\n   * Remove data from storage.\n   *\n   * @param namespace - Controller namespace (e.g., 'SnapController').\n   * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').\n   */\n  async removeItem(namespace: string, key: string): Promise<void> {\n    // Adapter builds full storage key (e.g., mobile: 'storageService:namespace:key')\n    await this.#storage.removeItem(namespace, key);\n  }\n\n  /**\n   * Get all keys for a namespace.\n   * Delegates to storage adapter which handles filtering.\n   *\n   * @param namespace - Controller namespace (e.g., 'SnapController').\n   * @returns Array of keys (without prefix) for this namespace.\n   */\n  async getAllKeys(namespace: string): Promise<string[]> {\n    return await this.#storage.getAllKeys(namespace);\n  }\n\n  /**\n   * Clear all data for a namespace.\n   *\n   * @param namespace - Controller namespace (e.g., 'SnapController').\n   */\n  async clear(namespace: string): Promise<void> {\n    await this.#storage.clear(namespace);\n  }\n}\n"]}

package/dist/StorageService.d.cts

@@ -1,5 +1,5 @@
 import type { Json } from "@metamask/utils";
-import type { StorageServiceOptions } from "./types.cjs";
+import type { StorageGetResult, StorageServiceOptions } from "./types.cjs";
 import { SERVICE_NAME } from "./types.cjs";
 /**
  * StorageService provides a platform-agnostic way for controllers to store
@@ -40,13 +40,16 @@ import { SERVICE_NAME } from "./types.cjs";
  *     );
  *   }
  *
- *   async getSnapSourceCode(snapId: string): Promise<string | null> {
- *     const result = await this.messenger.call(
+ *   async getSnapSourceCode(snapId: string): Promise<string | undefined> {
+ *     const { result, error } = await this.messenger.call(
  *       'StorageService:getItem',
  *       'SnapController',
  *       `${snapId}:sourceCode`,
  *     );
- *     return result as string | null; // Caller must validate/cast
+ *     if (error) {
+ *       throw error; // Handle error
+ *     }
+ *     return result as string | undefined; // undefined if not found
  *   }
  * }
  * ```
@@ -117,9 +120,9 @@ export declare class StorageService {
      *
      * @param namespace - Controller namespace (e.g., 'SnapController').
      * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').
-     * @returns Parsed JSON data or null if not found.
+     * @returns StorageGetResult: { result } if found, {} if not found, { error } on failure.
      */
-    getItem(namespace: string, key: string): Promise<Json | null>;
+    getItem(namespace: string, key: string): Promise<StorageGetResult>;
     /**
      * Remove data from storage.
      *

package/dist/StorageService.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"StorageService.d.cts","sourceRoot":"","sources":["../src/StorageService.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,wBAAwB;AAG5C,OAAO,KAAK,EAGV,qBAAqB,EACtB,oBAAgB;AACjB,OAAO,EAAE,YAAY,EAAE,oBAAgB;AAYvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AACH,qBAAa,cAAc;;IACzB;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,OAAO,YAAY,CAAC;IAYnC;;;;;;;OAOG;gBACS,EAAE,SAAS,EAAE,OAAO,EAAE,EAAE,qBAAqB;IAoBzD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAczE;;;;;;OAMG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;IAKnE;;;;;OAKG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK/D;;;;;;OAMG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAItD;;;;OAIG;IACG,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAG9C"}
+{"version":3,"file":"StorageService.d.cts","sourceRoot":"","sources":["../src/StorageService.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,wBAAwB;AAG5C,OAAO,KAAK,EAEV,gBAAgB,EAEhB,qBAAqB,EACtB,oBAAgB;AACjB,OAAO,EAAE,YAAY,EAAE,oBAAgB;AAYvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG;AACH,qBAAa,cAAc;;IACzB;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,OAAO,YAAY,CAAC;IAYnC;;;;;;;OAOG;gBACS,EAAE,SAAS,EAAE,OAAO,EAAE,EAAE,qBAAqB;IAoBzD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAczE;;;;;;OAMG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAKxE;;;;;OAKG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK/D;;;;;;OAMG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAItD;;;;OAIG;IACG,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAG9C"}

package/dist/StorageService.d.mts

@@ -1,5 +1,5 @@
 import type { Json } from "@metamask/utils";
-import type { StorageServiceOptions } from "./types.mjs";
+import type { StorageGetResult, StorageServiceOptions } from "./types.mjs";
 import { SERVICE_NAME } from "./types.mjs";
 /**
  * StorageService provides a platform-agnostic way for controllers to store
@@ -40,13 +40,16 @@ import { SERVICE_NAME } from "./types.mjs";
  *     );
  *   }
  *
- *   async getSnapSourceCode(snapId: string): Promise<string | null> {
- *     const result = await this.messenger.call(
+ *   async getSnapSourceCode(snapId: string): Promise<string | undefined> {
+ *     const { result, error } = await this.messenger.call(
  *       'StorageService:getItem',
  *       'SnapController',
  *       `${snapId}:sourceCode`,
  *     );
- *     return result as string | null; // Caller must validate/cast
+ *     if (error) {
+ *       throw error; // Handle error
+ *     }
+ *     return result as string | undefined; // undefined if not found
  *   }
  * }
  * ```
@@ -117,9 +120,9 @@ export declare class StorageService {
      *
      * @param namespace - Controller namespace (e.g., 'SnapController').
      * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').
-     * @returns Parsed JSON data or null if not found.
+     * @returns StorageGetResult: { result } if found, {} if not found, { error } on failure.
      */
-    getItem(namespace: string, key: string): Promise<Json | null>;
+    getItem(namespace: string, key: string): Promise<StorageGetResult>;
     /**
      * Remove data from storage.
      *

package/dist/StorageService.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"StorageService.d.mts","sourceRoot":"","sources":["../src/StorageService.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,wBAAwB;AAG5C,OAAO,KAAK,EAGV,qBAAqB,EACtB,oBAAgB;AACjB,OAAO,EAAE,YAAY,EAAE,oBAAgB;AAYvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AACH,qBAAa,cAAc;;IACzB;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,OAAO,YAAY,CAAC;IAYnC;;;;;;;OAOG;gBACS,EAAE,SAAS,EAAE,OAAO,EAAE,EAAE,qBAAqB;IAoBzD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAczE;;;;;;OAMG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;IAKnE;;;;;OAKG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK/D;;;;;;OAMG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAItD;;;;OAIG;IACG,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAG9C"}
+{"version":3,"file":"StorageService.d.mts","sourceRoot":"","sources":["../src/StorageService.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,wBAAwB;AAG5C,OAAO,KAAK,EAEV,gBAAgB,EAEhB,qBAAqB,EACtB,oBAAgB;AACjB,OAAO,EAAE,YAAY,EAAE,oBAAgB;AAYvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG;AACH,qBAAa,cAAc;;IACzB;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,OAAO,YAAY,CAAC;IAYnC;;;;;;;OAOG;gBACS,EAAE,SAAS,EAAE,OAAO,EAAE,EAAE,qBAAqB;IAoBzD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAczE;;;;;;OAMG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAKxE;;;;;OAKG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK/D;;;;;;OAMG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAItD;;;;OAIG;IACG,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAG9C"}

package/dist/StorageService.mjs

@@ -59,13 +59,16 @@ const MESSENGER_EXPOSED_METHODS = [
  *     );
  *   }
  *
- *   async getSnapSourceCode(snapId: string): Promise<string | null> {
- *     const result = await this.messenger.call(
+ *   async getSnapSourceCode(snapId: string): Promise<string | undefined> {
+ *     const { result, error } = await this.messenger.call(
  *       'StorageService:getItem',
  *       'SnapController',
  *       `${snapId}:sourceCode`,
  *     );
- *     return result as string | null; // Caller must validate/cast
+ *     if (error) {
+ *       throw error; // Handle error
+ *     }
+ *     return result as string | undefined; // undefined if not found
  *   }
  * }
  * ```
@@ -157,7 +160,7 @@ export class StorageService {
      *
      * @param namespace - Controller namespace (e.g., 'SnapController').
      * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').
-     * @returns Parsed JSON data or null if not found.
+     * @returns StorageGetResult: { result } if found, {} if not found, { error } on failure.
      */
     async getItem(namespace, key) {
         // Adapter handles deserialization and unwrapping

package/dist/StorageService.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"StorageService.mjs","sourceRoot":"","sources":["../src/StorageService.ts"],"names":[],"mappings":";;;;;;;;;;;;AAEA,OAAO,EAAE,sBAAsB,EAAE,qCAAiC;AAMlE,OAAO,EAAE,YAAY,EAAE,oBAAgB;AAEvC,oBAAoB;AAEpB,MAAM,yBAAyB,GAAG;IAChC,SAAS;IACT,SAAS;IACT,YAAY;IACZ,YAAY;IACZ,OAAO;CACC,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AACH,MAAM,OAAO,cAAc;IAgBzB;;;;;;;OAOG;IACH,YAAY,EAAE,SAAS,EAAE,OAAO,EAAyB;QAlBzD;;WAEG;QACM,4CAAoC;QAE7C;;WAEG;QACM,0CAAyB;QAWhC,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;QACzB,uBAAA,IAAI,6BAAc,SAAS,MAAA,CAAC;QAC5B,uBAAA,IAAI,2BAAY,OAAO,IAAI,IAAI,sBAAsB,EAAE,MAAA,CAAC;QAExD,uDAAuD;QACvD,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,CAAC,IAAI,CACV,GAAG,YAAY,0DAA0D;gBACvE,0EAA0E,CAC7E,CAAC;QACJ,CAAC;QAED,6BAA6B;QAC7B,uBAAA,IAAI,iCAAW,CAAC,4BAA4B,CAC1C,IAAI,EACJ,yBAAyB,CAC1B,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,KAAK,CAAC,OAAO,CAAC,SAAiB,EAAE,GAAW,EAAE,KAAW;QACvD,2DAA2D;QAC3D,MAAM,uBAAA,IAAI,+BAAS,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;QAEnD,0DAA0D;QAC1D,+CAA+C;QAC/C,wBAAwB;QACxB,uBAAA,IAAI,iCAAW,CAAC,OAAO,CACrB,GAAG,YAAY,YAAY,SAAS,EAAW,EAC/C,GAAG,EACH,KAAK,CACN,CAAC;IACJ,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,CAAC,SAAiB,EAAE,GAAW;QAC1C,iDAAiD;QACjD,OAAO,MAAM,uBAAA,IAAI,+BAAS,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IACrD,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,UAAU,CAAC,SAAiB,EAAE,GAAW;QAC7C,iFAAiF;QACjF,MAAM,uBAAA,IAAI,+BAAS,CAAC,UAAU,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IACjD,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,UAAU,CAAC,SAAiB;QAChC,OAAO,MAAM,uBAAA,IAAI,+BAAS,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;IACnD,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,KAAK,CAAC,SAAiB;QAC3B,MAAM,uBAAA,IAAI,+BAAS,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IACvC,CAAC;CACF","sourcesContent":["import type { Json } from '@metamask/utils';\n\nimport { InMemoryStorageAdapter } from './InMemoryStorageAdapter';\nimport type {\n  StorageAdapter,\n  StorageServiceMessenger,\n  StorageServiceOptions,\n} from './types';\nimport { SERVICE_NAME } from './types';\n\n// === MESSENGER ===\n\nconst MESSENGER_EXPOSED_METHODS = [\n  'setItem',\n  'getItem',\n  'removeItem',\n  'getAllKeys',\n  'clear',\n] as const;\n\n/**\n * StorageService provides a platform-agnostic way for controllers to store\n * large, infrequently accessed data outside of memory/Redux state.\n *\n * **Use cases:**\n * - Snap source code (6+ MB that's rarely accessed)\n * - Token metadata caches (4+ MB of cached data)\n * - Large cached responses from APIs\n * - Any data > 100 KB that's not frequently accessed\n *\n * **Benefits:**\n * - Reduces memory usage (data stays on disk)\n * - Faster Redux persist (less data to serialize)\n * - Faster app startup (less data to parse)\n * - Lazy loading (data loaded only when needed)\n *\n * **Platform Support:**\n * - Mobile: FilesystemStorage adapter\n * - Extension: IndexedDB adapter\n * - Tests/Dev: InMemoryStorageAdapter (default)\n *\n * @example Using the service via messenger\n *\n * ```typescript\n * // In a controller\n * type AllowedActions =\n *   | StorageServiceSetItemAction\n *   | StorageServiceGetItemAction;\n *\n * class SnapController extends BaseController {\n *   async storeSnapSourceCode(snapId: string, sourceCode: string) {\n *     await this.messenger.call(\n *       'StorageService:setItem',\n *       'SnapController',\n *       `${snapId}:sourceCode`,\n *       sourceCode,\n *     );\n *   }\n *\n *   async getSnapSourceCode(snapId: string): Promise<string | null> {\n *     const result = await this.messenger.call(\n *       'StorageService:getItem',\n *       'SnapController',\n *       `${snapId}:sourceCode`,\n *     );\n *     return result as string | null; // Caller must validate/cast\n *   }\n * }\n * ```\n *\n * @example Initializing in a client\n *\n * ```typescript\n * // Mobile\n * const service = new StorageService({\n *   messenger: storageServiceMessenger,\n *   storage: filesystemStorageAdapter, // Platform-specific\n * });\n *\n * // Extension\n * const service = new StorageService({\n *   messenger: storageServiceMessenger,\n *   storage: indexedDBAdapter, // Platform-specific\n * });\n *\n * // Tests (uses in-memory by default)\n * const service = new StorageService({\n *   messenger: storageServiceMessenger,\n *   // No storage - uses InMemoryStorageAdapter\n * });\n * ```\n */\nexport class StorageService {\n  /**\n   * The name of the service.\n   */\n  readonly name: typeof SERVICE_NAME;\n\n  /**\n   * The messenger suited for this service.\n   */\n  readonly #messenger: StorageServiceMessenger;\n\n  /**\n   * The storage adapter for persisting data.\n   */\n  readonly #storage: StorageAdapter;\n\n  /**\n   * Constructs a new StorageService.\n   *\n   * @param options - The options.\n   * @param options.messenger - The messenger suited for this service.\n   * @param options.storage - Storage adapter for persisting data.\n   * If not provided, uses InMemoryStorageAdapter (data lost on restart).\n   */\n  constructor({ messenger, storage }: StorageServiceOptions) {\n    this.name = SERVICE_NAME;\n    this.#messenger = messenger;\n    this.#storage = storage ?? new InMemoryStorageAdapter();\n\n    // Warn if using in-memory storage (data won't persist)\n    if (!storage) {\n      console.warn(\n        `${SERVICE_NAME}: No storage adapter provided. Using in-memory storage. ` +\n          'Data will be lost on restart. Provide a storage adapter for persistence.',\n      );\n    }\n\n    // Register messenger actions\n    this.#messenger.registerMethodActionHandlers(\n      this,\n      MESSENGER_EXPOSED_METHODS,\n    );\n  }\n\n  /**\n   * Store large JSON data in storage.\n   *\n   * ⚠️ **Designed for large values (100KB+), not many small ones.**\n   * Each storage operation has I/O overhead. For best performance,\n   * store one large object rather than many small key-value pairs.\n   *\n   * @example Good: Store entire cache as one value\n   * ```typescript\n   * await service.setItem('TokenList', 'cache', { '0x1': [...], '0x38': [...] });\n   * ```\n   *\n   * @example Avoid: Many small values\n   * ```typescript\n   * // ❌ Don't do this - too many small writes\n   * await service.setItem('TokenList', 'cache:0x1', [...]);\n   * await service.setItem('TokenList', 'cache:0x38', [...]);\n   * ```\n   *\n   * @param namespace - Controller namespace (e.g., 'SnapController').\n   * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').\n   * @param value - JSON data to store (should be 100KB+ for optimal use).\n   */\n  async setItem(namespace: string, key: string, value: Json): Promise<void> {\n    // Adapter handles serialization and wrapping with metadata\n    await this.#storage.setItem(namespace, key, value);\n\n    // Publish event so other controllers can react to changes\n    // Event type: StorageService:itemSet:namespace\n    // Payload: [key, value]\n    this.#messenger.publish(\n      `${SERVICE_NAME}:itemSet:${namespace}` as const,\n      key,\n      value,\n    );\n  }\n\n  /**\n   * Retrieve JSON data from storage.\n   *\n   * @param namespace - Controller namespace (e.g., 'SnapController').\n   * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').\n   * @returns Parsed JSON data or null if not found.\n   */\n  async getItem(namespace: string, key: string): Promise<Json | null> {\n    // Adapter handles deserialization and unwrapping\n    return await this.#storage.getItem(namespace, key);\n  }\n\n  /**\n   * Remove data from storage.\n   *\n   * @param namespace - Controller namespace (e.g., 'SnapController').\n   * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').\n   */\n  async removeItem(namespace: string, key: string): Promise<void> {\n    // Adapter builds full storage key (e.g., mobile: 'storageService:namespace:key')\n    await this.#storage.removeItem(namespace, key);\n  }\n\n  /**\n   * Get all keys for a namespace.\n   * Delegates to storage adapter which handles filtering.\n   *\n   * @param namespace - Controller namespace (e.g., 'SnapController').\n   * @returns Array of keys (without prefix) for this namespace.\n   */\n  async getAllKeys(namespace: string): Promise<string[]> {\n    return await this.#storage.getAllKeys(namespace);\n  }\n\n  /**\n   * Clear all data for a namespace.\n   *\n   * @param namespace - Controller namespace (e.g., 'SnapController').\n   */\n  async clear(namespace: string): Promise<void> {\n    await this.#storage.clear(namespace);\n  }\n}\n"]}
+{"version":3,"file":"StorageService.mjs","sourceRoot":"","sources":["../src/StorageService.ts"],"names":[],"mappings":";;;;;;;;;;;;AAEA,OAAO,EAAE,sBAAsB,EAAE,qCAAiC;AAOlE,OAAO,EAAE,YAAY,EAAE,oBAAgB;AAEvC,oBAAoB;AAEpB,MAAM,yBAAyB,GAAG;IAChC,SAAS;IACT,SAAS;IACT,YAAY;IACZ,YAAY;IACZ,OAAO;CACC,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG;AACH,MAAM,OAAO,cAAc;IAgBzB;;;;;;;OAOG;IACH,YAAY,EAAE,SAAS,EAAE,OAAO,EAAyB;QAlBzD;;WAEG;QACM,4CAAoC;QAE7C;;WAEG;QACM,0CAAyB;QAWhC,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;QACzB,uBAAA,IAAI,6BAAc,SAAS,MAAA,CAAC;QAC5B,uBAAA,IAAI,2BAAY,OAAO,IAAI,IAAI,sBAAsB,EAAE,MAAA,CAAC;QAExD,uDAAuD;QACvD,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,CAAC,IAAI,CACV,GAAG,YAAY,0DAA0D;gBACvE,0EAA0E,CAC7E,CAAC;QACJ,CAAC;QAED,6BAA6B;QAC7B,uBAAA,IAAI,iCAAW,CAAC,4BAA4B,CAC1C,IAAI,EACJ,yBAAyB,CAC1B,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,KAAK,CAAC,OAAO,CAAC,SAAiB,EAAE,GAAW,EAAE,KAAW;QACvD,2DAA2D;QAC3D,MAAM,uBAAA,IAAI,+BAAS,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;QAEnD,0DAA0D;QAC1D,+CAA+C;QAC/C,wBAAwB;QACxB,uBAAA,IAAI,iCAAW,CAAC,OAAO,CACrB,GAAG,YAAY,YAAY,SAAS,EAAW,EAC/C,GAAG,EACH,KAAK,CACN,CAAC;IACJ,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,CAAC,SAAiB,EAAE,GAAW;QAC1C,iDAAiD;QACjD,OAAO,MAAM,uBAAA,IAAI,+BAAS,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IACrD,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,UAAU,CAAC,SAAiB,EAAE,GAAW;QAC7C,iFAAiF;QACjF,MAAM,uBAAA,IAAI,+BAAS,CAAC,UAAU,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IACjD,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,UAAU,CAAC,SAAiB;QAChC,OAAO,MAAM,uBAAA,IAAI,+BAAS,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;IACnD,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,KAAK,CAAC,SAAiB;QAC3B,MAAM,uBAAA,IAAI,+BAAS,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IACvC,CAAC;CACF","sourcesContent":["import type { Json } from '@metamask/utils';\n\nimport { InMemoryStorageAdapter } from './InMemoryStorageAdapter';\nimport type {\n  StorageAdapter,\n  StorageGetResult,\n  StorageServiceMessenger,\n  StorageServiceOptions,\n} from './types';\nimport { SERVICE_NAME } from './types';\n\n// === MESSENGER ===\n\nconst MESSENGER_EXPOSED_METHODS = [\n  'setItem',\n  'getItem',\n  'removeItem',\n  'getAllKeys',\n  'clear',\n] as const;\n\n/**\n * StorageService provides a platform-agnostic way for controllers to store\n * large, infrequently accessed data outside of memory/Redux state.\n *\n * **Use cases:**\n * - Snap source code (6+ MB that's rarely accessed)\n * - Token metadata caches (4+ MB of cached data)\n * - Large cached responses from APIs\n * - Any data > 100 KB that's not frequently accessed\n *\n * **Benefits:**\n * - Reduces memory usage (data stays on disk)\n * - Faster Redux persist (less data to serialize)\n * - Faster app startup (less data to parse)\n * - Lazy loading (data loaded only when needed)\n *\n * **Platform Support:**\n * - Mobile: FilesystemStorage adapter\n * - Extension: IndexedDB adapter\n * - Tests/Dev: InMemoryStorageAdapter (default)\n *\n * @example Using the service via messenger\n *\n * ```typescript\n * // In a controller\n * type AllowedActions =\n *   | StorageServiceSetItemAction\n *   | StorageServiceGetItemAction;\n *\n * class SnapController extends BaseController {\n *   async storeSnapSourceCode(snapId: string, sourceCode: string) {\n *     await this.messenger.call(\n *       'StorageService:setItem',\n *       'SnapController',\n *       `${snapId}:sourceCode`,\n *       sourceCode,\n *     );\n *   }\n *\n *   async getSnapSourceCode(snapId: string): Promise<string | undefined> {\n *     const { result, error } = await this.messenger.call(\n *       'StorageService:getItem',\n *       'SnapController',\n *       `${snapId}:sourceCode`,\n *     );\n *     if (error) {\n *       throw error; // Handle error\n *     }\n *     return result as string | undefined; // undefined if not found\n *   }\n * }\n * ```\n *\n * @example Initializing in a client\n *\n * ```typescript\n * // Mobile\n * const service = new StorageService({\n *   messenger: storageServiceMessenger,\n *   storage: filesystemStorageAdapter, // Platform-specific\n * });\n *\n * // Extension\n * const service = new StorageService({\n *   messenger: storageServiceMessenger,\n *   storage: indexedDBAdapter, // Platform-specific\n * });\n *\n * // Tests (uses in-memory by default)\n * const service = new StorageService({\n *   messenger: storageServiceMessenger,\n *   // No storage - uses InMemoryStorageAdapter\n * });\n * ```\n */\nexport class StorageService {\n  /**\n   * The name of the service.\n   */\n  readonly name: typeof SERVICE_NAME;\n\n  /**\n   * The messenger suited for this service.\n   */\n  readonly #messenger: StorageServiceMessenger;\n\n  /**\n   * The storage adapter for persisting data.\n   */\n  readonly #storage: StorageAdapter;\n\n  /**\n   * Constructs a new StorageService.\n   *\n   * @param options - The options.\n   * @param options.messenger - The messenger suited for this service.\n   * @param options.storage - Storage adapter for persisting data.\n   * If not provided, uses InMemoryStorageAdapter (data lost on restart).\n   */\n  constructor({ messenger, storage }: StorageServiceOptions) {\n    this.name = SERVICE_NAME;\n    this.#messenger = messenger;\n    this.#storage = storage ?? new InMemoryStorageAdapter();\n\n    // Warn if using in-memory storage (data won't persist)\n    if (!storage) {\n      console.warn(\n        `${SERVICE_NAME}: No storage adapter provided. Using in-memory storage. ` +\n          'Data will be lost on restart. Provide a storage adapter for persistence.',\n      );\n    }\n\n    // Register messenger actions\n    this.#messenger.registerMethodActionHandlers(\n      this,\n      MESSENGER_EXPOSED_METHODS,\n    );\n  }\n\n  /**\n   * Store large JSON data in storage.\n   *\n   * ⚠️ **Designed for large values (100KB+), not many small ones.**\n   * Each storage operation has I/O overhead. For best performance,\n   * store one large object rather than many small key-value pairs.\n   *\n   * @example Good: Store entire cache as one value\n   * ```typescript\n   * await service.setItem('TokenList', 'cache', { '0x1': [...], '0x38': [...] });\n   * ```\n   *\n   * @example Avoid: Many small values\n   * ```typescript\n   * // ❌ Don't do this - too many small writes\n   * await service.setItem('TokenList', 'cache:0x1', [...]);\n   * await service.setItem('TokenList', 'cache:0x38', [...]);\n   * ```\n   *\n   * @param namespace - Controller namespace (e.g., 'SnapController').\n   * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').\n   * @param value - JSON data to store (should be 100KB+ for optimal use).\n   */\n  async setItem(namespace: string, key: string, value: Json): Promise<void> {\n    // Adapter handles serialization and wrapping with metadata\n    await this.#storage.setItem(namespace, key, value);\n\n    // Publish event so other controllers can react to changes\n    // Event type: StorageService:itemSet:namespace\n    // Payload: [key, value]\n    this.#messenger.publish(\n      `${SERVICE_NAME}:itemSet:${namespace}` as const,\n      key,\n      value,\n    );\n  }\n\n  /**\n   * Retrieve JSON data from storage.\n   *\n   * @param namespace - Controller namespace (e.g., 'SnapController').\n   * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').\n   * @returns StorageGetResult: { result } if found, {} if not found, { error } on failure.\n   */\n  async getItem(namespace: string, key: string): Promise<StorageGetResult> {\n    // Adapter handles deserialization and unwrapping\n    return await this.#storage.getItem(namespace, key);\n  }\n\n  /**\n   * Remove data from storage.\n   *\n   * @param namespace - Controller namespace (e.g., 'SnapController').\n   * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').\n   */\n  async removeItem(namespace: string, key: string): Promise<void> {\n    // Adapter builds full storage key (e.g., mobile: 'storageService:namespace:key')\n    await this.#storage.removeItem(namespace, key);\n  }\n\n  /**\n   * Get all keys for a namespace.\n   * Delegates to storage adapter which handles filtering.\n   *\n   * @param namespace - Controller namespace (e.g., 'SnapController').\n   * @returns Array of keys (without prefix) for this namespace.\n   */\n  async getAllKeys(namespace: string): Promise<string[]> {\n    return await this.#storage.getAllKeys(namespace);\n  }\n\n  /**\n   * Clear all data for a namespace.\n   *\n   * @param namespace - Controller namespace (e.g., 'SnapController').\n   */\n  async clear(namespace: string): Promise<void> {\n    await this.#storage.clear(namespace);\n  }\n}\n"]}

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,uBAAuB;AACvB,uDAAkD;AAAzC,gHAAA,cAAc,OAAA;AAEvB,kBAAkB;AAClB,uEAAkE;AAAzD,gIAAA,sBAAsB,OAAA;AAqB/B,uDAAuD;AACvD,qCAA2D;AAAlD,qGAAA,YAAY,OAAA;AAAE,2GAAA,kBAAkB,OAAA","sourcesContent":["// Export service class\nexport { StorageService } from './StorageService';\n\n// Export adapters\nexport { InMemoryStorageAdapter } from './InMemoryStorageAdapter';\n\n// Export types from types.ts\nexport type {\n  StorageAdapter,\n  StorageServiceOptions,\n  StorageServiceActions,\n  StorageServiceEvents,\n  StorageServiceMessenger,\n  StorageServiceItemSetEvent,\n} from './types';\n\n// Export individual action types from generated file\nexport type {\n  StorageServiceSetItemAction,\n  StorageServiceGetItemAction,\n  StorageServiceRemoveItemAction,\n  StorageServiceGetAllKeysAction,\n  StorageServiceClearAction,\n} from './StorageService-method-action-types';\n\n// Export service name and storage key prefix constants\nexport { SERVICE_NAME, STORAGE_KEY_PREFIX } from './types';\n"]}
+{"version":3,"file":"index.cjs","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,uBAAuB;AACvB,uDAAkD;AAAzC,gHAAA,cAAc,OAAA;AAEvB,kBAAkB;AAClB,uEAAkE;AAAzD,gIAAA,sBAAsB,OAAA;AAsB/B,uDAAuD;AACvD,qCAA2D;AAAlD,qGAAA,YAAY,OAAA;AAAE,2GAAA,kBAAkB,OAAA","sourcesContent":["// Export service class\nexport { StorageService } from './StorageService';\n\n// Export adapters\nexport { InMemoryStorageAdapter } from './InMemoryStorageAdapter';\n\n// Export types from types.ts\nexport type {\n  StorageAdapter,\n  StorageGetResult,\n  StorageServiceOptions,\n  StorageServiceActions,\n  StorageServiceEvents,\n  StorageServiceMessenger,\n  StorageServiceItemSetEvent,\n} from './types';\n\n// Export individual action types from generated file\nexport type {\n  StorageServiceSetItemAction,\n  StorageServiceGetItemAction,\n  StorageServiceRemoveItemAction,\n  StorageServiceGetAllKeysAction,\n  StorageServiceClearAction,\n} from './StorageService-method-action-types';\n\n// Export service name and storage key prefix constants\nexport { SERVICE_NAME, STORAGE_KEY_PREFIX } from './types';\n"]}

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 export { StorageService } from "./StorageService.cjs";
 export { InMemoryStorageAdapter } from "./InMemoryStorageAdapter.cjs";
-export type { StorageAdapter, StorageServiceOptions, StorageServiceActions, StorageServiceEvents, StorageServiceMessenger, StorageServiceItemSetEvent, } from "./types.cjs";
+export type { StorageAdapter, StorageGetResult, StorageServiceOptions, StorageServiceActions, StorageServiceEvents, StorageServiceMessenger, StorageServiceItemSetEvent, } from "./types.cjs";
 export type { StorageServiceSetItemAction, StorageServiceGetItemAction, StorageServiceRemoveItemAction, StorageServiceGetAllKeysAction, StorageServiceClearAction, } from "./StorageService-method-action-types.cjs";
 export { SERVICE_NAME, STORAGE_KEY_PREFIX } from "./types.cjs";
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,6BAAyB;AAGlD,OAAO,EAAE,sBAAsB,EAAE,qCAAiC;AAGlE,YAAY,EACV,cAAc,EACd,qBAAqB,EACrB,qBAAqB,EACrB,oBAAoB,EACpB,uBAAuB,EACvB,0BAA0B,GAC3B,oBAAgB;AAGjB,YAAY,EACV,2BAA2B,EAC3B,2BAA2B,EAC3B,8BAA8B,EAC9B,8BAA8B,EAC9B,yBAAyB,GAC1B,iDAA6C;AAG9C,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,oBAAgB"}
+{"version":3,"file":"index.d.cts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,6BAAyB;AAGlD,OAAO,EAAE,sBAAsB,EAAE,qCAAiC;AAGlE,YAAY,EACV,cAAc,EACd,gBAAgB,EAChB,qBAAqB,EACrB,qBAAqB,EACrB,oBAAoB,EACpB,uBAAuB,EACvB,0BAA0B,GAC3B,oBAAgB;AAGjB,YAAY,EACV,2BAA2B,EAC3B,2BAA2B,EAC3B,8BAA8B,EAC9B,8BAA8B,EAC9B,yBAAyB,GAC1B,iDAA6C;AAG9C,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,oBAAgB"}

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 export { StorageService } from "./StorageService.mjs";
 export { InMemoryStorageAdapter } from "./InMemoryStorageAdapter.mjs";
-export type { StorageAdapter, StorageServiceOptions, StorageServiceActions, StorageServiceEvents, StorageServiceMessenger, StorageServiceItemSetEvent, } from "./types.mjs";
+export type { StorageAdapter, StorageGetResult, StorageServiceOptions, StorageServiceActions, StorageServiceEvents, StorageServiceMessenger, StorageServiceItemSetEvent, } from "./types.mjs";
 export type { StorageServiceSetItemAction, StorageServiceGetItemAction, StorageServiceRemoveItemAction, StorageServiceGetAllKeysAction, StorageServiceClearAction, } from "./StorageService-method-action-types.mjs";
 export { SERVICE_NAME, STORAGE_KEY_PREFIX } from "./types.mjs";
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,6BAAyB;AAGlD,OAAO,EAAE,sBAAsB,EAAE,qCAAiC;AAGlE,YAAY,EACV,cAAc,EACd,qBAAqB,EACrB,qBAAqB,EACrB,oBAAoB,EACpB,uBAAuB,EACvB,0BAA0B,GAC3B,oBAAgB;AAGjB,YAAY,EACV,2BAA2B,EAC3B,2BAA2B,EAC3B,8BAA8B,EAC9B,8BAA8B,EAC9B,yBAAyB,GAC1B,iDAA6C;AAG9C,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,oBAAgB"}
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,6BAAyB;AAGlD,OAAO,EAAE,sBAAsB,EAAE,qCAAiC;AAGlE,YAAY,EACV,cAAc,EACd,gBAAgB,EAChB,qBAAqB,EACrB,qBAAqB,EACrB,oBAAoB,EACpB,uBAAuB,EACvB,0BAA0B,GAC3B,oBAAgB;AAGjB,YAAY,EACV,2BAA2B,EAC3B,2BAA2B,EAC3B,8BAA8B,EAC9B,8BAA8B,EAC9B,yBAAyB,GAC1B,iDAA6C;AAG9C,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,oBAAgB"}

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,uBAAuB;AACvB,OAAO,EAAE,cAAc,EAAE,6BAAyB;AAElD,kBAAkB;AAClB,OAAO,EAAE,sBAAsB,EAAE,qCAAiC;AAqBlE,uDAAuD;AACvD,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,oBAAgB","sourcesContent":["// Export service class\nexport { StorageService } from './StorageService';\n\n// Export adapters\nexport { InMemoryStorageAdapter } from './InMemoryStorageAdapter';\n\n// Export types from types.ts\nexport type {\n  StorageAdapter,\n  StorageServiceOptions,\n  StorageServiceActions,\n  StorageServiceEvents,\n  StorageServiceMessenger,\n  StorageServiceItemSetEvent,\n} from './types';\n\n// Export individual action types from generated file\nexport type {\n  StorageServiceSetItemAction,\n  StorageServiceGetItemAction,\n  StorageServiceRemoveItemAction,\n  StorageServiceGetAllKeysAction,\n  StorageServiceClearAction,\n} from './StorageService-method-action-types';\n\n// Export service name and storage key prefix constants\nexport { SERVICE_NAME, STORAGE_KEY_PREFIX } from './types';\n"]}
+{"version":3,"file":"index.mjs","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,uBAAuB;AACvB,OAAO,EAAE,cAAc,EAAE,6BAAyB;AAElD,kBAAkB;AAClB,OAAO,EAAE,sBAAsB,EAAE,qCAAiC;AAsBlE,uDAAuD;AACvD,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,oBAAgB","sourcesContent":["// Export service class\nexport { StorageService } from './StorageService';\n\n// Export adapters\nexport { InMemoryStorageAdapter } from './InMemoryStorageAdapter';\n\n// Export types from types.ts\nexport type {\n  StorageAdapter,\n  StorageGetResult,\n  StorageServiceOptions,\n  StorageServiceActions,\n  StorageServiceEvents,\n  StorageServiceMessenger,\n  StorageServiceItemSetEvent,\n} from './types';\n\n// Export individual action types from generated file\nexport type {\n  StorageServiceSetItemAction,\n  StorageServiceGetItemAction,\n  StorageServiceRemoveItemAction,\n  StorageServiceGetAllKeysAction,\n  StorageServiceClearAction,\n} from './StorageService-method-action-types';\n\n// Export service name and storage key prefix constants\nexport { SERVICE_NAME, STORAGE_KEY_PREFIX } from './types';\n"]}

package/dist/types.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"types.cjs","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";;;AA2GA,wBAAwB;AACX,QAAA,YAAY,GAAG,gBAAgB,CAAC;AAE7C;;;;GAIG;AACU,QAAA,kBAAkB,GAAG,iBAAiB,CAAC","sourcesContent":["import type { Messenger } from '@metamask/messenger';\nimport type { Json } from '@metamask/utils';\n\nimport type { StorageServiceMethodActions } from './StorageService-method-action-types';\n\n/**\n * Platform-agnostic storage adapter interface.\n * Each client (mobile, extension) implements this interface\n * with their preferred storage mechanism.\n *\n * ⚠️ **Designed for large, infrequently accessed data (100KB+)**\n *\n * ✅ **Use for:**\n * - Snap source code (~6 MB per snap)\n * - Token metadata caches (~4 MB)\n * - Large API response caches\n *\n * ❌ **Avoid for:**\n * - Small values (< 10 KB) - use controller state instead\n * - Frequently accessed data - use controller state instead\n * - Many small key-value pairs - use a single large object instead\n *\n * @example Mobile implementation using FilesystemStorage\n * @example Extension implementation using IndexedDB\n * @example Tests using InMemoryStorageAdapter\n */\nexport type StorageAdapter = {\n  /**\n   * Retrieve an item from storage.\n   * Adapter is responsible for building the full storage key.\n   *\n   * @param namespace - The controller namespace (e.g., 'SnapController').\n   * @param key - The data key (e.g., 'snap-id:sourceCode').\n   * @returns The JSON value, or null if not found.\n   */\n  getItem(namespace: string, key: string): Promise<Json | null>;\n\n  /**\n   * Store a large JSON value in storage.\n   *\n   * ⚠️ **Store large values, not many small ones.**\n   * Each storage operation has I/O overhead. For best performance:\n   * - Store one large object rather than many small key-value pairs\n   * - Minimum recommended size: 100 KB per value\n   *\n   * Adapter is responsible for:\n   * - Building the full storage key\n   * - Serializing to string (JSON.stringify)\n   *\n   * @param namespace - The controller namespace (e.g., 'SnapController').\n   * @param key - The data key (e.g., 'snap-id:sourceCode').\n   * @param value - The JSON value to store.\n   */\n  setItem(namespace: string, key: string, value: Json): Promise<void>;\n\n  /**\n   * Remove an item from storage.\n   * Adapter is responsible for building the full storage key.\n   *\n   * @param namespace - The controller namespace (e.g., 'SnapController').\n   * @param key - The data key (e.g., 'snap-id:sourceCode').\n   */\n  removeItem(namespace: string, key: string): Promise<void>;\n\n  /**\n   * Get all keys for a specific namespace.\n   * Should return keys without the 'storage:namespace:' prefix.\n   *\n   * Adapter is responsible for:\n   * - Filtering keys by prefix: 'storage:{namespace}:'\n   * - Stripping the prefix from returned keys\n   * - Returning only the key portion after the prefix\n   *\n   * @param namespace - The namespace to get keys for (e.g., 'SnapController').\n   * @returns Array of keys without prefix (e.g., ['snap1:sourceCode', 'snap2:sourceCode']).\n   */\n  getAllKeys(namespace: string): Promise<string[]>;\n\n  /**\n   * Clear all items for a specific namespace.\n   *\n   * Adapter is responsible for:\n   * - Finding all keys with prefix: 'storageService:{namespace}:'\n   * - Removing all matching keys\n   *\n   * @param namespace - The namespace to clear (e.g., 'SnapController').\n   */\n  clear(namespace: string): Promise<void>;\n};\n\n/**\n * Options for constructing a {@link StorageService}.\n */\nexport type StorageServiceOptions = {\n  /**\n   * The messenger suited for this service.\n   */\n  messenger: StorageServiceMessenger;\n\n  /**\n   * Storage adapter for persisting data.\n   * If not provided, uses in-memory storage (data lost on restart).\n   * Production clients MUST provide a persistent storage adapter.\n   */\n  storage?: StorageAdapter;\n};\n\n// Service name constant\nexport const SERVICE_NAME = 'StorageService';\n\n/**\n * Storage key prefix for all keys managed by StorageService.\n * Keys are formatted as: {STORAGE_KEY_PREFIX}{namespace}:{key}\n * Example: 'storageService:SnapController:snap-id:sourceCode'\n */\nexport const STORAGE_KEY_PREFIX = 'storageService:';\n\n/**\n * All actions that {@link StorageService} exposes to other consumers.\n * Action types are auto-generated from the service methods.\n */\nexport type StorageServiceActions = StorageServiceMethodActions;\n\n/**\n * Event published when a storage item is set.\n * Event type includes namespace only, key passed in payload.\n *\n * @example\n * Subscribe to all changes in TokenListController:\n * messenger.subscribe('StorageService:itemSet:TokenListController', (key, value) => {\n *   // key = 'cache:0x1', 'cache:0x38', etc.\n *   // value = the data that was set\n *   if (key.startsWith('cache:')) {\n *     const chainId = key.replace('cache:', '');\n *     // React to cache change for specific chain\n *   }\n * });\n */\nexport type StorageServiceItemSetEvent = {\n  type: `${typeof SERVICE_NAME}:itemSet:${string}`;\n  payload: [key: string, value: Json];\n};\n\n/**\n * All events that {@link StorageService} publishes.\n */\nexport type StorageServiceEvents = StorageServiceItemSetEvent;\n\n/**\n * Actions from other messengers that {@link StorageService} calls.\n */\ntype AllowedActions = never;\n\n/**\n * Events from other messengers that {@link StorageService} subscribes to.\n */\ntype AllowedEvents = never;\n\n/**\n * The messenger restricted to actions and events that\n * {@link StorageService} needs to access.\n */\nexport type StorageServiceMessenger = Messenger<\n  typeof SERVICE_NAME,\n  StorageServiceActions | AllowedActions,\n  StorageServiceEvents | AllowedEvents\n>;\n"]}
+{"version":3,"file":"types.cjs","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";;;AAwHA,wBAAwB;AACX,QAAA,YAAY,GAAG,gBAAgB,CAAC;AAE7C;;;;GAIG;AACU,QAAA,kBAAkB,GAAG,iBAAiB,CAAC","sourcesContent":["import type { Messenger } from '@metamask/messenger';\nimport type { Json } from '@metamask/utils';\n\nimport type { StorageServiceMethodActions } from './StorageService-method-action-types';\n\n/**\n * Result type for getItem operations.\n * Distinguishes between: found data, not found, and error conditions.\n *\n * - `{ result: Json }` - Data was found and successfully retrieved\n * - `{}` (empty object) - No data stored with that key\n * - `{ error: Error }` - Error occurred during retrieval\n */\nexport type StorageGetResult =\n  | { result: Json; error?: never }\n  | { result?: never; error: Error }\n  | Record<string, never>;\n\n/**\n * Platform-agnostic storage adapter interface.\n * Each client (mobile, extension) implements this interface\n * with their preferred storage mechanism.\n *\n * ⚠️ **Designed for large, infrequently accessed data (100KB+)**\n *\n * ✅ **Use for:**\n * - Snap source code (~6 MB per snap)\n * - Token metadata caches (~4 MB)\n * - Large API response caches\n *\n * ❌ **Avoid for:**\n * - Small values (< 10 KB) - use controller state instead\n * - Frequently accessed data - use controller state instead\n * - Many small key-value pairs - use a single large object instead\n *\n * @example Mobile implementation using FilesystemStorage\n * @example Extension implementation using IndexedDB\n * @example Tests using InMemoryStorageAdapter\n */\nexport type StorageAdapter = {\n  /**\n   * Retrieve an item from storage.\n   * Adapter is responsible for building the full storage key.\n   *\n   * @param namespace - The controller namespace (e.g., 'SnapController').\n   * @param key - The data key (e.g., 'snap-id:sourceCode').\n   * @returns StorageGetResult: { result } if found, {} if not found, { error } on failure.\n   */\n  getItem(namespace: string, key: string): Promise<StorageGetResult>;\n\n  /**\n   * Store a large JSON value in storage.\n   *\n   * ⚠️ **Store large values, not many small ones.**\n   * Each storage operation has I/O overhead. For best performance:\n   * - Store one large object rather than many small key-value pairs\n   * - Minimum recommended size: 100 KB per value\n   *\n   * Adapter is responsible for:\n   * - Building the full storage key\n   * - Serializing to string (JSON.stringify)\n   *\n   * @param namespace - The controller namespace (e.g., 'SnapController').\n   * @param key - The data key (e.g., 'snap-id:sourceCode').\n   * @param value - The JSON value to store.\n   */\n  setItem(namespace: string, key: string, value: Json): Promise<void>;\n\n  /**\n   * Remove an item from storage.\n   * Adapter is responsible for building the full storage key.\n   *\n   * @param namespace - The controller namespace (e.g., 'SnapController').\n   * @param key - The data key (e.g., 'snap-id:sourceCode').\n   */\n  removeItem(namespace: string, key: string): Promise<void>;\n\n  /**\n   * Get all keys for a specific namespace.\n   * Should return keys without the 'storage:namespace:' prefix.\n   *\n   * Adapter is responsible for:\n   * - Filtering keys by prefix: 'storage:{namespace}:'\n   * - Stripping the prefix from returned keys\n   * - Returning only the key portion after the prefix\n   *\n   * @param namespace - The namespace to get keys for (e.g., 'SnapController').\n   * @returns Array of keys without prefix (e.g., ['snap1:sourceCode', 'snap2:sourceCode']).\n   */\n  getAllKeys(namespace: string): Promise<string[]>;\n\n  /**\n   * Clear all items for a specific namespace.\n   *\n   * Adapter is responsible for:\n   * - Finding all keys with prefix: 'storageService:{namespace}:'\n   * - Removing all matching keys\n   *\n   * @param namespace - The namespace to clear (e.g., 'SnapController').\n   */\n  clear(namespace: string): Promise<void>;\n};\n\n/**\n * Options for constructing a {@link StorageService}.\n */\nexport type StorageServiceOptions = {\n  /**\n   * The messenger suited for this service.\n   */\n  messenger: StorageServiceMessenger;\n\n  /**\n   * Storage adapter for persisting data.\n   * If not provided, uses in-memory storage (data lost on restart).\n   * Production clients MUST provide a persistent storage adapter.\n   */\n  storage?: StorageAdapter;\n};\n\n// Service name constant\nexport const SERVICE_NAME = 'StorageService';\n\n/**\n * Storage key prefix for all keys managed by StorageService.\n * Keys are formatted as: {STORAGE_KEY_PREFIX}{namespace}:{key}\n * Example: 'storageService:SnapController:snap-id:sourceCode'\n */\nexport const STORAGE_KEY_PREFIX = 'storageService:';\n\n/**\n * All actions that {@link StorageService} exposes to other consumers.\n * Action types are auto-generated from the service methods.\n */\nexport type StorageServiceActions = StorageServiceMethodActions;\n\n/**\n * Event published when a storage item is set.\n * Event type includes namespace only, key passed in payload.\n *\n * @example\n * Subscribe to all changes in TokenListController:\n * messenger.subscribe('StorageService:itemSet:TokenListController', (key, value) => {\n *   // key = 'cache:0x1', 'cache:0x38', etc.\n *   // value = the data that was set\n *   if (key.startsWith('cache:')) {\n *     const chainId = key.replace('cache:', '');\n *     // React to cache change for specific chain\n *   }\n * });\n */\nexport type StorageServiceItemSetEvent = {\n  type: `${typeof SERVICE_NAME}:itemSet:${string}`;\n  payload: [key: string, value: Json];\n};\n\n/**\n * All events that {@link StorageService} publishes.\n */\nexport type StorageServiceEvents = StorageServiceItemSetEvent;\n\n/**\n * Actions from other messengers that {@link StorageService} calls.\n */\ntype AllowedActions = never;\n\n/**\n * Events from other messengers that {@link StorageService} subscribes to.\n */\ntype AllowedEvents = never;\n\n/**\n * The messenger restricted to actions and events that\n * {@link StorageService} needs to access.\n */\nexport type StorageServiceMessenger = Messenger<\n  typeof SERVICE_NAME,\n  StorageServiceActions | AllowedActions,\n  StorageServiceEvents | AllowedEvents\n>;\n"]}

package/dist/types.d.cts

@@ -1,6 +1,21 @@
 import type { Messenger } from "@metamask/messenger";
 import type { Json } from "@metamask/utils";
 import type { StorageServiceMethodActions } from "./StorageService-method-action-types.cjs";
+/**
+ * Result type for getItem operations.
+ * Distinguishes between: found data, not found, and error conditions.
+ *
+ * - `{ result: Json }` - Data was found and successfully retrieved
+ * - `{}` (empty object) - No data stored with that key
+ * - `{ error: Error }` - Error occurred during retrieval
+ */
+export type StorageGetResult = {
+    result: Json;
+    error?: never;
+} | {
+    result?: never;
+    error: Error;
+} | Record<string, never>;
 /**
  * Platform-agnostic storage adapter interface.
  * Each client (mobile, extension) implements this interface
@@ -29,9 +44,9 @@ export type StorageAdapter = {
      *
      * @param namespace - The controller namespace (e.g., 'SnapController').
      * @param key - The data key (e.g., 'snap-id:sourceCode').
-     * @returns The JSON value, or null if not found.
+     * @returns StorageGetResult: { result } if found, {} if not found, { error } on failure.
      */
-    getItem(namespace: string, key: string): Promise<Json | null>;
+    getItem(namespace: string, key: string): Promise<StorageGetResult>;
     /**
      * Store a large JSON value in storage.
      *

package/dist/types.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.cts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,4BAA4B;AACrD,OAAO,KAAK,EAAE,IAAI,EAAE,wBAAwB;AAE5C,OAAO,KAAK,EAAE,2BAA2B,EAAE,iDAA6C;AAExF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B;;;;;;;OAOG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;IAE9D;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpE;;;;;;OAMG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1D;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAEjD;;;;;;;;OAQG;IACH,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC;;OAEG;IACH,SAAS,EAAE,uBAAuB,CAAC;IAEnC;;;;OAIG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B,CAAC;AAGF,eAAO,MAAM,YAAY,mBAAmB,CAAC;AAE7C;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,oBAAoB,CAAC;AAEpD;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAAG,2BAA2B,CAAC;AAEhE;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,0BAA0B,GAAG;IACvC,IAAI,EAAE,GAAG,OAAO,YAAY,YAAY,MAAM,EAAE,CAAC;IACjD,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;CACrC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,0BAA0B,CAAC;AAE9D;;GAEG;AACH,KAAK,cAAc,GAAG,KAAK,CAAC;AAE5B;;GAEG;AACH,KAAK,aAAa,GAAG,KAAK,CAAC;AAE3B;;;GAGG;AACH,MAAM,MAAM,uBAAuB,GAAG,SAAS,CAC7C,OAAO,YAAY,EACnB,qBAAqB,GAAG,cAAc,EACtC,oBAAoB,GAAG,aAAa,CACrC,CAAC"}
+{"version":3,"file":"types.d.cts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,4BAA4B;AACrD,OAAO,KAAK,EAAE,IAAI,EAAE,wBAAwB;AAE5C,OAAO,KAAK,EAAE,2BAA2B,EAAE,iDAA6C;AAExF;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,MAAM,EAAE,IAAI,CAAC;IAAC,KAAK,CAAC,EAAE,KAAK,CAAA;CAAE,GAC/B;IAAE,MAAM,CAAC,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,GAChC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAE1B;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B;;;;;;;OAOG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAEnE;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpE;;;;;;OAMG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1D;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAEjD;;;;;;;;OAQG;IACH,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC;;OAEG;IACH,SAAS,EAAE,uBAAuB,CAAC;IAEnC;;;;OAIG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B,CAAC;AAGF,eAAO,MAAM,YAAY,mBAAmB,CAAC;AAE7C;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,oBAAoB,CAAC;AAEpD;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAAG,2BAA2B,CAAC;AAEhE;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,0BAA0B,GAAG;IACvC,IAAI,EAAE,GAAG,OAAO,YAAY,YAAY,MAAM,EAAE,CAAC;IACjD,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;CACrC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,0BAA0B,CAAC;AAE9D;;GAEG;AACH,KAAK,cAAc,GAAG,KAAK,CAAC;AAE5B;;GAEG;AACH,KAAK,aAAa,GAAG,KAAK,CAAC;AAE3B;;;GAGG;AACH,MAAM,MAAM,uBAAuB,GAAG,SAAS,CAC7C,OAAO,YAAY,EACnB,qBAAqB,GAAG,cAAc,EACtC,oBAAoB,GAAG,aAAa,CACrC,CAAC"}

package/dist/types.d.mts

@@ -1,6 +1,21 @@
 import type { Messenger } from "@metamask/messenger";
 import type { Json } from "@metamask/utils";
 import type { StorageServiceMethodActions } from "./StorageService-method-action-types.mjs";
+/**
+ * Result type for getItem operations.
+ * Distinguishes between: found data, not found, and error conditions.
+ *
+ * - `{ result: Json }` - Data was found and successfully retrieved
+ * - `{}` (empty object) - No data stored with that key
+ * - `{ error: Error }` - Error occurred during retrieval
+ */
+export type StorageGetResult = {
+    result: Json;
+    error?: never;
+} | {
+    result?: never;
+    error: Error;
+} | Record<string, never>;
 /**
  * Platform-agnostic storage adapter interface.
  * Each client (mobile, extension) implements this interface
@@ -29,9 +44,9 @@ export type StorageAdapter = {
      *
      * @param namespace - The controller namespace (e.g., 'SnapController').
      * @param key - The data key (e.g., 'snap-id:sourceCode').
-     * @returns The JSON value, or null if not found.
+     * @returns StorageGetResult: { result } if found, {} if not found, { error } on failure.
      */
-    getItem(namespace: string, key: string): Promise<Json | null>;
+    getItem(namespace: string, key: string): Promise<StorageGetResult>;
     /**
      * Store a large JSON value in storage.
      *

package/dist/types.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.mts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,4BAA4B;AACrD,OAAO,KAAK,EAAE,IAAI,EAAE,wBAAwB;AAE5C,OAAO,KAAK,EAAE,2BAA2B,EAAE,iDAA6C;AAExF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B;;;;;;;OAOG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;IAE9D;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpE;;;;;;OAMG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1D;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAEjD;;;;;;;;OAQG;IACH,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC;;OAEG;IACH,SAAS,EAAE,uBAAuB,CAAC;IAEnC;;;;OAIG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B,CAAC;AAGF,eAAO,MAAM,YAAY,mBAAmB,CAAC;AAE7C;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,oBAAoB,CAAC;AAEpD;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAAG,2BAA2B,CAAC;AAEhE;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,0BAA0B,GAAG;IACvC,IAAI,EAAE,GAAG,OAAO,YAAY,YAAY,MAAM,EAAE,CAAC;IACjD,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;CACrC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,0BAA0B,CAAC;AAE9D;;GAEG;AACH,KAAK,cAAc,GAAG,KAAK,CAAC;AAE5B;;GAEG;AACH,KAAK,aAAa,GAAG,KAAK,CAAC;AAE3B;;;GAGG;AACH,MAAM,MAAM,uBAAuB,GAAG,SAAS,CAC7C,OAAO,YAAY,EACnB,qBAAqB,GAAG,cAAc,EACtC,oBAAoB,GAAG,aAAa,CACrC,CAAC"}
+{"version":3,"file":"types.d.mts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,4BAA4B;AACrD,OAAO,KAAK,EAAE,IAAI,EAAE,wBAAwB;AAE5C,OAAO,KAAK,EAAE,2BAA2B,EAAE,iDAA6C;AAExF;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,MAAM,EAAE,IAAI,CAAC;IAAC,KAAK,CAAC,EAAE,KAAK,CAAA;CAAE,GAC/B;IAAE,MAAM,CAAC,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,GAChC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAE1B;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B;;;;;;;OAOG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAEnE;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpE;;;;;;OAMG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1D;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAEjD;;;;;;;;OAQG;IACH,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC;;OAEG;IACH,SAAS,EAAE,uBAAuB,CAAC;IAEnC;;;;OAIG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B,CAAC;AAGF,eAAO,MAAM,YAAY,mBAAmB,CAAC;AAE7C;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,oBAAoB,CAAC;AAEpD;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAAG,2BAA2B,CAAC;AAEhE;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,0BAA0B,GAAG;IACvC,IAAI,EAAE,GAAG,OAAO,YAAY,YAAY,MAAM,EAAE,CAAC;IACjD,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;CACrC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,0BAA0B,CAAC;AAE9D;;GAEG;AACH,KAAK,cAAc,GAAG,KAAK,CAAC;AAE5B;;GAEG;AACH,KAAK,aAAa,GAAG,KAAK,CAAC;AAE3B;;;GAGG;AACH,MAAM,MAAM,uBAAuB,GAAG,SAAS,CAC7C,OAAO,YAAY,EACnB,qBAAqB,GAAG,cAAc,EACtC,oBAAoB,GAAG,aAAa,CACrC,CAAC"}

package/dist/types.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"types.mjs","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AA2GA,wBAAwB;AACxB,MAAM,CAAC,MAAM,YAAY,GAAG,gBAAgB,CAAC;AAE7C;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,iBAAiB,CAAC","sourcesContent":["import type { Messenger } from '@metamask/messenger';\nimport type { Json } from '@metamask/utils';\n\nimport type { StorageServiceMethodActions } from './StorageService-method-action-types';\n\n/**\n * Platform-agnostic storage adapter interface.\n * Each client (mobile, extension) implements this interface\n * with their preferred storage mechanism.\n *\n * ⚠️ **Designed for large, infrequently accessed data (100KB+)**\n *\n * ✅ **Use for:**\n * - Snap source code (~6 MB per snap)\n * - Token metadata caches (~4 MB)\n * - Large API response caches\n *\n * ❌ **Avoid for:**\n * - Small values (< 10 KB) - use controller state instead\n * - Frequently accessed data - use controller state instead\n * - Many small key-value pairs - use a single large object instead\n *\n * @example Mobile implementation using FilesystemStorage\n * @example Extension implementation using IndexedDB\n * @example Tests using InMemoryStorageAdapter\n */\nexport type StorageAdapter = {\n  /**\n   * Retrieve an item from storage.\n   * Adapter is responsible for building the full storage key.\n   *\n   * @param namespace - The controller namespace (e.g., 'SnapController').\n   * @param key - The data key (e.g., 'snap-id:sourceCode').\n   * @returns The JSON value, or null if not found.\n   */\n  getItem(namespace: string, key: string): Promise<Json | null>;\n\n  /**\n   * Store a large JSON value in storage.\n   *\n   * ⚠️ **Store large values, not many small ones.**\n   * Each storage operation has I/O overhead. For best performance:\n   * - Store one large object rather than many small key-value pairs\n   * - Minimum recommended size: 100 KB per value\n   *\n   * Adapter is responsible for:\n   * - Building the full storage key\n   * - Serializing to string (JSON.stringify)\n   *\n   * @param namespace - The controller namespace (e.g., 'SnapController').\n   * @param key - The data key (e.g., 'snap-id:sourceCode').\n   * @param value - The JSON value to store.\n   */\n  setItem(namespace: string, key: string, value: Json): Promise<void>;\n\n  /**\n   * Remove an item from storage.\n   * Adapter is responsible for building the full storage key.\n   *\n   * @param namespace - The controller namespace (e.g., 'SnapController').\n   * @param key - The data key (e.g., 'snap-id:sourceCode').\n   */\n  removeItem(namespace: string, key: string): Promise<void>;\n\n  /**\n   * Get all keys for a specific namespace.\n   * Should return keys without the 'storage:namespace:' prefix.\n   *\n   * Adapter is responsible for:\n   * - Filtering keys by prefix: 'storage:{namespace}:'\n   * - Stripping the prefix from returned keys\n   * - Returning only the key portion after the prefix\n   *\n   * @param namespace - The namespace to get keys for (e.g., 'SnapController').\n   * @returns Array of keys without prefix (e.g., ['snap1:sourceCode', 'snap2:sourceCode']).\n   */\n  getAllKeys(namespace: string): Promise<string[]>;\n\n  /**\n   * Clear all items for a specific namespace.\n   *\n   * Adapter is responsible for:\n   * - Finding all keys with prefix: 'storageService:{namespace}:'\n   * - Removing all matching keys\n   *\n   * @param namespace - The namespace to clear (e.g., 'SnapController').\n   */\n  clear(namespace: string): Promise<void>;\n};\n\n/**\n * Options for constructing a {@link StorageService}.\n */\nexport type StorageServiceOptions = {\n  /**\n   * The messenger suited for this service.\n   */\n  messenger: StorageServiceMessenger;\n\n  /**\n   * Storage adapter for persisting data.\n   * If not provided, uses in-memory storage (data lost on restart).\n   * Production clients MUST provide a persistent storage adapter.\n   */\n  storage?: StorageAdapter;\n};\n\n// Service name constant\nexport const SERVICE_NAME = 'StorageService';\n\n/**\n * Storage key prefix for all keys managed by StorageService.\n * Keys are formatted as: {STORAGE_KEY_PREFIX}{namespace}:{key}\n * Example: 'storageService:SnapController:snap-id:sourceCode'\n */\nexport const STORAGE_KEY_PREFIX = 'storageService:';\n\n/**\n * All actions that {@link StorageService} exposes to other consumers.\n * Action types are auto-generated from the service methods.\n */\nexport type StorageServiceActions = StorageServiceMethodActions;\n\n/**\n * Event published when a storage item is set.\n * Event type includes namespace only, key passed in payload.\n *\n * @example\n * Subscribe to all changes in TokenListController:\n * messenger.subscribe('StorageService:itemSet:TokenListController', (key, value) => {\n *   // key = 'cache:0x1', 'cache:0x38', etc.\n *   // value = the data that was set\n *   if (key.startsWith('cache:')) {\n *     const chainId = key.replace('cache:', '');\n *     // React to cache change for specific chain\n *   }\n * });\n */\nexport type StorageServiceItemSetEvent = {\n  type: `${typeof SERVICE_NAME}:itemSet:${string}`;\n  payload: [key: string, value: Json];\n};\n\n/**\n * All events that {@link StorageService} publishes.\n */\nexport type StorageServiceEvents = StorageServiceItemSetEvent;\n\n/**\n * Actions from other messengers that {@link StorageService} calls.\n */\ntype AllowedActions = never;\n\n/**\n * Events from other messengers that {@link StorageService} subscribes to.\n */\ntype AllowedEvents = never;\n\n/**\n * The messenger restricted to actions and events that\n * {@link StorageService} needs to access.\n */\nexport type StorageServiceMessenger = Messenger<\n  typeof SERVICE_NAME,\n  StorageServiceActions | AllowedActions,\n  StorageServiceEvents | AllowedEvents\n>;\n"]}
+{"version":3,"file":"types.mjs","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAwHA,wBAAwB;AACxB,MAAM,CAAC,MAAM,YAAY,GAAG,gBAAgB,CAAC;AAE7C;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,iBAAiB,CAAC","sourcesContent":["import type { Messenger } from '@metamask/messenger';\nimport type { Json } from '@metamask/utils';\n\nimport type { StorageServiceMethodActions } from './StorageService-method-action-types';\n\n/**\n * Result type for getItem operations.\n * Distinguishes between: found data, not found, and error conditions.\n *\n * - `{ result: Json }` - Data was found and successfully retrieved\n * - `{}` (empty object) - No data stored with that key\n * - `{ error: Error }` - Error occurred during retrieval\n */\nexport type StorageGetResult =\n  | { result: Json; error?: never }\n  | { result?: never; error: Error }\n  | Record<string, never>;\n\n/**\n * Platform-agnostic storage adapter interface.\n * Each client (mobile, extension) implements this interface\n * with their preferred storage mechanism.\n *\n * ⚠️ **Designed for large, infrequently accessed data (100KB+)**\n *\n * ✅ **Use for:**\n * - Snap source code (~6 MB per snap)\n * - Token metadata caches (~4 MB)\n * - Large API response caches\n *\n * ❌ **Avoid for:**\n * - Small values (< 10 KB) - use controller state instead\n * - Frequently accessed data - use controller state instead\n * - Many small key-value pairs - use a single large object instead\n *\n * @example Mobile implementation using FilesystemStorage\n * @example Extension implementation using IndexedDB\n * @example Tests using InMemoryStorageAdapter\n */\nexport type StorageAdapter = {\n  /**\n   * Retrieve an item from storage.\n   * Adapter is responsible for building the full storage key.\n   *\n   * @param namespace - The controller namespace (e.g., 'SnapController').\n   * @param key - The data key (e.g., 'snap-id:sourceCode').\n   * @returns StorageGetResult: { result } if found, {} if not found, { error } on failure.\n   */\n  getItem(namespace: string, key: string): Promise<StorageGetResult>;\n\n  /**\n   * Store a large JSON value in storage.\n   *\n   * ⚠️ **Store large values, not many small ones.**\n   * Each storage operation has I/O overhead. For best performance:\n   * - Store one large object rather than many small key-value pairs\n   * - Minimum recommended size: 100 KB per value\n   *\n   * Adapter is responsible for:\n   * - Building the full storage key\n   * - Serializing to string (JSON.stringify)\n   *\n   * @param namespace - The controller namespace (e.g., 'SnapController').\n   * @param key - The data key (e.g., 'snap-id:sourceCode').\n   * @param value - The JSON value to store.\n   */\n  setItem(namespace: string, key: string, value: Json): Promise<void>;\n\n  /**\n   * Remove an item from storage.\n   * Adapter is responsible for building the full storage key.\n   *\n   * @param namespace - The controller namespace (e.g., 'SnapController').\n   * @param key - The data key (e.g., 'snap-id:sourceCode').\n   */\n  removeItem(namespace: string, key: string): Promise<void>;\n\n  /**\n   * Get all keys for a specific namespace.\n   * Should return keys without the 'storage:namespace:' prefix.\n   *\n   * Adapter is responsible for:\n   * - Filtering keys by prefix: 'storage:{namespace}:'\n   * - Stripping the prefix from returned keys\n   * - Returning only the key portion after the prefix\n   *\n   * @param namespace - The namespace to get keys for (e.g., 'SnapController').\n   * @returns Array of keys without prefix (e.g., ['snap1:sourceCode', 'snap2:sourceCode']).\n   */\n  getAllKeys(namespace: string): Promise<string[]>;\n\n  /**\n   * Clear all items for a specific namespace.\n   *\n   * Adapter is responsible for:\n   * - Finding all keys with prefix: 'storageService:{namespace}:'\n   * - Removing all matching keys\n   *\n   * @param namespace - The namespace to clear (e.g., 'SnapController').\n   */\n  clear(namespace: string): Promise<void>;\n};\n\n/**\n * Options for constructing a {@link StorageService}.\n */\nexport type StorageServiceOptions = {\n  /**\n   * The messenger suited for this service.\n   */\n  messenger: StorageServiceMessenger;\n\n  /**\n   * Storage adapter for persisting data.\n   * If not provided, uses in-memory storage (data lost on restart).\n   * Production clients MUST provide a persistent storage adapter.\n   */\n  storage?: StorageAdapter;\n};\n\n// Service name constant\nexport const SERVICE_NAME = 'StorageService';\n\n/**\n * Storage key prefix for all keys managed by StorageService.\n * Keys are formatted as: {STORAGE_KEY_PREFIX}{namespace}:{key}\n * Example: 'storageService:SnapController:snap-id:sourceCode'\n */\nexport const STORAGE_KEY_PREFIX = 'storageService:';\n\n/**\n * All actions that {@link StorageService} exposes to other consumers.\n * Action types are auto-generated from the service methods.\n */\nexport type StorageServiceActions = StorageServiceMethodActions;\n\n/**\n * Event published when a storage item is set.\n * Event type includes namespace only, key passed in payload.\n *\n * @example\n * Subscribe to all changes in TokenListController:\n * messenger.subscribe('StorageService:itemSet:TokenListController', (key, value) => {\n *   // key = 'cache:0x1', 'cache:0x38', etc.\n *   // value = the data that was set\n *   if (key.startsWith('cache:')) {\n *     const chainId = key.replace('cache:', '');\n *     // React to cache change for specific chain\n *   }\n * });\n */\nexport type StorageServiceItemSetEvent = {\n  type: `${typeof SERVICE_NAME}:itemSet:${string}`;\n  payload: [key: string, value: Json];\n};\n\n/**\n * All events that {@link StorageService} publishes.\n */\nexport type StorageServiceEvents = StorageServiceItemSetEvent;\n\n/**\n * Actions from other messengers that {@link StorageService} calls.\n */\ntype AllowedActions = never;\n\n/**\n * Events from other messengers that {@link StorageService} subscribes to.\n */\ntype AllowedEvents = never;\n\n/**\n * The messenger restricted to actions and events that\n * {@link StorageService} needs to access.\n */\nexport type StorageServiceMessenger = Messenger<\n  typeof SERVICE_NAME,\n  StorageServiceActions | AllowedActions,\n  StorageServiceEvents | AllowedEvents\n>;\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metamask-previews/storage-service",
-  "version": "0.0.0-preview-d6fe4594",
+  "version": "0.0.0-preview-2b2b3f4d",
   "description": "Platform-agnostic service for storing large, infrequently accessed controller data",
   "keywords": [
     "MetaMask",