@sv443-network/userutils 9.1.0 → 9.2.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @sv443-network/userutils
 
+## 9.2.0
+
+### Minor Changes
+
+- 905fea4: Added function `isDomLoaded()` to check if the DOM is queryable, regardless of `@run-at` setting
+- 4264154: Added parameter `withDecimals` to `digitCount()` (true by default)
+- 4264154: Added function `roundFixed()` to round a floating-point number to the given amount of decimals. Can also round to the given power of 10.
+- 7e492cf: Added `probeElementStyle()` to probe the computed style of a temporary element, allowing to resolve CSS variables and default style values, etc.
+- 905fea4: Added function `onDomLoad()` to call a callback and/or resolve a Promise when the DOM is loaded, even retroactively
+- 4264154: Added function `bitSetHas()` to check if a given value is present in a [bitset](https://www.geeksforgeeks.org/cpp-bitset-and-its-application/)
+- bf55335: Replaced a bunch of generic `Error`s with the new custom error class instances
+- bf55335: Added custom error classes `ChecksumMismatchError`, `DataMigrationError` and `PlatformError`, extending from the base class `UUError`
+  The base class has the additional property `date` which is the time of the error creation
+
+### Patch Changes
+
+- 157dacb: Fixed example code in tsdoc comments of translation functions
+- 4264154: Fixed `digitCount()` not counting decimals by default
+
 ## 9.1.0
 
 ### Minor Changes

package/README-summary.md

@@ -36,6 +36,8 @@ View the documentation of previous major releases:
 - **DOM:**
     - [`SelectorObserver`](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#selectorobserver) - class that manages listeners that are called when selectors are found in the DOM
     - [`getUnsafeWindow()`](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#getunsafewindow) - get the unsafeWindow object or fall back to the regular window object
+    - [`isDomLoaded()`](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#isdomloaded) - check if the DOM has finished loading and can be queried and modified
+    - [`onDomLoad()`](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#ondomload) - run a function or pause async execution until the DOM has finished loading (or immediately if DOM is already loaded)
     - [`addParent()`](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#addparent) - add a parent element around another element
     - [`addGlobalStyle()`](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#addglobalstyle) - add a global style to the page
     - [`preloadImages()`](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#preloadimages) - preload images into the browser cache for faster loading later on
@@ -46,11 +48,14 @@ View the documentation of previous major releases:
     - [`observeElementProp()`](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#observeelementprop) - observe changes to an element's property that can't be observed with MutationObserver
     - [`getSiblingsFrame()`](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#getsiblingsframe) - returns a frame of an element's siblings, with a given alignment and size
     - [`setInnerHtmlUnsafe()`](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#setinnerhtmlunsafe) - set the innerHTML of an element using a [Trusted Types policy](https://developer.mozilla.org/en-US/docs/Web/API/Trusted_Types_API) without sanitizing or escaping it
+    - [`probeElementStyle()`](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#probeelementstyle) - probe the computed style of a temporary element (get default font size, resolve CSS variables, etc.)
 - **Math:**
     - [`clamp()`](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#clamp) - constrain a number between a min and max value
     - [`mapRange()`](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#maprange) - map a number from one range to the same spot in another range
     - [`randRange()`](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#randrange) - generate a random number between a min and max boundary
     - [`digitCount()`](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#digitcount) - calculate the amount of digits in a number
+    - [`roundFixed()`](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#roundfixed) - round a floating-point number at the given amount of decimals, or to the given power of 10
+    - [`bitSetHas()`](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#bitsethas) - check if a bit is set in a [bitset](https://www.geeksforgeeks.org/cpp-bitset-and-its-application/)
 - **Misc:**
     - [`DataStore`](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#datastore) - class that manages a hybrid sync & async persistent JSON database, including data migration
     - [`DataStoreSerializer`](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#datastoreserializer) - class for importing & exporting data of multiple DataStore instances, including compression, checksumming and running migrations
@@ -101,6 +106,11 @@ View the documentation of previous major releases:
     - [`ValueGen`](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#valuegen) - a "generator" value that allows for super flexible value typing and declaration
     - [`StringGen`](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#stringgen) - a "generator" string that allows for super flexible string typing and declaration, including enhanced support for unions
     - [`ListWithLength`](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#listwithlength) - represents an array or object with a numeric `length`, `count` or `size` property
+- **Custom Error classes:**
+    - [`UUError`](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#uuerror) - base class for all custom UserUtils errors - has a custom `date` prop set to the time of creation
+    - [`ChecksumMismatchError`](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#checksummismatcherror) - thrown when a string of data doesn't match its checksum
+    - [`DataMigrationError`](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#datamigrationerror) - thrown when a data migration fails
+    - [`PlatformError`](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#platformerror) - thrown when a function is called in an unsupported environment
 
 <br><br>
 

package/README.md

@@ -39,6 +39,8 @@ View the documentation of previous major releases:
   - [**DOM:**](./docs.md#dom)
     - [`SelectorObserver`](./docs.md#selectorobserver) - class that manages listeners that are called when selectors are found in the DOM
     - [`getUnsafeWindow()`](./docs.md#getunsafewindow) - get the unsafeWindow object or fall back to the regular window object
+    - [`isDomLoaded()`](./docs.md#isdomloaded) - check if the DOM has finished loading and can be queried and modified
+    - [`onDomLoad()`](./docs.md#ondomload) - run a function or pause async execution until the DOM has finished loading (or immediately if DOM is already loaded)
     - [`addParent()`](./docs.md#addparent) - add a parent element around another element
     - [`addGlobalStyle()`](./docs.md#addglobalstyle) - add a global style to the page
     - [`preloadImages()`](./docs.md#preloadimages) - preload images into the browser cache for faster loading later on
@@ -49,11 +51,14 @@ View the documentation of previous major releases:
     - [`observeElementProp()`](./docs.md#observeelementprop) - observe changes to an element's property that can't be observed with MutationObserver
     - [`getSiblingsFrame()`](./docs.md#getsiblingsframe) - returns a frame of an element's siblings, with a given alignment and size
     - [`setInnerHtmlUnsafe()`](./docs.md#setinnerhtmlunsafe) - set the innerHTML of an element using a [Trusted Types policy](https://developer.mozilla.org/en-US/docs/Web/API/Trusted_Types_API) without sanitizing or escaping it
+    - [`probeElementStyle()`](./docs.md#probeelementstyle) - probe the computed style of a temporary element (get default font size, resolve CSS variables, etc.)
   - [**Math:**](./docs.md#math)
     - [`clamp()`](./docs.md#clamp) - constrain a number between a min and max value
     - [`mapRange()`](./docs.md#maprange) - map a number from one range to the same spot in another range
     - [`randRange()`](./docs.md#randrange) - generate a random number between a min and max boundary
     - [`digitCount()`](./docs.md#digitcount) - calculate the amount of digits in a number
+    - [`roundFixed()`](./docs.md#roundfixed) - round a floating-point number at the given amount of decimals, or to the given power of 10
+    - [`bitSetHas()`](./docs.md#bitsethas) - check if a bit is set in a [bitset](https://www.geeksforgeeks.org/cpp-bitset-and-its-application/)
   - [**Misc:**](./docs.md#misc)
     - [`DataStore`](./docs.md#datastore) - class that manages a hybrid sync & async persistent JSON database, including data migration
     - [`DataStoreSerializer`](./docs.md#datastoreserializer) - class for importing & exporting data of multiple DataStore instances, including compression, checksumming and running migrations
@@ -104,6 +109,11 @@ View the documentation of previous major releases:
     - [`ValueGen`](./docs.md#valuegen) - a "generator" value that allows for super flexible value typing and declaration
     - [`StringGen`](./docs.md#stringgen) - a "generator" string that allows for super flexible string typing and declaration, including enhanced support for unions
     - [`ListWithLength`](./docs.md#listwithlength) - represents an array or object with a numeric `length`, `count` or `size` property
+  - [**Custom Error classes**](./docs.md#error-classes)
+    - [`UUError`](./docs.md#uuerror) - base class for all custom UserUtils errors - has a custom `date` prop set to the time of creation
+    - [`ChecksumMismatchError`](./docs.md#checksummismatcherror) - thrown when a string of data doesn't match its checksum
+    - [`DataMigrationError`](./docs.md#datamigrationerror) - thrown when a data migration fails
+    - [`PlatformError`](./docs.md#platformerror) - thrown when a function is called in an unsupported environment
 
 <br><br>
 

package/dist/index.cjs

@@ -99,13 +99,21 @@ function randRange(...args) {
   } else
     return Math.floor(Math.random() * (max - min + 1)) + min;
 }
-function digitCount(num) {
+function digitCount(num, withDecimals = true) {
   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
-  );
+  const [intPart, decPart] = num.toString().split(".");
+  const intDigits = intPart === "0" ? 1 : Math.floor(Math.log10(Math.abs(Number(intPart))) + 1);
+  const decDigits = withDecimals && decPart ? decPart.length : 0;
+  return intDigits + decDigits;
+}
+function roundFixed(num, fractionDigits) {
+  const scale = 10 ** fractionDigits;
+  return Math.round(num * scale) / scale;
+}
+function bitSetHas(bitSet, checkVal) {
+  return (bitSet & checkVal) === checkVal;
 }
 
 // lib/array.ts
@@ -130,7 +138,7 @@ function randomizeArray(array) {
   if (array.length === 0)
     return retArray;
   for (let i = retArray.length - 1; i > 0; i--) {
-    const j = Math.floor(randRange(0, 1e4) / 1e4 * (i + 1));
+    const j = Math.floor(Math.random() * (i + 1));
     [retArray[i], retArray[j]] = [retArray[j], retArray[i]];
   }
   return retArray;
@@ -173,10 +181,10 @@ function darkenColor(color, percent, upperCase = false) {
   else if (color.startsWith("rgb")) {
     const rgbValues = (_a = color.match(/\d+(\.\d+)?/g)) == null ? undefined : _a.map(Number);
     if (!rgbValues)
-      throw new Error("Invalid RGB/RGBA color format");
+      throw new TypeError("Invalid RGB/RGBA color format");
     [r, g, b, a] = rgbValues;
   } else
-    throw new Error("Unsupported color format");
+    throw new TypeError("Unsupported color format");
   [r, g, b] = darkenRgb(r, g, b, percent);
   if (isHexCol)
     return rgbToHex(r, g, b, a, color.startsWith("#"), upperCase);
@@ -185,10 +193,39 @@ function darkenColor(color, percent, upperCase = false) {
   else if (color.startsWith("rgb"))
     return `rgb(${r}, ${g}, ${b})`;
   else
-    throw new Error("Unsupported color format");
+    throw new TypeError("Unsupported color format");
 }
 
+// lib/errors.ts
+var UUError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    __publicField(this, "date");
+    this.date = /* @__PURE__ */ new Date();
+  }
+};
+var ChecksumMismatchError = class extends UUError {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "ChecksumMismatchError";
+  }
+};
+var MigrationError = class extends UUError {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "MigrationError";
+  }
+};
+var PlatformError = class extends UUError {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "PlatformError";
+  }
+};
+
 // lib/dom.ts
+var domReady = false;
+document.addEventListener("DOMContentLoaded", () => domReady = true);
 function getUnsafeWindow() {
   try {
     return unsafeWindow;
@@ -244,8 +281,8 @@ function openInNewTab(href, background, additionalProps) {
 }
 function interceptEvent(eventObject, eventName, predicate = () => true) {
   var _a;
-  if ((eventObject === window || eventObject === getUnsafeWindow()) && ((_a = GM == null ? undefined : GM.info) == null ? undefined : _a.scriptHandler) && GM.info.scriptHandler === "FireMonkey")
-    throw new Error("Intercepting window events is not supported on FireMonkey due to the isolated context the userscript runs in.");
+  if (((_a = GM == null ? undefined : GM.info) == null ? undefined : _a.scriptHandler) && GM.info.scriptHandler === "FireMonkey" && (eventObject === window || eventObject === getUnsafeWindow()))
+    throw new PlatformError("Intercepting window events is not supported on FireMonkey due to the isolated context the userscript runs in.");
   Error.stackTraceLimit = Math.max(Error.stackTraceLimit, 100);
   if (isNaN(Error.stackTraceLimit))
     Error.stackTraceLimit = 100;
@@ -327,6 +364,36 @@ function setInnerHtmlUnsafe(element, html) {
   element.innerHTML = (_c = (_b = ttPolicy == null ? undefined : ttPolicy.createHTML) == null ? undefined : _b.call(ttPolicy, html)) != null ? _c : html;
   return element;
 }
+function probeElementStyle(probeStyle, element, hideOffscreen = true, parentElement = document.body) {
+  const el = element ? typeof element === "function" ? element() : element : document.createElement("span");
+  if (hideOffscreen) {
+    el.style.position = "absolute";
+    el.style.left = "-9999px";
+    el.style.top = "-9999px";
+    el.style.zIndex = "-9999";
+  }
+  el.classList.add("_uu_probe_element");
+  parentElement.appendChild(el);
+  const style = window.getComputedStyle(el);
+  const result = probeStyle(style, el);
+  setTimeout(() => el.remove(), 1);
+  return result;
+}
+function isDomLoaded() {
+  return domReady;
+}
+function onDomLoad(cb) {
+  return new Promise((res) => {
+    if (domReady) {
+      cb == null ? undefined : cb();
+      res();
+    } else
+      document.addEventListener("DOMContentLoaded", () => {
+        cb == null ? undefined : cb();
+        res();
+      });
+  });
+}
 
 // lib/crypto.ts
 function compress(input, compressionFormat, outputType = "string") {
@@ -374,6 +441,8 @@ function computeHash(input, algorithm = "SHA-256") {
   });
 }
 function randomId(length = 16, radix = 16, enhancedEntropy = false, randomCase = true) {
+  if (radix < 2 || radix > 36)
+    throw new RangeError("The radix argument must be between 2 and 36");
   let arr = [];
   const caseArr = randomCase ? [0, 1] : [0];
   if (enhancedEntropy) {
@@ -547,8 +616,7 @@ var DataStore = class {
             lastFmtVer = oldFmtVer = ver;
           } catch (err) {
             if (!resetOnError)
-              throw new Error(`Error while running migration function for format version '${fmtVer}'`);
-            console.error(`Error while running migration function for format version '${fmtVer}' - resetting to the default value.`, err);
+              throw new MigrationError(`Error while running migration function for format version '${fmtVer}'`, { cause: err });
             yield this.saveDefaultData();
             return this.getData();
           }
@@ -609,7 +677,6 @@ var DataStore = class {
       return JSON.parse(decRes != null ? decRes : data);
     });
   }
-  //#region misc
   /** Copies a JSON-compatible object and loses all its internal references in the process */
   deepCopy(obj) {
     return JSON.parse(JSON.stringify(obj));
@@ -661,7 +728,7 @@ var DataStore = class {
 };
 
 // lib/DataStoreSerializer.ts
-var DataStoreSerializer = class {
+var DataStoreSerializer = class _DataStoreSerializer {
   constructor(stores, options = {}) {
     __publicField(this, "stores");
     __publicField(this, "options");
@@ -679,27 +746,25 @@ var DataStoreSerializer = class {
       return computeHash(input, "SHA-256");
     });
   }
-  /** Serializes a DataStore instance */
-  serializeStore(storeInst) {
-    return __async(this, null, function* () {
-      const data = storeInst.encodingEnabled() ? yield storeInst.encodeData(JSON.stringify(storeInst.getData())) : JSON.stringify(storeInst.getData());
-      const checksum = this.options.addChecksum ? yield this.calcChecksum(data) : undefined;
-      return {
-        id: storeInst.id,
-        data,
-        formatVersion: storeInst.formatVersion,
-        encoded: storeInst.encodingEnabled(),
-        checksum
-      };
-    });
-  }
-  /** Serializes the data stores into a string */
-  serialize() {
+  /**
+   * Serializes the data stores into a string.  
+   * @param useEncoding Whether to encode the data using each DataStore's `encodeData()` method
+   * @param stringified Whether to return the result as a string or as an array of `SerializedDataStore` objects
+   */
+  serialize(useEncoding = true, stringified = true) {
     return __async(this, null, function* () {
       const serData = [];
-      for (const store of this.stores)
-        serData.push(yield this.serializeStore(store));
-      return JSON.stringify(serData);
+      for (const storeInst of this.stores) {
+        const data = useEncoding && storeInst.encodingEnabled() ? yield storeInst.encodeData(JSON.stringify(storeInst.getData())) : JSON.stringify(storeInst.getData());
+        serData.push({
+          id: storeInst.id,
+          data,
+          formatVersion: storeInst.formatVersion,
+          encoded: useEncoding && storeInst.encodingEnabled(),
+          checksum: this.options.addChecksum ? yield this.calcChecksum(data) : undefined
+        });
+      }
+      return stringified ? JSON.stringify(serData) : serData;
     });
   }
   /**
@@ -708,7 +773,9 @@ var DataStoreSerializer = class {
    */
   deserialize(serializedData) {
     return __async(this, null, function* () {
-      const deserStores = JSON.parse(serializedData);
+      const deserStores = typeof serializedData === "string" ? JSON.parse(serializedData) : serializedData;
+      if (!Array.isArray(deserStores) || !deserStores.every(_DataStoreSerializer.isSerializedDataStore))
+        throw new TypeError("Invalid serialized data format! Expected an array of SerializedDataStore objects.");
       for (const storeData of deserStores) {
         const storeInst = this.stores.find((s) => s.id === storeData.id);
         if (!storeInst)
@@ -716,7 +783,7 @@ var DataStoreSerializer = class {
         if (this.options.ensureIntegrity && typeof storeData.checksum === "string") {
           const checksum = yield this.calcChecksum(storeData.data);
           if (checksum !== storeData.checksum)
-            throw new Error(`Checksum mismatch for DataStore with ID "${storeData.id}"!
+            throw new ChecksumMismatchError(`Checksum mismatch for DataStore with ID "${storeData.id}"!
 Expected: ${storeData.checksum}
 Has: ${checksum}`);
         }
@@ -760,6 +827,10 @@ Has: ${checksum}`);
       return Promise.allSettled(this.stores.map((store) => store.deleteData()));
     });
   }
+  /** Checks if a given value is a SerializedDataStore object */
+  static isSerializedDataStore(obj) {
+    return typeof obj === "object" && obj !== null && "id" in obj && "data" in obj && "formatVersion" in obj && "encoded" in obj;
+  }
 };
 var NanoEmitter = class {
   constructor(options = {}) {
@@ -899,7 +970,7 @@ var Debouncer = class extends NanoEmitter {
         }, this.timeout);
         break;
       default:
-        throw new Error(`Invalid debouncer type: ${this.type}`);
+        throw new TypeError(`Invalid debouncer type: ${this.type}`);
     }
   }
 };
@@ -1403,8 +1474,6 @@ function getListLength(obj, zeroOnInvalid = true) {
 }
 
 // lib/SelectorObserver.ts
-var domLoaded = false;
-document.addEventListener("DOMContentLoaded", () => domLoaded = true);
 var SelectorObserver = class {
   constructor(baseElement, options = {}) {
     __publicField(this, "enabled", false);
@@ -1445,7 +1514,7 @@ var SelectorObserver = class {
   }
   /** Call to check all selectors in the {@linkcode listenerMap} using {@linkcode checkSelector()} */
   checkAllSelectors() {
-    if (!this.enabled || !domLoaded)
+    if (!this.enabled || !isDomLoaded())
       return;
     for (const [selector, listeners] of this.listenerMap.entries())
       this.checkSelector(selector, listeners);
@@ -1589,9 +1658,9 @@ function translate(language, key, ...trArgs) {
   if (typeof language !== "string" || language.length === 0 || typeof trObj !== "object" || trObj === null)
     return fallbackLang ? translate(fallbackLang, key, ...trArgs) : key;
   const transformTrVal = (trKey, trValue) => {
-    const tfs = valTransforms.filter(({ regex }) => new RegExp(regex).test(trValue));
+    const tfs = valTransforms.filter(({ regex }) => new RegExp(regex).test(String(trValue)));
     if (tfs.length === 0)
-      return trValue;
+      return String(trValue);
     let retStr = String(trValue);
     for (const tf of tfs) {
       const re = new RegExp(tf.regex);
@@ -1740,15 +1809,20 @@ var tr = {
   }
 };
 
+exports.ChecksumMismatchError = ChecksumMismatchError;
 exports.DataStore = DataStore;
 exports.DataStoreSerializer = DataStoreSerializer;
 exports.Debouncer = Debouncer;
 exports.Dialog = Dialog;
+exports.MigrationError = MigrationError;
 exports.NanoEmitter = NanoEmitter;
+exports.PlatformError = PlatformError;
 exports.SelectorObserver = SelectorObserver;
+exports.UUError = UUError;
 exports.addGlobalStyle = addGlobalStyle;
 exports.addParent = addParent;
 exports.autoPlural = autoPlural;
+exports.bitSetHas = bitSetHas;
 exports.clamp = clamp;
 exports.compress = compress;
 exports.computeHash = computeHash;
@@ -1768,20 +1842,24 @@ exports.hexToRgb = hexToRgb;
 exports.insertValues = insertValues;
 exports.interceptEvent = interceptEvent;
 exports.interceptWindowEvent = interceptWindowEvent;
+exports.isDomLoaded = isDomLoaded;
 exports.isScrollable = isScrollable;
 exports.lightenColor = lightenColor;
 exports.mapRange = mapRange;
 exports.observeElementProp = observeElementProp;
+exports.onDomLoad = onDomLoad;
 exports.openDialogs = openDialogs;
 exports.openInNewTab = openInNewTab;
 exports.pauseFor = pauseFor;
 exports.preloadImages = preloadImages;
+exports.probeElementStyle = probeElementStyle;
 exports.randRange = randRange;
 exports.randomId = randomId;
 exports.randomItem = randomItem;
 exports.randomItemIndex = randomItemIndex;
 exports.randomizeArray = randomizeArray;
 exports.rgbToHex = rgbToHex;
+exports.roundFixed = roundFixed;
 exports.setInnerHtmlUnsafe = setInnerHtmlUnsafe;
 exports.takeRandomItem = takeRandomItem;
 exports.tr = tr;

package/dist/index.global.js

@@ -7,8 +7,8 @@
 
 // ==UserLibrary==
 // @name         UserUtils
-// @description  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 much more
-// @version      9.1.0
+// @description  General purpose DOM/GreaseMonkey library that allows you to register listeners for when CSS selectors exist, intercept events, create persistent & synchronous data stores, modify the DOM more easily and much more
+// @version      9.2.0
 // @license      MIT
 // @copyright    Sv443 (https://github.com/Sv443)
 
@@ -117,13 +117,21 @@ var UserUtils = (function (exports) {
     } else
       return Math.floor(Math.random() * (max - min + 1)) + min;
   }
-  function digitCount(num) {
+  function digitCount(num, withDecimals = true) {
     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
-    );
+    const [intPart, decPart] = num.toString().split(".");
+    const intDigits = intPart === "0" ? 1 : Math.floor(Math.log10(Math.abs(Number(intPart))) + 1);
+    const decDigits = withDecimals && decPart ? decPart.length : 0;
+    return intDigits + decDigits;
+  }
+  function roundFixed(num, fractionDigits) {
+    const scale = 10 ** fractionDigits;
+    return Math.round(num * scale) / scale;
+  }
+  function bitSetHas(bitSet, checkVal) {
+    return (bitSet & checkVal) === checkVal;
   }
 
   // lib/array.ts
@@ -148,7 +156,7 @@ var UserUtils = (function (exports) {
     if (array.length === 0)
       return retArray;
     for (let i = retArray.length - 1; i > 0; i--) {
-      const j = Math.floor(randRange(0, 1e4) / 1e4 * (i + 1));
+      const j = Math.floor(Math.random() * (i + 1));
       [retArray[i], retArray[j]] = [retArray[j], retArray[i]];
     }
     return retArray;
@@ -191,10 +199,10 @@ var UserUtils = (function (exports) {
     else if (color.startsWith("rgb")) {
       const rgbValues = (_a = color.match(/\d+(\.\d+)?/g)) == null ? undefined : _a.map(Number);
       if (!rgbValues)
-        throw new Error("Invalid RGB/RGBA color format");
+        throw new TypeError("Invalid RGB/RGBA color format");
       [r, g, b, a] = rgbValues;
     } else
-      throw new Error("Unsupported color format");
+      throw new TypeError("Unsupported color format");
     [r, g, b] = darkenRgb(r, g, b, percent);
     if (isHexCol)
       return rgbToHex(r, g, b, a, color.startsWith("#"), upperCase);
@@ -203,10 +211,39 @@ var UserUtils = (function (exports) {
     else if (color.startsWith("rgb"))
       return `rgb(${r}, ${g}, ${b})`;
     else
-      throw new Error("Unsupported color format");
+      throw new TypeError("Unsupported color format");
   }
 
+  // lib/errors.ts
+  var UUError = class extends Error {
+    constructor(message, options) {
+      super(message, options);
+      __publicField(this, "date");
+      this.date = /* @__PURE__ */ new Date();
+    }
+  };
+  var ChecksumMismatchError = class extends UUError {
+    constructor(message, options) {
+      super(message, options);
+      this.name = "ChecksumMismatchError";
+    }
+  };
+  var MigrationError = class extends UUError {
+    constructor(message, options) {
+      super(message, options);
+      this.name = "MigrationError";
+    }
+  };
+  var PlatformError = class extends UUError {
+    constructor(message, options) {
+      super(message, options);
+      this.name = "PlatformError";
+    }
+  };
+
   // lib/dom.ts
+  var domReady = false;
+  document.addEventListener("DOMContentLoaded", () => domReady = true);
   function getUnsafeWindow() {
     try {
       return unsafeWindow;
@@ -262,8 +299,8 @@ var UserUtils = (function (exports) {
   }
   function interceptEvent(eventObject, eventName, predicate = () => true) {
     var _a;
-    if ((eventObject === window || eventObject === getUnsafeWindow()) && ((_a = GM == null ? undefined : GM.info) == null ? undefined : _a.scriptHandler) && GM.info.scriptHandler === "FireMonkey")
-      throw new Error("Intercepting window events is not supported on FireMonkey due to the isolated context the userscript runs in.");
+    if (((_a = GM == null ? undefined : GM.info) == null ? undefined : _a.scriptHandler) && GM.info.scriptHandler === "FireMonkey" && (eventObject === window || eventObject === getUnsafeWindow()))
+      throw new PlatformError("Intercepting window events is not supported on FireMonkey due to the isolated context the userscript runs in.");
     Error.stackTraceLimit = Math.max(Error.stackTraceLimit, 100);
     if (isNaN(Error.stackTraceLimit))
       Error.stackTraceLimit = 100;
@@ -345,6 +382,36 @@ var UserUtils = (function (exports) {
     element.innerHTML = (_c = (_b = ttPolicy == null ? undefined : ttPolicy.createHTML) == null ? undefined : _b.call(ttPolicy, html)) != null ? _c : html;
     return element;
   }
+  function probeElementStyle(probeStyle, element, hideOffscreen = true, parentElement = document.body) {
+    const el = element ? typeof element === "function" ? element() : element : document.createElement("span");
+    if (hideOffscreen) {
+      el.style.position = "absolute";
+      el.style.left = "-9999px";
+      el.style.top = "-9999px";
+      el.style.zIndex = "-9999";
+    }
+    el.classList.add("_uu_probe_element");
+    parentElement.appendChild(el);
+    const style = window.getComputedStyle(el);
+    const result = probeStyle(style, el);
+    setTimeout(() => el.remove(), 1);
+    return result;
+  }
+  function isDomLoaded() {
+    return domReady;
+  }
+  function onDomLoad(cb) {
+    return new Promise((res) => {
+      if (domReady) {
+        cb == null ? undefined : cb();
+        res();
+      } else
+        document.addEventListener("DOMContentLoaded", () => {
+          cb == null ? undefined : cb();
+          res();
+        });
+    });
+  }
 
   // lib/crypto.ts
   function compress(input, compressionFormat, outputType = "string") {
@@ -392,6 +459,8 @@ var UserUtils = (function (exports) {
     });
   }
   function randomId(length = 16, radix = 16, enhancedEntropy = false, randomCase = true) {
+    if (radix < 2 || radix > 36)
+      throw new RangeError("The radix argument must be between 2 and 36");
     let arr = [];
     const caseArr = randomCase ? [0, 1] : [0];
     if (enhancedEntropy) {
@@ -565,8 +634,7 @@ var UserUtils = (function (exports) {
               lastFmtVer = oldFmtVer = ver;
             } catch (err) {
               if (!resetOnError)
-                throw new Error(`Error while running migration function for format version '${fmtVer}'`);
-              console.error(`Error while running migration function for format version '${fmtVer}' - resetting to the default value.`, err);
+                throw new MigrationError(`Error while running migration function for format version '${fmtVer}'`, { cause: err });
               yield this.saveDefaultData();
               return this.getData();
             }
@@ -627,7 +695,6 @@ var UserUtils = (function (exports) {
         return JSON.parse(decRes != null ? decRes : data);
       });
     }
-    //#region misc
     /** Copies a JSON-compatible object and loses all its internal references in the process */
     deepCopy(obj) {
       return JSON.parse(JSON.stringify(obj));
@@ -679,7 +746,7 @@ var UserUtils = (function (exports) {
   };
 
   // lib/DataStoreSerializer.ts
-  var DataStoreSerializer = class {
+  var DataStoreSerializer = class _DataStoreSerializer {
     constructor(stores, options = {}) {
       __publicField(this, "stores");
       __publicField(this, "options");
@@ -697,27 +764,25 @@ var UserUtils = (function (exports) {
         return computeHash(input, "SHA-256");
       });
     }
-    /** Serializes a DataStore instance */
-    serializeStore(storeInst) {
-      return __async(this, null, function* () {
-        const data = storeInst.encodingEnabled() ? yield storeInst.encodeData(JSON.stringify(storeInst.getData())) : JSON.stringify(storeInst.getData());
-        const checksum = this.options.addChecksum ? yield this.calcChecksum(data) : undefined;
-        return {
-          id: storeInst.id,
-          data,
-          formatVersion: storeInst.formatVersion,
-          encoded: storeInst.encodingEnabled(),
-          checksum
-        };
-      });
-    }
-    /** Serializes the data stores into a string */
-    serialize() {
+    /**
+     * Serializes the data stores into a string.  
+     * @param useEncoding Whether to encode the data using each DataStore's `encodeData()` method
+     * @param stringified Whether to return the result as a string or as an array of `SerializedDataStore` objects
+     */
+    serialize(useEncoding = true, stringified = true) {
       return __async(this, null, function* () {
         const serData = [];
-        for (const store of this.stores)
-          serData.push(yield this.serializeStore(store));
-        return JSON.stringify(serData);
+        for (const storeInst of this.stores) {
+          const data = useEncoding && storeInst.encodingEnabled() ? yield storeInst.encodeData(JSON.stringify(storeInst.getData())) : JSON.stringify(storeInst.getData());
+          serData.push({
+            id: storeInst.id,
+            data,
+            formatVersion: storeInst.formatVersion,
+            encoded: useEncoding && storeInst.encodingEnabled(),
+            checksum: this.options.addChecksum ? yield this.calcChecksum(data) : undefined
+          });
+        }
+        return stringified ? JSON.stringify(serData) : serData;
       });
     }
     /**
@@ -726,7 +791,9 @@ var UserUtils = (function (exports) {
      */
     deserialize(serializedData) {
       return __async(this, null, function* () {
-        const deserStores = JSON.parse(serializedData);
+        const deserStores = typeof serializedData === "string" ? JSON.parse(serializedData) : serializedData;
+        if (!Array.isArray(deserStores) || !deserStores.every(_DataStoreSerializer.isSerializedDataStore))
+          throw new TypeError("Invalid serialized data format! Expected an array of SerializedDataStore objects.");
         for (const storeData of deserStores) {
           const storeInst = this.stores.find((s) => s.id === storeData.id);
           if (!storeInst)
@@ -734,7 +801,7 @@ var UserUtils = (function (exports) {
           if (this.options.ensureIntegrity && typeof storeData.checksum === "string") {
             const checksum = yield this.calcChecksum(storeData.data);
             if (checksum !== storeData.checksum)
-              throw new Error(`Checksum mismatch for DataStore with ID "${storeData.id}"!
+              throw new ChecksumMismatchError(`Checksum mismatch for DataStore with ID "${storeData.id}"!
 Expected: ${storeData.checksum}
 Has: ${checksum}`);
           }
@@ -778,6 +845,10 @@ Has: ${checksum}`);
         return Promise.allSettled(this.stores.map((store) => store.deleteData()));
       });
     }
+    /** Checks if a given value is a SerializedDataStore object */
+    static isSerializedDataStore(obj) {
+      return typeof obj === "object" && obj !== null && "id" in obj && "data" in obj && "formatVersion" in obj && "encoded" in obj;
+    }
   };
 
   // node_modules/.pnpm/nanoevents@9.1.0/node_modules/nanoevents/index.js
@@ -937,7 +1008,7 @@ Has: ${checksum}`);
           }, this.timeout);
           break;
         default:
-          throw new Error(`Invalid debouncer type: ${this.type}`);
+          throw new TypeError(`Invalid debouncer type: ${this.type}`);
       }
     }
   };
@@ -1441,8 +1512,6 @@ Has: ${checksum}`);
   }
 
   // lib/SelectorObserver.ts
-  var domLoaded = false;
-  document.addEventListener("DOMContentLoaded", () => domLoaded = true);
   var SelectorObserver = class {
     constructor(baseElement, options = {}) {
       __publicField(this, "enabled", false);
@@ -1483,7 +1552,7 @@ Has: ${checksum}`);
     }
     /** Call to check all selectors in the {@linkcode listenerMap} using {@linkcode checkSelector()} */
     checkAllSelectors() {
-      if (!this.enabled || !domLoaded)
+      if (!this.enabled || !isDomLoaded())
         return;
       for (const [selector, listeners] of this.listenerMap.entries())
         this.checkSelector(selector, listeners);
@@ -1627,9 +1696,9 @@ Has: ${checksum}`);
     if (typeof language !== "string" || language.length === 0 || typeof trObj !== "object" || trObj === null)
       return fallbackLang ? translate(fallbackLang, key, ...trArgs) : key;
     const transformTrVal = (trKey, trValue) => {
-      const tfs = valTransforms.filter(({ regex }) => new RegExp(regex).test(trValue));
+      const tfs = valTransforms.filter(({ regex }) => new RegExp(regex).test(String(trValue)));
       if (tfs.length === 0)
-        return trValue;
+        return String(trValue);
       let retStr = String(trValue);
       for (const tf of tfs) {
         const re = new RegExp(tf.regex);
@@ -1778,15 +1847,20 @@ Has: ${checksum}`);
     }
   };
 
+  exports.ChecksumMismatchError = ChecksumMismatchError;
   exports.DataStore = DataStore;
   exports.DataStoreSerializer = DataStoreSerializer;
   exports.Debouncer = Debouncer;
   exports.Dialog = Dialog;
+  exports.MigrationError = MigrationError;
   exports.NanoEmitter = NanoEmitter;
+  exports.PlatformError = PlatformError;
   exports.SelectorObserver = SelectorObserver;
+  exports.UUError = UUError;
   exports.addGlobalStyle = addGlobalStyle;
   exports.addParent = addParent;
   exports.autoPlural = autoPlural;
+  exports.bitSetHas = bitSetHas;
   exports.clamp = clamp;
   exports.compress = compress;
   exports.computeHash = computeHash;
@@ -1806,20 +1880,24 @@ Has: ${checksum}`);
   exports.insertValues = insertValues;
   exports.interceptEvent = interceptEvent;
   exports.interceptWindowEvent = interceptWindowEvent;
+  exports.isDomLoaded = isDomLoaded;
   exports.isScrollable = isScrollable;
   exports.lightenColor = lightenColor;
   exports.mapRange = mapRange;
   exports.observeElementProp = observeElementProp;
+  exports.onDomLoad = onDomLoad;
   exports.openDialogs = openDialogs;
   exports.openInNewTab = openInNewTab;
   exports.pauseFor = pauseFor;
   exports.preloadImages = preloadImages;
+  exports.probeElementStyle = probeElementStyle;
   exports.randRange = randRange;
   exports.randomId = randomId;
   exports.randomItem = randomItem;
   exports.randomItemIndex = randomItemIndex;
   exports.randomizeArray = randomizeArray;
   exports.rgbToHex = rgbToHex;
+  exports.roundFixed = roundFixed;
   exports.setInnerHtmlUnsafe = setInnerHtmlUnsafe;
   exports.takeRandomItem = takeRandomItem;
   exports.tr = tr;

package/dist/index.js

@@ -97,13 +97,21 @@ function randRange(...args) {
   } else
     return Math.floor(Math.random() * (max - min + 1)) + min;
 }
-function digitCount(num) {
+function digitCount(num, withDecimals = true) {
   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
-  );
+  const [intPart, decPart] = num.toString().split(".");
+  const intDigits = intPart === "0" ? 1 : Math.floor(Math.log10(Math.abs(Number(intPart))) + 1);
+  const decDigits = withDecimals && decPart ? decPart.length : 0;
+  return intDigits + decDigits;
+}
+function roundFixed(num, fractionDigits) {
+  const scale = 10 ** fractionDigits;
+  return Math.round(num * scale) / scale;
+}
+function bitSetHas(bitSet, checkVal) {
+  return (bitSet & checkVal) === checkVal;
 }
 
 // lib/array.ts
@@ -128,7 +136,7 @@ function randomizeArray(array) {
   if (array.length === 0)
     return retArray;
   for (let i = retArray.length - 1; i > 0; i--) {
-    const j = Math.floor(randRange(0, 1e4) / 1e4 * (i + 1));
+    const j = Math.floor(Math.random() * (i + 1));
     [retArray[i], retArray[j]] = [retArray[j], retArray[i]];
   }
   return retArray;
@@ -171,10 +179,10 @@ function darkenColor(color, percent, upperCase = false) {
   else if (color.startsWith("rgb")) {
     const rgbValues = (_a = color.match(/\d+(\.\d+)?/g)) == null ? undefined : _a.map(Number);
     if (!rgbValues)
-      throw new Error("Invalid RGB/RGBA color format");
+      throw new TypeError("Invalid RGB/RGBA color format");
     [r, g, b, a] = rgbValues;
   } else
-    throw new Error("Unsupported color format");
+    throw new TypeError("Unsupported color format");
   [r, g, b] = darkenRgb(r, g, b, percent);
   if (isHexCol)
     return rgbToHex(r, g, b, a, color.startsWith("#"), upperCase);
@@ -183,10 +191,39 @@ function darkenColor(color, percent, upperCase = false) {
   else if (color.startsWith("rgb"))
     return `rgb(${r}, ${g}, ${b})`;
   else
-    throw new Error("Unsupported color format");
+    throw new TypeError("Unsupported color format");
 }
 
+// lib/errors.ts
+var UUError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    __publicField(this, "date");
+    this.date = /* @__PURE__ */ new Date();
+  }
+};
+var ChecksumMismatchError = class extends UUError {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "ChecksumMismatchError";
+  }
+};
+var MigrationError = class extends UUError {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "MigrationError";
+  }
+};
+var PlatformError = class extends UUError {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "PlatformError";
+  }
+};
+
 // lib/dom.ts
+var domReady = false;
+document.addEventListener("DOMContentLoaded", () => domReady = true);
 function getUnsafeWindow() {
   try {
     return unsafeWindow;
@@ -242,8 +279,8 @@ function openInNewTab(href, background, additionalProps) {
 }
 function interceptEvent(eventObject, eventName, predicate = () => true) {
   var _a;
-  if ((eventObject === window || eventObject === getUnsafeWindow()) && ((_a = GM == null ? undefined : GM.info) == null ? undefined : _a.scriptHandler) && GM.info.scriptHandler === "FireMonkey")
-    throw new Error("Intercepting window events is not supported on FireMonkey due to the isolated context the userscript runs in.");
+  if (((_a = GM == null ? undefined : GM.info) == null ? undefined : _a.scriptHandler) && GM.info.scriptHandler === "FireMonkey" && (eventObject === window || eventObject === getUnsafeWindow()))
+    throw new PlatformError("Intercepting window events is not supported on FireMonkey due to the isolated context the userscript runs in.");
   Error.stackTraceLimit = Math.max(Error.stackTraceLimit, 100);
   if (isNaN(Error.stackTraceLimit))
     Error.stackTraceLimit = 100;
@@ -325,6 +362,36 @@ function setInnerHtmlUnsafe(element, html) {
   element.innerHTML = (_c = (_b = ttPolicy == null ? undefined : ttPolicy.createHTML) == null ? undefined : _b.call(ttPolicy, html)) != null ? _c : html;
   return element;
 }
+function probeElementStyle(probeStyle, element, hideOffscreen = true, parentElement = document.body) {
+  const el = element ? typeof element === "function" ? element() : element : document.createElement("span");
+  if (hideOffscreen) {
+    el.style.position = "absolute";
+    el.style.left = "-9999px";
+    el.style.top = "-9999px";
+    el.style.zIndex = "-9999";
+  }
+  el.classList.add("_uu_probe_element");
+  parentElement.appendChild(el);
+  const style = window.getComputedStyle(el);
+  const result = probeStyle(style, el);
+  setTimeout(() => el.remove(), 1);
+  return result;
+}
+function isDomLoaded() {
+  return domReady;
+}
+function onDomLoad(cb) {
+  return new Promise((res) => {
+    if (domReady) {
+      cb == null ? undefined : cb();
+      res();
+    } else
+      document.addEventListener("DOMContentLoaded", () => {
+        cb == null ? undefined : cb();
+        res();
+      });
+  });
+}
 
 // lib/crypto.ts
 function compress(input, compressionFormat, outputType = "string") {
@@ -372,6 +439,8 @@ function computeHash(input, algorithm = "SHA-256") {
   });
 }
 function randomId(length = 16, radix = 16, enhancedEntropy = false, randomCase = true) {
+  if (radix < 2 || radix > 36)
+    throw new RangeError("The radix argument must be between 2 and 36");
   let arr = [];
   const caseArr = randomCase ? [0, 1] : [0];
   if (enhancedEntropy) {
@@ -545,8 +614,7 @@ var DataStore = class {
             lastFmtVer = oldFmtVer = ver;
           } catch (err) {
             if (!resetOnError)
-              throw new Error(`Error while running migration function for format version '${fmtVer}'`);
-            console.error(`Error while running migration function for format version '${fmtVer}' - resetting to the default value.`, err);
+              throw new MigrationError(`Error while running migration function for format version '${fmtVer}'`, { cause: err });
             yield this.saveDefaultData();
             return this.getData();
           }
@@ -607,7 +675,6 @@ var DataStore = class {
       return JSON.parse(decRes != null ? decRes : data);
     });
   }
-  //#region misc
   /** Copies a JSON-compatible object and loses all its internal references in the process */
   deepCopy(obj) {
     return JSON.parse(JSON.stringify(obj));
@@ -659,7 +726,7 @@ var DataStore = class {
 };
 
 // lib/DataStoreSerializer.ts
-var DataStoreSerializer = class {
+var DataStoreSerializer = class _DataStoreSerializer {
   constructor(stores, options = {}) {
     __publicField(this, "stores");
     __publicField(this, "options");
@@ -677,27 +744,25 @@ var DataStoreSerializer = class {
       return computeHash(input, "SHA-256");
     });
   }
-  /** Serializes a DataStore instance */
-  serializeStore(storeInst) {
-    return __async(this, null, function* () {
-      const data = storeInst.encodingEnabled() ? yield storeInst.encodeData(JSON.stringify(storeInst.getData())) : JSON.stringify(storeInst.getData());
-      const checksum = this.options.addChecksum ? yield this.calcChecksum(data) : undefined;
-      return {
-        id: storeInst.id,
-        data,
-        formatVersion: storeInst.formatVersion,
-        encoded: storeInst.encodingEnabled(),
-        checksum
-      };
-    });
-  }
-  /** Serializes the data stores into a string */
-  serialize() {
+  /**
+   * Serializes the data stores into a string.  
+   * @param useEncoding Whether to encode the data using each DataStore's `encodeData()` method
+   * @param stringified Whether to return the result as a string or as an array of `SerializedDataStore` objects
+   */
+  serialize(useEncoding = true, stringified = true) {
     return __async(this, null, function* () {
       const serData = [];
-      for (const store of this.stores)
-        serData.push(yield this.serializeStore(store));
-      return JSON.stringify(serData);
+      for (const storeInst of this.stores) {
+        const data = useEncoding && storeInst.encodingEnabled() ? yield storeInst.encodeData(JSON.stringify(storeInst.getData())) : JSON.stringify(storeInst.getData());
+        serData.push({
+          id: storeInst.id,
+          data,
+          formatVersion: storeInst.formatVersion,
+          encoded: useEncoding && storeInst.encodingEnabled(),
+          checksum: this.options.addChecksum ? yield this.calcChecksum(data) : undefined
+        });
+      }
+      return stringified ? JSON.stringify(serData) : serData;
     });
   }
   /**
@@ -706,7 +771,9 @@ var DataStoreSerializer = class {
    */
   deserialize(serializedData) {
     return __async(this, null, function* () {
-      const deserStores = JSON.parse(serializedData);
+      const deserStores = typeof serializedData === "string" ? JSON.parse(serializedData) : serializedData;
+      if (!Array.isArray(deserStores) || !deserStores.every(_DataStoreSerializer.isSerializedDataStore))
+        throw new TypeError("Invalid serialized data format! Expected an array of SerializedDataStore objects.");
       for (const storeData of deserStores) {
         const storeInst = this.stores.find((s) => s.id === storeData.id);
         if (!storeInst)
@@ -714,7 +781,7 @@ var DataStoreSerializer = class {
         if (this.options.ensureIntegrity && typeof storeData.checksum === "string") {
           const checksum = yield this.calcChecksum(storeData.data);
           if (checksum !== storeData.checksum)
-            throw new Error(`Checksum mismatch for DataStore with ID "${storeData.id}"!
+            throw new ChecksumMismatchError(`Checksum mismatch for DataStore with ID "${storeData.id}"!
 Expected: ${storeData.checksum}
 Has: ${checksum}`);
         }
@@ -758,6 +825,10 @@ Has: ${checksum}`);
       return Promise.allSettled(this.stores.map((store) => store.deleteData()));
     });
   }
+  /** Checks if a given value is a SerializedDataStore object */
+  static isSerializedDataStore(obj) {
+    return typeof obj === "object" && obj !== null && "id" in obj && "data" in obj && "formatVersion" in obj && "encoded" in obj;
+  }
 };
 var NanoEmitter = class {
   constructor(options = {}) {
@@ -897,7 +968,7 @@ var Debouncer = class extends NanoEmitter {
         }, this.timeout);
         break;
       default:
-        throw new Error(`Invalid debouncer type: ${this.type}`);
+        throw new TypeError(`Invalid debouncer type: ${this.type}`);
     }
   }
 };
@@ -1401,8 +1472,6 @@ function getListLength(obj, zeroOnInvalid = true) {
 }
 
 // lib/SelectorObserver.ts
-var domLoaded = false;
-document.addEventListener("DOMContentLoaded", () => domLoaded = true);
 var SelectorObserver = class {
   constructor(baseElement, options = {}) {
     __publicField(this, "enabled", false);
@@ -1443,7 +1512,7 @@ var SelectorObserver = class {
   }
   /** Call to check all selectors in the {@linkcode listenerMap} using {@linkcode checkSelector()} */
   checkAllSelectors() {
-    if (!this.enabled || !domLoaded)
+    if (!this.enabled || !isDomLoaded())
       return;
     for (const [selector, listeners] of this.listenerMap.entries())
       this.checkSelector(selector, listeners);
@@ -1587,9 +1656,9 @@ function translate(language, key, ...trArgs) {
   if (typeof language !== "string" || language.length === 0 || typeof trObj !== "object" || trObj === null)
     return fallbackLang ? translate(fallbackLang, key, ...trArgs) : key;
   const transformTrVal = (trKey, trValue) => {
-    const tfs = valTransforms.filter(({ regex }) => new RegExp(regex).test(trValue));
+    const tfs = valTransforms.filter(({ regex }) => new RegExp(regex).test(String(trValue)));
     if (tfs.length === 0)
-      return trValue;
+      return String(trValue);
     let retStr = String(trValue);
     for (const tf of tfs) {
       const re = new RegExp(tf.regex);
@@ -1738,4 +1807,4 @@ var tr = {
   }
 };
 
-export { DataStore, DataStoreSerializer, Debouncer, Dialog, NanoEmitter, SelectorObserver, addGlobalStyle, addParent, autoPlural, clamp, compress, computeHash, consumeGen, consumeStringGen, currentDialogId, darkenColor, debounce, decompress, defaultDialogCss, defaultStrings, digitCount, fetchAdvanced, getListLength, getSiblingsFrame, getUnsafeWindow, hexToRgb, insertValues, interceptEvent, interceptWindowEvent, isScrollable, lightenColor, mapRange, observeElementProp, openDialogs, openInNewTab, pauseFor, preloadImages, randRange, randomId, randomItem, randomItemIndex, randomizeArray, rgbToHex, setInnerHtmlUnsafe, takeRandomItem, tr };
+export { ChecksumMismatchError, DataStore, DataStoreSerializer, Debouncer, Dialog, MigrationError, NanoEmitter, PlatformError, SelectorObserver, UUError, addGlobalStyle, addParent, autoPlural, bitSetHas, clamp, compress, computeHash, consumeGen, consumeStringGen, currentDialogId, darkenColor, debounce, decompress, defaultDialogCss, defaultStrings, digitCount, fetchAdvanced, getListLength, getSiblingsFrame, getUnsafeWindow, hexToRgb, insertValues, interceptEvent, interceptWindowEvent, isDomLoaded, isScrollable, lightenColor, mapRange, observeElementProp, onDomLoad, openDialogs, openInNewTab, pauseFor, preloadImages, probeElementStyle, randRange, randomId, randomItem, randomItemIndex, randomizeArray, rgbToHex, roundFixed, setInnerHtmlUnsafe, takeRandomItem, tr };

package/dist/lib/DataStoreSerializer.d.ts

@@ -2,7 +2,7 @@
  * @module lib/DataStoreSerializer  
  * This module contains the DataStoreSerializer class, which allows you to import and export serialized DataStore data - [see the documentation for more info](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#datastoreserializer)  
  */
-import { type DataStore } from "./index.js";
+import type { DataStore } from "./DataStore.js";
 export type DataStoreSerializerOptions = {
     /** Whether to add a checksum to the exported data */
     addChecksum?: boolean;
@@ -43,15 +43,23 @@ export declare class DataStoreSerializer {
     constructor(stores: DataStore[], options?: DataStoreSerializerOptions);
     /** Calculates the checksum of a string */
     protected calcChecksum(input: string): Promise<string>;
-    /** Serializes a DataStore instance */
-    protected serializeStore(storeInst: DataStore): Promise<SerializedDataStore>;
-    /** Serializes the data stores into a string */
-    serialize(): Promise<string>;
+    /**
+     * Serializes the data stores into a string.  
+     * @param useEncoding Whether to encode the data using each DataStore's `encodeData()` method  
+     * @param stringified Whether to return the result as a string or as an array of `SerializedDataStore` objects  
+     */
+    serialize(useEncoding: boolean, stringified: true): Promise<string>;
+    /**
+     * Serializes the data stores into a string.  
+     * @param useEncoding Whether to encode the data using each DataStore's `encodeData()` method  
+     * @param stringified Whether to return the result as a string or as an array of `SerializedDataStore` objects  
+     */
+    serialize(useEncoding: boolean, stringified: false): Promise<SerializedDataStore[]>;
     /**
      * Deserializes the data exported via {@linkcode serialize()} and imports it into the DataStore instances.  
      * Also triggers the migration process if the data format has changed.  
      */
-    deserialize(serializedData: string): Promise<void>;
+    deserialize(serializedData: string | SerializedDataStore[]): Promise<void>;
     /**
      * Loads the persistent data of the DataStore instances into the in-memory cache.  
      * Also triggers the migration process if the data format has changed.  
@@ -65,4 +73,6 @@ export declare class DataStoreSerializer {
      * Leaves the in-memory data untouched.  
      */
     deleteStoresData(): Promise<PromiseSettledResult<void>[]>;
+    /** Checks if a given value is a SerializedDataStore object */
+    static isSerializedDataStore(obj: unknown): obj is SerializedDataStore;
 }

package/dist/lib/dom.d.ts

@@ -76,3 +76,22 @@ export declare function getSiblingsFrame<TSibling extends Element = HTMLElement>
  * - ⚠️ This function does not perform any sanitization and should thus be used with utmost caution, as it can easily lead to XSS vulnerabilities!  
  */
 export declare function setInnerHtmlUnsafe<TElement extends Element = HTMLElement>(element: TElement, html: string): TElement;
+/**
+ * Creates an invisible temporary element to probe its rendered style.  
+ * Has to be run after the `DOMContentLoaded` event has fired on the document object.  
+ * @param probeStyle Function to probe the element's style. First argument is the element's style object from [`window.getComputedStyle()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/getComputedStyle), second argument is the element itself  
+ * @param element The element to probe, or a function that creates and returns the element - should not be added to the DOM prior to calling this function! - all probe elements will have the class `_uu_probe_element` added to them  
+ * @param hideOffscreen Whether to hide the element offscreen, enabled by default - disable if you want to probe the position style properties of the element  
+ * @param parentElement The parent element to append the probe element to, defaults to `document.body`  
+ * @returns The value returned by the `probeElement` function  
+ */
+export declare function probeElementStyle<TValue, TElem extends HTMLElement = HTMLSpanElement>(probeStyle: (style: CSSStyleDeclaration, element: TElem) => TValue, element?: TElem | (() => TElem), hideOffscreen?: boolean, parentElement?: HTMLElement): TValue;
+/** Returns whether or not the DOM has finished loading */
+export declare function isDomLoaded(): boolean;
+/**
+ * Executes a callback and/or resolves the returned Promise when the DOM has finished loading.  
+ * Immediately executes/resolves if the DOM is already loaded.  
+ * @param cb Callback to execute when the DOM has finished loading  
+ * @returns Returns a Promise that resolves when the DOM has finished loading  
+ */
+export declare function onDomLoad(cb?: () => void): Promise<void>;

package/dist/lib/errors.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @module lib/errors  
+ * Contains custom error classes  
+ */
+/** Base class for all UserUtils errors - adds a `date` prop set to the error throw time */
+export declare class UUError extends Error {
+    readonly date: Date;
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Error while validating checksum */
+export declare class ChecksumMismatchError extends UUError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Error while migrating data */
+export declare class MigrationError extends UUError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Error due to the platform, like using a feature that's not supported by the browser */
+export declare class PlatformError extends UUError {
+    constructor(message: string, options?: ErrorOptions);
+}

package/dist/lib/index.d.ts

@@ -10,6 +10,7 @@ export * from "./DataStoreSerializer.js";
 export * from "./Debouncer.js";
 export * from "./Dialog.js";
 export * from "./dom.js";
+export * from "./errors.js";
 export * from "./math.js";
 export * from "./misc.js";
 export * from "./NanoEmitter.js";

package/dist/lib/math.d.ts

@@ -27,5 +27,55 @@ 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;
+/**
+ * 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.  
+ * @param num The number to count the digits of  
+ * @param withDecimals Whether to count the decimal places as well (defaults to true)  
+ * @example ```ts  
+ * digitCount();         // NaN  
+ * digitCount(0);        // 1  
+ * digitCount(123);      // 3  
+ * digitCount(123.456);  // 6  
+ * digitCount(Infinity); // Infinity  
+ * ```  
+ */
+export declare function digitCount(num: number | Stringifiable, withDecimals?: boolean): number;
+/**
+ * Rounds {@linkcode num} to a fixed amount of decimal places, specified by {@linkcode fractionDigits} (supports negative values to round to the nearest power of 10).  
+ * @example ```ts  
+ * roundFixed(234.567, -2); // 200  
+ * roundFixed(234.567, -1); // 230  
+ * roundFixed(234.567, 0);  // 235  
+ * roundFixed(234.567, 1);  // 234.6  
+ * roundFixed(234.567, 2);  // 234.57  
+ * roundFixed(234.567, 3);  // 234.567  
+ * ```  
+ */
+export declare function roundFixed(num: number, fractionDigits: number): number;
+/**
+ * Checks if the {@linkcode bitSet} has the {@linkcode checkVal} set  
+ * @example ```ts  
+ * // the two vertically adjacent bits are tested for:  
+ * bitSetHas(  
+ *   0b1110,  
+ *   0b0010,  
+ * ); // true  
+ *  
+ * bitSetHas(  
+ *   0b1110,  
+ *   0b0001,  
+ * ); // false  
+ *  
+ * // with TS enums (or JS maps):  
+ * enum MyEnum {  
+ *   A = 1, B = 2, C = 4,  
+ *   D = 8, E = 16, F = 32,  
+ * }  
+ *  
+ * const myBitSet = MyEnum.A | MyEnum.B;  
+ * bitSetHas(myBitSet, MyEnum.B); // true  
+ * bitSetHas(myBitSet, MyEnum.F); // false  
+ * ```  
+ */
+export declare function bitSetHas<TType extends number | bigint>(bitSet: TType, checkVal: TType): boolean;

package/dist/lib/translation.d.ts

@@ -120,35 +120,42 @@ declare function getFallbackLanguage(): string | undefined;
  * After all %n-formatted values have been injected, the transform functions will be called sequentially in the order they were added.  
  * @example  
  * ```ts  
- * tr.addTranslations("en", {  
- *    "greeting": {  
- *      "with_username": "Hello, ${USERNAME}",  
- *      "headline_html": "Hello, ${USERNAME}<br><c=red>You have ${UNREAD_NOTIFS} unread notifications.</c>"  
+ * import { tr, type TrKeys } from "@sv443-network/userutils";  
+ *  
+ * const transEn = {  
+ *    "headline": {  
+ *      "basic": "Hello, ${USERNAME}",  
+ *      "html": "Hello, ${USERNAME}<br><c=red>You have ${UNREAD_NOTIFS} unread notifications.</c>"  
  *    }  
- * });  
+ * } as const;  
+ *  
+ * tr.addTranslations("en", transEn);  
  *  
- * // replace ${PATTERN}  
- * tr.addTransform(/<\$([A-Z_]+)>/g, ({ matches }) => {  
+ * // replace ${PATTERN} with predefined values  
+ * tr.addTransform(/\$\{([A-Z_]+)\}/g, ({ matches }) => {  
  *   switch(matches?.[1]) {  
- *     default: return "<UNKNOWN_PATTERN>";  
- *     // these would be grabbed from elsewhere in the application:  
- *     case "USERNAME": return "JohnDoe45";  
- *     case "UNREAD_NOTIFS": return 5;  
+ *     default:  
+ *       return `[UNKNOWN: ${matches?.[1]}]`;  
+ *     // these would be grabbed from elsewhere in the application, like a DataStore, global state or variable:  
+ *     case "USERNAME":  
+ *       return "JohnDoe45";  
+ *     case "UNREAD_NOTIFS":  
+ *       return 5;  
  *   }  
  * });  
  *  
- * // replace <c=red>...</c> with <span class="color red">...</span>  
+ * // replace <c=red>...</c> with <span style="color: red;">...</span>  
  * tr.addTransform(/<c=([a-z]+)>(.*?)<\/c>/g, ({ matches }) => {  
  *   const color = matches?.[1];  
  *   const content = matches?.[2];  
  *  
- *   return "<span class=\"color " + color + "\">" + content + "</span>";  
+ *   return `<span style="color: ${color};">${content}</span>`;  
  * });  
  *  
- * tr.setLanguage("en");  
+ * const t = tr.use<TrKeys<typeof transEn>>("en");  
  *  
- * tr("greeting.with_username"); // "Hello, JohnDoe45"  
- * tr("greeting.headline"); // "<b>Hello, JohnDoe45</b>\nYou have 5 unread notifications."  
+ * t("headline.basic"); // "Hello, JohnDoe45"  
+ * t("headline.html");  // "Hello, JohnDoe45<br><span style="color: red;">You have 5 unread notifications.</span>"  
  * ```  
  * @param args A tuple containing the regular expression to match and the transform function to call if the pattern is found in a translation string  
  */

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@sv443-network/userutils",
   "libName": "UserUtils",
-  "version": "9.1.0",
-  "description": "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 much more",
+  "version": "9.2.0",
+  "description": "General purpose DOM/GreaseMonkey library that allows you to register listeners for when CSS selectors exist, intercept events, create persistent & synchronous data stores, modify the DOM more easily and much more",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "types": "dist/lib/index.d.ts",