/**
 * XPathEngine — Phase 14: XPath 1.0 subset engine  (v1.4 update)
 * ──────────────────────────────────────────────────────────────────
 * v1.4 additions (G22)
 * ─────────────────────
 *  • `compileXPath(expr)` — pre-parses an expression into a reusable
 *    CompiledXPath object.  Execution: `compiled.evaluate(context)`.
 *  • Expression compilation cache (LRU-bounded, default 512 entries).
 *  • `xpath()` now uses the cache automatically.
 *  • Bug fixes:
 *      - `xpath()` returns `XmlNode[]` not just elements (text() support)
 *      - Correct handling of text() node test in descendant axes
 *      - normalize-space() and string-length() work on context text()
 *
 * Supported axes
 * ──────────────
 *  child::           e.g.  child::book  or  book
 *  descendant-or-self::   //
 *  attribute::       @id
 *  self::            .
 *  parent::          ..
 *
 * Node tests
 * ──────────
 *  *              any element / attribute
 *  name           local-name match
 *  ns:name        namespace + local-name match
 *  text()         text nodes
 *  node()         any node
 *
 * Predicates
 * ──────────
 *  [n]            positional  (1-based)
 *  [@attr]        attribute existence
 *  [@attr="val"]  attribute value
 *  [@attr!="v"]   attribute not-equal
 *  [child]        child existence
 *  [last()]       last position
 *
 * Functions
 * ─────────
 *  text()        node test
 *  last()        in predicate
 *  position()    in predicate
 *  count(path)   child count
 *  normalize-space(x)
 *  contains(a,b)
 *  starts-with(a,b)
 *  string-length(a)
 *  not(expr)
 *
 * Usage
 * ─────
 *  import { xpath, compileXPath } from './XPathEngine';
 *  const books = xpath(doc.root!, '//book[@lang="en"]');
 *  const first = xpath.first(doc.root!, 'catalog/book');
 *
 *  // G22: pre-compile for reuse
 *  const expr  = compileXPath('//book[@lang="en"]');
 *  const books = expr.evaluate(doc.root!);
 */
import { XmlElement, XmlDocument } from './XmlNodes';
export type XPathContext = XmlElement | XmlDocument;
interface Step {
    axis: 'child' | 'descendant-or-self' | 'attribute' | 'self' | 'parent';
    nodeTest: string;
    predicates: Predicate[];
}
interface Predicate {
    raw: string;
}
/**
 * A pre-parsed, reusable XPath expression.
 * Created by `compileXPath(expr)` — never instantiate directly.
 */
export declare class CompiledXPath {
    /** The original expression string */
    readonly expression: string;
    /** Internal parsed steps */
    private readonly steps;
    constructor(expression: string, steps: Step[]);
    /** Execute against a context node, returning all matching nodes. */
    evaluate(context: XPathContext): XmlElement[];
    /** Return the first matching element, or null. */
    first(context: XPathContext): XmlElement | null;
    /** Return the count of matching elements. */
    count(context: XPathContext): number;
    /** Return the string value of the first match, or null. */
    string(context: XPathContext): string | null;
}
/**
 * Compile an XPath expression string into a reusable CompiledXPath.
 * Results are automatically cached (two-tier LRU, v1.7.0).
 */
export declare function compileXPath(expression: string): CompiledXPath;
/**
 * Clear the XPath expression cache (both tiers).
 */
export declare function clearXPathCache(): void;
/** Return the total number of cached expressions across both tiers. */
export declare function xpathCacheSize(): number;
/**
 * P2: Cache telemetry — returns hit/miss counters and current cache sizes.
 * Use with `--profile` CLI flag or for adaptive tuning decisions.
 * Counters are process-lifetime and can be reset with `clearXPathCache()`.
 */
export interface XPathCacheStats {
    hotHits: number;
    coldHits: number;
    misses: number;
    hotSize: number;
    coldSize: number;
}
export declare function xpathCacheStats(): XPathCacheStats;
/**
 * P2: Configurable XPath cache sizes.
 * Allows callers with different workload profiles to tune the two-tier LRU.
 *
 * @param coldMax Maximum entries in the cold (full LRU) tier. Default: 512.
 * @param hotMax  Maximum entries in the hot (MRU) tier. Default: 128.
 *
 * @example
 * // Large schema workload — increase cold tier
 * configureXPathCache({ coldMax: 2048, hotMax: 256 });
 */
export declare function configureXPathCache(opts: {
    coldMax?: number;
    hotMax?: number;
}): void;
/**
 * Evaluate an XPath expression and return all matching elements.
 * Uses the internal compile cache automatically (G22).
 */
export declare function xpath(context: XPathContext, expr: string): XmlElement[];
export declare namespace xpath {
    var first: (context: XPathContext, expr: string) => XmlElement | null;
    var count: (context: XPathContext, expr: string) => number;
    var string: (context: XPathContext, expr: string) => string | null;
}
export {};
//# sourceMappingURL=XPathEngine.d.ts.map