@sv443-network/coreutils 1.0.0 → 2.0.0

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 */

package/dist/lib/DataStoreEngine.d.ts

@@ -4,15 +4,22 @@
  * [See the documentation for more info.](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#class-datastoreengine)  
  */
 import type { DataStoreData, DataStoreOptions } from "./DataStore.js";
-import type { SerializableVal } from "./types.js";
+import type { Prettify, SerializableVal } from "./types.js";
+/** Contains the only properties of {@linkcode DataStoreOptions} that are relevant to the {@linkcode DataStoreEngine} class. */
+export type DataStoreEngineDSOptions<TData extends DataStoreData> = Prettify<Pick<DataStoreOptions<TData>, "decodeData" | "encodeData" | "id">>;
+export interface DataStoreEngine<TData extends DataStoreData> {
+    /** Deletes all data in persistent storage, including the data container itself (e.g. a file or a database) */
+    deleteStorage?(): Promise<void>;
+}
 /**
  * Base class for creating {@linkcode DataStore} storage engines.  
  * This acts as an interchangeable API for writing and reading persistent data in various environments.  
  */
 export declare abstract class DataStoreEngine<TData extends DataStoreData> {
-    protected dataStoreOptions: DataStoreOptions<TData>;
-    /** Called by DataStore on creation, to pass its options */
-    setDataStoreOptions(dataStoreOptions: DataStoreOptions<TData>): void;
+    protected dataStoreOptions: DataStoreEngineDSOptions<TData>;
+    constructor(options?: DataStoreEngineDSOptions<TData>);
+    /** Called by DataStore on creation, to pass its options. Only call this if you are using this instance standalone! */
+    setDataStoreOptions(dataStoreOptions: DataStoreEngineDSOptions<TData>): void;
     /** Fetches a value from persistent storage */
     abstract getValue<TValue extends SerializableVal = string>(name: string, defaultValue: TValue): Promise<string | TValue>;
     /** Sets a value in persistent storage */
@@ -23,6 +30,8 @@ export declare abstract class DataStoreEngine<TData extends DataStoreData> {
     serializeData(data: TData, useEncoding?: boolean): Promise<string>;
     /** Deserializes the given string to a JSON object, optionally decoded with `options.decodeData` if {@linkcode useEncoding} is set to true */
     deserializeData(data: string, useEncoding?: boolean): Promise<TData>;
+    /** Throws an error if the DataStoreOptions are not set or invalid */
+    protected ensureDataStoreOptions(): void;
     /**
      * 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))`.  
@@ -33,20 +42,25 @@ export declare abstract class DataStoreEngine<TData extends DataStoreData> {
 export type BrowserStorageEngineOptions = {
     /** Whether to store the data in LocalStorage (default) or SessionStorage */
     type?: "localStorage" | "sessionStorage";
+    /**
+     * Specifies the necessary options for storing data.  
+     * - ⚠️ Only specify this if you are using this instance standalone! The parent DataStore will set this automatically.  
+     */
+    dataStoreOptions?: DataStoreEngineDSOptions<DataStoreData>;
 };
 /**
  * Storage engine for the {@linkcode DataStore} class that uses the browser's LocalStorage or SessionStorage to store data.  
  *  
- * ⚠️ 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  
  */
 export declare class BrowserStorageEngine<TData extends DataStoreData> extends DataStoreEngine<TData> {
-    protected options: Required<BrowserStorageEngineOptions>;
+    protected options: BrowserStorageEngineOptions & Required<Pick<BrowserStorageEngineOptions, "type">>;
     /**
      * 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?: BrowserStorageEngineOptions);
     /** Fetches a value from persistent storage */
@@ -60,20 +74,25 @@ export declare class BrowserStorageEngine<TData extends DataStoreData> extends D
 export type FileStorageEngineOptions = {
     /** Function that returns a string or a plain string that is the data file path, including name and extension. Defaults to `.ds-${dataStoreID}` */
     filePath?: ((dataStoreID: string) => string) | string;
+    /**
+     * Specifies the necessary options for storing data.  
+     * - ⚠️ Only specify this if you are using this instance standalone! The parent DataStore will set this automatically.  
+     */
+    dataStoreOptions?: DataStoreEngineDSOptions<DataStoreData>;
 };
 /**
  * Storage engine for the {@linkcode DataStore} class that uses a JSON file to store data.  
  *  
- * ⚠️ 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  
  */
 export declare class FileStorageEngine<TData extends DataStoreData> extends DataStoreEngine<TData> {
-    protected options: Required<FileStorageEngineOptions>;
+    protected options: FileStorageEngineOptions & Required<Pick<FileStorageEngineOptions, "filePath">>;
     /**
      * 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?: FileStorageEngineOptions);
     /** Reads the file contents */
@@ -86,4 +105,6 @@ export declare class FileStorageEngine<TData extends DataStoreData> extends Data
     setValue<TValue extends SerializableVal = string>(name: string, value: TValue): Promise<void>;
     /** Deletes a value from persistent storage */
     deleteValue(name: string): Promise<void>;
+    /** Deletes the file that contains the data of this DataStore. */
+    deleteStorage(): Promise<void>;
 }

package/dist/lib/NanoEmitter.d.ts

@@ -3,10 +3,26 @@
  * This module contains the NanoEmitter class, which is a tiny event emitter powered by [nanoevents](https://www.npmjs.com/package/nanoevents) - [see the documentation for more info](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#nanoemitter)  
  */
 import { type DefaultEvents, type Emitter, type EventsMap, type Unsubscribe } from "nanoevents";
+import type { Prettify } from "./types.js";
 export interface NanoEmitterOptions {
     /** If set to true, allows emitting events through the public method emit() */
     publicEmit: boolean;
 }
+type NanoEmitterOnMultiTriggerOptions<TEvtMap extends EventsMap, TKey extends keyof TEvtMap = keyof TEvtMap> = {
+    /** Calls the callback when one of the given events is emitted */
+    oneOf?: TKey[];
+    /** Calls the callback when all of the given events are emitted */
+    allOf?: TKey[];
+};
+/** Options for the {@linkcode NanoEmitter.onMulti()} method */
+export type NanoEmitterOnMultiOptions<TEvtMap extends EventsMap, TKey extends keyof TEvtMap = keyof TEvtMap> = Prettify<{
+    /** If true, the callback will be called only once for the first event (or set of events) that match the criteria */
+    once?: boolean;
+    /** If provided, can be used to abort the subscription if the signal is aborted */
+    signal?: AbortSignal;
+    /** The callback to call when the event with the given name is emitted */
+    callback: (event: TKey, ...args: Parameters<TEvtMap[TKey]>) => void;
+} & NanoEmitterOnMultiTriggerOptions<TEvtMap, TKey> & (Pick<Required<NanoEmitterOnMultiTriggerOptions<TEvtMap, TKey>>, "oneOf"> | Pick<Required<NanoEmitterOnMultiTriggerOptions<TEvtMap, TKey>>, "allOf">)>;
 /**
  * Class that can be extended or instantiated by itself to create a lightweight event emitter with helper methods and a strongly typed event map.  
  * If extended from, you can use `this.events.emit()` to emit events, even if the `emit()` method doesn't work because `publicEmit` is not set to true in the constructor.  
@@ -58,9 +74,24 @@ export declare class NanoEmitter<TEvtMap extends EventsMap = DefaultEvents> {
      * ```  
      */
     once<TKey extends keyof TEvtMap>(event: TKey | "_", cb?: TEvtMap[TKey]): Promise<Parameters<TEvtMap[TKey]>>;
+    /**
+     * 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<TEvt extends keyof TEvtMap>(options: NanoEmitterOnMultiOptions<TEvtMap> | Array<NanoEmitterOnMultiOptions<TEvtMap>>): Unsubscribe;
     /**
      * 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  
@@ -69,3 +100,4 @@ export declare class NanoEmitter<TEvtMap extends EventsMap = DefaultEvents> {
     /** Unsubscribes all event listeners from this instance */
     unsubscribeAll(): void;
 }
+export {};

package/dist/lib/TieredCache.d.ts

@@ -46,7 +46,7 @@ export type TieredCacheTierOptions<TData extends DataStoreData> = Prettify<{
     /**
      * Engine used for persistent storage. Can be a function that returns a DataStoreEngine or a DataStoreEngine instance.  
      * If this property is not set, this tier will not persist data and only keeps it in memory.  
-     * ⚠️ **Don't reuse instances in multiple tiers and make sure the ID is always unique!**  
+     * - ⚠️ **Don't reuse instances in multiple tiers and make sure the ID is always unique!**  
      */
     engine?: (() => DataStoreEngine<TData>) | DataStoreEngine<TData>;
     /** Which compression format to use for this tier's persistent storage. Defaults to `deflate-raw` - set to `null` to disable compression. */

package/dist/lib/crypto.d.ts

@@ -1,27 +1,27 @@
 /**
  * @module crypto  
- * This module contains various cryptographic functions, like compression and ArrayBuffer encoding - [see the documentation for more info](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#crypto)  
+ * This module contains various cryptographic functions, like compression and Uint8Array encoding - [see the documentation for more info](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#crypto)  
  */
 import type { Stringifiable } from "./types.js";
-/** Converts an ArrayBuffer to a base64-encoded (ASCII) string */
-export declare function abtoa(buf: ArrayBuffer): string;
-/** Converts a base64-encoded (ASCII) string to an ArrayBuffer representation of its bytes */
-export declare function atoab(str: string): ArrayBuffer;
-/** Compresses a string or an ArrayBuffer using the provided {@linkcode compressionFormat} and returns it as a base64 string */
-export declare function compress(input: Stringifiable | ArrayBuffer, compressionFormat: CompressionFormat, outputType?: "string"): Promise<string>;
-/** Compresses a string or an ArrayBuffer using the provided {@linkcode compressionFormat} and returns it as an ArrayBuffer */
-export declare function compress(input: Stringifiable | ArrayBuffer, compressionFormat: CompressionFormat, outputType: "arrayBuffer"): Promise<ArrayBuffer>;
-/** Decompresses a previously compressed base64 string or ArrayBuffer, with the format passed by {@linkcode compressionFormat}, converted to a string */
-export declare function decompress(input: Stringifiable | ArrayBuffer, compressionFormat: CompressionFormat, outputType?: "string"): Promise<string>;
-/** Decompresses a previously compressed base64 string or ArrayBuffer, with the format passed by {@linkcode compressionFormat}, converted to an ArrayBuffer */
-export declare function decompress(input: Stringifiable | ArrayBuffer, compressionFormat: CompressionFormat, outputType: "arrayBuffer"): Promise<ArrayBuffer>;
+/** Converts an Uint8Array to a base64-encoded (ASCII) string */
+export declare function abtoa(buf: Uint8Array): string;
+/** Converts a base64-encoded (ASCII) string to an Uint8Array representation of its bytes */
+export declare function atoab(str: string): Uint8Array;
+/** Compresses a string or an Uint8Array using the provided {@linkcode compressionFormat} and returns it as a base64 string */
+export declare function compress(input: Stringifiable | Uint8Array, compressionFormat: CompressionFormat, outputType?: "string"): Promise<string>;
+/** Compresses a string or an Uint8Array using the provided {@linkcode compressionFormat} and returns it as an Uint8Array */
+export declare function compress(input: Stringifiable | Uint8Array, compressionFormat: CompressionFormat, outputType: "arrayBuffer"): Promise<Uint8Array>;
+/** Decompresses a previously compressed base64 string or Uint8Array, with the format passed by {@linkcode compressionFormat}, converted to a string */
+export declare function decompress(input: Stringifiable | Uint8Array, compressionFormat: CompressionFormat, outputType?: "string"): Promise<string>;
+/** Decompresses a previously compressed base64 string or Uint8Array, with the format passed by {@linkcode compressionFormat}, converted to an Uint8Array */
+export declare function decompress(input: Stringifiable | Uint8Array, compressionFormat: CompressionFormat, outputType: "arrayBuffer"): Promise<Uint8Array>;
 /**
- * Creates a hash / checksum of the given {@linkcode input} string or ArrayBuffer using the specified {@linkcode algorithm} ("SHA-256" by default).  
+ * Creates a hash / checksum of the given {@linkcode input} string or Uint8Array using the specified {@linkcode algorithm} ("SHA-256" by default).  
  *  
  * - ⚠️ Uses the SubtleCrypto API so it needs to run in a secure context (HTTPS).  
  * - ⚠️ If you use this for cryptography, make sure to use a secure algorithm (under no circumstances use SHA-1) and to [salt](https://en.wikipedia.org/wiki/Salt_(cryptography)) your input data.  
  */
-export declare function computeHash(input: string | ArrayBuffer, algorithm?: string): Promise<string>;
+export declare function computeHash(input: string | Uint8Array, algorithm?: string): Promise<string>;
 /**
  * Generates a random ID with the specified length and radix (16 characters and hexadecimal by default)  
  *  

package/dist/lib/math.d.ts

@@ -35,6 +35,10 @@ export declare function mapRange(value: number, range1min: number, range1max: nu
  * For example, you can map the value 2 in the range of 0-5 to the range of 0-10 and you'd get a 4 as a result.  
  */
 export declare function mapRange(value: number, range1max: number, range2max: number): number;
+/** Makes the {@linkcode value} over- & underflow so it is always between {@linkcode min} and {@linkcode max}, if it's outside the range */
+export declare function overflowVal(value: number, min: number, max: number): number;
+/** Makes the {@linkcode value} over- & underflow so it is always between `0` and {@linkcode max}, if it's outside the range */
+export declare function overflowVal(value: number, max: number): number;
 /**
  * Returns a random number between {@linkcode min} and {@linkcode max} (inclusive)  
  * Set {@linkcode enhancedEntropy} to true to use `crypto.getRandomValues()` for better cryptographic randomness (this also makes it take longer to generate)  

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sv443-network/coreutils",
   "libName": "@sv443-network/coreutils",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "Cross-platform, general-purpose, JavaScript core library for Node, Deno and the browser. Intended to be used in conjunction with `@sv443-network/userutils` and `@sv443-network/djsutils`, but can be used independently as well.",
   "main": "dist/CoreUtils.cjs",
   "module": "dist/CoreUtils.mjs",
@@ -85,6 +85,7 @@
     "publish-package": "changeset publish",
     "publish-package-jsr": "pnpm update-jsr-version && npx jsr publish --allow-dirty",
     "check-jsr": "pnpm update-jsr-version && npx jsr publish --allow-dirty --dry-run",
+    "check-npm": "npm publish --dry-run",
     "change": "changeset",
     "test": "vitest",
     "test-coverage": "vitest --coverage"