@sv443-network/userutils 6.3.0 → 7.0.1

package/dist/index.mjs

@@ -77,14 +77,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) {
@@ -120,28 +112,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.  
@@ -150,19 +146,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();
@@ -173,19 +175,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();
     }));
@@ -194,12 +197,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();
       }));
@@ -215,14 +218,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;
@@ -237,6 +251,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();
@@ -244,18 +260,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)
@@ -266,16 +283,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
@@ -286,11 +418,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)
@@ -437,9 +564,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) {
@@ -479,8 +611,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);
@@ -491,7 +653,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,
@@ -513,11 +674,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)
@@ -549,9 +720,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
@@ -560,11 +728,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
@@ -577,13 +750,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.
@@ -591,11 +766,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;
@@ -665,4 +841,4 @@ tr.getLanguage = () => {
   return curLang;
 };
 
-export { DataStore, SelectorObserver, addGlobalStyle, addParent, autoPlural, clamp, compress, debounce, decompress, fetchAdvanced, getSiblingsFrame, getUnsafeWindow, insertAfter, insertValues, interceptEvent, interceptWindowEvent, isScrollable, mapRange, observeElementProp, openInNewTab, pauseFor, preloadImages, randRange, randomId, randomItem, randomItemIndex, randomizeArray, takeRandomItem, tr };
+export { DataStore, DataStoreSerializer, SelectorObserver, addGlobalStyle, addParent, autoPlural, clamp, compress, computeHash, debounce, decompress, fetchAdvanced, getSiblingsFrame, getUnsafeWindow, insertValues, interceptEvent, interceptWindowEvent, isScrollable, mapRange, observeElementProp, openInNewTab, pauseFor, preloadImages, randRange, randomId, randomItem, randomItemIndex, randomizeArray, takeRandomItem, tr };

package/dist/lib/DataStore.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="greasemonkey" />
 /** Function that takes the data in the old format and returns the data in the new format. Also supports an asynchronous migration. */
 type MigrationFunc = (oldData: any) => any | Promise<any>;
 /** Dictionary of format version numbers and the function that migrates to them from the previous whole integer */
@@ -10,7 +11,7 @@ export type DataStoreOptions<TData> = {
      * The default data object to use if no data is saved in persistent storage yet.
      * Until the data is loaded from persistent storage with `loadData()`, this will be the data returned by `getData()`
      *
-     * ⚠️ This has to be an object that can be serialized to JSON, so no functions or circular references are allowed, they will cause unexpected behavior.
+     * ⚠️ This has to be an object that can be serialized to JSON using `JSON.stringify()`, so no functions or circular references are allowed, they will cause unexpected behavior.
      */
     defaultData: TData;
     /**
@@ -28,6 +29,12 @@ export type DataStoreOptions<TData> = {
      * If the current format version is not in the dictionary, no migrations will be run.
      */
     migrations?: DataMigrationsDict;
+    /**
+     * Where the data should be saved (`"GM"` by default).
+     * The protected methods `getValue` , `setValue`  and `deleteValue` are used to interact with the storage.
+     * If you want to use a different storage method, you can extend the class and overwrite these methods.
+     */
+    storageMethod?: "GM" | "localStorage" | "sessionStorage";
 } & ({
     /**
      * Function to use to encode the data prior to saving it in persistent storage.
@@ -50,32 +57,36 @@ export type DataStoreOptions<TData> = {
     decodeData?: never;
 });
 /**
- * Manages a sync & async persistent JSON database that is cached in memory and persistently saved across sessions.
+ * Manages a hybrid synchronous & asynchronous persistent JSON database that is cached in memory and persistently saved across sessions using [GM storage.](https://wiki.greasespot.net/GM.setValue)
  * Supports migrating data from older format 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`
+ * All methods are at least `protected`, so you can easily extend this class and overwrite them to use a different storage method or to add additional functionality.
+ * Remember that you can call `super.methodName()` in the subclass to access the original method.
+ *
+ * ⚠️ 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 `defaultData`) - this should also be the type of the data format associated with the current `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.)
  */
-export declare class DataStore<TData = any> {
+export declare class DataStore<TData extends object = object> {
     readonly id: string;
     readonly formatVersion: number;
     readonly defaultData: TData;
+    readonly encodeData: DataStoreOptions<TData>["encodeData"];
+    readonly decodeData: DataStoreOptions<TData>["decodeData"];
+    readonly storageMethod: Required<DataStoreOptions<TData>>["storageMethod"];
     private cachedData;
     private migrations?;
-    private encodeData;
-    private decodeData;
     /**
      * 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: DataStoreOptions<TData>);
     /**
      * Loads the data saved in persistent storage into the in-memory cache and also returns it.
@@ -86,8 +97,9 @@ export declare class DataStore<TData = any> {
     /**
      * 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(): TData;
+    getData(deepCopy?: boolean): TData;
     /** Saves the data synchronously to the in-memory cache and asynchronously to the persistent storage */
     setData(data: TData): Promise<void>;
     /** Saves the default data passed in the constructor synchronously to the in-memory cache and asynchronously to persistent storage */
@@ -100,13 +112,30 @@ export declare class DataStore<TData = any> {
      * ⚠️ This requires the additional directive `@grant GM.deleteValue`
      */
     deleteData(): Promise<void>;
-    /** Runs all necessary migration functions consecutively - may be overwritten in a subclass */
-    protected runMigrations(oldData: any, oldFmtVer: number): Promise<TData>;
+    /** Returns whether encoding and decoding are enabled for this DataStore instance */
+    encodingEnabled(): this is Required<Pick<DataStoreOptions<TData>, "encodeData" | "decodeData">>;
+    /**
+     * 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: any, oldFmtVer: number, resetOnError?: boolean): Promise<TData>;
     /** Serializes the data using the optional this.encodeData() and returns it as a string */
-    private serializeData;
+    protected serializeData(data: TData, useEncoding?: boolean): Promise<string>;
     /** Deserializes the data using the optional this.decodeData() and returns it as a JSON object */
-    private deserializeData;
-    /** Copies a JSON-compatible object and loses its internal references */
-    private deepCopy;
+    protected deserializeData(data: string, useEncoding?: boolean): Promise<TData>;
+    /** Copies a JSON-compatible object and loses all its internal references in the process */
+    protected deepCopy<T>(obj: T): T;
+    /** Gets a value from persistent storage - can be overwritten in a subclass if you want to use something other than GM storage */
+    protected getValue<TValue extends GM.Value = string>(name: string, defaultValue: TValue): Promise<string | TValue>;
+    /**
+     * 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.
+     */
+    protected setValue(name: string, value: GM.Value): Promise<void>;
+    /** Deletes a value from persistent storage - can be overwritten in a subclass if you want to use something other than GM storage */
+    protected deleteValue(name: string): Promise<void>;
 }
 export {};

package/dist/lib/DataStoreSerializer.d.ts

@@ -0,0 +1,44 @@
+import { type DataStore } from "./index.js";
+export type DataStoreSerializerOptions = {
+    /** Whether to add a checksum to the exported data */
+    addChecksum?: boolean;
+    /** Whether to ensure the integrity of the data when importing it (unless the checksum property doesn't exist) */
+    ensureIntegrity?: boolean;
+};
+/** Serialized data of a DataStore instance */
+export type SerializedDataStore = {
+    /** The ID of the DataStore instance */
+    id: string;
+    /** The serialized data */
+    data: string;
+    /** The format version of the data */
+    formatVersion: number;
+    /** Whether the data is encoded */
+    encoded: boolean;
+    /** The checksum of the data - key is not present for data without a checksum */
+    checksum?: string;
+};
+/**
+ * Allows for easy serialization and deserialization of multiple DataStore instances.
+ *
+ * All methods are at least `protected`, so you can easily extend this class and overwrite them to use a different storage method or to add additional functionality.
+ * Remember that you can call `super.methodName()` in the subclass to access the original method.
+ *
+ * ⚠️ Needs to run in a secure context (HTTPS) due to the use of the SubtleCrypto API if checksumming is enabled.
+ */
+export declare class DataStoreSerializer {
+    protected stores: DataStore[];
+    protected options: Required<DataStoreSerializerOptions>;
+    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>;
+    /**
+     * 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>;
+}