@sv443-network/userutils 8.1.0 → 8.2.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @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

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>
 
@@ -930,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>
 
@@ -948,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:
@@ -960,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>
 
@@ -1008,6 +1026,7 @@ The options object has the following properties:
 | `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) |
@@ -1018,8 +1037,9 @@ The options object has the following properties:
 #### `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.
+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>
 
@@ -1062,7 +1082,8 @@ If `resetOnError` is set to `false`, the migration will be aborted if an error i
 #### `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.
+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>
 
@@ -1124,10 +1145,12 @@ export const manager = new DataStore({
   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.
@@ -1254,7 +1277,7 @@ See the [`DataStore.loadData()`](#datastoreloaddata) method for more information
   },
   {
     "status": "rejected",
-    "reason": "Checksum mismatch for DataStore with ID \"bar-data\"!\nExpected: 69beefdead420\nHas: 420abcdef69"
+    "reason": "Checksum mismatch for DataStore with ID \"bar-data\"!\nExpected: 69beefdead420\nHas: abcdef42"
   }
 ]
 ```
@@ -1406,25 +1429,28 @@ The options object has the following properties:
 #### `Dialog.open()`
 Usage: `open(): Promise<void>`  
 Opens the dialog.  
+If the dialog is not mounted yet, it will be mounted before opening.  
 
 <br>
 
 #### `Dialog.close()`
 Usage: `close(): void`  
 Closes the dialog.  
+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.  
+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`  
-Unmounts the dialog from the DOM.  
+Closes the dialog first if it's open, then removes it from the DOM.  
 
 <br>
 
@@ -1451,7 +1477,7 @@ Returns `true` if the dialog is mounted, else `false`.
 #### `Dialog.destroy()`
 Usage: `destroy(): void`  
 Destroys the dialog.  
-Removes all listeners and unmounts the dialog by default.  
+Removes all listeners by default and closes and unmounts the dialog.  
 
 <br>
 
@@ -1508,6 +1534,10 @@ fooDialog.on("close", () => {
   console.log("Dialog closed");
 });
 
+fooDialog.on("open", () => {
+  console.log("Currently open dialogs:", Dialog.getOpenDialogs());
+});
+
 fooDialog.open();
 ```
 </details>
@@ -1587,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();
@@ -1620,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");
@@ -1900,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)  
@@ -1910,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>
 
@@ -2411,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>
@@ -2441,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>
 
@@ -2465,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>
@@ -2484,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.1.0
+// @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") {

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") {

package/dist/lib/DataStore.d.ts

@@ -33,6 +33,13 @@ 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 {@linkcode DataStore.getValue()}, {@linkcode DataStore.setValue()}  and {@linkcode DataStore.deleteValue()} are used to interact with the storage.
@@ -83,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.

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.1.0",
+  "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",