dom-track/dist/index.d.ts

Fluent utility to track DOM elements as they appear, change, or get removed — using both callback and Promise-based APIs.

interface DomTrackOptions {
    observeChildList?: boolean;
    observeAttributes?: boolean;
    observeCharacterData?: boolean;
    observeSubtree?: boolean;
    debounceMs?: number | null;
    waitForTimeoutMs?: number;
    signal?: AbortSignal;
}
type InternalDomTrackOptions = Required<Omit<DomTrackOptions, "signal" | "debounceMs">> & Pick<DomTrackOptions, "signal"> & {
    debounceMs: number | null;
};
type WatchCallback = (el: HTMLElement, container: HTMLElement) => void;
type RemoveCallback = (el: HTMLElement, container: HTMLElement) => void;
interface WatchHandle {
    cancel(): void;
}

declare class WatchPromise<T = HTMLElement> implements PromiseLike<T> {
    private watchSetup;
    private timeoutMs?;
    private timeoutCallback?;
    private signal?;
    private isOnce;
    private watchHandle?;
    private promise;
    private isSetupComplete;
    constructor(watchSetup: (resolve: (value: T) => void, reject: (err: any) => void) => WatchHandle);
    once(): this;
    timeout(ms: number, onTimeout?: () => void): this;
    abortSignal(signal: AbortSignal): this;
    private createPromise;
    private setupTimeoutAndAbort;
    private ensureSetup;
    then<TResult1 = T, TResult2 = never>(onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | undefined | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined | null): Promise<TResult1 | TResult2>;
    catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | undefined | null): Promise<T | TResult>;
    finally(onfinally?: (() => void) | undefined | null): Promise<T>;
    readonly [Symbol.toStringTag] = "Promise";
}

declare class DomTrack {
    private observer;
    protected container: HTMLElement;
    protected bufferedAdditions: MutationRecord[];
    protected debounceAdditions: () => void;
    protected options: InternalDomTrackOptions;
    private trackRegistry;
    constructor(container: HTMLElement, options?: DomTrackOptions);
    protected attachObserver(): void;
    protected ensureObserver(): void;
    protected handleMutations: (mutations: MutationRecord[]) => void;
    protected processRemovals(nodes: NodeList | Node[]): void;
    private processAdditions;
    protected handleBufferedAdditions(): void;
    protected triggerRemoveCallbacks(el: HTMLElement): void;
    protected checkForCleanup(): void;
    seen(selector: string, cb: WatchCallback): WatchHandle;
    seen(selector: string): WatchPromise<HTMLElement>;
    changed(selector: string, cb: WatchCallback): WatchHandle;
    changed(selector: string): WatchPromise<HTMLElement>;
    gone(selector: string, cb: RemoveCallback): WatchHandle;
    goneForElement(el: HTMLElement, cb: RemoveCallback): void;
    disconnect(): void;
}
/**
 * Faster observer only for element removal tracking as the removal observer is usually attached to the whole body
 */
declare class DomTrackRemovals extends DomTrack {
    constructor(container: HTMLElement, options?: Omit<DomTrackOptions, "observeAttributes" | "debounceMs" | "waitForTimeoutMs">);
    protected handleMutations: (mutations: MutationRecord[]) => void;
    seen(_1?: any, _2?: any): any;
    changed(_1?: any, _2?: any): any;
}

export { DomTrack, type DomTrackOptions, DomTrackRemovals, type RemoveCallback, type WatchCallback, type WatchHandle };