{"_id":"@cardos/key-value-storage","name":"@cardos/key-value-storage","dist-tags":{"latest":"0.1.3"},"versions":{"0.1.3":{"name":"@cardos/key-value-storage","version":"0.1.3","description":"A flexible key-value storage system with multi-level caching support","main":"dist/index.js","module":"dist/index.mjs","types":"dist/index.d.ts","keywords":["storage","key-value","cache","typescript"],"author":{"name":"Cardos"},"license":"MIT","publishConfig":{"access":"public"},"devDependencies":{"rimraf":"^5.0.5","tsup":"^8.0.2","typescript":"^5.3.3"},"scripts":{"build":"tsup","dev":"tsup --watch","clean":"rimraf dist","typecheck":"tsc --noEmit","buildAndPublish":"pnpm build && pnpm publish --access public"},"_id":"@cardos/key-value-storage@0.1.3","_integrity":"sha512-UTLqTq+y6XjRoW8TuWQC1qMuu7IxxIXa2jPnnZq2HEkf5eFAeqR5AjcjuElnDRSL5hPJW/gH1FQE/O+4tSaW0g==","_resolved":"/private/var/folders/1g/9_97kc2s6ng4wqj672qxnn7m0000gp/T/7f307eea911ab83bd1834b2c67f5344e/cardos-key-value-storage-0.1.3.tgz","_from":"file:cardos-key-value-storage-0.1.3.tgz","_nodeVersion":"20.18.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-UTLqTq+y6XjRoW8TuWQC1qMuu7IxxIXa2jPnnZq2HEkf5eFAeqR5AjcjuElnDRSL5hPJW/gH1FQE/O+4tSaW0g==","shasum":"7c7f52b87d71fbaa1fdcfff18afdce2cc3305f62","tarball":"https://registry.npmjs.org/@cardos/key-value-storage/-/key-value-storage-0.1.3.tgz","fileCount":9,"unpackedSize":81844,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIEl9VN6S/NYRx7SPKwik8rbtQNC5XBE5zhpAiA8kBnVJAiBKBZimN+PVMvKHhhRqPjop3PGrjgeeciOHKoBkrJKsyA=="}]},"_npmUser":{"name":"peiiii","email":"1535376447@qq.com"},"directories":{},"maintainers":[{"name":"peiiii","email":"1535376447@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/key-value-storage_0.1.3_1748673838833_0.8366238855773769"},"_hasShrinkwrap":false}},"time":{"created":"2025-05-31T06:43:58.765Z","0.1.3":"2025-05-31T06:43:59.153Z","modified":"2025-05-31T06:43:59.414Z"},"maintainers":[{"name":"peiiii","email":"1535376447@qq.com"}],"description":"A flexible key-value storage system with multi-level caching support","keywords":["storage","key-value","cache","typescript"],"author":{"name":"Cardos"},"license":"MIT","readme":"# 键值对存储系统\n\n一个灵活的键值对存储系统，支持多级缓存和多种存储提供者。\n\n## 特性\n\n- 支持多种存储提供者：\n  - 本地存储 (localStorage)\n  - 内存存储 (Map)\n  - 远程存储 (HTTP)\n  - 级联存储 (多级缓存)\n- 类型安全的键值对存储\n- 支持缓存过期时间 (TTL)\n- 支持缓存大小限制\n- 支持只读缓存层级\n- 支持缓存预热\n- 支持缓存统计\n\n## 安装\n\n```bash\npnpm add @cardos/key-value-storage\n```\n\n## 使用示例\n\n### 基本使用\n\n```typescript\nimport {\n  KeyValueStorage,\n  LocalKeyValueStorageProvider\n} from '@cardos/key-value-storage';\n\n// 创建存储实例\nconst storage = new LocalKeyValueStorageProvider();\nconst storage = new KeyValueStorage(storage);\n\n// 设置值\nawait storage.set(\"theme.mode\", \"dark\");\n\n// 获取值\nconst themeMode = await storage.get(\"theme.mode\");\n\n// 删除值\nawait storage.remove(\"theme.mode\");\n```\n\n### 使用类型安全的存储\n\n```typescript\nimport {\n  KeyValueStorage,\n  MemoryKeyValueStorageProvider,\n  TypedKeyValueStorage\n} from '@cardos/key-value-storage';\n\n// 定义存储类型\ntype AppStorage = {\n  // 主题设置\n  theme: {\n    mode: \"light\" | \"dark\";\n    name: string;\n  };\n  // 布局设置\n  layout: {\n    sidebarCollapsed: boolean;\n    activityBarExpanded: boolean;\n  };\n  // 聊天设置\n  chat: {\n    defaultSessionId: string | null;\n  };\n};\n\n// 创建类型安全的存储实例\nconst storage = new KeyValueStorage(\n  new MemoryKeyValueStorageProvider()\n) as TypedKeyValueStorage<AppStorage>;\n\n// 设置值 - 类型安全\nawait storage.set(\"theme.mode\", \"dark\"); // ✅ 正确\nawait storage.set(\"theme.name\", \"default\"); // ✅ 正确\nawait storage.set(\"layout.sidebarCollapsed\", true); // ✅ 正确\n\n// 以下代码会在编译时报错\n// await storage.set(\"theme.mode\", \"invalid\"); // ❌ 错误：类型 \"invalid\" 不能赋值给类型 \"light\" | \"dark\"\n// await storage.set(\"invalid.key\", \"value\"); // ❌ 错误：类型 \"invalid.key\" 不能赋值给类型 Paths<AppStorage>\n// await storage.set(\"theme.mode\", 123); // ❌ 错误：类型 \"number\" 不能赋值给类型 \"light\" | \"dark\"\n\n// 获取值 - 类型安全\nconst themeMode = await storage.get(\"theme.mode\"); // 类型为 \"light\" | \"dark\" | null\nconst sidebarCollapsed = await storage.get(\"layout.sidebarCollapsed\"); // 类型为 boolean | null\n\n// 以下代码会在编译时报错\n// const invalid = await storage.get(\"invalid.key\"); // ❌ 错误：类型 \"invalid.key\" 不能赋值给类型 Paths<AppStorage>\n\n// 获取所有键 - 类型安全\nconst keys = await storage.keys(); // 类型为 Paths<AppStorage>[]\nconsole.log(\"All keys:\", keys);\n\n// 获取存储大小\nconst size = await storage.size();\nconsole.log(\"Storage size:\", size);\n\n// 清除所有存储\nawait storage.clear();\n```\n\n### 使用级联存储\n\n```typescript\nimport {\n  KeyValueStorage,\n  CascadingKeyValueStorageProvider,\n  MemoryKeyValueStorageProvider,\n  LocalKeyValueStorageProvider,\n  RemoteKeyValueStorageProvider\n} from '@cardos/key-value-storage';\n\n// 创建级联存储\nconst cascadingStorage = new CascadingKeyValueStorageProvider([\n  {\n    name: 'memory',\n    storage: new MemoryKeyValueStorageProvider(),\n    maxSize: 1000,\n    ttl: 5 * 60 * 1000, // 5分钟过期\n  },\n  {\n    name: 'local',\n    storage: new LocalKeyValueStorageProvider(),\n  },\n  {\n    name: 'remote',\n    storage: new RemoteKeyValueStorageProvider('https://api.example.com'),\n  }\n]);\n\nconst storage = new KeyValueStorage(cascadingStorage);\n\n// 使用存储\nawait storage.set(\"theme.mode\", \"dark\");\nconst themeMode = await storage.get(\"theme.mode\");\n```\n\n## API\n\n### KeyValueStorage\n\n主要的存储管理器类。\n\n```typescript\nclass KeyValueStorage {\n  constructor(storageProvider: IKeyValueStorageProvider);\n  setStorageProvider(storageProvider: IKeyValueStorageProvider): void;\n  get<T extends StorageValue>(key: StorageKeyPath): Promise<T | null>;\n  set<T extends StorageValue>(key: StorageKeyPath, value: T): Promise<void>;\n  remove(key: StorageKeyPath): Promise<void>;\n  clear(): Promise<void>;\n  keys(): Promise<string[]>;\n  size(): Promise<number>;\n}\n```\n\n### TypedKeyValueStorage\n\n类型安全的存储管理器类型。\n\n```typescript\ntype TypedKeyValueStorage<T> = Omit<KeyValueStorage, \"get\" | \"set\" | \"remove\" | \"clear\" | \"keys\" | \"size\"> & {\n  get<K extends Paths<T>>(key: K): Promise<GetValueType<T, K> | null>;\n  set<K extends Paths<T>>(key: K, value: GetValueType<T, K>): Promise<void>;\n  remove<K extends Paths<T>>(key: K): Promise<void>;\n  clear(): Promise<void>;\n  keys(): Promise<Paths<T>[]>;\n  size(): Promise<number>;\n};\n```\n\n### 存储提供者\n\n#### LocalKeyValueStorageProvider\n\n使用 localStorage 实现的本地存储提供者。\n\n```typescript\nclass LocalKeyValueStorageProvider implements IKeyValueStorageProvider {\n  constructor();\n}\n```\n\n#### MemoryKeyValueStorageProvider\n\n使用 Map 实现的内存存储提供者。\n\n```typescript\nclass MemoryKeyValueStorageProvider implements IKeyValueStorageProvider {\n  constructor();\n}\n```\n\n#### RemoteKeyValueStorageProvider\n\n通过 HTTP 请求实现的远程存储提供者。\n\n```typescript\nclass RemoteKeyValueStorageProvider implements IKeyValueStorageProvider {\n  constructor(baseUrl: string);\n}\n```\n\n#### CascadingKeyValueStorageProvider\n\n实现多级缓存的级联存储提供者。\n\n```typescript\nclass CascadingKeyValueStorageProvider implements IKeyValueStorageProvider {\n  constructor(levels: CacheLevelConfig[]);\n  getStats(): Promise<Record<string, { size: number; hitCount: number; missCount: number; }>>;\n  warmup(keys: string[]): Promise<void>;\n}\n```\n\n### 类型定义\n\n```typescript\ninterface IKeyValueStorageProvider {\n  get(key: string): Promise<string | null> | string | null;\n  set(key: string, value: string): Promise<void> | void;\n  remove(key: string): Promise<void> | void;\n  clear(): Promise<void> | void;\n  keys(): Promise<string[]> | string[];\n  size(): Promise<number> | number;\n}\n\ninterface CacheLevelConfig {\n  name: string;\n  storageProvider: IKeyValueStorageProvider;\n  maxSize?: number;\n  ttl?: number;\n  readOnly?: boolean;\n}\n\n// 类型安全的工具类型\ntype Paths<T> = T extends object\n  ? {\n      [K in keyof T]: K extends string\n        ? T[K] extends object\n          ? `${K}.${Paths<T[K]>}`\n          : K\n        : never;\n    }[keyof T]\n  : never;\n\ntype GetValueType<T, P extends string> = P extends keyof T\n  ? T[P]\n  : P extends `${infer K}.${infer R}`\n  ? K extends keyof T\n    ? GetValueType<T[K], R>\n    : never\n  : never;\n```\n\n## 贡献\n\n欢迎提交 Issue 和 Pull Request。\n\n## 许可证\n\nMIT ","readmeFilename":"README.zh-CN.md","_rev":"1-3c9b0a12fd1c25e0fb1b70b046c769e8"}