@sv443-network/userutils 9.2.1 → 9.4.0

package/dist/index.global.js

@@ -8,7 +8,7 @@
 // ==UserLibrary==
 // @name         UserUtils
 // @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.1
+// @version      9.4.0
 // @license      MIT
 // @copyright    Sv443 (https://github.com/Sv443)
 
@@ -21,6 +21,8 @@
 
 var UserUtils = (function (exports) {
   var __defProp = Object.defineProperty;
+  var __defProps = Object.defineProperties;
+  var __getOwnPropDescs = Object.getOwnPropertyDescriptors;
   var __getOwnPropSymbols = Object.getOwnPropertySymbols;
   var __hasOwnProp = Object.prototype.hasOwnProperty;
   var __propIsEnum = Object.prototype.propertyIsEnumerable;
@@ -36,6 +38,7 @@ var UserUtils = (function (exports) {
       }
     return a;
   };
+  var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
   var __objRest = (source, exclude) => {
     var target = {};
     for (var prop in source)
@@ -268,16 +271,16 @@ var UserUtils = (function (exports) {
   function preloadImages(srcUrls, rejects = false) {
     const promises = srcUrls.map((src) => new Promise((res, rej) => {
       const image = new Image();
-      image.src = src;
       image.addEventListener("load", () => res(image));
       image.addEventListener("error", (evt) => rejects && rej(evt));
+      image.src = src;
     }));
     return Promise.allSettled(promises);
   }
   function openInNewTab(href, background, additionalProps) {
-    var _a;
     try {
-      (_a = GM.openInTab) == null ? void 0 : _a.call(GM, href, background);
+      if (typeof window.GM === "object")
+        GM.openInTab(href, background);
     } catch (e) {
       const openElem = document.createElement("a");
       Object.assign(openElem, __spreadValues({
@@ -294,12 +297,17 @@ var UserUtils = (function (exports) {
       });
       document.body.appendChild(openElem);
       openElem.click();
-      setTimeout(openElem.remove, 0);
+      setTimeout(() => {
+        try {
+          openElem.remove();
+        } catch (e2) {
+        }
+      }, 0);
     }
   }
   function interceptEvent(eventObject, eventName, predicate = () => true) {
     var _a;
-    if (((_a = GM == null ? undefined : GM.info) == null ? undefined : _a.scriptHandler) && GM.info.scriptHandler === "FireMonkey" && (eventObject === window || eventObject === getUnsafeWindow()))
+    if (typeof window.GM === "object" && ((_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))
@@ -459,6 +467,8 @@ var UserUtils = (function (exports) {
     });
   }
   function randomId(length = 16, radix = 16, enhancedEntropy = false, randomCase = true) {
+    if (length < 1)
+      throw new RangeError("The length argument must be at least 1");
     if (radix < 2 || radix > 36)
       throw new RangeError("The radix argument must be between 2 and 36");
     let arr = [];
@@ -765,14 +775,15 @@ var UserUtils = (function (exports) {
       });
     }
     /**
-     * Serializes the data stores into a string.  
+     * Serializes only a subset of the data stores into a string.  
+     * @param stores An array of store IDs or functions that take a store ID and return a boolean
      * @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) {
+    serializePartial(stores, useEncoding = true, stringified = true) {
       return __async(this, null, function* () {
         const serData = [];
-        for (const storeInst of this.stores) {
+        for (const storeInst of this.stores.filter((s) => typeof stores === "function" ? stores(s.id) : stores.includes(s.id))) {
           const data = useEncoding && storeInst.encodingEnabled() ? yield storeInst.encodeData(JSON.stringify(storeInst.getData())) : JSON.stringify(storeInst.getData());
           serData.push({
             id: storeInst.id,
@@ -786,15 +797,25 @@ var UserUtils = (function (exports) {
       });
     }
     /**
-     * Deserializes the data exported via {@linkcode serialize()} and imports it into the DataStore instances.  
+     * 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* () {
+        return this.serializePartial(this.stores.map((s) => s.id), useEncoding, stringified);
+      });
+    }
+    /**
+     * Deserializes the data exported via {@linkcode serialize()} and imports only a subset into the DataStore instances.  
      * Also triggers the migration process if the data format has changed.
      */
-    deserialize(serializedData) {
+    deserializePartial(stores, data) {
       return __async(this, null, function* () {
-        const deserStores = typeof serializedData === "string" ? JSON.parse(serializedData) : serializedData;
-        if (!Array.isArray(deserStores) || !deserStores.every(_DataStoreSerializer.isSerializedDataStore))
+        const deserStores = typeof data === "string" ? JSON.parse(data) : data;
+        if (!Array.isArray(deserStores) || !deserStores.every(_DataStoreSerializer.isSerializedDataStoreObj))
           throw new TypeError("Invalid serialized data format! Expected an array of SerializedDataStore objects.");
-        for (const storeData of deserStores) {
+        for (const storeData of deserStores.filter((s) => typeof stores === "function" ? stores(s.id) : stores.includes(s.id))) {
           const storeInst = this.stores.find((s) => s.id === storeData.id);
           if (!storeInst)
             throw new Error(`DataStore instance with ID "${storeData.id}" not found! Make sure to provide it in the DataStoreSerializer constructor.`);
@@ -813,42 +834,68 @@ Has: ${checksum}`);
         }
       });
     }
+    /**
+     * Deserializes the data exported via {@linkcode serialize()} and imports the data into all matching DataStore instances.  
+     * Also triggers the migration process if the data format has changed.
+     */
+    deserialize(data) {
+      return __async(this, null, function* () {
+        return this.deserializePartial(this.stores.map((s) => s.id), data);
+      });
+    }
     /**
      * Loads the persistent data of the DataStore instances into the in-memory cache.  
      * Also triggers the migration process if the data format has changed.
+     * @param stores An array of store IDs or a function that takes the store IDs and returns a boolean - if omitted, all stores will be loaded
      * @returns Returns a PromiseSettledResult array with the results of each DataStore instance in the format `{ id: string, data: object }`
      */
-    loadStoresData() {
+    loadStoresData(stores) {
       return __async(this, null, function* () {
-        return Promise.allSettled(this.stores.map(
-          (store) => __async(this, null, function* () {
+        return Promise.allSettled(
+          this.getStoresFiltered(stores).map((store) => __async(this, null, function* () {
             return {
               id: store.id,
               data: yield store.loadData()
             };
-          })
-        ));
+          }))
+        );
       });
     }
-    /** Resets the persistent data of the DataStore instances to their default values. */
-    resetStoresData() {
+    /**
+     * Resets the persistent and in-memory data of the DataStore instances to their default values.
+     * @param stores An array of store IDs or a function that takes the store IDs and returns a boolean - if omitted, all stores will be affected
+     */
+    resetStoresData(stores) {
       return __async(this, null, function* () {
-        return Promise.allSettled(this.stores.map((store) => store.saveDefaultData()));
+        return Promise.allSettled(
+          this.getStoresFiltered(stores).map((store) => store.saveDefaultData())
+        );
       });
     }
     /**
      * Deletes the persistent data of the DataStore instances.  
-     * Leaves the in-memory data untouched.
+     * Leaves the in-memory data untouched.  
+     * @param stores An array of store IDs or a function that takes the store IDs and returns a boolean - if omitted, all stores will be affected
      */
-    deleteStoresData() {
+    deleteStoresData(stores) {
       return __async(this, null, function* () {
-        return Promise.allSettled(this.stores.map((store) => store.deleteData()));
+        return Promise.allSettled(
+          this.getStoresFiltered(stores).map((store) => store.deleteData())
+        );
       });
     }
+    /** Checks if a given value is an array of SerializedDataStore objects */
+    static isSerializedDataStoreObjArray(obj) {
+      return Array.isArray(obj) && obj.every((o) => typeof o === "object" && o !== null && "id" in o && "data" in o && "formatVersion" in o && "encoded" in o);
+    }
     /** Checks if a given value is a SerializedDataStore object */
-    static isSerializedDataStore(obj) {
+    static isSerializedDataStoreObj(obj) {
       return typeof obj === "object" && obj !== null && "id" in obj && "data" in obj && "formatVersion" in obj && "encoded" in obj;
     }
+    /** Returns the DataStore instances whose IDs match the provided array or function */
+    getStoresFiltered(stores) {
+      return this.stores.filter((s) => typeof stores === "undefined" ? true : Array.isArray(stores) ? stores.includes(s.id) : stores(s.id));
+    }
   };
 
   // node_modules/.pnpm/nanoevents@9.1.0/node_modules/nanoevents/index.js
@@ -871,6 +918,7 @@ Has: ${checksum}`);
 
   // lib/NanoEmitter.ts
   var NanoEmitter = class {
+    /** Creates a new instance of NanoEmitter - a lightweight event emitter with helper methods and a strongly typed event map */
     constructor(options = {}) {
       __publicField(this, "events", createNanoEvents());
       __publicField(this, "eventUnsubscribes", []);
@@ -879,7 +927,27 @@ Has: ${checksum}`);
         publicEmit: false
       }, options);
     }
-    /** Subscribes to an event - returns a function that unsubscribes the event listener */
+    /**
+     * Subscribes to an event and calls the callback when it's emitted.  
+     * @param event The event to subscribe to. Use `as "_"` in case your event names aren't thoroughly typed (like when using a template literal, e.g. \`event-${val}\` as "_")
+     * @returns Returns a function that can be called to unsubscribe the event listener
+     * @example ```ts
+     * const emitter = new NanoEmitter<{
+     *   foo: (bar: string) => void;
+     * }>({
+     *   publicEmit: true,
+     * });
+     * 
+     * let i = 0;
+     * const unsub = emitter.on("foo", (bar) => {
+     *   // unsubscribe after 10 events:
+     *   if(++i === 10) unsub();
+     *   console.log(bar);
+     * });
+     * 
+     * emitter.emit("foo", "bar");
+     * ```
+     */
     on(event, cb) {
       let unsub;
       const unsubProxy = () => {
@@ -892,19 +960,43 @@ Has: ${checksum}`);
       this.eventUnsubscribes.push(unsub);
       return unsubProxy;
     }
-    /** Subscribes to an event and calls the callback or resolves the Promise only once */
+    /**
+     * Subscribes to an event and calls the callback or resolves the Promise only once when it's emitted.  
+     * @param event The event to subscribe to. Use `as "_"` in case your event names aren't thoroughly typed (like when using a template literal, e.g. \`event-${val}\` as "_")
+     * @param cb The callback to call when the event is emitted - if provided or not, the returned Promise will resolve with the event arguments
+     * @returns Returns a Promise that resolves with the event arguments when the event is emitted
+     * @example ```ts
+     * const emitter = new NanoEmitter<{
+     *   foo: (bar: string) => void;
+     * }>();
+     * 
+     * // Promise syntax:
+     * const [bar] = await emitter.once("foo");
+     * console.log(bar);
+     * 
+     * // Callback syntax:
+     * emitter.once("foo", (bar) => console.log(bar));
+     * ```
+     */
     once(event, cb) {
       return new Promise((resolve) => {
         let unsub;
         const onceProxy = (...args) => {
-          unsub();
           cb == null ? undefined : cb(...args);
+          unsub == null ? undefined : unsub();
           resolve(args);
         };
-        unsub = this.on(event, onceProxy);
+        unsub = this.events.on(event, onceProxy);
+        this.eventUnsubscribes.push(unsub);
       });
     }
-    /** Emits an event on this instance - Needs `publicEmit` to be set to true in the constructor! */
+    /**
+     * Emits an event on this instance.  
+     * ⚠️ Needs `publicEmit` to be set to true in the NanoEmitter constructor or super() call!
+     * @param event The event to emit
+     * @param args The arguments to pass to the event listeners
+     * @returns Returns true if `publicEmit` is true and the event was emitted successfully
+     */
     emit(event, ...args) {
       if (this.emitterOptions.publicEmit) {
         this.events.emit(event, ...args);
@@ -912,7 +1004,7 @@ Has: ${checksum}`);
       }
       return false;
     }
-    /** Unsubscribes all event listeners */
+    /** Unsubscribes all event listeners from this instance */
     unsubscribeAll() {
       for (const unsub of this.eventUnsubscribes)
         unsub();
@@ -952,6 +1044,10 @@ Has: ${checksum}`);
     removeAllListeners() {
       this.listeners = [];
     }
+    /** Returns all registered listeners */
+    getListeners() {
+      return this.listeners;
+    }
     //#region timeout
     /** Sets the timeout for the debouncer */
     setTimeout(timeout) {
@@ -980,7 +1076,7 @@ Has: ${checksum}`);
       const cl = (...a) => {
         this.queuedCall = undefined;
         this.emit("call", ...a);
-        this.listeners.forEach((l) => l.apply(this, a));
+        this.listeners.forEach((l) => l.call(this, ...a));
       };
       const setRepeatTimeout = () => {
         this.activeTimeout = setTimeout(() => {
@@ -1454,8 +1550,6 @@ Has: ${checksum}`);
         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) {
@@ -1510,6 +1604,115 @@ Has: ${checksum}`);
   function getListLength(obj, zeroOnInvalid = true) {
     return "length" in obj ? obj.length : "size" in obj ? obj.size : "count" in obj ? obj.count : zeroOnInvalid ? 0 : NaN;
   }
+  function purifyObj(obj) {
+    return Object.assign(/* @__PURE__ */ Object.create(null), obj);
+  }
+
+  // lib/Mixins.ts
+  var Mixins = class {
+    /**
+     * Creates a new Mixins instance.
+     * @param config Configuration object to customize the behavior.
+     */
+    constructor(config = {}) {
+      /** List of all registered mixins */
+      __publicField(this, "mixins", []);
+      /** Default configuration object for mixins */
+      __publicField(this, "defaultMixinCfg");
+      /** Whether the priorities should auto-increment if not specified */
+      __publicField(this, "autoIncPrioEnabled");
+      /** The current auto-increment priority counter */
+      __publicField(this, "autoIncPrioCounter", /* @__PURE__ */ new Map());
+      var _a, _b, _c;
+      this.defaultMixinCfg = purifyObj({
+        priority: (_a = config.defaultPriority) != null ? _a : 0,
+        stopPropagation: (_b = config.defaultStopPropagation) != null ? _b : false,
+        signal: config.defaultSignal
+      });
+      this.autoIncPrioEnabled = (_c = config.autoIncrementPriority) != null ? _c : false;
+    }
+    //#region public
+    /**
+     * Adds a mixin function to the given {@linkcode mixinKey}.  
+     * If no priority is specified, it will be calculated via the protected method {@linkcode calcPriority()} based on the constructor configuration, or fall back to the default priority.
+     * @param mixinKey The key to identify the mixin function.
+     * @param mixinFn The function to be called to apply the mixin. The first argument is the input value, the second argument is the context object (if any).
+     * @param config Configuration object to customize the mixin behavior, or just the priority if a number is passed.
+     * @returns Returns a cleanup function, to be called when this mixin is no longer needed.
+     */
+    add(mixinKey, mixinFn, config = purifyObj({})) {
+      const calcPrio = typeof config === "number" ? config : this.calcPriority(mixinKey, config);
+      const mixin = purifyObj(__spreadValues(__spreadValues(__spreadProps(__spreadValues({}, this.defaultMixinCfg), {
+        key: mixinKey,
+        fn: mixinFn
+      }), typeof config === "object" ? config : {}), typeof calcPrio === "number" && !isNaN(calcPrio) ? { priority: calcPrio } : {}));
+      this.mixins.push(mixin);
+      const rem = () => {
+        this.mixins = this.mixins.filter((m) => m !== mixin);
+      };
+      if (mixin.signal)
+        mixin.signal.addEventListener("abort", rem, { once: true });
+      return rem;
+    }
+    /** Returns a list of all added mixins with their keys and configuration objects, but not their functions */
+    list() {
+      return this.mixins.map((_a) => {
+        var _b = _a, rest = __objRest(_b, ["fn"]);
+        return rest;
+      });
+    }
+    /**
+     * Applies all mixins with the given key to the input value, respecting the priority and stopPropagation settings.  
+     * If additional context is set in the MixinMap, it will need to be passed as the third argument.  
+     * @returns The modified value after all mixins have been applied.
+     */
+    resolve(mixinKey, inputValue, ...inputCtx) {
+      const mixins = this.mixins.filter((m) => m.key === mixinKey);
+      const sortedMixins = [...mixins].sort((a, b) => b.priority - a.priority);
+      let result = inputValue;
+      for (let i = 0; i < sortedMixins.length; i++) {
+        const mixin = sortedMixins[i];
+        result = mixin.fn(result, ...inputCtx);
+        if (result instanceof Promise) {
+          return (() => __async(this, null, function* () {
+            result = yield result;
+            if (mixin.stopPropagation)
+              return result;
+            for (let j = i + 1; j < sortedMixins.length; j++) {
+              const mixin2 = sortedMixins[j];
+              result = yield mixin2.fn(result, ...inputCtx);
+              if (mixin2.stopPropagation)
+                break;
+            }
+            return result;
+          }))();
+        } else if (mixin.stopPropagation)
+          break;
+      }
+      return result;
+    }
+    //#region protected
+    /** Calculates the priority for a mixin based on the given configuration and the current auto-increment state of the instance */
+    calcPriority(mixinKey, config) {
+      var _a;
+      if (config.priority !== undefined)
+        return undefined;
+      if (!this.autoIncPrioEnabled)
+        return (_a = config.priority) != null ? _a : this.defaultMixinCfg.priority;
+      if (!this.autoIncPrioCounter.has(mixinKey))
+        this.autoIncPrioCounter.set(mixinKey, this.defaultMixinCfg.priority);
+      let prio = this.autoIncPrioCounter.get(mixinKey);
+      while (this.mixins.some((m) => m.key === mixinKey && m.priority === prio))
+        prio++;
+      this.autoIncPrioCounter.set(mixinKey, prio + 1);
+      return prio;
+    }
+    /** Removes all mixins with the given key */
+    removeAll(mixinKey) {
+      this.mixins.filter((m) => m.key === mixinKey);
+      this.mixins = this.mixins.filter((m) => m.key !== mixinKey);
+    }
+  };
 
   // lib/SelectorObserver.ts
   var SelectorObserver = class {
@@ -1768,15 +1971,15 @@ Has: ${checksum}`);
     return fallbackLang;
   }
   function addTransform(transform) {
-    const [pattern, fn] = transform;
+    const [regex, fn] = transform;
     valTransforms.push({
       fn,
-      regex: typeof pattern === "string" ? new RegExp(pattern, "gm") : pattern
+      regex
     });
   }
   function deleteTransform(patternOrFn) {
     const idx = valTransforms.findIndex(
-      (t) => typeof patternOrFn === "function" ? t.fn === patternOrFn : typeof patternOrFn === "string" ? t.regex.source === patternOrFn : t.regex === patternOrFn
+      (t) => typeof patternOrFn === "function" ? t.fn === patternOrFn : t.regex === patternOrFn
     );
     if (idx !== -1) {
       valTransforms.splice(idx, 1);
@@ -1853,6 +2056,7 @@ Has: ${checksum}`);
   exports.Debouncer = Debouncer;
   exports.Dialog = Dialog;
   exports.MigrationError = MigrationError;
+  exports.Mixins = Mixins;
   exports.NanoEmitter = NanoEmitter;
   exports.PlatformError = PlatformError;
   exports.SelectorObserver = SelectorObserver;
@@ -1891,6 +2095,7 @@ Has: ${checksum}`);
   exports.pauseFor = pauseFor;
   exports.preloadImages = preloadImages;
   exports.probeElementStyle = probeElementStyle;
+  exports.purifyObj = purifyObj;
   exports.randRange = randRange;
   exports.randomId = randomId;
   exports.randomItem = randomItem;