@juspay/neurolink/dist/utils/imageCache.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

/**
 * Image Cache Utility for NeuroLink
 *
 * Implements an LRU cache for downloaded images to avoid redundant URL downloads.
 * Addresses IMG-026: No Caching issue - same URL downloaded multiple times wasting bandwidth.
 *
 * Features:
 * - LRU (Least Recently Used) eviction strategy
 * - Configurable cache size and TTL
 * - Cache hit/miss metrics
 * - Content hash tracking for deduplication
 *
 * @module utils/imageCache
 */
import type { CachedImage, ImageCacheConfig, ImageCacheStats } from "../types/index.js";
/**
 * LRU Cache for downloaded images
 *
 * Uses URL as primary key and tracks content hashes for deduplication.
 * Implements LRU eviction and configurable TTL for memory management.
 */
export declare class ImageCache {
    private cache;
    private contentHashIndex;
    private maxSize;
    private ttlMs;
    private maxImageSize;
    private enabled;
    private stats;
    constructor(config?: ImageCacheConfig);
    /**
     * Parse a config value with bounds checking
     */
    private parseConfigValue;
    /**
     * Normalize URL for consistent cache key generation.
     *
     * Delegates to the shared {@link normalizeUrlForCache} — this normalized
     * URL is used as the in-memory Map key (see `get`/`set` below), which lives
     * for the process lifetime, so both tracking-param noise and presigned-URL
     * auth/signature secrets must be stripped consistently with
     * `fileDetector.cacheKeyForUrl`'s identical requirement. See
     * `stripSensitiveUrlParamsForCacheKey`'s doc comment for why a naive
     * strip-only approach (no hash suffix) would be a correctness bug, not just
     * a hygiene one.
     */
    private normalizeUrl;
    /**
     * Generate content hash from image data
     */
    private generateContentHash;
    /**
     * Check if an entry is expired based on TTL
     */
    private isExpired;
    /**
     * Check if cache is enabled
     */
    isEnabled(): boolean;
    /**
     * Get a cached image by URL
     * Returns null if not found or expired
     */
    get(url: string): CachedImage | null;
    /**
     * Get a cached image by content hash
     * Useful for deduplication when the same image is accessed via different URLs
     */
    getByContentHash(contentHash: string): CachedImage | null;
    /**
     * Store an image in the cache
     */
    set(url: string, dataUri: string, contentType: string, imageData: Buffer): void;
    /**
     * Delete an entry from the cache
     */
    delete(url: string): boolean;
    /**
     * Evict the oldest (least recently used) entry
     */
    private evictOldest;
    /**
     * Clear all expired entries
     */
    evictExpired(): number;
    /**
     * Clear all entries from the cache
     */
    clear(): void;
    /**
     * Get cache statistics
     */
    getStats(): ImageCacheStats;
    /**
     * Check if a URL is cached and not expired
     */
    has(url: string): boolean;
    /**
     * Get the current cache size
     */
    getSize(): number;
    /**
     * Get cache configuration
     */
    getConfig(): {
        enabled: boolean;
        maxSize: number;
        ttlMs: number;
        maxImageSize: number;
    };
}
/**
 * Get the global image cache instance
 * Creates a new instance if none exists
 */
export declare function getImageCache(config?: ImageCacheConfig): ImageCache;
/**
 * Reset the global image cache (useful for testing)
 */
export declare function resetImageCache(): void;
/**
 * Get image cache statistics from the global instance
 */
export declare function getImageCacheStats(): ImageCacheStats | null;