@sv443-network/userutils 8.3.3 → 9.0.0

package/dist/lib/DataStore.d.ts

@@ -1,67 +1,64 @@
-/// <reference types="greasemonkey" />
 import type { Prettify } 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>;
+export type DataMigrationsDict = Record<number, ((oldData: unknown) => unknown | Promise<unknown>)>;
 /** Options for the DataStore instance */
 export type DataStoreOptions<TData> = 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.
+     * 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.
+     * 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!
+     * 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;
     /**
-     * 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.
+     * 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.
+     * 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[];
     /**
-     * Where the data should be saved (`"GM"` by default).
-     * The protected methods {@linkcode DataStore.getValue()}, {@linkcode DataStore.setValue()}  and {@linkcode DataStore.deleteValue()} are used to interact with the storage.
-     * `"GM"` storage, `"localStorage"` and `"sessionStorage"` are supported out of the box, but in an extended class you can overwrite those methods to implement any other storage method.
+     * Where the data should be saved (`"GM"` by default).  
+     * The protected methods {@linkcode DataStore.getValue()}, {@linkcode DataStore.setValue()}  and {@linkcode DataStore.deleteValue()} are used to interact with the storage.  
+     * `"GM"` storage, `"localStorage"` and `"sessionStorage"` are supported out of the box, but in an extended class you can overwrite those methods to implement any other storage method.  
      */
     storageMethod?: "GM" | "localStorage" | "sessionStorage";
 } & ({
     /**
-     * Function to use to encode the data prior to saving it in persistent storage.
-     * If this is specified, make sure to declare {@linkcode decodeData()} as well.
-     *
-     * You can make use of UserUtils' [`compress()`](https://github.com/Sv443-Network/UserUtils?tab=readme-ov-file#compress) function 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)
+     * Function to use to encode the data prior to saving it in persistent storage.  
+     * If this is specified, make sure to declare {@linkcode decodeData()} as well.  
+     *  
+     * You can make use of UserUtils' [`compress()`](https://github.com/Sv443-Network/UserUtils?tab=readme-ov-file#compress) function 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: (data: string) => string | Promise<string>;
     /**
-     * Function to use to decode the data after reading it from persistent storage.
-     * If this is specified, make sure to declare {@linkcode encodeData()} as well.
-     *
-     * You can make use of UserUtils' [`decompress()`](https://github.com/Sv443-Network/UserUtils?tab=readme-ov-file#decompress) function 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)
+     * Function to use to decode the data after reading it from persistent storage.  
+     * If this is specified, make sure to declare {@linkcode encodeData()} as well.  
+     *  
+     * You can make use of UserUtils' [`decompress()`](https://github.com/Sv443-Network/UserUtils?tab=readme-ov-file#decompress) function 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: (data: string) => string | Promise<string>;
 } | {
@@ -69,18 +66,18 @@ export type DataStoreOptions<TData> = Prettify<{
     decodeData?: never;
 })>;
 /**
- * Manages a hybrid synchronous & asynchronous persistent JSON database that is cached in memory and persistently saved across sessions using [GM storage](https://wiki.greasespot.net/GM.setValue) (default), [localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) or [sessionStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage).
- * 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 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.
- *
- * ⚠️ The stored data has to be **serializable using `JSON.stringify()`**, meaning no undefined, circular references, etc. are allowed.
- * ⚠️ If the storageMethod is left as the default of `"GM"` the directives `@grant GM.getValue` and `@grant GM.setValue` are required. If you then also use the method {@linkcode DataStore.deleteData()}, the extra directive `@grant GM.deleteValue` is needed too.
- * ⚠️ 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)
+ * Manages a hybrid synchronous & asynchronous persistent JSON database that is cached in memory and persistently saved across sessions using [GM storage](https://wiki.greasespot.net/GM.setValue) (default), [localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) or [sessionStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage).  
+ * 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.  
+ * - ⚠️ If the storageMethod is left as the default of `"GM"`, the directives `@grant GM.getValue` and `@grant GM.setValue` are required. If you then also use the method {@linkcode DataStore.deleteData()}, the extra directive `@grant GM.deleteValue` is needed too.  
+ * - ⚠️ 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)  
  */
 export declare class DataStore<TData extends object = object> {
     readonly id: string;
@@ -93,26 +90,26 @@ export declare class DataStore<TData extends object = object> {
     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 options The options for this DataStore instance
+     * 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 options The options for this DataStore instance  
      */
     constructor(options: DataStoreOptions<TData>);
     /**
-     * Loads the data saved in persistent storage into the in-memory cache and also returns 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.
+     * Loads the data saved in persistent storage into the in-memory cache and also returns 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).
-     * @param deepCopy Whether to return a deep copy of the data (default: `false`) - only necessary if your data object is nested and may have a bigger performance impact if enabled
+     * 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).  
+     * @param deepCopy Whether to return a deep copy of the data (default: `false`) - only necessary if your data object is nested and may have a bigger performance impact if enabled  
      */
     getData(deepCopy?: boolean): TData;
     /** Saves the data synchronously to the in-memory cache and asynchronously to the persistent storage */
@@ -120,26 +117,26 @@ export declare class DataStore<TData extends object = object> {
     /** 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"`
+     * 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.
+     * 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: any, oldFmtVer: number, resetOnError?: boolean): Promise<TData>;
+    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.
+     * 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>;
     /** Serializes the data using the optional this.encodeData() and returns it as a string */
@@ -148,14 +145,13 @@ export declare class DataStore<TData extends object = object> {
     protected deserializeData(data: string, useEncoding?: boolean): Promise<TData>;
     /** Copies a JSON-compatible object and loses all its internal references in the process */
     protected deepCopy<T>(obj: T): T;
-    /** Gets a value from persistent storage - can be overwritten in a subclass if you want to use something other than GM storage */
+    /** Gets a value from persistent storage - can be overwritten in a subclass if you want to use something other than the default storage methods */
     protected getValue<TValue extends GM.Value = string>(name: string, defaultValue: TValue): Promise<string | TValue>;
     /**
-     * Sets a value in persistent storage - can be overwritten in a subclass if you want to use something other than GM storage.
-     * The default storage engines will stringify all passed values like numbers or booleans, so be aware of that.
+     * Sets a value in persistent storage - can be overwritten in a subclass if you want to use something other than the default storage methods.  
+     * The default storage engines will stringify all passed values like numbers or booleans, so be aware of that.  
      */
     protected setValue(name: string, value: GM.Value): Promise<void>;
-    /** Deletes a value from persistent storage - can be overwritten in a subclass if you want to use something other than GM storage */
+    /** Deletes a value from persistent storage - can be overwritten in a subclass if you want to use something other than the default storage methods */
     protected deleteValue(name: string): Promise<void>;
 }
-export {};

package/dist/lib/DataStoreSerializer.d.ts

@@ -26,12 +26,12 @@ export type LoadStoresDataResult = {
     data: object;
 };
 /**
- * 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.
+ * 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 {
     protected stores: DataStore[];
@@ -44,21 +44,21 @@ export declare class DataStoreSerializer {
     /** Serializes the data stores into a string */
     serialize(): Promise<string>;
     /**
-     * Deserializes the data exported via {@linkcode serialize()} and imports it into the DataStore instances.
-     * Also triggers the migration process if the data format has changed.
+     * Deserializes the data exported via {@linkcode serialize()} and imports it into the DataStore instances.  
+     * Also triggers the migration process if the data format has changed.  
      */
     deserialize(serializedData: string): 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.
-     * @returns Returns a PromiseSettledResult array with the results of each DataStore instance in the format `{ id: string, data: object }`
+     * Loads the persistent data of the DataStore instances into the in-memory cache.  
+     * Also triggers the migration process if the data format has changed.  
+     * @returns Returns a PromiseSettledResult array with the results of each DataStore instance in the format `{ id: string, data: object }`  
      */
     loadStoresData(): Promise<PromiseSettledResult<LoadStoresDataResult>[]>;
     /** Resets the persistent data of the DataStore instances to their default values. */
     resetStoresData(): Promise<PromiseSettledResult<void>[]>;
     /**
-     * Deletes the persistent data of the DataStore instances.
-     * Leaves the in-memory data untouched.
+     * Deletes the persistent data of the DataStore instances.  
+     * Leaves the in-memory data untouched.  
      */
     deleteStoresData(): Promise<PromiseSettledResult<void>[]>;
 }

package/dist/lib/Debouncer.d.ts

@@ -0,0 +1,77 @@
+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";
+export type DebouncerFunc<TArgs> = (...args: TArgs[]) => void | unknown;
+/** Event map for the {@linkcode Debouncer} */
+export type DebouncerEventMap<TArgs> = {
+    /** Emitted when the debouncer calls all registered listeners, as a pub-sub alternative */
+    call: DebouncerFunc<TArgs>;
+    /** 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<TArgs> extends NanoEmitter<DebouncerEventMap<TArgs>> {
+    protected timeout: number;
+    protected type: DebouncerType;
+    /** All registered listener functions and the time they were attached */
+    protected listeners: DebouncerFunc<TArgs>[];
+    /** The currently active timeout */
+    protected activeTimeout: ReturnType<typeof setTimeout> | undefined;
+    /** The latest queued call */
+    protected queuedCall: DebouncerFunc<TArgs> | 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: DebouncerFunc<TArgs>): void;
+    /** Removes the listener with the specified function reference */
+    removeListener(fn: DebouncerFunc<TArgs>): void;
+    /** Removes all listeners */
+    removeAllListeners(): void;
+    /** 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: TArgs[]): 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 DebouncerFunc<TArgs>, TArgs>(fn: TFunc, timeout?: number, type?: DebouncerType): DebouncerFunc<TArgs> & {
+    debouncer: Debouncer<TArgs>;
+};

package/dist/lib/Dialog.d.ts

@@ -71,8 +71,8 @@ export declare class Dialog extends NanoEmitter<{
     /** Clears the DOM of the dialog and then renders it again */
     remount(): Promise<void>;
     /**
-     * Opens the dialog - also mounts it if it hasn't been mounted yet
-     * Prevents default action and immediate propagation of the passed event
+     * Opens the dialog - also mounts it if it hasn't been mounted yet  
+     * Prevents default action and immediate propagation of the passed event  
      */
     open(e?: MouseEvent | KeyboardEvent): Promise<HTMLElement | void>;
     /** Closes the dialog - prevents default action and immediate propagation of the passed event */
@@ -91,9 +91,9 @@ export declare class Dialog extends NanoEmitter<{
     /** Called once to attach all generic event listeners */
     protected attachListeners(bgElem: HTMLElement): void;
     /**
-     * Adds generic, accessible interaction listeners to the passed element.
-     * All listeners have the default behavior prevented and stop propagation (for keyboard events only as long as the captured key is valid).
-     * @param listenerOptions Provide a {@linkcode listenerOptions} object to configure the listeners
+     * Adds generic, accessible interaction listeners to the passed element.  
+     * All listeners have the default behavior prevented and stop propagation (for keyboard events only as long as the captured key is valid).  
+     * @param listenerOptions Provide a {@linkcode listenerOptions} object to configure the listeners  
      */
     protected onInteraction<TElem extends HTMLElement>(elem: TElem, listener: (evt: MouseEvent | KeyboardEvent) => void, listenerOptions?: AddEventListenerOptions & {
         preventDefault?: boolean;

package/dist/lib/SelectorObserver.d.ts

@@ -1,35 +1,33 @@
+import { type DebouncerType } from "./Debouncer.js";
 import type { Prettify } from "./types.js";
 /** Options for the `onSelector()` method of {@linkcode SelectorObserver} */
 export type SelectorListenerOptions<TElem extends Element = HTMLElement> = Prettify<SelectorOptionsOne<TElem> | SelectorOptionsAll<TElem>>;
-type SelectorOptionsOne<TElem extends Element> = SelectorOptionsCommon & {
+export type SelectorOptionsOne<TElem extends Element> = SelectorOptionsCommon & {
     /** Whether to use `querySelectorAll()` instead - default is false */
     all?: false;
     /** Gets called whenever the selector was found in the DOM */
     listener: (element: TElem) => void;
 };
-type SelectorOptionsAll<TElem extends Element> = SelectorOptionsCommon & {
+export type SelectorOptionsAll<TElem extends Element> = SelectorOptionsCommon & {
     /** Whether to use `querySelectorAll()` instead - default is false */
     all: true;
     /** Gets called whenever the selector was found in the DOM */
     listener: (elements: NodeListOf<TElem>) => void;
 };
-type SelectorOptionsCommon = {
+export type SelectorOptionsCommon = {
     /** Whether to call the listener continuously instead of once - default is false */
     continuous?: boolean;
     /** Whether to debounce the listener to reduce calls to `querySelector` or `querySelectorAll` - set undefined or <=0 to disable (default) */
     debounce?: number;
-    /** Whether to call the function at the very first call ("rising" edge) or the very last call ("falling" edge, default) */
-    debounceEdge?: "rising" | "falling";
+    /** The edge type of the debouncer - default is "immediate" - refer to {@linkcode Debouncer} for more info */
+    debounceType?: DebouncerType;
 };
-type UnsubscribeFunction = () => void;
+export type UnsubscribeFunction = () => void;
 export type SelectorObserverOptions = {
     /** If set, applies this debounce in milliseconds to all listeners that don't have their own debounce set */
     defaultDebounce?: number;
-    /**
-     * If set, applies this debounce edge to all listeners that don't have their own set.
-     * Edge = Whether to call the function at the very first call ("rising" edge) or the very last call ("falling" edge, default)
-     */
-    defaultDebounceEdge?: "rising" | "falling";
+    /** If set, applies this debounce edge type to all listeners that don't have their own set - refer to {@linkcode Debouncer} for more info */
+    defaultDebounceType?: DebouncerType;
     /** Whether to disable the observer when no listeners are present - default is true */
     disableOnNoListeners?: boolean;
     /** Whether to ensure the observer is enabled when a new listener is added - default is true */
@@ -47,15 +45,15 @@ export declare class SelectorObserver {
     private customOptions;
     private listenerMap;
     /**
-     * Creates a new SelectorObserver that will observe the children of the given base element selector for changes (only creation and deletion of elements by default)
-     * @param baseElementSelector The selector of the element to observe
-     * @param options Fine-tune what triggers the MutationObserver's checking function - `subtree` and `childList` are set to true by default
+     * Creates a new SelectorObserver that will observe the children of the given base element selector for changes (only creation and deletion of elements by default)  
+     * @param baseElementSelector The selector of the element to observe  
+     * @param options Fine-tune what triggers the MutationObserver's checking function - `subtree` and `childList` are set to true by default  
      */
     constructor(baseElementSelector: string, options?: SelectorObserverConstructorOptions);
     /**
-     * Creates a new SelectorObserver that will observe the children of the given base element for changes (only creation and deletion of elements by default)
-     * @param baseElement The element to observe
-     * @param options Fine-tune what triggers the MutationObserver's checking function - `subtree` and `childList` are set to true by default
+     * Creates a new SelectorObserver that will observe the children of the given base element for changes (only creation and deletion of elements by default)  
+     * @param baseElement The element to observe  
+     * @param options Fine-tune what triggers the MutationObserver's checking function - `subtree` and `childList` are set to true by default  
      */
     constructor(baseElement: Element, options?: SelectorObserverConstructorOptions);
     /** Call to check all selectors in the {@linkcode listenerMap} using {@linkcode checkSelector()} */
@@ -63,22 +61,22 @@ export declare class SelectorObserver {
     /** Checks if the element(s) with the given {@linkcode selector} exist in the DOM and calls the respective {@linkcode listeners} accordingly */
     protected checkSelector(selector: string, listeners: SelectorListenerOptions[]): void;
     /**
-     * Starts observing the children of the base element for changes to the given {@linkcode selector} according to the set {@linkcode options}
-     * @param selector The selector to observe
-     * @param options Options for the selector observation
-     * @param options.listener Gets called whenever the selector was found in the DOM
-     * @param [options.all] Whether to use `querySelectorAll()` instead - default is false
-     * @param [options.continuous] Whether to call the listener continuously instead of just once - default is false
-     * @param [options.debounce] Whether to debounce the listener to reduce calls to `querySelector` or `querySelectorAll` - set undefined or <=0 to disable (default)
-     * @returns Returns a function that can be called to remove this listener more easily
+     * Starts observing the children of the base element for changes to the given {@linkcode selector} according to the set {@linkcode options}  
+     * @param selector The selector to observe  
+     * @param options Options for the selector observation  
+     * @param options.listener Gets called whenever the selector was found in the DOM  
+     * @param [options.all] Whether to use `querySelectorAll()` instead - default is false  
+     * @param [options.continuous] Whether to call the listener continuously instead of just once - default is false  
+     * @param [options.debounce] Whether to debounce the listener to reduce calls to `querySelector` or `querySelectorAll` - set undefined or <=0 to disable (default)  
+     * @returns Returns a function that can be called to remove this listener more easily  
      */
     addListener<TElem extends Element = HTMLElement>(selector: string, options: SelectorListenerOptions<TElem>): UnsubscribeFunction;
     /** Disables the observation of the child elements */
     disable(): void;
     /**
-     * Enables or reenables the observation of the child elements.
-     * @param immediatelyCheckSelectors Whether to immediately check if all previously registered selectors exist (default is true)
-     * @returns Returns true when the observation was enabled, false otherwise (e.g. when the base element wasn't found)
+     * Enables or reenables the observation of the child elements.  
+     * @param immediatelyCheckSelectors Whether to immediately check if all previously registered selectors exist (default is true)  
+     * @returns Returns true when the observation was enabled, false otherwise (e.g. when the base element wasn't found)  
      */
     enable(immediatelyCheckSelectors?: boolean): boolean;
     /** Returns whether the observation of the child elements is currently enabled */
@@ -86,13 +84,13 @@ export declare class SelectorObserver {
     /** Removes all listeners that have been registered with {@linkcode addListener()} */
     clearListeners(): void;
     /**
-     * Removes all listeners for the given {@linkcode selector} that have been registered with {@linkcode addListener()}
-     * @returns Returns true when all listeners for the associated selector were found and removed, false otherwise
+     * Removes all listeners for the given {@linkcode selector} that have been registered with {@linkcode addListener()}  
+     * @returns Returns true when all listeners for the associated selector were found and removed, false otherwise  
      */
     removeAllListeners(selector: string): boolean;
     /**
-     * Removes a single listener for the given {@linkcode selector} and {@linkcode options} that has been registered with {@linkcode addListener()}
-     * @returns Returns true when the listener was found and removed, false otherwise
+     * Removes a single listener for the given {@linkcode selector} and {@linkcode options} that has been registered with {@linkcode addListener()}  
+     * @returns Returns true when the listener was found and removed, false otherwise  
      */
     removeListener(selector: string, options: SelectorListenerOptions): boolean;
     /** Returns all listeners that have been registered with {@linkcode addListener()} */
@@ -100,4 +98,3 @@ export declare class SelectorObserver {
     /** Returns all listeners for the given {@linkcode selector} that have been registered with {@linkcode addListener()} */
     getListeners(selector: string): SelectorListenerOptions<HTMLElement>[] | undefined;
 }
-export {};

package/dist/lib/array.d.ts

@@ -3,8 +3,8 @@ export type NonEmptyArray<TArray = unknown> = [TArray, ...TArray[]];
 /** Returns a random item from the passed array */
 export declare function randomItem<TItem = unknown>(array: TItem[]): TItem | undefined;
 /**
- * Returns a tuple of a random item and its index from the passed array
- * Returns `[undefined, undefined]` if the passed array is empty
+ * Returns a tuple of a random item and its index from the passed array  
+ * Returns `[undefined, undefined]` if the passed array is empty  
  */
 export declare function randomItemIndex<TItem = unknown>(array: TItem[]): [item?: TItem, index?: number];
 /** Returns a random item from the passed array and mutates the array to remove the item */

package/dist/lib/colors.d.ts

@@ -1,21 +1,21 @@
 /**
- * Converts a hex color string in the format `#RRGGBB`, `#RRGGBBAA` (or even `RRGGBB` and `RGB`) to a tuple.
- * @returns Returns a tuple array where R, G and B are an integer from 0-255 and alpha is a float from 0 to 1, or undefined if no alpha channel exists.
+ * Converts a hex color string in the format `#RRGGBB`, `#RRGGBBAA` (or even `RRGGBB` and `RGB`) to a tuple.  
+ * @returns Returns a tuple array where R, G and B are an integer from 0-255 and alpha is a float from 0 to 1, or undefined if no alpha channel exists.  
  */
 export declare function hexToRgb(hex: string): [red: number, green: number, blue: number, alpha?: number];
 /** Converts RGB or RGBA number values to a hex color string in the format `#RRGGBB` or `#RRGGBBAA` */
 export declare function rgbToHex(red: number, green: number, blue: number, alpha?: number, withHash?: boolean, upperCase?: boolean): string;
 /**
- * Lightens a CSS color value (in #HEX, rgb() or rgba() format) by a given percentage.
- * Will not exceed the maximum range (00-FF or 0-255).
- * @returns Returns the new color value in the same format as the input
- * @throws Throws if the color format is invalid or not supported
+ * Lightens a CSS color value (in #HEX, rgb() or rgba() format) by a given percentage.  
+ * Will not exceed the maximum range (00-FF or 0-255).  
+ * @returns Returns the new color value in the same format as the input  
+ * @throws Throws if the color format is invalid or not supported  
  */
 export declare function lightenColor(color: string, percent: number, upperCase?: boolean): string;
 /**
- * Darkens a CSS color value (in #HEX, rgb() or rgba() format) by a given percentage.
- * Will not exceed the maximum range (00-FF or 0-255).
- * @returns Returns the new color value in the same format as the input
- * @throws Throws if the color format is invalid or not supported
+ * Darkens a CSS color value (in #HEX, rgb() or rgba() format) by a given percentage.  
+ * Will not exceed the maximum range (00-FF or 0-255).  
+ * @returns Returns the new color value in the same format as the input  
+ * @throws Throws if the color format is invalid or not supported  
  */
 export declare function darkenColor(color: string, percent: number, upperCase?: boolean): string;

package/dist/lib/crypto.d.ts

@@ -7,19 +7,19 @@ export declare function decompress(input: string | ArrayBuffer, compressionForma
 /** Decompresses a previously compressed base64 string or ArrayBuffer, with the format passed by {@linkcode compressionFormat}, converted to an ArrayBuffer */
 export declare function decompress(input: string | ArrayBuffer, compressionFormat: CompressionFormat, outputType: "arrayBuffer"): Promise<ArrayBuffer>;
 /**
- * Creates a hash / checksum of the given {@linkcode input} string or ArrayBuffer 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.
+ * Creates a hash / checksum of the given {@linkcode input} string or ArrayBuffer 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>;
 /**
- * Generates a random ID with the specified length and radix (16 characters and hexadecimal by default)
- *
- * ⚠️ Not suitable for generating anything related to cryptography! Use [SubtleCrypto's `generateKey()`](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/generateKey) for that instead.
- * @param length The length of the ID to generate (defaults to 16)
- * @param radix The [radix](https://en.wikipedia.org/wiki/Radix) of each digit (defaults to 16 which is hexadecimal. Use 2 for binary, 10 for decimal, 36 for alphanumeric, etc.)
- * @param enhancedEntropy If set to true, uses [`crypto.getRandomValues()`](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues) for better cryptographic randomness (this also makes it take longer to generate)
- * @param randomCase If set to false, the generated ID will be lowercase only - also makes use of the `enhancedEntropy` parameter unless the output doesn't contain letters
+ * Generates a random ID with the specified length and radix (16 characters and hexadecimal by default)  
+ *  
+ * - ⚠️ Not suitable for generating anything related to cryptography! Use [SubtleCrypto's `generateKey()`](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/generateKey) for that instead.  
+ * @param length The length of the ID to generate (defaults to 16)  
+ * @param radix The [radix](https://en.wikipedia.org/wiki/Radix) of each digit (defaults to 16 which is hexadecimal. Use 2 for binary, 10 for decimal, 36 for alphanumeric, etc.)  
+ * @param enhancedEntropy If set to true, uses [`crypto.getRandomValues()`](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues) for better cryptographic randomness (this also makes it take longer to generate)  
+ * @param randomCase If set to false, the generated ID will be lowercase only - also makes use of the `enhancedEntropy` parameter unless the output doesn't contain letters  
  */
 export declare function randomId(length?: number, radix?: number, enhancedEntropy?: boolean, randomCase?: boolean): string;