@sv443-network/coreutils 3.2.0 → 3.3.0

package/dist/CoreUtils.mjs

@@ -463,9 +463,208 @@ function truncStr(input, length, endStr = "...") {
   return finalStr.length > length ? finalStr.substring(0, length) : finalStr;
 }
 
+// node_modules/.pnpm/nanoevents@9.1.0/node_modules/nanoevents/index.js
+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);
+    };
+  }
+});
+
+// lib/NanoEmitter.ts
+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 = [];
+  }
+};
+
 // lib/DataStore.ts
 var dsFmtVer = 1;
-var DataStore = class {
+var DataStore = class extends NanoEmitter {
   id;
   formatVersion;
   defaultData;
@@ -497,6 +696,7 @@ var DataStore = class {
    * @param opts The options for this DataStore instance
    */
   constructor(opts) {
+    super(opts.nanoEmitterOptions);
     this.id = opts.id;
     this.formatVersion = opts.formatVersion;
     this.defaultData = opts.defaultData;
@@ -567,30 +767,26 @@ var DataStore = class {
         this.migrateIds = [];
       }
       const storedDataRaw = await this.engine.getValue(`${this.keyPrefix}${this.id}-dat`, null);
-      let storedFmtVer = Number(await this.engine.getValue(`${this.keyPrefix}${this.id}-ver`, NaN));
+      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();
-        return this.engine.deepCopy(this.defaultData);
+        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(`${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(`${this.keyPrefix}${this.id}-ver`, storedFmtVer = this.formatVersion);
-        saveData = true;
-      }
       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;
     }
@@ -609,27 +805,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([
+      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([
+    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
   /**
@@ -645,6 +861,7 @@ var DataStore = class {
       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 */
@@ -665,16 +882,22 @@ 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);
         }
@@ -685,10 +908,9 @@ var DataStore = class {
       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
   /**
@@ -717,6 +939,7 @@ var DataStore = class {
         this.engine.deleteValue(`${this.keyPrefix}${id}-ver`),
         this.engine.deleteValue(`${this.keyPrefix}${id}-enf`)
       ]);
+      this.events.emit("migrateId", id, this.id);
     }));
   }
 };
@@ -1085,205 +1308,6 @@ Has: ${checksum}`);
   }
 };
 
-// node_modules/.pnpm/nanoevents@9.1.0/node_modules/nanoevents/index.js
-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);
-    };
-  }
-});
-
-// lib/NanoEmitter.ts
-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 = [];
-  }
-};
-
 // lib/Debouncer.ts
 var Debouncer = class extends NanoEmitter {
   /**