@json-to-office/shared 0.35.0 → 1.0.0

package/dist/cache/index.d.ts

@@ -1,464 +0,0 @@
-import { EventEmitter } from 'events';
-
-/**
- * Cache Types and Interfaces
- * Core type definitions for the component caching system
- */
-/**
- * Cache entry metadata
- */
-interface CacheMetadata {
-    /** Creation timestamp */
-    timestamp: number;
-    /** Number of cache hits */
-    hits: number;
-    /** Size in bytes */
-    size: number;
-    /** Component dependencies */
-    dependencies: string[];
-    /** Content signature for validation */
-    signature: string;
-    /** Time-to-live in seconds */
-    ttl?: number;
-    /** Last access timestamp */
-    lastAccessed: number;
-}
-/**
- * Cached component entry
- */
-interface CachedComponent extends CacheMetadata {
-    /** Processed component result */
-    result: unknown;
-    /** Component name for analytics */
-    componentName: string;
-    /** Original component props hash */
-    propsHash: string;
-}
-/**
- * Cache statistics
- */
-interface CacheStatistics {
-    /** Total number of entries */
-    entries: number;
-    /** Total cache size in bytes */
-    totalSize: number;
-    /** Cache hit rate (0-1) */
-    hitRate: number;
-    /** Cache miss rate (0-1) */
-    missRate: number;
-    /** Total hits */
-    totalHits: number;
-    /** Total misses */
-    totalMisses: number;
-    /** Average response time in ms */
-    avgResponseTime: number;
-    /** Eviction count */
-    evictions: number;
-    /** Per-component statistics */
-    componentStats: Map<string, ComponentStatistics>;
-}
-/**
- * Component-specific statistics
- */
-interface ComponentStatistics {
-    /** Component name */
-    name: string;
-    /** Number of cache hits */
-    hits: number;
-    /** Number of cache misses */
-    misses: number;
-    /** Average processing time when missed */
-    avgProcessTime: number;
-    /** Average size of cached entries */
-    avgSize: number;
-    /** Number of cached entries */
-    entries: number;
-}
-/**
- * Cache key options
- */
-interface CacheKeyOptions {
-    /** Include theme in key generation */
-    includeTheme?: boolean;
-    /** Include render context in key */
-    includeContext?: boolean;
-    /** Additional key components */
-    additionalKeys?: string[];
-    /** Key version for cache busting */
-    version?: string;
-}
-/**
- * Cache configuration
- */
-interface CacheConfiguration {
-    /** Enable/disable caching globally */
-    enabled: boolean;
-    /** Memory cache configuration */
-    memory: {
-        enabled: boolean;
-        /** Maximum cache size in MB */
-        maxSize: number;
-        /** Maximum number of entries */
-        maxEntries: number;
-        /** Default TTL in seconds */
-        defaultTTL: number;
-        /** Check expired entries interval in seconds */
-        cleanupInterval: number;
-    };
-    /** Disk cache configuration (future) */
-    disk?: {
-        enabled: boolean;
-        /** Cache directory path */
-        path: string;
-        /** Maximum cache size in MB */
-        maxSize: number;
-        /** Default TTL in seconds */
-        defaultTTL: number;
-        /** Compression enabled */
-        compression: boolean;
-    };
-    /** Eviction policy */
-    evictionPolicy: 'lru' | 'lfu' | 'fifo' | 'ttl';
-    /** Component-specific configurations */
-    componentConfig?: {
-        [componentName: string]: {
-            /** Whether this component is cacheable */
-            cacheable: boolean;
-            /** Custom TTL for this component */
-            ttl?: number;
-            /** Maximum entries for this component */
-            maxEntries?: number;
-        };
-    };
-    /** Performance settings */
-    performance: {
-        /** Enable performance tracking */
-        trackMetrics: boolean;
-        /** Metrics sampling rate (0-1) */
-        metricsSampleRate: number;
-        /** Enable cache warming */
-        enableWarming: boolean;
-        /** Parallel processing for batch operations */
-        parallelProcessing: boolean;
-    };
-}
-/**
- * Cache events for monitoring
- */
-interface CacheEvents {
-    hit: (key: string, component: CachedComponent) => void;
-    miss: (key: string) => void;
-    set: (key: string, component: CachedComponent) => void;
-    evict: (key: string, reason: 'ttl' | 'size' | 'manual') => void;
-    error: (error: Error) => void;
-    stats: (stats: CacheStatistics) => void;
-}
-
-/**
- * Cache Manager Base Class
- * Abstract base class for cache implementations
- */
-
-/**
- * Main cache manager abstract class
- */
-declare abstract class ComponentCacheManager extends EventEmitter {
-    protected config: CacheConfiguration;
-    protected stats: CacheStatistics;
-    constructor(config: CacheConfiguration);
-    /**
-     * Get a cached component
-     */
-    abstract get(key: string): Promise<CachedComponent | undefined>;
-    /**
-     * Set a cached component
-     */
-    abstract set(key: string, component: CachedComponent): Promise<void>;
-    /**
-     * Check if key exists
-     */
-    abstract has(key: string): Promise<boolean>;
-    /**
-     * Delete a cached entry
-     */
-    abstract delete(key: string): Promise<boolean>;
-    /**
-     * Clear all cache entries
-     */
-    abstract clear(): Promise<void>;
-    /**
-     * Get all keys (for utilities)
-     */
-    abstract getKeys(): Promise<string[]>;
-    /**
-     * Get cache statistics with deep immutability
-     */
-    getStats(): CacheStatistics;
-    /**
-     * Get configuration with deep immutability
-     */
-    getConfig(): CacheConfiguration;
-    /**
-     * Get multiple entries (batch operation)
-     */
-    getMany(keys: string[]): Promise<Map<string, CachedComponent>>;
-    /**
-     * Set multiple entries (batch operation)
-     */
-    setMany(entries: [string, CachedComponent][]): Promise<void>;
-    /**
-     * Delete multiple entries
-     */
-    deleteMany(keys: string[]): Promise<number>;
-    /**
-     * Initialize statistics
-     */
-    protected initializeStats(): CacheStatistics;
-    /**
-     * Update statistics on cache hit
-     */
-    protected updateHitStats(key: string, component: CachedComponent): void;
-    /**
-     * Update statistics on cache miss
-     */
-    protected updateMissStats(key: string, componentName?: string): void;
-    /**
-     * Update component-specific statistics
-     */
-    protected updateComponentStats(componentName: string, event: 'hit' | 'miss'): void;
-    /**
-     * Recalculate hit/miss rates
-     */
-    protected recalculateRates(): void;
-    /**
-     * Emit statistics periodically
-     */
-    protected emitStats(): void;
-}
-
-/**
- * Memory Cache Implementation
- * In-memory cache with LRU eviction policy
- */
-
-/**
- * In-memory cache with LRU eviction
- */
-declare class MemoryCache extends ComponentCacheManager {
-    private cache;
-    private head;
-    private tail;
-    private currentSize;
-    private keyToComponentName;
-    private cleanupTimer?;
-    constructor(config: CacheConfiguration);
-    get(key: string): Promise<CachedComponent | undefined>;
-    set(key: string, component: CachedComponent): Promise<void>;
-    has(key: string): Promise<boolean>;
-    delete(key: string): Promise<boolean>;
-    clear(): Promise<void>;
-    getKeys(): Promise<string[]>;
-    /**
-     * Extract component name from cache key
-     */
-    private extractComponentNameFromKey;
-    /**
-     * Check if component is expired
-     */
-    private isExpired;
-    /**
-     * Check if component is cacheable
-     */
-    private isCacheable;
-    /**
-     * Ensure enough space for new entry
-     */
-    private ensureSpace;
-    /**
-     * LRU operations - Add node to head
-     */
-    private addToHead;
-    /**
-     * Remove node from list
-     */
-    private removeNode;
-    /**
-     * Move node to head
-     */
-    private moveToHead;
-    /**
-     * Start cleanup timer for expired entries
-     */
-    private startCleanupTimer;
-    /**
-     * Stop cleanup timer
-     */
-    destroy(): void;
-}
-
-/**
- * Cache Configuration
- * Default configuration and environment-based configuration
- */
-
-/**
- * Default cache configuration
- */
-declare const DEFAULT_CACHE_CONFIG: CacheConfiguration;
-/**
- * Get cache configuration from environment variables
- */
-declare function getCacheConfigFromEnv(): Partial<CacheConfiguration>;
-/**
- * Merge configurations with priority
- */
-declare function mergeConfigs(...configs: Partial<CacheConfiguration>[]): CacheConfiguration;
-
-/**
- * Component Cache Analytics
- * Advanced analytics and insights for component-level caching
- */
-
-/**
- * Time-series data point for tracking metrics over time
- */
-interface TimeSeriesPoint {
-    timestamp: number;
-    value: number;
-}
-/**
- * Component performance metrics
- */
-interface ComponentPerformanceMetrics {
-    /** Component name identifier */
-    componentName: string;
-    /** Cache hit rate (0-1) */
-    hitRate: number;
-    /** Total requests (hits + misses) */
-    totalRequests: number;
-    /** Average response time for cache hits (ms) */
-    avgHitTime: number;
-    /** Average response time for cache misses (ms) */
-    avgMissTime: number;
-    /** Cache efficiency score (0-100) */
-    efficiencyScore: number;
-    /** Memory usage in bytes */
-    memoryUsage: number;
-    /** Time saved by caching (ms) */
-    timeSaved: number;
-    /** Cost-benefit ratio */
-    costBenefitRatio: number;
-}
-/**
- * Component cache trends over time
- */
-interface ComponentCacheTrends {
-    /** Component name */
-    componentName: string;
-    /** Hit rate trend */
-    hitRateTrend: TimeSeriesPoint[];
-    /** Request volume trend */
-    requestVolumeTrend: TimeSeriesPoint[];
-    /** Response time trend */
-    responseTimeTrend: TimeSeriesPoint[];
-    /** Memory usage trend */
-    memoryUsageTrend: TimeSeriesPoint[];
-}
-/**
- * Cache optimization recommendations
- */
-interface CacheOptimizationRecommendation {
-    /** Component name to optimize */
-    componentName: string;
-    /** Recommendation type */
-    type: 'increase_ttl' | 'decrease_ttl' | 'increase_size' | 'disable_cache' | 'enable_cache';
-    /** Recommendation description */
-    description: string;
-    /** Expected improvement percentage */
-    expectedImprovement: number;
-    /** Priority level (1-5, 5 being highest) */
-    priority: number;
-    /** Detailed reasoning */
-    reasoning: string;
-}
-/**
- * Comprehensive cache analytics report
- */
-interface CacheAnalyticsReport {
-    /** Report generation timestamp */
-    timestamp: number;
-    /** Overall cache health score (0-100) */
-    healthScore: number;
-    /** Total cache efficiency percentage */
-    overallEfficiency: number;
-    /** Per-component performance metrics */
-    componentMetrics: ComponentPerformanceMetrics[];
-    /** Component cache trends */
-    trends: ComponentCacheTrends[];
-    /** Optimization recommendations */
-    recommendations: CacheOptimizationRecommendation[];
-    /** Top performing components */
-    topPerformers: string[];
-    /** Components needing attention */
-    needsAttention: string[];
-    /** Estimated performance gain from caching */
-    performanceGain: {
-        timeReduction: number;
-        cpuReduction: number;
-        memoryOptimization: number;
-    };
-}
-/**
- * Component Cache Analytics Engine
- */
-declare class ComponentCacheAnalytics {
-    private historyWindow;
-    private metricsHistory;
-    private performanceBaseline;
-    /**
-     * Analyze cache statistics and generate comprehensive report
-     */
-    analyzeCache(stats: CacheStatistics): CacheAnalyticsReport;
-    /**
-     * Calculate detailed metrics for each component
-     */
-    private calculateComponentMetrics;
-    /**
-     * Calculate efficiency score for a component
-     */
-    private calculateEfficiencyScore;
-    /**
-     * Calculate trends over time
-     */
-    private calculateTrends;
-    /**
-     * Get or create history for a metric
-     */
-    private getOrCreateHistory;
-    /**
-     * Generate optimization recommendations
-     */
-    private generateRecommendations;
-    /**
-     * Check if a trend is declining
-     */
-    private isDecliningSlopbankTrend;
-    /**
-     * Calculate overall cache health score
-     */
-    private calculateHealthScore;
-    /**
-     * Calculate overall cache efficiency
-     */
-    private calculateOverallEfficiency;
-    /**
-     * Calculate performance gain from caching
-     */
-    private calculatePerformanceGain;
-    /**
-     * Reset analytics history
-     */
-    reset(): void;
-}
-
-export { type CacheAnalyticsReport, type CacheConfiguration, type CacheEvents, type CacheKeyOptions, type CacheMetadata, type CacheOptimizationRecommendation, type CacheStatistics, type CachedComponent, ComponentCacheAnalytics, ComponentCacheManager, type ComponentCacheTrends, type ComponentPerformanceMetrics, type ComponentStatistics, DEFAULT_CACHE_CONFIG, MemoryCache, type TimeSeriesPoint, getCacheConfigFromEnv, mergeConfigs };