synthia-cache-system/dist/cache-plugin-manager-DN8Y1tpu.d.ts

Synthia Engine Cache System - 核心缓存系统实现，提供多级缓存、版本管理、性能监控等功能

/**
 * 缓存系统类型定义
 */
interface CacheConfig {
    /** 本地缓存配置 */
    local: {
        /** 缓存目录 */
        dir: string;
        /** 最大缓存大小 (字节) */
        maxSize: number;
        /** 缓存过期时间 (毫秒) */
        ttl: number;
        /** 是否启用压缩 */
        compression: boolean;
    };
    /** 云端缓存配置 */
    cloud: {
        /** 是否启用云端缓存 */
        enabled: boolean;
        /** 云端存储类型 */
        provider: 'aws-s3' | 'aliyun-oss' | 'tencent-cos';
        /** 存储桶名称 */
        bucket: string;
        /** 区域 */
        region: string;
        /** 访问密钥ID */
        accessKeyId: string;
        /** 访问密钥 */
        accessKeySecret: string;
        /** 端点URL */
        endpoint?: string;
    };
    /** 缓存策略 */
    strategy: {
        /** 缓存级别 */
        level: 'local' | 'cloud' | 'hybrid';
        /** 本地缓存优先 */
        localFirst: boolean;
        /** 自动同步到云端 */
        autoSync: boolean;
        /** 同步间隔 (毫秒) */
        syncInterval: number;
    };
}
interface CacheItem {
    /** 缓存键 */
    key: string;
    /** 缓存值 */
    value: any;
    /** 缓存元信息 */
    meta: CacheMeta;
    /** 创建时间 */
    createdAt: number;
    /** 最后访问时间 */
    lastAccessedAt: number;
    /** 访问次数 */
    accessCount: number;
}
interface CacheMeta {
    /** 哈希值 */
    hash: string;
    /** 大小 (字节) */
    size: number;
    /** 过期时间 */
    expiresAt: number;
    /** 依赖文件列表 */
    dependencies: string[];
    /** 标签 */
    tags: string[];
    /** 版本 */
    version: string;
    /** 依赖文件哈希值 */
    dependenciesHash?: string;
    /** 创建时间 */
    createdAt?: number;
    /** 最后修改时间 */
    lastModified?: number;
}
interface CacheStats {
    /** 总缓存数量 */
    totalItems: number;
    /** 总缓存大小 */
    totalSize: number;
    /** 命中次数 */
    hits: number;
    /** 未命中次数 */
    misses: number;
    /** 命中率 */
    hitRate: number;
    /** 平均访问时间 */
    avgAccessTime: number;
    /** 最常访问的缓存 */
    topItems: Array<{
        key: string;
        accessCount: number;
        size: number;
    }>;
}
interface CacheOperation {
    /** 操作类型 */
    type: 'get' | 'set' | 'delete' | 'clear';
    /** 缓存键 */
    key?: string;
    /** 操作时间 */
    timestamp: number;
    /** 操作耗时 */
    duration: number;
    /** 操作结果 */
    success: boolean;
    /** 错误信息 */
    error?: string;
}
interface CacheProvider {
    /** 获取缓存 */
    get(key: string): Promise<CacheItem | null>;
    /** 设置缓存 */
    set(key: string, value: any, meta: Partial<CacheMeta>): Promise<void>;
    /** 删除缓存 */
    delete(key: string): Promise<void>;
    /** 清空缓存 */
    clear(): Promise<void>;
    /** 检查缓存是否存在 */
    has(key: string): Promise<boolean>;
    /** 获取缓存统计信息 */
    getStats(): Promise<CacheStats>;
    /** 获取所有缓存键 */
    keys(): Promise<string[]>;
    /** 获取缓存大小 */
    size(): Promise<number>;
}
interface CloudCacheProvider extends CacheProvider {
    /** 同步到云端 */
    sync(key: string): Promise<void>;
    /** 从云端拉取 */
    pull(key: string): Promise<CacheItem | null>;
    /** 批量同步 */
    batchSync(keys: string[]): Promise<void>;
}
interface CacheManager {
    /** 获取缓存 */
    get(key: string): Promise<any>;
    /** 设置缓存 */
    set(key: string, value: any, options?: Partial<CacheMeta>): Promise<void>;
    /** 删除缓存 */
    delete(key: string): Promise<void>;
    /** 清空缓存 */
    clear(): Promise<void>;
    /** 批量获取缓存 */
    getBatch(keys: string[]): Promise<Map<string, any>>;
    /** 批量设置缓存 */
    setBatch(items: Array<{
        key: string;
        value: any;
        options?: Partial<CacheMeta>;
    }>): Promise<void>;
    /** 批量删除缓存 */
    deleteBatch(keys: string[]): Promise<void>;
    /** 事务性操作缓存 */
    setTransaction(operations: Array<{
        type: 'set' | 'delete';
        key: string;
        value?: any;
        options?: Partial<CacheMeta>;
    }>): Promise<void>;
    /** 获取缓存统计 */
    getStats(): Promise<CacheStats>;
    /** 预热缓存 */
    warmup(keys: string[]): Promise<void>;
    /** 清理过期缓存 */
    cleanup(): Promise<void>;
    /** 导出缓存 */
    export(): Promise<Buffer>;
    /** 导入缓存 */
    import(data: Buffer): Promise<void>;
}

declare class SynthiaCacheManager implements CacheManager {
    private localCache;
    private cloudCache?;
    private config;
    private spinner;
    constructor(config: CacheConfig);
    /**
     * 获取缓存
     */
    get(key: string): Promise<any>;
    /**
     * 设置缓存
     */
    set(key: string, value: any, options?: Partial<CacheItem['meta']>): Promise<void>;
    /**
     * 批量设置缓存
     */
    setBatch(items: Array<{
        key: string;
        value: any;
        options?: Partial<CacheItem['meta']>;
    }>): Promise<void>;
    /**
     * 事务性设置缓存
     */
    setTransaction(operations: Array<{
        type: 'set' | 'delete';
        key: string;
        value?: any;
        options?: Partial<CacheItem['meta']>;
    }>): Promise<void>;
    /**
     * 批量获取缓存
     */
    getBatch(keys: string[]): Promise<Map<string, any>>;
    /**
     * 删除缓存
     */
    delete(key: string): Promise<void>;
    /**
     * 批量删除缓存
     */
    deleteBatch(keys: string[]): Promise<void>;
    /**
     * 清空缓存
     */
    clear(): Promise<void>;
    /**
     * 获取缓存统计
     */
    getStats(): Promise<CacheStats>;
    /**
     * 预热缓存
     */
    warmup(keys: string[]): Promise<void>;
    /**
     * 清理过期缓存
     */
    cleanup(): Promise<void>;
    /**
     * 导出缓存
     */
    export(): Promise<Buffer>;
    /**
     * 导入缓存
     */
    import(data: Buffer): Promise<void>;
}

/**
 * 缓存版本管理器
 * 负责管理缓存的版本控制、依赖追踪和失效检测
 */
declare class CacheVersionManager {
    private versionDir;
    private dependencyGraph;
    private versionHistory;
    private spinner;
    constructor(versionDir?: string);
    /**
     * 计算文件或内容的哈希值
     */
    calculateHash(content: string | Buffer): string;
    /**
     * 计算文件哈希值
     */
    calculateFileHash(filePath: string): string;
    /**
     * 计算依赖文件的哈希值
     */
    calculateDependenciesHash(dependencies: string[]): string;
    /**
     * 检查缓存是否有效
     */
    isCacheValid(key: string, dependencies: string[], currentHash?: string): boolean;
    /**
     * 更新缓存版本信息
     */
    updateCacheVersion(key: string, value: any, dependencies: string[], tags?: string[], version?: string): CacheMeta;
    /**
     * 获取受影响的缓存键
     */
    getAffectedCacheKeys(changedFiles: string[]): string[];
    /**
     * 清理无效的缓存版本
     */
    cleanupInvalidVersions(): void;
    /**
     * 获取缓存统计信息
     */
    getVersionStats(): {
        totalKeys: number;
        totalVersions: number;
        dependencyGraphSize: number;
        averageVersionsPerKey: number;
    };
    /**
     * 导出版本信息
     */
    exportVersionInfo(): Buffer;
    /**
     * 导入版本信息
     */
    importVersionInfo(data: Buffer): void;
    /**
     * 获取缓存元信息
     */
    private getCacheMeta;
    /**
     * 保存缓存元信息
     */
    private saveCacheMeta;
    /**
     * 更新依赖图
     */
    private updateDependencyGraph;
    /**
     * 更新版本历史
     */
    private updateVersionHistory;
    /**
     * 获取版本路径
     */
    private getVersionPath;
    /**
     * 确保版本目录存在
     */
    private ensureVersionDir;
    /**
     * 加载依赖图
     */
    private loadDependencyGraph;
    /**
     * 保存依赖图
     */
    private saveDependencyGraph;
    /**
     * 加载版本历史
     */
    private loadVersionHistory;
    /**
     * 保存版本历史
     */
    private saveVersionHistory;
}

/**
 * 缓存预热和智能清理策略管理器
 * 提供智能的缓存预热、清理和优化策略
 */
declare class CacheStrategyManager {
    private cacheManager;
    private spinner;
    private cleanupThresholds;
    constructor(cacheManager: CacheManager);
    /**
     * 预热缓存
     */
    warmup(keys: string[]): Promise<void>;
    /**
     * 智能清理缓存
     */
    smartCleanup(): Promise<{
        cleanedItems: number;
        freedSpace: number;
        strategy: string;
    }>;
    /**
     * 清理过期缓存
     */
    cleanupExpired(): Promise<{
        cleanedItems: number;
        freedSpace: number;
    }>;
    /**
     * 优化缓存策略
     */
    optimizeStrategy(): Promise<{
        recommendations: string[];
        estimatedImprovement: number;
    }>;
    /**
     * 批量预热缓存
     */
    batchWarmup(warmupGroups: Array<{
        keys: string[];
        priority: 'high' | 'medium' | 'low';
        timeout?: number;
    }>): Promise<void>;
    /**
     * 选择清理策略
     */
    private selectCleanupStrategy;
    /**
     * 基于大小的清理
     */
    private cleanupBySize;
    /**
     * 基于年龄的清理
     */
    private cleanupByAge;
    /**
     * 基于命中率的清理
     */
    private cleanupByHitRate;
    /**
     * 基于访问频率的清理
     */
    private cleanupByFrequency;
    /**
     * 格式化字节大小
     */
    private formatBytes;
}

/**
 * 缓存性能监控和指标收集器
 * 提供详细的性能指标、监控和报告功能
 */
declare class CacheMetricsCollector {
    private metrics;
    private operations;
    private spinner;
    private maxOperationsHistory;
    constructor();
    /**
     * 记录缓存操作
     */
    recordOperation(operation: CacheOperation): void;
    /**
     * 获取性能指标
     */
    getMetrics(): {
        realTime: any;
        historical: any;
        performance: any;
        recommendations: string[];
    };
    /**
     * 生成性能报告
     */
    generateReport(): Promise<void>;
    /**
     * 导出指标数据
     */
    exportMetrics(): Buffer;
    /**
     * 导入指标数据
     */
    importMetrics(data: Buffer): void;
    /**
     * 重置指标
     */
    resetMetrics(): void;
    /**
     * 获取实时指标
     */
    private getRealTimeMetrics;
    /**
     * 获取历史指标
     */
    private getHistoricalMetrics;
    /**
     * 获取性能指标
     */
    private getPerformanceMetrics;
    /**
     * 生成优化建议
     */
    private generateRecommendations;
    /**
     * 更新实时指标
     */
    private updateRealTimeMetrics;
    /**
     * 初始化指标
     */
    private initializeMetrics;
    /**
     * 获取指标摘要
     */
    getMetricsSummary(): {
        totalOperations: number;
        successRate: number;
        avgResponseTime: number;
        errorRate: number;
        uptime: number;
    };
}

/**
 * 缓存插件接口
 */
interface CachePlugin {
    /** 插件名称 */
    name: string;
    /** 插件版本 */
    version: string;
    /** 插件描述 */
    description?: string;
    /** 初始化插件 */
    initialize?(config: any): Promise<void>;
    /** 插件销毁 */
    destroy?(): Promise<void>;
    /** 缓存操作钩子 */
    hooks?: {
        beforeGet?(key: string): Promise<void>;
        afterGet?(key: string, value: any): Promise<void>;
        beforeSet?(key: string, value: any): Promise<void>;
        afterSet?(key: string, value: any): Promise<void>;
        beforeDelete?(key: string): Promise<void>;
        afterDelete?(key: string): Promise<void>;
        beforeClear?(): Promise<void>;
        afterClear?(): Promise<void>;
    };
    /** 获取插件配置 */
    getConfig?(): any;
    /** 设置插件配置 */
    setConfig?(config: any): void;
}
/**
 * 缓存插件管理器
 * 提供插件的注册、管理和生命周期控制
 */
declare class CachePluginManager {
    private plugins;
    private pluginConfigs;
    private spinner;
    constructor();
    /**
     * 注册插件
     */
    registerPlugin(plugin: CachePlugin): void;
    /**
     * 卸载插件
     */
    unregisterPlugin(pluginName: string): Promise<void>;
    /**
     * 初始化所有插件
     */
    initializePlugins(): Promise<void>;
    /**
     * 销毁所有插件
     */
    destroyPlugins(): Promise<void>;
    /**
     * 执行钩子函数
     */
    executeHook(hookName: keyof NonNullable<CachePlugin['hooks']>, ...args: any[]): Promise<void>;
    /**
     * 获取插件列表
     */
    getPlugins(): Array<{
        name: string;
        version: string;
        description?: string;
        config?: any;
    }>;
    /**
     * 获取插件
     */
    getPlugin(name: string): CachePlugin | undefined;
    /**
     * 设置插件配置
     */
    setPluginConfig(pluginName: string, config: any): void;
    /**
     * 获取插件配置
     */
    getPluginConfig(pluginName: string): any;
    /**
     * 检查插件是否存在
     */
    hasPlugin(pluginName: string): boolean;
    /**
     * 获取插件统计信息
     */
    getPluginStats(): {
        totalPlugins: number;
        activePlugins: number;
        pluginNames: string[];
    };
}
/**
 * 缓存管理器包装器
 * 为缓存管理器添加插件支持
 */
declare class CacheManagerWithPlugins implements CacheManager {
    private cacheManager;
    private pluginManager;
    constructor(cacheManager: CacheManager, pluginManager: CachePluginManager);
    /**
     * 获取缓存
     */
    get(key: string): Promise<any>;
    /**
     * 设置缓存
     */
    set(key: string, value: any, options?: Partial<CacheMeta>): Promise<void>;
    /**
     * 删除缓存
     */
    delete(key: string): Promise<void>;
    /**
     * 清空缓存
     */
    clear(): Promise<void>;
    /**
     * 批量获取缓存
     */
    getBatch(keys: string[]): Promise<Map<string, any>>;
    /**
     * 批量设置缓存
     */
    setBatch(items: Array<{
        key: string;
        value: any;
        options?: Partial<CacheMeta>;
    }>): Promise<void>;
    /**
     * 批量删除缓存
     */
    deleteBatch(keys: string[]): Promise<void>;
    /**
     * 事务性操作缓存
     */
    setTransaction(operations: Array<{
        type: 'set' | 'delete';
        key: string;
        value?: any;
        options?: Partial<CacheMeta>;
    }>): Promise<void>;
    /**
     * 获取缓存统计
     */
    getStats(): Promise<CacheStats>;
    /**
     * 预热缓存
     */
    warmup(keys: string[]): Promise<void>;
    /**
     * 清理过期缓存
     */
    cleanup(): Promise<void>;
    /**
     * 导出缓存
     */
    export(): Promise<Buffer>;
    /**
     * 导入缓存
     */
    import(data: Buffer): Promise<void>;
    /**
     * 获取插件管理器
     */
    getPluginManager(): CachePluginManager;
}

export { type CacheProvider as C, SynthiaCacheManager as S, type CacheConfig as a, type CacheMeta as b, type CacheItem as c, type CacheStats as d, type CloudCacheProvider as e, type CacheOperation as f, type CacheManager as g, CacheVersionManager as h, CacheStrategyManager as i, CacheMetricsCollector as j, type CachePlugin as k, CachePluginManager as l, CacheManagerWithPlugins as m };