@sv443-network/userutils 10.0.5 → 10.1.0

package/dist/UserUtils.umd.js

@@ -179,11 +179,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.4/node_modules/@sv443-network/coreutils/dist/CoreUtils.mjs
+// node_modules/.pnpm/@sv443-network+coreutils@3.3.0/node_modules/@sv443-network/coreutils/dist/CoreUtils.mjs
 function bitSetHas(bitSet, checkVal) {
   return (bitSet & checkVal) === checkVal;
 }
@@ -649,8 +650,202 @@ function truncStr(input, length, endStr = "...") {
   const finalStr = str.length > length ? str.substring(0, length - endStr.length) + endStr : str;
   return finalStr.length > length ? finalStr.substring(0, length) : finalStr;
 }
+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 = __spreadValues({
+      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 = __spreadValues({
+        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 dsFmtVer = 1;
-var DataStore = class {
+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.  
@@ -662,14 +857,17 @@ 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", true);
+    __publicField(this, "memoryCache");
     __publicField(this, "engine");
+    __publicField(this, "keyPrefix");
     __publicField(this, "options");
     /**
      * Whether all first-init checks should be done.  
@@ -681,21 +879,21 @@ var DataStore = class {
     __publicField(this, "cachedData");
     __publicField(this, "migrations");
     __publicField(this, "migrateIds", []);
-    var _a, _b;
     this.id = opts.id;
     this.formatVersion = opts.formatVersion;
     this.defaultData = opts.defaultData;
-    this.memoryCache = Boolean((_a = opts.memoryCache) != null ? _a : 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 = (_b = opts.encodeData[0]) != null ? _b : null;
+      this.compressionFormat = (_c = opts.encodeData[0]) != null ? _c : null;
     } else if (opts.compressionFormat === null) {
       this.encodeData = void 0;
       this.decodeData = void 0;
@@ -738,13 +936,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) ? (_a = this.compressionFormat) != null ? _a : 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}`));
             }
             yield Promise.allSettled(promises);
@@ -756,31 +954,27 @@ var DataStore = class {
           yield this.migrateId(this.migrateIds);
           this.migrateIds = [];
         }
-        const storedDataRaw = yield this.engine.getValue(`__ds-${this.id}-dat`, null);
-        let storedFmtVer = Number(yield this.engine.getValue(`__ds-${this.id}-ver`, NaN));
-        if (typeof storedDataRaw !== "string") {
-          yield this.saveDefaultData();
-          return this.engine.deepCopy(this.defaultData);
+        const storedDataRaw = yield this.engine.getValue(`${this.keyPrefix}${this.id}-dat`, null);
+        const storedFmtVer = Number(yield this.engine.getValue(`${this.keyPrefix}${this.id}-ver`, NaN));
+        if (typeof storedDataRaw !== "string" && typeof storedDataRaw !== "object" || storedDataRaw === null || isNaN(storedFmtVer)) {
+          yield this.saveDefaultData(false);
+          const data = this.engine.deepCopy(this.defaultData);
+          this.events.emit("loadData", data);
+          return data;
         }
         const storedData = storedDataRaw != null ? storedDataRaw : JSON.stringify(this.defaultData);
-        const encodingFmt = String(yield this.engine.getValue(`__ds-${this.id}-enf`, null));
+        const encodingFmt = String(yield 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)) {
-          yield this.engine.setValue(`__ds-${this.id}-ver`, storedFmtVer = this.formatVersion);
-          saveData = true;
-        }
-        let parsed = yield this.engine.deserializeData(storedData, isEncoded);
+        let parsed = typeof storedData === "string" ? yield this.engine.deserializeData(storedData, isEncoded) : storedData;
         if (storedFmtVer < this.formatVersion && this.migrations)
           parsed = yield this.runMigrations(parsed, storedFmtVer);
-        if (saveData)
-          yield 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);
         yield this.saveDefaultData();
         return this.defaultData;
       }
@@ -790,7 +984,7 @@ 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).  
-   * ⚠️ If `memoryCache` was set to `false` in the constructor options, this method will throw an error.
+   * ⚠️ Only available when `memoryCache` is `true` (default). When set to `false`, this produces a type and runtime error - use {@linkcode loadData()} instead.
    */
   getData() {
     if (!this.memoryCache)
@@ -800,28 +994,48 @@ 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((resolve) => __async(this, null, function* () {
-      yield Promise.allSettled([
-        this.engine.setValue(`__ds-${this.id}-dat`, yield 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 = yield Promise.allSettled([
+        this.engine.setValue(`${this.keyPrefix}${this.id}-dat`, yield 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 */
-  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()})
+   */
+  saveDefaultData(emitEvent = true) {
     return __async(this, null, function* () {
       if (this.memoryCache)
         this.cachedData = this.defaultData;
-      yield Promise.allSettled([
-        this.engine.setValue(`__ds-${this.id}-dat`, yield 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 = yield Promise.allSettled([
+        this.engine.setValue(`${this.keyPrefix}${this.id}-dat`, yield 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
@@ -834,11 +1048,12 @@ var DataStore = class {
     return __async(this, null, function* () {
       var _a, _b;
       yield 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`)
       ]);
       yield (_b = (_a = this.engine).deleteStorage) == null ? void 0 : _b.call(_a);
+      this.events.emit("deleteData");
     });
   }
   //#region encodingEnabled
@@ -861,30 +1076,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 ? yield 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;
             yield this.saveDefaultData();
-            return this.getData();
+            return this.engine.deepCopy(this.defaultData);
           }
         }
       }
       yield Promise.allSettled([
-        this.engine.setValue(`__ds-${this.id}-dat`, yield 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`, yield 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
@@ -898,9 +1118,9 @@ var DataStore = class {
       yield Promise.all(ids.map((id) => __async(this, null, function* () {
         const [data, fmtVer, isEncoded] = yield (() => __async(this, null, function* () {
           const [d, f, e] = yield 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"];
         }))();
@@ -908,13 +1128,14 @@ var DataStore = class {
           return;
         const parsed = yield this.engine.deserializeData(data, isEncoded);
         yield Promise.allSettled([
-          this.engine.setValue(`__ds-${this.id}-dat`, yield 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`, yield 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);
       })));
     });
   }
@@ -1046,7 +1267,7 @@ var FileStorageEngine = class extends DataStoreEngine {
           fs = (_a = yield 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 = yield fs.readFile(path, "utf-8");
         return data ? JSON.parse((_a2 = yield (_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) {
@@ -1065,7 +1286,7 @@ var FileStorageEngine = class extends DataStoreEngine {
           fs = (_a = yield 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);
         yield fs.mkdir(path.slice(0, path.lastIndexOf(path.includes("/") ? "/" : "\\")), { recursive: true });
         yield fs.writeFile(path, (_a2 = yield (_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) {
@@ -1083,8 +1304,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;
     });
   }
@@ -1095,7 +1329,18 @@ var FileStorageEngine = class extends DataStoreEngine {
         let data = yield 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;
         yield this.writeFile(data);
       })).catch((err) => {
         console.error("Error in setValue:", err);
@@ -1132,7 +1377,7 @@ var FileStorageEngine = class extends DataStoreEngine {
           fs = (_a = yield 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 yield fs.unlink(path);
       } catch (err) {
         console.error("Error deleting file:", err);
@@ -1295,200 +1540,6 @@ 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) {
-    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 = __spreadValues({
-      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 = __spreadValues({
-        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.
@@ -1592,6 +1643,22 @@ function debounce(fn, timeout = 200, type = "immediate") {
   return func;
 }
 
+// lib/consts.ts
+var rawConsts = {
+  coreUtilsVersion: "3.3.0",
+  userUtilsVersion: "10.1.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) {
@@ -2558,7 +2625,7 @@ function translate(language, key, ...trArgs) {
   if (typeof language !== "string")
     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)));
@@ -2619,6 +2686,9 @@ function addTranslations(language, translations) {
 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];
@@ -2649,52 +2719,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 = () => {
-      var _a;
-      if (!str.includes(patternStart) || typeof trArgs[0] === "undefined" || typeof trArgs[0] !== "object" || !eachKeyInTrString(Object.keys((_a = trArgs[0]) != null ? _a : {})))
-        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 (e) {
-      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));
     }
@@ -2707,13 +2780,81 @@ var tr = {
   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
   }
 };
@@ -2740,5 +2881,3 @@ if (typeof module.exports == "object" && typeof exports == "object") {
 
 
 
-
-//# sourceMappingURL=UserUtils.umd.js.map