refactor(storage-service): use Json type instead of unknown

- Replace unknown with Json type from @metamask/utils for type safety
- Add @metamask/utils as dependency (required for public API types)
- Remove StoredDataWrapper - just stringify/parse values directly
- Update StorageAdapter interface, StorageService, and InMemoryStorageAdapter

packages/storage-service/package.json

@@ -48,7 +48,8 @@
     "test:watch": "NODE_OPTIONS=--experimental-vm-modules jest --watch"
   },
   "dependencies": {
-    "@metamask/messenger": "^0.3.0"
+    "@metamask/messenger": "^0.3.0",
+    "@metamask/utils": "^11.8.1"
   },
   "devDependencies": {
     "@metamask/auto-changelog": "^3.4.4",

packages/storage-service/src/InMemoryStorageAdapter.ts

@@ -1,17 +1,8 @@
+import type { Json } from '@metamask/utils';
+
 import type { StorageAdapter } from './types';
 import { STORAGE_KEY_PREFIX } from './types';
 
-/**
- * Wrapper for stored data with metadata.
- * Each adapter can define its own wrapper structure.
- */
-type StoredDataWrapper<T = unknown> = {
-  /** Timestamp when data was stored (milliseconds since epoch). */
-  timestamp: number;
-  /** The actual data being stored. */
-  data: T;
-};
-
 /**
  * In-memory storage adapter (default fallback).
  * Implements the {@link StorageAdapter} interface using a Map.
@@ -30,8 +21,8 @@ type StoredDataWrapper<T = unknown> = {
  * @example
  * ```typescript
  * const adapter = new InMemoryStorageAdapter();
- * await adapter.setItem('key', 'value');
- * const value = await adapter.getItem('key'); // Returns 'value'
+ * await adapter.setItem('SnapController', 'snap-id:sourceCode', 'const x = 1;');
+ * const value = await adapter.getItem('SnapController', 'snap-id:sourceCode'); // 'const x = 1;'
  * // After restart: data is lost
  * ```
  */
@@ -51,13 +42,13 @@ export class InMemoryStorageAdapter implements StorageAdapter {
 
   /**
    * Retrieve an item from in-memory storage.
-   * Deserializes and unwraps the stored data.
+   * Deserializes JSON data from storage.
    *
    * @param namespace - The controller namespace.
    * @param key - The data key.
-   * @returns The unwrapped data, or null if not found.
+   * @returns The parsed JSON data, or null if not found.
    */
-  async getItem(namespace: string, key: string): Promise<unknown> {
+  async getItem(namespace: string, key: string): Promise<Json | null> {
     const fullKey = `${STORAGE_KEY_PREFIX}${namespace}:${key}`;
     const serialized = this.#storage.get(fullKey);
 
@@ -66,8 +57,7 @@ export class InMemoryStorageAdapter implements StorageAdapter {
     }
 
     try {
-      const wrapper: StoredDataWrapper = JSON.parse(serialized);
-      return wrapper.data;
+      return JSON.parse(serialized) as Json;
     } catch (error) {
       // istanbul ignore next - defensive error handling for corrupted data
       console.error(`Failed to parse stored data for ${fullKey}:`, error);
@@ -78,19 +68,15 @@ export class InMemoryStorageAdapter implements StorageAdapter {
 
   /**
    * Store an item in in-memory storage.
-   * Wraps with metadata and serializes to string.
+   * Serializes JSON data to string.
    *
    * @param namespace - The controller namespace.
    * @param key - The data key.
-   * @param value - The value to store (will be wrapped and serialized).
+   * @param value - The JSON value to store.
    */
-  async setItem(namespace: string, key: string, value: unknown): Promise<void> {
+  async setItem(namespace: string, key: string, value: Json): Promise<void> {
     const fullKey = `${STORAGE_KEY_PREFIX}${namespace}:${key}`;
-    const wrapper: StoredDataWrapper = {
-      timestamp: Date.now(),
-      data: value,
-    };
-    this.#storage.set(fullKey, JSON.stringify(wrapper));
+    this.#storage.set(fullKey, JSON.stringify(value));
   }
 
   /**

packages/storage-service/src/StorageService-method-action-types.ts

@@ -6,7 +6,7 @@
 import type { StorageService } from './StorageService';
 
 /**
- * Store large data in storage.
+ * Store large JSON data in storage.
  *
  * ⚠️ **Designed for large values (100KB+), not many small ones.**
  * Each storage operation has I/O overhead. For best performance,
@@ -26,22 +26,19 @@ import type { StorageService } from './StorageService';
  *
  * @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).
+ * @param value - JSON 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.
+ * Retrieve JSON data from storage.
  *
  * @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.
+ * @returns Parsed JSON data or null if not found.
  */
 export type StorageServiceGetItemAction = {
   type: `StorageService:getItem`;

packages/storage-service/src/StorageService.ts

@@ -1,3 +1,5 @@
+import type { Json } from '@metamask/utils';
+
 import { InMemoryStorageAdapter } from './InMemoryStorageAdapter';
 import type {
   StorageAdapter,
@@ -133,7 +135,7 @@ export class StorageService {
   }
 
   /**
-   * Store large data in storage.
+   * Store large JSON data in storage.
    *
    * ⚠️ **Designed for large values (100KB+), not many small ones.**
    * Each storage operation has I/O overhead. For best performance,
@@ -153,9 +155,9 @@ export class StorageService {
    *
    * @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).
+   * @param value - JSON data to store (should be 100KB+ for optimal use).
    */
-  async setItem(namespace: string, key: string, value: unknown): Promise<void> {
+  async setItem(namespace: string, key: string, value: Json): Promise<void> {
     // Adapter handles serialization and wrapping with metadata
     await this.#storage.setItem(namespace, key, value);
 
@@ -170,16 +172,13 @@ 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.
+   * Retrieve JSON data from storage.
    *
    * @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.
+   * @returns Parsed JSON data or null if not found.
    */
-  async getItem(namespace: string, key: string): Promise<unknown> {
+  async getItem(namespace: string, key: string): Promise<Json | null> {
     // Adapter handles deserialization and unwrapping
     return await this.#storage.getItem(namespace, key);
   }

packages/storage-service/src/types.ts

@@ -1,4 +1,5 @@
 import type { Messenger } from '@metamask/messenger';
+import type { Json } from '@metamask/utils';
 
 import type { StorageServiceMethodActions } from './StorageService-method-action-types';
 
@@ -30,12 +31,12 @@ export type StorageAdapter = {
    *
    * @param namespace - The controller namespace (e.g., 'SnapController').
    * @param key - The data key (e.g., 'snap-id:sourceCode').
-   * @returns The value as a string, or null if not found.
+   * @returns The JSON value, or null if not found.
    */
-  getItem(namespace: string, key: string): Promise<unknown>;
+  getItem(namespace: string, key: string): Promise<Json | null>;
 
   /**
-   * Store a large value in storage.
+   * Store a large JSON value in storage.
    *
    * ⚠️ **Store large values, not many small ones.**
    * Each storage operation has I/O overhead. For best performance:
@@ -44,14 +45,13 @@ export type StorageAdapter = {
    *
    * Adapter is responsible for:
    * - Building the full storage key
-   * - Wrapping value with metadata (timestamp, etc.)
    * - Serializing to string (JSON.stringify)
    *
    * @param namespace - The controller namespace (e.g., 'SnapController').
    * @param key - The data key (e.g., 'snap-id:sourceCode').
-   * @param value - The value to store (will be wrapped and serialized by adapter).
+   * @param value - The JSON value to store.
    */
-  setItem(namespace: string, key: string, value: unknown): Promise<void>;
+  setItem(namespace: string, key: string, value: Json): Promise<void>;
 
   /**
    * Remove an item from storage.
@@ -138,7 +138,7 @@ export type StorageServiceActions = StorageServiceMethodActions;
  */
 export type StorageServiceItemSetEvent = {
   type: `${typeof SERVICE_NAME}:itemSet:${string}`;
-  payload: [key: string, value: unknown];
+  payload: [key: string, value: Json];
 };
 
 /**

yarn.lock

@@ -4920,6 +4920,7 @@ __metadata:
   dependencies:
     "@metamask/auto-changelog": "npm:^3.4.4"
     "@metamask/messenger": "npm:^0.3.0"
+    "@metamask/utils": "npm:^11.8.1"
     "@ts-bridge/cli": "npm:^0.6.4"
     "@types/jest": "npm:^27.4.1"
     deepmerge: "npm:^4.2.2"