@metamask-previews/storage-service 1.0.0-preview-f5c5aecd → 1.0.0-preview-81c9cf83

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

@@ -0,0 +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 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 - 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 data from storage.\n *\n * Returns `unknown` since there's no schema validation.\n * Callers should validate or cast the result to the expected type.\n *\n * @param namespace - Controller namespace (e.g., 'SnapController').\n * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').\n * @returns Parsed data or null if not found. Type is `unknown` - caller must validate.\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

@@ -0,0 +1,81 @@
+/**
+ * This file is auto generated by `scripts/generate-method-action-types.ts`.
+ * Do not edit manually.
+ */
+import type { StorageService } from "./StorageService.cjs";
+/**
+ * Store large data in storage.
+ *
+ * ⚠️ **Designed for large values (100KB+), not many small ones.**
+ * Each storage operation has I/O overhead. For best performance,
+ * store one large object rather than many small key-value pairs.
+ *
+ * @example Good: Store entire cache as one value
+ * ```typescript
+ * await service.setItem('TokenList', 'cache', { '0x1': [...], '0x38': [...] });
+ * ```
+ *
+ * @example Avoid: Many small values
+ * ```typescript
+ * // ❌ Don't do this - too many small writes
+ * await service.setItem('TokenList', 'cache:0x1', [...]);
+ * await service.setItem('TokenList', 'cache:0x38', [...]);
+ * ```
+ *
+ * @param namespace - Controller namespace (e.g., 'SnapController').
+ * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').
+ * @param value - Data to store (should be 100KB+ for optimal use).
+ */
+export type StorageServiceSetItemAction = {
+    type: `StorageService:setItem`;
+    handler: StorageService['setItem'];
+};
+/**
+ * Retrieve data from storage.
+ *
+ * Returns `unknown` since there's no schema validation.
+ * Callers should validate or cast the result to the expected type.
+ *
+ * @param namespace - Controller namespace (e.g., 'SnapController').
+ * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').
+ * @returns Parsed data or null if not found. Type is `unknown` - caller must validate.
+ */
+export type StorageServiceGetItemAction = {
+    type: `StorageService:getItem`;
+    handler: StorageService['getItem'];
+};
+/**
+ * Remove data from storage.
+ *
+ * @param namespace - Controller namespace (e.g., 'SnapController').
+ * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').
+ */
+export type StorageServiceRemoveItemAction = {
+    type: `StorageService:removeItem`;
+    handler: StorageService['removeItem'];
+};
+/**
+ * Get all keys for a namespace.
+ * Delegates to storage adapter which handles filtering.
+ *
+ * @param namespace - Controller namespace (e.g., 'SnapController').
+ * @returns Array of keys (without prefix) for this namespace.
+ */
+export type StorageServiceGetAllKeysAction = {
+    type: `StorageService:getAllKeys`;
+    handler: StorageService['getAllKeys'];
+};
+/**
+ * Clear all data for a namespace.
+ *
+ * @param namespace - Controller namespace (e.g., 'SnapController').
+ */
+export type StorageServiceClearAction = {
+    type: `StorageService:clear`;
+    handler: StorageService['clear'];
+};
+/**
+ * Union of all StorageService action types.
+ */
+export type StorageServiceMethodActions = StorageServiceSetItemAction | StorageServiceGetItemAction | StorageServiceRemoveItemAction | StorageServiceGetAllKeysAction | StorageServiceClearAction;
+//# sourceMappingURL=StorageService-method-action-types.d.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"StorageService-method-action-types.d.cts","sourceRoot":"","sources":["../src/StorageService-method-action-types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,6BAAyB;AAEvD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,2BAA2B,GAAG;IACxC,IAAI,EAAE,wBAAwB,CAAC;IAC/B,OAAO,EAAE,cAAc,CAAC,SAAS,CAAC,CAAC;CACpC,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,MAAM,2BAA2B,GAAG;IACxC,IAAI,EAAE,wBAAwB,CAAC;IAC/B,OAAO,EAAE,cAAc,CAAC,SAAS,CAAC,CAAC;CACpC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,8BAA8B,GAAG;IAC3C,IAAI,EAAE,2BAA2B,CAAC;IAClC,OAAO,EAAE,cAAc,CAAC,YAAY,CAAC,CAAC;CACvC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,8BAA8B,GAAG;IAC3C,IAAI,EAAE,2BAA2B,CAAC;IAClC,OAAO,EAAE,cAAc,CAAC,YAAY,CAAC,CAAC;CACvC,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,yBAAyB,GAAG;IACtC,IAAI,EAAE,sBAAsB,CAAC;IAC7B,OAAO,EAAE,cAAc,CAAC,OAAO,CAAC,CAAC;CAClC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,2BAA2B,GACnC,2BAA2B,GAC3B,2BAA2B,GAC3B,8BAA8B,GAC9B,8BAA8B,GAC9B,yBAAyB,CAAC"}

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

@@ -0,0 +1,81 @@
+/**
+ * This file is auto generated by `scripts/generate-method-action-types.ts`.
+ * Do not edit manually.
+ */
+import type { StorageService } from "./StorageService.mjs";
+/**
+ * Store large data in storage.
+ *
+ * ⚠️ **Designed for large values (100KB+), not many small ones.**
+ * Each storage operation has I/O overhead. For best performance,
+ * store one large object rather than many small key-value pairs.
+ *
+ * @example Good: Store entire cache as one value
+ * ```typescript
+ * await service.setItem('TokenList', 'cache', { '0x1': [...], '0x38': [...] });
+ * ```
+ *
+ * @example Avoid: Many small values
+ * ```typescript
+ * // ❌ Don't do this - too many small writes
+ * await service.setItem('TokenList', 'cache:0x1', [...]);
+ * await service.setItem('TokenList', 'cache:0x38', [...]);
+ * ```
+ *
+ * @param namespace - Controller namespace (e.g., 'SnapController').
+ * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').
+ * @param value - Data to store (should be 100KB+ for optimal use).
+ */
+export type StorageServiceSetItemAction = {
+    type: `StorageService:setItem`;
+    handler: StorageService['setItem'];
+};
+/**
+ * Retrieve data from storage.
+ *
+ * Returns `unknown` since there's no schema validation.
+ * Callers should validate or cast the result to the expected type.
+ *
+ * @param namespace - Controller namespace (e.g., 'SnapController').
+ * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').
+ * @returns Parsed data or null if not found. Type is `unknown` - caller must validate.
+ */
+export type StorageServiceGetItemAction = {
+    type: `StorageService:getItem`;
+    handler: StorageService['getItem'];
+};
+/**
+ * Remove data from storage.
+ *
+ * @param namespace - Controller namespace (e.g., 'SnapController').
+ * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').
+ */
+export type StorageServiceRemoveItemAction = {
+    type: `StorageService:removeItem`;
+    handler: StorageService['removeItem'];
+};
+/**
+ * Get all keys for a namespace.
+ * Delegates to storage adapter which handles filtering.
+ *
+ * @param namespace - Controller namespace (e.g., 'SnapController').
+ * @returns Array of keys (without prefix) for this namespace.
+ */
+export type StorageServiceGetAllKeysAction = {
+    type: `StorageService:getAllKeys`;
+    handler: StorageService['getAllKeys'];
+};
+/**
+ * Clear all data for a namespace.
+ *
+ * @param namespace - Controller namespace (e.g., 'SnapController').
+ */
+export type StorageServiceClearAction = {
+    type: `StorageService:clear`;
+    handler: StorageService['clear'];
+};
+/**
+ * Union of all StorageService action types.
+ */
+export type StorageServiceMethodActions = StorageServiceSetItemAction | StorageServiceGetItemAction | StorageServiceRemoveItemAction | StorageServiceGetAllKeysAction | StorageServiceClearAction;
+//# sourceMappingURL=StorageService-method-action-types.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"StorageService-method-action-types.d.mts","sourceRoot":"","sources":["../src/StorageService-method-action-types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,6BAAyB;AAEvD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,2BAA2B,GAAG;IACxC,IAAI,EAAE,wBAAwB,CAAC;IAC/B,OAAO,EAAE,cAAc,CAAC,SAAS,CAAC,CAAC;CACpC,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,MAAM,2BAA2B,GAAG;IACxC,IAAI,EAAE,wBAAwB,CAAC;IAC/B,OAAO,EAAE,cAAc,CAAC,SAAS,CAAC,CAAC;CACpC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,8BAA8B,GAAG;IAC3C,IAAI,EAAE,2BAA2B,CAAC;IAClC,OAAO,EAAE,cAAc,CAAC,YAAY,CAAC,CAAC;CACvC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,8BAA8B,GAAG;IAC3C,IAAI,EAAE,2BAA2B,CAAC;IAClC,OAAO,EAAE,cAAc,CAAC,YAAY,CAAC,CAAC;CACvC,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,yBAAyB,GAAG;IACtC,IAAI,EAAE,sBAAsB,CAAC;IAC7B,OAAO,EAAE,cAAc,CAAC,OAAO,CAAC,CAAC;CAClC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,2BAA2B,GACnC,2BAA2B,GAC3B,2BAA2B,GAC3B,8BAA8B,GAC9B,8BAA8B,GAC9B,yBAAyB,CAAC"}

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

@@ -0,0 +1,6 @@
+/**
+ * This file is auto generated by `scripts/generate-method-action-types.ts`.
+ * Do not edit manually.
+ */
+export {};
+//# sourceMappingURL=StorageService-method-action-types.mjs.map

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

@@ -0,0 +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 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 - 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 data from storage.\n *\n * Returns `unknown` since there's no schema validation.\n * Callers should validate or cast the result to the expected type.\n *\n * @param namespace - Controller namespace (e.g., 'SnapController').\n * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').\n * @returns Parsed data or null if not found. Type is `unknown` - caller must validate.\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

@@ -15,6 +15,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.StorageService = void 0;
 const InMemoryStorageAdapter_1 = require("./InMemoryStorageAdapter.cjs");
 const types_1 = require("./types.cjs");
+// === MESSENGER ===
+const MESSENGER_EXPOSED_METHODS = [
+    'setItem',
+    'getItem',
+    'removeItem',
+    'getAllKeys',
+    'clear',
+];
 /**
  * StorageService provides a platform-agnostic way for controllers to store
  * large, infrequently accessed data outside of memory/Redux state.
@@ -55,11 +63,12 @@ const types_1 = require("./types.cjs");
  *   }
  *
  *   async getSnapSourceCode(snapId: string): Promise<string | null> {
- *     return await this.messenger.call(
+ *     const result = await this.messenger.call(
  *       'StorageService:getItem',
  *       'SnapController',
  *       `${snapId}:sourceCode`,
  *     );
+ *     return result as string | null; // Caller must validate/cast
  *   }
  * }
  * ```
@@ -113,19 +122,30 @@ class StorageService {
                 'Data will be lost on restart. Provide a storage adapter for persistence.');
         }
         // Register messenger actions
-        __classPrivateFieldGet(this, _StorageService_messenger, "f").registerActionHandler(`${types_1.SERVICE_NAME}:setItem`, this.setItem.bind(this));
-        __classPrivateFieldGet(this, _StorageService_messenger, "f").registerActionHandler(`${types_1.SERVICE_NAME}:getItem`, this.getItem.bind(this));
-        __classPrivateFieldGet(this, _StorageService_messenger, "f").registerActionHandler(`${types_1.SERVICE_NAME}:removeItem`, this.removeItem.bind(this));
-        __classPrivateFieldGet(this, _StorageService_messenger, "f").registerActionHandler(`${types_1.SERVICE_NAME}:getAllKeys`, this.getAllKeys.bind(this));
-        __classPrivateFieldGet(this, _StorageService_messenger, "f").registerActionHandler(`${types_1.SERVICE_NAME}:clear`, this.clear.bind(this));
+        __classPrivateFieldGet(this, _StorageService_messenger, "f").registerMethodActionHandlers(this, MESSENGER_EXPOSED_METHODS);
     }
     /**
-     * Store data in storage.
+     * Store large data in storage.
+     *
+     * ⚠️ **Designed for large values (100KB+), not many small ones.**
+     * Each storage operation has I/O overhead. For best performance,
+     * store one large object rather than many small key-value pairs.
+     *
+     * @example Good: Store entire cache as one value
+     * ```typescript
+     * await service.setItem('TokenList', 'cache', { '0x1': [...], '0x38': [...] });
+     * ```
+     *
+     * @example Avoid: Many small values
+     * ```typescript
+     * // ❌ Don't do this - too many small writes
+     * await service.setItem('TokenList', 'cache:0x1', [...]);
+     * await service.setItem('TokenList', 'cache:0x38', [...]);
+     * ```
      *
      * @param namespace - Controller namespace (e.g., 'SnapController').
      * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').
-     * @param value - Data to store (will be JSON stringified).
-     * @template T - The type of the value being stored.
+     * @param value - Data to store (should be 100KB+ for optimal use).
      */
     async setItem(namespace, key, value) {
         // Adapter handles serialization and wrapping with metadata
@@ -138,15 +158,16 @@ class StorageService {
     /**
      * Retrieve data from storage.
      *
+     * Returns `unknown` since there's no schema validation.
+     * Callers should validate or cast the result to the expected type.
+     *
      * @param namespace - Controller namespace (e.g., 'SnapController').
      * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').
-     * @returns Parsed data or null if not found.
-     * @template T - The type of the value being retrieved.
+     * @returns Parsed data or null if not found. Type is `unknown` - caller must validate.
      */
     async getItem(namespace, key) {
         // Adapter handles deserialization and unwrapping
-        const result = await __classPrivateFieldGet(this, _StorageService_storage, "f").getItem(namespace, key);
-        return result;
+        return await __classPrivateFieldGet(this, _StorageService_storage, "f").getItem(namespace, key);
     }
     /**
      * Remove data from storage.
@@ -157,10 +178,6 @@ class StorageService {
     async removeItem(namespace, key) {
         // Adapter builds full storage key (e.g., mobile: 'storageService:namespace:key')
         await __classPrivateFieldGet(this, _StorageService_storage, "f").removeItem(namespace, key);
-        // Publish event so other controllers can react to removal
-        // Event type: StorageService:itemRemoved:namespace
-        // Payload: [key]
-        __classPrivateFieldGet(this, _StorageService_messenger, "f").publish(`${types_1.SERVICE_NAME}:itemRemoved:${namespace}`, key);
     }
     /**
      * Get all keys for a namespace.
@@ -174,7 +191,6 @@ class StorageService {
     }
     /**
      * Clear all data for a namespace.
-     * Delegates to storage adapter which handles clearing.
      *
      * @param namespace - Controller namespace (e.g., 'SnapController').
      */

package/dist/StorageService.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"StorageService.cjs","sourceRoot":"","sources":["../src/StorageService.ts"],"names":[],"mappings":"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","sourcesContent":["import { InMemoryStorageAdapter } from './InMemoryStorageAdapter';\nimport type {\n  StorageAdapter,\n  StorageServiceMessenger,\n  StorageServiceOptions,\n} from './types';\nimport { SERVICE_NAME } from './types';\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 *     return await this.messenger.call(\n *       'StorageService:getItem',\n *       'SnapController',\n *       `${snapId}:sourceCode`,\n *     );\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.registerActionHandler(\n      `${SERVICE_NAME}:setItem`,\n      this.setItem.bind(this),\n    );\n    this.#messenger.registerActionHandler(\n      `${SERVICE_NAME}:getItem`,\n      this.getItem.bind(this),\n    );\n    this.#messenger.registerActionHandler(\n      `${SERVICE_NAME}:removeItem`,\n      this.removeItem.bind(this),\n    );\n    this.#messenger.registerActionHandler(\n      `${SERVICE_NAME}:getAllKeys`,\n      this.getAllKeys.bind(this),\n    );\n    this.#messenger.registerActionHandler(\n      `${SERVICE_NAME}:clear`,\n      this.clear.bind(this),\n    );\n  }\n\n  /**\n   * Store data in storage.\n   *\n   * @param namespace - Controller namespace (e.g., 'SnapController').\n   * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').\n   * @param value - Data to store (will be JSON stringified).\n   * @template T - The type of the value being stored.\n   */\n  async setItem<T>(namespace: string, key: string, value: T): Promise<void> {\n    // Adapter handles serialization and wrapping with metadata\n    await this.#storage.setItem(namespace, key, value as never);\n\n    // Publish event so other controllers can react to changes\n    // Event type: StorageService:itemSet:namespace\n    // Payload: [value, key]\n    this.#messenger.publish(\n      `${SERVICE_NAME}:itemSet:${namespace}` as `${typeof SERVICE_NAME}:itemSet:${string}`,\n      value,\n      key,\n    );\n  }\n\n  /**\n   * Retrieve 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 data or null if not found.\n   * @template T - The type of the value being retrieved.\n   */\n  async getItem<T>(namespace: string, key: string): Promise<T | null> {\n    // Adapter handles deserialization and unwrapping\n    const result = await this.#storage.getItem(namespace, key);\n    return result as T | null;\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    // Publish event so other controllers can react to removal\n    // Event type: StorageService:itemRemoved:namespace\n    // Payload: [key]\n    this.#messenger.publish(\n      `${SERVICE_NAME}:itemRemoved:${namespace}` as `${typeof SERVICE_NAME}:itemRemoved:${string}`,\n      key,\n    );\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   * Delegates to storage adapter which handles clearing.\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":";;;;;;;;;;;;;;;AAAA,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,KAAc;QAC1D,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,KAAK,EACL,GAAG,CACJ,CAAC;IACJ,CAAC;IAED;;;;;;;;;OASG;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;AA9HD,wCA8HC","sourcesContent":["import { 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 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 - Data to store (should be 100KB+ for optimal use).\n   */\n  async setItem(namespace: string, key: string, value: unknown): 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: [value, key]\n    this.#messenger.publish(\n      `${SERVICE_NAME}:itemSet:${namespace}` as const,\n      value,\n      key,\n    );\n  }\n\n  /**\n   * Retrieve data from storage.\n   *\n   * Returns `unknown` since there's no schema validation.\n   * Callers should validate or cast the result to the expected type.\n   *\n   * @param namespace - Controller namespace (e.g., 'SnapController').\n   * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').\n   * @returns Parsed data or null if not found. Type is `unknown` - caller must validate.\n   */\n  async getItem(namespace: string, key: string): Promise<unknown> {\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

@@ -40,11 +40,12 @@ import { SERVICE_NAME } from "./types.cjs";
  *   }
  *
  *   async getSnapSourceCode(snapId: string): Promise<string | null> {
- *     return await this.messenger.call(
+ *     const result = await this.messenger.call(
  *       'StorageService:getItem',
  *       'SnapController',
  *       `${snapId}:sourceCode`,
  *     );
+ *     return result as string | null; // Caller must validate/cast
  *   }
  * }
  * ```
@@ -87,23 +88,40 @@ export declare class StorageService {
      */
     constructor({ messenger, storage }: StorageServiceOptions);
     /**
-     * Store data in storage.
+     * Store large data in storage.
+     *
+     * ⚠️ **Designed for large values (100KB+), not many small ones.**
+     * Each storage operation has I/O overhead. For best performance,
+     * store one large object rather than many small key-value pairs.
+     *
+     * @example Good: Store entire cache as one value
+     * ```typescript
+     * await service.setItem('TokenList', 'cache', { '0x1': [...], '0x38': [...] });
+     * ```
+     *
+     * @example Avoid: Many small values
+     * ```typescript
+     * // ❌ Don't do this - too many small writes
+     * await service.setItem('TokenList', 'cache:0x1', [...]);
+     * await service.setItem('TokenList', 'cache:0x38', [...]);
+     * ```
      *
      * @param namespace - Controller namespace (e.g., 'SnapController').
      * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').
-     * @param value - Data to store (will be JSON stringified).
-     * @template T - The type of the value being stored.
+     * @param value - Data to store (should be 100KB+ for optimal use).
      */
-    setItem<T>(namespace: string, key: string, value: T): Promise<void>;
+    setItem(namespace: string, key: string, value: unknown): Promise<void>;
     /**
      * Retrieve data from storage.
      *
+     * Returns `unknown` since there's no schema validation.
+     * Callers should validate or cast the result to the expected type.
+     *
      * @param namespace - Controller namespace (e.g., 'SnapController').
      * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').
-     * @returns Parsed data or null if not found.
-     * @template T - The type of the value being retrieved.
+     * @returns Parsed data or null if not found. Type is `unknown` - caller must validate.
      */
-    getItem<T>(namespace: string, key: string): Promise<T | null>;
+    getItem(namespace: string, key: string): Promise<unknown>;
     /**
      * Remove data from storage.
      *
@@ -121,7 +139,6 @@ export declare class StorageService {
     getAllKeys(namespace: string): Promise<string[]>;
     /**
      * Clear all data for a namespace.
-     * Delegates to storage adapter which handles clearing.
      *
      * @param namespace - Controller namespace (e.g., 'SnapController').
      */

package/dist/StorageService.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"StorageService.d.cts","sourceRoot":"","sources":["../src/StorageService.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAGV,qBAAqB,EACtB,oBAAgB;AACjB,OAAO,EAAE,YAAY,EAAE,oBAAgB;AAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AACH,qBAAa,cAAc;;IACzB;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,OAAO,YAAY,CAAC;IAYnC;;;;;;;OAOG;gBACS,EAAE,SAAS,EAAE,OAAO,EAAE,EAAE,qBAAqB;IAoCzD;;;;;;;OAOG;IACG,OAAO,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAczE;;;;;;;OAOG;IACG,OAAO,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAMnE;;;;;OAKG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAa/D;;;;;;OAMG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAItD;;;;;OAKG;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":"AACA,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,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAc5E;;;;;;;;;OASG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAK/D;;;;;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

@@ -40,11 +40,12 @@ import { SERVICE_NAME } from "./types.mjs";
  *   }
  *
  *   async getSnapSourceCode(snapId: string): Promise<string | null> {
- *     return await this.messenger.call(
+ *     const result = await this.messenger.call(
  *       'StorageService:getItem',
  *       'SnapController',
  *       `${snapId}:sourceCode`,
  *     );
+ *     return result as string | null; // Caller must validate/cast
  *   }
  * }
  * ```
@@ -87,23 +88,40 @@ export declare class StorageService {
      */
     constructor({ messenger, storage }: StorageServiceOptions);
     /**
-     * Store data in storage.
+     * Store large data in storage.
+     *
+     * ⚠️ **Designed for large values (100KB+), not many small ones.**
+     * Each storage operation has I/O overhead. For best performance,
+     * store one large object rather than many small key-value pairs.
+     *
+     * @example Good: Store entire cache as one value
+     * ```typescript
+     * await service.setItem('TokenList', 'cache', { '0x1': [...], '0x38': [...] });
+     * ```
+     *
+     * @example Avoid: Many small values
+     * ```typescript
+     * // ❌ Don't do this - too many small writes
+     * await service.setItem('TokenList', 'cache:0x1', [...]);
+     * await service.setItem('TokenList', 'cache:0x38', [...]);
+     * ```
      *
      * @param namespace - Controller namespace (e.g., 'SnapController').
      * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').
-     * @param value - Data to store (will be JSON stringified).
-     * @template T - The type of the value being stored.
+     * @param value - Data to store (should be 100KB+ for optimal use).
      */
-    setItem<T>(namespace: string, key: string, value: T): Promise<void>;
+    setItem(namespace: string, key: string, value: unknown): Promise<void>;
     /**
      * Retrieve data from storage.
      *
+     * Returns `unknown` since there's no schema validation.
+     * Callers should validate or cast the result to the expected type.
+     *
      * @param namespace - Controller namespace (e.g., 'SnapController').
      * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').
-     * @returns Parsed data or null if not found.
-     * @template T - The type of the value being retrieved.
+     * @returns Parsed data or null if not found. Type is `unknown` - caller must validate.
      */
-    getItem<T>(namespace: string, key: string): Promise<T | null>;
+    getItem(namespace: string, key: string): Promise<unknown>;
     /**
      * Remove data from storage.
      *
@@ -121,7 +139,6 @@ export declare class StorageService {
     getAllKeys(namespace: string): Promise<string[]>;
     /**
      * Clear all data for a namespace.
-     * Delegates to storage adapter which handles clearing.
      *
      * @param namespace - Controller namespace (e.g., 'SnapController').
      */

package/dist/StorageService.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"StorageService.d.mts","sourceRoot":"","sources":["../src/StorageService.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAGV,qBAAqB,EACtB,oBAAgB;AACjB,OAAO,EAAE,YAAY,EAAE,oBAAgB;AAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AACH,qBAAa,cAAc;;IACzB;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,OAAO,YAAY,CAAC;IAYnC;;;;;;;OAOG;gBACS,EAAE,SAAS,EAAE,OAAO,EAAE,EAAE,qBAAqB;IAoCzD;;;;;;;OAOG;IACG,OAAO,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAczE;;;;;;;OAOG;IACG,OAAO,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAMnE;;;;;OAKG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAa/D;;;;;;OAMG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAItD;;;;;OAKG;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":"AACA,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,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAc5E;;;;;;;;;OASG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAK/D;;;;;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

@@ -12,6 +12,14 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
 var _StorageService_messenger, _StorageService_storage;
 import { InMemoryStorageAdapter } from "./InMemoryStorageAdapter.mjs";
 import { SERVICE_NAME } from "./types.mjs";
+// === MESSENGER ===
+const MESSENGER_EXPOSED_METHODS = [
+    'setItem',
+    'getItem',
+    'removeItem',
+    'getAllKeys',
+    'clear',
+];
 /**
  * StorageService provides a platform-agnostic way for controllers to store
  * large, infrequently accessed data outside of memory/Redux state.
@@ -52,11 +60,12 @@ import { SERVICE_NAME } from "./types.mjs";
  *   }
  *
  *   async getSnapSourceCode(snapId: string): Promise<string | null> {
- *     return await this.messenger.call(
+ *     const result = await this.messenger.call(
  *       'StorageService:getItem',
  *       'SnapController',
  *       `${snapId}:sourceCode`,
  *     );
+ *     return result as string | null; // Caller must validate/cast
  *   }
  * }
  * ```
@@ -110,19 +119,30 @@ export class StorageService {
                 'Data will be lost on restart. Provide a storage adapter for persistence.');
         }
         // Register messenger actions
-        __classPrivateFieldGet(this, _StorageService_messenger, "f").registerActionHandler(`${SERVICE_NAME}:setItem`, this.setItem.bind(this));
-        __classPrivateFieldGet(this, _StorageService_messenger, "f").registerActionHandler(`${SERVICE_NAME}:getItem`, this.getItem.bind(this));
-        __classPrivateFieldGet(this, _StorageService_messenger, "f").registerActionHandler(`${SERVICE_NAME}:removeItem`, this.removeItem.bind(this));
-        __classPrivateFieldGet(this, _StorageService_messenger, "f").registerActionHandler(`${SERVICE_NAME}:getAllKeys`, this.getAllKeys.bind(this));
-        __classPrivateFieldGet(this, _StorageService_messenger, "f").registerActionHandler(`${SERVICE_NAME}:clear`, this.clear.bind(this));
+        __classPrivateFieldGet(this, _StorageService_messenger, "f").registerMethodActionHandlers(this, MESSENGER_EXPOSED_METHODS);
     }
     /**
-     * Store data in storage.
+     * Store large data in storage.
+     *
+     * ⚠️ **Designed for large values (100KB+), not many small ones.**
+     * Each storage operation has I/O overhead. For best performance,
+     * store one large object rather than many small key-value pairs.
+     *
+     * @example Good: Store entire cache as one value
+     * ```typescript
+     * await service.setItem('TokenList', 'cache', { '0x1': [...], '0x38': [...] });
+     * ```
+     *
+     * @example Avoid: Many small values
+     * ```typescript
+     * // ❌ Don't do this - too many small writes
+     * await service.setItem('TokenList', 'cache:0x1', [...]);
+     * await service.setItem('TokenList', 'cache:0x38', [...]);
+     * ```
      *
      * @param namespace - Controller namespace (e.g., 'SnapController').
      * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').
-     * @param value - Data to store (will be JSON stringified).
-     * @template T - The type of the value being stored.
+     * @param value - Data to store (should be 100KB+ for optimal use).
      */
     async setItem(namespace, key, value) {
         // Adapter handles serialization and wrapping with metadata
@@ -135,15 +155,16 @@ export class StorageService {
     /**
      * Retrieve data from storage.
      *
+     * Returns `unknown` since there's no schema validation.
+     * Callers should validate or cast the result to the expected type.
+     *
      * @param namespace - Controller namespace (e.g., 'SnapController').
      * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').
-     * @returns Parsed data or null if not found.
-     * @template T - The type of the value being retrieved.
+     * @returns Parsed data or null if not found. Type is `unknown` - caller must validate.
      */
     async getItem(namespace, key) {
         // Adapter handles deserialization and unwrapping
-        const result = await __classPrivateFieldGet(this, _StorageService_storage, "f").getItem(namespace, key);
-        return result;
+        return await __classPrivateFieldGet(this, _StorageService_storage, "f").getItem(namespace, key);
     }
     /**
      * Remove data from storage.
@@ -154,10 +175,6 @@ export class StorageService {
     async removeItem(namespace, key) {
         // Adapter builds full storage key (e.g., mobile: 'storageService:namespace:key')
         await __classPrivateFieldGet(this, _StorageService_storage, "f").removeItem(namespace, key);
-        // Publish event so other controllers can react to removal
-        // Event type: StorageService:itemRemoved:namespace
-        // Payload: [key]
-        __classPrivateFieldGet(this, _StorageService_messenger, "f").publish(`${SERVICE_NAME}:itemRemoved:${namespace}`, key);
     }
     /**
      * Get all keys for a namespace.
@@ -171,7 +188,6 @@ export class StorageService {
     }
     /**
      * Clear all data for a namespace.
-     * Delegates to storage adapter which handles clearing.
      *
      * @param namespace - Controller namespace (e.g., 'SnapController').
      */