import type { CacheItem } from './types.ts';
/**
 * Unwraps a cache value, handling WeakRef if present.
 * Returns tuple: [value, wasGarbageCollected]
 *
 * @param value - Value to unwrap (may be WeakRef)
 * @returns Tuple of [unwrapped value, whether it was GC'd]
 */
export declare const unwrapValue: <T>(value: T | WeakRef<object>) => [T | undefined, boolean];
/**
 * Creates a cache item with metadata.
 *
 * @param value - Value to cache
 * @param createdAt - Creation timestamp
 * @param expiresAt - Expiration timestamp
 * @param useWeakRef - Whether to use WeakRef for objects
 * @param accessSequence - Monotonic sequence number
 * @returns Cache item with metadata
 */
export declare const createCacheItem: <T>(value: T, createdAt: number, expiresAt: number, useWeakRef: boolean, accessSequence: number) => CacheItem<T>;
/**
 * Checks if a cache item is expired.
 *
 * @param item - Cache item to check
 * @returns True if expired
 */
export declare const isExpired: <T>(item: CacheItem<T>) => boolean;
/**
 * Checks if a cache item is stale (older than staleIn but not expired).
 *
 * @param item - Cache item to check
 * @param staleIn - Staleness threshold in milliseconds
 * @returns True if stale but not expired
 */
export declare const isStale: <T>(item: CacheItem<T>, staleIn: number) => boolean;
/**
 * Updates access metadata for a cache item atomically.
 *
 * @param item - Cache item to update
 * @param sequence - New sequence number
 */
export declare const updateAccessMetadata: <T>(item: CacheItem<T>, sequence: number) => void;
/**
 * Symbol used for timeout racing in stale-while-revalidate.
 */
export declare const TIMEOUT_SYMBOL: unique symbol;
/**
 * Evicts the least recently used item from a cache.
 * Uses sequence number for tie-breaking when timestamps are identical.
 *
 * @param cache - Map to evict from
 * @returns Key of evicted item, or null if cache is empty
 */
export declare const evictLRU: <T>(cache: Map<string, CacheItem<T>>) => string | null;