@sv443-network/userutils 8.0.2 → 8.2.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @sv443-network/userutils
 
+## 8.2.0
+
+### Minor Changes
+
+- 3fe8b25: Added overload to `mapRange()` that only needs both `max` values and assumes 0 for both `min` values
+- d7e8a31: Added utility type `Prettify` to make complex types more readable
+- 8ec2010: Added `randomCase` parameter to the function `randomId()` (true by default)
+- d9a36d5: Added property `migrateIds` to the constructor of `DataStore` for easier ID migration
+- b2f757e: Added `enhancedEntropy` parameter to the function `randRange()` (false by default)
+
+## 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

@@ -78,6 +78,7 @@ View the documentation of previous major releases:
     - [`NonEmptyArray`](#nonemptyarray) - any array that should have at least one item
     - [`NonEmptyString`](#nonemptystring) - any string that should have at least one character
     - [`LooseUnion`](#looseunion) - a union that gives autocomplete in the IDE but also allows any other value of the same type
+    - [`Prettify`](#prettify) - expands a complex type into a more readable format while keeping functionality the same
 
 <br><br>
 
@@ -186,8 +187,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 +218,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>
@@ -921,16 +931,12 @@ clamp(99999, 0, Infinity);   // 99999
 ### mapRange()
 Usage:  
 ```ts
-mapRange(
-  value: number,
-  range1min: number,
-  range1max: number,
-  range2min: number,
-  range2max: number
-): number
+mapRange(value: number, range1min: number, range1max: number, range2min: number, range2max: number): number
+mapRange(value: number, range1max: number, range2max: number): number
 ```
   
 Maps a number from one range to the spot it would be in another range.  
+If only the `max` arguments are passed, the function will set the `min` for both ranges to 0.  
   
 <details><summary><b>Example - click to view</b></summary>
 
@@ -939,6 +945,7 @@ import { mapRange } from "@sv443-network/userutils";
 
 mapRange(5, 0, 10, 0, 100); // 50
 mapRange(5, 0, 10, 0, 50);  // 25
+mapRange(5, 10, 50);        // 25
 
 // to calculate a percentage from arbitrary values, use 0 and 100 as the second range
 // for example, if 4 files of a total of 13 were downloaded:
@@ -951,21 +958,41 @@ mapRange(4, 0, 13, 0, 100); // 30.76923076923077
 ### randRange()
 Usages:  
 ```ts
-randRange(min: number, max: number): number
-randRange(max: number): number
+randRange(min: number, max: number, enhancedEntropy?: boolean): number
+randRange(max: number, enhancedEntropy?: boolean): number
 ```
   
 Returns a random number between `min` and `max` (inclusive).  
 If only one argument is passed, it will be used as the `max` value and `min` will be set to 0.  
   
+If `enhancedEntropy` is set to true (false by default), the [Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues) is used for generating the random numbers.  
+Note that this makes the function call take longer, but the generated IDs will have a higher entropy.  
+  
 <details><summary><b>Example - click to view</b></summary>
 
 ```ts
 import { randRange } from "@sv443-network/userutils";
 
-randRange(0, 10);  // 4
-randRange(10, 20); // 17
-randRange(10);     // 7
+randRange(0, 10);       // 4
+randRange(10, 20);      // 17
+randRange(10);          // 7
+randRange(0, 10, true); // 4 (the devil is in the details)
+
+
+function benchmark(enhancedEntropy: boolean) {
+  const timestamp = Date.now();
+  for(let i = 0; i < 100_000; i++)
+    randRange(0, 100, enhancedEntropy);
+  console.log(`Generated 100k in ${Date.now() - timestamp}ms`)
+}
+
+// using Math.random():
+benchmark(false); // Generated 100k in 90ms
+
+// using crypto.getRandomValues():
+benchmark(true);  // Generated 100k in 461ms
+
+// about a 5x slowdown, but the generated numbers are more entropic
 ```
 </details>
 
@@ -995,44 +1022,73 @@ 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. |
+| `migrateIds?` | (Optional) A string or array of strings that migrate 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. The ID migration will be done once per session in the call to [`loadData()`](#datastoreloaddata). |
 | `storageMethod?` | (Optional) The method that is used to store the data. Can be `"GM"` (default), `"localStorage"` or `"sessionStorage"`. If you want to store the data in a different way, you can override the methods of the DataStore class. |
 | `encodeData?` | (Optional, but required when `decodeData` is set) Function that encodes the data before saving - you can use [compress()](#compress) here to save space at the cost of a little bit of performance |
 | `decodeData?` | (Optional, but required when `encodeData` is set) Function that decodes the data when loading - you can use [decompress()](#decompress) here to decode data that was previously compressed with [compress()](#compress) |
 
 <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 no data was saved in persistent storage before, the value of `options.defaultData` will be returned and also written to persistent storage before resolving.  
+If the `options.migrateIds` property is present and this is the first time calling this function in this session, the data will be migrated from the old ID(s) to the current one.  
+Then, if the `formatVersion` of the saved data is lower than the current one and the `options.migrations` property is present, the instance will try to migrate the data to the latest format before resolving, updating the in-memory cache and persistent storage.  
+
+<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.  
+Instead of calling this manually, consider setting the `migrateIds` property in the constructor to automatically migrate the data once per session in the call to `loadData()`, unless you know that you need to migrate the ID(s) manually.
+
+<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,14 +1141,16 @@ 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,
-  /** The current version of the data format */
+  /** The current version of the data format - should be a whole number that is only ever incremented */
   formatVersion,
   /** Data format migration functions called when the formatVersion is increased */
   migrations,
+  /** If the data was saved under different ID(s) before, providing them here will make sure the data is migrated to the current ID when `loadData()` is called */
+  migrateIds: ["my-data", "config"],
   /**
    * Where the data should be stored.  
    * For example, you could use `"sessionStorage"` to make the data be automatically deleted after the browser session is finished, or use `"localStorage"` if you don't have access to GM storage for some reason.
@@ -1161,12 +1219,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 +1240,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: abcdef42"
+  }
+]
+```
+
+</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 +1339,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 +1373,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 +1385,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 +1422,74 @@ 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`  
+If the dialog is not mounted yet, it will be mounted before opening.  
+
+<br>
+
+#### `Dialog.close()`
+Usage: `close(): void`  
 Closes the dialog.  
-  
-`mount(): Promise<void>`  
+If `options.destroyOnClose` is set to `true`, [`Dialog.destroy()`](#dialogdestroy) will be called immediately after closing.
+
+<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`  
-Unmounts the dialog from the DOM.  
-  
-`remount(): Promise<void>`  
+After calling, the dialog will exist in the DOM but will be invisible until [`Dialog.open()`](#dialogopen) is called.  
+Call this before opening the dialog to avoid a rendering delay.  
+
+<br>
+
+#### `Dialog.unmount()`
+Usage: `unmount(): void`  
+Closes the dialog first if it's open, then removes it from the DOM.  
+
+<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`  
+Removes all listeners by default and closes and unmounts the dialog.  
+
+<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.  
   
@@ -1392,6 +1534,10 @@ fooDialog.on("close", () => {
   console.log("Dialog closed");
 });
 
+fooDialog.on("open", () => {
+  console.log("Currently open dialogs:", Dialog.getOpenDialogs());
+});
+
 fooDialog.open();
 ```
 </details>
@@ -1471,6 +1617,7 @@ myInstance.on("foo", (bar) => {
   console.log("foo event (outside):", bar);
 });
 
+// only works if publicEmit is set to true
 myInstance.emit("baz", "hello from the outside");
 
 myInstance.unsubscribeAll();
@@ -1504,6 +1651,7 @@ myEmitter.once("baz", (qux) => {
 });
 
 function doStuff() {
+  // only works if publicEmit is set to true
   myEmitter.emit("foo", "hello");
   myEmitter.emit("baz", 42);
   myEmitter.emit("foo", "world");
@@ -1784,7 +1932,7 @@ run();
 ### randomId()
 Usage:  
 ```ts
-randomId(length?: number, radix?: number, enhancedEntropy?: boolean): string
+randomId(length?: number, radix?: number, enhancedEntropy?: boolean, randomCase?: boolean): string
 ```
   
 Generates a random ID of a given length and [radix (base).](https://en.wikipedia.org/wiki/Radix)  
@@ -1794,20 +1942,41 @@ You may change the radix to get digits from different numerical systems.
 Use 2 for binary, 8 for octal, 10 for decimal, 16 for hexadecimal and 36 for alphanumeric.  
   
 If `enhancedEntropy` is set to true (false by default), the [Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues) is used for generating the random numbers.  
-Note that this takes MUCH longer, but the generated IDs will have a higher entropy.  
+Note that this makes the function call take longer, but the generated IDs will have a higher entropy.  
+  
+If `randomCase` is set to true (which it is by default), the generated ID will contain both upper and lower case letters.  
+This randomization is also affected by the `enhancedEntropy` setting, unless there are no alphabetic characters in the output in which case it will be skipped.  
   
-⚠️ Not suitable for generating anything related to cryptography! Use [SubtleCrypto's `generateKey()`](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/generateKey) for that instead.  
+⚠️ This is not suitable for generating anything related to cryptography! Use [SubtleCrypto's `generateKey()`](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/generateKey) for that instead.  
   
 <details><summary><b>Example - click to view</b></summary>
 
 ```ts
 import { randomId } from "@sv443-network/userutils";
 
-randomId();       // "1bda419a73629d4f" (length 16, radix 16)
-randomId(10);     // "f86cd354a4"       (length 10, radix 16)
-randomId(10, 2);  // "1010001101"       (length 10, radix 2)
-randomId(10, 10); // "0183428506"       (length 10, radix 10)
-randomId(10, 36); // "z46jfpa37r"       (length 10, radix 36)
+randomId();                    // "1bda419a73629d4f" (length 16, radix 16)
+randomId(10);                  // "f86cd354a4"       (length 10, radix 16)
+randomId(10, 2);               // "1010001101"       (length 10, radix 2)
+randomId(10, 10);              // "0183428506"       (length 10, radix 10)
+randomId(10, 36, false, true); // "z46jFPa37R"       (length 10, radix 36, random case)
+
+
+function benchmark(enhancedEntropy: boolean, randomCase: boolean) {
+  const timestamp = Date.now();
+  for(let i = 0; i < 10_000; i++)
+    randomId(16, 36, enhancedEntropy, randomCase);
+  console.log(`Generated 10k in ${Date.now() - timestamp}ms`)
+}
+
+// using Math.random():
+benchmark(false, false); // Generated 10k in 239ms
+benchmark(false, true);  // Generated 10k in 248ms
+
+// using crypto.getRandomValues():
+benchmark(true, false);  // Generated 10k in 1076ms
+benchmark(true, true);   // Generated 10k in 1054ms
+
+// 3rd and 4th have a similar time, but in reality the 4th blocks the event loop for much longer
 ```
 </details>
 
@@ -2295,7 +2464,7 @@ Usage:
 NonEmptyArray<TItem = unknown>
 ```
   
-This type describes an array that has at least one item.  
+This generic type describes an array that has at least one item.  
 Use the generic parameter to specify the type of the items in the array.  
   
 <details><summary><b>Example - click to view</b></summary>
@@ -2325,7 +2494,7 @@ Usage:
 NonEmptyString<TString extends string>
 ```
   
-This type describes a string that has at least one character.  
+This generic type describes a string that has at least one character.  
   
 <details><summary><b>Example - click to view</b></summary>
 
@@ -2349,7 +2518,7 @@ Usage:
 LooseUnion<TUnion extends string | number | object>
 ```
   
-A type that offers autocomplete in the IDE for the passed union but also allows any value of the same type to be passed.  
+A generic type that offers autocomplete in the IDE for the passed union but also allows any value of the same type to be passed.  
 Supports unions of strings, numbers and objects.  
   
 <details><summary><b>Example - click to view</b></summary>
@@ -2368,6 +2537,61 @@ foo(1);   // type error: Argument of type '1' is not assignable to parameter of
 ```
 </details>
 
+<br>
+
+## Prettify
+Usage:
+```ts
+Prettify<T>
+```
+  
+A generic type that makes TypeScript and your IDE display the type in a more readable way.  
+This is especially useful for types that reference other types or are very complex.  
+It will also make a variable show its type's structure instead of just the type name (see example).  
+  
+<details><summary><b>Example - click to view</b></summary>
+
+```ts
+// tooltip shows all constituent types, leaving you to figure it out yourself:
+// type Foo = {
+//   a: number;
+// } & Omit<{
+//   b: string;
+//   c: boolean;
+// }, "c">
+type Foo = {
+  a: number;
+} & Omit<{
+  b: string;
+  c: boolean;
+}, "c">;
+
+// tooltip shows just the type name:
+// const foo: Foo
+const foo: Foo = {
+  a: 1,
+  b: "2"
+};
+
+// tooltip shows the actual type structure:
+// type Bar = {
+//   a: number;
+//   b: string;
+// }
+type Bar = Prettify<Foo>;
+
+// tooltip again shows the actual type structure:
+// const bar: {
+//   a: number;
+//   b: string;
+// }
+const bar: Bar = {
+  a: 1,
+  b: "2"
+};
+```
+</details>
+
 <br><br><br><br>
 
 <!-- #region Footer -->

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.2.0
 // @license      MIT
 // @copyright    Sv443 (https://github.com/Sv443)
 
@@ -78,12 +78,18 @@ var UserUtils = (function (exports) {
     return Math.max(Math.min(value, max), min);
   }
   function mapRange(value, range1min, range1max, range2min, range2max) {
+    if (typeof range2min === "undefined" || range2max === void 0) {
+      range2max = range1max;
+      range2min = 0;
+      range1max = range1min;
+      range1min = 0;
+    }
     if (Number(range1min) === 0 && Number(range2min) === 0)
       return value * (range2max / range1max);
     return (value - range1min) * ((range2max - range2min) / (range1max - range1min)) + range2min;
   }
   function randRange(...args) {
-    let min, max;
+    let min, max, enhancedEntropy = false;
     if (typeof args[0] === "number" && typeof args[1] === "number")
       [min, max] = args;
     else if (typeof args[0] === "number" && typeof args[1] !== "number") {
@@ -91,13 +97,25 @@ var UserUtils = (function (exports) {
       [max] = args;
     } else
       throw new TypeError(`Wrong parameter(s) provided - expected: "number" and "number|undefined", got: "${typeof args[0]}" and "${typeof args[1]}"`);
+    if (typeof args[2] === "boolean")
+      enhancedEntropy = args[2];
+    else if (typeof args[1] === "boolean")
+      enhancedEntropy = args[1];
     min = Number(min);
     max = Number(max);
     if (isNaN(min) || isNaN(max))
       return NaN;
     if (min > max)
       throw new TypeError(`Parameter "min" can't be bigger than "max"`);
-    return Math.floor(Math.random() * (max - min + 1)) + min;
+    if (enhancedEntropy) {
+      const uintArr = new Uint8Array(1);
+      crypto.getRandomValues(uintArr);
+      return Number(Array.from(
+        uintArr,
+        (v) => Math.round(mapRange(v, 0, 255, min, max)).toString(10).substring(0, 1)
+      ).join(""));
+    } else
+      return Math.floor(Math.random() * (max - min + 1)) + min;
   }
 
   // lib/array.ts
@@ -356,19 +374,25 @@ var UserUtils = (function (exports) {
       return hashHex;
     });
   }
-  function randomId(length = 16, radix = 16, enhancedEntropy = false) {
+  function randomId(length = 16, radix = 16, enhancedEntropy = false, randomCase = true) {
+    let arr = [];
+    const caseArr = randomCase ? [0, 1] : [0];
     if (enhancedEntropy) {
-      const arr = new Uint8Array(length);
-      crypto.getRandomValues(arr);
-      return Array.from(
-        arr,
+      const uintArr = new Uint8Array(length);
+      crypto.getRandomValues(uintArr);
+      arr = Array.from(
+        uintArr,
         (v) => mapRange(v, 0, 255, 0, radix).toString(radix).substring(0, 1)
-      ).join("");
+      );
+    } else {
+      arr = Array.from(
+        { length },
+        () => Math.floor(Math.random() * radix).toString(radix)
+      );
     }
-    return Array.from(
-      { length },
-      () => Math.floor(Math.random() * radix).toString(radix)
-    ).join("");
+    if (!arr.some((v) => /[a-zA-Z]/.test(v)))
+      return arr.join("");
+    return arr.map((v) => caseArr[randRange(0, caseArr.length - 1, enhancedEntropy)] === 1 ? v.toUpperCase() : v).join("");
   }
 
   // lib/DataStore.ts
@@ -392,12 +416,15 @@ var UserUtils = (function (exports) {
       __publicField(this, "storageMethod");
       __publicField(this, "cachedData");
       __publicField(this, "migrations");
+      __publicField(this, "migrateIds", []);
       var _a;
       this.id = options.id;
       this.formatVersion = options.formatVersion;
       this.defaultData = options.defaultData;
       this.cachedData = options.defaultData;
       this.migrations = options.migrations;
+      if (options.migrateIds)
+        this.migrateIds = Array.isArray(options.migrateIds) ? options.migrateIds : [options.migrateIds];
       this.storageMethod = (_a = options.storageMethod) != null ? _a : "GM";
       this.encodeData = options.encodeData;
       this.decodeData = options.decodeData;
@@ -411,6 +438,10 @@ var UserUtils = (function (exports) {
     loadData() {
       return __async(this, null, function* () {
         try {
+          if (this.migrateIds.length > 0) {
+            yield this.migrateId(this.migrateIds);
+            this.migrateIds = [];
+          }
           const gmData = yield this.getValue(`_uucfg-${this.id}`, JSON.stringify(this.defaultData));
           let gmFmtVer = Number(yield this.getValue(`_uucfgver-${this.id}`, NaN));
           if (typeof gmData !== "string") {
@@ -478,7 +509,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 +563,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 +729,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

@@ -58,12 +58,18 @@ function clamp(value, min, max) {
   return Math.max(Math.min(value, max), min);
 }
 function mapRange(value, range1min, range1max, range2min, range2max) {
+  if (typeof range2min === "undefined" || range2max === void 0) {
+    range2max = range1max;
+    range2min = 0;
+    range1max = range1min;
+    range1min = 0;
+  }
   if (Number(range1min) === 0 && Number(range2min) === 0)
     return value * (range2max / range1max);
   return (value - range1min) * ((range2max - range2min) / (range1max - range1min)) + range2min;
 }
 function randRange(...args) {
-  let min, max;
+  let min, max, enhancedEntropy = false;
   if (typeof args[0] === "number" && typeof args[1] === "number")
     [min, max] = args;
   else if (typeof args[0] === "number" && typeof args[1] !== "number") {
@@ -71,13 +77,25 @@ function randRange(...args) {
     [max] = args;
   } else
     throw new TypeError(`Wrong parameter(s) provided - expected: "number" and "number|undefined", got: "${typeof args[0]}" and "${typeof args[1]}"`);
+  if (typeof args[2] === "boolean")
+    enhancedEntropy = args[2];
+  else if (typeof args[1] === "boolean")
+    enhancedEntropy = args[1];
   min = Number(min);
   max = Number(max);
   if (isNaN(min) || isNaN(max))
     return NaN;
   if (min > max)
     throw new TypeError(`Parameter "min" can't be bigger than "max"`);
-  return Math.floor(Math.random() * (max - min + 1)) + min;
+  if (enhancedEntropy) {
+    const uintArr = new Uint8Array(1);
+    crypto.getRandomValues(uintArr);
+    return Number(Array.from(
+      uintArr,
+      (v) => Math.round(mapRange(v, 0, 255, min, max)).toString(10).substring(0, 1)
+    ).join(""));
+  } else
+    return Math.floor(Math.random() * (max - min + 1)) + min;
 }
 
 // lib/array.ts
@@ -336,19 +354,25 @@ function computeHash(input, algorithm = "SHA-256") {
     return hashHex;
   });
 }
-function randomId(length = 16, radix = 16, enhancedEntropy = false) {
+function randomId(length = 16, radix = 16, enhancedEntropy = false, randomCase = true) {
+  let arr = [];
+  const caseArr = randomCase ? [0, 1] : [0];
   if (enhancedEntropy) {
-    const arr = new Uint8Array(length);
-    crypto.getRandomValues(arr);
-    return Array.from(
-      arr,
+    const uintArr = new Uint8Array(length);
+    crypto.getRandomValues(uintArr);
+    arr = Array.from(
+      uintArr,
       (v) => mapRange(v, 0, 255, 0, radix).toString(radix).substring(0, 1)
-    ).join("");
+    );
+  } else {
+    arr = Array.from(
+      { length },
+      () => Math.floor(Math.random() * radix).toString(radix)
+    );
   }
-  return Array.from(
-    { length },
-    () => Math.floor(Math.random() * radix).toString(radix)
-  ).join("");
+  if (!arr.some((v) => /[a-zA-Z]/.test(v)))
+    return arr.join("");
+  return arr.map((v) => caseArr[randRange(0, caseArr.length - 1, enhancedEntropy)] === 1 ? v.toUpperCase() : v).join("");
 }
 
 // lib/DataStore.ts
@@ -372,12 +396,15 @@ var DataStore = class {
     __publicField(this, "storageMethod");
     __publicField(this, "cachedData");
     __publicField(this, "migrations");
+    __publicField(this, "migrateIds", []);
     var _a;
     this.id = options.id;
     this.formatVersion = options.formatVersion;
     this.defaultData = options.defaultData;
     this.cachedData = options.defaultData;
     this.migrations = options.migrations;
+    if (options.migrateIds)
+      this.migrateIds = Array.isArray(options.migrateIds) ? options.migrateIds : [options.migrateIds];
     this.storageMethod = (_a = options.storageMethod) != null ? _a : "GM";
     this.encodeData = options.encodeData;
     this.decodeData = options.decodeData;
@@ -391,6 +418,10 @@ var DataStore = class {
   loadData() {
     return __async(this, null, function* () {
       try {
+        if (this.migrateIds.length > 0) {
+          yield this.migrateId(this.migrateIds);
+          this.migrateIds = [];
+        }
         const gmData = yield this.getValue(`_uucfg-${this.id}`, JSON.stringify(this.defaultData));
         let gmFmtVer = Number(yield this.getValue(`_uucfgver-${this.id}`, NaN));
         if (typeof gmData !== "string") {
@@ -458,7 +489,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 +543,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 +709,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.
      */
@@ -29,10 +33,17 @@ export type DataStoreOptions<TData> = {
      * If the current format version is not in the dictionary, no migrations will be run.
      */
     migrations?: DataMigrationsDict;
+    /**
+     * If an ID or multiple IDs are passed here, the data will be migrated from the old ID(s) to the current ID.
+     * This will happen once per page load, when {@linkcode DataStore.loadData()} is called.
+     * All future calls to {@linkcode DataStore.loadData()} in the session will not check for the old ID(s) anymore.
+     * To migrate IDs manually, use the method {@linkcode DataStore.migrateId()} instead.
+     */
+    migrateIds?: string | string[];
     /**
      * 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 +68,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;
@@ -77,6 +90,7 @@ export declare class DataStore<TData extends object = object> {
     readonly storageMethod: Required<DataStoreOptions<TData>>["storageMethod"];
     private cachedData;
     private migrations?;
+    private migrateIds;
     /**
      * Creates an instance of DataStore to manage a sync & async database that is cached in memory and persistently saved across sessions.
      * Supports migrating data from older versions to newer ones and populating the cache with default data if no persistent data is found.
@@ -109,7 +123,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 +136,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/dist/lib/crypto.d.ts

@@ -19,6 +19,7 @@ export declare function computeHash(input: string | ArrayBuffer, algorithm?: str
  * ⚠️ Not suitable for generating anything related to cryptography! Use [SubtleCrypto's `generateKey()`](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/generateKey) for that instead.
  * @param length The length of the ID to generate (defaults to 16)
  * @param radix The [radix](https://en.wikipedia.org/wiki/Radix) of each digit (defaults to 16 which is hexadecimal. Use 2 for binary, 10 for decimal, 36 for alphanumeric, etc.)
- * @param enhancedEntropy If set to true, uses [`crypto.getRandomValues()`](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues) for better cryptographic randomness (this also makes it take MUCH longer to generate)
+ * @param enhancedEntropy If set to true, uses [`crypto.getRandomValues()`](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues) for better cryptographic randomness (this also makes it take longer to generate)
+ * @param randomCase If set to false, the generated ID will be lowercase only - also makes use of the `enhancedEntropy` parameter unless the output doesn't contain letters
  */
-export declare function randomId(length?: number, radix?: number, enhancedEntropy?: boolean): string;
+export declare function randomId(length?: number, radix?: number, enhancedEntropy?: boolean, randomCase?: boolean): string;

package/dist/lib/math.d.ts

@@ -1,11 +1,22 @@
 /** Ensures the passed {@linkcode value} always stays between {@linkcode min} and {@linkcode max} */
 export declare function clamp(value: number, min: number, max: number): number;
 /**
- * Transforms the value parameter from the numerical range `range1min─range1max` to the numerical range `range2min─range2max`
+ * Transforms the value parameter from the numerical range `range1min` to `range1max` to the numerical range `range2min` to `range2max`
  * For example, you can map the value 2 in the range of 0-5 to the range of 0-10 and you'd get a 4 as a result.
  */
 export declare function mapRange(value: number, range1min: number, range1max: number, range2min: number, range2max: number): number;
-/** Returns a random number between {@linkcode min} and {@linkcode max} (inclusive) */
-export declare function randRange(min: number, max: number): number;
-/** Returns a random number between 0 and {@linkcode max} (inclusive) */
-export declare function randRange(max: number): number;
+/**
+ * Transforms the value parameter from the numerical range `0` to `range1max` to the numerical range `0` to `range2max`
+ * For example, you can map the value 2 in the range of 0-5 to the range of 0-10 and you'd get a 4 as a result.
+ */
+export declare function mapRange(value: number, range1max: number, range2max: number): number;
+/**
+ * Returns a random number between {@linkcode min} and {@linkcode max} (inclusive)
+ * Set {@linkcode enhancedEntropy} to true to use `crypto.getRandomValues()` for better cryptographic randomness (this also makes it take longer to generate)
+ */
+export declare function randRange(min: number, max: number, enhancedEntropy?: boolean): number;
+/**
+ * Returns a random number between 0 and {@linkcode max} (inclusive)
+ * Set {@linkcode enhancedEntropy} to true to use `crypto.getRandomValues()` for better cryptographic randomness (this also makes it take longer to generate)
+ */
+export declare function randRange(max: number, enhancedEntropy?: boolean): number;

package/dist/lib/types.d.ts

@@ -15,3 +15,10 @@ export type LooseUnion<TUnion extends string | number | object> = (TUnion) | (TU
  * }
  */
 export type NonEmptyString<TString extends string> = TString extends "" ? never : TString;
+/**
+ * Makes the structure of a type more readable by expanding it.
+ * This can be useful for debugging or for improving the readability of complex types.
+ */
+export type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sv443-network/userutils",
   "libName": "UserUtils",
-  "version": "8.0.2",
+  "version": "8.2.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",