@sv443-network/userutils 8.3.3 → 8.4.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @sv443-network/userutils
 
+## 8.4.0
+
+### Minor Changes
+
+- e10d629: Added function `digitCount()` to calculate the amount of digits in the passed number
+- 949877a: Added support for nested objects in translations (e.g. `tr("foo.bar.baz")`)
+- 52d392a: Added `ValueGen` and `StringGen` types with accompanying `consumeGen()` and `consumeStringGen()` functions to allow for super flexible typing and declaration of values
+- bbce0e1: Added overload to `clamp()` without `min` parameter
+
 ## 8.3.3
 
 ### Patch Changes

package/README.md

@@ -23,7 +23,7 @@ View the documentation of previous major releases:
 </sup>
 <sub>
 
-<a href="https://github.com/Sv443-Network/UserUtils/blob/v7.3.0/README.md" rel="noopener noreferrer">7.3.0</a>, <a href="https://github.com/Sv443-Network/UserUtils/blob/v6.3.0/README.md" rel="noopener noreferrer">6.3.0</a>, <a href="https://github.com/Sv443-Network/UserUtils/blob/v5.0.1/README.md" rel="noopener noreferrer">5.0.1</a>, <a href="https://github.com/Sv443-Network/UserUtils/blob/v4.2.1/README.md" rel="noopener noreferrer">4.2.1</a>, <a href="https://github.com/Sv443-Network/UserUtils/blob/v3.0.0/README.md" rel="noopener noreferrer">3.0.0</a>, <a href="https://github.com/Sv443-Network/UserUtils/blob/v2.0.1/README.md" rel="noopener noreferrer">2.0.1</a>, <a href="https://github.com/Sv443-Network/UserUtils/blob/v1.2.0/README.md" rel="noopener noreferrer">1.2.0</a>, <a href="https://github.com/Sv443-Network/UserUtils/blob/v0.5.3/README.md" rel="noopener noreferrer">0.5.3</a>
+<a href="https://github.com/Sv443-Network/UserUtils/blob/v8.0.0/README.md" rel="noopener noreferrer">8.0.0</a>, <a href="https://github.com/Sv443-Network/UserUtils/blob/v7.0.0/README.md" rel="noopener noreferrer">7.0.0</a>, <a href="https://github.com/Sv443-Network/UserUtils/blob/v6.0.0/README.md" rel="noopener noreferrer">6.0.0</a>, <a href="https://github.com/Sv443-Network/UserUtils/blob/v5.0.0/README.md" rel="noopener noreferrer">5.0.0</a>, <a href="https://github.com/Sv443-Network/UserUtils/blob/v4.0.0/README.md" rel="noopener noreferrer">4.0.0</a>, <a href="https://github.com/Sv443-Network/UserUtils/blob/v3.0.0/README.md" rel="noopener noreferrer">3.0.0</a>, <a href="https://github.com/Sv443-Network/UserUtils/blob/v2.0.0/README.md" rel="noopener noreferrer">2.0.0</a>, <a href="https://github.com/Sv443-Network/UserUtils/blob/v1.0.0/README.md" rel="noopener noreferrer">1.0.0</a>, <a href="https://github.com/Sv443-Network/UserUtils/blob/v0.5.3/README.md" rel="noopener noreferrer">0.5.3</a>
 
 </sub>
 </div>
@@ -52,6 +52,7 @@ View the documentation of previous major releases:
     - [`clamp()`](#clamp) - constrain a number between a min and max value
     - [`mapRange()`](#maprange) - map a number from one range to the same spot in another range
     - [`randRange()`](#randrange) - generate a random number between a min and max boundary
+    - [`digitCount()`](#digitcount) - calculate the amount of digits in a number
   - [**Misc:**](#misc)
     - [`DataStore`](#datastore) - class that manages a hybrid sync & async persistent JSON database, including data migration
     - [`DataStoreSerializer`](#datastoreserializer) - class for importing & exporting data of multiple DataStore instances, including compression, checksumming and running migrations
@@ -66,14 +67,16 @@ View the documentation of previous major releases:
     - [`decompress()`](#decompress) - decompress a previously compressed string
     - [`computeHash()`](#computehash) - compute the hash / checksum of a string or ArrayBuffer
     - [`randomId()`](#randomid) - generate a random ID of a given length and radix
+    - [`consumeGen()`](#consumegen) - consumes a ValueGen and returns the value
+    - [`consumeStringGen()`](#consumestringgen) - consumes a StringGen and returns the string
   - [**Arrays:**](#arrays)
     - [`randomItem()`](#randomitem) - returns a random item from an array
     - [`randomItemIndex()`](#randomitemindex) - returns a tuple of a random item and its index from an array
     - [`takeRandomItem()`](#takerandomitem) - returns a random item from an array and mutates it to remove the item
     - [`randomizeArray()`](#randomizearray) - returns a copy of the array with its items in a random order
   - [**Translation:**](#translation)
-    - [`tr()`](#tr) - simple translation of a string to another language
-    - [`tr.forLang()`](#trforlang) - specify a language besides the currently set one for the translation
+    - [`tr()`](#tr) - simple JSON-based translation system with placeholder and nesting support
+    - [`tr.forLang()`](#trforlang) - translate with the specified language instead of the currently active one
     - [`tr.addLanguage()`](#traddlanguage) - add a language and its translations
     - [`tr.setLanguage()`](#trsetlanguage) - set the currently active language for translations
     - [`tr.getLanguage()`](#trgetlanguage) - returns the currently active language
@@ -89,6 +92,8 @@ View the documentation of previous major releases:
     - [`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
+    - [`ValueGen`](#valuegen) - a "generator" value that allows for super flexible value typing and declaration
+    - [`StringGen`](#stringgen) - a "generator" string that allows for super flexible string typing and declaration, including enhanced support for unions
 
 <br><br>
 
@@ -952,9 +957,11 @@ setInnerHtmlUnsafe(myXssElement, userModifiableVariable);
 Usage:  
 ```ts
 clamp(num: number, min: number, max: number): number
+clamp(num: number, max: number): number
 ```
   
 Clamps a number between a min and max boundary (inclusive).  
+If only the `num` and `max` arguments are passed, the `min` boundary will be set to 0.  
   
 <details><summary><b>Example - click to view</b></summary>
 
@@ -962,13 +969,14 @@ Clamps a number between a min and max boundary (inclusive).
 import { clamp } from "@sv443-network/userutils";
 
 clamp(7, 0, 10);     // 7
-clamp(-1, 0, 10);    // 0
+clamp(7, 10);        // 7 (equivalent to the above)
+clamp(-1, 10);       // 0
 clamp(5, -5, 0);     // 0
 clamp(99999, 0, 10); // 10
 
-// clamp without a min or max boundary:
-clamp(-99999, -Infinity, 0); // -99999
-clamp(99999, 0, Infinity);   // 99999
+// use Infinity to clamp without a min or max boundary:
+clamp(Number.MAX_SAFE_INTEGER, Infinity);     // 9007199254740991
+clamp(Number.MIN_SAFE_INTEGER, -Infinity, 0); // -9007199254740991
 ```
 </details>
 
@@ -1042,6 +1050,40 @@ benchmark(true);  // Generated 100k in 461ms
 ```
 </details>
 
+<br>
+
+### digitCount()
+Usage:  
+```ts
+digitCount(num: number | Stringifiable): number
+```
+  
+Calculates and returns the amount of digits in the given number.  
+The given value will be converted by being passed to `String()` and then `Number()` before the calculation.  
+Returns `NaN` if the number is invalid.  
+  
+<details><summary><b>Example - click to view</b></summary>
+
+```ts
+import { digitCount } from "@sv443-network/userutils";
+
+const num1 = 123;
+const num2 = 123456789;
+const num3 = "  123456789    ";
+const num4 = Number.MAX_SAFE_INTEGER;
+const num5 = "a123b456c789d";
+const num6 = parseInt("0x123456789abcdef", 16);
+
+digitCount(num1); // 3
+digitCount(num2); // 9
+digitCount(num3); // 9
+digitCount(num4); // 16
+digitCount(num5); // NaN (because hex conversion has to be done through parseInt(str, 16)), like below:
+digitCount(num6); // 17
+```
+
+</details>
+
 <br><br>
 
 <!-- #region Misc -->
@@ -1728,15 +1770,15 @@ If an array or NodeList is passed, the amount of contained items will be used.
 ```ts
 import { autoPlural } from "@sv443-network/userutils";
 
-autoPlural("apple", 0); // "apples"
-autoPlural("apple", 1); // "apple"
-autoPlural("apple", 2); // "apples"
+autoPlural("item", 0); // "items"
+autoPlural("item", 1); // "item"
+autoPlural("item", 2); // "items"
 
-autoPlural("apple", [1]);    // "apple"
-autoPlural("apple", [1, 2]); // "apples"
+autoPlural("element", document.querySelectorAll("html")); // "element"
+autoPlural("element", document.querySelectorAll("*"));    // "elements"
 
 const items = [1, 2, 3, 4, "foo", "bar"];
-console.log(`Found ${items.length} ${autoPlural("item", items)}`); // "Found 6 items"
+console.log(items.length, autoPlural("item", items)); // "6 items"
 ```
 </details>
 
@@ -2037,6 +2079,85 @@ benchmark(true, true);   // Generated 10k in 1054ms
 
 <br><br>
 
+### consumeGen()
+Usage:  
+```ts
+consumeGen(valGen: ValueGen): 
+```
+  
+Turns a [`ValueGen`](#valuegen) into its final value.  
+ValueGen allows for tons of flexibility in how the value can be obtained. Calling this function will resolve the final value.  
+  
+<details><summary><b>Example - click to view</b></summary>
+
+```ts
+import { consumeGen, type ValueGen } from "@sv443-network/userutils";
+
+async function doSomething(value: ValueGen<number>) {
+  // type gets inferred as `number` because above `value` is typed as a ValueGen<number>
+  const finalValue = await consumeGen(value);
+  console.log(finalValue);
+}
+
+// the following are all valid and yield 42:
+doSomething(42);
+doSomething(() => 42);
+doSomething(Promise.resolve(42));
+doSomething(async () => 42);
+
+// throws a typescript error:
+doSomething("foo");
+```
+
+</details>
+
+<br><br>
+
+### consumeStringGen()
+Usage:  
+```ts
+consumeStringGen(strGen: StringGen): Promise<string>
+```
+  
+Turns a [`StringGen`](#stringgen) into its final string value.  
+StringGen allows for tons of flexibility in how the string can be obtained. Calling this function will resolve the final string.  
+Optionally you can use the template parameter to define the union of strings that the StringGen should yield.  
+  
+<details><summary><b>Example - click to view</b></summary>
+
+```ts
+import { consumeStringGen, type StringGen } from "@sv443-network/userutils";
+
+export class MyTextPromptThing {
+  // full flexibility on how the string can be passed to the constructor,
+  // because it can be obtained synchronously or asynchronously,
+  // in string or function form:
+  constructor(private text: StringGen) {}
+
+  /** Shows the prompt dialog */
+  public async showPrompt() {
+    const promptText = await consumeStringGen(this.text);
+    const promptHtml = promptText.trim().replace(/\n/g, "<br>");
+
+    // ...
+  }
+}
+
+// all valid:
+const myText = "Hello, World!";
+new MyTextPromptThing(myText);
+new MyTextPromptThing(() => myText);
+new MyTextPromptThing(Promise.resolve(myText));
+new MyTextPromptThing(async () => myText);
+
+// throws a typescript error:
+new MyTextPromptThing(420);
+```
+
+</details>
+
+<br><br>
+
 <!-- #region Arrays -->
 ## Arrays:
 
@@ -2144,43 +2265,63 @@ Pluralization is not supported but can be achieved manually by adding variations
 ### tr()
 Usage:  
 ```ts
-tr(key: string, ...values: Stringifiable[]): string
+tr(key: string, ...insertValues: Stringifiable[]): string
 ```
   
 The function returns the translation of the passed key in the language added by [`tr.addLanguage()`](#traddlanguage) and set by [`tr.setLanguage()`](#trsetlanguage)  
-Should the translation contain placeholders in the format `%n`, where `n` is the number of the value starting at 1, they will be replaced with the respective item of the `values` rest parameter.  
-The items of the `values` rest parameter will be stringified using `toString()` (see [Stringifiable](#stringifiable)) before being inserted into the translation.
+Should the translation contain placeholders in the format `%n`, where `n` is the number of the value starting at 1, they will be replaced with the respective item of the `insertValues` rest parameter.  
+The items of the `insertValues` rest parameter will be stringified using `toString()` (see [Stringifiable](#stringifiable)) before being inserted into the translation.
+  
+Should you be using nested objects in your translations, you can use the dot notation to access them.  
+First, the key will be split by dots and the parts will be used to traverse the translation object.  
+If that doesn't yield a result, the function will try to access the key including dots on the top level of the translation object.  
+If that also doesn't yield a result, the key itself will be returned.  
+  
+If no language has been added or set before calling this function, it will also return the key itself.  
+  
+To check if a translation has been found, compare the returned value with the key. If they are the same, the translation was not found.  
+You could also write a wrapper function that can then return a default value or `null` if the translation was not found instead.  
   
-If the key is not found or no language has been added or set before calling this function, it will return the key itself.  
-If the key is found and the translation contains placeholders but no values are passed, it will return the translation as-is, including unmodified placeholders.  
-If the key is found, the translation doesn't contain placeholders but values are still passed, they will be ignored and the translation will be returned as-is.  
+If the key is found and the translation contains placeholders but none or an insufficient amount of values are passed, it will try to insert as many values as were passed and leave the rest of the placeholders untouched in their `%n` format.  
+If the key is found, the translation doesn't contain placeholders but values are still passed, the values will be ignored and the translation will be returned without modification.  
   
 <details><summary><b>Example - click to view</b></summary>
 
 ```ts
 import { tr } from "@sv443-network/userutils";
 
+// add languages and translations:
 tr.addLanguage("en", {
-  "welcome": "Welcome",
-  "welcome_name": "Welcome, %1",
+  welcome: {
+    generic: "Welcome",
+    with_name: "Welcome, %1",
+  },
 });
+
 tr.addLanguage("de", {
-  "welcome": "Willkommen",
-  "welcome_name": "Willkommen, %1",
+  welcome: {
+    generic: "Willkommen",
+    with_name: "Willkommen, %1",
+  },
 });
 
 // this has to be called at least once before calling tr()
 tr.setLanguage("en");
 
-console.log(tr("welcome"));              // "Welcome"
-console.log(tr("welcome_name", "John")); // "Welcome, John"
-console.log(tr("non_existent_key"));     // "non_existent_key"
+console.log(tr("welcome.generic"));           // "Welcome"
+console.log(tr("welcome.with_name", "John")); // "Welcome, John"
+
+console.log(tr("non_existent_key")); // "non_existent_key"
+console.log(tr("welcome"));          // "welcome" (because anything that isn't a string will make the function return the key itself)
 
 // language can be changed at any time, synchronously
 tr.setLanguage("de");
 
-console.log(tr("welcome"));              // "Willkommen"
-console.log(tr("welcome_name", "John")); // "Willkommen, John"
+console.log(tr("welcome.generic")); // "Willkommen"
+
+// or without overwriting the current language:
+
+console.log(tr.forLang("en", "welcome.generic")); // "Welcome"
 ```
 </details>
 
@@ -2189,7 +2330,7 @@ console.log(tr("welcome_name", "John")); // "Willkommen, John"
 ### tr.forLang()
 Usage:  
 ```ts
-tr.forLang(language: string, key: string, ...values: Stringifiable[]): string
+tr.forLang(language: string, key: string, ...insertValues: Stringifiable[]): string
 ```  
   
 Returns the translation of the passed key in the specified language. Otherwise behaves exactly like [`tr()`](#tr)  
@@ -2222,12 +2363,12 @@ console.log(tr.forLang("de", "welcome_name", "John")); // "Willkommen, John"
 ### tr.addLanguage()
 Usage:  
 ```ts
-tr.addLanguage(language: string, translations: Record<string, string>): void
+tr.addLanguage(language: string, translations: Record<string, string | object>): void
 ```
 
 Adds or overwrites a language and its associated translations to the translation function.  
 The passed language can be any unique identifier, though I highly recommend sticking to a standard like [BCP 47 / RFC 5646](https://www.rfc-editor.org/rfc/rfc5646.txt) (which is used by the [`Intl` namespace](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl) and methods like [`Number.toLocaleString()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toLocaleString)), or [ISO 639-1.](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)  
-The passed translations should be a flat object (no nested objects are allowed for now), where the key is the translation key used in `tr()` and the value is the translation itself.  
+The passed translations can either be a flat object where the key is the translation key used in `tr()` and the value is the translation itself, or an infinitely nestable object structure containing the same.  
 If `tr.addLanguage()` is called multiple times with the same language, the previous translations of that language will be overwritten.  
   
 The translation values may contain placeholders in the format `%n`, where `n` is the number of the value starting at 1.  
@@ -2236,42 +2377,46 @@ These can be used to inject values into the translation when calling `tr()`
 <details><summary><b>Example - click to view</b></summary>
 
 ```ts
-import { tr } from "@sv443-network/userutils";
+import { tr, type Stringifiable } from "@sv443-network/userutils";
 
 // add a language with associated translations:
 
-tr.addLanguage("de", {
-  "color": "Farbe",
+tr.addLanguage("en", {
+  lang_name: "Eglis", // no worries, the example below will overwrite this value
 });
 
-
-// with placeholders:
+// overwriting previous translation, now with nested objects and placeholders:
 
 tr.addLanguage("en", {
-  "welcome_generic": "Welcome!",
-  "welcome_name": "Welcome, %1!",
-  "welcome_extended": "Welcome, %1!\nYour last login was on %2\nYou have %3 unread messages",
+  // to get this value, you could call `tr.forLang("en", "lang_name")`
+  lang_name: "English",
+  home_page: {
+    welcome: {
+      generic: "Welcome!",
+      // this can be accessed with `tr("home_page.welcome.name", "John")`
+      name: "Welcome, %1!",
+      extended: "Welcome, %1!\nYour last login was on %2\nYou have %3 unread messages",
+    },
+  },
 });
 
-
 // can be used for different locales too:
 
 tr.addLanguage("en-US", {
-  "fries": "fries",
-  "color": "color",
+  fries: "fries",
+  color: "color",
 });
 
 tr.addLanguage("en-GB", {
-  "fries": "chips",
-  "color": "colour",
+  fries: "chips",
+  color: "colour",
 });
 
-
 // apply default values for different locales to reduce redundancy in shared translation values:
 
 const translation_de = {
-  "greeting": "Guten Tag!",
-  "foo": "Foo",
+  greeting: "Guten Tag!",
+  foo: "Foo",
 };
 
 tr.addLanguage("de-DE", translation_de);
@@ -2279,17 +2424,16 @@ tr.addLanguage("de-DE", translation_de);
 tr.addLanguage("de-CH", {
   // overwrite the "greeting" but keep other keys as they are:
   ...translation_de,
-  "greeting": "Grüezi!",
+  greeting: "Grüezi!",
 });
 
 tr.addLanguage("de-AT", {
   // overwrite "greeting" again but keep other keys as they are:
   ...translation_de,
-  "greeting": "Grüß Gott!",
+  greeting: "Grüß Gott!",
 });
 
-
-// example for custom pluralization:
+// example for custom pluralization using a predefined suffix:
 
 tr.addLanguage("en", {
   "cart_items_added-0": "No items were added to the cart",
@@ -2297,10 +2441,14 @@ tr.addLanguage("en", {
   "cart_items_added-n": "Added %1 items to the cart",
 });
 
+/** A number or any object with a length or size property */
 type Numberish = number | Array<unknown> | NodeList | { length: number } | { size: number };
 
-/** Returns the translation key with a custom pluralization identifier added to it for the given number of items (or size of Array/NodeList or anything else with a `length` or `size` property) */
-function pl(key: string, num: Numberish): string {
+/**
+ * Returns the translated value given the key with a common pluralization identifier appended to it,  
+ * given the number of items (or size of Array/NodeList or anything else with a `length` or `size` property).
+ */
+function trpl(key: string, num: Numberish, ...values: Stringifiable[]): string {
   if(typeof num !== "number") {
     if("length" in num)
       num = num.length;
@@ -2308,25 +2456,32 @@ function pl(key: string, num: Numberish): string {
       num = num.size;
   }
 
+  let plKey = key;
   if(num === 0)
-    return `${key}-0`;
+    plKey = `${key}-0`;
   else if(num === 1)
-    return `${key}-1`;
+    plKey = `${key}-1`;
   else
-    return `${key}-n`; // will also be the fallback for non-numeric values
+    plKey = `${key}-n`; // will be the fallback for everything like non-numeric values or NaN
+
+  return tr(plKey, ...values);
 };
 
+// this has to be called once for tr("key") to work - otherwise you can use tr.forLang("en", "key")
+tr.setLanguage("en");
+
 const items = [];
-console.log(tr(pl("cart_items_added", items), items.length)); // "No items were added to the cart"
+console.log(trpl("cart_items_added", items, items.length)); // "No items were added to the cart"
 
 items.push("foo");
-console.log(tr(pl("cart_items_added", items), items.length)); // "Added 1 item to the cart"
+console.log(trpl("cart_items_added", items, items.length)); // "Added 1 item to the cart"
 
 items.push("bar");
-console.log(tr(pl("cart_items_added", items), items.length)); // "Added 2 items to the cart"
+console.log(trpl("cart_items_added", items, items.length)); // "Added 2 items to the cart"
 
-// you will need to catch cases like this manually or in your own implementation of `pl()`:
-console.log(tr(pl("cart_items_added", NaN), NaN)); // "Added NaN items to the cart"
+// if you run across cases like this, you need to modify your implementation of `trpl()` accordingly:
+const someVal = parseInt("not a number");
+console.log(trpl("cart_items_added", someVal, someVal)); // "Added NaN items to the cart"
 ```
 </details>
 
@@ -2338,10 +2493,11 @@ Usage:
 tr.setLanguage(language: string): void
 ```
 
-Synchronously sets the language that will be used for translations.  
+Synchronously sets the language that will be used for translations by default.  
+Alternatively, you can use [`tr.forLang()`](#trforlang) to get translations in a different language without changing the current language.  
 No validation is done on the passed language, so make sure it is correct and it has been added with `tr.addLanguage()` before calling `tr()`  
   
-For an example, see [`tr()`](#tr)
+For an example, please see [`tr()`](#tr)
 
 <br>
 
@@ -2359,7 +2515,7 @@ If no language has been set yet, it will return undefined.
 ### tr.getTranslations()
 Usage:  
 ```ts
-tr.getTranslations(language?: string): Record<string, string> | undefined
+tr.getTranslations(language?: string): Record<string, string | object> | undefined
 ```  
   
 Returns the translations of the specified language.  
@@ -2372,7 +2528,7 @@ If no translations are found, it will return undefined.
 import { tr } from "@sv443-network/userutils";
 
 tr.addLanguage("en", {
-  "welcome": "Welcome",
+  welcome: "Welcome",
 });
 
 console.log(tr.getTranslations());     // undefined
@@ -2528,7 +2684,7 @@ logSomething(barObject); // Type error
 
 <br>
 
-## NonEmptyArray
+### NonEmptyArray
 Usage:
 ```ts
 NonEmptyArray<TItem = unknown>
@@ -2558,7 +2714,7 @@ logFirstItem(["04abc", "69"]); // 4
 
 <br>
 
-## NonEmptyString
+### NonEmptyString
 Usage:
 ```ts
 NonEmptyString<TString extends string>
@@ -2582,7 +2738,7 @@ convertToNumber("");      // type error: Argument of type 'string' is not assign
 
 <br>
 
-## LooseUnion
+### LooseUnion
 Usage:
 ```ts
 LooseUnion<TUnion extends string | number | object>
@@ -2609,7 +2765,7 @@ foo(1);   // type error: Argument of type '1' is not assignable to parameter of
 
 <br>
 
-## Prettify
+### Prettify
 Usage:
 ```ts
 Prettify<T>
@@ -2662,6 +2818,29 @@ const bar: Bar = {
 ```
 </details>
 
+<br><br>
+
+### ValueGen
+Usage:
+```ts
+ValueGen<TValueType>
+```
+  
+Describes a value that can be obtained in various ways, including via the type itself, a function that returns the type, a Promise that resolves to the type or either a sync or an async function that returns the type.  
+Use it in the [`consumeGen()`](#consumegen) function to convert the given ValueGen value to the type it represents. Also refer to that function for an example.  
+
+<br><br>
+
+### StringGen
+Usage:
+```ts
+StringGen<TStrUnion>
+```
+  
+Describes a string that can be obtained in various ways, including via the type itself, a function that returns the type, a Promise that resolves to the type or either a sync or an async function that returns the type.  
+Contrary to [`ValueGen`](#valuegen), this type allows for specifying a union of strings that the StringGen should yield, as long as it is loosely typed as just `string`.  
+Use it in the [`consumeStringGen()`](#consumestringgen) function to convert the given StringGen value to a plain string. Also refer to that function for an example.
+
 <br><br><br><br>
 
 <!-- #region Footer -->

package/dist/index.cjs

@@ -30,10 +30,7 @@ var __objRest = (source, exclude) => {
     }
   return target;
 };
-var __publicField = (obj, key, value) => {
-  __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
-  return value;
-};
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
 var __async = (__this, __arguments, generator) => {
   return new Promise((resolve, reject) => {
     var fulfilled = (value) => {
@@ -57,14 +54,17 @@ var __async = (__this, __arguments, generator) => {
 
 // lib/math.ts
 function clamp(value, min, max) {
+  if (typeof max !== "number") {
+    max = min;
+    min = 0;
+  }
   return Math.max(Math.min(value, max), min);
 }
 function mapRange(value, range1min, range1max, range2min, range2max) {
-  if (typeof range2min === "undefined" || range2max === void 0) {
+  if (typeof range2min === "undefined" || typeof range2max === "undefined") {
     range2max = range1max;
-    range2min = 0;
     range1max = range1min;
-    range1min = 0;
+    range2min = range1min = 0;
   }
   if (Number(range1min) === 0 && Number(range2min) === 0)
     return value * (range2max / range1max);
@@ -78,7 +78,7 @@ function randRange(...args) {
     min = 0;
     [max] = args;
   } else
-    throw new TypeError(`Wrong parameter(s) provided - expected: "number" and "number|undefined", got: "${typeof args[0]}" and "${typeof args[1]}"`);
+    throw new TypeError(`Wrong parameter(s) provided - expected (number, boolean|undefined) or (number, number, boolean|undefined) but got (${args.map((a) => typeof a).join(", ")}) instead`);
   if (typeof args[2] === "boolean")
     enhancedEntropy = args[2];
   else if (typeof args[1] === "boolean")
@@ -99,6 +99,14 @@ function randRange(...args) {
   } else
     return Math.floor(Math.random() * (max - min + 1)) + min;
 }
+function digitCount(num) {
+  num = Number(!["string", "number"].includes(typeof num) ? String(num) : num);
+  if (typeof num === "number" && isNaN(num))
+    return NaN;
+  return num === 0 ? 1 : Math.floor(
+    Math.log10(Math.abs(Number(num))) + 1
+  );
+}
 
 // lib/array.ts
 function randomItem(array) {
@@ -1143,8 +1151,7 @@ var Dialog = class _Dialog extends NanoEmitter {
         if (interactionKeys.includes(e.key)) {
           preventDefault && e.preventDefault();
           stopPropagation && e.stopPropagation();
-        } else
-          return;
+        } else return;
       } else if (e instanceof MouseEvent) {
         preventDefault && e.preventDefault();
         stopPropagation && e.stopPropagation();
@@ -1270,6 +1277,18 @@ function fetchAdvanced(_0) {
     }
   });
 }
+function consumeGen(valGen) {
+  return __async(this, null, function* () {
+    return yield typeof valGen === "function" ? valGen() : valGen;
+  });
+}
+function consumeStringGen(strGen) {
+  return __async(this, null, function* () {
+    return typeof strGen === "string" ? strGen : String(
+      typeof strGen === "function" ? yield strGen() : strGen
+    );
+  });
+}
 
 // lib/SelectorObserver.ts
 var domLoaded = false;
@@ -1449,23 +1468,28 @@ var SelectorObserver = class {
 
 // lib/translation.ts
 var trans = {};
-var curLang;
-var trLang = (language, key, ...args) => {
+var curLang = "";
+function translate(language, key, ...args) {
   var _a;
-  if (!language)
+  const trObj = (_a = trans[language]) == null ? void 0 : _a.data;
+  if (typeof language !== "string" || typeof trObj !== "object" || trObj === null)
     return key;
-  const trText = (_a = trans[language]) == null ? void 0 : _a[key];
-  if (!trText)
-    return key;
-  if (args.length > 0 && trText.match(/%\d/)) {
-    return insertValues(trText, ...args);
+  const keyParts = key.split(".");
+  let value = trObj;
+  for (const part of keyParts) {
+    if (typeof value !== "object" || value === null)
+      break;
+    value = value == null ? void 0 : value[part];
   }
-  return trText;
-};
-function tr(key, ...args) {
-  return trLang(curLang, key, ...args);
+  if (typeof value === "string")
+    return insertValues(value, args);
+  value = trObj == null ? void 0 : trObj[key];
+  if (typeof value === "string")
+    return insertValues(value, args);
+  return key;
 }
-tr.forLang = trLang;
+var tr = (key, ...args) => translate(curLang, key, ...args);
+tr.forLang = translate;
 tr.addLanguage = (language, translations) => {
   trans[language] = translations;
 };
@@ -1490,11 +1514,14 @@ exports.autoPlural = autoPlural;
 exports.clamp = clamp;
 exports.compress = compress;
 exports.computeHash = computeHash;
+exports.consumeGen = consumeGen;
+exports.consumeStringGen = consumeStringGen;
 exports.darkenColor = darkenColor;
 exports.debounce = debounce;
 exports.decompress = decompress;
 exports.defaultDialogCss = defaultDialogCss;
 exports.defaultStrings = defaultStrings;
+exports.digitCount = digitCount;
 exports.fetchAdvanced = fetchAdvanced;
 exports.getSiblingsFrame = getSiblingsFrame;
 exports.getUnsafeWindow = getUnsafeWindow;

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.3.3
+// @version      8.4.0
 // @license      MIT
 // @copyright    Sv443 (https://github.com/Sv443)
 
@@ -48,10 +48,7 @@ var UserUtils = (function (exports) {
       }
     return target;
   };
-  var __publicField = (obj, key, value) => {
-    __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
-    return value;
-  };
+  var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
   var __async = (__this, __arguments, generator) => {
     return new Promise((resolve, reject) => {
       var fulfilled = (value) => {
@@ -75,14 +72,17 @@ var UserUtils = (function (exports) {
 
   // lib/math.ts
   function clamp(value, min, max) {
+    if (typeof max !== "number") {
+      max = min;
+      min = 0;
+    }
     return Math.max(Math.min(value, max), min);
   }
   function mapRange(value, range1min, range1max, range2min, range2max) {
-    if (typeof range2min === "undefined" || range2max === void 0) {
+    if (typeof range2min === "undefined" || typeof range2max === "undefined") {
       range2max = range1max;
-      range2min = 0;
       range1max = range1min;
-      range1min = 0;
+      range2min = range1min = 0;
     }
     if (Number(range1min) === 0 && Number(range2min) === 0)
       return value * (range2max / range1max);
@@ -96,7 +96,7 @@ var UserUtils = (function (exports) {
       min = 0;
       [max] = args;
     } else
-      throw new TypeError(`Wrong parameter(s) provided - expected: "number" and "number|undefined", got: "${typeof args[0]}" and "${typeof args[1]}"`);
+      throw new TypeError(`Wrong parameter(s) provided - expected (number, boolean|undefined) or (number, number, boolean|undefined) but got (${args.map((a) => typeof a).join(", ")}) instead`);
     if (typeof args[2] === "boolean")
       enhancedEntropy = args[2];
     else if (typeof args[1] === "boolean")
@@ -117,6 +117,14 @@ var UserUtils = (function (exports) {
     } else
       return Math.floor(Math.random() * (max - min + 1)) + min;
   }
+  function digitCount(num) {
+    num = Number(!["string", "number"].includes(typeof num) ? String(num) : num);
+    if (typeof num === "number" && isNaN(num))
+      return NaN;
+    return num === 0 ? 1 : Math.floor(
+      Math.log10(Math.abs(Number(num))) + 1
+    );
+  }
 
   // lib/array.ts
   function randomItem(array) {
@@ -766,10 +774,10 @@ Has: ${checksum}`);
     }
   };
 
-  // node_modules/nanoevents/index.js
+  // node_modules/.pnpm/nanoevents@9.1.0/node_modules/nanoevents/index.js
   var createNanoEvents = () => ({
     emit(event, ...args) {
-      for (let i = 0, callbacks = this.events[event] || [], length = callbacks.length; i < length; i++) {
+      for (let callbacks = this.events[event] || [], i = 0, length = callbacks.length; i < length; i++) {
         callbacks[i](...args);
       }
     },
@@ -1181,8 +1189,7 @@ Has: ${checksum}`);
           if (interactionKeys.includes(e.key)) {
             preventDefault && e.preventDefault();
             stopPropagation && e.stopPropagation();
-          } else
-            return;
+          } else return;
         } else if (e instanceof MouseEvent) {
           preventDefault && e.preventDefault();
           stopPropagation && e.stopPropagation();
@@ -1308,6 +1315,18 @@ Has: ${checksum}`);
       }
     });
   }
+  function consumeGen(valGen) {
+    return __async(this, null, function* () {
+      return yield typeof valGen === "function" ? valGen() : valGen;
+    });
+  }
+  function consumeStringGen(strGen) {
+    return __async(this, null, function* () {
+      return typeof strGen === "string" ? strGen : String(
+        typeof strGen === "function" ? yield strGen() : strGen
+      );
+    });
+  }
 
   // lib/SelectorObserver.ts
   var domLoaded = false;
@@ -1487,23 +1506,28 @@ Has: ${checksum}`);
 
   // lib/translation.ts
   var trans = {};
-  var curLang;
-  var trLang = (language, key, ...args) => {
+  var curLang = "";
+  function translate(language, key, ...args) {
     var _a;
-    if (!language)
-      return key;
-    const trText = (_a = trans[language]) == null ? void 0 : _a[key];
-    if (!trText)
+    const trObj = (_a = trans[language]) == null ? void 0 : _a.data;
+    if (typeof language !== "string" || typeof trObj !== "object" || trObj === null)
       return key;
-    if (args.length > 0 && trText.match(/%\d/)) {
-      return insertValues(trText, ...args);
-    }
-    return trText;
-  };
-  function tr(key, ...args) {
-    return trLang(curLang, key, ...args);
+    const keyParts = key.split(".");
+    let value = trObj;
+    for (const part of keyParts) {
+      if (typeof value !== "object" || value === null)
+        break;
+      value = value == null ? void 0 : value[part];
+    }
+    if (typeof value === "string")
+      return insertValues(value, args);
+    value = trObj == null ? void 0 : trObj[key];
+    if (typeof value === "string")
+      return insertValues(value, args);
+    return key;
   }
-  tr.forLang = trLang;
+  var tr = (key, ...args) => translate(curLang, key, ...args);
+  tr.forLang = translate;
   tr.addLanguage = (language, translations) => {
     trans[language] = translations;
   };
@@ -1528,11 +1552,14 @@ Has: ${checksum}`);
   exports.clamp = clamp;
   exports.compress = compress;
   exports.computeHash = computeHash;
+  exports.consumeGen = consumeGen;
+  exports.consumeStringGen = consumeStringGen;
   exports.darkenColor = darkenColor;
   exports.debounce = debounce;
   exports.decompress = decompress;
   exports.defaultDialogCss = defaultDialogCss;
   exports.defaultStrings = defaultStrings;
+  exports.digitCount = digitCount;
   exports.fetchAdvanced = fetchAdvanced;
   exports.getSiblingsFrame = getSiblingsFrame;
   exports.getUnsafeWindow = getUnsafeWindow;

package/dist/index.js

@@ -28,10 +28,7 @@ var __objRest = (source, exclude) => {
     }
   return target;
 };
-var __publicField = (obj, key, value) => {
-  __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
-  return value;
-};
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
 var __async = (__this, __arguments, generator) => {
   return new Promise((resolve, reject) => {
     var fulfilled = (value) => {
@@ -55,14 +52,17 @@ var __async = (__this, __arguments, generator) => {
 
 // lib/math.ts
 function clamp(value, min, max) {
+  if (typeof max !== "number") {
+    max = min;
+    min = 0;
+  }
   return Math.max(Math.min(value, max), min);
 }
 function mapRange(value, range1min, range1max, range2min, range2max) {
-  if (typeof range2min === "undefined" || range2max === void 0) {
+  if (typeof range2min === "undefined" || typeof range2max === "undefined") {
     range2max = range1max;
-    range2min = 0;
     range1max = range1min;
-    range1min = 0;
+    range2min = range1min = 0;
   }
   if (Number(range1min) === 0 && Number(range2min) === 0)
     return value * (range2max / range1max);
@@ -76,7 +76,7 @@ function randRange(...args) {
     min = 0;
     [max] = args;
   } else
-    throw new TypeError(`Wrong parameter(s) provided - expected: "number" and "number|undefined", got: "${typeof args[0]}" and "${typeof args[1]}"`);
+    throw new TypeError(`Wrong parameter(s) provided - expected (number, boolean|undefined) or (number, number, boolean|undefined) but got (${args.map((a) => typeof a).join(", ")}) instead`);
   if (typeof args[2] === "boolean")
     enhancedEntropy = args[2];
   else if (typeof args[1] === "boolean")
@@ -97,6 +97,14 @@ function randRange(...args) {
   } else
     return Math.floor(Math.random() * (max - min + 1)) + min;
 }
+function digitCount(num) {
+  num = Number(!["string", "number"].includes(typeof num) ? String(num) : num);
+  if (typeof num === "number" && isNaN(num))
+    return NaN;
+  return num === 0 ? 1 : Math.floor(
+    Math.log10(Math.abs(Number(num))) + 1
+  );
+}
 
 // lib/array.ts
 function randomItem(array) {
@@ -1141,8 +1149,7 @@ var Dialog = class _Dialog extends NanoEmitter {
         if (interactionKeys.includes(e.key)) {
           preventDefault && e.preventDefault();
           stopPropagation && e.stopPropagation();
-        } else
-          return;
+        } else return;
       } else if (e instanceof MouseEvent) {
         preventDefault && e.preventDefault();
         stopPropagation && e.stopPropagation();
@@ -1268,6 +1275,18 @@ function fetchAdvanced(_0) {
     }
   });
 }
+function consumeGen(valGen) {
+  return __async(this, null, function* () {
+    return yield typeof valGen === "function" ? valGen() : valGen;
+  });
+}
+function consumeStringGen(strGen) {
+  return __async(this, null, function* () {
+    return typeof strGen === "string" ? strGen : String(
+      typeof strGen === "function" ? yield strGen() : strGen
+    );
+  });
+}
 
 // lib/SelectorObserver.ts
 var domLoaded = false;
@@ -1447,23 +1466,28 @@ var SelectorObserver = class {
 
 // lib/translation.ts
 var trans = {};
-var curLang;
-var trLang = (language, key, ...args) => {
+var curLang = "";
+function translate(language, key, ...args) {
   var _a;
-  if (!language)
+  const trObj = (_a = trans[language]) == null ? void 0 : _a.data;
+  if (typeof language !== "string" || typeof trObj !== "object" || trObj === null)
     return key;
-  const trText = (_a = trans[language]) == null ? void 0 : _a[key];
-  if (!trText)
-    return key;
-  if (args.length > 0 && trText.match(/%\d/)) {
-    return insertValues(trText, ...args);
+  const keyParts = key.split(".");
+  let value = trObj;
+  for (const part of keyParts) {
+    if (typeof value !== "object" || value === null)
+      break;
+    value = value == null ? void 0 : value[part];
   }
-  return trText;
-};
-function tr(key, ...args) {
-  return trLang(curLang, key, ...args);
+  if (typeof value === "string")
+    return insertValues(value, args);
+  value = trObj == null ? void 0 : trObj[key];
+  if (typeof value === "string")
+    return insertValues(value, args);
+  return key;
 }
-tr.forLang = trLang;
+var tr = (key, ...args) => translate(curLang, key, ...args);
+tr.forLang = translate;
 tr.addLanguage = (language, translations) => {
   trans[language] = translations;
 };
@@ -1477,4 +1501,4 @@ tr.getTranslations = (language) => {
   return trans[language != null ? language : curLang];
 };
 
-export { DataStore, DataStoreSerializer, Dialog, NanoEmitter, SelectorObserver, addGlobalStyle, addParent, autoPlural, clamp, compress, computeHash, currentDialogId, darkenColor, debounce, decompress, defaultDialogCss, defaultStrings, fetchAdvanced, getSiblingsFrame, getUnsafeWindow, hexToRgb, insertValues, interceptEvent, interceptWindowEvent, isScrollable, lightenColor, mapRange, observeElementProp, openDialogs, openInNewTab, pauseFor, preloadImages, randRange, randomId, randomItem, randomItemIndex, randomizeArray, rgbToHex, setInnerHtmlUnsafe, takeRandomItem, tr };
+export { DataStore, DataStoreSerializer, Dialog, NanoEmitter, SelectorObserver, addGlobalStyle, addParent, autoPlural, clamp, compress, computeHash, consumeGen, consumeStringGen, currentDialogId, darkenColor, debounce, decompress, defaultDialogCss, defaultStrings, digitCount, fetchAdvanced, getSiblingsFrame, getUnsafeWindow, hexToRgb, insertValues, interceptEvent, interceptWindowEvent, isScrollable, lightenColor, mapRange, observeElementProp, openDialogs, openInNewTab, pauseFor, preloadImages, randRange, randomId, randomItem, randomItemIndex, randomizeArray, rgbToHex, setInnerHtmlUnsafe, takeRandomItem, tr };

package/dist/lib/DataStore.d.ts

@@ -1,4 +1,3 @@
-/// <reference types="greasemonkey" />
 import type { Prettify } from "./types.js";
 /** Function that takes the data in the old format and returns the data in the new format. Also supports an asynchronous migration. */
 type MigrationFunc = (oldData: any) => any | Promise<any>;

package/dist/lib/math.d.ts

@@ -1,5 +1,8 @@
+import type { Stringifiable } from "./types.js";
 /** Ensures the passed {@linkcode value} always stays between {@linkcode min} and {@linkcode max} */
 export declare function clamp(value: number, min: number, max: number): number;
+/** Ensures the passed {@linkcode value} always stays between 0 and {@linkcode max} */
+export declare function clamp(value: number, max: number): number;
 /**
  * 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.
@@ -20,3 +23,5 @@ export declare function randRange(min: number, max: number, enhancedEntropy?: bo
  * 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;
+/** Calculates the amount of digits in the given number - the given number or string will be passed to the `Number()` constructor. Returns NaN if the number is invalid. */
+export declare function digitCount(num: number | Stringifiable): number;

package/dist/lib/misc.d.ts

@@ -29,4 +29,25 @@ export type FetchAdvancedOpts = Prettify<Partial<{
     timeout: number;
 }> & RequestInit>;
 /** Calls the fetch API with special options like a timeout */
-export declare function fetchAdvanced(input: RequestInfo | URL, options?: FetchAdvancedOpts): Promise<Response>;
+export declare function fetchAdvanced(input: string | RequestInfo | URL, options?: FetchAdvancedOpts): Promise<Response>;
+/**
+ * A ValueGen value is either its type, a promise that resolves to its type, or a function that returns its type, either synchronous or asynchronous.
+ * ValueGen allows for the utmost flexibility when applied to any type, as long as {@linkcode consumeGen()} is used to get the final value.
+ * @template TValueType The type of the value that the ValueGen should yield
+ */
+export type ValueGen<TValueType> = TValueType | Promise<TValueType> | (() => TValueType | Promise<TValueType>);
+/**
+ * Turns a {@linkcode ValueGen} into its final value.
+ * @template TValueType The type of the value that the ValueGen should yield
+ */
+export declare function consumeGen<TValueType>(valGen: ValueGen<TValueType>): Promise<TValueType>;
+/**
+ * A StringGen value is either a string, anything that can be converted to a string, or a function that returns one of the previous two, either synchronous or asynchronous, or a promise that returns a string.
+ * StringGen allows for the utmost flexibility when dealing with strings, as long as {@linkcode consumeStringGen()} is used to get the final string.
+ */
+export type StringGen = ValueGen<Stringifiable>;
+/**
+ * Turns a {@linkcode StringGen} into its final string value.
+ * @template TStrUnion The union of strings that the StringGen should yield - this allows for finer type control compared to {@linkcode consumeGen()}
+ */
+export declare function consumeStringGen<TStrUnion extends string>(strGen: StringGen): Promise<TStrUnion>;

package/dist/lib/translation.d.ts

@@ -1,4 +1,28 @@
 import type { Stringifiable } from "./types.js";
+/**
+ * Translation object to pass to {@linkcode tr.addLanguage()}
+ * Can be a flat object of identifier keys and the translation text as the value, or an infinitely nestable object containing the same.
+ *
+ * @example
+ * // Flat object:
+ * const tr_en: TrObject = {
+ *   hello: "Hello, %1!",
+ *   foo: "Foo",
+ * };
+ *
+ * // Nested object:
+ * const tr_de: TrObject = {
+ *   hello: "Hallo, %1!",
+ *   foo: {
+ *     bar: "Foo bar",
+ *   },
+ * };
+ */
+export interface TrObject {
+    [key: string]: string | TrObject;
+}
+/** Common function to resolve the translation text in a specific language. */
+declare function translate(language: string, key: string, ...args: Stringifiable[]): string;
 /**
  * Returns the translated text for the specified key in the current language set by {@linkcode tr.setLanguage()}
  * Use {@linkcode tr.forLang()} to get the translation for a specific language instead of the currently set one.
@@ -8,12 +32,21 @@ import type { Stringifiable } from "./types.js";
  * @param key Key of the translation to return
  * @param args Optional arguments to be passed to the translated text. They will replace placeholders in the format `%n`, where `n` is the 1-indexed argument number
  */
-declare function tr(key: string, ...args: Stringifiable[]): string;
-declare namespace tr {
-    var forLang: (language: string, key: string, ...args: Stringifiable[]) => string;
-    var addLanguage: (language: string, translations: Record<string, string>) => void;
-    var setLanguage: (language: string) => void;
-    var getLanguage: () => string;
-    var getTranslations: (language?: string | undefined) => Record<string, string> | undefined;
-}
+declare const tr: {
+    (key: string, ...args: Stringifiable[]): string;
+    /**
+     * Returns the translated text for the specified key in the specified language.
+     * If the key is not found in the specified previously registered translation, the key itself is returned.
+     *
+     * ⚠️ Remember to register a language with {@linkcode tr.addLanguage()} before using this function, otherwise it will always return the key itself.
+     * @param language Language to use for the translation
+     * @param key Key of the translation to return
+     * @param args Optional arguments to be passed to the translated text. They will replace placeholders in the format `%n`, where `n` is the 1-indexed argument number
+     */
+    forLang: typeof translate;
+    addLanguage(language: string, translations: TrObject): void;
+    setLanguage(language: string): void;
+    getLanguage(): string;
+    getTranslations(language?: string): TrObject | undefined;
+};
 export { tr };

package/dist/lib/types.d.ts

@@ -1,7 +1,9 @@
 /** Represents any value that is either a string itself or can be converted to one (implicitly and explicitly) because it has a toString() method */
 export type Stringifiable = string | {
     toString(): string;
-};
+} | {
+    [Symbol.toStringTag]: string;
+} | number | boolean | null | undefined;
 /**
  * A type that offers autocomplete for the passed union but also allows any arbitrary value of the same type to be passed.
  * Supports unions of strings, numbers and objects.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sv443-network/userutils",
   "libName": "UserUtils",
-  "version": "8.3.3",
+  "version": "8.4.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",
@@ -15,24 +15,6 @@
     }
   },
   "type": "module",
-  "scripts": {
-    "lint": "tsc --noEmit && eslint .",
-    "build-types": "tsc --emitDeclarationOnly --declaration --outDir dist",
-    "build-common": "tsup lib/index.ts --format cjs,esm --clean --treeshake",
-    "build-all": "tsup lib/index.ts --format cjs,esm,iife --treeshake --onSuccess \"npm run build-types && npm run post-build-global && echo Finished building.\"",
-    "build": "npm run build-common -- && npm run build-types",
-    "post-build-global": "npm run node-ts -- ./tools/post-build-global.mts",
-    "dev": "npm run build-common -- --sourcemap --watch --onSuccess \"npm run build-types && echo Finished building.\"",
-    "dev-all": "npm run build-all -- --watch",
-    "update-jsr-version": "npm run node-ts -- ./tools/update-jsr-version.mts",
-    "publish-package": "changeset publish",
-    "publish-package-jsr": "npm run update-jsr-version && npx jsr publish --allow-dirty",
-    "change": "changeset",
-    "node-ts": "node --no-warnings=ExperimentalWarning --enable-source-maps --loader ts-node/esm",
-    "test-serve": "npm run node-ts -- ./test/TestPage/server.mts",
-    "test-dev": "cd test/TestScript && npm run dev",
-    "test": "concurrently \"npm run test-serve\" \"npm run test-dev\""
-  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Sv443-Network/UserUtils.git"
@@ -51,22 +33,22 @@
   },
   "homepage": "https://github.com/Sv443-Network/UserUtils",
   "dependencies": {
-    "nanoevents": "^9.0.0"
+    "nanoevents": "^9.1.0"
   },
   "devDependencies": {
-    "@changesets/cli": "^2.26.2",
-    "@types/express": "^4.17.19",
-    "@types/greasemonkey": "^4.0.4",
-    "@types/node": "^20.5.9",
-    "@typescript-eslint/eslint-plugin": "^6.2.1",
-    "@typescript-eslint/parser": "^6.2.1",
-    "concurrently": "^8.2.1",
-    "eslint": "^8.46.0",
-    "express": "^4.18.2",
-    "ts-node": "^10.9.1",
-    "tslib": "^2.6.1",
-    "tsup": "^7.1.0",
-    "typescript": "^5.1.6"
+    "@changesets/cli": "^2.27.11",
+    "@types/express": "^4.17.21",
+    "@types/greasemonkey": "^4.0.7",
+    "@types/node": "^20.17.10",
+    "@typescript-eslint/eslint-plugin": "^6.21.0",
+    "@typescript-eslint/parser": "^6.21.0",
+    "concurrently": "^8.2.2",
+    "eslint": "^8.57.1",
+    "express": "^4.21.2",
+    "ts-node": "^10.9.2",
+    "tslib": "^2.8.1",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2"
   },
   "files": [
     "/dist/index.js",
@@ -78,5 +60,23 @@
     "/README.md",
     "/CHANGELOG.md",
     "/LICENSE.txt"
-  ]
+  ],
+  "scripts": {
+    "lint": "eslint . && tsc --noEmit",
+    "build-types": "tsc --emitDeclarationOnly --declaration --outDir dist",
+    "build-common": "tsup lib/index.ts --format cjs,esm --clean --treeshake",
+    "build-all": "tsup lib/index.ts --format cjs,esm,iife --treeshake --onSuccess \"npm run build-types && npm run post-build-global && echo Finished building.\"",
+    "build": "npm run build-common -- && npm run build-types",
+    "post-build-global": "npm run node-ts -- ./tools/post-build-global.mts",
+    "dev": "npm run build-common -- --sourcemap --watch --onSuccess \"npm run build-types && echo Finished building.\"",
+    "dev-all": "npm run build-all -- --watch",
+    "update-jsr-version": "npm run node-ts -- ./tools/update-jsr-version.mts",
+    "publish-package": "changeset publish",
+    "publish-package-jsr": "npm run update-jsr-version && npx jsr publish --allow-dirty",
+    "change": "changeset",
+    "node-ts": "node --no-warnings=ExperimentalWarning --enable-source-maps --loader ts-node/esm",
+    "test-serve": "npm run node-ts -- ./test/TestPage/server.mts",
+    "test-dev": "cd test/TestScript && npm run dev",
+    "test": "concurrently \"npm run test-serve\" \"npm run test-dev\""
+  }
 }