/**
 * WebCache — URL content caching with TTL-based expiration and LRU eviction.
 *
 * Provides an in-memory cache for fetched URL content with configurable
 * time-to-live and maximum size constraints. Entries are evicted in
 * oldest-first (LRU-style by insertion time) order when the cache
 * exceeds its configured size budget.
 *
 * Designed to be sandbox-safe: no Node.js-specific APIs are used for
 * size estimation — content size is approximated using UTF-16 char width.
 */
/**
 * A single cached response for a URL.
 */
export interface CacheEntry {
    /** The normalized URL used as the cache key. */
    url: string;
    /** The response body content. */
    content: string;
    /** MIME type of the cached content (e.g. "text/html"). */
    contentType: string;
    /** HTTP status code of the original response. */
    statusCode: number;
    /** Timestamp (ms since epoch) when this entry was stored. */
    cachedAt: number;
    /** Time-to-live in milliseconds for this specific entry. */
    ttlMs: number;
    /** Approximate size of `content` in bytes. */
    sizeBytes: number;
}
/**
 * Configuration options for the WebCache instance.
 */
export interface WebCacheOptions {
    /**
     * Default time-to-live in milliseconds for cached entries.
     * Individual entries can override this value.
     * @default 900_000 (15 minutes)
     */
    defaultTtlMs?: number;
    /**
     * Maximum total size of cached content in bytes.
     * When exceeded, the oldest entries are evicted first.
     * @default 52_428_800 (50 MB)
     */
    maxCacheSizeBytes?: number;
}
/**
 * In-memory URL content cache with TTL expiration and size-bounded LRU eviction.
 *
 * Thread-safety note: This class is designed for single-threaded JS runtimes.
 * No internal locking is provided.
 */
export declare class WebCache {
    private readonly defaultTtlMs;
    private readonly maxCacheSizeBytes;
    /**
     * The backing store. We use a `Map` because it preserves insertion order,
     * which gives us a natural oldest-first iteration for eviction.
     */
    private readonly store;
    /** Running total of `sizeBytes` across all entries in the store. */
    private currentSizeBytes;
    /** Number of `get` / `has` calls that found a valid (non-expired) entry. */
    private hitCount;
    /** Number of `get` / `has` calls that did not find a valid entry. */
    private missCount;
    constructor(options?: WebCacheOptions);
    /**
     * Retrieve a cached entry for the given URL.
     *
     * Returns `null` (and records a miss) when:
     *  - The URL has never been cached.
     *  - The cached entry has expired according to its TTL.
     *
     * Expired entries are lazily removed on access.
     */
    get(url: string): CacheEntry | null;
    /**
     * Store a URL response in the cache.
     *
     * If the content size alone exceeds `maxCacheSizeBytes`, the entry is
     * still stored (after evicting everything else) so that oversized single
     * responses do not silently vanish — callers can observe them via `get`
     * until they expire.
     *
     * @param url     The URL to cache.
     * @param content The response body.
     * @param meta    Optional metadata for the cached entry.
     * @returns The newly created CacheEntry.
     */
    put(url: string, content: string, meta?: {
        contentType?: string;
        statusCode?: number;
        ttlMs?: number;
    }): CacheEntry;
    /**
     * Check whether a non-expired cache entry exists for the given URL.
     *
     * This method updates hit/miss counters identically to `get`.
     */
    has(url: string): boolean;
    /**
     * Remove a specific URL from the cache.
     *
     * @returns `true` if an entry was found and removed, `false` otherwise.
     */
    invalidate(url: string): boolean;
    /**
     * Remove all entries from the cache and reset counters.
     */
    clear(): void;
    /**
     * Return a snapshot of cache statistics.
     */
    stats(): {
        entries: number;
        totalSizeBytes: number;
        maxSizeBytes: number;
        hitCount: number;
        missCount: number;
    };
    /**
     * Determine whether an entry has exceeded its TTL.
     */
    private isExpired;
    /**
     * Remove a single entry from the store and update size accounting.
     */
    private removeEntry;
    /**
     * Evict oldest entries (by insertion order) until `requiredBytes` can fit
     * within the `maxCacheSizeBytes` budget.
     *
     * Expired entries encountered during eviction are removed regardless of
     * whether their removal is strictly necessary to reclaim space.
     */
    private evict;
    /**
     * Create a CacheEntry, run eviction if necessary, and insert it.
     */
    private insertEntry;
}
