@toolprint/hypertool-mcp/dist/persona/cache.d.ts

HyperTool MCP proxy server for routing requests between clients and multiple underlying MCP servers

/**
 * High-Performance Persona Cache System
 *
 * This module implements a comprehensive caching system for LoadedPersona objects
 * with TTL-based expiration, LRU eviction, memory management, and file system
 * monitoring for automatic invalidation. Designed for optimal performance with
 * minimal memory footprint and non-blocking operations.
 *
 * @fileoverview Advanced persona caching with performance monitoring and management
 */
import { EventEmitter } from "events";
import type { LoadedPersona, PersonaCacheConfig, PersonaCacheStats } from "./types.js";
/**
 * Cache eviction reasons for monitoring
 */
export declare enum EvictionReason {
    TTL_EXPIRED = "ttl_expired",
    LRU_EVICTION = "lru_eviction",
    MEMORY_LIMIT = "memory_limit",
    FILE_CHANGED = "file_changed",
    MANUAL_CLEAR = "manual_clear"
}
/**
 * Cache operation metrics for performance monitoring
 */
export interface CacheMetrics {
    /** Total cache operations */
    operations: number;
    /** Average lookup time in microseconds */
    averageLookupTime: number;
    /** Cache hit ratio over time windows */
    hitRatioHistory: number[];
    /** Memory usage over time */
    memoryUsageHistory: number[];
    /** Eviction counts by reason */
    evictionCounts: Record<EvictionReason, number>;
}
/**
 * Cache events for monitoring and integration
 */
export declare enum CacheEvents {
    CACHE_HIT = "cache:hit",
    CACHE_MISS = "cache:miss",
    CACHE_SET = "cache:set",
    CACHE_EVICTED = "cache:evicted",
    CACHE_CLEARED = "cache:cleared",
    FILE_CHANGED = "cache:file_changed",
    MEMORY_WARNING = "cache:memory_warning"
}
/**
 * High-performance PersonaCache with comprehensive features
 *
 * Features:
 * - TTL-based expiration with configurable defaults
 * - LRU eviction for memory management
 * - File system monitoring for auto-invalidation
 * - Memory usage tracking and limits
 * - Performance metrics and statistics
 * - Thread-safe operations
 * - Event emission for monitoring
 */
export declare class PersonaCache extends EventEmitter {
    private readonly config;
    private readonly cache;
    private readonly accessOrder;
    private stats;
    private metrics;
    private totalMemoryUsage;
    private operationCounter;
    private lookupTimes;
    private ttlCleanupInterval?;
    private metricsUpdateInterval?;
    constructor(config?: PersonaCacheConfig);
    /**
     * Get a cached persona with performance tracking
     */
    get(name: string, sourcePath?: string): LoadedPersona | null;
    /**
     * Set a persona in the cache with file system monitoring
     */
    set(persona: LoadedPersona): void;
    /**
     * Check if a persona is cached
     */
    has(name: string, sourcePath?: string): boolean;
    /**
     * Remove a specific persona from cache
     */
    delete(name: string, sourcePath?: string): boolean;
    /**
     * Clear all cached personas
     */
    clear(): void;
    /**
     * Get current cache statistics
     */
    getStats(): PersonaCacheStats;
    /**
     * Get detailed cache metrics
     */
    getMetrics(): CacheMetrics;
    /**
     * Get all cached persona names
     */
    getCachedPersonaNames(): string[];
    /**
     * Invalidate cache entries for a specific source path
     */
    invalidateByPath(sourcePath: string): number;
    /**
     * Refresh TTL for a cached persona
     */
    refreshTTL(name: string, sourcePath?: string, customTTL?: number): boolean;
    /**
     * Manually trigger cleanup of expired entries
     */
    cleanup(): void;
    /**
     * Cleanup and destroy cache
     */
    destroy(): void;
    /**
     * Create cache key for a persona
     */
    private createCacheKey;
    /**
     * Serialize cache key to string
     */
    private serializeCacheKey;
    /**
     * Deserialize cache key from string
     */
    private deserializeCacheKey;
    /**
     * Simple string hashing function
     */
    private hashString;
    /**
     * Setup file system watchers for auto-invalidation
     */
    private setupFileWatchers;
    /**
     * Handle file system changes
     */
    private handleFileChange;
    /**
     * Evict a cache entry with cleanup
     */
    private evictEntry;
    /**
     * Update access order for LRU
     */
    private updateAccessOrder;
    /**
     * Enforce memory limits with LRU eviction
     */
    private enforceMemoryLimits;
    /**
     * Enforce maximum cache size with LRU eviction
     */
    private enforceSizeLimit;
    /**
     * Estimate memory usage of a persona
     */
    private estimatePersonaMemoryUsage;
    /**
     * Record cache hit with statistics update
     */
    private recordCacheHit;
    /**
     * Record cache miss with statistics update
     */
    private recordCacheMiss;
    /**
     * Update hit rate calculation
     */
    private updateHitRate;
    /**
     * Update cache statistics
     */
    private updateStats;
    /**
     * Calculate average lookup time
     */
    private calculateAverageLookupTime;
    /**
     * Start background cleanup tasks
     */
    private startBackgroundTasks;
    /**
     * Stop background cleanup tasks
     */
    private stopBackgroundTasks;
    /**
     * Cleanup expired cache entries
     */
    private cleanupExpiredEntries;
    /**
     * Update metrics history for trending
     */
    private updateMetricsHistory;
}
/**
 * Create a persona cache with default configuration
 */
export declare function createPersonaCache(config?: PersonaCacheConfig): PersonaCache;
/**
 * Singleton cache instance for application-wide use
 */
export declare const defaultPersonaCache: PersonaCache;
/**
 * Cache factory for testing and multiple cache instances
 */
export declare class PersonaCacheFactory {
    private static instances;
    /**
     * Get or create a named cache instance
     */
    static getInstance(name: string, config?: PersonaCacheConfig): PersonaCache;
    /**
     * Destroy a named cache instance
     */
    static destroyInstance(name: string): boolean;
    /**
     * Destroy all cache instances
     */
    static destroyAll(): void;
    /**
     * Get all active cache instance names
     */
    static getActiveInstances(): string[];
}
//# sourceMappingURL=cache.d.ts.map