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

package/dist/StorageService.mjs

@@ -0,0 +1,199 @@
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+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.
+ *
+ * **Use cases:**
+ * - Snap source code (6+ MB that's rarely accessed)
+ * - Token metadata caches (4+ MB of cached data)
+ * - Large cached responses from APIs
+ * - Any data > 100 KB that's not frequently accessed
+ *
+ * **Benefits:**
+ * - Reduces memory usage (data stays on disk)
+ * - Faster Redux persist (less data to serialize)
+ * - Faster app startup (less data to parse)
+ * - Lazy loading (data loaded only when needed)
+ *
+ * **Platform Support:**
+ * - Mobile: FilesystemStorage adapter
+ * - Extension: IndexedDB adapter
+ * - Tests/Dev: InMemoryStorageAdapter (default)
+ *
+ * @example Using the service via messenger
+ *
+ * ```typescript
+ * // In a controller
+ * type AllowedActions =
+ *   | StorageServiceSetItemAction
+ *   | StorageServiceGetItemAction;
+ *
+ * class SnapController extends BaseController {
+ *   async storeSnapSourceCode(snapId: string, sourceCode: string) {
+ *     await this.messenger.call(
+ *       'StorageService:setItem',
+ *       'SnapController',
+ *       `${snapId}:sourceCode`,
+ *       sourceCode,
+ *     );
+ *   }
+ *
+ *   async getSnapSourceCode(snapId: string): Promise<string | null> {
+ *     const result = await this.messenger.call(
+ *       'StorageService:getItem',
+ *       'SnapController',
+ *       `${snapId}:sourceCode`,
+ *     );
+ *     return result as string | null; // Caller must validate/cast
+ *   }
+ * }
+ * ```
+ *
+ * @example Initializing in a client
+ *
+ * ```typescript
+ * // Mobile
+ * const service = new StorageService({
+ *   messenger: storageServiceMessenger,
+ *   storage: filesystemStorageAdapter, // Platform-specific
+ * });
+ *
+ * // Extension
+ * const service = new StorageService({
+ *   messenger: storageServiceMessenger,
+ *   storage: indexedDBAdapter, // Platform-specific
+ * });
+ *
+ * // Tests (uses in-memory by default)
+ * const service = new StorageService({
+ *   messenger: storageServiceMessenger,
+ *   // No storage - uses InMemoryStorageAdapter
+ * });
+ * ```
+ */
+export class StorageService {
+    /**
+     * Constructs a new StorageService.
+     *
+     * @param options - The options.
+     * @param options.messenger - The messenger suited for this service.
+     * @param options.storage - Storage adapter for persisting data.
+     * If not provided, uses InMemoryStorageAdapter (data lost on restart).
+     */
+    constructor({ messenger, storage }) {
+        /**
+         * The messenger suited for this service.
+         */
+        _StorageService_messenger.set(this, void 0);
+        /**
+         * The storage adapter for persisting data.
+         */
+        _StorageService_storage.set(this, void 0);
+        this.name = SERVICE_NAME;
+        __classPrivateFieldSet(this, _StorageService_messenger, messenger, "f");
+        __classPrivateFieldSet(this, _StorageService_storage, storage ?? new InMemoryStorageAdapter(), "f");
+        // Warn if using in-memory storage (data won't persist)
+        if (!storage) {
+            console.warn(`${SERVICE_NAME}: No storage adapter provided. Using in-memory storage. ` +
+                'Data will be lost on restart. Provide a storage adapter for persistence.');
+        }
+        // Register messenger actions
+        __classPrivateFieldGet(this, _StorageService_messenger, "f").registerMethodActionHandlers(this, MESSENGER_EXPOSED_METHODS);
+    }
+    /**
+     * 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).
+     */
+    async setItem(namespace, key, value) {
+        // Adapter handles serialization and wrapping with metadata
+        await __classPrivateFieldGet(this, _StorageService_storage, "f").setItem(namespace, key, value);
+        // Publish event so other controllers can react to changes
+        // Event type: StorageService:itemSet:namespace
+        // Payload: [value, key]
+        __classPrivateFieldGet(this, _StorageService_messenger, "f").publish(`${SERVICE_NAME}:itemSet:${namespace}`, value, key);
+    }
+    /**
+     * 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.
+     */
+    async getItem(namespace, key) {
+        // Adapter handles deserialization and unwrapping
+        return await __classPrivateFieldGet(this, _StorageService_storage, "f").getItem(namespace, key);
+    }
+    /**
+     * Remove data from storage.
+     *
+     * @param namespace - Controller namespace (e.g., 'SnapController').
+     * @param key - Storage key (e.g., 'npm:@metamask/example-snap:sourceCode').
+     */
+    async removeItem(namespace, key) {
+        // Adapter builds full storage key (e.g., mobile: 'storageService:namespace:key')
+        await __classPrivateFieldGet(this, _StorageService_storage, "f").removeItem(namespace, key);
+    }
+    /**
+     * 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.
+     */
+    async getAllKeys(namespace) {
+        return await __classPrivateFieldGet(this, _StorageService_storage, "f").getAllKeys(namespace);
+    }
+    /**
+     * Clear all data for a namespace.
+     *
+     * @param namespace - Controller namespace (e.g., 'SnapController').
+     */
+    async clear(namespace) {
+        await __classPrivateFieldGet(this, _StorageService_storage, "f").clear(namespace);
+    }
+}
+_StorageService_messenger = new WeakMap(), _StorageService_storage = new WeakMap();
+//# sourceMappingURL=StorageService.mjs.map

package/dist/StorageService.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"StorageService.mjs","sourceRoot":"","sources":["../src/StorageService.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,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,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,YAAY,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","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/index.cjs

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STORAGE_KEY_PREFIX = exports.SERVICE_NAME = exports.InMemoryStorageAdapter = exports.StorageService = void 0;
+// Export service class
+var StorageService_1 = require("./StorageService.cjs");
+Object.defineProperty(exports, "StorageService", { enumerable: true, get: function () { return StorageService_1.StorageService; } });
+// Export adapters
+var InMemoryStorageAdapter_1 = require("./InMemoryStorageAdapter.cjs");
+Object.defineProperty(exports, "InMemoryStorageAdapter", { enumerable: true, get: function () { return InMemoryStorageAdapter_1.InMemoryStorageAdapter; } });
+// Export service name and storage key prefix constants
+var types_1 = require("./types.cjs");
+Object.defineProperty(exports, "SERVICE_NAME", { enumerable: true, get: function () { return types_1.SERVICE_NAME; } });
+Object.defineProperty(exports, "STORAGE_KEY_PREFIX", { enumerable: true, get: function () { return types_1.STORAGE_KEY_PREFIX; } });
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +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"]}

package/dist/index.d.cts

@@ -0,0 +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 { 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

@@ -0,0 +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"}

package/dist/index.d.mts

@@ -0,0 +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 { 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

@@ -0,0 +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"}

package/dist/index.mjs

@@ -0,0 +1,7 @@
+// Export service class
+export { StorageService } from "./StorageService.mjs";
+// Export adapters
+export { InMemoryStorageAdapter } from "./InMemoryStorageAdapter.mjs";
+// Export service name and storage key prefix constants
+export { SERVICE_NAME, STORAGE_KEY_PREFIX } from "./types.mjs";
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +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"]}

package/dist/types.cjs

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STORAGE_KEY_PREFIX = exports.SERVICE_NAME = void 0;
+// Service name constant
+exports.SERVICE_NAME = 'StorageService';
+/**
+ * Storage key prefix for all keys managed by StorageService.
+ * Keys are formatted as: {STORAGE_KEY_PREFIX}{namespace}:{key}
+ * Example: 'storageService:SnapController:snap-id:sourceCode'
+ */
+exports.STORAGE_KEY_PREFIX = 'storageService:';
+//# sourceMappingURL=types.cjs.map

package/dist/types.cjs.map

@@ -0,0 +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';\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 value as a string, or null if not found.\n   */\n  getItem(namespace: string, key: string): Promise<unknown>;\n\n  /**\n   * Store a large 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   * - Wrapping value with metadata (timestamp, etc.)\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 value to store (will be wrapped and serialized by adapter).\n   */\n  setItem(namespace: string, key: string, value: unknown): 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', (value, key) => {\n *   // value = the data that was set\n *   // key = 'cache:0x1', 'cache:0x38', etc.\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: [value: unknown, key: string];\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

@@ -0,0 +1,148 @@
+import type { Messenger } from "@metamask/messenger";
+import type { StorageServiceMethodActions } from "./StorageService-method-action-types.cjs";
+/**
+ * Platform-agnostic storage adapter interface.
+ * 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
+ */
+export type StorageAdapter = {
+    /**
+     * Retrieve an item from storage.
+     * Adapter is responsible for building the full storage key.
+     *
+     * @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.
+     */
+    getItem(namespace: string, key: string): Promise<unknown>;
+    /**
+     * 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.)
+     * - 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).
+     */
+    setItem(namespace: string, key: string, value: unknown): Promise<void>;
+    /**
+     * Remove an item from storage.
+     * Adapter is responsible for building the full storage key.
+     *
+     * @param namespace - The controller namespace (e.g., 'SnapController').
+     * @param key - The data key (e.g., 'snap-id:sourceCode').
+     */
+    removeItem(namespace: string, key: string): Promise<void>;
+    /**
+     * Get all keys for a specific namespace.
+     * Should return keys without the 'storage:namespace:' prefix.
+     *
+     * Adapter is responsible for:
+     * - Filtering keys by prefix: 'storage:{namespace}:'
+     * - Stripping the prefix from returned keys
+     * - Returning only the key portion after the prefix
+     *
+     * @param namespace - The namespace to get keys for (e.g., 'SnapController').
+     * @returns Array of keys without prefix (e.g., ['snap1:sourceCode', 'snap2:sourceCode']).
+     */
+    getAllKeys(namespace: string): Promise<string[]>;
+    /**
+     * Clear all items for a specific namespace.
+     *
+     * Adapter is responsible for:
+     * - Finding all keys with prefix: 'storageService:{namespace}:'
+     * - Removing all matching keys
+     *
+     * @param namespace - The namespace to clear (e.g., 'SnapController').
+     */
+    clear(namespace: string): Promise<void>;
+};
+/**
+ * Options for constructing a {@link StorageService}.
+ */
+export type StorageServiceOptions = {
+    /**
+     * The messenger suited for this service.
+     */
+    messenger: StorageServiceMessenger;
+    /**
+     * Storage adapter for persisting data.
+     * If not provided, uses in-memory storage (data lost on restart).
+     * Production clients MUST provide a persistent storage adapter.
+     */
+    storage?: StorageAdapter;
+};
+export declare const SERVICE_NAME = "StorageService";
+/**
+ * Storage key prefix for all keys managed by StorageService.
+ * Keys are formatted as: {STORAGE_KEY_PREFIX}{namespace}:{key}
+ * Example: 'storageService:SnapController:snap-id:sourceCode'
+ */
+export declare const STORAGE_KEY_PREFIX = "storageService:";
+/**
+ * All actions that {@link StorageService} exposes to other consumers.
+ * Action types are auto-generated from the service methods.
+ */
+export type StorageServiceActions = StorageServiceMethodActions;
+/**
+ * Event published when a storage item is set.
+ * Event type includes namespace only, key passed in payload.
+ *
+ * @example
+ * Subscribe to all changes in TokenListController:
+ * messenger.subscribe('StorageService:itemSet:TokenListController', (value, key) => {
+ *   // value = the data that was set
+ *   // key = 'cache:0x1', 'cache:0x38', etc.
+ *   if (key.startsWith('cache:')) {
+ *     const chainId = key.replace('cache:', '');
+ *     // React to cache change for specific chain
+ *   }
+ * });
+ */
+export type StorageServiceItemSetEvent = {
+    type: `${typeof SERVICE_NAME}:itemSet:${string}`;
+    payload: [value: unknown, key: string];
+};
+/**
+ * All events that {@link StorageService} publishes.
+ */
+export type StorageServiceEvents = StorageServiceItemSetEvent;
+/**
+ * Actions from other messengers that {@link StorageService} calls.
+ */
+type AllowedActions = never;
+/**
+ * Events from other messengers that {@link StorageService} subscribes to.
+ */
+type AllowedEvents = never;
+/**
+ * The messenger restricted to actions and events that
+ * {@link StorageService} needs to access.
+ */
+export type StorageServiceMessenger = Messenger<typeof SERVICE_NAME, StorageServiceActions | AllowedActions, StorageServiceEvents | AllowedEvents>;
+export {};
+//# sourceMappingURL=types.d.cts.map

package/dist/types.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.cts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,4BAA4B;AAErD,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,OAAO,CAAC,CAAC;IAE1D;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvE;;;;;;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,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC;CACxC,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

@@ -0,0 +1,148 @@
+import type { Messenger } from "@metamask/messenger";
+import type { StorageServiceMethodActions } from "./StorageService-method-action-types.mjs";
+/**
+ * Platform-agnostic storage adapter interface.
+ * 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
+ */
+export type StorageAdapter = {
+    /**
+     * Retrieve an item from storage.
+     * Adapter is responsible for building the full storage key.
+     *
+     * @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.
+     */
+    getItem(namespace: string, key: string): Promise<unknown>;
+    /**
+     * 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.)
+     * - 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).
+     */
+    setItem(namespace: string, key: string, value: unknown): Promise<void>;
+    /**
+     * Remove an item from storage.
+     * Adapter is responsible for building the full storage key.
+     *
+     * @param namespace - The controller namespace (e.g., 'SnapController').
+     * @param key - The data key (e.g., 'snap-id:sourceCode').
+     */
+    removeItem(namespace: string, key: string): Promise<void>;
+    /**
+     * Get all keys for a specific namespace.
+     * Should return keys without the 'storage:namespace:' prefix.
+     *
+     * Adapter is responsible for:
+     * - Filtering keys by prefix: 'storage:{namespace}:'
+     * - Stripping the prefix from returned keys
+     * - Returning only the key portion after the prefix
+     *
+     * @param namespace - The namespace to get keys for (e.g., 'SnapController').
+     * @returns Array of keys without prefix (e.g., ['snap1:sourceCode', 'snap2:sourceCode']).
+     */
+    getAllKeys(namespace: string): Promise<string[]>;
+    /**
+     * Clear all items for a specific namespace.
+     *
+     * Adapter is responsible for:
+     * - Finding all keys with prefix: 'storageService:{namespace}:'
+     * - Removing all matching keys
+     *
+     * @param namespace - The namespace to clear (e.g., 'SnapController').
+     */
+    clear(namespace: string): Promise<void>;
+};
+/**
+ * Options for constructing a {@link StorageService}.
+ */
+export type StorageServiceOptions = {
+    /**
+     * The messenger suited for this service.
+     */
+    messenger: StorageServiceMessenger;
+    /**
+     * Storage adapter for persisting data.
+     * If not provided, uses in-memory storage (data lost on restart).
+     * Production clients MUST provide a persistent storage adapter.
+     */
+    storage?: StorageAdapter;
+};
+export declare const SERVICE_NAME = "StorageService";
+/**
+ * Storage key prefix for all keys managed by StorageService.
+ * Keys are formatted as: {STORAGE_KEY_PREFIX}{namespace}:{key}
+ * Example: 'storageService:SnapController:snap-id:sourceCode'
+ */
+export declare const STORAGE_KEY_PREFIX = "storageService:";
+/**
+ * All actions that {@link StorageService} exposes to other consumers.
+ * Action types are auto-generated from the service methods.
+ */
+export type StorageServiceActions = StorageServiceMethodActions;
+/**
+ * Event published when a storage item is set.
+ * Event type includes namespace only, key passed in payload.
+ *
+ * @example
+ * Subscribe to all changes in TokenListController:
+ * messenger.subscribe('StorageService:itemSet:TokenListController', (value, key) => {
+ *   // value = the data that was set
+ *   // key = 'cache:0x1', 'cache:0x38', etc.
+ *   if (key.startsWith('cache:')) {
+ *     const chainId = key.replace('cache:', '');
+ *     // React to cache change for specific chain
+ *   }
+ * });
+ */
+export type StorageServiceItemSetEvent = {
+    type: `${typeof SERVICE_NAME}:itemSet:${string}`;
+    payload: [value: unknown, key: string];
+};
+/**
+ * All events that {@link StorageService} publishes.
+ */
+export type StorageServiceEvents = StorageServiceItemSetEvent;
+/**
+ * Actions from other messengers that {@link StorageService} calls.
+ */
+type AllowedActions = never;
+/**
+ * Events from other messengers that {@link StorageService} subscribes to.
+ */
+type AllowedEvents = never;
+/**
+ * The messenger restricted to actions and events that
+ * {@link StorageService} needs to access.
+ */
+export type StorageServiceMessenger = Messenger<typeof SERVICE_NAME, StorageServiceActions | AllowedActions, StorageServiceEvents | AllowedEvents>;
+export {};
+//# sourceMappingURL=types.d.mts.map

package/dist/types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.mts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,4BAA4B;AAErD,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,OAAO,CAAC,CAAC;IAE1D;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvE;;;;;;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,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC;CACxC,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

@@ -0,0 +1,9 @@
+// Service name constant
+export const SERVICE_NAME = 'StorageService';
+/**
+ * Storage key prefix for all keys managed by StorageService.
+ * Keys are formatted as: {STORAGE_KEY_PREFIX}{namespace}:{key}
+ * Example: 'storageService:SnapController:snap-id:sourceCode'
+ */
+export const STORAGE_KEY_PREFIX = 'storageService:';
+//# sourceMappingURL=types.mjs.map

package/dist/types.mjs.map

@@ -0,0 +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';\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 value as a string, or null if not found.\n   */\n  getItem(namespace: string, key: string): Promise<unknown>;\n\n  /**\n   * Store a large 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   * - Wrapping value with metadata (timestamp, etc.)\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 value to store (will be wrapped and serialized by adapter).\n   */\n  setItem(namespace: string, key: string, value: unknown): 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', (value, key) => {\n *   // value = the data that was set\n *   // key = 'cache:0x1', 'cache:0x38', etc.\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: [value: unknown, key: string];\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"]}