tiny-essentials
Version:
Collection of small, essential scripts designed to be used across various projects. These simple utilities are crafted for speed, ease of use, and versatility.
145 lines • 5.06 kB
text/typescript
export default TinyElementObserver;
/**
* Callback type used for element mutation detectors.
*/
export type ElementDetectorsFn = (mutation: MutationRecord, index: number, mutations: MutationRecord[]) => void;
/**
* Callback type used for element mutation detectors.
*
* @callback ElementDetectorsFn
* @param {MutationRecord} mutation - Single mutation record being processed.
* @param {number} index - Index of the current mutation in the batch.
* @param {MutationRecord[]} mutations - Full list of mutation records from the observer callback.
* @returns {void}
*/
/**
* TinyElementObserver
*
* A utility class for tracking DOM element mutations.
* It leverages the native MutationObserver API, providing a higher-level abstraction
* with a system of configurable detectors that can dispatch custom events or run custom logic.
* @template {Element} HTMLElement
*/
declare class TinyElementObserver<HTMLElement extends Element> {
/**
* Create a new TinyElementObserver instance.
*
* @param {HTMLElement} el - Set the target element to be observed.
* @param {Object} [settings={}] - Configuration object.
* @param {Array<[string, ElementDetectorsFn]>} [settings.initDetectors=[]] - Optional initial detectors to register.
* @param {MutationObserverInit} [settings.initCfg] - Optional MutationObserver configuration.
*/
constructor(el: HTMLElement, { initDetectors, initCfg }?: {
initDetectors?: [string, ElementDetectorsFn][] | undefined;
initCfg?: MutationObserverInit | undefined;
});
/**
* Get the current element being observed.
* @returns {HTMLElement} The DOM element being tracked, or `undefined` if none is set.
*/
get el(): HTMLElement;
/**
* Set the observer settings.
* @param {MutationObserverInit} settings
*/
set settings(settings: MutationObserverInit);
/**
* Get the observer settings.
* @returns {MutationObserverInit}
*/
get settings(): MutationObserverInit;
/**
* Get the current MutationObserver instance.
* @returns {MutationObserver|null}
*/
get observer(): MutationObserver | null;
/**
* Set the element detectors.
* @param {Array<[string, ElementDetectorsFn]>} detectors
*/
set detectors(detectors: Array<[string, ElementDetectorsFn]>);
/**
* Get the element detectors.
* @returns {Array<[string, ElementDetectorsFn]>}
*/
get detectors(): Array<[string, ElementDetectorsFn]>;
/**
* Returns true if a MutationObserver is currently active.
* @returns {boolean}
*/
get isActive(): boolean;
/**
* Get the number of registered detectors.
*
* @returns {number} Total count of detectors.
*/
get size(): number;
/**
* Remove all registered detectors.
* After calling this, no mutation events will be processed
* until new detectors are added again.
*/
clear(): void;
/**
* Start tracking DOM mutations on the defined element.
*
* @throws {Error} If no element has been set to observe.
*/
start(): void;
/**
* Stop tracking changes.
*/
stop(): void;
/**
* Add a detector to the end of the array.
* @param {string} name
* @param {ElementDetectorsFn} handler
*/
add(name: string, handler: ElementDetectorsFn): void;
/**
* Add a detector to the start of the array.
* @param {string} name
* @param {ElementDetectorsFn} handler
*/
insertAtStart(name: string, handler: ElementDetectorsFn): void;
/**
* Insert a detector at a specific index.
* @param {number} index
* @param {string} name
* @param {ElementDetectorsFn} handler
* @param {'before'|'after'} position - Position relative to the index
*/
insertAt(index: number, name: string, handler: ElementDetectorsFn, position?: "before" | "after"): void;
/**
* Remove a detector at a specific index.
* @param {number} index
*/
removeAt(index: number): void;
/**
* Remove detectors relative to a specific index.
* @param {number} index - Reference index
* @param {number} before - Number of items before the index to remove
* @param {number} after - Number of items after the index to remove
*/
removeAround(index: number, before?: number, after?: number): void;
/**
* Check if a detector exists at a specific index.
* @param {number} index
* @returns {boolean}
*/
isIndexUsed(index: number): boolean;
/**
* Check if a handler function already exists in the array.
* @param {ElementDetectorsFn} handler
* @returns {boolean}
*/
hasHandler(handler: ElementDetectorsFn): boolean;
/**
* Completely destroy this observer instance.
* Stops the MutationObserver (if active) and clears all detectors,
* leaving the instance unusable until reconfigured.
*/
destroy(): void;
#private;
}
//# sourceMappingURL=TinyElementObserver.d.mts.map