@sv443-network/coreutils 0.0.1 → 2.0.0

package/dist/CoreUtils.umd.js

@@ -83,6 +83,7 @@ __export(lib_exports, {
   joinArrayReadable: () => joinArrayReadable,
   lightenColor: () => lightenColor,
   mapRange: () => mapRange,
+  overflowVal: () => overflowVal,
   pauseFor: () => pauseFor,
   pureObj: () => pureObj,
   randRange: () => randRange,
@@ -92,6 +93,7 @@ __export(lib_exports, {
   randomizeArray: () => randomizeArray,
   rgbToHex: () => rgbToHex,
   roundFixed: () => roundFixed,
+  scheduleExit: () => scheduleExit,
   secsToTimeStr: () => secsToTimeStr,
   setImmediateInterval: () => setImmediateInterval,
   setImmediateTimeoutLoop: () => setImmediateTimeoutLoop,
@@ -145,6 +147,19 @@ function mapRange(value, range1min, range1max, range2min, range2max) {
     return value * (range2max / range1max);
   return (value - range1min) * ((range2max - range2min) / (range1max - range1min)) + range2min;
 }
+function overflowVal(value, minOrMax, max) {
+  const min = typeof max === "number" ? minOrMax : 0;
+  max = typeof max === "number" ? max : minOrMax;
+  if (min > max)
+    throw new RangeError(`Parameter "min" can't be bigger than "max"`);
+  if (isNaN(value) || isNaN(min) || isNaN(max) || !isFinite(value) || !isFinite(min) || !isFinite(max))
+    return NaN;
+  if (value >= min && value <= max)
+    return value;
+  const range = max - min + 1;
+  const wrappedValue = ((value - min) % range + range) % range + min;
+  return wrappedValue;
+}
 function randRange(...args) {
   let min, max, enhancedEntropy = false;
   if (typeof args[0] === "number" && typeof args[1] === "number")
@@ -240,10 +255,8 @@ function darkenColor(color, percent, upperCase = false) {
     return rgbToHex(r, g, b, a, color.startsWith("#"), upperCase);
   else if (color.startsWith("rgba"))
     return `rgba(${r}, ${g}, ${b}, ${a ?? NaN})`;
-  else if (color.startsWith("rgb"))
-    return `rgb(${r}, ${g}, ${b})`;
   else
-    throw new TypeError("Unsupported color format");
+    return `rgb(${r}, ${g}, ${b})`;
 }
 function hexToRgb(hex) {
   hex = (hex.startsWith("#") ? hex.slice(1) : hex).trim();
@@ -276,22 +289,22 @@ function atoab(str) {
   return Uint8Array.from(atob(str), (c) => c.charCodeAt(0));
 }
 async function compress(input, compressionFormat, outputType = "string") {
-  const byteArray = input instanceof ArrayBuffer ? input : new TextEncoder().encode((input == null ? void 0 : input.toString()) ?? String(input));
+  const byteArray = input instanceof Uint8Array ? input : new TextEncoder().encode((input == null ? void 0 : input.toString()) ?? String(input));
   const comp = new CompressionStream(compressionFormat);
   const writer = comp.writable.getWriter();
   writer.write(byteArray);
   writer.close();
-  const buf = await new Response(comp.readable).arrayBuffer();
-  return outputType === "arrayBuffer" ? buf : abtoa(buf);
+  const uintArr = new Uint8Array(await new Response(comp.readable).arrayBuffer());
+  return outputType === "arrayBuffer" ? uintArr : abtoa(uintArr);
 }
 async function decompress(input, compressionFormat, outputType = "string") {
-  const byteArray = input instanceof ArrayBuffer ? input : atoab((input == null ? void 0 : input.toString()) ?? String(input));
+  const byteArray = input instanceof Uint8Array ? input : atoab((input == null ? void 0 : input.toString()) ?? String(input));
   const decomp = new DecompressionStream(compressionFormat);
   const writer = decomp.writable.getWriter();
   writer.write(byteArray);
   writer.close();
-  const buf = await new Response(decomp.readable).arrayBuffer();
-  return outputType === "arrayBuffer" ? buf : new TextDecoder().decode(buf);
+  const uintArr = new Uint8Array(await new Response(decomp.readable).arrayBuffer());
+  return outputType === "arrayBuffer" ? uintArr : new TextDecoder().decode(uintArr);
 }
 async function computeHash(input, algorithm = "SHA-256") {
   let data;
@@ -400,6 +413,18 @@ function setImmediateTimeoutLoop(callback, interval, signal) {
   signal == null ? void 0 : signal.addEventListener("abort", cleanup);
   loop();
 }
+function scheduleExit(code = 0, timeout = 0) {
+  if (timeout < 0)
+    throw new TypeError("Timeout must be a non-negative number");
+  let exit;
+  if (typeof process !== "undefined" && "exit" in process)
+    exit = () => process.exit(code);
+  else if (typeof Deno !== "undefined" && "exit" in Deno)
+    exit = () => Deno.exit(code);
+  else
+    throw new Error("Cannot exit the process, no exit method available");
+  setTimeout(exit, timeout);
+}
 
 // lib/text.ts
 function autoPlural(term, num, pluralType = "auto") {
@@ -525,7 +550,14 @@ var DataStore = class {
   decodeData;
   compressionFormat = "deflate-raw";
   engine;
+  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.
+   */
   firstInit = true;
+  /** In-memory cached copy of the data that is saved in persistent storage used for synchronous read access. */
   cachedData;
   migrations;
   migrateIds = [];
@@ -533,13 +565,13 @@ var DataStore = class {
    * Creates an instance of DataStore to manage a sync & async database that is cached in memory and persistently saved across sessions.  
    * Supports migrating data from older versions to newer ones and populating the cache with default data if no persistent data is found.  
    *   
-   * - ⚠️ Requires the directives `@grant GM.getValue` and `@grant GM.setValue` if the storageMethod is left as the default of `"GM"`  
    * - ⚠️ Make sure to call {@linkcode loadData()} at least once after creating an instance, or the returned data will be the same as `options.defaultData`
    * 
    * @template TData The type of the data that is saved in persistent storage for the currently set format version (will be automatically inferred from `defaultData` if not provided) - **This has to be a JSON-compatible object!** (no undefined, circular references, etc.)
    * @param opts The options for this DataStore instance
    */
   constructor(opts) {
+    var _a;
     this.id = opts.id;
     this.formatVersion = opts.formatVersion;
     this.defaultData = opts.defaultData;
@@ -550,8 +582,9 @@ var DataStore = class {
     this.encodeData = opts.encodeData;
     this.decodeData = opts.decodeData;
     this.engine = typeof opts.engine === "function" ? opts.engine() : opts.engine;
+    this.options = opts;
     if (typeof opts.compressionFormat === "undefined")
-      opts.compressionFormat = "deflate-raw";
+      opts.compressionFormat = ((_a = opts.encodeData) == null ? void 0 : _a[0]) ?? "deflate-raw";
     if (typeof opts.compressionFormat === "string") {
       this.encodeData = [opts.compressionFormat, async (data) => await compress(data, opts.compressionFormat, "string")];
       this.decodeData = [opts.compressionFormat, async (data) => await compress(data, opts.compressionFormat, "string")];
@@ -586,9 +619,14 @@ var DataStore = class {
               promises.push(this.engine.setValue(newKey, value));
               promises.push(this.engine.deleteValue(oldKey));
             };
-            oldData && migrateFmt(`_uucfg-${this.id}`, `__ds-${this.id}-dat`, oldData);
-            !isNaN(oldVer) && migrateFmt(`_uucfgver-${this.id}`, `__ds-${this.id}-ver`, oldVer);
-            typeof oldEnc === "boolean" && migrateFmt(`_uucfgenc-${this.id}`, `__ds-${this.id}-enc`, oldEnc === true ? this.compressionFormat : null);
+            if (oldData)
+              migrateFmt(`_uucfg-${this.id}`, `__ds-${this.id}-dat`, oldData);
+            if (!isNaN(oldVer))
+              migrateFmt(`_uucfgver-${this.id}`, `__ds-${this.id}-ver`, oldVer);
+            if (typeof oldEnc === "boolean")
+              migrateFmt(`_uucfgenc-${this.id}`, `__ds-${this.id}-enf`, oldEnc === true ? Boolean(this.compressionFormat) || null : null);
+            else
+              promises.push(this.engine.setValue(`__ds-${this.id}-enf`, this.compressionFormat));
             await Promise.allSettled(promises);
           }
           await this.engine.setValue("__ds_fmt_ver", dsFmtVer);
@@ -598,21 +636,22 @@ var DataStore = class {
         await this.migrateId(this.migrateIds);
         this.migrateIds = [];
       }
-      const gmData = await this.engine.getValue(`__ds-${this.id}-dat`, JSON.stringify(this.defaultData));
-      let gmFmtVer = Number(await this.engine.getValue(`__ds-${this.id}-ver`, NaN));
-      if (typeof gmData !== "string") {
+      const storedData = await this.engine.getValue(`__ds-${this.id}-dat`, JSON.stringify(this.defaultData));
+      let storedFmtVer = Number(await this.engine.getValue(`__ds-${this.id}-ver`, NaN));
+      if (typeof storedData !== "string") {
         await this.saveDefaultData();
         return { ...this.defaultData };
       }
-      const isEncoded = Boolean(await this.engine.getValue(`__ds-${this.id}-enc`, false));
+      const encodingFmt = String(await this.engine.getValue(`__ds-${this.id}-enf`, null));
+      const isEncoded = encodingFmt !== "null" && encodingFmt !== "false";
       let saveData = false;
-      if (isNaN(gmFmtVer)) {
-        await this.engine.setValue(`__ds-${this.id}-ver`, gmFmtVer = this.formatVersion);
+      if (isNaN(storedFmtVer)) {
+        await this.engine.setValue(`__ds-${this.id}-ver`, storedFmtVer = this.formatVersion);
         saveData = true;
       }
-      let parsed = await this.engine.deserializeData(gmData, isEncoded);
-      if (gmFmtVer < this.formatVersion && this.migrations)
-        parsed = await this.runMigrations(parsed, gmFmtVer);
+      let parsed = await this.engine.deserializeData(storedData, isEncoded);
+      if (storedFmtVer < this.formatVersion && this.migrations)
+        parsed = await this.runMigrations(parsed, storedFmtVer);
       if (saveData)
         await this.setData(parsed);
       return this.cachedData = this.engine.deepCopy(parsed);
@@ -632,12 +671,11 @@ var DataStore = class {
   /** Saves the data synchronously to the in-memory cache and asynchronously to the persistent storage */
   setData(data) {
     this.cachedData = data;
-    const useEncoding = this.encodingEnabled();
     return new Promise(async (resolve) => {
       await Promise.allSettled([
-        this.engine.setValue(`__ds-${this.id}-dat`, await this.engine.serializeData(data, useEncoding)),
+        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}-enc`, useEncoding)
+        this.engine.setValue(`__ds-${this.id}-enf`, this.compressionFormat)
       ]);
       resolve();
     });
@@ -645,30 +683,29 @@ var DataStore = class {
   /** Saves the default data passed in the constructor synchronously to the in-memory cache and asynchronously to persistent storage */
   async saveDefaultData() {
     this.cachedData = this.defaultData;
-    const useEncoding = this.encodingEnabled();
     await Promise.allSettled([
-      this.engine.setValue(`__ds-${this.id}-dat`, await this.engine.serializeData(this.defaultData, useEncoding)),
+      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}-enc`, useEncoding)
+      this.engine.setValue(`__ds-${this.id}-enf`, this.compressionFormat)
     ]);
   }
   /**
-   * Call this method to clear all persistently stored data associated with this DataStore instance.  
+   * Call this method to clear all persistently stored data associated with this DataStore instance, including the storage container (if supported by the DataStoreEngine).  
    * The in-memory cache will be left untouched, so you may still access the data with {@linkcode getData()}  
-   * Calling {@linkcode loadData()} or {@linkcode setData()} after this method was called will recreate persistent storage with the cached or default data.  
-   *   
-   * - ⚠️ This requires the additional directive `@grant GM.deleteValue` if the storageMethod is left as the default of `"GM"`
+   * Calling {@linkcode loadData()} or {@linkcode setData()} after this method was called will recreate persistent storage with the cached or default data.
    */
   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}-enc`)
+      this.engine.deleteValue(`__ds-${this.id}-enf`)
     ]);
+    await ((_b = (_a = this.engine).deleteStorage) == null ? void 0 : _b.call(_a));
   }
   /** Returns whether encoding and decoding are enabled for this DataStore instance */
   encodingEnabled() {
-    return Boolean(this.encodeData && this.decodeData);
+    return Boolean(this.encodeData && this.decodeData) && this.compressionFormat !== null || Boolean(this.compressionFormat);
   }
   //#region migrations
   /**
@@ -702,7 +739,7 @@ var DataStore = class {
     await Promise.allSettled([
       this.engine.setValue(`__ds-${this.id}-dat`, await this.engine.serializeData(newData)),
       this.engine.setValue(`__ds-${this.id}-ver`, lastFmtVer),
-      this.engine.setValue(`__ds-${this.id}-enc`, this.encodingEnabled())
+      this.engine.setValue(`__ds-${this.id}-enf`, this.compressionFormat)
     ]);
     return this.cachedData = { ...newData };
   }
@@ -713,19 +750,24 @@ var DataStore = class {
   async migrateId(oldIds) {
     const ids = Array.isArray(oldIds) ? oldIds : [oldIds];
     await Promise.all(ids.map(async (id) => {
-      const data = await this.engine.getValue(`__ds-${id}-dat`, JSON.stringify(this.defaultData));
-      const fmtVer = Number(await this.engine.getValue(`__ds-${id}-ver`, NaN));
-      const isEncoded = Boolean(await this.engine.getValue(`__ds-${id}-enc`, false));
+      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)
+        ]);
+        return [d, Number(f), Boolean(e) && String(e) !== "null"];
+      })();
       if (data === void 0 || isNaN(fmtVer))
         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.engine.setValue(`__ds-${this.id}-ver`, fmtVer),
-        this.engine.setValue(`__ds-${this.id}-enc`, isEncoded),
+        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}-enc`)
+        this.engine.deleteValue(`__ds-${id}-enf`)
       ]);
     }));
   }
@@ -735,7 +777,11 @@ var DataStore = class {
 var DataStoreEngine = class {
   dataStoreOptions;
   // setDataStoreOptions() is called from inside the DataStore constructor to set this value
-  /** Called by DataStore on creation, to pass its options */
+  constructor(options) {
+    if (options)
+      this.dataStoreOptions = options;
+  }
+  /** Called by DataStore on creation, to pass its options. Only call this if you are using this instance standalone! */
   setDataStoreOptions(dataStoreOptions) {
     this.dataStoreOptions = dataStoreOptions;
   }
@@ -743,6 +789,7 @@ var DataStoreEngine = class {
   /** Serializes the given object to a string, optionally encoded with `options.encodeData` if {@linkcode useEncoding} is set to true */
   async serializeData(data, useEncoding) {
     var _a, _b, _c, _d, _e;
+    this.ensureDataStoreOptions();
     const stringData = JSON.stringify(data);
     if (!useEncoding || !((_a = this.dataStoreOptions) == null ? void 0 : _a.encodeData) || !((_b = this.dataStoreOptions) == null ? void 0 : _b.decodeData))
       return stringData;
@@ -754,12 +801,20 @@ var DataStoreEngine = class {
   /** Deserializes the given string to a JSON object, optionally decoded with `options.decodeData` if {@linkcode useEncoding} is set to true */
   async deserializeData(data, useEncoding) {
     var _a, _b, _c;
+    this.ensureDataStoreOptions();
     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);
   }
   //#region misc api
+  /** Throws an error if the DataStoreOptions are not set or invalid */
+  ensureDataStoreOptions() {
+    if (!this.dataStoreOptions)
+      throw new DatedError("DataStoreEngine must be initialized with DataStore options before use. If you are using this instance standalone, set them in the constructor or call `setDataStoreOptions()` with the DataStore options.");
+    if (!this.dataStoreOptions.id)
+      throw new DatedError("DataStoreEngine must be initialized with a valid DataStore ID");
+  }
   /**
    * Copies a JSON-compatible object and loses all its internal references in the process.  
    * Uses [`structuredClone()`](https://developer.mozilla.org/en-US/docs/Web/API/structuredClone) if available, otherwise falls back to `JSON.parse(JSON.stringify(obj))`.
@@ -778,11 +833,11 @@ var BrowserStorageEngine = class extends DataStoreEngine {
   /**
    * Creates an instance of `BrowserStorageEngine`.  
    *   
-   * ⚠️ Requires a DOM environment  
-   * ⚠️ Don't reuse this engine across multiple {@linkcode DataStore} instances
+   * - ⚠️ Requires a DOM environment  
+   * - ⚠️ Don't reuse engines across multiple {@linkcode DataStore} instances
    */
   constructor(options) {
-    super();
+    super(options == null ? void 0 : options.dataStoreOptions);
     this.options = {
       type: "localStorage",
       ...options
@@ -814,11 +869,11 @@ var FileStorageEngine = class extends DataStoreEngine {
   /**
    * Creates an instance of `FileStorageEngine`.  
    *   
-   * ⚠️ Requires Node.js or Deno with Node compatibility  
-   * ⚠️ Don't reuse this engine across multiple {@linkcode DataStore} instances
+   * - ⚠️ Requires Node.js or Deno with Node compatibility (v1.31+)  
+   * - ⚠️ Don't reuse engines across multiple {@linkcode DataStore} instances
    */
   constructor(options) {
-    super();
+    super(options == null ? void 0 : options.dataStoreOptions);
     this.options = {
       filePath: (id) => `.ds-${id}`,
       ...options
@@ -827,28 +882,32 @@ var FileStorageEngine = class extends DataStoreEngine {
   //#region json file
   /** Reads the file contents */
   async readFile() {
-    var _a, _b, _c;
+    var _a, _b, _c, _d;
+    this.ensureDataStoreOptions();
     try {
       if (!fs)
-        fs = (await import("node:fs/promises")).default;
+        fs = (_a = await import("fs/promises")) == null ? void 0 : _a.default;
+      if (!fs)
+        throw new DatedError("FileStorageEngine requires Node.js or Deno with Node compatibility (v1.31+)", { cause: new Error("'node:fs/promises' module not available") });
       const path = typeof this.options.filePath === "string" ? this.options.filePath : this.options.filePath(this.dataStoreOptions.id);
       const data = await fs.readFile(path, "utf-8");
-      if (!data)
-        return void 0;
-      return JSON.parse(await ((_c = (_b = (_a = this.dataStoreOptions) == null ? void 0 : _a.decodeData) == null ? void 0 : _b[1]) == null ? void 0 : _c.call(_b, data)) ?? data);
+      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 void 0;
     }
   }
   /** Overwrites the file contents */
   async writeFile(data) {
-    var _a, _b, _c;
+    var _a, _b, _c, _d;
+    this.ensureDataStoreOptions();
     try {
       if (!fs)
-        fs = (await import("node:fs/promises")).default;
+        fs = (_a = await import("fs/promises")) == null ? void 0 : _a.default;
+      if (!fs)
+        throw new DatedError("FileStorageEngine requires Node.js or Deno with Node compatibility (v1.31+)", { cause: new Error("'node:fs/promises' module not available") });
       const path = typeof this.options.filePath === "string" ? this.options.filePath : this.options.filePath(this.dataStoreOptions.id);
       await fs.mkdir(path.slice(0, path.lastIndexOf("/")), { recursive: true });
-      await fs.writeFile(path, await ((_c = (_b = (_a = this.dataStoreOptions) == null ? void 0 : _a.encodeData) == null ? void 0 : _b[1]) == null ? void 0 : _c.call(_b, JSON.stringify(data))) ?? JSON.stringify(data, void 0, 2), "utf-8");
+      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");
     } catch (err) {
       console.error("Error writing file:", err);
     }
@@ -882,6 +941,21 @@ var FileStorageEngine = class extends DataStoreEngine {
     delete data[name];
     await this.writeFile(data);
   }
+  /** Deletes the file that contains the data of this DataStore. */
+  async deleteStorage() {
+    var _a;
+    this.ensureDataStoreOptions();
+    try {
+      if (!fs)
+        fs = (_a = await import("fs/promises")) == null ? void 0 : _a.default;
+      if (!fs)
+        throw new DatedError("FileStorageEngine requires Node.js or Deno with Node compatibility (v1.31+)", { cause: new Error("'node:fs/promises' module not available") });
+      const path = typeof this.options.filePath === "string" ? this.options.filePath : this.options.filePath(this.dataStoreOptions.id);
+      await fs.unlink(path);
+    } catch (err) {
+      console.error("Error deleting file:", err);
+    }
+  }
 };
 
 // lib/DataStoreSerializer.ts
@@ -909,14 +983,16 @@ var DataStoreSerializer = class _DataStoreSerializer {
    * @param stringified Whether to return the result as a string or as an array of `SerializedDataStore` objects
    */
   async serializePartial(stores, useEncoding = true, stringified = true) {
+    var _a;
     const serData = [];
     for (const storeInst of this.stores.filter((s) => typeof stores === "function" ? stores(s.id) : stores.includes(s.id))) {
-      const data = useEncoding && storeInst.encodingEnabled() ? await storeInst.encodeData[1](JSON.stringify(storeInst.getData())) : JSON.stringify(storeInst.getData());
+      const encoded = Boolean(useEncoding && storeInst.encodingEnabled() && ((_a = storeInst.encodeData) == null ? void 0 : _a[1]));
+      const data = encoded ? await storeInst.encodeData[1](JSON.stringify(storeInst.getData())) : JSON.stringify(storeInst.getData());
       serData.push({
         id: storeInst.id,
         data,
         formatVersion: storeInst.formatVersion,
-        encoded: useEncoding && storeInst.encodingEnabled(),
+        encoded,
         checksum: this.options.addChecksum ? await this.calcChecksum(data) : void 0
       });
     }
@@ -1040,6 +1116,7 @@ var NanoEmitter = class {
       ...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 "_")
@@ -1073,6 +1150,7 @@ var NanoEmitter = class {
     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 "_")
@@ -1103,9 +1181,90 @@ var NanoEmitter = class {
       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 aborted 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.  
+   * You may use a combination of the above two options, but at least one of them 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;
+      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));
+      };
+      for (const event of oneOf) {
+        const unsub = this.events.on(event, (...args) => {
+          checkUnsubAllEvt();
+          callback(event, ...args);
+          if (once)
+            checkUnsubAllEvt(true);
+        });
+        curEvtUnsubs.push(unsub);
+      }
+      const allOfEmitted = /* @__PURE__ */ new Set();
+      const checkAllOf = (event, ...args) => {
+        checkUnsubAllEvt();
+        allOfEmitted.add(event);
+        if (allOfEmitted.size === allOf.length) {
+          callback(event, ...args);
+          if (once)
+            checkUnsubAllEvt(true);
+        }
+      };
+      for (const event of allOf) {
+        const unsub = this.events.on(event, (...args) => {
+          checkUnsubAllEvt();
+          checkAllOf(event, ...args);
+        });
+        curEvtUnsubs.push(unsub);
+      }
+      if (oneOf.length === 0 && allOf.length === 0)
+        throw new TypeError("NanoEmitter.onMulti(): Either `oneOf` or `allOf` or both must be provided in the options");
+      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!
+   * - ⚠️ 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
@@ -1117,6 +1276,7 @@ var NanoEmitter = class {
     }
     return false;
   }
+  //#region unsubscribeAll
   /** Unsubscribes all event listeners from this instance */
   unsubscribeAll() {
     for (const unsub of this.eventUnsubscribes)

package/dist/lib/DataStore.d.ts

@@ -34,7 +34,7 @@ export type DataStoreOptions<TData extends DataStoreData> = Prettify<{
      * The engine middleware to use for persistent storage.  
      * Create an instance of {@linkcode FileStorageEngine} (Node.js), {@linkcode BrowserStorageEngine} (DOM) or your own engine class that extends {@linkcode DataStoreEngine} and pass it here.  
      *  
-     * ⚠️ Don't reuse the same engine instance for multiple DataStores, unless it explicitly supports it!  
+     * - ⚠️ Don't reuse the same engine instance for multiple DataStores, unless it explicitly supports it!  
      */
     engine: (() => DataStoreEngine<TData>) | DataStoreEngine<TData>;
     /**
@@ -57,26 +57,30 @@ export type DataStoreOptions<TData extends DataStoreData> = Prettify<{
     decodeData?: never;
     /**
      * The format to use for compressing the data. Defaults to `deflate-raw`. Explicitly set to `null` to store data uncompressed.  
-     * ⚠️ Use either this, or `encodeData` and `decodeData`, but not all three at a time!  
+     * - ⚠️ Use either this property, or both `encodeData` and `decodeData`, but not all three!  
      */
     compressionFormat?: CompressionFormat | null;
 } | {
     /**
      * Tuple of a compression format identifier and a function to use to encode the data prior to saving it in persistent storage.  
-     * If this is specified, `compressionFormat` can't be used. Also make sure to declare {@linkcode decodeData()} as well.  
+     * Set the identifier to `null` or `"identity"` to indicate that no traditional compression is used.  
+     *  
+     * - ⚠️ If this is specified, `compressionFormat` can't be used. Also make sure to declare {@linkcode decodeData()} as well.  
      *  
      * You can make use of the [`compress()` function](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#function-compress) here to make the data use up less space at the cost of a little bit of performance.  
      * @param data The input data as a serialized object (JSON string)  
      */
-    encodeData: [format: LooseUnion<CompressionFormat>, encode: (data: string) => string | Promise<string>];
+    encodeData: [format: LooseUnion<CompressionFormat> | null, encode: (data: string) => string | Promise<string>];
     /**
      * Tuple of a compression format identifier and a function to use to decode the data after reading it from persistent storage.  
-     * If this is specified, `compressionFormat` can't be used. Also make sure to declare {@linkcode encodeData()} as well.  
+     * Set the identifier to `null` or `"identity"` to indicate that no traditional compression is used.  
+     *  
+     * - ⚠️ If this is specified, `compressionFormat` can't be used. Also make sure to declare {@linkcode encodeData()} as well.  
      *  
      * You can make use of the [`decompress()` function](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#function-decompress) here to make the data use up less space at the cost of a little bit of performance.  
      * @returns The resulting data as a valid serialized object (JSON string)  
      */
-    decodeData: [format: LooseUnion<CompressionFormat>, decode: (data: string) => string | Promise<string>];
+    decodeData: [format: LooseUnion<CompressionFormat> | null, decode: (data: string) => string | Promise<string>];
     compressionFormat?: never;
 })>;
 /** Generic type that represents the serializable data structure saved in a {@linkcode DataStore} instance. */
@@ -100,9 +104,16 @@ export declare class DataStore<TData extends DataStoreData> {
     readonly defaultData: TData;
     readonly encodeData: DataStoreOptions<TData>["encodeData"];
     readonly decodeData: DataStoreOptions<TData>["decodeData"];
-    readonly compressionFormat = "deflate-raw";
+    readonly compressionFormat: Exclude<DataStoreOptions<TData>["compressionFormat"], undefined>;
     readonly engine: DataStoreEngine<TData>;
+    options: DataStoreOptions<TData>;
+    /**
+     * 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.  
+     */
     protected firstInit: boolean;
+    /** In-memory cached copy of the data that is saved in persistent storage used for synchronous read access. */
     private cachedData;
     private migrations?;
     private migrateIds;
@@ -110,7 +121,6 @@ export declare class DataStore<TData extends DataStoreData> {
      * Creates an instance of DataStore to manage a sync & async database that is cached in memory and persistently saved across sessions.  
      * Supports migrating data from older versions to newer ones and populating the cache with default data if no persistent data is found.  
      *  
-     * - ⚠️ Requires the directives `@grant GM.getValue` and `@grant GM.setValue` if the storageMethod is left as the default of `"GM"`  
      * - ⚠️ Make sure to call {@linkcode loadData()} at least once after creating an instance, or the returned data will be the same as `options.defaultData`  
      *  
      * @template TData The type of the data that is saved in persistent storage for the currently set format version (will be automatically inferred from `defaultData` if not provided) - **This has to be a JSON-compatible object!** (no undefined, circular references, etc.)  
@@ -133,11 +143,9 @@ export declare class DataStore<TData extends DataStoreData> {
     /** Saves the default data passed in the constructor synchronously to the in-memory cache and asynchronously to persistent storage */
     saveDefaultData(): Promise<void>;
     /**
-     * Call this method to clear all persistently stored data associated with this DataStore instance.  
+     * Call this method to clear all persistently stored data associated with this DataStore instance, including the storage container (if supported by the DataStoreEngine).  
      * The in-memory cache will be left untouched, so you may still access the data with {@linkcode getData()}  
      * Calling {@linkcode loadData()} or {@linkcode setData()} after this method was called will recreate persistent storage with the cached or default data.  
-     *  
-     * - ⚠️ This requires the additional directive `@grant GM.deleteValue` if the storageMethod is left as the default of `"GM"`  
      */
     deleteData(): Promise<void>;
     /** Returns whether encoding and decoding are enabled for this DataStore instance */