diff --git a/app/scripts/lib/Stores/BaseStore.ts b/app/scripts/lib/Stores/BaseStore.ts index ca3c62fd409b..d31a734dc65a 100644 --- a/app/scripts/lib/Stores/BaseStore.ts +++ b/app/scripts/lib/Stores/BaseStore.ts @@ -38,46 +38,27 @@ export type MetaMaskStorageStructure = { export type EmptyState = Omit; /** - * The BaseStore class is an Abstract Class meant to be extended by other classes - * that implement the methods and properties marked as abstract. There are a - * few properties and methods that are not abstract and are implemented here to - * be consumed by the extending classes. At the time of writing this class - * there are only two extending classes: ReadOnlyNetworkStore and - * ExtensionStore. Both of these extending classes are the result of - * refactoring the previous storage implementation to TypeScript while - * consolidating some logic related to storage that was external to the - * implementation of those storage systems. ReadOnlyNetworkStore is a class - * that is used while in an End To End or other Test environment where the full - * chrome storage API may not be available. ExtensionStore is the class that is - * used when the full chrome storage API is available. While Chrome is the - * target of this documentation, Firefox also has a mostly identical storage - * API that is used interchangeably. + * The BaseStore class is an abstract class designed to be extended by other + * classes that implement the abstract methods `set` and `get`. This class + * provides the foundation for different storage implementations, enabling + * them to adhere to a consistent interface for retrieving and setting + * application state. * - * The classes that extend this system take on the responsibilities listed here - * 1. Retrieve the current state from the underlying storage system. If that - * state is unavailable, then the storage system should return a default state - * in the case that this is the first time the extension has been installed. If - * the state is not available due to some form of possible corruption, using - * the best methods available to detect such things, then a backup of the vault - * should be inserted into a state tree that otherwise resembles a first time - * installation. If the backup of the vault is unavailable, then a default - * state tree should be used. In any case we should provide clear and concise - * communication to the user about what happened and their best recourse for - * handling the situation if the extension cannot gracefully recover. + * Responsibilities of extending classes: + * 1. **Retrieve State:** + * - Implement a `get` method that retrieves the current state from the + * underlying storage system. This method should handle scenarios where + * the state is unavailable by providing a fallback, such as returning + * null` or an appropriate default value. * - * 2. Set the current state to the underlying storage system. This should be - * implemented in such a way that the current metadata is stored in a separate - * key that is tracked by the storage system. This metadata should *not* be a - * input to the set method. If the underlying storage system allows for partial - * state objects it should be sufficient to pass the data key, which is the - * full MetaMask state tree. If not, then the metadata should be supplied by - * the storage system itself. + * 2. **Set State:** + * - Implement a `set` method that updates the state in the underlying + * storage system. This method should handle necessary validation or + * error handling to ensure the state is persisted correctly. * - * 3. Provide a method for generating a first time state tree. This method is - * implemented as a part of this Abstract class and should not be overwritten - * unless future work requires specific implementations for different storage - * systems. This method should return a state tree that is the default state - * tree for a new install. + * This class does not provide any concrete implementation for these methods, + * leaving the specifics to the extending classes based on the storage + * mechanism they represent. */ export abstract class BaseStore { abstract set(state: IntermediaryStateType): Promise; diff --git a/app/scripts/lib/Stores/PersistanceManager.ts b/app/scripts/lib/Stores/PersistanceManager.ts index 785d5f3e73cb..4ac50af7eb0a 100644 --- a/app/scripts/lib/Stores/PersistanceManager.ts +++ b/app/scripts/lib/Stores/PersistanceManager.ts @@ -8,6 +8,36 @@ import { import ExtensionStore from './ExtensionStore'; import ReadOnlyNetworkStore from './ReadOnlyNetworkStore'; +/** + * The PersistanceManager class serves as a high-level manager for handling + * storage-related operations using a local storage system. It provides methods to read + * and write state, manage metadata, and handle errors or corruption in the + * underlying storage system. + * + * Key Responsibilities: + * + * 1. **State Management:** + * - Tracks the most recently retrieved state + * - reads state from the storage system + * - writes updated state to the storage system + * + * 2. **Metadata Handling:** + * - Manages a `metadata` object containing versioning information for the + * state tree. The version is used to ensure consistency and proper + * handling of migrations. + * + * 3. **Error Management:** + * - Tracks whether data persistence is failing and logs appropriate errors + * - Captures exceptions during write operations and reports them using + * Sentry + * + * + * Usage: + * The `PersistanceManager` is instantiated with a `localStore`, which is an + * implementation of the `BaseStore` class (either `ExtensionStore` or + * `ReadOnlyNetworkStore`). It provides methods for setting and retrieving + * state, managing metadata, and handling cleanup tasks. + */ export class PersistanceManager { /** * dataPersistenceFailing is a boolean that is set to true if the storage @@ -34,8 +64,6 @@ export class PersistanceManager { */ #metadata?: { version: number }; - stateCorruptionDetected: boolean; - isExtensionInitialized: boolean; localStore: ExtensionStore | ReadOnlyNetworkStore; @@ -45,7 +73,6 @@ export class PersistanceManager { }: { localStore: ExtensionStore | ReadOnlyNetworkStore; }) { - this.stateCorruptionDetected = false; this.dataPersistenceFailing = false; this.mostRecentRetrievedState = null; this.isExtensionInitialized = false;