@sv443-network/userutils 6.2.0 → 7.0.0

package/dist/index.js

@@ -79,14 +79,6 @@ function randRange(...args) {
     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) {
@@ -122,28 +114,32 @@ var DataStore = class {
    * 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.  
@@ -152,19 +148,25 @@ var DataStore = class {
   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();
@@ -175,19 +177,20 @@ var DataStore = class {
   /**
    * 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();
     }));
@@ -196,12 +199,12 @@ var DataStore = class {
   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();
       }));
@@ -217,14 +220,25 @@ var DataStore = class {
   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;
@@ -239,6 +253,8 @@ var DataStore = class {
             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();
@@ -246,18 +262,19 @@ var DataStore = class {
         }
       }
       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)
@@ -268,16 +285,131 @@ var DataStore = class {
   /** 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
@@ -288,11 +420,6 @@ function getUnsafeWindow() {
     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)
@@ -316,18 +443,22 @@ function preloadImages(srcUrls, rejects = false) {
   }));
   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);
@@ -435,9 +566,14 @@ function fetchAdvanced(_0) {
       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) {
@@ -477,8 +613,38 @@ function ab2str(buf) {
 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);
@@ -489,7 +655,6 @@ var SelectorObserver = class {
     __publicField(this, "listenerMap");
     this.baseElement = baseElement;
     this.listenerMap = /* @__PURE__ */ new Map();
-    this.observer = new MutationObserver(() => this.checkAllSelectors());
     const _a = options, {
       defaultDebounce,
       defaultDebounceEdge,
@@ -511,11 +676,21 @@ var SelectorObserver = class {
       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)
@@ -547,9 +722,6 @@ var SelectorObserver = class {
         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
@@ -558,11 +730,16 @@ var SelectorObserver = class {
    * @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
@@ -575,13 +752,15 @@ var SelectorObserver = class {
     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.
@@ -589,11 +768,12 @@ var SelectorObserver = class {
    * @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;
@@ -664,18 +844,19 @@ tr.getLanguage = () => {
 };
 
 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;