@sv443-network/coreutils 1.0.0 → 2.0.0

package/CHANGELOG.md

@@ -1,13 +1,30 @@
 # @sv443-network/coreutils
 
+## 2.0.0
+
+### Major Changes
+
+- 273fa5a: Removed the boolean property `__ds-${id}-enc` from the `DataStore` and `DataStoreEngine` classes.
+  Now the key `__ds-${id}-enf` will hold the encoding format identifier string, or `null` if not set (will get created on the next write call).
+  This will make it possible to switch the encoding format without compatibility issues.
+  This functionality is not officially supported yet, but can be achieved manually by calling the storage API methods of `storeInstance.engine`
+
+### Minor Changes
+
+- 29fb048: Added `overflowVal()` to conform a value to an over- & undeflowing range
+- 91cbe9c: Added optional abstract method `DataStoreEngine.deleteStorage()` for deleting the data storage container itself. If implemented in subclasses, it will be called from the method `DataStore.deleteData()`
+- 3cae1cb: Added `dataStoreOptions` constructor prop to the DataStoreEngine subclasses to enable them to be used standalone.
+- f6465b5: Added method `NanoEmitter.onMulti()` to listen to when multiple events have emitted, with fine grained options
+
 ## 1.0.0
 
 This is the initial release of CoreUtils. Most features have been originally ported from [version 9.4.1 of `@sv443-network/userutils`](https://github.com/Sv443-Network/UserUtils/tree/v9.4.1)  
 Parts of the code have been overhauled, and some features have been added:
+
 - Additions:
   - Added [`capitalize()`](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#function-capitalize) to capitalize the first letter of a string.
-  - Added [`setImmediateInterval()`](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#function-setimmediateinterval) to set an interval that runs immediately, then again on a fixed *interval.*
-  - Added [`setImmediateTimeoutLoop()`](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#function-setimmediatetimeoutloop) to set a recursive `setTimeout()` loop with a fixed *delay.*
+  - Added [`setImmediateInterval()`](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#function-setimmediateinterval) to set an interval that runs immediately, then again on a fixed _interval._
+  - Added [`setImmediateTimeoutLoop()`](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#function-setimmediatetimeoutloop) to set a recursive `setTimeout()` loop with a fixed _delay._
   - Added [`takeRandomItemIndex()`](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#function-takerandomitemindex), as a mutating counterpart to [`randomItemIndex()`](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#function-randomitemindex)
   - Added [`truncStr()`](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#function-truncstr) to truncate a string to a given length, optionally adding an ellipsis.
   - Added [`valsWithin()`](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#function-valswithin) to check if two values, rounded at the given decimal, are within a certain range of each other.

package/README.md

@@ -4,7 +4,7 @@
 Cross-platform, general-purpose, JavaScript core library for Node, Deno and the browser.  
 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) • [Features](#features) • [Installation](#installation) • [License](#license) • [Changelog](./CHANGELOG.md)
+### [Documentation](./docs.md#readme) • [Features](#features) • [Installation](#installation) • [License](./LICENSE.txt) • [Changelog](./CHANGELOG.md)
 
 </div>
 <br>
@@ -34,12 +34,14 @@ Intended to be used in conjunction with [`@sv443-network/userutils`](https://git
   - 🟧 [`class DataStore`](./docs.md#class-datastore) - The main class for the data store
     - 🔷 [`type DataStoreOptions`](./docs.md#type-datastoreoptions) - Options for the data store
     - 🔷 [`type DataMigrationsDict`](./docs.md#type-datamigrationsdict) - Dictionary of data migration functions
+    - 🔷 [`type DataStoreData`](./docs.md#type-datastoredata) - The type of the serializable data
   - 🟧 [`class DataStoreSerializer`](./docs.md#class-datastoreserializer) - Serializes and deserializes data for multiple DataStore instances
     - 🔷 [`type DataStoreSerializerOptions`](./docs.md#type-datastoreserializeroptions) - Options for the DataStoreSerializer
     - 🔷 [`type LoadStoresDataResult`](./docs.md#type-loadstoresdataresult) - Result of calling [`loadStoresData()`](./docs.md#datastoreserializer-loadstoresdata)
     - 🔷 [`type SerializedDataStore`](./docs.md#type-serializeddatastore) - Meta object and serialized data of a DataStore instance
     - 🔷 [`type StoreFilter`](./docs.md#type-storefilter) - Filter for selecting data stores
   - 🟧 [`class DataStoreEngine`](./docs.md#class-datastoreengine) - Base class for DataStore storage engines, which handle the data storage
+    - 🔷 [`type DataStoreEngineDSOptions`](./docs.md#type-datastoreenginedsoptions) - Reduced version of [`DataStoreOptions`](./docs.md#type-datastoreoptions)
   - [Storage Engines:](./docs.md#storage-engines)
     - 🟧 [`class BrowserStorageEngine`](./docs.md#class-browserstorageengine) - Storage engine for browser environments (localStorage, sessionStorage)
       - 🔷 [`type BrowserStorageEngineOptions`](./docs.md#browserstorageengineoptions) - Options for the browser storage engine
@@ -63,6 +65,7 @@ Intended to be used in conjunction with [`@sv443-network/userutils`](https://git
   - 🟣 [`function formatNumber()`](./docs.md#function-formatnumber) - Formats a number to a string using the given locale and format identifier
     - 🔷 [`type NumberFormat`](./docs.md#type-numberformat) - Number format identifier
   - 🟣 [`function mapRange()`](./docs.md#function-maprange) - Maps a number from one range to another
+  - 🟣 [`function overflowVal()`](./docs.md#function-overflowVal) - Makes sure a number is in a range by over- & underflowing it
   - 🟣 [`function randRange()`](./docs.md#function-randrange) - Returns a random number in the given range
   - 🟣 [`function roundFixed()`](./docs.md#function-roundfixed) - Rounds the given number to the given number of decimal places
   - 🟣 [`function valsWithin()`](./docs.md#function-valswithin) - Checks if the given numbers are within a certain range of each other
@@ -90,7 +93,7 @@ Intended to be used in conjunction with [`@sv443-network/userutils`](https://git
     - 🟩 [`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-sectostimestr) - Turns the given number of seconds into a string in the format `(hh:)mm:ss` with intelligent zero-padding
+  - 🟣 [`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
   - 🟣 [`function truncStr()`](./docs.md#function-truncstr) - Truncates the given string to the given length
 <!-- - *[**TieredCache:**](./docs.md#tieredcache)
   - 🟧 *[`class TieredCache`](./docs.md#class-tieredcache) - A multi-tier cache that uses multiple storage engines with different expiration times
@@ -122,7 +125,7 @@ Intended to be used in conjunction with [`@sv443-network/userutils`](https://git
 > 🟣 = function  
 > 🟧 = class  
 > 🔷 = type  
-> 🔶 = const
+> 🟩 = const
 
 <br>
 
@@ -135,11 +138,11 @@ yarn add @sv443-network/coreutils
 npx jsr install @sv443-network/coreutils
 deno add jsr:@sv443-network/coreutils
 ```
-- If you are in a DOM environment, you can include the UMD bundle using your favorite CDN:
+- If you are in a DOM environment, you can include the UMD bundle using your favorite CDN (after inserting the version number):
 ```html
-<script src="https://cdn.jsdelivr.net/npm/@sv443-network/coreutils@latest/dist/CoreUtils.min.umd.js"></script>
-<script src="https://unpkg.com/@sv443-network/coreutils@latest/dist/CoreUtils.min.umd.js"></script>
-<script src="https://esm.sh/@sv443-network/coreutils@latest/dist/CoreUtils.min.umd.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@sv443-network/coreutils@INSERT_VERSION_HERE/dist/CoreUtils.min.umd.js"></script>
+<script src="https://unpkg.com/@sv443-network/coreutils@INSERT_VERSION_HERE/dist/CoreUtils.min.umd.js"></script>
+<script src="https://esm.sh/@sv443-network/coreutils@INSERT_VERSION_HERE/dist/CoreUtils.min.umd.js"></script>
 ```
 - Then, import parts of the library as needed:
 ```ts
@@ -164,5 +167,18 @@ const CoreUtils = require("@sv443-network/coreutils");
 // - to make the global variable `CoreUtils` available, import this file:
 // "@sv443-network/coreutils/dist/CoreUtils.min.umd.js"
 // - or import the library on your HTML page:
-// <script src="https://cdn.jsdelivr.net/npm/@sv443-network/coreutils@latest/dist/CoreUtils.min.umd.js"></script>
+// <script src="https://cdn.jsdelivr.net/npm/@sv443-network/coreutils@INSERT_VERSION_HERE/dist/CoreUtils.min.umd.js"></script>
+// (make sure to insert the version number above. Use 'latest' (not recommended) or a specific version, e.g. '9.4.3')
 ```
+
+<br><br>
+
+<div align="center" style="text-align: center;">
+
+Made with ❤️ by [Sv443](https://github.com/Sv443)  
+If you like this userscript, please consider [supporting the development](https://github.com/sponsors/Sv443)  
+  
+© 2025 Sv443 & Sv443 Network  
+[MIT license](./LICENSE.txt)
+
+</div>

package/dist/CoreUtils.cjs

@@ -65,6 +65,7 @@ __export(lib_exports, {
   joinArrayReadable: () => joinArrayReadable,
   lightenColor: () => lightenColor,
   mapRange: () => mapRange,
+  overflowVal: () => overflowVal,
   pauseFor: () => pauseFor,
   pureObj: () => pureObj,
   randRange: () => randRange,
@@ -128,6 +129,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")
@@ -223,10 +237,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();
@@ -259,22 +271,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;
@@ -520,7 +532,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 = [];
@@ -528,13 +547,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;
@@ -545,8 +564,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")];
@@ -581,9 +601,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);
@@ -593,21 +618,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);
@@ -627,12 +653,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();
     });
@@ -640,30 +665,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
   /**
@@ -697,7 +721,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 };
   }
@@ -708,19 +732,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`)
       ]);
     }));
   }
@@ -730,7 +759,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;
   }
@@ -738,6 +771,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;
@@ -749,12 +783,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))`.
@@ -773,11 +815,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
@@ -809,11 +851,11 @@ var FileStorageEngine = class extends DataStoreEngine {
   /**
    * Creates an instance of `FileStorageEngine`.  
    *   
-   * ⚠️ Requires Node.js or Deno with Node compatibility (v1.31+)  
-   * ⚠️ 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
@@ -822,30 +864,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("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");
-      return data ? 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) : void 0;
+      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("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);
     }
@@ -879,6 +923,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
@@ -906,14 +965,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
       });
     }
@@ -1037,6 +1098,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 "_")
@@ -1070,6 +1132,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 "_")
@@ -1100,9 +1163,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
@@ -1114,6 +1258,7 @@ var NanoEmitter = class {
     }
     return false;
   }
+  //#region unsubscribeAll
   /** Unsubscribes all event listeners from this instance */
   unsubscribeAll() {
     for (const unsub of this.eventUnsubscribes)