@sv443-network/userutils 8.0.2 → 8.1.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @sv443-network/userutils
 
+## 8.1.0
+
+### Minor Changes
+
+- 6296529: Added new DataStoreSerializer methods `loadStoresData()`, `resetStoresData()` and `deleteStoresData()` for parallelized bulk operations on DataStore instances
+- b0bce9c: Added DataStore method `migrateId()` to be able to migrate to a new ID
+
 ## 8.0.2
 
 ### Patch Changes

package/README.md

@@ -186,8 +186,9 @@ Additionally, there are the following extra options:
 
 <br>
 
-#### Methods:
-`addListener<TElement = HTMLElement>(selector: string, options: SelectorListenerOptions): void`  
+### Methods:
+#### `SelectorObserver.addListener()`
+Usage: `SelectorObserver.addListener<TElement = HTMLElement>(selector: string, options: SelectorListenerOptions): void`  
 Adds a listener (specified in `options.listener`) for the given selector that will be called once the selector exists in the DOM. It will be passed the element(s) that match the selector as the only argument.  
 The listener will be called immediately if the selector already exists in the DOM.  
 
@@ -216,45 +217,53 @@ The listener will be called immediately if the selector already exists in the DO
   
 <br>
 
-`enable(immediatelyCheckSelectors?: boolean): boolean`  
+#### `SelectorObserver.enable()`
+Usage: `SelectorObserver.enable(immediatelyCheckSelectors?: boolean): boolean`  
 Enables the observation of the child elements for the first time or if it was disabled before.  
 `immediatelyCheckSelectors` is set to true by default, which means all previously registered selectors will be checked. Set to false to only check them on the first detected mutation.  
 Returns true if the observation was enabled, false if it was already enabled or the passed `baseElementSelector` couldn't be found.  
   
 <br>
 
-`disable(): void`  
+#### `SelectorObserver.disable()`
+Usage: `SelectorObserver.disable(): void`  
 Disables the observation of the child elements.  
 If selectors are currently being checked, the current selector will be finished before disabling.  
   
 <br>
 
-`isEnabled(): boolean`  
+#### `SelectorObserver.isEnabled()`
+Usage: `SelectorObserver.isEnabled(): boolean`  
 Returns whether the observation of the child elements is currently enabled.  
   
 <br>
 
-`clearListeners(): void`  
+#### `SelectorObserver.clearListeners()`
+Usage: `SelectorObserver.clearListeners(): void`  
 Removes all listeners for all selectors.  
   
 <br>
 
-`removeAllListeners(selector: string): boolean`  
+#### `SelectorObserver.removeAllListeners()`
+Usage: `SelectorObserver.removeAllListeners(selector: string): boolean`  
 Removes all listeners for the given selector.  
   
 <br>
 
-`removeListener(selector: string, options: SelectorListenerOptions): boolean`  
+#### `SelectorObserver.removeListener()`
+Usage: `SelectorObserver.removeListener(selector: string, options: SelectorListenerOptions): boolean`  
 Removes a specific listener for the given selector and options.  
   
 <br>
 
-`getAllListeners(): Map<string, SelectorListenerOptions[]>`  
+#### `SelectorObserver.getAllListeners()`
+Usage: `SelectorObserver.getAllListeners(): Map<string, SelectorListenerOptions[]>`  
 Returns a Map of all selectors and their listeners.  
   
 <br>
 
-`getListeners(selector: string): SelectorListenerOptions[] | undefined`  
+#### `SelectorObserver.getListeners()`
+Usage: `SelectorObserver.getListeners(selector: string): SelectorListenerOptions[] | undefined`  
 Returns all listeners for the given selector or undefined if there are none.  
 
 <br>
@@ -995,7 +1004,7 @@ It combines the data of multiple DataStore instances into a single object that c
 The options object has the following properties:
 | Property | Description |
 | :-- | :-- |
-| `id` | A unique internal identification string for this instance. If two DataStores share the same ID, they will overwrite each other's data. Choose wisely because if it is changed, the previously saved data will not be able to be loaded anymore. |
+| `id` | A unique internal identification string for this instance. If two DataStores share the same ID, they will overwrite each other's data, so it is recommended that you use a prefix that is unique to your project. |
 | `defaultData` | The default data to use if no data is saved in persistent storage yet. Until the data is loaded from persistent storage, this will be the data returned by `getData()`. For TypeScript, the type of the data passed here is what will be used for all other methods of the instance. |
 | `formatVersion` | An incremental version of the data format. If the format of the data is changed in any way, this number should be incremented, in which case all necessary functions of the migrations dictionary will be run consecutively. Never decrement this number or skip numbers. |
 | `migrations?` | (Optional) A dictionary of functions that can be used to migrate data from older versions of the data to newer ones. The keys of the dictionary should be the format version that the functions can migrate to, from the previous whole integer value. The values should be functions that take the data in the old format and return the data in the new format. The functions will be run in order from the oldest to the newest version. If the current format version is not in the dictionary, no migrations will be run. |
@@ -1005,34 +1014,60 @@ The options object has the following properties:
 
 <br>
 
-#### Methods:
-`loadData(): Promise<TData>`  
+### Methods:
+#### `DataStore.loadData()`
+Usage: `loadData(): Promise<TData>`  
 Asynchronously loads the data from persistent storage and returns it.  
 If no data was saved in persistent storage before, the value of `options.defaultData` will be returned and written to persistent storage.  
-If the formatVersion of the saved data is lower than the current one and the `options.migrations` property is present, the data will be migrated to the latest format before the Promise resolves.  
-  
-`getData(): TData`  
+If the formatVersion of the saved data is lower than the current one and the `options.migrations` property is present, the data will be migrated to the latest format before the Promise resolves.
+
+<br>
+
+#### `DataStore.getData()`
+Usage: `getData(): TData`  
 Synchronously returns the current data that is stored in the internal cache.  
-If no data was loaded from persistent storage yet using `loadData()`, the value of `options.defaultData` will be returned.  
-  
-`setData(data: TData): Promise<void>`  
-Writes the given data synchronously to the internal cache and asynchronously to persistent storage.  
-  
-`saveDefaultData(): Promise<void>`  
-Writes the default data given in `options.defaultData` synchronously to the internal cache and asynchronously to persistent storage.  
-  
-`deleteData(): Promise<void>`  
+If no data was loaded from persistent storage yet using `loadData()`, the value of `options.defaultData` will be returned.
+
+<br>
+
+#### `DataStore.setData()`
+Usage: `setData(data: TData): Promise<void>`  
+Writes the given data synchronously to the internal cache and asynchronously to persistent storage.
+
+<br>
+
+#### `DataStore.saveDefaultData()`
+Usage: `saveDefaultData(): Promise<void>`  
+Writes the default data given in `options.defaultData` synchronously to the internal cache and asynchronously to persistent storage.
+
+<br>
+
+#### `DataStore.deleteData()`
+Usage: `deleteData(): Promise<void>`  
 Fully deletes the data from persistent storage only.  
 The internal cache will be left untouched, so any subsequent calls to `getData()` will return the data that was last loaded.  
 If `loadData()` or `setData()` are called after this, the persistent storage will be populated with the value of `options.defaultData` again.  
 This is why you should either immediately repopulate the cache and persistent storage or the page should probably be reloaded or closed after this method is called.  
-⚠️ If you want to use this method, the additional directive `@grant GM.deleteValue` is required.  
-  
-`runMigrations(oldData: any, oldFmtVer: number, resetOnError?: boolean): Promise<TData>`  
+⚠️ If you want to use this method, the additional directive `@grant GM.deleteValue` is required.
+
+<br>
+
+#### `DataStore.runMigrations()`
+Usage: `runMigrations(oldData: any, oldFmtVer: number, resetOnError?: boolean): Promise<TData>`  
 Runs all necessary migration functions to migrate the given `oldData` to the latest format.  
-If `resetOnError` is set to `false`, the migration will be aborted if an error is thrown and no data will be committed. If it is set to `true` (default) and an error is encountered, it will be suppressed and the `defaultData` will be saved to persistent storage and returned.  
-  
-`encodingEnabled(): boolean`  
+If `resetOnError` is set to `false`, the migration will be aborted if an error is thrown and no data will be committed. If it is set to `true` (default) and an error is encountered, it will be suppressed and the `defaultData` will be saved to persistent storage and returned.
+
+<br>
+
+#### `DataStore.migrateId()`
+Usage: `migrateId(oldIds: string | string[]): Promise<void>`  
+Tries to migrate the currently saved persistent data from one or more old IDs to the ID set in the constructor.  
+If no data exist for the old ID(s), nothing will be done, but some time may still pass trying to fetch the non-existent data.
+
+<br>
+
+#### `DataStore.encodingEnabled()`
+Usage: `encodingEnabled(): boolean`  
 Returns `true` if both `options.encodeData` and `options.decodeData` are set, else `false`.  
 Uses TypeScript's type guard notation for easier use in conditional statements.
 
@@ -1085,7 +1120,7 @@ const migrations = {
 
 // You probably want to export this instance (or helper functions) so you can use it anywhere in your script:
 export const manager = new DataStore({
-  /** A unique ID for this instance - choose wisely as changing it is not supported and will result in data loss! */
+  /** A unique ID for this instance */
   id: "my-userscript-config",
   /** Default, initial and fallback data */
   defaultData,
@@ -1161,12 +1196,9 @@ The options object has the following properties:
 
 <br>
 
-#### Methods:
-`constructor(stores: DataStore[], options?: DataStoreSerializerOptions)`  
-Creates a new DataStoreSerializer instance with the given DataStore instances and options.  
-If no options are passed, the defaults will be used.  
-  
-`serialize(): Promise<string>`  
+### Methods:
+#### `DataStoreSerializer.serialize()`
+Usage: `serialize(): Promise<string>`  
 Serializes all DataStore instances passed in the constructor and returns the serialized data as a JSON string.  
 <details><summary>Click to view the structure of the returned data.</summary>  
 
@@ -1185,15 +1217,65 @@ Serializes all DataStore instances passed in the constructor and returns the ser
 ]
 ```
 </details>  
-  
-`deserialize(data: string): Promise<void>`  
-Deserializes the given JSON string and imports the data into the DataStore instances.  
+
+<br>
+
+#### `DataStoreSerializer.deserialize()`
+Usage: `deserialize(data: string): Promise<void>`  
+Deserializes the given string that was created with `serialize()` and imports the contained data each DataStore instance.  
 In the process of importing the data, the migrations will be run, if the `formatVersion` property is lower than the one set on the DataStore instance.
   
 If `ensureIntegrity` is set to `true` and the checksum doesn't match, an error will be thrown.  
 If `ensureIntegrity` is set to `false`, the checksum check will be skipped entirely.  
 If the `checksum` property is missing on the imported data, the checksum check will also be skipped.  
 If `encoded` is set to `true`, the data will be decoded using the `decodeData` function set on the DataStore instance.  
+  
+<br>
+
+#### `DataStoreSerializer.loadStoresData()`
+Usage: `loadStoresData(): PromiseSettledResult<{ id: string, data: object }>[];`  
+Loads the persistent data of the DataStore instances into the in-memory cache of each DataStore instance.  
+Also triggers the migration process if the data format has changed.  
+See the [`DataStore.loadData()`](#datastoreloaddata) method for more information.  
+  
+<details><summary>Click to view the structure of the returned data.</summary>  
+
+```jsonc
+[
+  {
+    "status": "fulfilled",
+    "value": {
+      "id": "foo-data",
+      "data": {
+        "foo": "hello",
+        "bar": "world"
+      }
+    }
+  },
+  {
+    "status": "rejected",
+    "reason": "Checksum mismatch for DataStore with ID \"bar-data\"!\nExpected: 69beefdead420\nHas: 420abcdef69"
+  }
+]
+```
+
+</details>
+
+<br>
+
+#### `DataStoreSerializer.resetStoresData()`
+Usage: `resetStoresData(): PromiseSettledResult[];`  
+Resets the persistent data of the DataStore instances to their default values.  
+This affects both the in-memory cache and the persistent storage.  
+Any call to `serialize()` will then use the value of `options.defaultData` of the respective DataStore instance.  
+
+<br>
+
+#### `DataStoreSerializer.deleteStoresData()`
+Usage: `deleteStoresData(): PromiseSettledResult[];`  
+Deletes the persistent data of the DataStore instances from the set storage method.  
+Leaves the in-memory cache of the DataStore instances untouched.  
+Any call to `setData()` on the instances will recreate their own persistent storage data.
 
 <br>
 
@@ -1234,9 +1316,8 @@ const serializer = new DataStoreSerializer([fooStore, barStore], {
 });
 
 async function exportMyDataPls() {
-  // first, make sure the persistent data of the stores is loaded into their caches:
-  await fooStore.loadData();
-  await barStore.loadData();
+  // first, make sure the persistent data of all stores is loaded into their caches:
+  await serializer.loadStoresData();
 
   // now serialize the data:
   const serializedData = await serializer.serialize();
@@ -1269,11 +1350,11 @@ async function exportMyDataPls() {
 }
 
 async function importMyDataPls() {
-  // grab the data from the file by using the system file picker or any other method
+  // grab the data from the file by using the system file picker or a text field or something similar
   const data = await getDataFromSomewhere();
 
   try {
-    // import the data
+    // import the data and run migrations if necessary
     await serializer.deserialize(data);
   }
   catch(err) {
@@ -1281,6 +1362,11 @@ async function importMyDataPls() {
     alert(`Data import failed: ${err}`);
   }
 }
+
+async function resetMyDataPls() {
+  // reset the data of all stores in both the cache and the persistent storage
+  await serializer.resetStoresData();
+}
 ```
 </details>
 
@@ -1313,41 +1399,71 @@ The options object has the following properties:
 | `verticalAlign?: "top" \| "center" \| "bottom"` | (Optional) Where to align or anchor the dialog vertically. Defaults to `"center"`. |
 | `strings?: Partial<typeof defaultStrings>` | (Optional) Strings used in the dialog (used for translations). Defaults to the default English strings (importable with the name `defaultStrings`). |
 | `dialogCss?: string` | (Optional) CSS to apply to the dialog. Defaults to the default (importable with the name `defaultDialogCss`). |
-  
-Methods:  
-`open(): Promise<void>`  
+
+<br>
+
+### Methods:
+#### `Dialog.open()`
+Usage: `open(): Promise<void>`  
 Opens the dialog.  
-  
-`close(): void`  
+
+<br>
+
+#### `Dialog.close()`
+Usage: `close(): void`  
 Closes the dialog.  
-  
-`mount(): Promise<void>`  
+
+<br>
+
+#### `Dialog.mount()`
+Usage: `mount(): Promise<void>`  
 Mounts the dialog to the DOM by calling the render functions provided in the options object.  
 Can be done before opening the dialog to avoid a delay.  
-  
-`unmount(): void`  
+
+<br>
+
+#### `Dialog.unmount()`
+Usage: `unmount(): void`  
 Unmounts the dialog from the DOM.  
-  
-`remount(): Promise<void>`  
+
+<br>
+
+#### `Dialog.remount()`
+Usage: `remount(): Promise<void>`  
 Unmounts and mounts the dialog again.  
 The render functions in the options object will be called again.  
 May cause a flickering effect due to the rendering delay.  
-  
-`isOpen(): boolean`  
+
+<br>
+
+#### `Dialog.isOpen()`
+Usage: `isOpen(): boolean`  
 Returns `true` if the dialog is open, else `false`.  
-  
-`isMounted(): boolean`  
+
+<br>
+
+#### `Dialog.isMounted()`
+Usage: `isMounted(): boolean`  
 Returns `true` if the dialog is mounted, else `false`.  
-  
-`destroy(): void`  
+
+<br>
+
+#### `Dialog.destroy()`
+Usage: `destroy(): void`  
 Destroys the dialog.  
 Removes all listeners and unmounts the dialog by default.  
-  
-`static getCurrentDialogId(): string`  
+
+<br>
+
+#### `Dialog.getCurrentDialogId()`
+Usage: `static getCurrentDialogId(): string`  
 Static method that returns the ID of the currently open dialog.  
 Needs to be called without creating an instance of the class.  
-  
-`static getOpenDialogs(): string[]`  
+
+<br>
+
+#### `Dialog.getOpenDialogs()`
+Usage: `static getOpenDialogs(): string[]`  
 Static method that returns an array of the IDs of all open dialogs.  
 Needs to be called without creating an instance of the class.  
   

package/dist/index.global.js

@@ -8,7 +8,7 @@
 // ==UserLibrary==
 // @name         UserUtils
 // @description  Library with various utilities for userscripts - register listeners for when CSS selectors exist, intercept events, create persistent & synchronous data stores, modify the DOM more easily and more
-// @version      8.0.2
+// @version      8.1.0
 // @license      MIT
 // @copyright    Sv443 (https://github.com/Sv443)
 
@@ -478,7 +478,7 @@ var UserUtils = (function (exports) {
      * The in-memory cache will be left untouched, so you may still access the data with {@linkcode getData()}  
      * Calling {@linkcode loadData()} or {@linkcode setData()} after this method was called will recreate persistent storage with the cached or default data.  
      *   
-     * ⚠️ This requires the additional directive `@grant GM.deleteValue`
+     * ⚠️ This requires the additional directive `@grant GM.deleteValue` if the storageMethod is left as the default of `"GM"`
      */
     deleteData() {
       return __async(this, null, function* () {
@@ -532,6 +532,31 @@ var UserUtils = (function (exports) {
         return this.cachedData = __spreadValues({}, newData);
       });
     }
+    /**
+     * Tries to migrate the currently saved persistent data from one or more old IDs to the ID set in the constructor.  
+     * If no data exist for the old ID(s), nothing will be done, but some time may still pass trying to fetch the non-existent data.
+     */
+    migrateId(oldIds) {
+      return __async(this, null, function* () {
+        const ids = Array.isArray(oldIds) ? oldIds : [oldIds];
+        yield Promise.all(ids.map((id) => __async(this, null, function* () {
+          const data = yield this.getValue(`_uucfg-${id}`, JSON.stringify(this.defaultData));
+          const fmtVer = Number(yield this.getValue(`_uucfgver-${id}`, NaN));
+          const isEncoded = Boolean(yield this.getValue(`_uucfgenc-${id}`, false));
+          if (data === void 0 || isNaN(fmtVer))
+            return;
+          const parsed = yield this.deserializeData(data, isEncoded);
+          yield Promise.allSettled([
+            this.setValue(`_uucfg-${this.id}`, yield this.serializeData(parsed)),
+            this.setValue(`_uucfgver-${this.id}`, fmtVer),
+            this.setValue(`_uucfgenc-${this.id}`, isEncoded),
+            this.deleteValue(`_uucfg-${id}`),
+            this.deleteValue(`_uucfgver-${id}`),
+            this.deleteValue(`_uucfgenc-${id}`)
+          ]);
+        })));
+      });
+    }
     //#region serialization
     /** Serializes the data using the optional this.encodeData() and returns it as a string */
     serializeData(data, useEncoding = true) {
@@ -673,6 +698,38 @@ Has: ${checksum}`);
         }
       });
     }
+    /**
+     * Loads the persistent data of the DataStore instances into the in-memory cache.  
+     * Also triggers the migration process if the data format has changed.
+     * @returns Returns a PromiseSettledResult array with the results of each DataStore instance in the format `{ id: string, data: object }`
+     */
+    loadStoresData() {
+      return __async(this, null, function* () {
+        return Promise.allSettled(this.stores.map(
+          (store) => __async(this, null, function* () {
+            return {
+              id: store.id,
+              data: yield store.loadData()
+            };
+          })
+        ));
+      });
+    }
+    /** Resets the persistent data of the DataStore instances to their default values. */
+    resetStoresData() {
+      return __async(this, null, function* () {
+        return Promise.allSettled(this.stores.map((store) => store.saveDefaultData()));
+      });
+    }
+    /**
+     * Deletes the persistent data of the DataStore instances.  
+     * Leaves the in-memory data untouched.
+     */
+    deleteStoresData() {
+      return __async(this, null, function* () {
+        return Promise.allSettled(this.stores.map((store) => store.deleteData()));
+      });
+    }
   };
 
   // node_modules/nanoevents/index.js

package/dist/index.js

@@ -458,7 +458,7 @@ var DataStore = class {
    * The in-memory cache will be left untouched, so you may still access the data with {@linkcode getData()}  
    * Calling {@linkcode loadData()} or {@linkcode setData()} after this method was called will recreate persistent storage with the cached or default data.  
    *   
-   * ⚠️ This requires the additional directive `@grant GM.deleteValue`
+   * ⚠️ This requires the additional directive `@grant GM.deleteValue` if the storageMethod is left as the default of `"GM"`
    */
   deleteData() {
     return __async(this, null, function* () {
@@ -512,6 +512,31 @@ var DataStore = class {
       return this.cachedData = __spreadValues({}, newData);
     });
   }
+  /**
+   * Tries to migrate the currently saved persistent data from one or more old IDs to the ID set in the constructor.  
+   * If no data exist for the old ID(s), nothing will be done, but some time may still pass trying to fetch the non-existent data.
+   */
+  migrateId(oldIds) {
+    return __async(this, null, function* () {
+      const ids = Array.isArray(oldIds) ? oldIds : [oldIds];
+      yield Promise.all(ids.map((id) => __async(this, null, function* () {
+        const data = yield this.getValue(`_uucfg-${id}`, JSON.stringify(this.defaultData));
+        const fmtVer = Number(yield this.getValue(`_uucfgver-${id}`, NaN));
+        const isEncoded = Boolean(yield this.getValue(`_uucfgenc-${id}`, false));
+        if (data === void 0 || isNaN(fmtVer))
+          return;
+        const parsed = yield this.deserializeData(data, isEncoded);
+        yield Promise.allSettled([
+          this.setValue(`_uucfg-${this.id}`, yield this.serializeData(parsed)),
+          this.setValue(`_uucfgver-${this.id}`, fmtVer),
+          this.setValue(`_uucfgenc-${this.id}`, isEncoded),
+          this.deleteValue(`_uucfg-${id}`),
+          this.deleteValue(`_uucfgver-${id}`),
+          this.deleteValue(`_uucfgenc-${id}`)
+        ]);
+      })));
+    });
+  }
   //#region serialization
   /** Serializes the data using the optional this.encodeData() and returns it as a string */
   serializeData(data, useEncoding = true) {
@@ -653,6 +678,38 @@ Has: ${checksum}`);
       }
     });
   }
+  /**
+   * Loads the persistent data of the DataStore instances into the in-memory cache.  
+   * Also triggers the migration process if the data format has changed.
+   * @returns Returns a PromiseSettledResult array with the results of each DataStore instance in the format `{ id: string, data: object }`
+   */
+  loadStoresData() {
+    return __async(this, null, function* () {
+      return Promise.allSettled(this.stores.map(
+        (store) => __async(this, null, function* () {
+          return {
+            id: store.id,
+            data: yield store.loadData()
+          };
+        })
+      ));
+    });
+  }
+  /** Resets the persistent data of the DataStore instances to their default values. */
+  resetStoresData() {
+    return __async(this, null, function* () {
+      return Promise.allSettled(this.stores.map((store) => store.saveDefaultData()));
+    });
+  }
+  /**
+   * Deletes the persistent data of the DataStore instances.  
+   * Leaves the in-memory data untouched.
+   */
+  deleteStoresData() {
+    return __async(this, null, function* () {
+      return Promise.allSettled(this.stores.map((store) => store.deleteData()));
+    });
+  }
 };
 var NanoEmitter = class {
   constructor(options = {}) {

package/dist/lib/DataStore.d.ts

@@ -5,11 +5,15 @@ type MigrationFunc = (oldData: any) => any | Promise<any>;
 export type DataMigrationsDict = Record<number, MigrationFunc>;
 /** Options for the DataStore instance */
 export type DataStoreOptions<TData> = {
-    /** A unique internal ID for this data store - choose wisely as changing it is not supported yet. */
+    /**
+     * A unique internal ID for this data store.
+     * To avoid conflicts with other scripts, it is recommended to use a prefix that is unique to your script.
+     * If you want to change the ID, you should make use of the {@linkcode DataStore.migrateId()} method.
+     */
     id: string;
     /**
      * The default data object to use if no data is saved in persistent storage yet.
-     * Until the data is loaded from persistent storage with `loadData()`, this will be the data returned by `getData()`
+     * Until the data is loaded from persistent storage with {@linkcode DataStore.loadData()}, this will be the data returned by {@linkcode DataStore.getData()}.
      *
      * ⚠️ This has to be an object that can be serialized to JSON using `JSON.stringify()`, so no functions or circular references are allowed, they will cause unexpected behavior.
      */
@@ -31,8 +35,8 @@ export type DataStoreOptions<TData> = {
     migrations?: DataMigrationsDict;
     /**
      * Where the data should be saved (`"GM"` by default).
-     * The protected methods `getValue` , `setValue`  and `deleteValue` are used to interact with the storage.
-     * If you want to use a different storage method, you can extend the class and overwrite these methods.
+     * The protected methods {@linkcode DataStore.getValue()}, {@linkcode DataStore.setValue()}  and {@linkcode DataStore.deleteValue()} are used to interact with the storage.
+     * `"GM"` storage, `"localStorage"` and `"sessionStorage"` are supported out of the box, but in an extended class you can overwrite those methods to implement any other storage method.
      */
     storageMethod?: "GM" | "localStorage" | "sessionStorage";
 } & ({
@@ -57,16 +61,18 @@ export type DataStoreOptions<TData> = {
     decodeData?: never;
 });
 /**
- * Manages a hybrid synchronous & asynchronous persistent JSON database that is cached in memory and persistently saved across sessions using [GM storage.](https://wiki.greasespot.net/GM.setValue)
+ * Manages a hybrid synchronous & asynchronous persistent JSON database that is cached in memory and persistently saved across sessions using [GM storage](https://wiki.greasespot.net/GM.setValue) (default), [localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) or [sessionStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage).
  * Supports migrating data from older format versions to newer ones and populating the cache with default data if no persistent data is found.
+ * Can be overridden to implement any other storage method.
  *
  * All methods are at least `protected`, so you can easily extend this class and overwrite them to use a different storage method or to add additional functionality.
  * Remember that you can call `super.methodName()` in the subclass to access the original method.
  *
- * ⚠️ Requires the directives `@grant GM.getValue` and `@grant GM.setValue` if the storageMethod is left as the default of `"GM"`
+ * ⚠️ The stored data has to be **serializable using `JSON.stringify()`**, meaning no undefined, circular references, etc. are allowed.
+ * ⚠️ If the storageMethod is left as the default of `"GM"` the directives `@grant GM.getValue` and `@grant GM.setValue` are required. If you then also use the method {@linkcode DataStore.deleteData()}, the extra directive `@grant GM.deleteValue` is needed too.
  * ⚠️ Make sure to call {@linkcode loadData()} at least once after creating an instance, or the returned data will be the same as `options.defaultData`
  *
- * @template TData The type of the data that is saved in persistent storage for the currently set format version (will be automatically inferred from `defaultData` if not provided) - **This has to be a JSON-compatible object!** (no undefined, circular references, etc.)
+ * @template TData The type of the data that is saved in persistent storage for the currently set format version (will be automatically inferred from `defaultData` if not provided)
  */
 export declare class DataStore<TData extends object = object> {
     readonly id: string;
@@ -109,7 +115,7 @@ export declare class DataStore<TData extends object = object> {
      * The in-memory cache will be left untouched, so you may still access the data with {@linkcode getData()}
      * Calling {@linkcode loadData()} or {@linkcode setData()} after this method was called will recreate persistent storage with the cached or default data.
      *
-     * ⚠️ This requires the additional directive `@grant GM.deleteValue`
+     * ⚠️ This requires the additional directive `@grant GM.deleteValue` if the storageMethod is left as the default of `"GM"`
      */
     deleteData(): Promise<void>;
     /** Returns whether encoding and decoding are enabled for this DataStore instance */
@@ -122,6 +128,11 @@ export declare class DataStore<TData extends object = object> {
      * If one of the migrations fails, the data will be reset to the default value if `resetOnError` is set to `true` (default). Otherwise, an error will be thrown and no data will be saved.
      */
     runMigrations(oldData: any, oldFmtVer: number, resetOnError?: boolean): Promise<TData>;
+    /**
+     * Tries to migrate the currently saved persistent data from one or more old IDs to the ID set in the constructor.
+     * If no data exist for the old ID(s), nothing will be done, but some time may still pass trying to fetch the non-existent data.
+     */
+    migrateId(oldIds: string | string[]): Promise<void>;
     /** Serializes the data using the optional this.encodeData() and returns it as a string */
     protected serializeData(data: TData, useEncoding?: boolean): Promise<string>;
     /** Deserializes the data using the optional this.decodeData() and returns it as a JSON object */

package/dist/lib/DataStoreSerializer.d.ts

@@ -18,6 +18,13 @@ export type SerializedDataStore = {
     /** The checksum of the data - key is not present for data without a checksum */
     checksum?: string;
 };
+/** Result of {@linkcode DataStoreSerializer.loadStoresData()} */
+export type LoadStoresDataResult = {
+    /** The ID of the DataStore instance */
+    id: string;
+    /** The in-memory data object */
+    data: object;
+};
 /**
  * Allows for easy serialization and deserialization of multiple DataStore instances.
  *
@@ -41,4 +48,17 @@ export declare class DataStoreSerializer {
      * Also triggers the migration process if the data format has changed.
      */
     deserialize(serializedData: string): Promise<void>;
+    /**
+     * Loads the persistent data of the DataStore instances into the in-memory cache.
+     * Also triggers the migration process if the data format has changed.
+     * @returns Returns a PromiseSettledResult array with the results of each DataStore instance in the format `{ id: string, data: object }`
+     */
+    loadStoresData(): Promise<PromiseSettledResult<LoadStoresDataResult>[]>;
+    /** Resets the persistent data of the DataStore instances to their default values. */
+    resetStoresData(): Promise<PromiseSettledResult<void>[]>;
+    /**
+     * Deletes the persistent data of the DataStore instances.
+     * Leaves the in-memory data untouched.
+     */
+    deleteStoresData(): Promise<PromiseSettledResult<void>[]>;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sv443-network/userutils",
   "libName": "UserUtils",
-  "version": "8.0.2",
+  "version": "8.1.0",
   "description": "Library with various utilities for userscripts - register listeners for when CSS selectors exist, intercept events, create persistent & synchronous data stores, modify the DOM more easily and more",
   "main": "dist/index.js",
   "module": "dist/index.js",