@sv443-network/userutils 9.0.4 → 9.2.0

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}`);
     }
   }
 };
@@ -1329,10 +1400,23 @@ var Dialog = class _Dialog extends NanoEmitter {
 };
 
 // lib/misc.ts
-function autoPlural(word, num) {
-  if (Array.isArray(num) || num instanceof NodeList)
-    num = num.length;
-  return `${word}${num === 1 ? "" : "s"}`;
+function autoPlural(term, num, pluralType = "auto") {
+  let n = num;
+  if (typeof n !== "number")
+    n = getListLength(n, false);
+  if (!["-s", "-ies"].includes(pluralType))
+    pluralType = "auto";
+  if (isNaN(n))
+    n = 2;
+  const pType = pluralType === "auto" ? String(term).endsWith("y") ? "-ies" : "-s" : pluralType;
+  switch (pType) {
+    case "-s":
+      return `${term}${n === 1 ? "" : "s"}`;
+    case "-ies":
+      return `${String(term).slice(0, -1)}${n === 1 ? "y" : "ies"}`;
+    default:
+      return String(term);
+  }
 }
 function insertValues(input, ...values) {
   return input.replace(/%\d/gm, (match) => {
@@ -1341,29 +1425,33 @@ function insertValues(input, ...values) {
     return (_b = (_a = values[argIndex]) != null ? _a : match) == null ? undefined : _b.toString();
   });
 }
-function pauseFor(time) {
-  return new Promise((res) => {
-    setTimeout(() => res(), time);
+function pauseFor(time, signal, rejectOnAbort = false) {
+  return new Promise((res, rej) => {
+    const timeout = setTimeout(() => res(), time);
+    signal == null ? undefined : signal.addEventListener("abort", () => {
+      clearTimeout(timeout);
+      rejectOnAbort ? rej(new Error("The pause was aborted")) : res();
+    });
   });
 }
 function fetchAdvanced(_0) {
   return __async(this, arguments, function* (input, options = {}) {
-    var _a;
     const { timeout = 1e4 } = options;
-    const { signal, abort } = new AbortController();
-    (_a = options.signal) == null ? undefined : _a.addEventListener("abort", abort);
-    let signalOpts = {}, id = undefined;
+    const ctl = new AbortController();
+    const _a = options, { signal } = _a, restOpts = __objRest(_a, ["signal"]);
+    signal == null ? undefined : signal.addEventListener("abort", () => ctl.abort());
+    let sigOpts = {}, id = undefined;
     if (timeout >= 0) {
-      id = setTimeout(() => abort(), timeout);
-      signalOpts = { signal };
+      id = setTimeout(() => ctl.abort(), timeout);
+      sigOpts = { signal: ctl.signal };
     }
     try {
-      const res = yield fetch(input, __spreadValues(__spreadValues({}, options), signalOpts));
-      id && clearTimeout(id);
+      const res = yield fetch(input, __spreadValues(__spreadValues({}, restOpts), sigOpts));
+      typeof id !== "undefined" && clearTimeout(id);
       return res;
     } catch (err) {
-      id && clearTimeout(id);
-      throw err;
+      typeof id !== "undefined" && clearTimeout(id);
+      throw new Error("Error while calling fetch", { cause: err });
     }
   });
 }
@@ -1379,10 +1467,11 @@ function consumeStringGen(strGen) {
     );
   });
 }
+function getListLength(obj, zeroOnInvalid = true) {
+  return "length" in obj ? obj.length : "size" in obj ? obj.size : "count" in obj ? obj.count : zeroOnInvalid ? 0 : NaN;
+}
 
 // lib/SelectorObserver.ts
-var domLoaded = false;
-document.addEventListener("DOMContentLoaded", () => domLoaded = true);
 var SelectorObserver = class {
   constructor(baseElement, options = {}) {
     __publicField(this, "enabled", false);
@@ -1423,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);
@@ -1567,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);
@@ -1718,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, 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/misc.d.ts

@@ -2,13 +2,18 @@
  * @module lib/misc  
  * This module contains miscellaneous functions that don't fit in another category - [see the documentation for more info](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#misc)  
  */
-import type { Prettify, Stringifiable } from "./types.js";
+import type { ListWithLength, Prettify, Stringifiable } from "./types.js";
+/** Which plural form to use when auto-pluralizing */
+export type PluralType = "auto" | "-s" | "-ies";
 /**
- * Automatically appends an `s` to the passed {@linkcode word}, if {@linkcode num} is not equal to 1  
- * @param word A word in singular form, to auto-convert to plural  
- * @param num If this is an array or NodeList, the amount of items is used  
+ * Automatically pluralizes the given string by adding an `-s` or `-ies` to the passed {@linkcode term}, if {@linkcode num} is not equal to 1.  
+ * By default, words ending in `-y` will have it replaced with `-ies`, and all other words will simply have `-s` appended.  
+ * {@linkcode pluralType} will default to `auto` if invalid and {@linkcode num} is set to 2 if it resolves to `NaN`.  
+ * @param term The term, written in singular form, to auto-convert to plural form  
+ * @param num A number, or list-like value that has either a `length`, `count` or `size` property, like an array, Map or NodeList - does not support iterables, they need to be converted to an array first  
+ * @param pluralType Which plural form to use when auto-pluralizing. Defaults to `"auto"`, which removes the last char and uses `-ies` for words ending in `y` and simply appends `-s` for all other words  
  */
-export declare function autoPlural(word: Stringifiable, num: number | unknown[] | NodeList): string;
+export declare function autoPlural(term: Stringifiable, num: number | ListWithLength, pluralType?: PluralType): string;
 /**
  * Inserts the passed values into a string at the respective placeholders.  
  * The placeholder format is `%n`, where `n` is the 1-indexed argument number.  
@@ -16,8 +21,12 @@ export declare function autoPlural(word: Stringifiable, num: number | unknown[]
  * @param values The values to insert, in order, starting at `%1`  
  */
 export declare function insertValues(input: string, ...values: Stringifiable[]): string;
-/** Pauses async execution for the specified time in ms */
-export declare function pauseFor(time: number): Promise<void>;
+/**
+ * Pauses async execution for the specified time in ms.  
+ * If an `AbortSignal` is passed, the pause will be aborted when the signal is triggered.  
+ * By default, this will resolve the promise, but you can set {@linkcode rejectOnAbort} to true to reject it instead.  
+ */
+export declare function pauseFor(time: number, signal?: AbortSignal, rejectOnAbort?: boolean): Promise<void>;
 /** Options for the `fetchAdvanced()` function */
 export type FetchAdvancedOpts = Prettify<Partial<{
     /** Timeout in milliseconds after which the fetch call will be canceled with an AbortController signal */
@@ -46,3 +55,9 @@ export type StringGen = ValueGen<Stringifiable>;
  * @template TStrUnion The union of strings that the StringGen should yield - this allows for finer type control compared to {@linkcode consumeGen()}  
  */
 export declare function consumeStringGen<TStrUnion extends string>(strGen: StringGen): Promise<TStrUnion>;
+/**
+ * Returns the length of the given list-like object (anything with a numeric `length`, `size` or `count` property, like an array, Map or NodeList).  
+ * If the object doesn't have any of these properties, it will return 0 by default.  
+ * Set {@linkcode zeroOnInvalid} to false to return NaN instead of 0 if the object doesn't have any of the properties.  
+ */
+export declare function getListLength(obj: ListWithLength, zeroOnInvalid?: boolean): number;

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/dist/lib/types.d.ts

@@ -28,3 +28,11 @@ export type NonEmptyString<TString extends string> = TString extends "" ? never
 export type Prettify<T> = {
     [K in keyof T]: T[K];
 } & {};
+/** Any value that is list-like, i.e. has a numeric length, count or size property */
+export type ListWithLength = {
+    length: number;
+} | {
+    count: number;
+} | {
+    size: number;
+};