import { SynthiaCacheManager, type CacheConfig } from 'synthia-cache-system';

// 配置缓存系统
const config: CacheConfig = {
  local: {
    dir: '.synthia-cache',
    maxSize: 100 * 1024 * 1024, // 100MB
    ttl: 7 * 24 * 60 * 60 * 1000, // 7天
    compression: true,
  },
  cloud: {
    enabled: false, // 设置为 true 启用云端缓存
    provider: 'aws-s3',
    bucket: 'your-bucket-name',
    region: 'us-east-1',
    accessKeyId: 'your-access-key-id',
    accessKeySecret: 'your-secret-access-key',
  },
  strategy: {
    level: 'local', // 'local' | 'cloud' | 'hybrid'
    localFirst: true,
    autoSync: false,
    syncInterval: 5 * 60 * 1000, // 5分钟
  },
};

// 创建缓存管理器
const cacheManager = new SynthiaCacheManager(config);

// 设置缓存
await cacheManager.set('user:123', {
  id: 123,
  name: 'John Doe',
  email: 'john@example.com',
});

// 获取缓存
const user = await cacheManager.get('user:123');
console.log(user); // { id: 123, name: 'John Doe', email: 'john@example.com' }

📋 API 文档

CacheManager

基本操作

// 设置缓存
await cacheManager.set(key: string, value: any, options?: Partial<CacheMeta>)

// 获取缓存
const value = await cacheManager.get(key: string)

// 删除缓存
await cacheManager.delete(key: string)

// 清空缓存
await cacheManager.clear()

批量操作

// 批量设置缓存
await cacheManager.setBatch(items: Array<{
  key: string
  value: any
  options?: Partial<CacheMeta>
}>)

// 批量获取缓存
const results = await cacheManager.getBatch(keys: string[])

// 批量删除缓存
await cacheManager.deleteBatch(keys: string[])

事务操作

// 事务性操作缓存
await cacheManager.setTransaction(operations: Array<{
  type: 'set' | 'delete'
  key: string
  value?: any
  options?: Partial<CacheMeta>
}>)

高级操作

// 获取缓存统计
const stats = await cacheManager.getStats()

// 预热缓存
await cacheManager.warmup(keys: string[])

// 清理过期缓存
await cacheManager.cleanup()

// 导出缓存
const data = await cacheManager.export()

// 导入缓存
await cacheManager.import(data)

CacheVersionManager

缓存版本管理器，提供版本控制和依赖追踪功能：

import { CacheVersionManager } from 'synthia-cache-system';

const versionManager = new CacheVersionManager();

// 更新缓存版本信息
const meta = versionManager.updateCacheVersion(
  'user:123',
  userData,
  ['package.json', 'src/config.ts'],
  ['user', 'profile'],
  '1.0.0'
);

// 检查缓存是否有效
const isValid = versionManager.isCacheValid('user:123', dependencies);

// 获取受影响的缓存键
const affectedKeys = versionManager.getAffectedCacheKeys(['src/config.ts']);

// 清理无效版本
versionManager.cleanupInvalidVersions();

CacheCompressor

缓存压缩器，提供多种压缩算法：

import { CacheCompressor } from 'synthia-cache-system';

const compressor = new CacheCompressor();

// 压缩数据
const compressed = await compressor.compress(data, 'gzip');

// 解压缩数据
const decompressed = await compressor.decompress(compressed, 'gzip');

// 选择最佳压缩算法
const result = await compressor.selectBestCompression(data);
console.log(`最佳算法: ${result.algorithm}, 压缩比: ${result.ratio}`);

// 批量压缩
const compressedItems = await compressor.compressBatch(items, 'gzip');

CacheStrategyManager

缓存策略管理器，提供智能的预热和清理策略：

import { CacheStrategyManager } from 'synthia-cache-system';

const strategyManager = new CacheStrategyManager(cacheManager);

// 预热缓存
await strategyManager.warmup(['user:123', 'user:124']);

// 智能清理
const result = await strategyManager.smartCleanup();
console.log(
  `清理了 ${result.cleanedItems} 项，释放了 ${result.freedSpace} 字节`
);

// 优化策略
const recommendations = await strategyManager.optimizeStrategy();
console.log('优化建议:', recommendations.recommendations);

// 批量预热
await strategyManager.batchWarmup([
  { keys: ['user:123'], priority: 'high' },
  { keys: ['user:124', 'user:125'], priority: 'medium' },
]);

CacheMetricsCollector

性能监控和指标收集器：

import { CacheMetricsCollector } from 'synthia-cache-system';

const metricsCollector = new CacheMetricsCollector();

// 记录操作
metricsCollector.recordOperation({
  type: 'get',
  key: 'user:123',
  timestamp: Date.now(),
  duration: 15,
  success: true,
});

// 生成性能报告
await metricsCollector.generateReport();

// 获取指标
const metrics = metricsCollector.getMetrics();
console.log('实时指标:', metrics.realTime);
console.log('性能指标:', metrics.performance);
console.log('优化建议:', metrics.recommendations);

// 导出指标数据
const data = metricsCollector.exportMetrics();

CachePluginManager

插件管理器，提供可扩展的插件架构：

import {
  CachePluginManager,
  CacheManagerWithPlugins,
} from 'synthia-cache-system';

const pluginManager = new CachePluginManager();

// 定义插件
const myPlugin: CachePlugin = {
  name: 'my-plugin',
  version: '1.0.0',
  description: '我的缓存插件',
  hooks: {
    beforeGet: async (key: string) => {
      console.log(`准备获取缓存: ${key}`);
    },
    afterSet: async (key: string, value: any) => {
      console.log(`缓存设置完成: ${key}`);
    },
  },
};

// 注册插件
pluginManager.registerPlugin(myPlugin);

// 创建带插件的缓存管理器
const enhancedCacheManager = new CacheManagerWithPlugins(
  cacheManager,
  pluginManager
);

// 初始化插件
await pluginManager.initializePlugins();

// 使用增强的缓存管理器
await enhancedCacheManager.set('user:123', userData);

🎯 使用场景

1. 构建缓存

// 缓存构建结果
const buildCache = new SynthiaCacheManager({
  local: { dir: '.build-cache', maxSize: 500 * 1024 * 1024 },
  cloud: { enabled: true, provider: 'aws-s3', bucket: 'build-cache' },
  strategy: { level: 'hybrid', autoSync: true },
});

await buildCache.set('build:main', buildOutput, {
  dependencies: ['src/**/*.ts', 'package.json'],
  tags: ['build', 'main'],
  version: '1.0.0',
});

2. API 响应缓存

// API 响应缓存
const apiCache = new SynthiaCacheManager({
  local: { dir: '.api-cache', ttl: 5 * 60 * 1000 }, // 5分钟
  strategy: { level: 'local' },
});

// 批量缓存 API 响应
const apiResponses = [
  { key: 'api:users', value: usersData },
  { key: 'api:products', value: productsData },
];
await apiCache.setBatch(apiResponses);

3. 数据库查询缓存

// 数据库查询缓存
const dbCache = new SynthiaCacheManager({
  local: { dir: '.db-cache', ttl: 30 * 60 * 1000 }, // 30分钟
  strategy: { level: 'local' },
});

// 事务性缓存数据库操作
await dbCache.setTransaction([
  { type: 'set', key: 'user:123', value: userData },
  { type: 'set', key: 'user:124', value: userData2 },
  { type: 'delete', key: 'user:125' },
]);

🔧 配置选项

本地缓存配置

const localConfig = {
  dir: '.synthia-cache', // 缓存目录
  maxSize: 100 * 1024 * 1024, // 最大缓存大小 (100MB)
  ttl: 7 * 24 * 60 * 60 * 1000, // 过期时间 (7天)
  compression: true, // 启用压缩
};

云端缓存配置

const cloudConfig = {
  enabled: true, // 启用云端缓存
  provider: 'aws-s3', // 云服务提供商
  bucket: 'my-cache-bucket', // 存储桶名称
  region: 'us-east-1', // 区域
  accessKeyId: 'your-key-id', // 访问密钥ID
  accessKeySecret: 'your-secret', // 访问密钥
};

缓存策略配置

const strategyConfig = {
  level: 'hybrid', // 缓存级别
  localFirst: true, // 本地优先
  autoSync: true, // 自动同步
  syncInterval: 5 * 60 * 1000, // 同步间隔 (5分钟)
};

📊 性能优化

1. 批量操作

使用批量操作可以显著提升性能：

// 批量设置 - 比单个设置快 3-5 倍
await cacheManager.setBatch(items);

// 批量获取 - 减少网络往返
const results = await cacheManager.getBatch(keys);

2. 压缩优化

选择合适的压缩算法可以节省存储空间：

const compressor = new CacheCompressor();
const result = await compressor.selectBestCompression(data);
// 通常可以节省 30-70% 的存储空间

3. 智能清理

定期执行智能清理可以保持缓存性能：

const strategyManager = new CacheStrategyManager(cacheManager);
await strategyManager.smartCleanup();
// 自动选择最佳清理策略

🛠️ 开发工具

性能监控

const metricsCollector = new CacheMetricsCollector();

// 记录所有缓存操作
metricsCollector.recordOperation(operation);

// 生成详细报告
await metricsCollector.generateReport();

版本管理

const versionManager = new CacheVersionManager();

// 检查缓存有效性
const isValid = versionManager.isCacheValid(key, dependencies);

// 获取受影响的缓存
const affectedKeys = versionManager.getAffectedCacheKeys(changedFiles);

🔍 工作原理

1. 缓存键生成

系统会根据以下因素生成缓存键：

项目路径和版本
依赖文件哈希
构建配置哈希
源文件变化

2. 缓存策略

本地优先: 优先使用本地缓存
云端同步: 支持云端缓存同步
智能失效: 自动检测缓存失效
版本管理: 多版本缓存管理

3. 性能优化

并行处理: 并行执行缓存操作
批量操作: 批量处理缓存请求
压缩存储: 智能压缩减少存储空间
预热机制: 智能预热常用缓存

🧪 测试

# 运行测试
npm test

# 运行特定测试
npm test -- --testNamePattern="LocalCache"

# 运行测试并生成覆盖率报告
npm test -- --coverage

📝 示例

查看 examples/ 目录中的完整示例：

basic-usage.ts - 基本使用示例
cloud-cache.ts - 云端缓存示例
plugin-example.ts - 插件开发示例

🤝 贡献

欢迎贡献代码！请查看贡献指南了解详细信息。

📄 许可证

MIT License - 查看 LICENSE 文件了解详细信息。

Keywords

FAQs

What is synthia-cache-system?

Is synthia-cache-system well maintained?

Package last updated on 06 Nov 2025

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

synthia-cache-system