@sv443-network/userutils 6.2.0 → 7.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 <!-- #MARKER Description -->
 ## UserUtils
-Zero-dependency library with various utilities for userscripts - register listeners for when CSS selectors exist, intercept events, manage persistent user configurations, modify the DOM more easily and more.  
+Zero-dependency 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. Fully web compatible and supports ESM and CJS imports and global declaration.  
 If you like using this library, please consider [supporting the development ❤️](https://github.com/sponsors/Sv443)
@@ -26,47 +26,48 @@ View the documentation of previous major releases:
 - [**License**](#license)
 - [**Features**](#features)
   - [**DOM:**](#dom)
-    - [SelectorObserver](#selectorobserver) - class that manages listeners that are called when selectors are found in the DOM
-    - [getUnsafeWindow()](#getunsafewindow) - get the unsafeWindow object or fall back to the regular window object
-    - [insertAfter()](#insertafter) - insert an element as a sibling after another element
-    - [addParent()](#addparent) - add a parent element around another element
-    - [addGlobalStyle()](#addglobalstyle) - add a global style to the page
-    - [preloadImages()](#preloadimages) - preload images into the browser cache for faster loading later on
-    - [openInNewTab()](#openinnewtab) - open a link in a new tab
-    - [interceptEvent()](#interceptevent) - conditionally intercepts events registered by `addEventListener()` on any given EventTarget object
-    - [interceptWindowEvent()](#interceptwindowevent) - conditionally intercepts events registered by `addEventListener()` on the window object
-    - [isScrollable()](#isscrollable) - check if an element has a horizontal or vertical scroll bar
-    - [observeElementProp()](#observeelementprop) - observe changes to an element's property that can't be observed with MutationObserver
-    - [getSiblingsFrame()](#getsiblingsframe) - returns a frame of an element's siblings, with a given alignment and size
+    - [`SelectorObserver`](#selectorobserver) - class that manages listeners that are called when selectors are found in the DOM
+    - [`getUnsafeWindow()`](#getunsafewindow) - get the unsafeWindow object or fall back to the regular window object
+    - [`addParent()`](#addparent) - add a parent element around another element
+    - [`addGlobalStyle()`](#addglobalstyle) - add a global style to the page
+    - [`preloadImages()`](#preloadimages) - preload images into the browser cache for faster loading later on
+    - [`openInNewTab()`](#openinnewtab) - open a link in a new tab
+    - [`interceptEvent()`](#interceptevent) - conditionally intercepts events registered by `addEventListener()` on any given EventTarget object
+    - [`interceptWindowEvent()`](#interceptwindowevent) - conditionally intercepts events registered by `addEventListener()` on the window object
+    - [`isScrollable()`](#isscrollable) - check if an element has a horizontal or vertical scroll bar
+    - [`observeElementProp()`](#observeelementprop) - observe changes to an element's property that can't be observed with MutationObserver
+    - [`getSiblingsFrame()`](#getsiblingsframe) - returns a frame of an element's siblings, with a given alignment and size
   - [**Math:**](#math)
-    - [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
-    - [randomId()](#randomid) - generate a random ID of a given length and radix
+    - [`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
   - [**Misc:**](#misc)
-    - [DataStore](#datastore) - class that manages a sync & async persistent JSON database, including data migration
-    - [autoPlural()](#autoplural) - automatically pluralize a string
-    - [pauseFor()](#pausefor) - pause the execution of a function for a given amount of time
-    - [debounce()](#debounce) - call a function only once in a series of calls, after or before a given timeout
-    - [fetchAdvanced()](#fetchadvanced) - wrapper around the fetch API with a timeout option
-    - [insertValues()](#insertvalues) - insert values into a string at specified placeholders
-    - [compress()](#compress) - compress a string with Gzip or Deflate
-    - [decompress()](#decompress) - decompress a previously compressed string
+    - [`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
+    - [`autoPlural()`](#autoplural) - automatically pluralize a string
+    - [`pauseFor()`](#pausefor) - pause the execution of a function for a given amount of time
+    - [`debounce()`](#debounce) - call a function only once in a series of calls, after or before a given timeout
+    - [`fetchAdvanced()`](#fetchadvanced) - wrapper around the fetch API with a timeout option
+    - [`insertValues()`](#insertvalues) - insert values into a string at specified placeholders
+    - [`compress()`](#compress) - compress a string with Gzip or Deflate
+    - [`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
   - [**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
+    - [`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()`](#tr) - simple translation of a string to another language
     - [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
   - [**Utility types for TypeScript:**](#utility-types)
-    - [Stringifiable](#stringifiable) - any value that is a string or can be converted to one (implicitly or explicitly)
-    - [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
+    - [`Stringifiable`](#stringifiable) - any value that is a string or can be converted to one (implicitly or explicitly)
+    - [`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
 
 <br><br>
 
@@ -80,7 +81,7 @@ View the documentation of previous major releases:
   ```ts
   import { addGlobalStyle } from "@sv443-network/userutils";
 
-  // or just import everything (not recommended because this doesn't allow for treeshaking):
+  // or just import everything (not recommended because of worse treeshaking support):
 
   import * as UserUtils from "@sv443-network/userutils";
   ```
@@ -145,12 +146,13 @@ new SelectorObserver(baseElementSelector: string, options?: SelectorObserverOpti
 ```
 
 A class that manages listeners that are called when elements at given selectors are found in the DOM.  
-This is useful for userscripts that need to wait for elements to be added to the DOM at an indeterminate point in time before they can be interacted with.  
+It is useful for userscripts that need to wait for elements to be added to the DOM at an indeterminate point in time before they can be interacted with.  
+By default, it uses the MutationObserver API to observe for any element changes, and as such is highly customizable, but can also be configured to run on a fixed interval.  
   
 The constructor takes a `baseElement`, which is a parent of the elements you want to observe.  
 If a selector string is passed instead, it will be used to find the element.  
-If you want to observe the entire document, you can pass `document.body`  
-
+If you want to observe the entire document, you can pass `document.body` - ⚠️ you should only use this to initialize other SelectorObserver instances, and never run continuous listeners on this instance, as the performance impact can be massive!  
+  
 The `options` parameter is optional and will be passed to the MutationObserver that is used internally.  
 The MutationObserver options present by default are `{ childList: true, subtree: true }` - you may see the [MutationObserver.observe() documentation](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver/observe#options) for more information and a list of options.  
 For example, if you want to trigger the listeners when certain attributes change, pass `{ attributeFilter: ["class", "data-my-attribute"] }`  
@@ -159,6 +161,8 @@ Additionally, there are the following extra options:
 - `disableOnNoListeners` - whether to disable the SelectorObserver when there are no listeners left (defaults to false)
 - `enableOnAddListener` - whether to enable the SelectorObserver when a new listener is added (defaults to true)
 - `defaultDebounce` - if set to a number, this debounce will be applied to every listener that doesn't have a custom debounce set (defaults to 0)
+- `defaultDebounceEdge` - can be set to "falling" (default) or "rising", to call the function at (rising) on the very first call and subsequent times after the given debounce time or (falling) the very last call after the debounce time passed with no new calls - [see `debounce()` for more info and a diagram](#debounce)
+- `checkInterval` - if set to a number, the checks will be run on interval instead of on mutation events - in that case all MutationObserverInit props will be ignored
   
 ⚠️ Make sure to call `enable()` to actually start observing. This will need to be done after the DOM has loaded (when using `@run-at document-end` or after `DOMContentLoaded` has fired) **and** as soon as the `baseElement` or `baseElementSelector` is available.
 
@@ -177,16 +181,19 @@ The listener will be called immediately if the selector already exists in the DO
 > This will also include elements that were already found in a previous listener call.  
 > If set to false (default), querySelector() will be used and only the first matching element will be returned.
   
-> If `options.continuous` is set to true, the listener will not be deregistered after it was called once (defaults to false).  
+> If `options.continuous` is set to true, this listener will not be deregistered after it was called once (defaults to false).  
 >   
-> ⚠️ You should keep usage of this option to a minimum, as it will cause the listener to be called every time the selector is *checked for and found* and this can stack up quite quickly.  
+> ⚠️ You should keep usage of this option to a minimum, as it will cause this listener to be called every time the selector is *checked for and found* and this can stack up quite quickly.  
 > ⚠️ You should try to only use this option on SelectorObserver instances that are scoped really low in the DOM tree to prevent as many selector checks as possible from being triggered.  
 > ⚠️ I also recommend always setting a debounce time (see constructor or below) if you use this option.
   
-> If `options.debounce` is set to a number above 0, the listener will be debounced by that amount of milliseconds (defaults to 0).  
-> E.g. if the debounce time is set to 200 and the selector is found twice within 100ms, only the last call of the listener will be executed.
+> If `options.debounce` is set to a number above 0, this listener will be debounced by that amount of milliseconds (defaults to 0).  
+> E.g. if the debounce time is set to 200 and the selector is found twice within 100ms, only the last call of this listener will be executed.
+
+> `options.debounceEdge` is set to "falling" by default, which means the debounce timer will start after the last call of this listener.  
+> If set to "rising", the debounce timer will start after the first call of this listener.
   
-> When using TypeScript, the generic `TElement` can be used to specify the type of the element(s) that the listener will return.  
+> When using TypeScript, the generic `TElement` can be used to specify the type of the element(s) that this listener will return.  
 > It will default to HTMLElement if left undefined.
   
 <br>
@@ -262,6 +269,9 @@ document.addEventListener("DOMContentLoaded", () => {
     attributeFilter: ["class", "style", "data-whatever"],
     // debounce all listeners by 100ms unless specified otherwise:
     defaultDebounce: 100,
+    // "rising" means listeners are called immediately and use the debounce as a timeout between subsequent calls - see the debounce() function for a better explanation
+    defaultDebounceEdge: "rising",
+    // other settings from the MutationObserver API can be set here too - see https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver/observe#options
   });
 
   barObserver.addListener("#my-element", {
@@ -273,6 +283,8 @@ document.addEventListener("DOMContentLoaded", () => {
   barObserver.addListener("#my-other-element", {
     // set the debounce higher than provided by the defaultDebounce property:
     debounce: 250,
+    // adjust the debounceEdge back to the default "falling" for this specific listener:
+    debounceEdge: "falling",
     listener: (element) => {
       console.log("Other element's attributes changed:", element);
     },
@@ -286,7 +298,7 @@ document.addEventListener("DOMContentLoaded", () => {
   const bazObserver = new SelectorObserver(document.body);
 
   // for TypeScript, specify that input elements are returned by the listener:
-  bazObserver.addListener<HTMLInputElement>("input", {
+  const unsubscribe = bazObserver.addListener<HTMLInputElement>("input", {
     all: true,        // use querySelectorAll() instead of querySelector()
     continuous: true, // don't remove the listener after it was called once
     debounce: 50,     // debounce the listener by 50ms
@@ -298,6 +310,11 @@ document.addEventListener("DOMContentLoaded", () => {
 
   bazObserver.enable();
 
+  window.addEventListener("something", () => {
+    // remove the listener after the event "something" was dispatched:
+    unsubscribe();
+  });
+
 
   // use a different element as the base:
 
@@ -431,7 +448,7 @@ getUnsafeWindow(): Window
 ```
   
 Returns the unsafeWindow object or falls back to the regular window object if the `@grant unsafeWindow` is not given.  
-Userscripts are sandboxed and do not have access to the regular window object, so this function is useful for websites that reject some events that were dispatched by the userscript.  
+Userscripts are sandboxed and do not have access to the regular window object, so this function is useful for websites that reject some events that were dispatched by the userscript, or userscripts that need to interact with other userscripts, and more.  
   
 <details><summary><b>Example - click to view</b></summary>
 
@@ -454,34 +471,6 @@ document.body.dispatchEvent(mouseEvent);
 
 <br>
 
-### insertAfter()
-Usage:  
-```ts
-insertAfter(beforeElement: Element, afterElement: Element): Element
-```
-  
-Inserts the element passed as `afterElement` as a sibling after the passed `beforeElement`.  
-The passed `afterElement` will be returned.  
-  
-⚠️ This function needs to be run after the DOM has loaded (when using `@run-at document-end` or after `DOMContentLoaded` has fired).  
-  
-<details><summary><b>Example - click to view</b></summary>
-
-```ts
-import { insertAfter } from "@sv443-network/userutils";
-
-// insert a <div> as a sibling next to an element
-const beforeElement = document.querySelector("#before");
-const afterElement = document.createElement("div");
-afterElement.innerText = "After";
-
-insertAfter(beforeElement, afterElement);
-```
-
-</details>
-
-<br>
-
 ### addParent()
 Usage:  
 ```ts
@@ -541,7 +530,7 @@ document.addEventListener("DOMContentLoaded", () => {
 ### preloadImages()
 Usage:  
 ```ts
-preloadImages(urls: string[], rejects?: boolean): Promise<void>
+preloadImages(urls: string[], rejects?: boolean): Promise<Array<PromiseSettledResult<HTMLImageElement>>>
 ```
   
 Preloads images into browser cache by creating an invisible `<img>` element for each URL passed.  
@@ -573,14 +562,14 @@ preloadImages([
 ### openInNewTab()
 Usage:  
 ```ts
-openInNewTab(url: string): void
+openInNewTab(url: string, background?: boolean): void
 ```
   
-Creates an invisible anchor with a `_blank` target and clicks it.  
-Contrary to `window.open()`, this has a lesser chance to get blocked by the browser's popup blocker and doesn't open the URL as a new window.  
-This function has to be run in response to a user interaction event, else the browser might reject it.  
+Tries to use `GM.openInTab` to open the given URL in a new tab, or as a fallback if the grant is not given, creates an invisible anchor element and clicks it.  
+If `background` is set to true, the tab will be opened in the background. Leave `undefined` to use the browser's default behavior.  
   
-⚠️ This function needs to be run after the DOM has loaded (when using `@run-at document-end` or after `DOMContentLoaded` has fired).  
+⚠️ Needs the `@grant GM.openInTab` directive, otherwise only the fallback behavior will be used and the warning below is extra important:  
+⚠️ For the fallback to work, this function needs to be run in response to a user interaction event, else the browser might reject it.  
   
 <details><summary><b>Example - click to view</b></summary>
 
@@ -588,7 +577,8 @@ This function has to be run in response to a user interaction event, else the br
 import { openInNewTab } from "@sv443-network/userutils";
 
 document.querySelector("#my-button").addEventListener("click", () => {
-  openInNewTab("https://example.org/");
+  // open in background:
+  openInNewTab("https://example.org/", true);
 });
 ```
 
@@ -945,36 +935,6 @@ randRange(10);     // 7
 
 </details>
 
-<br>
-
-### randomId()
-Usage:  
-```ts
-randomId(length?: number, radix?: number): string
-```
-  
-Generates a cryptographically strong random ID of a given length and [radix (base).](https://en.wikipedia.org/wiki/Radix)  
-Uses the [Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues) for generating the random numbers.  
-⚠️ This is not intended for generating encryption keys, only for generating IDs with a decent amount of entropy!  
-  
-The default length is 16 and the default radix is 16 (hexadecimal).  
-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.  
-  
-<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)
-```
-
-</details>
-
 <br><br>
 
 <!-- #SECTION Misc -->
@@ -986,12 +946,17 @@ Usage:
 new DataStore(options: DataStoreOptions)
 ```
   
-A class that manages a sync & async JSON database that is persistently saved to and loaded from GM storage.  
+A class that manages a sync & async JSON database that is persistently saved to and loaded from GM storage, localStorage or sessionStorage.  
 Also supports automatic migration of outdated data formats via provided migration functions.  
 You may create as many instances as you like as long as they have different IDs.  
   
-⚠️ The data is stored as a JSON string, so only JSON-compatible data can be used. Circular structures and complex objects will throw an error on load and save.  
-⚠️ The directives `@grant GM.getValue` and `@grant GM.setValue` are required for this to work.  
+The class' internal methods are all declared as protected, so you can extend this class and override them if you need to add your own functionality, like changing the location data is stored.  
+  
+If you have multiple DataStore instances and you want to be able to easily and safely export and import their data, take a look at the [DataStoreSerializer](#datastoreserializer) class.  
+It combines the data of multiple DataStore instances into a single object that can be exported and imported as a whole by the end user.  
+  
+⚠️ The data is stored as a JSON string, so only JSON-compatible data can be used. Circular structures and complex objects will throw an error on load and save or cause otherwise unexpected behavior.  
+⚠️ The directives `@grant GM.getValue` and `@grant GM.setValue` are required if the storageMethod is left as the default of `"GM"`  
   
 The options object has the following properties:
 | Property | Description |
@@ -1000,8 +965,9 @@ 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. |
-| `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) |
+| `storageMethod?` | (Optional) The method that is used to store the data. Can be `"GM"` (default), `"localStorage"` or `"sessionStorage"`. If you want to store the data in a different way, you can override the methods of the DataStore class. |
+| `encodeData?` | (Optional, but required when `decodeData` is set) Function that encodes the data before saving - you can use [compress()](#compress) here to save space at the cost of a little bit of performance |
+| `decodeData?` | (Optional, but required when `encodeData` is set) Function that decodes the data when loading - you can use [decompress()](#decompress) here to decode data that was previously compressed with [compress()](#compress) |
 
 <br>
 
@@ -1022,10 +988,19 @@ Writes the given data synchronously to the internal cache and asynchronously to
 Writes the default data given in `options.defaultData` synchronously to the internal cache and asynchronously to persistent storage.  
   
 `deleteData(): Promise<void>`  
-Fully deletes the data from persistent storage.  
+Fully deletes the data from persistent storage only.  
 The internal cache will be left untouched, so any subsequent calls to `getData()` will return the data that was last loaded.  
 If `loadData()` or `setData()` are called after this, the persistent storage will be populated with the value of `options.defaultData` again.  
+This is why you should either immediately repopulate the cache and persistent storage or the page should probably be reloaded or closed after this method is called.  
 ⚠️ If you want to use this method, the additional directive `@grant GM.deleteValue` is required.  
+  
+`runMigrations(oldData: any, oldFmtVer: number, resetOnError?: boolean): Promise<TData>`  
+Runs all necessary migration functions to migrate the given `oldData` to the latest format.  
+If `resetOnError` is set to `false`, the migration will be aborted if an error is thrown and no data will be committed. If it is set to `true` (default) and an error is encountered, it will be suppressed and the `defaultData` will be saved to persistent storage and returned.  
+  
+`encodingEnabled(): boolean`  
+Returns `true` if both `options.encodeData` and `options.decodeData` are set, else `false`.  
+Uses TypeScript's type guard notation for easier use in conditional statements.
 
 <br>
 
@@ -1042,16 +1017,16 @@ interface MyConfig {
   qux: string;
 }
 
-/** Default data */
+/** Default data returned by getData() calls until setData() is used and also fallback data if something goes wrong */
 const defaultData: MyConfig = {
   foo: "hello",
   bar: 42,
   baz: "xyz",
   qux: "something",
 };
-/** If any properties are added to, removed from or renamed in MyConfig, increment this number */
+/** If any properties are added to, removed from, or renamed in the MyConfig type, increment this number */
 const formatVersion = 2;
-/** Functions that migrate outdated data to the latest format - make sure a function exists for every previously used formatVersion and that no numbers are skipped! */
+/** These are functions that migrate outdated data to the latest format - make sure a function exists for every previously used formatVersion and that no numbers are skipped! */
 const migrations = {
   // migrate from format version 0 to 1
   1: (oldData: Record<string, unknown>) => {
@@ -1063,8 +1038,8 @@ const migrations = {
   },
   // asynchronously migrate from format version 1 to 2
   2: async (oldData: Record<string, unknown>) => {
-    // arbitrary async operation required for the new format
-    const qux = JSON.parse(await (await fetch("https://api.example.org/some-data")).text());
+    // using arbitrary async operations for the new format:
+    const qux = await grabQuxDataAsync();
     return {
       foo: oldData.foo,
       bar: oldData.bar,
@@ -1074,32 +1049,38 @@ const migrations = {
   },
 };
 
-const manager = new DataStore({
-  /** A unique ID for this instance - choose wisely as changing it is not supported yet! */
+// You probably want to export this instance (or helper functions) so you can use it anywhere in your script:
+export const manager = new DataStore({
+  /** A unique ID for this instance - choose wisely as changing it is not supported and will result in data loss! */
   id: "my-userscript-config",
-  /** Default / fallback data */
+  /** Default, initial and fallback data */
   defaultData,
   /** The current version of the data format */
   formatVersion,
-  /** Data format migration functions */
+  /** Data format migration functions called when the formatVersion is increased */
   migrations,
+  /**
+   * 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.
+   */
+  storageMethod: "localStorage",
 
   // Compression example:
-  // Adding this will save space at the cost of a little bit of performance while initially loading and saving the data
-  // Only both of these properties or none of them should be set
-  // Everything else will be handled by the DataStore instance
-
-  /** Encodes data using the "deflate-raw" algorithm and digests it as a base64 string */
-  encodeData: (data) => compress(data, "deflate-raw", "base64"),
-  /** Decodes the "deflate-raw" encoded data as a base64 string */
-  decodeData: (data) => decompress(data, "deflate-raw", "base64"),
+  // Adding the following will save space at the cost of a little bit of performance (only for the initial loading and every time new data is saved)
+  // Feel free to use your own functions here, as long as they take in the stringified JSON and return another string, either synchronously or asynchronously
+  // Either both of these properties or none of them should be set
+
+  /** Compresses the data using the "deflate" algorithm and digests it as a string */
+  encodeData: (data) => compress(data, "deflate", "string"),
+  /** Decompresses the "deflate" encoded data as a string */
+  decodeData: (data) => decompress(data, "deflate", "string"),
 });
 
 /** Entrypoint of the userscript */
 async function init() {
   // wait for the data to be loaded from persistent storage
   // if no data was saved in persistent storage before or getData() is called before loadData(), the value of options.defaultData will be returned
-  // if the previously saved data needs to be migrated to a newer version, it will happen in this function call
+  // if the previously saved data needs to be migrated to a newer version, it will happen inside this function call
   const configData = await manager.loadData();
 
   console.log(configData.foo); // "hello"
@@ -1122,6 +1103,149 @@ init();
 
 </details>
 
+<br>
+
+### DataStoreSerializer
+Usage:  
+```ts
+new DataStoreSerializer(stores: DataStore[], options: DataStoreSerializerOptions)
+```
+
+A class that manages serializing and deserializing (exporting and importing) one to infinite DataStore instances.  
+The serialized data is a JSON string that can be saved to a file, copied to the clipboard, or stored in any other way.  
+Each DataStore instance's settings like data encoding are respected and saved next to the exported data.  
+Also, by default a checksum is calculated and importing data with a mismatching checksum will throw an error.  
+  
+The class' internal methods are all declared as protected, so you can extend this class and override them if you need to add your own functionality.  
+  
+⚠️ Needs to run in a secure context (HTTPS) due to the use of the SubtleCrypto API.  
+  
+The options object has the following properties:  
+| Property | Description |
+| :-- | :-- |
+| `addChecksum?` | (Optional) If set to `true` (default), a SHA-256 checksum will be calculated and saved with the serialized data. If set to `false`, no checksum will be calculated and saved. |
+| `ensureIntegrity?` | (Optional) If set to `true` (default), the checksum will be checked when importing data and an error will be thrown if it doesn't match. If set to `false`, the checksum will not be checked and no error will be thrown. If no checksum property exists on the imported data (for example because it wasn't enabled in a previous data format version), the checksum check will be skipped regardless of this setting. |
+
+<br>
+
+#### Methods:
+`constructor(stores: DataStore[], options?: DataStoreSerializerOptions)`  
+Creates a new DataStoreSerializer instance with the given DataStore instances and options.  
+If no options are passed, the defaults will be used.  
+  
+`serialize(): Promise<string>`  
+Serializes all DataStore instances passed in the constructor and returns the serialized data as a JSON string.  
+<details><summary>Click to view the structure of the returned data.</summary>  
+
+```jsonc
+[
+  {
+    "id": "foo-data",                               // the ID property given to the DataStore instance
+    "data": "eJyrVkrKTFeyUkrOKM1LLy1WqgUAMvAF6g==", // serialized data (may be compressed / encoded or not)
+    "formatVersion": 2,                             // the format version of the data
+    "encoded": true,                                // only set to true if both encodeData and decodeData are set in the DataStore instance
+    "checksum": "420deadbeef69",                    // property will be missing if addChecksum is set to false
+  },
+  {
+    // ...
+  }
+]
+```
+</details>  
+  
+`deserialize(data: string): Promise<void>`  
+Deserializes the given JSON string and imports the data into the DataStore instances.  
+In the process of importing the data, the migrations will be run, if the `formatVersion` property is lower than the one set on the DataStore instance.
+  
+If `ensureIntegrity` is set to `true` and the checksum doesn't match, an error will be thrown.  
+If `ensureIntegrity` is set to `false`, the checksum check will be skipped entirely.  
+If the `checksum` property is missing on the imported data, the checksum check will also be skipped.  
+If `encoded` is set to `true`, the data will be decoded using the `decodeData` function set on the DataStore instance.  
+
+<br>
+
+<details><summary><b>Example - click to view</b></summary>
+
+```ts
+import { DataStore, DataStoreSerializer, compress, decompress } from "@sv443-network/userutils";
+
+/** This store doesn't have migrations to run and also has no encodeData and decodeData functions */
+const fooStore = new DataStore({
+  id: "foo-data",
+  defaultData: {
+    foo: "hello",
+  },
+  formatVersion: 1,
+});
+
+/** This store has migrations to run and also has encodeData and decodeData functions */
+const barStore = new DataStore({
+  id: "bar-data",
+  defaultData: {
+    foo: "hello",
+  },
+  formatVersion: 2,
+  migrations: {
+    2: (oldData) => ({
+      ...oldData,
+      bar: "world",
+    }),
+  },
+  encodeData: (data) => compress(data, "deflate", "string"),
+  decodeData: (data) => decompress(data, "deflate", "string"),
+});
+
+const serializer = new DataStoreSerializer([fooStore, barStore], {
+  addChecksum: true,
+  ensureIntegrity: true,
+});
+
+async function exportMyDataPls() {
+  const serializedData = await serializer.serialize();
+  // create file and download it:
+  const blob = new Blob([serializedData], { type: "application/json" });
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = `data_export-${new Date().toISOString()}.json`;
+  a.click();
+  a.remove();
+
+  // This function exports an object like this:
+  // [
+  //   {
+  //     "id": "foo-data",
+  //     "data": "{\"foo\":\"hello\"}", // not compressed or encoded because encodeData and decodeData are not set
+  //     "formatVersion": 1,
+  //     "encoded": false,
+  //     "checksum": "420deadbeef69"
+  //   },
+  //   {
+  //     "id": "bar-data",
+  //     "data": "eJyrVkrKTFeyUkrOKM1LLy1WqgUAMvAF6g==", // compressed because encodeData and decodeData are set
+  //     "formatVersion": 2,
+  //     "encoded": true,
+  //     "checksum": "69beefdead420"
+  //   }
+  // ]
+}
+
+async function importMyDataPls() {
+  // grab the data from the file by using the system file picker or any other method
+  const data = await getDataFromSomewhere();
+
+  try {
+    // import the data
+    await serializer.deserialize(data);
+  }
+  catch(err) {
+    console.error(err);
+    alert(`Data import failed: ${err}`);
+  }
+}
+```
+</details>
+
 <br><br>
 
 ### autoPlural()
@@ -1356,6 +1480,73 @@ console.log(decompressed); // "Hello, World!"
 
 </details>
 
+<br>
+
+### computeHash()
+Usage:  
+```ts
+computeHash(input: string | ArrayBuffer, algorithm?: string): Promise<string>
+```
+  
+Computes a hash / checksum of a string or ArrayBuffer using the specified algorithm ("SHA-256" by default).  
+The algorithm must be supported by the [SubtleCrypto API](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/digest).  
+  
+⚠️ This function needs to be called in a secure context (HTTPS) due to the use of the SubtleCrypto API.  
+⚠️ If you use this for cryptography, make sure to use a secure algorithm (under no circumstances use SHA-1) and to [salt](https://en.wikipedia.org/wiki/Salt_(cryptography)) your input data.  
+  
+<details><summary><b>Example - click to view</b></summary>
+
+```ts
+import { computeHash } from "@sv443-network/userutils";
+
+async function run() {
+  const hash1 = await computeHash("Hello, World!");
+  const hash2 = await computeHash("Hello, World!");
+
+  console.log(hash1);           // dffd6021bb2bd5b0af676290809ec3a53191dd81c7f70a4b28688a362182986f
+  console.log(hash1 === hash2); // true (same input = same output)
+
+  const hash3 = await computeHash("Hello, world!"); // lowercase "w"
+  console.log(hash3); // 315f5bdb76d078c43b8ac0064e4a0164612b1fce77c869345bfc94c75894edd3
+}
+
+run();
+```
+</details>
+
+<br>
+
+### randomId()
+Usage:  
+```ts
+randomId(length?: number, radix?: number, enhancedEntropy?: boolean): string
+```
+  
+Generates a random ID of a given length and [radix (base).](https://en.wikipedia.org/wiki/Radix)  
+  
+The default length is 16 and the default radix is 16 (hexadecimal).  
+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.  
+  
+⚠️ 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)
+```
+
+</details>
+
 <br><br>
 
 <!-- #SECTION Arrays -->
@@ -1642,8 +1833,9 @@ They don't alter the runtime behavior of the code, but they can be used to make
 
 ### Stringifiable
 This type describes any value that either is a string itself or can be converted to a string.  
-To be considered stringifiable, the object needs to have a `toString()` method that returns a string (all primitive types have this method).  
-This method allows not just explicit conversion by calling it, but also implicit conversion by passing it into the `String()` constructor or by interpolating it in a template string.  
+To be considered stringifiable, the object needs to have a `toString()` method that returns a string.  
+Most primitives have this method, but something like undefined or null does not (they can only be used in the `String()` constructor or string interpolation).  
+Having this method allows not just explicit conversion by calling it, but also implicit conversion by passing it into the `String()` constructor or by interpolating it in a template string.  
   
 <details><summary><b>Example - click to view</b></summary>
 
@@ -1651,7 +1843,7 @@ This method allows not just explicit conversion by calling it, but also implicit
 import type { Stringifiable } from "@sv443-network/userutils";
 
 function logSomething(value: Stringifiable) {
-  console.log(`Log: ${value}`); // implicit conversion using `value.toString()`
+  console.log(`Log: ${value}`); // implicit conversion to a string
 }
 
 const fooObject = {
@@ -1665,11 +1857,10 @@ const barObject = {
 logSomething("foo");     // "Log: foo"
 logSomething(42);        // "Log: 42"
 logSomething(true);      // "Log: true"
-logSomething({});        // "Log: [object Object]"
 logSomething(Symbol(1)); // "Log: Symbol(1)"
 logSomething(fooObject); // "Log: hello world"
 
-logSomething(barObject); // Type Error
+logSomething(barObject); // Type error
 ```
 
 </details>