@sv443-network/userutils 6.2.0 → 7.0.0

package/dist/index.global.js

@@ -7,8 +7,8 @@
 
 // ==UserLibrary==
 // @name         UserUtils
-// @description  Library with various utilities for userscripts - register listeners for when CSS selectors exist, intercept events, manage persistent user configurations, modify the DOM more easily and more
-// @version      6.2.0
+// @description  Library with various utilities for userscripts - register listeners for when CSS selectors exist, intercept events, create persistent & synchronous data stores, modify the DOM more easily and more
+// @version      7.0.0
 // @license      MIT
 // @copyright    Sv443 (https://github.com/Sv443)
 
@@ -99,14 +99,6 @@ var UserUtils = (function (exports) {
       throw new TypeError(`Parameter "min" can't be bigger than "max"`);
     return Math.floor(Math.random() * (max - min + 1)) + min;
   }
-  function randomId(length = 16, radix = 16) {
-    const arr = new Uint8Array(length);
-    crypto.getRandomValues(arr);
-    return Array.from(
-      arr,
-      (v) => mapRange(v, 0, 255, 0, radix).toString(radix).substring(0, 1)
-    ).join("");
-  }
 
   // lib/array.ts
   function randomItem(array) {
@@ -142,28 +134,32 @@ var UserUtils = (function (exports) {
      * Creates an instance of DataStore to manage a sync & async database that is cached in memory and persistently saved across sessions.  
      * Supports migrating data from older versions to newer ones and populating the cache with default data if no persistent data is found.  
      *   
-     * ⚠️ Requires the directives `@grant GM.getValue` and `@grant GM.setValue`  
+     * ⚠️ Requires the directives `@grant GM.getValue` and `@grant GM.setValue` if the storageMethod is left as the default of `"GM"`  
      * ⚠️ Make sure to call {@linkcode loadData()} at least once after creating an instance, or the returned data will be the same as `options.defaultData`
      * 
-     * @template TData The type of the data that is saved in persistent storage (will be automatically inferred from `options.defaultData`) - this should also be the type of the data format associated with the current `options.formatVersion`
+     * @template TData The type of the data that is saved in persistent storage for the currently set format version (will be automatically inferred from `defaultData` if not provided) - **This has to be a JSON-compatible object!** (no undefined, circular references, etc.)
      * @param options The options for this DataStore instance
-    */
+     */
     constructor(options) {
       __publicField(this, "id");
       __publicField(this, "formatVersion");
       __publicField(this, "defaultData");
-      __publicField(this, "cachedData");
-      __publicField(this, "migrations");
       __publicField(this, "encodeData");
       __publicField(this, "decodeData");
+      __publicField(this, "storageMethod");
+      __publicField(this, "cachedData");
+      __publicField(this, "migrations");
+      var _a;
       this.id = options.id;
       this.formatVersion = options.formatVersion;
       this.defaultData = options.defaultData;
       this.cachedData = options.defaultData;
       this.migrations = options.migrations;
+      this.storageMethod = (_a = options.storageMethod) != null ? _a : "GM";
       this.encodeData = options.encodeData;
       this.decodeData = options.decodeData;
     }
+    //#region public
     /**
      * Loads the data saved in persistent storage into the in-memory cache and also returns it.  
      * Automatically populates persistent storage with default data if it doesn't contain any data yet.  
@@ -172,19 +168,25 @@ var UserUtils = (function (exports) {
     loadData() {
       return __async(this, null, function* () {
         try {
-          const gmData = yield GM.getValue(`_uucfg-${this.id}`, this.defaultData);
-          let gmFmtVer = Number(yield GM.getValue(`_uucfgver-${this.id}`));
+          const gmData = yield this.getValue(`_uucfg-${this.id}`, JSON.stringify(this.defaultData));
+          let gmFmtVer = Number(yield this.getValue(`_uucfgver-${this.id}`, NaN));
           if (typeof gmData !== "string") {
             yield this.saveDefaultData();
             return __spreadValues({}, this.defaultData);
           }
-          const isEncoded = yield GM.getValue(`_uucfgenc-${this.id}`, false);
-          if (isNaN(gmFmtVer))
-            yield GM.setValue(`_uucfgver-${this.id}`, gmFmtVer = this.formatVersion);
+          const isEncoded = Boolean(yield this.getValue(`_uucfgenc-${this.id}`, false));
+          let saveData = false;
+          if (isNaN(gmFmtVer)) {
+            yield this.setValue(`_uucfgver-${this.id}`, gmFmtVer = this.formatVersion);
+            saveData = true;
+          }
           let parsed = yield this.deserializeData(gmData, isEncoded);
           if (gmFmtVer < this.formatVersion && this.migrations)
             parsed = yield this.runMigrations(parsed, gmFmtVer);
-          return __spreadValues({}, this.cachedData = parsed);
+          if (saveData)
+            yield this.setData(parsed);
+          this.cachedData = __spreadValues({}, parsed);
+          return this.cachedData;
         } catch (err) {
           console.warn("Error while parsing JSON data, resetting it to the default value.", err);
           yield this.saveDefaultData();
@@ -195,19 +197,20 @@ var UserUtils = (function (exports) {
     /**
      * Returns a copy of the data from the in-memory cache.  
      * Use {@linkcode loadData()} to get fresh data from persistent storage (usually not necessary since the cache should always exactly reflect persistent storage).
+     * @param deepCopy Whether to return a deep copy of the data (default: `false`) - only necessary if your data object is nested and may have a bigger performance impact if enabled
      */
-    getData() {
-      return this.deepCopy(this.cachedData);
+    getData(deepCopy = false) {
+      return deepCopy ? this.deepCopy(this.cachedData) : __spreadValues({}, this.cachedData);
     }
     /** Saves the data synchronously to the in-memory cache and asynchronously to the persistent storage */
     setData(data) {
       this.cachedData = data;
-      const useEncoding = Boolean(this.encodeData && this.decodeData);
+      const useEncoding = this.encodingEnabled();
       return new Promise((resolve) => __async(this, null, function* () {
         yield Promise.all([
-          GM.setValue(`_uucfg-${this.id}`, yield this.serializeData(data, useEncoding)),
-          GM.setValue(`_uucfgver-${this.id}`, this.formatVersion),
-          GM.setValue(`_uucfgenc-${this.id}`, useEncoding)
+          this.setValue(`_uucfg-${this.id}`, yield this.serializeData(data, useEncoding)),
+          this.setValue(`_uucfgver-${this.id}`, this.formatVersion),
+          this.setValue(`_uucfgenc-${this.id}`, useEncoding)
         ]);
         resolve();
       }));
@@ -216,12 +219,12 @@ var UserUtils = (function (exports) {
     saveDefaultData() {
       return __async(this, null, function* () {
         this.cachedData = this.defaultData;
-        const useEncoding = Boolean(this.encodeData && this.decodeData);
+        const useEncoding = this.encodingEnabled();
         return new Promise((resolve) => __async(this, null, function* () {
           yield Promise.all([
-            GM.setValue(`_uucfg-${this.id}`, yield this.serializeData(this.defaultData, useEncoding)),
-            GM.setValue(`_uucfgver-${this.id}`, this.formatVersion),
-            GM.setValue(`_uucfgenc-${this.id}`, useEncoding)
+            this.setValue(`_uucfg-${this.id}`, yield this.serializeData(this.defaultData, useEncoding)),
+            this.setValue(`_uucfgver-${this.id}`, this.formatVersion),
+            this.setValue(`_uucfgenc-${this.id}`, useEncoding)
           ]);
           resolve();
         }));
@@ -237,14 +240,25 @@ var UserUtils = (function (exports) {
     deleteData() {
       return __async(this, null, function* () {
         yield Promise.all([
-          GM.deleteValue(`_uucfg-${this.id}`),
-          GM.deleteValue(`_uucfgver-${this.id}`),
-          GM.deleteValue(`_uucfgenc-${this.id}`)
+          this.deleteValue(`_uucfg-${this.id}`),
+          this.deleteValue(`_uucfgver-${this.id}`),
+          this.deleteValue(`_uucfgenc-${this.id}`)
         ]);
       });
     }
-    /** Runs all necessary migration functions consecutively - may be overwritten in a subclass */
-    runMigrations(oldData, oldFmtVer) {
+    /** Returns whether encoding and decoding are enabled for this DataStore instance */
+    encodingEnabled() {
+      return Boolean(this.encodeData && this.decodeData);
+    }
+    //#region migrations
+    /**
+     * Runs all necessary migration functions consecutively and saves the result to the in-memory cache and persistent storage and also returns it.  
+     * This method is automatically called by {@linkcode loadData()} if the data format has changed since the last time the data was saved.  
+     * Though calling this method manually is not necessary, it can be useful if you want to run migrations for special occasions like a user importing potentially outdated data that has been previously exported.  
+     *   
+     * If one of the migrations fails, the data will be reset to the default value if `resetOnError` is set to `true` (default). Otherwise, an error will be thrown and no data will be saved.
+     */
+    runMigrations(oldData, oldFmtVer, resetOnError = true) {
       return __async(this, null, function* () {
         if (!this.migrations)
           return oldData;
@@ -259,6 +273,8 @@ var UserUtils = (function (exports) {
               newData = migRes instanceof Promise ? yield migRes : migRes;
               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);
               yield this.saveDefaultData();
               return this.getData();
@@ -266,18 +282,19 @@ var UserUtils = (function (exports) {
           }
         }
         yield Promise.all([
-          GM.setValue(`_uucfg-${this.id}`, yield this.serializeData(newData)),
-          GM.setValue(`_uucfgver-${this.id}`, lastFmtVer),
-          GM.setValue(`_uucfgenc-${this.id}`, Boolean(this.encodeData && this.decodeData))
+          this.setValue(`_uucfg-${this.id}`, yield this.serializeData(newData)),
+          this.setValue(`_uucfgver-${this.id}`, lastFmtVer),
+          this.setValue(`_uucfgenc-${this.id}`, this.encodingEnabled())
         ]);
-        return newData;
+        return this.cachedData = __spreadValues({}, newData);
       });
     }
+    //#region serialization
     /** Serializes the data using the optional this.encodeData() and returns it as a string */
     serializeData(data, useEncoding = true) {
       return __async(this, null, function* () {
         const stringData = JSON.stringify(data);
-        if (!this.encodeData || !this.decodeData || !useEncoding)
+        if (!this.encodingEnabled() || !useEncoding)
           return stringData;
         const encRes = this.encodeData(stringData);
         if (encRes instanceof Promise)
@@ -288,16 +305,131 @@ var UserUtils = (function (exports) {
     /** Deserializes the data using the optional this.decodeData() and returns it as a JSON object */
     deserializeData(data, useEncoding = true) {
       return __async(this, null, function* () {
-        let decRes = this.decodeData && this.encodeData && useEncoding ? this.decodeData(data) : void 0;
+        let decRes = this.encodingEnabled() && useEncoding ? this.decodeData(data) : void 0;
         if (decRes instanceof Promise)
           decRes = yield decRes;
         return JSON.parse(decRes != null ? decRes : data);
       });
     }
-    /** Copies a JSON-compatible object and loses its internal references */
+    //#region misc
+    /** Copies a JSON-compatible object and loses all its internal references in the process */
     deepCopy(obj) {
       return JSON.parse(JSON.stringify(obj));
     }
+    //#region storage
+    /** Gets a value from persistent storage - can be overwritten in a subclass if you want to use something other than GM storage */
+    getValue(name, defaultValue) {
+      return __async(this, null, function* () {
+        var _a, _b;
+        switch (this.storageMethod) {
+          case "localStorage":
+            return (_a = localStorage.getItem(name)) != null ? _a : defaultValue;
+          case "sessionStorage":
+            return (_b = sessionStorage.getItem(name)) != null ? _b : defaultValue;
+          default:
+            return GM.getValue(name, defaultValue);
+        }
+      });
+    }
+    /**
+     * Sets a value in persistent storage - can be overwritten in a subclass if you want to use something other than GM storage.  
+     * The default storage engines will stringify all passed values like numbers or booleans, so be aware of that.
+     */
+    setValue(name, value) {
+      return __async(this, null, function* () {
+        switch (this.storageMethod) {
+          case "localStorage":
+            return localStorage.setItem(name, String(value));
+          case "sessionStorage":
+            return sessionStorage.setItem(name, String(value));
+          default:
+            return GM.setValue(name, String(value));
+        }
+      });
+    }
+    /** Deletes a value from persistent storage - can be overwritten in a subclass if you want to use something other than GM storage */
+    deleteValue(name) {
+      return __async(this, null, function* () {
+        switch (this.storageMethod) {
+          case "localStorage":
+            return localStorage.removeItem(name);
+          case "sessionStorage":
+            return sessionStorage.removeItem(name);
+          default:
+            return GM.deleteValue(name);
+        }
+      });
+    }
+  };
+
+  // lib/DataStoreSerializer.ts
+  var DataStoreSerializer = class {
+    constructor(stores, options = {}) {
+      __publicField(this, "stores");
+      __publicField(this, "options");
+      if (!getUnsafeWindow().crypto || !getUnsafeWindow().crypto.subtle)
+        throw new Error("DataStoreSerializer has to run in a secure context (HTTPS)!");
+      this.stores = stores;
+      this.options = __spreadValues({
+        addChecksum: true,
+        ensureIntegrity: true
+      }, options);
+    }
+    /** Calculates the checksum of a string */
+    calcChecksum(input) {
+      return __async(this, null, function* () {
+        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) : void 0;
+        return {
+          id: storeInst.id,
+          data,
+          formatVersion: storeInst.formatVersion,
+          encoded: storeInst.encodingEnabled(),
+          checksum
+        };
+      });
+    }
+    /** Serializes the data stores into a string */
+    serialize() {
+      return __async(this, null, function* () {
+        const serData = [];
+        for (const store of this.stores)
+          serData.push(yield this.serializeStore(store));
+        return JSON.stringify(serData);
+      });
+    }
+    /**
+     * 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) {
+      return __async(this, null, function* () {
+        const deserStores = JSON.parse(serializedData);
+        for (const storeData of deserStores) {
+          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.`);
+          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}"!
+Expected: ${storeData.checksum}
+Has: ${checksum}`);
+          }
+          const decodedData = storeData.encoded && storeInst.encodingEnabled() ? yield storeInst.decodeData(storeData.data) : storeData.data;
+          if (storeData.formatVersion && !isNaN(Number(storeData.formatVersion)) && Number(storeData.formatVersion) < storeInst.formatVersion)
+            yield storeInst.runMigrations(JSON.parse(decodedData), Number(storeData.formatVersion), false);
+          else
+            yield storeInst.setData(JSON.parse(decodedData));
+        }
+      });
+    }
   };
 
   // lib/dom.ts
@@ -308,11 +440,6 @@ var UserUtils = (function (exports) {
       return window;
     }
   }
-  function insertAfter(beforeElement, afterElement) {
-    var _a;
-    (_a = beforeElement.parentNode) == null ? void 0 : _a.insertBefore(afterElement, beforeElement.nextSibling);
-    return afterElement;
-  }
   function addParent(element, newParent) {
     const oldParent = element.parentNode;
     if (!oldParent)
@@ -336,18 +463,22 @@ var UserUtils = (function (exports) {
     }));
     return Promise.allSettled(promises);
   }
-  function openInNewTab(href) {
-    const openElem = document.createElement("a");
-    Object.assign(openElem, {
-      className: "userutils-open-in-new-tab",
-      target: "_blank",
-      rel: "noopener noreferrer",
-      href
-    });
-    openElem.style.display = "none";
-    document.body.appendChild(openElem);
-    openElem.click();
-    setTimeout(openElem.remove, 50);
+  function openInNewTab(href, background) {
+    try {
+      GM.openInTab(href, background);
+    } catch (e) {
+      const openElem = document.createElement("a");
+      Object.assign(openElem, {
+        className: "userutils-open-in-new-tab",
+        target: "_blank",
+        rel: "noopener noreferrer",
+        href
+      });
+      openElem.style.display = "none";
+      document.body.appendChild(openElem);
+      openElem.click();
+      setTimeout(openElem.remove, 50);
+    }
   }
   function interceptEvent(eventObject, eventName, predicate = () => true) {
     Error.stackTraceLimit = Math.max(Error.stackTraceLimit, 100);
@@ -455,9 +586,14 @@ var UserUtils = (function (exports) {
         id = setTimeout(() => controller.abort(), timeout);
         signalOpts = { signal: controller.signal };
       }
-      const res = yield fetch(input, __spreadValues(__spreadValues({}, options), signalOpts));
-      clearTimeout(id);
-      return res;
+      try {
+        const res = yield fetch(input, __spreadValues(__spreadValues({}, options), signalOpts));
+        id && clearTimeout(id);
+        return res;
+      } catch (err) {
+        id && clearTimeout(id);
+        throw err;
+      }
     });
   }
   function insertValues(input, ...values) {
@@ -497,8 +633,38 @@ var UserUtils = (function (exports) {
   function str2ab(str) {
     return Uint8Array.from(getUnsafeWindow().atob(str), (c) => c.charCodeAt(0));
   }
+  function computeHash(input, algorithm = "SHA-256") {
+    return __async(this, null, function* () {
+      let data;
+      if (typeof input === "string") {
+        const encoder = new TextEncoder();
+        data = encoder.encode(input);
+      } else
+        data = input;
+      const hashBuffer = yield crypto.subtle.digest(algorithm, data);
+      const hashArray = Array.from(new Uint8Array(hashBuffer));
+      const hashHex = hashArray.map((byte) => byte.toString(16).padStart(2, "0")).join("");
+      return hashHex;
+    });
+  }
+  function randomId(length = 16, radix = 16, enhancedEntropy = false) {
+    if (enhancedEntropy) {
+      const arr = new Uint8Array(length);
+      crypto.getRandomValues(arr);
+      return Array.from(
+        arr,
+        (v) => mapRange(v, 0, 255, 0, radix).toString(radix).substring(0, 1)
+      ).join("");
+    }
+    return Array.from(
+      { length },
+      () => Math.floor(Math.random() * radix).toString(radix)
+    ).join("");
+  }
 
   // lib/SelectorObserver.ts
+  var domLoaded = false;
+  document.addEventListener("DOMContentLoaded", () => domLoaded = true);
   var SelectorObserver = class {
     constructor(baseElement, options = {}) {
       __publicField(this, "enabled", false);
@@ -509,7 +675,6 @@ var UserUtils = (function (exports) {
       __publicField(this, "listenerMap");
       this.baseElement = baseElement;
       this.listenerMap = /* @__PURE__ */ new Map();
-      this.observer = new MutationObserver(() => this.checkAllSelectors());
       const _a = options, {
         defaultDebounce,
         defaultDebounceEdge,
@@ -531,11 +696,21 @@ var UserUtils = (function (exports) {
         disableOnNoListeners: disableOnNoListeners != null ? disableOnNoListeners : false,
         enableOnAddListener: enableOnAddListener != null ? enableOnAddListener : true
       };
+      if (typeof this.customOptions.checkInterval !== "number") {
+        this.observer = new MutationObserver(() => this.checkAllSelectors());
+      } else {
+        this.checkAllSelectors();
+        setInterval(() => this.checkAllSelectors(), this.customOptions.checkInterval);
+      }
     }
+    /** Call to check all selectors in the {@linkcode listenerMap} using {@linkcode checkSelector()} */
     checkAllSelectors() {
+      if (!this.enabled || !domLoaded)
+        return;
       for (const [selector, listeners] of this.listenerMap.entries())
         this.checkSelector(selector, listeners);
     }
+    /** Checks if the element(s) with the given {@linkcode selector} exist in the DOM and calls the respective {@linkcode listeners} accordingly */
     checkSelector(selector, listeners) {
       var _a;
       if (!this.enabled)
@@ -567,9 +742,6 @@ var UserUtils = (function (exports) {
           this.disable();
       }
     }
-    debounce(func, time, edge = "falling") {
-      return debounce(func, time, edge);
-    }
     /**
      * Starts observing the children of the base element for changes to the given {@linkcode selector} according to the set {@linkcode options}
      * @param selector The selector to observe
@@ -578,11 +750,16 @@ var UserUtils = (function (exports) {
      * @param [options.all] Whether to use `querySelectorAll()` instead - default is false
      * @param [options.continuous] Whether to call the listener continuously instead of just once - default is false
      * @param [options.debounce] Whether to debounce the listener to reduce calls to `querySelector` or `querySelectorAll` - set undefined or <=0 to disable (default)
+     * @returns Returns a function that can be called to remove this listener more easily
      */
     addListener(selector, options) {
-      options = __spreadValues({ all: false, continuous: false, debounce: 0 }, options);
+      options = __spreadValues({
+        all: false,
+        continuous: false,
+        debounce: 0
+      }, options);
       if (options.debounce && options.debounce > 0 || this.customOptions.defaultDebounce && this.customOptions.defaultDebounce > 0) {
-        options.listener = this.debounce(
+        options.listener = debounce(
           options.listener,
           options.debounce || this.customOptions.defaultDebounce,
           options.debounceEdge || this.customOptions.defaultDebounceEdge
@@ -595,13 +772,15 @@ var UserUtils = (function (exports) {
       if (this.enabled === false && this.customOptions.enableOnAddListener)
         this.enable();
       this.checkSelector(selector, [options]);
+      return () => this.removeListener(selector, options);
     }
     /** Disables the observation of the child elements */
     disable() {
+      var _a;
       if (!this.enabled)
         return;
       this.enabled = false;
-      this.observer.disconnect();
+      (_a = this.observer) == null ? void 0 : _a.disconnect();
     }
     /**
      * Enables or reenables the observation of the child elements.
@@ -609,11 +788,12 @@ var UserUtils = (function (exports) {
      * @returns Returns true when the observation was enabled, false otherwise (e.g. when the base element wasn't found)
      */
     enable(immediatelyCheckSelectors = true) {
+      var _a;
       const baseElement = typeof this.baseElement === "string" ? document.querySelector(this.baseElement) : this.baseElement;
       if (this.enabled || !baseElement)
         return false;
       this.enabled = true;
-      this.observer.observe(baseElement, this.observerOptions);
+      (_a = this.observer) == null ? void 0 : _a.observe(baseElement, this.observerOptions);
       if (immediatelyCheckSelectors)
         this.checkAllSelectors();
       return true;
@@ -684,18 +864,19 @@ var UserUtils = (function (exports) {
   };
 
   exports.DataStore = DataStore;
+  exports.DataStoreSerializer = DataStoreSerializer;
   exports.SelectorObserver = SelectorObserver;
   exports.addGlobalStyle = addGlobalStyle;
   exports.addParent = addParent;
   exports.autoPlural = autoPlural;
   exports.clamp = clamp;
   exports.compress = compress;
+  exports.computeHash = computeHash;
   exports.debounce = debounce;
   exports.decompress = decompress;
   exports.fetchAdvanced = fetchAdvanced;
   exports.getSiblingsFrame = getSiblingsFrame;
   exports.getUnsafeWindow = getUnsafeWindow;
-  exports.insertAfter = insertAfter;
   exports.insertValues = insertValues;
   exports.interceptEvent = interceptEvent;
   exports.interceptWindowEvent = interceptWindowEvent;