docs(storage-service): add JSDoc guidance for large value storage

- Add warnings that service is designed for large values (100KB+)
- Add examples of good vs bad usage patterns
- Discourage many small key-value pairs in favor of single large objects

packages/storage-service/src/StorageService.ts

@@ -138,11 +138,27 @@ export class StorageService {
   }
 
   /**
-   * 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).
+   * @param value - Data to store (should be 100KB+ for optimal use).
    * @template T - The type of the value being stored.
    */
   async setItem<T>(namespace: string, key: string, value: T): Promise<void> {

packages/storage-service/src/types.ts

@@ -5,6 +5,18 @@ import type { Messenger } from '@metamask/messenger';
  * Each client (mobile, extension) implements this interface
  * with their preferred storage mechanism.
  *
+ * ⚠️ **Designed for large, infrequently accessed data (100KB+)**
+ *
+ * ✅ **Use for:**
+ * - Snap source code (~6 MB per snap)
+ * - Token metadata caches (~4 MB)
+ * - Large API response caches
+ *
+ * ❌ **Avoid for:**
+ * - Small values (< 10 KB) - use controller state instead
+ * - Frequently accessed data - use controller state instead
+ * - Many small key-value pairs - use a single large object instead
+ *
  * @example Mobile implementation using FilesystemStorage
  * @example Extension implementation using IndexedDB
  * @example Tests using InMemoryStorageAdapter
@@ -21,7 +33,13 @@ export type StorageAdapter = {
   getItem(namespace: string, key: string): Promise<unknown>;
 
   /**
-   * Store an item in storage.
+   * Store a large value in storage.
+   *
+   * ⚠️ **Store large values, 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
+   * - Minimum recommended size: 100 KB per value
+   *
    * Adapter is responsible for:
    * - Building the full storage key
    * - Wrapping value with metadata (timestamp, etc.)