@digitalsamba/embedded-api-mcp-server/dist/src/cache.d.ts

Digital Samba Embedded API MCP Server - Model Context Protocol server for Digital Samba's Embedded API

/**
 * Digital Samba MCP Server - Cache Module
 *
 * This module provides caching functionality for the Digital Samba MCP Server.
 * It implements a flexible caching system for API responses, reducing load on
 * the Digital Samba API and improving response times for clients.
 *
 * Features include:
 * - Configurable TTL (Time-To-Live) for cached responses
 * - Memory-based cache storage
 * - Optional Redis-based storage for distributed deployments
 * - Cache invalidation strategies
 * - Support for conditional requests (ETag, If-Modified-Since)
 *
 * @module cache
 * @author Digital Samba Team
 * @version 0.1.0
 */
/**
 * Cache options interface
 */
export interface CacheOptions {
    /** Default TTL in milliseconds */
    ttl: number;
    /** Maximum number of items to store */
    maxItems?: number;
    /** Whether to use ETag for conditional requests */
    useEtag?: boolean;
    /** Function to generate cache keys */
    keyGenerator?: (namespace: string, id: string) => string;
    /** Custom serialization function */
    serializer?: (value: unknown) => string;
    /** Custom deserialization function */
    deserializer?: (value: string) => unknown;
}
/**
 * Cache entry interface
 */
interface CacheEntry<T> {
    /** Cached value */
    value: T;
    /** Expiration timestamp */
    expires: number;
    /** ETag for conditional requests */
    etag?: string;
    /** Last modified timestamp */
    lastModified?: Date;
}
/**
 * Default cache options
 */
export declare const defaultCacheOptions: CacheOptions;
/**
 * Memory-based cache implementation
 */
export declare class MemoryCache<T = unknown> {
    private cache;
    private options;
    private cleanupTimer?;
    /**
     * Creates a new MemoryCache
     * @param options Cache options
     */
    constructor(options?: Partial<CacheOptions>);
    /**
     * Generates an ETag for a value
     *
     * Creates a unique identifier based on the content hash that can be used
     * for HTTP conditional requests (If-None-Match header).
     *
     * @param {unknown} value - Value to generate ETag for
     * @returns {string} ETag string (MD5 hash truncated to 16 chars)
     * @private
     */
    private generateEtag;
    /**
     * Starts the cleanup interval to remove expired items
     */
    private startCleanupInterval;
    /**
     * Cleans up expired cache entries
     */
    cleanup(): void;
    /**
     * Sets a value in the cache
     *
     * This method stores a value in the cache with automatic expiration and optional
     * ETag generation for conditional requests. It handles cache size limits by
     * evicting the oldest entries when necessary.
     *
     * @param {string} namespace - Cache namespace (e.g., 'rooms', 'sessions')
     * @param {string} id - Unique identifier within the namespace
     * @param {T} value - Value to cache
     * @param {number} [ttl] - Optional TTL override in milliseconds
     * @returns {CacheEntry<T>} The cached entry with metadata
     *
     * @example
     * // Cache a room object for 10 minutes
     * cache.set('rooms', 'room-123', roomData, 600000);
     *
     * @example
     * // Cache with default TTL
     * cache.set('sessions', 'session-456', sessionData);
     */
    set(namespace: string, id: string, value: T, ttl?: number): CacheEntry<T>;
    /**
     * Gets a value from the cache
     * @param namespace Cache namespace
     * @param id Item identifier
     * @returns The cached entry or undefined if not found or expired
     */
    get(namespace: string, id: string): CacheEntry<T> | undefined;
    /**
     * Deletes a value from the cache
     * @param namespace Cache namespace
     * @param id Item identifier
     * @returns Whether the item was deleted
     */
    delete(namespace: string, id: string): boolean;
    /**
     * Invalidates a specific cache entry in a namespace
     * @param namespace Cache namespace
     * @param id Item identifier
     * @returns Whether the item was invalidated
     */
    invalidate(namespace: string, id: string): boolean;
    /**
     * Invalidates all items in a namespace
     * @param namespace Cache namespace
     * @returns Number of items invalidated
     */
    invalidateNamespace(namespace: string): number;
    /**
     * Checks if a value is fresh based on conditional headers
     * @param namespace Cache namespace
     * @param id Item identifier
     * @param etag ETag to compare
     * @param modifiedSince Last-Modified date to compare
     * @returns Whether the cached value is considered fresh
     */
    isFresh(namespace: string, id: string, etag?: string, modifiedSince?: Date): boolean;
    /**
     * Evicts the oldest item from the cache
     * @returns Whether an item was evicted
     */
    private evictOldest;
    /**
     * Clears the entire cache
     */
    clear(): void;
    /**
     * Gets cache statistics
     * @returns Cache statistics
     */
    getStats(): {
        totalItems: number;
        validItems: number;
        expiredItems: number;
        maxItems: number;
    };
    /**
     * Destroys the cache and clears cleanup timers
     */
    destroy(): void;
}
/**
 * Exports the default cache
 */
declare const _default: {
    MemoryCache: typeof MemoryCache;
};
export default _default;
//# sourceMappingURL=cache.d.ts.map