@sv443-network/userutils 10.0.6 → 10.2.0

package/dist/UserUtils.cjs

@@ -5,6 +5,7 @@ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
@@ -26,6 +27,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   mod
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
 
 // lib/index.ts
 var lib_exports = {};
@@ -62,6 +64,7 @@ __export(lib_exports, {
   consumeGen: () => consumeGen,
   consumeStringGen: () => consumeStringGen,
   createProgressBar: () => createProgressBar,
+  createRecurringTask: () => createRecurringTask,
   currentDialogId: () => currentDialogId,
   darkenColor: () => darkenColor,
   debounce: () => debounce,
@@ -110,11 +113,12 @@ __export(lib_exports, {
   takeRandomItemIndex: () => takeRandomItemIndex,
   tr: () => tr,
   truncStr: () => truncStr,
-  valsWithin: () => valsWithin
+  valsWithin: () => valsWithin,
+  versions: () => versions
 });
 module.exports = __toCommonJS(lib_exports);
 
-// node_modules/.pnpm/@sv443-network+coreutils@3.0.5/node_modules/@sv443-network/coreutils/dist/CoreUtils.mjs
+// node_modules/.pnpm/@sv443-network+coreutils@3.4.0/node_modules/@sv443-network/coreutils/dist/CoreUtils.mjs
 function bitSetHas(bitSet, checkVal) {
   return (bitSet & checkVal) === checkVal;
 }
@@ -260,7 +264,7 @@ function darkenColor(color, percent, upperCase = false) {
   if (isHexCol)
     return rgbToHex(r, g, b, a, color.startsWith("#"), upperCase);
   else if (color.startsWith("rgba"))
-    return `rgba(${r}, ${g}, ${b}, ${a ?? NaN})`;
+    return `rgba(${r}, ${g}, ${b}, ${a != null ? a : NaN})`;
   else
     return `rgb(${r}, ${g}, ${b})`;
 }
@@ -293,7 +297,8 @@ function atoab(str) {
   return Uint8Array.from(atob(str), (c) => c.charCodeAt(0));
 }
 async function compress(input, compressionFormat, outputType = "string") {
-  const byteArray = input instanceof Uint8Array ? input : new TextEncoder().encode((input == null ? void 0 : input.toString()) ?? String(input));
+  var _a;
+  const byteArray = input instanceof Uint8Array ? input : new TextEncoder().encode((_a = input == null ? void 0 : input.toString()) != null ? _a : String(input));
   const comp = new CompressionStream(compressionFormat);
   const writer = comp.writable.getWriter();
   writer.write(byteArray);
@@ -302,7 +307,8 @@ async function compress(input, compressionFormat, outputType = "string") {
   return outputType === "arrayBuffer" ? uintArr : abtoa(uintArr);
 }
 async function decompress(input, compressionFormat, outputType = "string") {
-  const byteArray = input instanceof Uint8Array ? input : atoab((input == null ? void 0 : input.toString()) ?? String(input));
+  var _a;
+  const byteArray = input instanceof Uint8Array ? input : atoab((_a = input == null ? void 0 : input.toString()) != null ? _a : String(input));
   const decomp = new DecompressionStream(compressionFormat);
   const writer = decomp.writable.getWriter();
   writer.write(byteArray);
@@ -347,9 +353,9 @@ function randomId(length = 16, radix = 16, enhancedEntropy = false, randomCase =
   return arr.map((v) => caseArr[randRange(0, caseArr.length - 1, enhancedEntropy)] === 1 ? v.toUpperCase() : v).join("");
 }
 var DatedError = class extends Error {
-  date;
   constructor(message, options) {
     super(message, options);
+    __publicField(this, "date");
     this.name = this.constructor.name;
     this.date = /* @__PURE__ */ new Date();
   }
@@ -432,7 +438,7 @@ function pauseFor(time, signal, rejectOnAbort = false) {
   });
 }
 function pureObj(obj) {
-  return Object.assign(/* @__PURE__ */ Object.create(null), obj ?? {});
+  return Object.assign(/* @__PURE__ */ Object.create(null), obj != null ? obj : {});
 }
 function setImmediateInterval(callback, interval, signal) {
   let intervalId;
@@ -471,15 +477,50 @@ function scheduleExit(code = 0, timeout = 0) {
   setTimeout(exit, timeout);
 }
 function getCallStack(asArray, lines = Infinity) {
+  var _a;
   if (typeof lines !== "number" || isNaN(lines) || lines < 0)
     throw new TypeError("lines parameter must be a non-negative number");
   try {
-    throw new Error("This is to capture a stack trace with CoreUtils.getCallStack(). (If you see this somewhere, you can safely ignore it.)");
+    throw new CustomError("GetCallStack", "Capturing a stack trace with CoreUtils.getCallStack(). If you see this anywhere, you can safely ignore it.");
   } catch (err) {
-    const stack = (err.stack ?? "").split("\n").map((line) => line.trim()).slice(2, lines + 2);
+    const stack = ((_a = err.stack) != null ? _a : "").split("\n").map((line) => line.trim()).slice(2, lines + 2);
     return asArray !== false ? stack : stack.join("\n");
   }
 }
+function createRecurringTask(options) {
+  var _a;
+  let iterations = 0;
+  let aborted = false;
+  (_a = options.signal) == null ? void 0 : _a.addEventListener("abort", () => {
+    aborted = true;
+  }, { once: true });
+  const runRecurringTask = async (initial = false) => {
+    var _a3, _b;
+    var _a2;
+    if (aborted)
+      return;
+    try {
+      if (((_a3 = options.immediate) != null ? _a3 : true) || !initial) {
+        iterations++;
+        if ((_b = await ((_a2 = options.condition) == null ? void 0 : _a2.call(options, iterations - 1))) != null ? _b : true) {
+          const val = await options.task(iterations - 1);
+          if (options.onSuccess)
+            await options.onSuccess(val, iterations - 1);
+        }
+      }
+    } catch (err) {
+      if (options.onError)
+        await options.onError(err, iterations - 1);
+      if (options.abortOnError)
+        aborted = true;
+      if (!options.onError && !options.abortOnError)
+        throw err;
+    }
+    if (!aborted && (typeof options.maxIterations !== "number" || iterations < options.maxIterations))
+      setTimeout(runRecurringTask, options.timeout);
+  };
+  return runRecurringTask(true);
+}
 function autoPlural(term, num, pluralType = "auto") {
   if (typeof num !== "number") {
     if ("length" in num)
@@ -529,9 +570,10 @@ function createProgressBar(percentage, barLength, chars = defaultPbChars) {
 }
 function insertValues(input, ...values) {
   return input.replace(/%\d/gm, (match) => {
+    var _a2;
     var _a;
     const argIndex = Number(match.substring(1)) - 1;
-    return (_a = values[argIndex] ?? match) == null ? void 0 : _a.toString();
+    return (_a = (_a2 = values[argIndex]) != null ? _a2 : match) == null ? void 0 : _a.toString();
   });
 }
 function joinArrayReadable(array, separators = ", ", lastSeparator = " and ") {
@@ -562,31 +604,209 @@ function secsToTimeStr(seconds) {
   ].join("");
 }
 function truncStr(input, length, endStr = "...") {
-  const str = (input == null ? void 0 : input.toString()) ?? String(input);
+  var _a;
+  const str = (_a = input == null ? void 0 : input.toString()) != null ? _a : String(input);
   const finalStr = str.length > length ? str.substring(0, length - endStr.length) + endStr : str;
   return finalStr.length > length ? finalStr.substring(0, length) : finalStr;
 }
-var dsFmtVer = 1;
-var DataStore = class {
-  id;
-  formatVersion;
-  defaultData;
-  encodeData;
-  decodeData;
-  compressionFormat = "deflate-raw";
-  memoryCache;
-  engine;
-  options;
+var createNanoEvents = () => ({
+  emit(event, ...args) {
+    for (let callbacks = this.events[event] || [], i = 0, length = callbacks.length; i < length; i++) {
+      callbacks[i](...args);
+    }
+  },
+  events: {},
+  on(event, cb) {
+    var _a;
+    ;
+    ((_a = this.events)[event] || (_a[event] = [])).push(cb);
+    return () => {
+      var _a2;
+      this.events[event] = (_a2 = this.events[event]) == null ? void 0 : _a2.filter((i) => cb !== i);
+    };
+  }
+});
+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", []);
+    __publicField(this, "emitterOptions");
+    this.emitterOptions = {
+      publicEmit: false,
+      ...options
+    };
+  }
+  //#region on
+  /**
+   * 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 = () => {
+      if (!unsub)
+        return;
+      unsub();
+      this.eventUnsubscribes = this.eventUnsubscribes.filter((u) => u !== unsub);
+    };
+    unsub = this.events.on(event, cb);
+    this.eventUnsubscribes.push(unsub);
+    return unsubProxy;
+  }
+  //#region 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) => {
+        cb == null ? void 0 : cb(...args);
+        unsub == null ? void 0 : unsub();
+        resolve(args);
+      });
+      unsub = this.events.on(event, onceProxy);
+      this.eventUnsubscribes.push(unsub);
+    });
+  }
+  //#region onMulti
+  /**
+   * Allows subscribing to multiple events and calling the callback only when one of, all of, or a subset of the events are emitted, either continuously or only once.  
+   * @param options An object or array of objects with the following properties:  
+   * `callback` (required) is the function that will be called when the conditions are met.  
+   *   
+   * Set `once` to true to call the callback only once for the first event (or set of events) that match the criteria, then stop listening.  
+   * If `signal` is provided, the subscription will be canceled when the given signal is aborted.  
+   *   
+   * If `oneOf` is used, the callback will be called when any of the matching events are emitted.  
+   * If `allOf` is used, the callback will be called after all of the matching events are emitted at least once, then any time any of them are emitted.  
+   * If both `oneOf` and `allOf` are used together, the callback will be called when any of the `oneOf` events are emitted AND all of the `allOf` events have been emitted at least once.  
+   * At least one of `oneOf` or `allOf` must be provided.  
+   *   
+   * @returns Returns a function that can be called to unsubscribe all listeners created by this call. Alternatively, pass an `AbortSignal` to all options objects to achieve the same effect or for finer control.
+   */
+  onMulti(options) {
+    const allUnsubs = [];
+    const unsubAll = () => {
+      for (const unsub of allUnsubs)
+        unsub();
+      allUnsubs.splice(0, allUnsubs.length);
+      this.eventUnsubscribes = this.eventUnsubscribes.filter((u) => !allUnsubs.includes(u));
+    };
+    for (const opts of Array.isArray(options) ? options : [options]) {
+      const optsWithDefaults = {
+        allOf: [],
+        oneOf: [],
+        once: false,
+        ...opts
+      };
+      const {
+        oneOf,
+        allOf,
+        once,
+        signal,
+        callback
+      } = optsWithDefaults;
+      if (signal == null ? void 0 : signal.aborted)
+        return unsubAll;
+      if (oneOf.length === 0 && allOf.length === 0)
+        throw new TypeError("NanoEmitter.onMulti(): Either `oneOf` or `allOf` or both must be provided in the options");
+      const curEvtUnsubs = [];
+      const checkUnsubAllEvt = (force = false) => {
+        if (!(signal == null ? void 0 : signal.aborted) && !force)
+          return;
+        for (const unsub of curEvtUnsubs)
+          unsub();
+        curEvtUnsubs.splice(0, curEvtUnsubs.length);
+        this.eventUnsubscribes = this.eventUnsubscribes.filter((u) => !curEvtUnsubs.includes(u));
+      };
+      const allOfEmitted = /* @__PURE__ */ new Set();
+      const allOfConditionMet = () => allOf.length === 0 || allOfEmitted.size === allOf.length;
+      for (const event of oneOf) {
+        const unsub = this.events.on(event, ((...args) => {
+          checkUnsubAllEvt();
+          if (allOfConditionMet()) {
+            callback(event, ...args);
+            if (once)
+              checkUnsubAllEvt(true);
+          }
+        }));
+        curEvtUnsubs.push(unsub);
+      }
+      for (const event of allOf) {
+        const unsub = this.events.on(event, ((...args) => {
+          checkUnsubAllEvt();
+          allOfEmitted.add(event);
+          if (allOfConditionMet() && (oneOf.length === 0 || oneOf.includes(event))) {
+            callback(event, ...args);
+            if (once)
+              checkUnsubAllEvt(true);
+          }
+        }));
+        curEvtUnsubs.push(unsub);
+      }
+      allUnsubs.push(() => checkUnsubAllEvt(true));
+    }
+    return unsubAll;
+  }
+  //#region emit
   /**
-   * Whether all first-init checks should be done.  
-   * This includes migrating the internal DataStore format, migrating data from the UserUtils format, and anything similar.  
-   * This is set to `true` by default. Create a subclass and set it to `false` before calling {@linkcode loadData()} if you want to explicitly skip these checks.
+   * 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
    */
-  firstInit = true;
-  /** In-memory cached copy of the data that is saved in persistent storage used for synchronous read access. */
-  cachedData;
-  migrations;
-  migrateIds = [];
+  emit(event, ...args) {
+    if (this.emitterOptions.publicEmit) {
+      this.events.emit(event, ...args);
+      return true;
+    }
+    return false;
+  }
+  //#region unsubscribeAll
+  /** Unsubscribes all event listeners from this instance */
+  unsubscribeAll() {
+    for (const unsub of this.eventUnsubscribes)
+      unsub();
+    this.eventUnsubscribes = [];
+  }
+};
+var dsFmtVer = 1;
+var DataStore = class extends NanoEmitter {
   //#region constructor
   /**
    * Creates an instance of DataStore to manage a sync & async database that is cached in memory and persistently saved across sessions.  
@@ -598,20 +818,43 @@ var DataStore = class {
    * @param opts The options for this DataStore instance
    */
   constructor(opts) {
+    var _a, _b, _c;
+    super(opts.nanoEmitterOptions);
+    __publicField(this, "id");
+    __publicField(this, "formatVersion");
+    __publicField(this, "defaultData");
+    __publicField(this, "encodeData");
+    __publicField(this, "decodeData");
+    __publicField(this, "compressionFormat", "deflate-raw");
+    __publicField(this, "memoryCache");
+    __publicField(this, "engine");
+    __publicField(this, "keyPrefix");
+    __publicField(this, "options");
+    /**
+     * Whether all first-init checks should be done.  
+     * This includes migrating the internal DataStore format, migrating data from the UserUtils format, and anything similar.  
+     * This is set to `true` by default. Create a subclass and set it to `false` before calling {@linkcode loadData()} if you want to explicitly skip these checks.
+     */
+    __publicField(this, "firstInit", true);
+    /** In-memory cached copy of the data that is saved in persistent storage used for synchronous read access. */
+    __publicField(this, "cachedData");
+    __publicField(this, "migrations");
+    __publicField(this, "migrateIds", []);
     this.id = opts.id;
     this.formatVersion = opts.formatVersion;
     this.defaultData = opts.defaultData;
-    this.memoryCache = opts.memoryCache ?? true;
+    this.memoryCache = (_a = opts.memoryCache) != null ? _a : true;
     this.cachedData = this.memoryCache ? opts.defaultData : {};
     this.migrations = opts.migrations;
     if (opts.migrateIds)
       this.migrateIds = Array.isArray(opts.migrateIds) ? opts.migrateIds : [opts.migrateIds];
     this.engine = typeof opts.engine === "function" ? opts.engine() : opts.engine;
+    this.keyPrefix = (_b = opts.keyPrefix) != null ? _b : "__ds-";
     this.options = opts;
     if ("encodeData" in opts && "decodeData" in opts && Array.isArray(opts.encodeData) && Array.isArray(opts.decodeData)) {
       this.encodeData = [opts.encodeData[0], opts.encodeData[1]];
       this.decodeData = [opts.decodeData[0], opts.decodeData[1]];
-      this.compressionFormat = opts.encodeData[0] ?? null;
+      this.compressionFormat = (_c = opts.encodeData[0]) != null ? _c : null;
     } else if (opts.compressionFormat === null) {
       this.encodeData = void 0;
       this.decodeData = void 0;
@@ -635,6 +878,7 @@ var DataStore = class {
    * Also runs all necessary migration functions if the data format has changed since the last time the data was saved.
    */
   async loadData() {
+    var _a;
     try {
       if (this.firstInit) {
         this.firstInit = false;
@@ -648,13 +892,13 @@ var DataStore = class {
             promises.push(this.engine.setValue(newKey, value));
             promises.push(this.engine.deleteValue(oldKey));
           };
-          migrateFmt(`_uucfg-${this.id}`, `__ds-${this.id}-dat`, oldData);
+          migrateFmt(`_uucfg-${this.id}`, `${this.keyPrefix}${this.id}-dat`, oldData);
           if (!isNaN(oldVer))
-            migrateFmt(`_uucfgver-${this.id}`, `__ds-${this.id}-ver`, oldVer);
+            migrateFmt(`_uucfgver-${this.id}`, `${this.keyPrefix}${this.id}-ver`, oldVer);
           if (typeof oldEnc === "boolean" || oldEnc === "true" || oldEnc === "false" || typeof oldEnc === "number" || oldEnc === "0" || oldEnc === "1")
-            migrateFmt(`_uucfgenc-${this.id}`, `__ds-${this.id}-enf`, [0, "0", true, "true"].includes(oldEnc) ? this.compressionFormat ?? null : null);
+            migrateFmt(`_uucfgenc-${this.id}`, `${this.keyPrefix}${this.id}-enf`, [0, "0", true, "true"].includes(oldEnc) ? (_a = this.compressionFormat) != null ? _a : null : null);
           else {
-            promises.push(this.engine.setValue(`__ds-${this.id}-enf`, this.compressionFormat));
+            promises.push(this.engine.setValue(`${this.keyPrefix}${this.id}-enf`, this.compressionFormat));
             promises.push(this.engine.deleteValue(`_uucfgenc-${this.id}`));
           }
           await Promise.allSettled(promises);
@@ -666,31 +910,27 @@ var DataStore = class {
         await this.migrateId(this.migrateIds);
         this.migrateIds = [];
       }
-      const storedDataRaw = await this.engine.getValue(`__ds-${this.id}-dat`, null);
-      let storedFmtVer = Number(await this.engine.getValue(`__ds-${this.id}-ver`, NaN));
-      if (typeof storedDataRaw !== "string") {
-        await this.saveDefaultData();
-        return this.engine.deepCopy(this.defaultData);
+      const storedDataRaw = await this.engine.getValue(`${this.keyPrefix}${this.id}-dat`, null);
+      const storedFmtVer = Number(await this.engine.getValue(`${this.keyPrefix}${this.id}-ver`, NaN));
+      if (typeof storedDataRaw !== "string" && typeof storedDataRaw !== "object" || storedDataRaw === null || isNaN(storedFmtVer)) {
+        await this.saveDefaultData(false);
+        const data = this.engine.deepCopy(this.defaultData);
+        this.events.emit("loadData", data);
+        return data;
       }
-      const storedData = storedDataRaw ?? JSON.stringify(this.defaultData);
-      const encodingFmt = String(await this.engine.getValue(`__ds-${this.id}-enf`, null));
+      const storedData = storedDataRaw != null ? storedDataRaw : JSON.stringify(this.defaultData);
+      const encodingFmt = String(await this.engine.getValue(`${this.keyPrefix}${this.id}-enf`, null));
       const isEncoded = encodingFmt !== "null" && encodingFmt !== "false" && encodingFmt !== "0" && encodingFmt !== "" && encodingFmt !== null;
-      let saveData = false;
-      if (isNaN(storedFmtVer)) {
-        await this.engine.setValue(`__ds-${this.id}-ver`, storedFmtVer = this.formatVersion);
-        saveData = true;
-      }
-      let parsed = await this.engine.deserializeData(storedData, isEncoded);
+      let parsed = typeof storedData === "string" ? await this.engine.deserializeData(storedData, isEncoded) : storedData;
       if (storedFmtVer < this.formatVersion && this.migrations)
         parsed = await this.runMigrations(parsed, storedFmtVer);
-      if (saveData)
-        await this.setData(parsed);
-      if (this.memoryCache)
-        return this.cachedData = this.engine.deepCopy(parsed);
-      else
-        return this.engine.deepCopy(parsed);
+      const result = this.memoryCache ? this.cachedData = this.engine.deepCopy(parsed) : this.engine.deepCopy(parsed);
+      this.events.emit("loadData", result);
+      return result;
     } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
       console.warn("Error while parsing JSON data, resetting it to the default value.", err);
+      this.events.emit("error", error);
       await this.saveDefaultData();
       return this.defaultData;
     }
@@ -709,27 +949,47 @@ var DataStore = class {
   //#region setData
   /** Saves the data synchronously to the in-memory cache and asynchronously to the persistent storage */
   setData(data) {
-    if (this.memoryCache)
+    const dataCopy = this.engine.deepCopy(data);
+    if (this.memoryCache) {
       this.cachedData = data;
+      this.events.emit("updateDataSync", dataCopy);
+    }
     return new Promise(async (resolve) => {
-      await Promise.allSettled([
-        this.engine.setValue(`__ds-${this.id}-dat`, await this.engine.serializeData(data, this.encodingEnabled())),
-        this.engine.setValue(`__ds-${this.id}-ver`, this.formatVersion),
-        this.engine.setValue(`__ds-${this.id}-enf`, this.compressionFormat)
+      const results = await Promise.allSettled([
+        this.engine.setValue(`${this.keyPrefix}${this.id}-dat`, await this.engine.serializeData(data, this.encodingEnabled())),
+        this.engine.setValue(`${this.keyPrefix}${this.id}-ver`, this.formatVersion),
+        this.engine.setValue(`${this.keyPrefix}${this.id}-enf`, this.compressionFormat)
       ]);
+      if (results.every((r) => r.status === "fulfilled"))
+        this.events.emit("updateData", dataCopy);
+      else {
+        const error = new Error("Error while saving data to persistent storage: " + results.map((r) => r.status === "rejected" ? r.reason : null).filter(Boolean).join("; "));
+        console.error(error);
+        this.events.emit("error", error);
+      }
       resolve();
     });
   }
   //#region saveDefaultData
-  /** Saves the default data passed in the constructor synchronously to the in-memory cache and asynchronously to persistent storage */
-  async saveDefaultData() {
+  /**
+   * Saves the default data passed in the constructor synchronously to the in-memory cache and asynchronously to persistent storage.
+   * @param emitEvent Whether to emit the `setDefaultData` event - set to `false` to prevent event emission (used internally during initial population in {@linkcode loadData()})
+   */
+  async saveDefaultData(emitEvent = true) {
     if (this.memoryCache)
       this.cachedData = this.defaultData;
-    await Promise.allSettled([
-      this.engine.setValue(`__ds-${this.id}-dat`, await this.engine.serializeData(this.defaultData, this.encodingEnabled())),
-      this.engine.setValue(`__ds-${this.id}-ver`, this.formatVersion),
-      this.engine.setValue(`__ds-${this.id}-enf`, this.compressionFormat)
+    const results = await Promise.allSettled([
+      this.engine.setValue(`${this.keyPrefix}${this.id}-dat`, await this.engine.serializeData(this.defaultData, this.encodingEnabled())),
+      this.engine.setValue(`${this.keyPrefix}${this.id}-ver`, this.formatVersion),
+      this.engine.setValue(`${this.keyPrefix}${this.id}-enf`, this.compressionFormat)
     ]);
+    if (results.every((r) => r.status === "fulfilled"))
+      emitEvent && this.events.emit("setDefaultData", this.defaultData);
+    else {
+      const error = new Error("Error while saving default data to persistent storage: " + results.map((r) => r.status === "rejected" ? r.reason : null).filter(Boolean).join("; "));
+      console.error(error);
+      this.events.emit("error", error);
+    }
   }
   //#region deleteData
   /**
@@ -740,11 +1000,12 @@ var DataStore = class {
   async deleteData() {
     var _a, _b;
     await Promise.allSettled([
-      this.engine.deleteValue(`__ds-${this.id}-dat`),
-      this.engine.deleteValue(`__ds-${this.id}-ver`),
-      this.engine.deleteValue(`__ds-${this.id}-enf`)
+      this.engine.deleteValue(`${this.keyPrefix}${this.id}-dat`),
+      this.engine.deleteValue(`${this.keyPrefix}${this.id}-ver`),
+      this.engine.deleteValue(`${this.keyPrefix}${this.id}-enf`)
     ]);
     await ((_b = (_a = this.engine).deleteStorage) == null ? void 0 : _b.call(_a));
+    this.events.emit("deleteData");
   }
   //#region encodingEnabled
   /** Returns whether encoding and decoding are enabled for this DataStore instance */
@@ -765,30 +1026,35 @@ var DataStore = class {
     let newData = oldData;
     const sortedMigrations = Object.entries(this.migrations).sort(([a], [b]) => Number(a) - Number(b));
     let lastFmtVer = oldFmtVer;
-    for (const [fmtVer, migrationFunc] of sortedMigrations) {
+    for (let i = 0; i < sortedMigrations.length; i++) {
+      const [fmtVer, migrationFunc] = sortedMigrations[i];
       const ver = Number(fmtVer);
       if (oldFmtVer < this.formatVersion && oldFmtVer < ver) {
         try {
           const migRes = migrationFunc(newData);
           newData = migRes instanceof Promise ? await migRes : migRes;
           lastFmtVer = oldFmtVer = ver;
+          const isFinal = ver >= this.formatVersion || i === sortedMigrations.length - 1;
+          this.events.emit("migrateData", ver, newData, isFinal);
         } catch (err) {
+          const migError = new MigrationError(`Error while running migration function for format version '${fmtVer}'`, { cause: err });
+          this.events.emit("migrationError", ver, migError);
+          this.events.emit("error", migError);
           if (!resetOnError)
-            throw new MigrationError(`Error while running migration function for format version '${fmtVer}'`, { cause: err });
+            throw migError;
           await this.saveDefaultData();
           return this.engine.deepCopy(this.defaultData);
         }
       }
     }
     await Promise.allSettled([
-      this.engine.setValue(`__ds-${this.id}-dat`, await this.engine.serializeData(newData, this.encodingEnabled())),
-      this.engine.setValue(`__ds-${this.id}-ver`, lastFmtVer),
-      this.engine.setValue(`__ds-${this.id}-enf`, this.compressionFormat)
+      this.engine.setValue(`${this.keyPrefix}${this.id}-dat`, await this.engine.serializeData(newData, this.encodingEnabled())),
+      this.engine.setValue(`${this.keyPrefix}${this.id}-ver`, lastFmtVer),
+      this.engine.setValue(`${this.keyPrefix}${this.id}-enf`, this.compressionFormat)
     ]);
-    if (this.memoryCache)
-      return this.cachedData = this.engine.deepCopy(newData);
-    else
-      return this.engine.deepCopy(newData);
+    const result = this.memoryCache ? this.cachedData = this.engine.deepCopy(newData) : this.engine.deepCopy(newData);
+    this.events.emit("updateData", result);
+    return result;
   }
   //#region migrateId
   /**
@@ -800,9 +1066,9 @@ var DataStore = class {
     await Promise.all(ids.map(async (id) => {
       const [data, fmtVer, isEncoded] = await (async () => {
         const [d, f, e] = await Promise.all([
-          this.engine.getValue(`__ds-${id}-dat`, JSON.stringify(this.defaultData)),
-          this.engine.getValue(`__ds-${id}-ver`, NaN),
-          this.engine.getValue(`__ds-${id}-enf`, null)
+          this.engine.getValue(`${this.keyPrefix}${id}-dat`, JSON.stringify(this.defaultData)),
+          this.engine.getValue(`${this.keyPrefix}${id}-ver`, NaN),
+          this.engine.getValue(`${this.keyPrefix}${id}-enf`, null)
         ]);
         return [d, Number(f), Boolean(e) && String(e) !== "null"];
       })();
@@ -810,20 +1076,21 @@ var DataStore = class {
         return;
       const parsed = await this.engine.deserializeData(data, isEncoded);
       await Promise.allSettled([
-        this.engine.setValue(`__ds-${this.id}-dat`, await this.engine.serializeData(parsed, this.encodingEnabled())),
-        this.engine.setValue(`__ds-${this.id}-ver`, fmtVer),
-        this.engine.setValue(`__ds-${this.id}-enf`, this.compressionFormat),
-        this.engine.deleteValue(`__ds-${id}-dat`),
-        this.engine.deleteValue(`__ds-${id}-ver`),
-        this.engine.deleteValue(`__ds-${id}-enf`)
+        this.engine.setValue(`${this.keyPrefix}${this.id}-dat`, await this.engine.serializeData(parsed, this.encodingEnabled())),
+        this.engine.setValue(`${this.keyPrefix}${this.id}-ver`, fmtVer),
+        this.engine.setValue(`${this.keyPrefix}${this.id}-enf`, this.compressionFormat),
+        this.engine.deleteValue(`${this.keyPrefix}${id}-dat`),
+        this.engine.deleteValue(`${this.keyPrefix}${id}-ver`),
+        this.engine.deleteValue(`${this.keyPrefix}${id}-enf`)
       ]);
+      this.events.emit("migrateId", id, this.id);
     }));
   }
 };
 var DataStoreEngine = class {
-  dataStoreOptions;
   // setDataStoreOptions() is called from inside the DataStore constructor to set this value
   constructor(options) {
+    __publicField(this, "dataStoreOptions");
     if (options)
       this.dataStoreOptions = options;
   }
@@ -851,7 +1118,7 @@ var DataStoreEngine = class {
     let decRes = ((_a = this.dataStoreOptions) == null ? void 0 : _a.decodeData) && useEncoding ? (_c = (_b = this.dataStoreOptions.decodeData) == null ? void 0 : _b[1]) == null ? void 0 : _c.call(_b, data) : void 0;
     if (decRes instanceof Promise)
       decRes = await decRes;
-    return JSON.parse(decRes ?? data);
+    return JSON.parse(decRes != null ? decRes : data);
   }
   //#region misc api
   /** Throws an error if the DataStoreOptions are not set or invalid */
@@ -869,13 +1136,12 @@ var DataStoreEngine = class {
     try {
       if ("structuredClone" in globalThis)
         return structuredClone(obj);
-    } catch {
+    } catch (e) {
     }
     return JSON.parse(JSON.stringify(obj));
   }
 };
 var BrowserStorageEngine = class extends DataStoreEngine {
-  options;
   /**
    * Creates an instance of `BrowserStorageEngine`.  
    *   
@@ -884,6 +1150,7 @@ var BrowserStorageEngine = class extends DataStoreEngine {
    */
   constructor(options) {
     super(options == null ? void 0 : options.dataStoreOptions);
+    __publicField(this, "options");
     this.options = {
       type: "localStorage",
       ...options
@@ -912,8 +1179,6 @@ var BrowserStorageEngine = class extends DataStoreEngine {
 };
 var fs;
 var FileStorageEngine = class extends DataStoreEngine {
-  options;
-  fileAccessQueue = Promise.resolve();
   /**
    * Creates an instance of `FileStorageEngine`.  
    *   
@@ -922,6 +1187,8 @@ var FileStorageEngine = class extends DataStoreEngine {
    */
   constructor(options) {
     super(options == null ? void 0 : options.dataStoreOptions);
+    __publicField(this, "options");
+    __publicField(this, "fileAccessQueue", Promise.resolve());
     this.options = {
       filePath: (id) => `.ds-${id}`,
       ...options
@@ -930,6 +1197,7 @@ var FileStorageEngine = class extends DataStoreEngine {
   //#region json file
   /** Reads the file contents */
   async readFile() {
+    var _a2;
     var _a, _b, _c, _d;
     this.ensureDataStoreOptions();
     try {
@@ -937,15 +1205,16 @@ var FileStorageEngine = class extends DataStoreEngine {
         fs = (_a = await import("fs/promises")) == null ? void 0 : _a.default;
       if (!fs)
         throw new ScriptContextError("FileStorageEngine requires Node.js or Deno with Node compatibility (v1.31+)", { cause: new DatedError("'node:fs/promises' module not available") });
-      const path = typeof this.options.filePath === "string" ? this.options.filePath : this.options.filePath(this.dataStoreOptions.id);
+      const path = typeof this.options.filePath === "string" ? this.options.filePath : this.options.filePath(this.dataStoreOptions.id, this.dataStoreOptions);
       const data = await fs.readFile(path, "utf-8");
-      return data ? JSON.parse(await ((_d = (_c = (_b = this.dataStoreOptions) == null ? void 0 : _b.decodeData) == null ? void 0 : _c[1]) == null ? void 0 : _d.call(_c, data)) ?? data) : void 0;
-    } catch {
+      return data ? JSON.parse((_a2 = await ((_d = (_c = (_b = this.dataStoreOptions) == null ? void 0 : _b.decodeData) == null ? void 0 : _c[1]) == null ? void 0 : _d.call(_c, data))) != null ? _a2 : data) : void 0;
+    } catch (e) {
       return void 0;
     }
   }
   /** Overwrites the file contents */
   async writeFile(data) {
+    var _a2;
     var _a, _b, _c, _d;
     this.ensureDataStoreOptions();
     try {
@@ -953,9 +1222,9 @@ var FileStorageEngine = class extends DataStoreEngine {
         fs = (_a = await import("fs/promises")) == null ? void 0 : _a.default;
       if (!fs)
         throw new ScriptContextError("FileStorageEngine requires Node.js or Deno with Node compatibility (v1.31+)", { cause: new DatedError("'node:fs/promises' module not available") });
-      const path = typeof this.options.filePath === "string" ? this.options.filePath : this.options.filePath(this.dataStoreOptions.id);
+      const path = typeof this.options.filePath === "string" ? this.options.filePath : this.options.filePath(this.dataStoreOptions.id, this.dataStoreOptions);
       await fs.mkdir(path.slice(0, path.lastIndexOf(path.includes("/") ? "/" : "\\")), { recursive: true });
-      await fs.writeFile(path, await ((_d = (_c = (_b = this.dataStoreOptions) == null ? void 0 : _b.encodeData) == null ? void 0 : _c[1]) == null ? void 0 : _d.call(_c, JSON.stringify(data))) ?? JSON.stringify(data, void 0, 2), "utf-8");
+      await fs.writeFile(path, (_a2 = await ((_d = (_c = (_b = this.dataStoreOptions) == null ? void 0 : _b.encodeData) == null ? void 0 : _c[1]) == null ? void 0 : _d.call(_c, JSON.stringify(data)))) != null ? _a2 : JSON.stringify(data, void 0, 2), "utf-8");
     } catch (err) {
       console.error("Error writing file:", err);
     }
@@ -969,8 +1238,21 @@ var FileStorageEngine = class extends DataStoreEngine {
     const value = data == null ? void 0 : data[name];
     if (typeof value === "undefined")
       return defaultValue;
-    if (typeof value === "string")
-      return value;
+    if (typeof defaultValue === "string") {
+      if (typeof value === "object" && value !== null)
+        return JSON.stringify(value);
+      if (typeof value === "string")
+        return value;
+      return String(value);
+    }
+    if (typeof value === "string") {
+      try {
+        const parsed = JSON.parse(value);
+        return parsed;
+      } catch (e) {
+        return defaultValue;
+      }
+    }
     return value;
   }
   /** Sets a value in persistent storage */
@@ -979,7 +1261,18 @@ var FileStorageEngine = class extends DataStoreEngine {
       let data = await this.readFile();
       if (!data)
         data = {};
-      data[name] = value;
+      let storeVal = value;
+      if (typeof value === "string") {
+        try {
+          if (value.startsWith("{") || value.startsWith("[")) {
+            const parsed = JSON.parse(value);
+            if (typeof parsed === "object" && parsed !== null)
+              storeVal = parsed;
+          }
+        } catch (e) {
+        }
+      }
+      data[name] = storeVal;
       await this.writeFile(data);
     }).catch((err) => {
       console.error("Error in setValue:", err);
@@ -1012,7 +1305,7 @@ var FileStorageEngine = class extends DataStoreEngine {
         fs = (_a = await import("fs/promises")) == null ? void 0 : _a.default;
       if (!fs)
         throw new ScriptContextError("FileStorageEngine requires Node.js or Deno with Node compatibility (v1.31+)", { cause: new DatedError("'node:fs/promises' module not available") });
-      const path = typeof this.options.filePath === "string" ? this.options.filePath : this.options.filePath(this.dataStoreOptions.id);
+      const path = typeof this.options.filePath === "string" ? this.options.filePath : this.options.filePath(this.dataStoreOptions.id, this.dataStoreOptions);
       return await fs.unlink(path);
     } catch (err) {
       console.error("Error deleting file:", err);
@@ -1020,9 +1313,9 @@ var FileStorageEngine = class extends DataStoreEngine {
   }
 };
 var DataStoreSerializer = class _DataStoreSerializer {
-  stores;
-  options;
   constructor(stores, options = {}) {
+    __publicField(this, "stores");
+    __publicField(this, "options");
     if (!crypto || !crypto.subtle)
       throw new ScriptContextError("DataStoreSerializer has to run in a secure context (HTTPS) or in another environment that implements the subtleCrypto API!");
     this.stores = stores;
@@ -1033,7 +1326,10 @@ var DataStoreSerializer = class _DataStoreSerializer {
       ...options
     };
   }
-  /** Calculates the checksum of a string */
+  /**
+   * Calculates the checksum of a string. Uses {@linkcode computeHash()} with SHA-256 and digests as a hex string by default.  
+   * Override this in a subclass if a custom checksum method is needed.
+   */
   async calcChecksum(input) {
     return computeHash(input, "SHA-256");
   }
@@ -1078,8 +1374,9 @@ var DataStoreSerializer = class _DataStoreSerializer {
     if (!Array.isArray(deserStores) || !deserStores.every(_DataStoreSerializer.isSerializedDataStoreObj))
       throw new TypeError("Invalid serialized data format! Expected an array of SerializedDataStore objects.");
     const resolveStoreId = (id) => {
+      var _a2;
       var _a;
-      return ((_a = Object.entries(this.options.remapIds).find(([, v]) => v.includes(id))) == null ? void 0 : _a[0]) ?? id;
+      return (_a2 = (_a = Object.entries(this.options.remapIds).find(([, v]) => v.includes(id))) == null ? void 0 : _a[0]) != null ? _a2 : id;
     };
     const matchesFilter = (id) => typeof stores === "function" ? stores(id) : stores.includes(id);
     for (const storeData of deserStores) {
@@ -1156,218 +1453,23 @@ Has: ${checksum}`);
     return this.stores.filter((s) => typeof stores === "undefined" ? true : Array.isArray(stores) ? stores.includes(s.id) : stores(s.id));
   }
 };
-var createNanoEvents = () => ({
-  emit(event, ...args) {
-    for (let callbacks = this.events[event] || [], i = 0, length = callbacks.length; i < length; i++) {
-      callbacks[i](...args);
-    }
-  },
-  events: {},
-  on(event, cb) {
-    ;
-    (this.events[event] ||= []).push(cb);
-    return () => {
-      var _a;
-      this.events[event] = (_a = this.events[event]) == null ? void 0 : _a.filter((i) => cb !== i);
-    };
-  }
-});
-var NanoEmitter = class {
-  events = createNanoEvents();
-  eventUnsubscribes = [];
-  emitterOptions;
-  /** Creates a new instance of NanoEmitter - a lightweight event emitter with helper methods and a strongly typed event map */
-  constructor(options = {}) {
-    this.emitterOptions = {
-      publicEmit: false,
-      ...options
-    };
-  }
-  //#region on
-  /**
-   * 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 = () => {
-      if (!unsub)
-        return;
-      unsub();
-      this.eventUnsubscribes = this.eventUnsubscribes.filter((u) => u !== unsub);
-    };
-    unsub = this.events.on(event, cb);
-    this.eventUnsubscribes.push(unsub);
-    return unsubProxy;
-  }
-  //#region 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) => {
-        cb == null ? void 0 : cb(...args);
-        unsub == null ? void 0 : unsub();
-        resolve(args);
-      });
-      unsub = this.events.on(event, onceProxy);
-      this.eventUnsubscribes.push(unsub);
-    });
-  }
-  //#region onMulti
-  /**
-   * Allows subscribing to multiple events and calling the callback only when one of, all of, or a subset of the events are emitted, either continuously or only once.  
-   * @param options An object or array of objects with the following properties:  
-   * `callback` (required) is the function that will be called when the conditions are met.  
-   *   
-   * Set `once` to true to call the callback only once for the first event (or set of events) that match the criteria, then stop listening.  
-   * If `signal` is provided, the subscription will be canceled when the given signal is aborted.  
-   *   
-   * If `oneOf` is used, the callback will be called when any of the matching events are emitted.  
-   * If `allOf` is used, the callback will be called after all of the matching events are emitted at least once, then any time any of them are emitted.  
-   * If both `oneOf` and `allOf` are used together, the callback will be called when any of the `oneOf` events are emitted AND all of the `allOf` events have been emitted at least once.  
-   * At least one of `oneOf` or `allOf` must be provided.  
-   *   
-   * @returns Returns a function that can be called to unsubscribe all listeners created by this call. Alternatively, pass an `AbortSignal` to all options objects to achieve the same effect or for finer control.
-   */
-  onMulti(options) {
-    const allUnsubs = [];
-    const unsubAll = () => {
-      for (const unsub of allUnsubs)
-        unsub();
-      allUnsubs.splice(0, allUnsubs.length);
-      this.eventUnsubscribes = this.eventUnsubscribes.filter((u) => !allUnsubs.includes(u));
-    };
-    for (const opts of Array.isArray(options) ? options : [options]) {
-      const optsWithDefaults = {
-        allOf: [],
-        oneOf: [],
-        once: false,
-        ...opts
-      };
-      const {
-        oneOf,
-        allOf,
-        once,
-        signal,
-        callback
-      } = optsWithDefaults;
-      if (signal == null ? void 0 : signal.aborted)
-        return unsubAll;
-      if (oneOf.length === 0 && allOf.length === 0)
-        throw new TypeError("NanoEmitter.onMulti(): Either `oneOf` or `allOf` or both must be provided in the options");
-      const curEvtUnsubs = [];
-      const checkUnsubAllEvt = (force = false) => {
-        if (!(signal == null ? void 0 : signal.aborted) && !force)
-          return;
-        for (const unsub of curEvtUnsubs)
-          unsub();
-        curEvtUnsubs.splice(0, curEvtUnsubs.length);
-        this.eventUnsubscribes = this.eventUnsubscribes.filter((u) => !curEvtUnsubs.includes(u));
-      };
-      const allOfEmitted = /* @__PURE__ */ new Set();
-      const allOfConditionMet = () => allOf.length === 0 || allOfEmitted.size === allOf.length;
-      for (const event of oneOf) {
-        const unsub = this.events.on(event, ((...args) => {
-          checkUnsubAllEvt();
-          if (allOfConditionMet()) {
-            callback(event, ...args);
-            if (once)
-              checkUnsubAllEvt(true);
-          }
-        }));
-        curEvtUnsubs.push(unsub);
-      }
-      for (const event of allOf) {
-        const unsub = this.events.on(event, ((...args) => {
-          checkUnsubAllEvt();
-          allOfEmitted.add(event);
-          if (allOfConditionMet() && (oneOf.length === 0 || oneOf.includes(event))) {
-            callback(event, ...args);
-            if (once)
-              checkUnsubAllEvt(true);
-          }
-        }));
-        curEvtUnsubs.push(unsub);
-      }
-      allUnsubs.push(() => checkUnsubAllEvt(true));
-    }
-    return unsubAll;
-  }
-  //#region emit
-  /**
-   * 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);
-      return true;
-    }
-    return false;
-  }
-  //#region unsubscribeAll
-  /** Unsubscribes all event listeners from this instance */
-  unsubscribeAll() {
-    for (const unsub of this.eventUnsubscribes)
-      unsub();
-    this.eventUnsubscribes = [];
-  }
-};
 var Debouncer = class extends NanoEmitter {
   /**
    * Creates a new debouncer with the specified timeout and edge type.
    * @param timeout Timeout in milliseconds between letting through calls - defaults to 200
    * @param type The edge type to use for the debouncer - see {@linkcode DebouncerType} for details or [the documentation for an explanation and diagram](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#debouncer) - defaults to "immediate"
    */
-  constructor(timeout = 200, type = "immediate") {
-    super();
+  constructor(timeout = 200, type = "immediate", nanoEmitterOptions) {
+    super(nanoEmitterOptions);
+    /** All registered listener functions and the time they were attached */
+    __publicField(this, "listeners", []);
+    /** The currently active timeout */
+    __publicField(this, "activeTimeout");
+    /** The latest queued call */
+    __publicField(this, "queuedCall");
     this.timeout = timeout;
     this.type = type;
   }
-  /** All registered listener functions and the time they were attached */
-  listeners = [];
-  /** The currently active timeout */
-  activeTimeout;
-  /** The latest queued call */
-  queuedCall;
   //#region listeners
   /** Adds a listener function that will be called on timeout */
   addListener(fn) {
@@ -1389,7 +1491,7 @@ var Debouncer = class extends NanoEmitter {
   //#region timeout
   /** Sets the timeout for the debouncer */
   setTimeout(timeout) {
-    this.emit("change", this.timeout = timeout, this.type);
+    this.events.emit("change", this.timeout = timeout, this.type);
   }
   /** Returns the current timeout */
   getTimeout() {
@@ -1402,7 +1504,7 @@ var Debouncer = class extends NanoEmitter {
   //#region type
   /** Sets the edge type for the debouncer */
   setType(type) {
-    this.emit("change", this.timeout, this.type = type);
+    this.events.emit("change", this.timeout, this.type = type);
   }
   /** Returns the current edge type */
   getType() {
@@ -1413,7 +1515,7 @@ var Debouncer = class extends NanoEmitter {
   call(...args) {
     const cl = (...a) => {
       this.queuedCall = void 0;
-      this.emit("call", ...a);
+      this.events.emit("call", ...a);
       this.listeners.forEach((l) => l.call(this, ...a));
     };
     const setRepeatTimeout = () => {
@@ -1446,14 +1548,30 @@ var Debouncer = class extends NanoEmitter {
     }
   }
 };
-function debounce(fn, timeout = 200, type = "immediate") {
-  const debouncer = new Debouncer(timeout, type);
+function debounce(fn, timeout = 200, type = "immediate", nanoEmitterOptions) {
+  const debouncer = new Debouncer(timeout, type, nanoEmitterOptions);
   debouncer.addListener(fn);
   const func = ((...args) => debouncer.call(...args));
   func.debouncer = debouncer;
   return func;
 }
 
+// lib/consts.ts
+var rawConsts = {
+  coreUtilsVersion: "3.4.0",
+  userUtilsVersion: "10.2.0"
+};
+function getConst(constKey, defaultVal) {
+  const val = rawConsts[constKey];
+  return val.match(/^#\{\{.+\}\}$/) ? defaultVal : val;
+}
+var versions = {
+  /** Semver version string of the bundled library CoreUtils. */
+  CoreUtils: getConst("coreUtilsVersion", "ERR:unknown"),
+  /** Semver version string of UserUtils. */
+  UserUtils: getConst("userUtilsVersion", "ERR:unknown")
+};
+
 // lib/Errors.ts
 var PlatformError = class extends DatedError {
   constructor(message, options) {
@@ -1466,7 +1584,7 @@ var PlatformError = class extends DatedError {
 function getUnsafeWindow() {
   try {
     return unsafeWindow;
-  } catch {
+  } catch (e) {
     return window;
   }
 }
@@ -1497,7 +1615,7 @@ function openInNewTab(href, background, additionalProps) {
   try {
     if (typeof window.GM === "object")
       GM.openInTab(href, background);
-  } catch {
+  } catch (e) {
     const openElem = document.createElement("a");
     Object.assign(openElem, {
       className: "userutils-open-in-new-tab",
@@ -1517,7 +1635,7 @@ function openInNewTab(href, background, additionalProps) {
     setTimeout(() => {
       try {
         openElem.remove();
-      } catch {
+      } catch (e2) {
       }
     }, 0);
   }
@@ -1533,8 +1651,8 @@ function interceptEvent(eventObject, eventName, predicate = () => true) {
   }
   (function(original) {
     eventObject.__proto__.addEventListener = function(...args) {
-      var _a2;
-      const origListener = typeof args[1] === "function" ? args[1] : ((_a2 = args[1]) == null ? void 0 : _a2.handleEvent) ?? (() => void 0);
+      var _a2, _b;
+      const origListener = typeof args[1] === "function" ? args[1] : (_b = (_a2 = args[1]) == null ? void 0 : _a2.handleEvent) != null ? _b : (() => void 0);
       args[1] = function(...a) {
         if (args[0] === eventName && predicate(Array.isArray(a) ? a[0] : a))
           return;
@@ -1577,8 +1695,8 @@ function observeElementProp(element, property, callback) {
   }
 }
 function getSiblingsFrame(refElement, siblingAmount, refElementAlignment = "center-top", includeRef = true) {
-  var _a;
-  const siblings = [...((_a = refElement.parentNode) == null ? void 0 : _a.childNodes) ?? []];
+  var _a, _b;
+  const siblings = [...(_b = (_a = refElement.parentNode) == null ? void 0 : _a.childNodes) != null ? _b : []];
   const elemSiblIdx = siblings.indexOf(refElement);
   if (elemSiblIdx === -1)
     throw new Error("Element doesn't have a parent node");
@@ -1599,13 +1717,13 @@ function getSiblingsFrame(refElement, siblingAmount, refElementAlignment = "cent
 }
 var ttPolicy;
 function setInnerHtmlUnsafe(element, html) {
-  var _a, _b;
+  var _a, _b, _c;
   if (!ttPolicy && typeof ((_a = window == null ? void 0 : window.trustedTypes) == null ? void 0 : _a.createPolicy) === "function") {
     ttPolicy = window.trustedTypes.createPolicy("_uu_set_innerhtml_unsafe", {
       createHTML: (unsafeHtml) => unsafeHtml
     });
   }
-  element.innerHTML = ((_b = ttPolicy == null ? void 0 : ttPolicy.createHTML) == null ? void 0 : _b.call(ttPolicy, html)) ?? html;
+  element.innerHTML = (_c = (_b = ttPolicy == null ? void 0 : ttPolicy.createHTML) == null ? void 0 : _b.call(ttPolicy, html)) != null ? _c : html;
   return element;
 }
 function probeElementStyle(probeStyle, element, hideOffscreen = true, parentElement = document.body) {
@@ -1798,20 +1916,20 @@ var defaultStrings = {
   closeDialogTooltip: "Click to close the dialog"
 };
 var Dialog = class _Dialog extends NanoEmitter {
-  /** Options passed to the dialog in the constructor */
-  options;
-  /** ID that gets added to child element IDs - has to be unique and conform to HTML ID naming rules! */
-  id;
-  /** Strings used in the dialog (used for translations) */
-  strings;
-  dialogOpen = false;
-  dialogMounted = false;
   constructor(options) {
     super();
+    /** Options passed to the dialog in the constructor */
+    __publicField(this, "options");
+    /** ID that gets added to child element IDs - has to be unique and conform to HTML ID naming rules! */
+    __publicField(this, "id");
+    /** Strings used in the dialog (used for translations) */
+    __publicField(this, "strings");
+    __publicField(this, "dialogOpen", false);
+    __publicField(this, "dialogMounted", false);
     const { strings, ...opts } = options;
     this.strings = {
       ...defaultStrings,
-      ...strings ?? {}
+      ...strings != null ? strings : {}
     };
     this.options = {
       closeOnBgClick: true,
@@ -1828,11 +1946,12 @@ var Dialog = class _Dialog extends NanoEmitter {
   //#region public
   /** Call after DOMContentLoaded to pre-render the dialog and invisibly mount it in the DOM */
   async mount() {
+    var _a;
     if (this.dialogMounted)
       return;
     this.dialogMounted = true;
     if (!document.querySelector("style.uu-dialog-css"))
-      addGlobalStyle(this.options.dialogCss ?? defaultDialogCss).classList.add("uu-dialog-css");
+      addGlobalStyle((_a = this.options.dialogCss) != null ? _a : defaultDialogCss).classList.add("uu-dialog-css");
     const bgElem = document.createElement("div");
     bgElem.id = `uu-${this.id}-dialog-bg`;
     bgElem.classList.add("uu-dialog-bg");
@@ -1900,7 +2019,7 @@ var Dialog = class _Dialog extends NanoEmitter {
   }
   /** Closes the dialog - prevents default action and immediate propagation of the passed event */
   close(e) {
-    var _a;
+    var _a, _b;
     e == null ? void 0 : e.preventDefault();
     e == null ? void 0 : e.stopImmediatePropagation();
     if (!this.isOpen())
@@ -1913,9 +2032,9 @@ var Dialog = class _Dialog extends NanoEmitter {
     dialogBg.style.display = "none";
     dialogBg.inert = true;
     openDialogs.splice(openDialogs.indexOf(this.id), 1);
-    currentDialogId = openDialogs[0] ?? null;
+    currentDialogId = (_a = openDialogs[0]) != null ? _a : null;
     if (currentDialogId)
-      (_a = document.querySelector(`#uu-${currentDialogId}-dialog-bg`)) == null ? void 0 : _a.removeAttribute("inert");
+      (_b = document.querySelector(`#uu-${currentDialogId}-dialog-bg`)) == null ? void 0 : _b.removeAttribute("inert");
     if (openDialogs.length === 0) {
       document.body.classList.add("uu-no-select");
       document.body.removeAttribute("inert");
@@ -1951,7 +2070,8 @@ var Dialog = class _Dialog extends NanoEmitter {
   }
   //#region protected
   getString(key) {
-    return this.strings[key] ?? defaultStrings[key];
+    var _a;
+    return (_a = this.strings[key]) != null ? _a : defaultStrings[key];
   }
   /** Called once to attach all generic event listeners */
   attachListeners(bgElem) {
@@ -1976,7 +2096,7 @@ var Dialog = class _Dialog extends NanoEmitter {
    * @param listenerOptions Provide a {@linkcode listenerOptions} object to configure the listeners
    */
   onInteraction(elem, listener, listenerOptions) {
-    const { preventDefault = true, stopPropagation = true, ...listenerOpts } = listenerOptions ?? {};
+    const { preventDefault = true, stopPropagation = true, ...listenerOpts } = listenerOptions != null ? listenerOptions : {};
     const interactionKeys = ["Enter", " ", "Space"];
     const proxListener = (e) => {
       if (e instanceof KeyboardEvent) {
@@ -2056,7 +2176,6 @@ var Dialog = class _Dialog extends NanoEmitter {
 
 // lib/GMStorageEngine.ts
 var GMStorageEngine = class extends DataStoreEngine {
-  options;
   /**
    * Creates an instance of `GMStorageEngine`.  
    *   
@@ -2065,6 +2184,7 @@ var GMStorageEngine = class extends DataStoreEngine {
    */
   constructor(options) {
     super(options == null ? void 0 : options.dataStoreOptions);
+    __publicField(this, "options");
     this.options = {
       ...options
     };
@@ -2120,25 +2240,26 @@ var GMStorageEngine = class extends DataStoreEngine {
 
 // lib/Mixins.ts
 var Mixins = class {
-  /** List of all registered mixins */
-  mixins = [];
-  /** Default configuration object for mixins */
-  defaultMixinCfg;
-  /** Whether the priorities should auto-increment if not specified */
-  autoIncPrioEnabled;
-  /** The current auto-increment priority counter */
-  autoIncPrioCounter = /* @__PURE__ */ new Map();
   /**
    * 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 = pureObj({
-      priority: config.defaultPriority ?? 0,
-      stopPropagation: config.defaultStopPropagation ?? false,
+      priority: (_a = config.defaultPriority) != null ? _a : 0,
+      stopPropagation: (_b = config.defaultStopPropagation) != null ? _b : false,
       signal: config.defaultSignal
     });
-    this.autoIncPrioEnabled = config.autoIncrementPriority ?? false;
+    this.autoIncPrioEnabled = (_c = config.autoIncrementPriority) != null ? _c : false;
   }
   //#region public
   /**
@@ -2203,10 +2324,11 @@ var Mixins = class {
   //#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 !== void 0)
       return void 0;
     if (!this.autoIncPrioEnabled)
-      return config.priority ?? this.defaultMixinCfg.priority;
+      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);
@@ -2227,13 +2349,13 @@ var Mixins = class {
 
 // lib/SelectorObserver.ts
 var SelectorObserver = class {
-  enabled = false;
-  baseElement;
-  observer;
-  observerOptions;
-  customOptions;
-  listenerMap;
   constructor(baseElement, options = {}) {
+    __publicField(this, "enabled", false);
+    __publicField(this, "baseElement");
+    __publicField(this, "observer");
+    __publicField(this, "observerOptions");
+    __publicField(this, "customOptions");
+    __publicField(this, "listenerMap");
     this.baseElement = baseElement;
     this.listenerMap = /* @__PURE__ */ new Map();
     const {
@@ -2249,10 +2371,10 @@ var SelectorObserver = class {
       ...observerOptions
     };
     this.customOptions = {
-      defaultDebounce: defaultDebounce ?? 0,
-      defaultDebounceType: defaultDebounceType ?? "immediate",
-      disableOnNoListeners: disableOnNoListeners ?? false,
-      enableOnAddListener: enableOnAddListener ?? true
+      defaultDebounce: defaultDebounce != null ? defaultDebounce : 0,
+      defaultDebounceType: defaultDebounceType != null ? defaultDebounceType : "immediate",
+      disableOnNoListeners: disableOnNoListeners != null ? disableOnNoListeners : false,
+      enableOnAddListener: enableOnAddListener != null ? enableOnAddListener : true
     };
     if (typeof this.customOptions.checkInterval !== "number") {
       this.observer = new MutationObserver(() => this.checkAllSelectors());
@@ -2403,9 +2525,9 @@ var valTransforms = [];
 var fallbackLang;
 function translate(language, key, ...trArgs) {
   if (typeof language !== "string")
-    language = fallbackLang ?? "";
+    language = fallbackLang != null ? fallbackLang : "";
   const trObj = trans[language];
-  if (typeof language !== "string" || language.length === 0 || typeof trObj !== "object" || trObj === null)
+  if (typeof language !== "string" || typeof trObj !== "object" || trObj === null)
     return fallbackLang && language !== fallbackLang ? translate(fallbackLang, key, ...trArgs) : key;
   const transformTrVal = (trKey, trValue) => {
     const tfs = valTransforms.filter(({ regex }) => new RegExp(regex).test(String(trValue)));
@@ -2457,15 +2579,18 @@ function trFor(language, key, ...args) {
 function useTr(language) {
   return (key, ...args) => translate(language, key, ...args);
 }
-function hasKey(language = fallbackLang ?? "", key) {
+function hasKey(language = fallbackLang != null ? fallbackLang : "", key) {
   return tr.for(language, key) !== key;
 }
 function addTranslations(language, translations) {
   trans[language] = JSON.parse(JSON.stringify(translations));
 }
-function getTranslations(language = fallbackLang ?? "") {
+function getTranslations(language = fallbackLang != null ? fallbackLang : "") {
   return trans[language];
 }
+function getAllTranslations(asCopy = true) {
+  return asCopy ? JSON.parse(JSON.stringify(trans)) : trans;
+}
 var deleteTranslations = (language) => {
   if (language in trans) {
     delete trans[language];
@@ -2496,51 +2621,55 @@ function deleteTransform(patternOrFn) {
   }
   return false;
 }
-var templateLiteralTransform = [
-  /\$\{([a-zA-Z0-9$_-]+)\}/gm,
-  ({ matches, trArgs, trValue }) => {
-    const patternStart = "${", patternEnd = "}", patternRegex = /\$\{.+\}/m;
-    let str = String(trValue);
-    const eachKeyInTrString = (keys) => keys.every((key) => trValue.includes(`${patternStart}${key}${patternEnd}`));
-    const namedMapping = () => {
-      if (!str.includes(patternStart) || typeof trArgs[0] === "undefined" || typeof trArgs[0] !== "object" || !eachKeyInTrString(Object.keys(trArgs[0] ?? {})))
-        return;
-      for (const match of matches) {
-        const repl = match[1] !== void 0 ? trArgs[0][match[1]] : void 0;
-        if (typeof repl !== "undefined")
-          str = str.replace(match[0], String(repl));
-      }
-    };
-    const positionalMapping = () => {
-      if (!patternRegex.test(str) || !trArgs[0])
-        return;
-      let matchNum = -1;
-      for (const match of matches) {
-        matchNum++;
-        if (typeof trArgs[matchNum] !== "undefined")
-          str = str.replace(match[0], String(trArgs[matchNum]));
-      }
-    };
-    let notStringifiable = false;
-    try {
-      String(trArgs[0]);
-    } catch {
-      notStringifiable = true;
+var commonKeyedTransform = ({ matches, trArgs, trValue }, patternRegex, quickMatchPattern) => {
+  let str = String(trValue);
+  const someMatchKeyInArgs = (obj) => matches.some((match) => match[1] !== void 0 && match[1] in obj);
+  const namedMapping = () => {
+    if (!str.includes(quickMatchPattern) || typeof trArgs[0] === "undefined" || typeof trArgs[0] !== "object" || !someMatchKeyInArgs(trArgs[0]))
+      return;
+    for (const match of matches) {
+      const repl = match[1] !== void 0 ? trArgs[0][match[1]] : void 0;
+      if (typeof repl !== "undefined")
+        str = str.replace(match[0], String(repl));
     }
-    const isArgsObject = trArgs[0] && typeof trArgs[0] === "object" && trArgs[0] !== null && (notStringifiable || String(trArgs[0]).startsWith("[object"));
-    if (isArgsObject && eachKeyInTrString(Object.keys(trArgs[0])))
-      namedMapping();
-    else
-      positionalMapping();
-    return str;
+  };
+  const positionalMapping = () => {
+    if (!patternRegex.test(str) || typeof trArgs[0] === "undefined")
+      return;
+    let matchNum = -1;
+    for (const match of matches) {
+      matchNum++;
+      if (typeof trArgs[matchNum] !== "undefined")
+        str = str.replace(match[0], String(trArgs[matchNum]));
+    }
+  };
+  let notStringifiable = false;
+  try {
+    void `${trArgs[0]}`;
+  } catch (e) {
+    notStringifiable = true;
   }
+  const isArgsObject = trArgs[0] && typeof trArgs[0] === "object" && trArgs[0] !== null && (notStringifiable || String(trArgs[0]).startsWith("[object"));
+  if (isArgsObject && someMatchKeyInArgs(trArgs[0]))
+    namedMapping();
+  else
+    positionalMapping();
+  return str;
+};
+var templateLiteralTransform = [
+  /\$\{([a-zA-Z0-9$_-]+)\}/gm,
+  (tfProps) => commonKeyedTransform(tfProps, /\$\{.+\}/m, "${")
+];
+var i18nTransform = [
+  /\{\{([a-zA-Z0-9$_-]+)\}\}/gm,
+  (tfProps) => commonKeyedTransform(tfProps, /\{\{.+\}\}/m, "{{")
 ];
 var percentTransform = [
   /%(\d+)/gm,
   ({ matches, trArgs, trValue }) => {
     let str = String(trValue);
     for (const match of matches) {
-      const repl = match[1] !== void 0 ? trArgs == null ? void 0 : trArgs[Number(match[1]) - 1] : void 0;
+      const repl = trArgs == null ? void 0 : trArgs[Number(match[1]) - 1];
       if (typeof repl !== "undefined")
         str = str.replace(match[0], String(repl));
     }
@@ -2550,17 +2679,84 @@ var percentTransform = [
 var tr = {
   for: (...params) => trFor(...params),
   use: (...params) => useTr(...params),
-  hasKey: (language = fallbackLang ?? "", key) => hasKey(language, key),
+  hasKey: (language = fallbackLang != null ? fallbackLang : "", key) => hasKey(language, key),
   addTranslations,
   getTranslations,
+  getAllTranslations,
   deleteTranslations,
   setFallbackLanguage,
   getFallbackLanguage,
   addTransform,
   deleteTransform,
+  /** Collection of predefined transform functions that can be added via {@linkcode tr.addTransform()} */
   transforms: {
+    /**
+     * This transform will replace placeholders matching `${key}` with the value of the passed argument(s).  
+     * The arguments can be passed in keyed object form or positionally via the spread operator:
+     * - Keyed: If the first argument is an object and `key` is found in it, the value will be used for the replacement.
+     * - Positional: If the first argument is not an object or has a `toString()` method that returns something that doesn't start with `[object`, the values will be positionally inserted in the order they were passed.
+     *   
+     * @example ```ts
+     * tr.addTranslations("en", {
+     *  "greeting": "Hello, ${user}!\nYou have ${notifs} notifications.",
+     * });
+     * tr.addTransform(tr.transforms.templateLiteral);
+     * 
+     * const t = tr.use("en");
+     * 
+     * // both calls return the same result:
+     * t("greeting", { user: "John", notifs: 5 }); // "Hello, John!\nYou have 5 notifications."
+     * t("greeting", "John", 5);                   // "Hello, John!\nYou have 5 notifications."
+     * 
+     * // when a key isn't found in the object, it will be left as-is:
+     * t("greeting", { user: "John" }); // "Hello, John!\nYou have ${notifs} notifications."
+     * ```
+     */
     templateLiteral: templateLiteralTransform,
+    /**
+     * This transform will replace placeholders matching `{{key}}` with the value of the passed argument(s).  
+     * This format is commonly used in i18n libraries. Note that advanced syntax is not supported, only simple key replacement.  
+     * The arguments can be passed in keyed object form or positionally via the spread operator:
+     * - Keyed: If the first argument is an object and `key` is found in it, the value will be used for the replacement.
+     * - Positional: If the first argument is not an object or has a `toString()` method that returns something that doesn't start with `[object`, the values will be positionally inserted in the order they were passed.
+     *   
+     * @example ```ts
+     * tr.addTranslations("en", {
+     *  "greeting": "Hello, {{user}}!\nYou have {{notifs}} notifications.",
+     * });
+     * tr.addTransform(tr.transforms.i18n);
+     * 
+     * const t = tr.use("en");
+     * 
+     * // both calls return the same result:
+     * t("greeting", { user: "Alice", notifs: 5 }); // "Hello, Alice!\nYou have 5 notifications."
+     * t("greeting", "Alice", 5);                   // "Hello, Alice!\nYou have 5 notifications."
+     * 
+     * // when a key isn't found in the object, it will be left as-is:
+     * t("greeting", { user: "Alice" }); // "Hello, Alice!\nYou have {{notifs}} notifications."
+     * ```
+     */
+    i18n: i18nTransform,
+    /**
+     * This transform will replace `%n` placeholders with the value of the passed arguments.  
+     * The `%n` placeholders are 1-indexed, meaning `%1` will be replaced by the first argument (index 0), `%2` by the second (index 1), and so on.  
+     * Objects will be stringified via `String()` before being inserted.  
+     *   
+     * @example ```ts
+     * tr.addTranslations("en", {
+     *  "greeting": "Hello, %1!\nYou have %2 notifications.",
+     * });
+     * tr.addTransform(tr.transforms.percent);
+     * 
+     * const t = tr.use("en");
+     * 
+     * // arguments are inserted in the order they're passed:
+     * t("greeting", "Bob", 5); // "Hello, Bob!\nYou have 5 notifications."
+     * 
+     * // when a value isn't found, the placeholder will be left as-is:
+     * t("greeting", "Bob"); // "Hello, Bob!\nYou have %2 notifications."
+     * ```
+     */
     percent: percentTransform
   }
 };
-//# sourceMappingURL=UserUtils.cjs.map