/**
 * Cache Management and Lifetime Boundaries for JSON Schema Form System
 *
 * This module defines the caching strategy and lifetime boundaries for the JSON Schema
 * form system, ensuring optimal performance while maintaining thread safety and memory efficiency.
 */
import type { Ajv } from 'ajv';
/**
 * CACHING ARCHITECTURE DECISIONS:
 *
 * 1. AJV Instance Lifetime:
 *    - Each form creates its own AJV instance via getAjvForSchema()
 *    - AJV instances are NOT shared between forms to avoid:
 *      * Schema pollution (one form's schemas affecting another)
 *      * Concurrency issues in multi-threaded environments
 *      * Complex cache invalidation when schemas change
 *
 * 2. Validator Compilation Cache:
 *    - Keyed by: AJV instance -> Schema object identity
 *    - Lifetime: Lives as long as the AJV instance exists
 *    - Thread-safe: Uses WeakMap for automatic cleanup
 *    - Scope: Per-AJV instance (form-level isolation)
 *
 * 3. $ref Resolution Cache:
 *    - Keyed by: Root schema object -> Definition object
 *    - Lifetime: Lives as long as the root schema exists
 *    - Thread-safe: Uses WeakMap for automatic cleanup
 *    - Scope: Global (shared across forms for efficiency)
 *
 * 4. External Schema Cache:
 *    - Managed by AJV's internal addSchema() mechanism
 *    - Lifetime: Per-AJV instance
 *    - Scope: Form-level (each form has its own external schemas)
 */
export interface CacheManagementOptions {
    /**
     * Whether to clear all caches on initialization.
     * Useful for testing or when you want a clean slate.
     */
    clearOnInit?: boolean;
    /**
     * Whether to enable automatic cache cleanup.
     * When true, caches are cleared when forms are disposed.
     */
    autoCleanup?: boolean;
}
/**
 * Comprehensive cache clearing for all JSON Schema form caches.
 * This is the primary cache management function that should be used
 * for test isolation and memory management.
 *
 * WHEN TO USE:
 * - In test beforeEach/afterEach hooks
 * - When switching between different schema sets
 * - For memory management in long-running applications
 * - When you suspect cache corruption
 */
export declare function clearAllCaches(): void;
/**
 * Clear caches for a specific AJV instance only.
 * This provides fine-grained cache control when you want to
 * invalidate only one form's caches.
 *
 * WHEN TO USE:
 * - When a specific form's schema changes
 * - For targeted memory cleanup
 * - When debugging cache-related issues in a specific form
 */
export declare function clearCachesForForm(ajv: Ajv): void;
/**
 * Cache statistics and debugging information.
 * Useful for monitoring cache effectiveness and debugging performance issues.
 */
export interface CacheStats {
    /** Number of AJV instances with cached validators (approximate) */
    ajvInstances: number;
    /** Whether caches are enabled */
    enabled: boolean;
    /** Cache implementation details */
    implementation: {
        validatorCache: 'WeakMap<Ajv, WeakMap<object, ValidateFunction>>';
        refCache: 'WeakMap<object, WeakMap<object, JSONSchema>>';
        pointerCache: 'WeakMap<object, Map<string, unknown>>';
    };
}
/**
 * Get comprehensive cache statistics for monitoring and debugging.
 */
export declare function getCacheStats(): CacheStats;
/**
 * THREAD SAFETY GUARANTEES:
 *
 * 1. WeakMap Operations:
 *    - All cache operations use WeakMaps which are thread-safe for reads
 *    - Cache clearing uses atomic WeakMap reassignment
 *    - No explicit locking required
 *
 * 2. AJV Instance Isolation:
 *    - Each form gets its own AJV instance
 *    - No shared mutable state between forms
 *    - External schema registration is per-instance
 *
 * 3. Memory Management:
 *    - WeakMaps automatically cleanup when objects are garbage collected
 *    - No manual memory management required in normal operation
 *    - clearAllCaches() provides explicit cleanup for testing/debugging
 */
/**
 * PERFORMANCE CHARACTERISTICS:
 *
 * 1. Cache Hit Performance:
 *    - O(1) lookup for compiled validators
 *    - O(1) lookup for resolved $refs
 *    - Minimal overhead for cache checks
 *
 * 2. Cache Miss Performance:
 *    - AJV compilation: ~1-10ms per schema (depends on complexity)
 *    - $ref resolution: ~0.1-1ms per reference
 *    - External schema loading: Network-dependent
 *
 * 3. Memory Usage:
 *    - Compiled validators: ~1-10KB per schema
 *    - Resolved refs: ~100B-1KB per reference
 *    - Automatic cleanup via WeakMap garbage collection
 */
/**
 * RECOMMENDED USAGE PATTERNS:
 *
 * 1. Production Applications:
 *    - Let caches accumulate naturally
 *    - Use clearAllCaches() only for memory pressure
 *    - Monitor via getCacheStats() if needed
 *
 * 2. Testing:
 *    - Call clearAllCaches() in beforeEach hooks
 *    - Ensures test isolation
 *    - Prevents cache-related test flakiness
 *
 * 3. Development:
 *    - Use clearCachesForForm() when schema changes
 *    - Call clearAllCaches() when switching projects
 *    - Monitor cache stats for performance debugging
 */
export declare const CacheManagement: {
    readonly clearAll: typeof clearAllCaches;
    readonly clearForForm: typeof clearCachesForForm;
    readonly getStats: typeof getCacheStats;
};