@metamask-previews/storage-service 1.0.0-preview-e493d3e8 → 1.0.0-preview-f5c5aecd

package/dist/types.d.cts

@@ -0,0 +1,171 @@
+import type { Messenger } from "@metamask/messenger";
+/**
+ * Platform-agnostic storage adapter interface.
+ * Each client (mobile, extension) implements this interface
+ * with their preferred storage mechanism.
+ *
+ * @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 an item in storage.
+     * 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:";
+/**
+ * Action for storing data in the storage service.
+ */
+export type StorageServiceSetItemAction = {
+    type: `${typeof SERVICE_NAME}:setItem`;
+    handler: <T>(namespace: string, key: string, value: T) => Promise<void>;
+};
+/**
+ * Action for retrieving data from the storage service.
+ */
+export type StorageServiceGetItemAction = {
+    type: `${typeof SERVICE_NAME}:getItem`;
+    handler: <T>(namespace: string, key: string) => Promise<T | null>;
+};
+/**
+ * Action for removing data from the storage service.
+ */
+export type StorageServiceRemoveItemAction = {
+    type: `${typeof SERVICE_NAME}:removeItem`;
+    handler: (namespace: string, key: string) => Promise<void>;
+};
+/**
+ * Action for getting all keys for a namespace.
+ */
+export type StorageServiceGetAllKeysAction = {
+    type: `${typeof SERVICE_NAME}:getAllKeys`;
+    handler: (namespace: string) => Promise<string[]>;
+};
+/**
+ * Action for clearing all data for a namespace.
+ */
+export type StorageServiceClearAction = {
+    type: `${typeof SERVICE_NAME}:clear`;
+    handler: (namespace: string) => Promise<void>;
+};
+/**
+ * All actions that {@link StorageService} exposes to other consumers.
+ */
+export type StorageServiceActions = StorageServiceSetItemAction | StorageServiceGetItemAction | StorageServiceRemoveItemAction | StorageServiceGetAllKeysAction | StorageServiceClearAction;
+/**
+ * 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];
+};
+/**
+ * Event published when a storage item is removed.
+ * Event type includes namespace only, key passed in payload.
+ */
+export type StorageServiceItemRemovedEvent = {
+    type: `${typeof SERVICE_NAME}:itemRemoved:${string}`;
+    payload: [key: string];
+};
+/**
+ * All events that {@link StorageService} publishes.
+ */
+export type StorageServiceEvents = StorageServiceItemSetEvent | StorageServiceItemRemovedEvent;
+/**
+ * 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":"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"}

package/dist/types.d.mts

@@ -0,0 +1,171 @@
+import type { Messenger } from "@metamask/messenger";
+/**
+ * Platform-agnostic storage adapter interface.
+ * Each client (mobile, extension) implements this interface
+ * with their preferred storage mechanism.
+ *
+ * @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 an item in storage.
+     * 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:";
+/**
+ * Action for storing data in the storage service.
+ */
+export type StorageServiceSetItemAction = {
+    type: `${typeof SERVICE_NAME}:setItem`;
+    handler: <T>(namespace: string, key: string, value: T) => Promise<void>;
+};
+/**
+ * Action for retrieving data from the storage service.
+ */
+export type StorageServiceGetItemAction = {
+    type: `${typeof SERVICE_NAME}:getItem`;
+    handler: <T>(namespace: string, key: string) => Promise<T | null>;
+};
+/**
+ * Action for removing data from the storage service.
+ */
+export type StorageServiceRemoveItemAction = {
+    type: `${typeof SERVICE_NAME}:removeItem`;
+    handler: (namespace: string, key: string) => Promise<void>;
+};
+/**
+ * Action for getting all keys for a namespace.
+ */
+export type StorageServiceGetAllKeysAction = {
+    type: `${typeof SERVICE_NAME}:getAllKeys`;
+    handler: (namespace: string) => Promise<string[]>;
+};
+/**
+ * Action for clearing all data for a namespace.
+ */
+export type StorageServiceClearAction = {
+    type: `${typeof SERVICE_NAME}:clear`;
+    handler: (namespace: string) => Promise<void>;
+};
+/**
+ * All actions that {@link StorageService} exposes to other consumers.
+ */
+export type StorageServiceActions = StorageServiceSetItemAction | StorageServiceGetItemAction | StorageServiceRemoveItemAction | StorageServiceGetAllKeysAction | StorageServiceClearAction;
+/**
+ * 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];
+};
+/**
+ * Event published when a storage item is removed.
+ * Event type includes namespace only, key passed in payload.
+ */
+export type StorageServiceItemRemovedEvent = {
+    type: `${typeof SERVICE_NAME}:itemRemoved:${string}`;
+    payload: [key: string];
+};
+/**
+ * All events that {@link StorageService} publishes.
+ */
+export type StorageServiceEvents = StorageServiceItemSetEvent | StorageServiceItemRemovedEvent;
+/**
+ * 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":"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"}

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":"AAuFA,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\n/**\n * Platform-agnostic storage adapter interface.\n * Each client (mobile, extension) implements this interface\n * with their preferred storage mechanism.\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 an item in storage.\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 * Action for storing data in the storage service.\n */\nexport type StorageServiceSetItemAction = {\n  type: `${typeof SERVICE_NAME}:setItem`;\n  handler: <T>(namespace: string, key: string, value: T) => Promise<void>;\n};\n\n/**\n * Action for retrieving data from the storage service.\n */\nexport type StorageServiceGetItemAction = {\n  type: `${typeof SERVICE_NAME}:getItem`;\n  handler: <T>(namespace: string, key: string) => Promise<T | null>;\n};\n\n/**\n * Action for removing data from the storage service.\n */\nexport type StorageServiceRemoveItemAction = {\n  type: `${typeof SERVICE_NAME}:removeItem`;\n  handler: (namespace: string, key: string) => Promise<void>;\n};\n\n/**\n * Action for getting all keys for a namespace.\n */\nexport type StorageServiceGetAllKeysAction = {\n  type: `${typeof SERVICE_NAME}:getAllKeys`;\n  handler: (namespace: string) => Promise<string[]>;\n};\n\n/**\n * Action for clearing all data for a namespace.\n */\nexport type StorageServiceClearAction = {\n  type: `${typeof SERVICE_NAME}:clear`;\n  handler: (namespace: string) => Promise<void>;\n};\n\n/**\n * All actions that {@link StorageService} exposes to other consumers.\n */\nexport type StorageServiceActions =\n  | StorageServiceSetItemAction\n  | StorageServiceGetItemAction\n  | StorageServiceRemoveItemAction\n  | StorageServiceGetAllKeysAction\n  | StorageServiceClearAction;\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 * Event published when a storage item is removed.\n * Event type includes namespace only, key passed in payload.\n */\nexport type StorageServiceItemRemovedEvent = {\n  type: `${typeof SERVICE_NAME}:itemRemoved:${string}`;\n  payload: [key: string];\n};\n\n/**\n * All events that {@link StorageService} publishes.\n */\nexport type StorageServiceEvents =\n  | StorageServiceItemSetEvent\n  | StorageServiceItemRemovedEvent;\n\n/**\n * Actions from other messengers that {@link StorageService} calls.\n */\ntype AllowedActions = never;\n\n/**\n * Events from other messengers that {@link StorageService} subscribes to.\n */\ntype AllowedEvents = never;\n\n/**\n * The messenger restricted to actions and events that\n * {@link StorageService} needs to access.\n */\nexport type StorageServiceMessenger = Messenger<\n  typeof SERVICE_NAME,\n  StorageServiceActions | AllowedActions,\n  StorageServiceEvents | AllowedEvents\n>;\n"]}

package/package.json

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