@sv443-network/coreutils 0.0.1

package/dist/lib/DataStore.d.ts

@@ -0,0 +1,159 @@
+/**
+ * @module DataStore  
+ * This module contains the DataStore class, which is a general purpose, sync and async persistent database for JSON-serializable data - [see the documentation for more info](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#class-datastore)  
+ */
+import type { DataStoreEngine } from "./DataStoreEngine.js";
+import type { LooseUnion, Prettify, SerializableVal } from "./types.js";
+/** Function that takes the data in the old format and returns the data in the new format. Also supports an asynchronous migration. */
+type MigrationFunc = (oldData: any) => any | Promise<any>;
+/** Dictionary of format version numbers and the function that migrates to them from the previous whole integer */
+export type DataMigrationsDict = Record<number, MigrationFunc>;
+/** Options for the DataStore instance */
+export type DataStoreOptions<TData extends DataStoreData> = Prettify<{
+    /**
+     * A unique internal ID for this data store.  
+     * To avoid conflicts with other scripts, it is recommended to use a prefix that is unique to your script.  
+     * If you want to change the ID, you should make use of the {@linkcode DataStore.migrateId()} method.  
+     */
+    id: string;
+    /**
+     * The default data object to use if no data is saved in persistent storage yet.  
+     * Until the data is loaded from persistent storage with {@linkcode DataStore.loadData()}, this will be the data returned by {@linkcode DataStore.getData()}.  
+     *  
+     * - ⚠️ This has to be an object that can be serialized to JSON using `JSON.stringify()`, so no functions or circular references are allowed, they will cause unexpected behavior.  
+     */
+    defaultData: TData;
+    /**
+     * An incremental, whole integer version number of the current format of data.  
+     * If the format of the data is changed in any way, this number should be incremented, in which case all necessary functions of the migrations dictionary will be run consecutively.  
+     *  
+     * - ⚠️ Never decrement this number and optimally don't skip any numbers either!  
+     */
+    formatVersion: number;
+    /**
+     * 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!  
+     */
+    engine: (() => DataStoreEngine<TData>) | DataStoreEngine<TData>;
+    /**
+     * A dictionary of functions that can be used to migrate data from older versions to newer ones.  
+     * The keys of the dictionary should be the format version that the functions can migrate to, from the previous whole integer value.  
+     * The values should be functions that take the data in the old format and return the data in the new format.  
+     * The functions will be run in order from the oldest to the newest version.  
+     * If the current format version is not in the dictionary, no migrations will be run.  
+     */
+    migrations?: DataMigrationsDict;
+    /**
+     * If an ID or multiple IDs are passed here, the data will be migrated from the old ID(s) to the current ID.  
+     * This will happen once per page load, when {@linkcode DataStore.loadData()} is called.  
+     * All future calls to {@linkcode DataStore.loadData()} in the session will not check for the old ID(s) anymore.  
+     * To migrate IDs manually, use the method {@linkcode DataStore.migrateId()} instead.  
+     */
+    migrateIds?: string | string[];
+} & ({
+    encodeData?: never;
+    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!  
+     */
+    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.  
+     *  
+     * 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>];
+    /**
+     * 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.  
+     *  
+     * 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>];
+    compressionFormat?: never;
+})>;
+/** Generic type that represents the serializable data structure saved in a {@linkcode DataStore} instance. */
+export type DataStoreData<TData extends SerializableVal = SerializableVal> = Record<string, SerializableVal | TData>;
+/**
+ * Manages a hybrid synchronous & asynchronous persistent JSON database that is cached in memory and persistently saved across sessions using one of the preset DataStoreEngines or your own one.  
+ * Supports migrating data from older format versions to newer ones and populating the cache with default data if no persistent data is found.  
+ * Can be overridden to implement any other storage method.  
+ *  
+ * All methods are `protected` or `public`, so you can easily extend this class and overwrite them to use a different storage method or to add other functionality.  
+ * Remember that you can use `super.methodName()` in the subclass to call the original method if needed.  
+ *  
+ * - ⚠️ The data is stored as a JSON string, so only data compatible with [`JSON.stringify()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) can be used. Circular structures and complex objects (containing functions, symbols, etc.) will either throw an error on load and save or cause otherwise unexpected behavior. Properties with a value of `undefined` will be removed from the data prior to saving it, so use `null` instead.  
+ * - ⚠️ 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 (FIXME:will be automatically inferred from `defaultData` if not provided)  
+ */
+export declare class DataStore<TData extends DataStoreData> {
+    readonly id: string;
+    readonly formatVersion: number;
+    readonly defaultData: TData;
+    readonly encodeData: DataStoreOptions<TData>["encodeData"];
+    readonly decodeData: DataStoreOptions<TData>["decodeData"];
+    readonly compressionFormat = "deflate-raw";
+    readonly engine: DataStoreEngine<TData>;
+    protected firstInit: boolean;
+    private cachedData;
+    private migrations?;
+    private migrateIds;
+    /**
+     * 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: DataStoreOptions<TData>);
+    /**
+     * 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.  
+     * Also runs all necessary migration functions if the data format has changed since the last time the data was saved.  
+     */
+    loadData(): Promise<TData>;
+    /**
+     * 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).  
+     */
+    getData(): TData;
+    /** Saves the data synchronously to the in-memory cache and asynchronously to the persistent storage */
+    setData(data: TData): Promise<void>;
+    /** 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.  
+     * 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 */
+    encodingEnabled(): this is Required<Pick<DataStoreOptions<TData>, "encodeData" | "decodeData">>;
+    /**
+     * 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.  
+     * Though calling this method manually is not necessary, it can be useful if you want to run migrations for special occasions like a user importing potentially outdated data that has been previously exported.  
+     *  
+     * If one of the migrations fails, the data will be reset to the default value if `resetOnError` is set to `true` (default). Otherwise, an error will be thrown and no data will be saved.  
+     */
+    runMigrations(oldData: unknown, oldFmtVer: number, resetOnError?: boolean): Promise<TData>;
+    /**
+     * 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.  
+     */
+    migrateId(oldIds: string | string[]): Promise<void>;
+}
+export {};

package/dist/lib/DataStoreEngine.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @module DataStoreEngine  
+ * This module contains the `DataStoreEngine` class and some of its subclasses like `FileStorageEngine` and `BrowserStorageEngine`.  
+ * [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";
+/**
+ * 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;
+    /** 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 */
+    abstract setValue(name: string, value: SerializableVal): Promise<void>;
+    /** Deletes a value from persistent storage */
+    abstract deleteValue(name: string): Promise<void>;
+    /** Serializes the given object to a string, optionally encoded with `options.encodeData` if {@linkcode useEncoding} is set to true */
+    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>;
+    /**
+     * 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))`.  
+     */
+    deepCopy<T>(obj: T): T;
+}
+/** Options for the {@linkcode BrowserStorageEngine} class */
+export type BrowserStorageEngineOptions = {
+    /** Whether to store the data in LocalStorage (default) or SessionStorage */
+    type?: "localStorage" | "sessionStorage";
+};
+/**
+ * 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  
+ */
+export declare class BrowserStorageEngine<TData extends DataStoreData> extends DataStoreEngine<TData> {
+    protected options: Required<BrowserStorageEngineOptions>;
+    /**
+     * Creates an instance of `BrowserStorageEngine`.  
+     *  
+     * ⚠️ Requires a DOM environment  
+     * ⚠️ Don't reuse this engine across multiple {@linkcode DataStore} instances  
+     */
+    constructor(options?: BrowserStorageEngineOptions);
+    /** Fetches a value from persistent storage */
+    getValue<TValue extends SerializableVal = string>(name: string, defaultValue: TValue): Promise<string | TValue>;
+    /** Sets a value in persistent storage */
+    setValue(name: string, value: SerializableVal): Promise<void>;
+    /** Deletes a value from persistent storage */
+    deleteValue(name: string): Promise<void>;
+}
+/** Options for the {@linkcode FileStorageEngine} class */
+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;
+};
+/**
+ * Storage engine for the {@linkcode DataStore} class that uses a JSON file to store data.  
+ *  
+ * ⚠️ Requires Node.js or Deno with Node compatibility  
+ * ⚠️ Don't reuse this engine across multiple {@linkcode DataStore} instances  
+ */
+export declare class FileStorageEngine<TData extends DataStoreData> extends DataStoreEngine<TData> {
+    protected options: Required<FileStorageEngineOptions>;
+    /**
+     * Creates an instance of `FileStorageEngine`.  
+     *  
+     * ⚠️ Requires Node.js or Deno with Node compatibility  
+     * ⚠️ Don't reuse this engine across multiple {@linkcode DataStore} instances  
+     */
+    constructor(options?: FileStorageEngineOptions);
+    /** Reads the file contents */
+    protected readFile(): Promise<TData | undefined>;
+    /** Overwrites the file contents */
+    protected writeFile(data: TData): Promise<void>;
+    /** Fetches a value from persistent storage */
+    getValue<TValue extends SerializableVal = string>(name: string, defaultValue: TValue): Promise<string | TValue>;
+    /** Sets a value in persistent storage */
+    setValue<TValue extends SerializableVal = string>(name: string, value: TValue): Promise<void>;
+    /** Deletes a value from persistent storage */
+    deleteValue(name: string): Promise<void>;
+}

package/dist/lib/DataStoreSerializer.d.ts

@@ -0,0 +1,116 @@
+/**
+ * @module DataStoreSerializer  
+ * This module contains the DataStoreSerializer class, which allows you to import and export serialized DataStore data - [see the documentation for more info](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#datastoreserializer)  
+ */
+import type { DataStore, DataStoreData } from "./DataStore.js";
+/** Options for the DataStoreSerializer class */
+export type DataStoreSerializerOptions = {
+    /** Whether to add a checksum to the exported data. Defaults to `true` */
+    addChecksum?: boolean;
+    /** Whether to ensure the integrity of the data when importing it by throwing an error (doesn't throw when the checksum property doesn't exist). Defaults to `true` */
+    ensureIntegrity?: boolean;
+};
+/** Meta object and serialized data of a DataStore instance */
+export type SerializedDataStore = {
+    /** The ID of the DataStore instance */
+    id: string;
+    /** The serialized data */
+    data: string;
+    /** The format version of the data */
+    formatVersion: number;
+    /** Whether the data is encoded */
+    encoded: boolean;
+    /** The checksum of the data - key is not present when `addChecksum` is `false` */
+    checksum?: string;
+};
+/** Result of {@linkcode DataStoreSerializer.loadStoresData()} */
+export type LoadStoresDataResult = {
+    /** The ID of the DataStore instance */
+    id: string;
+    /** The in-memory data object */
+    data: object;
+};
+/** Filter for selecting data stores */
+export type StoreFilter = string[] | ((id: string) => boolean);
+/**
+ * Allows for easy serialization and deserialization of multiple DataStore instances.  
+ *  
+ * All methods are at least `protected`, so you can easily extend this class and overwrite them to use a different storage method or to add additional functionality.  
+ * Remember that you can call `super.methodName()` in the subclass to access the original method.  
+ *  
+ * - ⚠️ Needs to run in a secure context (HTTPS) due to the use of the SubtleCrypto API if checksumming is enabled.  
+ */
+export declare class DataStoreSerializer<TData extends DataStoreData> {
+    protected stores: DataStore<TData>[];
+    protected options: Required<DataStoreSerializerOptions>;
+    constructor(stores: DataStore<TData>[], options?: DataStoreSerializerOptions);
+    /** Calculates the checksum of a string */
+    protected calcChecksum(input: string): Promise<string>;
+    /**
+     * Serializes only a subset of the data stores into a string.  
+     * @param stores An array of store IDs or functions that take a store ID and return a boolean  
+     * @param useEncoding Whether to encode the data using each DataStore's `encodeData()` method  
+     * @param stringified Whether to return the result as a string or as an array of `SerializedDataStore` objects  
+     */
+    serializePartial(stores: StoreFilter, useEncoding?: boolean, stringified?: true): Promise<string>;
+    /**
+     * Serializes only a subset of the data stores into a string.  
+     * @param stores An array of store IDs or functions that take a store ID and return a boolean  
+     * @param useEncoding Whether to encode the data using each DataStore's `encodeData()` method  
+     * @param stringified Whether to return the result as a string or as an array of `SerializedDataStore` objects  
+     */
+    serializePartial(stores: StoreFilter, useEncoding?: boolean, stringified?: false): Promise<SerializedDataStore[]>;
+    /**
+     * Serializes only a subset of the data stores into a string.  
+     * @param stores An array of store IDs or functions that take a store ID and return a boolean  
+     * @param useEncoding Whether to encode the data using each DataStore's `encodeData()` method  
+     * @param stringified Whether to return the result as a string or as an array of `SerializedDataStore` objects  
+     */
+    serializePartial(stores: StoreFilter, useEncoding?: boolean, stringified?: boolean): Promise<string | SerializedDataStore[]>;
+    /**
+     * Serializes the data stores into a string.  
+     * @param useEncoding Whether to encode the data using each DataStore's `encodeData()` method  
+     * @param stringified Whether to return the result as a string or as an array of `SerializedDataStore` objects  
+     */
+    serialize(useEncoding?: boolean, stringified?: true): Promise<string>;
+    /**
+     * Serializes the data stores into a string.  
+     * @param useEncoding Whether to encode the data using each DataStore's `encodeData()` method  
+     * @param stringified Whether to return the result as a string or as an array of `SerializedDataStore` objects  
+     */
+    serialize(useEncoding?: boolean, stringified?: false): Promise<SerializedDataStore[]>;
+    /**
+     * Deserializes the data exported via {@linkcode serialize()} and imports only a subset into the DataStore instances.  
+     * Also triggers the migration process if the data format has changed.  
+     */
+    deserializePartial(stores: StoreFilter, data: string | SerializedDataStore[]): Promise<void>;
+    /**
+     * Deserializes the data exported via {@linkcode serialize()} and imports the data into all matching DataStore instances.  
+     * Also triggers the migration process if the data format has changed.  
+     */
+    deserialize(data: string | SerializedDataStore[]): Promise<void>;
+    /**
+     * Loads the persistent data of the DataStore instances into the in-memory cache.  
+     * Also triggers the migration process if the data format has changed.  
+     * @param stores An array of store IDs or a function that takes the store IDs and returns a boolean - if omitted, all stores will be loaded  
+     * @returns Returns a PromiseSettledResult array with the results of each DataStore instance in the format `{ id: string, data: object }`  
+     */
+    loadStoresData(stores?: StoreFilter): Promise<PromiseSettledResult<LoadStoresDataResult>[]>;
+    /**
+     * Resets the persistent and in-memory data of the DataStore instances to their default values.  
+     * @param stores An array of store IDs or a function that takes the store IDs and returns a boolean - if omitted, all stores will be affected  
+     */
+    resetStoresData(stores?: StoreFilter): Promise<PromiseSettledResult<void>[]>;
+    /**
+     * Deletes the persistent data of the DataStore instances.  
+     * Leaves the in-memory data untouched.  
+     * @param stores An array of store IDs or a function that takes the store IDs and returns a boolean - if omitted, all stores will be affected  
+     */
+    deleteStoresData(stores?: StoreFilter): Promise<PromiseSettledResult<void>[]>;
+    /** Checks if a given value is an array of SerializedDataStore objects */
+    static isSerializedDataStoreObjArray(obj: unknown): obj is SerializedDataStore[];
+    /** Checks if a given value is a SerializedDataStore object */
+    static isSerializedDataStoreObj(obj: unknown): obj is SerializedDataStore;
+    /** Returns the DataStore instances whose IDs match the provided array or function */
+    protected getStoresFiltered(stores?: StoreFilter): DataStore<TData>[];
+}

package/dist/lib/Debouncer.d.ts

@@ -0,0 +1,86 @@
+/**
+ * @module Debouncer  
+ * This module contains the Debouncer class and debounce function that allow you to reduce the amount of calls in rapidly firing event listeners and such - [see the documentation for more info](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#debouncer)  
+ */
+import { NanoEmitter } from "./NanoEmitter.js";
+/**
+ * The type of edge to use for the debouncer - [see the docs for a diagram and explanation.](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#debouncer)  
+ * - `immediate` - (default & recommended) - calls the listeners at the very first call ("rising" edge) and queues the latest call until the timeout expires  
+ *   - Pros:  
+ *     - First call is let through immediately  
+ *   - Cons:  
+ *     - After all calls stop, the JS engine's event loop will continue to run until the last timeout expires (doesn't really matter on the web, but could cause a process exit delay in Node.js)  
+ * - `idle` - queues all calls until there are no more calls in the given timeout duration ("falling" edge), and only then executes the very last call  
+ *   - Pros:  
+ *     - Makes sure there are zero calls in the given `timeoutDuration` before executing the last call  
+ *   - Cons:  
+ *     - Calls are always delayed by at least `1 * timeoutDuration`  
+ *     - Calls could get stuck in the queue indefinitely if there is no downtime between calls that is greater than the `timeoutDuration`  
+ */
+export type DebouncerType = "immediate" | "idle";
+type AnyFn = (...args: any) => any;
+/** The debounced function type that is returned by the {@linkcode debounce} function */
+export type DebouncedFunction<TFunc extends AnyFn> = ((...args: Parameters<TFunc>) => ReturnType<TFunc>) & {
+    debouncer: Debouncer<TFunc>;
+};
+/** Event map for the {@linkcode Debouncer} */
+export type DebouncerEventMap<TFunc extends AnyFn> = {
+    /** Emitted when the debouncer calls all registered listeners, as a pub-sub alternative */
+    call: TFunc;
+    /** Emitted when the timeout or edge type is changed after the instance was created */
+    change: (timeout: number, type: DebouncerType) => void;
+};
+/**
+ * A debouncer that calls all listeners after a specified timeout, discarding all calls in-between.  
+ * It is very useful for event listeners that fire quickly, like `input` or `mousemove`, to prevent the listeners from being called too often and hogging resources.  
+ * The exact behavior can be customized with the `type` parameter.  
+ *  
+ * The instance inherits from {@linkcode NanoEmitter} and emits the following events:  
+ * - `call` - emitted when the debouncer calls all listeners - use this as a pub-sub alternative to the default callback-style listeners  
+ * - `change` - emitted when the timeout or edge type is changed after the instance was created  
+ */
+export declare class Debouncer<TFunc extends AnyFn> extends NanoEmitter<DebouncerEventMap<TFunc>> {
+    protected timeout: number;
+    protected type: DebouncerType;
+    /** All registered listener functions and the time they were attached */
+    protected listeners: TFunc[];
+    /** The currently active timeout */
+    protected activeTimeout: ReturnType<typeof setTimeout> | undefined;
+    /** The latest queued call */
+    protected queuedCall: (() => void) | undefined;
+    /**
+     * Creates a new debouncer with the specified timeout and edge type.  
+     * @param timeout Timeout in milliseconds between letting through calls - defaults to 200  
+     * @param type The edge type to use for the debouncer - see {@linkcode DebouncerType} for details or [the documentation for an explanation and diagram](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#debouncer) - defaults to "immediate"  
+     */
+    constructor(timeout?: number, type?: DebouncerType);
+    /** Adds a listener function that will be called on timeout */
+    addListener(fn: TFunc): void;
+    /** Removes the listener with the specified function reference */
+    removeListener(fn: TFunc): void;
+    /** Removes all listeners */
+    removeAllListeners(): void;
+    /** Returns all registered listeners */
+    getListeners(): TFunc[];
+    /** Sets the timeout for the debouncer */
+    setTimeout(timeout: number): void;
+    /** Returns the current timeout */
+    getTimeout(): number;
+    /** Whether the timeout is currently active, meaning any latest call to the {@linkcode call()} method will be queued */
+    isTimeoutActive(): boolean;
+    /** Sets the edge type for the debouncer */
+    setType(type: DebouncerType): void;
+    /** Returns the current edge type */
+    getType(): DebouncerType;
+    /** Use this to call the debouncer with the specified arguments that will be passed to all listener functions registered with {@linkcode addListener()} */
+    call(...args: Parameters<TFunc>): void;
+}
+/**
+ * Creates a {@linkcode Debouncer} instance with the specified timeout and edge type and attaches the passed function as a listener.  
+ * The returned function can be called with any arguments and will execute the `call()` method of the debouncer.  
+ * The debouncer instance is accessible via the `debouncer` property of the returned function.  
+ *  
+ * Refer to the {@linkcode Debouncer} class definition or the [Debouncer documentation](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#debouncer) for more information.  
+ */
+export declare function debounce<TFunc extends (...args: any[]) => any>(fn: TFunc, timeout?: number, type?: DebouncerType): DebouncedFunction<TFunc>;
+export {};

package/dist/lib/Errors.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @module Errors  
+ * Contains custom error classes that all have a `date` property set to the time of the error throw  
+ */
+/** Base class for all custom error classes - adds a `date` prop set to the time when the error was thrown */
+export declare class DatedError extends Error {
+    readonly date: Date;
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Error while validating checksum */
+export declare class ChecksumMismatchError extends DatedError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Error while migrating data */
+export declare class MigrationError extends DatedError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Error while validating data */
+export declare class ValidationError extends DatedError {
+    constructor(message: string, options?: ErrorOptions);
+}

package/dist/lib/NanoEmitter.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @module NanoEmitter  
+ * 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";
+export interface NanoEmitterOptions {
+    /** If set to true, allows emitting events through the public method emit() */
+    publicEmit: boolean;
+}
+/**
+ * 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.  
+ */
+export declare class NanoEmitter<TEvtMap extends EventsMap = DefaultEvents> {
+    protected readonly events: Emitter<TEvtMap>;
+    protected eventUnsubscribes: Unsubscribe[];
+    protected emitterOptions: NanoEmitterOptions;
+    /** Creates a new instance of NanoEmitter - a lightweight event emitter with helper methods and a strongly typed event map */
+    constructor(options?: Partial<NanoEmitterOptions>);
+    /**
+     * Subscribes to an event and calls the callback when it's emitted.  
+     * @param event The event to subscribe to. Use `as "_"` in case your event names aren't thoroughly typed (like when using a template literal, e.g. \`event-${val}\` as "_")  
+     * @returns Returns a function that can be called to unsubscribe the event listener  
+     * @example ```ts  
+     * const emitter = new NanoEmitter<{  
+     *   foo: (bar: string) => void;  
+     * }>({  
+     *   publicEmit: true,  
+     * });  
+     *  
+     * let i = 0;  
+     * const unsub = emitter.on("foo", (bar) => {  
+     *   // unsubscribe after 10 events:  
+     *   if(++i === 10) unsub();  
+     *   console.log(bar);  
+     * });  
+     *  
+     * emitter.emit("foo", "bar");  
+     * ```  
+     */
+    on<TKey extends keyof TEvtMap>(event: TKey | "_", cb: TEvtMap[TKey]): () => void;
+    /**
+     * Subscribes to an event and calls the callback or resolves the Promise only once when it's emitted.  
+     * @param event The event to subscribe to. Use `as "_"` in case your event names aren't thoroughly typed (like when using a template literal, e.g. \`event-${val}\` as "_")  
+     * @param cb The callback to call when the event is emitted - if provided or not, the returned Promise will resolve with the event arguments  
+     * @returns Returns a Promise that resolves with the event arguments when the event is emitted  
+     * @example ```ts  
+     * const emitter = new NanoEmitter<{  
+     *   foo: (bar: string) => void;  
+     * }>();  
+     *  
+     * // Promise syntax:  
+     * const [bar] = await emitter.once("foo");  
+     * console.log(bar);  
+     *  
+     * // Callback syntax:  
+     * emitter.once("foo", (bar) => console.log(bar));  
+     * ```  
+     */
+    once<TKey extends keyof TEvtMap>(event: TKey | "_", cb?: TEvtMap[TKey]): Promise<Parameters<TEvtMap[TKey]>>;
+    /**
+     * Emits an event on this instance.  
+     * ⚠️ Needs `publicEmit` to be set to true in the NanoEmitter constructor or super() call!  
+     * @param event The event to emit  
+     * @param args The arguments to pass to the event listeners  
+     * @returns Returns true if `publicEmit` is true and the event was emitted successfully  
+     */
+    emit<TKey extends keyof TEvtMap>(event: TKey, ...args: Parameters<TEvtMap[TKey]>): boolean;
+    /** Unsubscribes all event listeners from this instance */
+    unsubscribeAll(): void;
+}

package/dist/lib/TieredCache.d.ts

@@ -0,0 +1,86 @@
+/**
+ * @module TieredCache  
+ * This module contains the TieredCache class, which is a cache that can have multiple tiers with different max TTLs, with data being moved between tiers based on what is fetched the most.  
+ */
+import { DataStore, type DataStoreData } from "./DataStore.js";
+import { NanoEmitter, type NanoEmitterOptions } from "./NanoEmitter.js";
+import type { DataStoreEngine } from "./DataStoreEngine.js";
+import type { Prettify } from "./types.js";
+/** Options for the {@linkcode TieredCache} class. */
+export type TieredCacheOptions<TData extends DataStoreData> = Prettify<{
+    /** Unique identifier for this cache. */
+    id: string;
+    /** The available cache tiers. */
+    tiers: TieredCacheTierOptions<TData>[];
+    /** Optional options to pass to the {@linkcode NanoEmitter} constructor. */
+    nanoEmitterOptions?: NanoEmitterOptions;
+}>;
+/** Options object as resolved by the {@linkcode TieredCache.resolveTierOpts()} method. */
+type TieredCacheResolvedTierOpts<TData extends DataStoreData> = Prettify<TieredCacheTierOptions<TData> & Pick<Required<TieredCacheTierOptions<TData>>, "compressionFormat">>;
+/** Options for when a {@linkcode TieredCache} entry goes stale. */
+export type TieredCacheStaleOptions = Prettify<{
+    /** The method to use for determining which entries are stale. `recency` = least recently used, `frequency` = least frequently used, `relevance` = combination of both (default). */
+    method?: "relevance" | "recency" | "frequency";
+    /** Maximum time to live for the data in this tier in seconds. */
+    ttl?: number;
+    /** Maximum amount of entries to keep in this tier. */
+    amount?: number;
+    /** The index of the cache tier to send the entry to when it goes stale. Defaults to the next available tier, or deletes the entry if there is none. */
+    sendToTier?: number;
+}>;
+/** Options for entry propagation between {@linkcode TieredCache} tiers. */
+export type TieredCachePropagateTierOptions = Prettify<{
+    /** The index of the cache tier to propagate the entry to. Use negative numbers for accessing from the end, just like `Array.prototype.at()`. Use `1` for the second tier, use `-1` for the last. */
+    index: number;
+    /** Whether to propagate created entries to the cache with this index. Defaults to true. */
+    created?: boolean;
+    /** Whether to propagate updated entries to the cache with this index. Defaults to true. */
+    updated?: boolean;
+    /** Whether to propagate deleted entries to the cache with this index. Defaults to true. */
+    deleted?: boolean;
+    /** Whether to propagate accessed entries to the cache with this index. Defaults to true. */
+    accessed?: boolean;
+}>;
+/** Options for each {@linkcode TieredCache} tier. */
+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!**  
+     */
+    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. */
+    compressionFormat?: CompressionFormat | null;
+    /** Options for when an entry goes stale, making it move to a lower tier or get fully deleted. */
+    staleOptions?: TieredCacheStaleOptions;
+    /** To which tiers to propagate created and updated entries. Defaults to the next tier and all properties set to their default. */
+    propagateTiers?: TieredCachePropagateTierOptions[];
+}>;
+/** Events that can be emitted by the {@linkcode TieredCache} class. */
+export type TieredCacheEventMap = {};
+/**
+ * Cache class that can have multiple tiers with different max TTLs, with data being moved between tiers based on what is fetched the most.  
+ * Persists data using DataStore and DataStoreEngines.  
+ * The zeroth tier contains the most accessed data, and the last tier contains the least accessed data, so it is recommended to use slower storage engines for the last tier(s).  
+ */
+export declare class TieredCache<TData extends DataStoreData> extends NanoEmitter<TieredCacheEventMap> {
+    protected options: TieredCacheOptions<TData>;
+    protected stores: Map<number, DataStore<TData>>;
+    /**
+     * Creates a new TieredCache instance.  
+     * It is a cache that can have multiple tiers with different max TTLs, with data being moved between tiers based on what is fetched the most.  
+     * It persists data using DataStore and DataStoreEngines.  
+     * The zeroth tier contains the most accessed data, and the last tier contains the least accessed data, so it is recommended to use slower storage engines for the last tier(s).  
+     * If the given {@linkcode options} are invalid, a {@linkcode ValidationError} is thrown.  
+     */
+    constructor(options: TieredCacheOptions<TData>);
+    /** Validates the options for this cache and throws an Error containing all problems if they're invalid. Should be called once in the constructor. */
+    protected validateOptions(opts: TieredCacheOptions<TData>): void;
+    get(matching: string | ((tier: TieredCacheTierOptions<TData>) => boolean)): Promise<TData | undefined>;
+    upsert(matching: string | ((tier: TieredCacheTierOptions<TData>) => boolean), data: TData): Promise<boolean>;
+    /** Loads all persistent data from all tiers and initializes the DataStore instances. */
+    loadData(): Promise<PromiseSettledResult<TData>[]>;
+    /** Returns the options for the specified tier, after filling in all defaults. */
+    protected resolveTierOpts(index: number): Prettify<TieredCacheResolvedTierOpts<TData>> | undefined;
+}
+export {};