@sv443-network/userutils 8.3.2 → 8.4.0

package/README.md

@@ -5,15 +5,25 @@
 Lightweight 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.  
   
 Contains builtin TypeScript declarations. Supports ESM and CJS imports via a bundler and global declaration via `@require`  
+  
+You may want to check out my [template for userscripts in TypeScript](https://github.com/Sv443/Userscript.ts) that you can use to get started quickly. It also includes this library by default.  
 If you like using this library, please consider [supporting the development ❤️](https://github.com/sponsors/Sv443)
 
 <br>
+
+[![minified bundle size badge](https://badgen.net/bundlephobia/min/@sv443-network/userutils)](https://bundlephobia.com/package/@sv443-network/userutils)
+[![minified and gzipped bundle size badge](https://badgen.net/bundlephobia/minzip/@sv443-network/userutils)](https://bundlephobia.com/package/@sv443-network/userutils)
+[![tree shaking support badge](https://badgen.net/bundlephobia/tree-shaking/@sv443-network/userutils)](https://bundlephobia.com/package/@sv443-network/userutils)
+
+[![github stargazers badge](https://badgen.net/github/stars/Sv443-Network/UserUtils?icon=github)](https://github.com/Sv443-Network/UserUtils/stargazers)
+[![discord server badge](https://badgen.net/discord/online-members/aBH4uRG?icon=discord)](https://dc.sv443.net/)
+
 <sup>
 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>
@@ -42,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
@@ -56,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
@@ -79,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>
 
@@ -86,12 +101,16 @@ View the documentation of previous major releases:
 ## Installation:
 Shameless plug: I made a [template for userscripts in TypeScript](https://github.com/Sv443/Userscript.ts) that you can use to get started quickly. It also includes this library by default.  
   
-- If you are using a bundler (like webpack, rollup, vite, etc.), you can install this package using npm:
+- If you are using a bundler (like webpack, rollup, vite, etc.), you can install this package in one of the following ways:
   ```
   npm i @sv443-network/userutils
+  pnpm i @sv443-network/userutils
+  yarn add @sv443-network/userutils
+  npx jsr install @sv443-network/userutils
+  deno add jsr:@sv443-network/userutils
   ```
-  <sup>For other package managers, check out the respective install command on the [JavaScript Registry](https://jsr.io/@sv443-network/userutils)</sup>  
-  Then, import it in your script as usual:
+  Then import it in your script as usual:  
+  
   ```ts
   import { addGlobalStyle } from "@sv443-network/userutils";
 
@@ -102,16 +121,26 @@ Shameless plug: I made a [template for userscripts in TypeScript](https://github
 
 <br>
 
-- If you are not using a bundler or want to reduce the size of your userscript, you can include the latest release by adding one of these directives to the userscript header, depending on your preferred CDN:
+- If you are not using a bundler, want to reduce the size of your userscript, or declared the package as external in your bundler, you can include the latest release by adding one of these directives to the userscript header, depending on your preferred CDN:
+  
+  Versioned (recommended):
   ```
-  // @require https://greasyfork.org/scripts/472956-userutils/code/UserUtils.js
+  // @require https://cdn.jsdelivr.net/npm/@sv443-network/userutils@INSERT_VERSION/dist/index.global.js
+  // @require https://unpkg.com/@sv443-network/userutils@INSERT_VERSION/dist/index.global.js
   ```
+  Non-versioned (not recommended because auto-updating):
   ```
+  // @require https://update.greasyfork.org/scripts/472956/UserUtils.js
   // @require https://openuserjs.org/src/libs/Sv443/UserUtils.js
   ```
-  (in order for your userscript not to break on a major library update, instead use the versioned URL at the top of the [GreasyFork page](https://greasyfork.org/scripts/472956-userutils))  
     
-  Then, access the functions on the global variable `UserUtils`:
+> [!NOTE]  
+> In order for your userscript not to break on a major library update, use one the versioned URLs above after replacing `INSERT_VERSION` with the desired version (e.g. `8.3.2`) or the versioned URL that's shown at the top of the [GreasyFork page.](https://greasyfork.org/scripts/472956-userutils)  
+
+<br>
+
+- Then, access the functions on the global variable `UserUtils`:
+  
   ```ts
   UserUtils.addGlobalStyle("body { background-color: red; }");
 
@@ -120,10 +149,27 @@ Shameless plug: I made a [template for userscripts in TypeScript](https://github
   const { clamp } = UserUtils;
   console.log(clamp(1, 5, 10)); // 5
   ```
-  If you're using TypeScript and it complains about the missing global variable `UserUtils`, install the library using the package manager of your choice and add the following inside a `.d.ts` file somewhere in your project:
+
+<br>
+
+- If you're using TypeScript and it complains about the missing global variable `UserUtils`, install the library using the package manager of your choice and add the following inside a `.d.ts` file somewhere in the directory (or a subdirectory) defined in your `tsconfig.json`'s `baseUrl` option or `include` array:  
+  
   ```ts
+  declare const UserUtils: typeof import("@sv443-network/userutils");
+
   declare global {
-    const UserUtils: typeof import("@sv443-network/userutils");
+    interface Window {
+      UserUtils: typeof UserUtils;
+    }
+  }
+  ```
+
+<br>
+
+- If you're using a linter like ESLint, it might complain about the global variable `UserUtils` not being defined. To fix this, add the following to your ESLint configuration file:
+  ```json
+  "globals": {
+      "UserUtils": "readonly"
   }
   ```
 
@@ -137,8 +183,11 @@ Each feature has example code that can be expanded by clicking on the text "Exam
 The usages and examples are written in TypeScript and use ESM import syntax, but the library can also be used in plain JavaScript after removing the type annotations (and changing the imports if you are using CommonJS or the global declaration).  
 If the usage section contains multiple usages of the function, each occurrence represents an overload and you can choose which one you want to use.  
   
-Some features require the `@run-at` or `@grant` directives to be tweaked in the userscript header or have other requirements.  
-Their documentation will contain a section marked by a warning emoji (⚠️) that will go into more detail.
+Some features require the `@run-at` or `@grant` directives to be tweaked in the userscript header or have other specific requirements and limitations.  
+Those will be listed in a section marked by a warning emoji (⚠️) each.  
+  
+If you need help with something, please [create a new discussion](https://github.com/Sv443-Network/UserUtils/discussions) or [join my Discord server.](https://dc.sv443.net/)  
+For submitting bug reports or feature requests, please use the [GitHub issue tracker.](https://github.com/Sv443-Network/UserUtils/issues)
 
 <br><br>
 
@@ -908,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>
 
@@ -918,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>
 
@@ -998,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 -->
@@ -1684,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>
 
@@ -1993,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:
 
@@ -2100,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.  
   
-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.  
+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 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>
 
@@ -2145,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)  
@@ -2167,8 +2352,8 @@ tr.addLanguage("de", {
 // the language is set to "en"
 tr.setLanguage("en");
 
-console.log(tr("welcome_name", "John"));               // "Welcome"
-// the language doesn't need to be changed:
+console.log(tr("welcome_name", "John"));               // "Welcome, John"
+// no need to call tr.setLanguage():
 console.log(tr.forLang("de", "welcome_name", "John")); // "Willkommen, John"
 ```
 </details>
@@ -2178,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 a language and its associated translations to the translation function.  
-The passed language can be any unique identifier, though I recommend sticking to the [ISO 639-1 standard.](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)  
-The passed translations should be an object where the key is the translation key used in `tr()` and the value is the translation itself.  
+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 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.  
@@ -2192,54 +2377,63 @@ 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": "french fries",
+  fries: "fries",
+  color: "color",
 });
+
 tr.addLanguage("en-GB", {
-  "fries": "chips",
+  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);
+
 tr.addLanguage("de-CH", {
+  // overwrite the "greeting" but keep other keys as they are:
   ...translation_de,
-  // overwrite the "greeting" but keep other keys as they are
-  "greeting": "Grüezi!",
+  greeting: "Grüezi!",
 });
+
 tr.addLanguage("de-AT", {
+  // overwrite "greeting" again but keep other keys as they are:
   ...translation_de,
-  // overwrite "greeting" again but keep other keys as they are
-  "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",
@@ -2247,27 +2441,47 @@ tr.addLanguage("en", {
   "cart_items_added-n": "Added %1 items to the cart",
 });
 
-/** 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` property) */
-function pl(key: string, num: number | Array<unknown> | NodeList | { length: number }) {
-  if(typeof num !== "number")
-    num = num.length;
+/** A number or any object with a length or size property */
+type Numberish = number | Array<unknown> | NodeList | { length: number } | { size: number };
+
+/**
+ * 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;
+    else if("size" in num)
+      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`;
+    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"
+
+// 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>
 
@@ -2279,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>
 
@@ -2300,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.  
@@ -2313,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
@@ -2469,7 +2684,7 @@ logSomething(barObject); // Type error
 
 <br>
 
-## NonEmptyArray
+### NonEmptyArray
 Usage:
 ```ts
 NonEmptyArray<TItem = unknown>
@@ -2499,7 +2714,7 @@ logFirstItem(["04abc", "69"]); // 4
 
 <br>
 
-## NonEmptyString
+### NonEmptyString
 Usage:
 ```ts
 NonEmptyString<TString extends string>
@@ -2523,7 +2738,7 @@ convertToNumber("");      // type error: Argument of type 'string' is not assign
 
 <br>
 
-## LooseUnion
+### LooseUnion
 Usage:
 ```ts
 LooseUnion<TUnion extends string | number | object>
@@ -2550,7 +2765,7 @@ foo(1);   // type error: Argument of type '1' is not assignable to parameter of
 
 <br>
 
-## Prettify
+### Prettify
 Usage:
 ```ts
 Prettify<T>
@@ -2603,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 -->