@juspay/neurolink/dist/mcp/caching/toolCache.d.ts

The pipe layer of an AI nervous system: one interface connecting provider neurons to your application, across three inference types — generate, stream and decide. `decide` returns typed, calibrated judgements from a non-generative model (~400ms, ~$0.00002

/**
 * Tool Cache - Caches tool results and server responses
 *
 * Provides intelligent caching for MCP tool calls to improve performance
 * and reduce redundant operations. Supports multiple eviction strategies:
 * - LRU (Least Recently Used)
 * - FIFO (First In, First Out)
 * - LFU (Least Frequently Used)
 */
import { EventEmitter } from "events";
import type { CacheStats, McpCacheConfig } from "../../types/index.js";
/**
 * Tool Cache - High-performance caching for MCP tool results
 *
 * @example
 * ```typescript
 * const cache = new ToolCache({
 *   ttl: 60000, // 1 minute
 *   maxSize: 500,
 *   strategy: 'lru',
 * });
 *
 * // Cache a tool result
 * cache.set('getUserById:123', { id: 123, name: 'John' });
 *
 * // Retrieve from cache
 * const user = cache.get('getUserById:123');
 *
 * // Invalidate by pattern
 * cache.invalidate('getUserById:*');
 * ```
 */
export declare class ToolCache<T = unknown> extends EventEmitter {
    private cache;
    private config;
    private stats;
    private cleanupTimer?;
    constructor(config: McpCacheConfig);
    /**
     * Get a value from the cache
     *
     * Returns an isolated copy of the stored value (see `cloneCachedValue`), so
     * a caller mutating what it gets back cannot corrupt the entry for later
     * hits or for other concurrent callers of the same key.
     */
    get(key: string): T | undefined;
    /**
     * Set a value in the cache
     *
     * Stores an isolated copy of `value` (see `cloneCachedValue`), so mutating
     * the caller's original object after this call cannot reach into the
     * cache entry.
     */
    set(key: string, value: T, ttl?: number): void;
    /**
     * Check if a key exists and is not expired
     */
    has(key: string): boolean;
    /**
     * Delete a specific key from the cache
     */
    delete(key: string): boolean;
    /**
     * Invalidate entries matching a pattern
     * Supports glob-style patterns with * wildcard
     */
    invalidate(pattern: string): number;
    /**
     * Clear all entries from the cache
     */
    clear(): void;
    /**
     * Get or set a value (cache-aside pattern)
     */
    getOrSet(key: string, factory: () => Promise<T> | T, ttl?: number): Promise<T>;
    /**
     * Get cache statistics
     */
    getStats(): CacheStats;
    /**
     * Reset statistics
     */
    resetStats(): void;
    /**
     * Get all keys in the cache
     */
    keys(): string[];
    /**
     * Get the number of entries in the cache
     */
    get size(): number;
    /**
     * Generate a cache key from tool name and arguments
     */
    static generateKey(toolName: string, args: unknown): string;
    /**
     * Stop the auto-cleanup timer
     */
    destroy(): void;
    /**
     * Isolate a value crossing the cache boundary (on write into the entry,
     * and on read back out of it) so no two callers — nor a caller and the
     * stored entry itself — ever share object identity.
     *
     * Without this, `set()` stored the caller's object by reference and
     * `get()` returned `entry.value` by the same reference on every hit: one
     * caller mutating a result it got back (e.g. an in-place truncation or
     * normalization pass) silently corrupted the entry for every later
     * caller of the same key for the rest of the TTL.
     *
     * `structuredClone` is the primary path — it is a deep copy, has no
     * caller-visible side effects, and (unlike a JSON round-trip) tolerates
     * circular references, which a sufficiently deep or recursive tool
     * result could contain. It throws on values it cannot clone (functions,
     * some non-plain class instances); the JSON round-trip fallback covers
     * that case for the plain-data shapes MCP tool results actually have
     * (text/JSON content arrays), at the cost of silently dropping
     * `undefined`, functions and symbol keys — acceptable for a cache that
     * only ever holds serializable tool results.
     */
    private cloneCachedValue;
    private getFullKey;
    private isExpired;
    /**
     * Delete a cache entry by its full key with a specific eviction reason.
     */
    private deleteWithReason;
    private evictOne;
    private selectEvictionCandidate;
    private findLRU;
    private findFIFO;
    private findLFU;
    private patternToRegex;
    private updateHitRate;
    private startAutoCleanup;
    private cleanupExpired;
}
/**
 * Factory function to create a ToolCache instance
 */
export declare const createToolCache: <T = unknown>(config: McpCacheConfig) => ToolCache<T>;
/**
 * Default cache configuration
 */
export declare const DEFAULT_CACHE_CONFIG: McpCacheConfig;
/**
 * Tool-specific cache wrapper with automatic key generation
 */
export declare class ToolResultCache {
    private cache;
    constructor(config?: Partial<McpCacheConfig>);
    /**
     * Cache a tool result
     */
    cacheResult(toolName: string, args: unknown, result: unknown, ttl?: number): void;
    /**
     * Get a cached tool result
     */
    getCachedResult(toolName: string, args: unknown): unknown | undefined;
    /**
     * Check if a result is cached
     */
    hasCachedResult(toolName: string, args: unknown): boolean;
    /**
     * Invalidate all cached results for a tool
     */
    invalidateTool(toolName: string): number;
    /**
     * Get cache statistics
     */
    getStats(): CacheStats;
    /**
     * Clear all cached results
     */
    clear(): void;
    /**
     * Destroy the cache
     */
    destroy(): void;
}
/**
 * Create a tool result cache instance
 */
export declare const createToolResultCache: (config?: Partial<McpCacheConfig>) => ToolResultCache;