{"_id":"@cardos/key-value-store","_rev":"3-ba417afaa73e68bfdf1a5e3087cba0d1","name":"@cardos/key-value-store","dist-tags":{"latest":"0.1.2"},"versions":{"0.1.0":{"name":"@cardos/key-value-store","version":"0.1.0","keywords":["storage","key-value","cache","typescript"],"author":{"name":"Cardos"},"license":"MIT","_id":"@cardos/key-value-store@0.1.0","maintainers":[{"name":"peiiii","email":"1535376447@qq.com"}],"dist":{"shasum":"d4c3b2871125c84e09b75124595dfe4deb7a0461","tarball":"https://registry.npmjs.org/@cardos/key-value-store/-/key-value-store-0.1.0.tgz","fileCount":7,"integrity":"sha512-L0IzA4j8h5xx8FYxqS3Zf/7qeiUVgarkTg2vIn3+Nsw9WGAUKBzOgDwb5km/8HTF2iL9MCqbAYh+pjiHXibhSA==","signatures":[{"sig":"MEQCIFddbLGxnAmdaJZPeWIs+cdwBahLZq38h+5JGfmTwZtIAiBWpDjFezXo2oLMmfAJgkj3UE11wG769YUVzb83fzwZSQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":67347},"main":"dist/index.js","_from":"file:cardos-key-value-store-0.1.0.tgz","types":"dist/index.d.ts","module":"dist/index.mjs","scripts":{"dev":"tsup --watch","build":"tsup","clean":"rimraf dist","typecheck":"tsc --noEmit","buildAndPublish":"pnpm build && pnpm publish --access public"},"_npmUser":{"name":"peiiii","email":"1535376447@qq.com"},"_resolved":"/private/var/folders/1g/9_97kc2s6ng4wqj672qxnn7m0000gp/T/f477327e94a2ec69da5208bb4d29fb07/cardos-key-value-store-0.1.0.tgz","_integrity":"sha512-L0IzA4j8h5xx8FYxqS3Zf/7qeiUVgarkTg2vIn3+Nsw9WGAUKBzOgDwb5km/8HTF2iL9MCqbAYh+pjiHXibhSA==","_npmVersion":"10.8.2","description":"A flexible key-value storage system with multi-level caching support","directories":{},"_nodeVersion":"20.18.2","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.2","rimraf":"^5.0.5","typescript":"^5.3.3"},"_npmOperationalInternal":{"tmp":"tmp/key-value-store_0.1.0_1748672074873_0.9918486889574969","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@cardos/key-value-store","version":"0.1.1","keywords":["storage","key-value","cache","typescript"],"author":{"name":"Cardos"},"license":"MIT","_id":"@cardos/key-value-store@0.1.1","maintainers":[{"name":"peiiii","email":"1535376447@qq.com"}],"dist":{"shasum":"52158242c5be09316956267c3861d31b65ddb6fe","tarball":"https://registry.npmjs.org/@cardos/key-value-store/-/key-value-store-0.1.1.tgz","fileCount":9,"integrity":"sha512-yNepc3tbKZjL5nJECecBZXsU9l0d27C4yhMM9ITvZrQgZorE4NcvO/qN912wxmkxrveTfkXlTGOG5NP3DItXIA==","signatures":[{"sig":"MEYCIQCs8g26XCIw4lnPNhInU+KxHBW79lE/OXwYMIzAFLO0ggIhALF/7Ixm9TNCJx4D5LZ3i05k7zaZSK5nuEMvj1UbE8ke","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":80136},"main":"dist/index.js","_from":"file:cardos-key-value-store-0.1.1.tgz","types":"dist/index.d.ts","module":"dist/index.mjs","scripts":{"dev":"tsup --watch","build":"tsup","clean":"rimraf dist","typecheck":"tsc --noEmit","buildAndPublish":"pnpm build && pnpm publish --access public"},"_npmUser":{"name":"peiiii","email":"1535376447@qq.com"},"_resolved":"/private/var/folders/1g/9_97kc2s6ng4wqj672qxnn7m0000gp/T/2b1fbf4d98754dce3fe133f62a533a01/cardos-key-value-store-0.1.1.tgz","_integrity":"sha512-yNepc3tbKZjL5nJECecBZXsU9l0d27C4yhMM9ITvZrQgZorE4NcvO/qN912wxmkxrveTfkXlTGOG5NP3DItXIA==","_npmVersion":"10.8.2","description":"A flexible key-value storage system with multi-level caching support","directories":{},"_nodeVersion":"20.18.2","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.2","rimraf":"^5.0.5","typescript":"^5.3.3"},"_npmOperationalInternal":{"tmp":"tmp/key-value-store_0.1.1_1748672737128_0.5828660751139061","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@cardos/key-value-store","version":"0.1.2","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-store@0.1.2","_integrity":"sha512-LCs3q5b6dpZC26GXJ3I5yGERyp6vC5AZaSDXbKP9/Oum4YvmjnVnjt73AtIjR7c8Newb7yAUMgLzaX4Y8s/5MA==","_resolved":"/private/var/folders/1g/9_97kc2s6ng4wqj672qxnn7m0000gp/T/e580386017c54afdd8fe9dbfd84aae59/cardos-key-value-store-0.1.2.tgz","_from":"file:cardos-key-value-store-0.1.2.tgz","_nodeVersion":"20.18.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-LCs3q5b6dpZC26GXJ3I5yGERyp6vC5AZaSDXbKP9/Oum4YvmjnVnjt73AtIjR7c8Newb7yAUMgLzaX4Y8s/5MA==","shasum":"17d38aa963bffba3b50338c83b4d1b3d7be31493","tarball":"https://registry.npmjs.org/@cardos/key-value-store/-/key-value-store-0.1.2.tgz","fileCount":9,"unpackedSize":80136,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCxF2iMWC5S7pNteVmbfqGXYmJGV+WZy9PJ76NLyhpwIQIga40dvS3LL52Qk4qTVJXQVoQQ8h+GGrnhgwOrVAOcC9c="}]},"_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-store_0.1.2_1748672827194_0.8374714071378446"},"_hasShrinkwrap":false}},"time":{"created":"2025-05-31T06:14:34.755Z","modified":"2025-05-31T06:27:07.561Z","0.1.0":"2025-05-31T06:14:35.041Z","0.1.1":"2025-05-31T06:25:37.356Z","0.1.2":"2025-05-31T06:27:07.387Z"},"author":{"name":"Cardos"},"license":"MIT","keywords":["storage","key-value","cache","typescript"],"description":"A flexible key-value storage system with multi-level caching support","maintainers":[{"name":"peiiii","email":"1535376447@qq.com"}],"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-store\n```\n\n## 使用示例\n\n### 基本使用\n\n```typescript\nimport {\n  KeyValueStorage,\n  LocalKeyValueStoreProvider\n} from '@cardos/key-value-store';\n\n// 创建存储实例\nconst store = new LocalKeyValueStoreProvider();\nconst storage = new KeyValueStorage(store);\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  MemoryKeyValueStoreProvider,\n  TypedKeyValueStorage\n} from '@cardos/key-value-store';\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 MemoryKeyValueStoreProvider()\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  CascadingKeyValueStoreProvider,\n  MemoryKeyValueStoreProvider,\n  LocalKeyValueStoreProvider,\n  RemoteKeyValueStoreProvider\n} from '@cardos/key-value-store';\n\n// 创建级联存储\nconst cascadingStore = new CascadingKeyValueStoreProvider([\n  {\n    name: 'memory',\n    store: new MemoryKeyValueStoreProvider(),\n    maxSize: 1000,\n    ttl: 5 * 60 * 1000, // 5分钟过期\n  },\n  {\n    name: 'local',\n    store: new LocalKeyValueStoreProvider(),\n  },\n  {\n    name: 'remote',\n    store: new RemoteKeyValueStoreProvider('https://api.example.com'),\n  }\n]);\n\nconst storage = new KeyValueStorage(cascadingStore);\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(store: KeyValueStore);\n  setStore(store: KeyValueStore): 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#### LocalKeyValueStoreProvider\n\n使用 localStorage 实现的本地存储提供者。\n\n```typescript\nclass LocalKeyValueStoreProvider implements KeyValueStore {\n  constructor();\n}\n```\n\n#### MemoryKeyValueStoreProvider\n\n使用 Map 实现的内存存储提供者。\n\n```typescript\nclass MemoryKeyValueStoreProvider implements KeyValueStore {\n  constructor();\n}\n```\n\n#### RemoteKeyValueStoreProvider\n\n通过 HTTP 请求实现的远程存储提供者。\n\n```typescript\nclass RemoteKeyValueStoreProvider implements KeyValueStore {\n  constructor(baseUrl: string);\n}\n```\n\n#### CascadingKeyValueStoreProvider\n\n实现多级缓存的级联存储提供者。\n\n```typescript\nclass CascadingKeyValueStoreProvider implements KeyValueStore {\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 KeyValueStore {\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  store: KeyValueStore;\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"}