/**
 * Selector Query Cache System
 *
 * A reference-counted cache system for expensive selector operations.
 * Based on Playwright's caching pattern from packages/injected/src/selectorEvaluator.ts.
 *
 * This cache improves performance when the same selectors are queried multiple times
 * within a single operation (e.g., during accessibility tree construction).
 *
 * Usage:
 * ```ts
 * beginSelectorCaches();
 * try {
 *   // Multiple calls with same selector will use cached results
 *   const el1 = querySelector(root, '.btn');
 *   const el2 = querySelector(root, '.btn'); // Returns cached result
 * } finally {
 *   endSelectorCaches();
 * }
 *
 * // Or use the helper:
 * withSelectorCache(() => {
 *   const el = querySelector(root, '.btn');
 * });
 * ```
 */
import type { SelectorRoot } from './engine.js';
/**
 * Cache key type combining selector and root element identifier.
 */
export type CacheKey = string;
/**
 * Create a cache key from selector and root element.
 * Uses a stable element identifier to enable cache hits across calls.
 *
 * @param selector - The selector string
 * @param root - The root element or document to query from
 * @returns A unique cache key string
 */
export declare function createCacheKey(selector: string, root: SelectorRoot): CacheKey;
/**
 * Cache statistics for monitoring and debugging.
 */
export interface SelectorCacheStats {
    /** Whether caching is currently active */
    active: boolean;
    /** Current nesting depth of cache sessions */
    depth: number;
    /** Number of cache hits for querySelector */
    queryHits: number;
    /** Number of cache misses for querySelector */
    queryMisses: number;
    /** Number of cache hits for querySelectorAll */
    queryAllHits: number;
    /** Number of cache misses for querySelectorAll */
    queryAllMisses: number;
    /** Number of cache hits for matches */
    matchesHits: number;
    /** Number of cache misses for matches */
    matchesMisses: number;
    /** Number of cache hits for text content */
    textHits: number;
    /** Number of cache misses for text content */
    textMisses: number;
    /** Number of entries in query cache */
    queryEntries: number;
    /** Number of entries in queryAll cache */
    queryAllEntries: number;
    /** Number of entries in matches cache */
    matchesEntries: number;
    /** Number of entries in text cache */
    textEntries: number;
}
/**
 * Selector query cache manager with reference counting.
 *
 * Manages caches for different query patterns:
 * - query: Single element results from querySelector
 * - queryAll: Array results from querySelectorAll
 * - matches: Boolean results from element.matches()
 * - text: Cached text content for elements
 */
export declare class SelectorCacheManager {
    private cacheCounter;
    private queryCache;
    private queryAllCache;
    private matchesCache;
    private textCache;
    private _queryHits;
    private _queryMisses;
    private _queryAllHits;
    private _queryAllMisses;
    private _matchesHits;
    private _matchesMisses;
    private _textHits;
    private _textMisses;
    /**
     * Begin a caching session. Can be nested.
     * Each begin() must be paired with an end() call.
     */
    begin(): void;
    /**
     * End a caching session. Clears caches when counter reaches 0.
     */
    end(): void;
    /**
     * Check if caching is currently active.
     */
    isActive(): boolean;
    /**
     * Get cached query result or execute and cache.
     *
     * @param key - Cache key from createCacheKey
     * @param executor - Function to execute if not cached
     * @returns The cached or newly computed result
     */
    cachedQuery(key: CacheKey, executor: () => Element | null): Element | null;
    /**
     * Get cached queryAll result or execute and cache.
     *
     * @param key - Cache key from createCacheKey
     * @param executor - Function to execute if not cached
     * @returns The cached or newly computed result array
     */
    cachedQueryAll(key: CacheKey, executor: () => Element[]): Element[];
    /**
     * Get cached matches result or execute and cache.
     *
     * @param key - Cache key (typically element + selector based)
     * @param executor - Function to execute if not cached
     * @returns The cached or newly computed boolean result
     */
    cachedMatches(key: CacheKey, executor: () => boolean): boolean;
    /**
     * Get cached text content or compute and cache.
     *
     * @param element - The element to get text content for
     * @param executor - Function to compute text if not cached
     * @returns The cached or newly computed text content
     */
    cachedText(element: Element, executor: () => string): string;
    /**
     * Get cache statistics for debugging.
     */
    getStats(): SelectorCacheStats;
    /**
     * Clear all caches immediately, regardless of reference count.
     * Resets the counter to 0.
     */
    clearAll(): void;
}
/**
 * Global selector cache manager instance.
 */
export declare const selectorCache: SelectorCacheManager;
/**
 * Begin selector caching session.
 * Calls can be nested (reference counted).
 */
export declare function beginSelectorCaches(): void;
/**
 * End selector caching session.
 * When counter reaches 0, caches are cleared.
 */
export declare function endSelectorCaches(): void;
/**
 * Check if selector caching is currently active.
 */
export declare function isSelectorCachingActive(): boolean;
/**
 * Get selector cache statistics.
 */
export declare function getSelectorCacheStats(): SelectorCacheStats;
/**
 * Execute function within a cache session.
 * Automatically calls begin/end.
 *
 * @param fn - The function to execute within the cache session
 * @returns The return value of the function
 * @throws Re-throws any error from the function after clearing cache
 *
 * @example
 * ```ts
 * const result = withSelectorCache(() => {
 *   const btn = querySelector(root, 'button');
 *   const inputs = querySelectorAll(root, 'input');
 *   return { btn, inputs };
 * });
 * ```
 */
export declare function withSelectorCache<T>(fn: () => T): T;
/**
 * Async version of withSelectorCache.
 * Execute an async function within a cache session.
 *
 * Note: Be careful with long-running async operations as the cache
 * will persist until the promise resolves/rejects. This is typically
 * fine for batch DOM operations but may cause stale data if the DOM
 * changes during the async operation.
 *
 * @param fn - The async function to execute within the cache session
 * @returns A promise that resolves to the return value of the function
 * @throws Re-throws any error from the function after clearing cache
 *
 * @example
 * ```ts
 * const results = await withSelectorCacheAsync(async () => {
 *   const items = querySelectorAll(root, '.item');
 *   return Promise.all(items.map(processItem));
 * });
 * ```
 */
export declare function withSelectorCacheAsync<T>(fn: () => Promise<T>): Promise<T>;
/**
 * Clear all selector caches immediately.
 * Use for cleanup in error scenarios or tests.
 */
export declare function clearSelectorCaches(): void;
//# sourceMappingURL=cache.d.ts.map