@sv443-network/coreutils 2.0.3 → 3.0.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # @sv443-network/coreutils
 
+## 3.0.0
+
+### Major Changes
+
+- 7718855: **Changed `DataStoreEngine` instances to allow storing original values instead of only strings.**
+
+  The previous behavior of explicit serialization was prone to errors and made it hard to implement certain features, such as data migration from UserUtils.
+  If you have created a custom `DataStoreEngine`, please ensure it supports storing and retrieving all values supported by JSON, i.e. `string`, `number`, `boolean`, `null`, `object` and `array`. Values like `undefined`, `Symbol`, `Function` etc. are still not supported and will lead to errors.
+
+- 46570f4: **`NanoEmitter` multi methods' `oneOf` and `allOf` properties now behave like an AND condition instead of an OR.**
+
+### Minor Changes
+
+- 1124d2e: Added DataStoreSerializer property `remapIds` to support deserializing from stores with outdated IDs.
+- 240f83e: Added DataStore prop `memoryCache` to turn off the memory cache in data-intensive, non-latency-sensitive scenarios.
+- 7718855: Made DataStore able to migrate data from [UserUtils <=v9 DataStore](https://github.com/Sv443-Network/UserUtils/blob/v9.4.4/docs.md#datastore) instances.
+
+  In order to trigger the migration:
+
+  1. Switch the DataStore import from UserUtils to CoreUtils and keep the same DataStore ID.
+  2. Update the options object in the DataStore constructor. (You may also want to refer to the [new DataStore documentation](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#class-datastore).)
+     - The constructor now needs an `engine` property that is an instance of a [UserUtils `GMStorageEngine`.](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#class-gmstorageengine)
+     - Encoding with `deflate-raw` will now be enabled by default. Set `compressionFormat: null` to disable compression if it wasn't enabled in the UserUtils DataStore.
+     - Added shorthand property `compressionFormat` as an alternative to the properties `encodeData` and `decodeData`
+     - `encodeData` and `decodeData` are now a tuple array, consisting of a format identifier string and the function which was previously the only value of these properties.
+  3. The next call to `loadData()` will then migrate the data automatically and transparently.
+
+### Patch Changes
+
+- 99a797f: `secsToTimeStr()` now supports negative time and will only throw if the number is `NaN` or not finite.
+- 38e7813: Implemented `DatedError`, `CustomError` and new classes `ScriptContextError` and `NetworkError` throughout the library.
+
 ## 2.0.3
 
 ### Patch Changes

package/README.md

@@ -1,7 +1,7 @@
 <div align="center" style="text-align: center;">
 
 # CoreUtils
-Cross-platform, general-purpose, JavaScript core library for Node, Deno and the browser.  
+Cross-platform, general-purpose, JavaScript core library for Node, Deno and the browser with tons of various utility functions and classes.  
 Intended to be used in conjunction with [`@sv443-network/userutils`](https://github.com/Sv443-Network/UserUtils) and [`@sv443-network/djsutils`](https://github.com/Sv443-Network/DJSUtils), but can be used independently as well.
 
 ### [Documentation](./docs.md#readme) &bull; [Features](#features) &bull; [Installation](#installation) &bull; [License](./LICENSE.txt) &bull; [Changelog](./CHANGELOG.md)
@@ -56,6 +56,7 @@ Intended to be used in conjunction with [`@sv443-network/userutils`](https://git
 - [**Errors:**](./docs.md#errors)
   - 🟧 [`class DatedError`](./docs.md#class-datederror) - Base error class with a `date` property
     - 🟧 [`class ChecksumMismatchError`](./docs.md#class-checksummismatcherror) - Error thrown when two checksums don't match
+    - 🟧 [`class CustomError`](./docs.md#class-customerror) - Custom error with a configurable name for one-off situations
     - 🟧 [`class MigrationError`](./docs.md#class-migrationerror) - Error thrown in a failed data migration
     - 🟧 [`class ValidationError`](./docs.md#class-validationerror) - Error while validating data
 - [**Math:**](./docs.md#math)
@@ -90,7 +91,7 @@ Intended to be used in conjunction with [`@sv443-network/userutils`](https://git
   - 🟣 [`function autoPlural()`](./docs.md#function-autoplural) - Turns the given term into its plural form, depending on the given number or list length
   - 🟣 [`function capitalize()`](./docs.md#function-capitalize) - Capitalizes the first letter of the given string
   - 🟣 [`function createProgressBar()`](./docs.md#function-createprogressbar) - Creates a progress bar string with the given percentage and length
-    - 🟩 [`const defaultPbChars`](./docs.md#const-defaultpbchars) - Default characters for the progress bar
+    - ⬜ [`const defaultPbChars`](./docs.md#const-defaultpbchars) - Default characters for the progress bar
     - 🔷 [`type ProgressBarChars`](./docs.md#type-progressbarchars) - Type for the progress bar characters object
   - 🟣 [`function joinArrayReadable()`](./docs.md#function-joinarrayreadable) - Joins the given array into a string, using the given separators and last separator
   - 🟣 [`function secsToTimeStr()`](./docs.md#function-secstotimestr) - Turns the given number of seconds into a string in the format `(hh:)mm:ss` with intelligent zero-padding
@@ -125,7 +126,7 @@ Intended to be used in conjunction with [`@sv443-network/userutils`](https://git
 > 🟣 = function  
 > 🟧 = class  
 > 🔷 = type  
-> 🟩 = const
+> ⬜ = const
 
 <br>
 

package/dist/CoreUtils.cjs

@@ -32,6 +32,7 @@ var lib_exports = {};
 __export(lib_exports, {
   BrowserStorageEngine: () => BrowserStorageEngine,
   ChecksumMismatchError: () => ChecksumMismatchError,
+  CustomError: () => CustomError,
   DataStore: () => DataStore,
   DataStoreEngine: () => DataStoreEngine,
   DataStoreSerializer: () => DataStoreSerializer,
@@ -40,6 +41,8 @@ __export(lib_exports, {
   FileStorageEngine: () => FileStorageEngine,
   MigrationError: () => MigrationError,
   NanoEmitter: () => NanoEmitter,
+  NetworkError: () => NetworkError,
+  ScriptContextError: () => ScriptContextError,
   ValidationError: () => ValidationError,
   abtoa: () => abtoa,
   atoab: () => atoab,
@@ -59,6 +62,7 @@ __export(lib_exports, {
   digitCount: () => digitCount,
   fetchAdvanced: () => fetchAdvanced,
   formatNumber: () => formatNumber,
+  getCallStack: () => getCallStack,
   getListLength: () => getListLength,
   hexToRgb: () => hexToRgb,
   insertValues: () => insertValues,
@@ -175,7 +179,7 @@ function roundFixed(num, fractionDigits) {
   const scale = 10 ** fractionDigits;
   return Math.round(num * scale) / scale;
 }
-function valsWithin(a, b, dec = 10, withinRange = 0.5) {
+function valsWithin(a, b, dec = 1, withinRange = 0.5) {
   return Math.abs(roundFixed(a, dec) - roundFixed(b, dec)) <= withinRange;
 }
 
@@ -325,6 +329,52 @@ function randomId(length = 16, radix = 16, enhancedEntropy = false, randomCase =
   return arr.map((v) => caseArr[randRange(0, caseArr.length - 1, enhancedEntropy)] === 1 ? v.toUpperCase() : v).join("");
 }
 
+// lib/Errors.ts
+var DatedError = class extends Error {
+  date;
+  constructor(message, options) {
+    super(message, options);
+    this.name = this.constructor.name;
+    this.date = /* @__PURE__ */ new Date();
+  }
+};
+var ChecksumMismatchError = class extends DatedError {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "ChecksumMismatchError";
+  }
+};
+var CustomError = class extends DatedError {
+  constructor(name, message, options) {
+    super(message, options);
+    this.name = name;
+  }
+};
+var MigrationError = class extends DatedError {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "MigrationError";
+  }
+};
+var ValidationError = class extends DatedError {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "ValidationError";
+  }
+};
+var ScriptContextError = class extends DatedError {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "ScriptContextError";
+  }
+};
+var NetworkError = class extends DatedError {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "NetworkError";
+  }
+};
+
 // lib/misc.ts
 async function consumeGen(valGen) {
   return await (typeof valGen === "function" ? valGen() : valGen);
@@ -353,7 +403,7 @@ async function fetchAdvanced(input, options = {}) {
     return res;
   } catch (err) {
     typeof id !== "undefined" && clearTimeout(id);
-    throw new Error("Error while calling fetch", { cause: err });
+    throw new NetworkError("Error while calling fetch", { cause: err });
   }
 }
 function getListLength(listLike, zeroOnInvalid = true) {
@@ -364,7 +414,7 @@ function pauseFor(time, signal, rejectOnAbort = false) {
     const timeout = setTimeout(() => res(), time);
     signal == null ? void 0 : signal.addEventListener("abort", () => {
       clearTimeout(timeout);
-      rejectOnAbort ? rej(new Error("The pause was aborted")) : res();
+      rejectOnAbort ? rej(new CustomError("AbortError", "The pause was aborted")) : res();
     });
   });
 }
@@ -399,14 +449,24 @@ 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)
+  if (typeof process !== "undefined" && "exit" in process && typeof process.exit === "function")
     exit = () => process.exit(code);
-  else if (typeof Deno !== "undefined" && "exit" in Deno)
+  else if (typeof Deno !== "undefined" && "exit" in Deno && typeof Deno.exit === "function")
     exit = () => Deno.exit(code);
   else
-    throw new Error("Cannot exit the process, no exit method available");
+    throw new ScriptContextError("Cannot exit the process, no exit method available");
   setTimeout(exit, timeout);
 }
+function getCallStack(asArray, lines = Infinity) {
+  if (typeof lines !== "number" || isNaN(lines) || lines < 0)
+    throw new TypeError("lines parameter must be a non-negative number");
+  try {
+    throw new Error("This is to capture a stack trace with CoreUtils.getCallStack(). (If you see this somewhere, you can safely ignore it.)");
+  } catch (err) {
+    const stack = (err.stack ?? "").split("\n").map((line) => line.trim()).slice(2, lines + 2);
+    return asArray !== false ? stack : stack.join("\n");
+  }
+}
 
 // lib/text.ts
 function autoPlural(term, num, pluralType = "auto") {
@@ -476,16 +536,18 @@ function joinArrayReadable(array, separators = ", ", lastSeparator = " and ") {
   return arr.join(separators) + lastItm;
 }
 function secsToTimeStr(seconds) {
-  if (seconds < 0)
-    throw new TypeError("Seconds must be a positive number");
-  const hours = Math.floor(seconds / 3600);
-  const minutes = Math.floor(seconds % 3600 / 60);
-  const secs = Math.floor(seconds % 60);
-  return [
-    hours ? hours + ":" : "",
-    String(minutes).padStart(minutes > 0 || hours > 0 ? 2 : 1, "0"),
+  const isNegative = seconds < 0;
+  const s = Math.abs(seconds);
+  if (isNaN(s) || !isFinite(s))
+    throw new TypeError("The seconds argument must be a valid number");
+  const hrs = Math.floor(s / 3600);
+  const mins = Math.floor(s % 3600 / 60);
+  const secs = Math.floor(s % 60);
+  return (isNegative ? "-" : "") + [
+    hrs ? hrs + ":" : "",
+    String(mins).padStart(mins > 0 || hrs > 0 ? 2 : 1, "0"),
     ":",
-    String(secs).padStart(secs > 0 || minutes > 0 || hours > 0 ? 2 : 1, "0")
+    String(secs).padStart(secs > 0 || mins > 0 || hrs > 0 || seconds === 0 ? 2 : 1, "0")
   ].join("");
 }
 function truncStr(input, length, endStr = "...") {
@@ -494,34 +556,6 @@ function truncStr(input, length, endStr = "...") {
   return finalStr.length > length ? finalStr.substring(0, length) : finalStr;
 }
 
-// lib/Errors.ts
-var DatedError = class extends Error {
-  date;
-  constructor(message, options) {
-    super(message, options);
-    this.name = this.constructor.name;
-    this.date = /* @__PURE__ */ new Date();
-  }
-};
-var ChecksumMismatchError = class extends DatedError {
-  constructor(message, options) {
-    super(message, options);
-    this.name = "ChecksumMismatchError";
-  }
-};
-var MigrationError = class extends DatedError {
-  constructor(message, options) {
-    super(message, options);
-    this.name = "MigrationError";
-  }
-};
-var ValidationError = class extends DatedError {
-  constructor(message, options) {
-    super(message, options);
-    this.name = "ValidationError";
-  }
-};
-
 // lib/DataStore.ts
 var dsFmtVer = 1;
 var DataStore = class {
@@ -531,6 +565,7 @@ var DataStore = class {
   encodeData;
   decodeData;
   compressionFormat = "deflate-raw";
+  memoryCache = true;
   engine;
   options;
   /**
@@ -543,6 +578,7 @@ var DataStore = class {
   cachedData;
   migrations;
   migrateIds = [];
+  //#region constructor
   /**
    * 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.  
@@ -557,7 +593,8 @@ var DataStore = class {
     this.id = opts.id;
     this.formatVersion = opts.formatVersion;
     this.defaultData = opts.defaultData;
-    this.cachedData = opts.defaultData;
+    this.memoryCache = Boolean(opts.memoryCache ?? true);
+    this.cachedData = this.memoryCache ? opts.defaultData : {};
     this.migrations = opts.migrations;
     if (opts.migrateIds)
       this.migrateIds = Array.isArray(opts.migrateIds) ? opts.migrateIds : [opts.migrateIds];
@@ -582,7 +619,7 @@ var DataStore = class {
       throw new TypeError("Either `compressionFormat` or `encodeData` and `decodeData` have to be set and valid, but not all three at a time. Please refer to the documentation for more info.");
     this.engine.setDataStoreOptions(opts);
   }
-  //#region public
+  //#region loadData
   /**
    * Loads the data saved in persistent storage into the in-memory cache and also returns a copy of it.  
    * Automatically populates persistent storage with default data if it doesn't contain any data yet.  
@@ -593,28 +630,28 @@ var DataStore = class {
       if (this.firstInit) {
         this.firstInit = false;
         const dsVer = Number(await this.engine.getValue("__ds_fmt_ver", 0));
-        if (isNaN(dsVer) || dsVer < 1) {
-          const oldData = await this.engine.getValue(`_uucfg-${this.id}`, null);
-          if (oldData) {
-            const oldVer = Number(await this.engine.getValue(`_uucfgver-${this.id}`, NaN));
-            const oldEnc = await this.engine.getValue(`_uucfgenc-${this.id}`, null);
-            const promises = [];
-            const migrateFmt = (oldKey, newKey, value) => {
-              promises.push(this.engine.setValue(newKey, value));
-              promises.push(this.engine.deleteValue(oldKey));
-            };
-            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);
+        const oldData = await this.engine.getValue(`_uucfg-${this.id}`, null);
+        if (oldData) {
+          const oldVer = Number(await this.engine.getValue(`_uucfgver-${this.id}`, NaN));
+          const oldEnc = await this.engine.getValue(`_uucfgenc-${this.id}`, null);
+          const promises = [];
+          const migrateFmt = (oldKey, newKey, value) => {
+            promises.push(this.engine.setValue(newKey, value));
+            promises.push(this.engine.deleteValue(oldKey));
+          };
+          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 ? this.compressionFormat ?? null : null);
+          else {
+            promises.push(this.engine.setValue(`__ds-${this.id}-enf`, this.compressionFormat));
+            promises.push(this.engine.deleteValue(`_uucfgenc-${this.id}`));
           }
-          await this.engine.setValue("__ds_fmt_ver", dsFmtVer);
+          await Promise.allSettled(promises);
         }
+        if (isNaN(dsVer) || dsVer < dsFmtVer)
+          await this.engine.setValue("__ds_fmt_ver", dsFmtVer);
       }
       if (this.migrateIds.length > 0) {
         await this.migrateId(this.migrateIds);
@@ -624,7 +661,7 @@ var DataStore = class {
       let storedFmtVer = Number(await this.engine.getValue(`__ds-${this.id}-ver`, NaN));
       if (typeof storedDataRaw !== "string") {
         await this.saveDefaultData();
-        return { ...this.defaultData };
+        return this.engine.deepCopy(this.defaultData);
       }
       const storedData = storedDataRaw ?? JSON.stringify(this.defaultData);
       const encodingFmt = String(await this.engine.getValue(`__ds-${this.id}-enf`, null));
@@ -639,23 +676,32 @@ var DataStore = class {
         parsed = await this.runMigrations(parsed, storedFmtVer);
       if (saveData)
         await this.setData(parsed);
-      return this.cachedData = this.engine.deepCopy(parsed);
+      if (this.memoryCache)
+        return this.cachedData = this.engine.deepCopy(parsed);
+      else
+        return this.engine.deepCopy(parsed);
     } catch (err) {
       console.warn("Error while parsing JSON data, resetting it to the default value.", err);
       await this.saveDefaultData();
       return this.defaultData;
     }
   }
+  //#region getData
   /**
    * 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).
+   * 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.
    */
   getData() {
+    if (!this.memoryCache)
+      throw new DatedError("In-memory cache is disabled for this DataStore instance, so getData() can't be used. Please use loadData() instead.");
     return this.engine.deepCopy(this.cachedData);
   }
+  //#region setData
   /** Saves the data synchronously to the in-memory cache and asynchronously to the persistent storage */
   setData(data) {
-    this.cachedData = data;
+    if (this.memoryCache)
+      this.cachedData = data;
     return new Promise(async (resolve) => {
       await Promise.allSettled([
         this.engine.setValue(`__ds-${this.id}-dat`, await this.engine.serializeData(data, this.encodingEnabled())),
@@ -665,15 +711,18 @@ var DataStore = class {
       resolve();
     });
   }
+  //#region saveDefaultData
   /** 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;
+    if (this.memoryCache)
+      this.cachedData = this.defaultData;
     await Promise.allSettled([
       this.engine.setValue(`__ds-${this.id}-dat`, await this.engine.serializeData(this.defaultData, this.encodingEnabled())),
       this.engine.setValue(`__ds-${this.id}-ver`, this.formatVersion),
       this.engine.setValue(`__ds-${this.id}-enf`, this.compressionFormat)
     ]);
   }
+  //#region deleteData
   /**
    * 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()}  
@@ -688,11 +737,12 @@ var DataStore = class {
     ]);
     await ((_b = (_a = this.engine).deleteStorage) == null ? void 0 : _b.call(_a));
   }
+  //#region encodingEnabled
   /** Returns whether encoding and decoding are enabled for this DataStore instance */
   encodingEnabled() {
     return Boolean(this.encodeData && this.decodeData) && this.compressionFormat !== null || Boolean(this.compressionFormat);
   }
-  //#region migrations
+  //#region runMigrations
   /**
    * Runs all necessary migration functions consecutively and saves the result to the in-memory cache and persistent storage and also returns it.  
    * This method is automatically called by {@linkcode loadData()} if the data format has changed since the last time the data was saved.  
@@ -726,8 +776,12 @@ var DataStore = class {
       this.engine.setValue(`__ds-${this.id}-ver`, lastFmtVer),
       this.engine.setValue(`__ds-${this.id}-enf`, this.compressionFormat)
     ]);
-    return this.cachedData = { ...newData };
+    if (this.memoryCache)
+      return this.cachedData = this.engine.deepCopy(newData);
+    else
+      return this.engine.deepCopy(newData);
   }
+  //#region migrateId
   /**
    * Tries to migrate the currently saved persistent data from one or more old IDs to the ID set in the constructor.  
    * If no data exist for the old ID(s), nothing will be done, but some time may still pass trying to fetch the non-existent data.
@@ -771,7 +825,7 @@ var DataStoreEngine = class {
     this.dataStoreOptions = dataStoreOptions;
   }
   //#region serialization api
-  /** Serializes the given object to a string, optionally encoded with `options.encodeData` if {@linkcode useEncoding} is set to true */
+  /** Serializes the given object to a string, optionally encoded with `options.encodeData` if {@linkcode useEncoding} is not set to false and the `encodeData` and `decodeData` options are set */
   async serializeData(data, useEncoding) {
     var _a, _b, _c, _d, _e;
     this.ensureDataStoreOptions();
@@ -819,7 +873,7 @@ var BrowserStorageEngine = class extends DataStoreEngine {
    * Creates an instance of `BrowserStorageEngine`.  
    *   
    * - ⚠️ Requires a DOM environment  
-   * - ⚠️ Don't reuse engines across multiple {@linkcode DataStore} instances
+   * - ⚠️ Don't reuse engine instances, always create a new one for each {@linkcode DataStore} instance
    */
   constructor(options) {
     super(options == null ? void 0 : options.dataStoreOptions);
@@ -857,7 +911,7 @@ var FileStorageEngine = class extends DataStoreEngine {
    * Creates an instance of `FileStorageEngine`.  
    *   
    * - ⚠️ Requires Node.js or Deno with Node compatibility (v1.31+)  
-   * - ⚠️ Don't reuse engines across multiple {@linkcode DataStore} instances
+   * - ⚠️ Don't reuse engine instances, always create a new one for each {@linkcode DataStore} instance
    */
   constructor(options) {
     super(options == null ? void 0 : options.dataStoreOptions);
@@ -875,7 +929,7 @@ var FileStorageEngine = class extends DataStoreEngine {
       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") });
+        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 data = await fs.readFile(path, "utf-8");
       return data ? JSON.parse(await ((_d = (_c = (_b = this.dataStoreOptions) == null ? void 0 : _b.decodeData) == null ? void 0 : _c[1]) == null ? void 0 : _d.call(_c, data)) ?? data) : void 0;
@@ -891,7 +945,7 @@ var FileStorageEngine = class extends DataStoreEngine {
       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") });
+        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);
       await fs.mkdir(path.slice(0, path.lastIndexOf(path.includes("/") ? "/" : "\\")), { recursive: true });
       await fs.writeFile(path, await ((_d = (_c = (_b = this.dataStoreOptions) == null ? void 0 : _b.encodeData) == null ? void 0 : _c[1]) == null ? void 0 : _d.call(_c, JSON.stringify(data))) ?? JSON.stringify(data, void 0, 2), "utf-8");
@@ -950,9 +1004,9 @@ var FileStorageEngine = class extends DataStoreEngine {
       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") });
+        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);
-      await fs.unlink(path);
+      return await fs.unlink(path);
     } catch (err) {
       console.error("Error deleting file:", err);
     }
@@ -965,11 +1019,12 @@ var DataStoreSerializer = class _DataStoreSerializer {
   options;
   constructor(stores, options = {}) {
     if (!crypto || !crypto.subtle)
-      throw new Error("DataStoreSerializer has to run in a secure context (HTTPS) or in another environment that implements the subtleCrypto API!");
+      throw new ScriptContextError("DataStoreSerializer has to run in a secure context (HTTPS) or in another environment that implements the subtleCrypto API!");
     this.stores = stores;
     this.options = {
       addChecksum: true,
       ensureIntegrity: true,
+      remapIds: {},
       ...options
     };
   }
@@ -986,9 +1041,11 @@ var DataStoreSerializer = class _DataStoreSerializer {
   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 filteredStores = this.stores.filter((s) => typeof stores === "function" ? stores(s.id) : stores.includes(s.id));
+    for (const storeInst of filteredStores) {
       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());
+      const rawData = storeInst.memoryCache ? storeInst.getData() : await storeInst.loadData();
+      const data = encoded ? await storeInst.encodeData[1](JSON.stringify(rawData)) : JSON.stringify(rawData);
       serData.push({
         id: storeInst.id,
         data,
@@ -1015,10 +1072,18 @@ var DataStoreSerializer = class _DataStoreSerializer {
     const deserStores = typeof data === "string" ? JSON.parse(data) : data;
     if (!Array.isArray(deserStores) || !deserStores.every(_DataStoreSerializer.isSerializedDataStoreObj))
       throw new TypeError("Invalid serialized data format! Expected an array of SerializedDataStore objects.");
-    for (const storeData of deserStores.filter((s) => typeof stores === "function" ? stores(s.id) : stores.includes(s.id))) {
-      const storeInst = this.stores.find((s) => s.id === storeData.id);
+    const resolveStoreId = (id) => {
+      var _a;
+      return ((_a = Object.entries(this.options.remapIds).find(([, v]) => v.includes(id))) == null ? void 0 : _a[0]) ?? id;
+    };
+    const matchesFilter = (id) => typeof stores === "function" ? stores(id) : stores.includes(id);
+    for (const storeData of deserStores) {
+      const effectiveId = resolveStoreId(storeData.id);
+      if (!matchesFilter(effectiveId))
+        continue;
+      const storeInst = this.stores.find((s) => s.id === effectiveId);
       if (!storeInst)
-        throw new Error(`DataStore instance with ID "${storeData.id}" not found! Make sure to provide it in the DataStoreSerializer constructor.`);
+        throw new DatedError(`Can't deserialize data because no DataStore instance with the ID "${effectiveId}" was found! Make sure to provide it in the DataStoreSerializer constructor.`);
       if (this.options.ensureIntegrity && typeof storeData.checksum === "string") {
         const checksum = await this.calcChecksum(storeData.data);
         if (checksum !== storeData.checksum)
@@ -1189,11 +1254,12 @@ var NanoEmitter = class {
    * `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 `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.  
-   * You may use a combination of the above two options, but at least one of them must be provided.  
+   * 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.
    */
@@ -1221,6 +1287,8 @@ var NanoEmitter = class {
       } = 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)
@@ -1230,34 +1298,31 @@ var NanoEmitter = class {
         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();
-          callback(event, ...args);
-          if (once)
-            checkUnsubAllEvt(true);
+          if (allOfConditionMet()) {
+            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);
+          allOfEmitted.add(event);
+          if (allOfConditionMet() && (oneOf.length === 0 || oneOf.includes(event))) {
+            callback(event, ...args);
+            if (once)
+              checkUnsubAllEvt(true);
+          }
         }));
         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;