KV 键值存储

基本操作

读取

import { kv } from 'void/kv';

const user = await kv.get<User>('user:123');
// User | null

写入

await kv.put('user:123', { name: 'Alice', role: 'admin' });

包括字符串在内的所有值都会被 JSON 序列化。读取时类型会被保留，因此 "123" 或 "null" 这样的字符串仍会作为字符串返回。

添加 TTL（秒）或绝对过期时间（Unix 时间戳）：

await kv.put('session:abc', sessionData, { ttl: 3600 });
await kv.put('token:xyz', tokenData, { expiration: 1700000000 });

为 key 附加元数据：

await kv.put('user:123', userData, {
  metadata: { updatedBy: 'admin' },
});

删除

await kv.delete('user:123');

列举

const result = await kv.list({ prefix: 'user:' });
// { keys: [{ name: "user:1" }, { name: "user:2" }], list_complete: true }

用 limit 与 cursor 分页：

const page = await kv.list({ prefix: 'user:', limit: 100 });
if (!page.list_complete) {
  const next = await kv.list({ prefix: 'user:', limit: 100, cursor: page.cursor });
}

带元数据读取

const result = await kv.getWithMetadata<User, { updatedBy: string }>('user:123');
// { value: User | null, metadata: { updatedBy: string } | null }

类型化 Map

对于同类型的集合，用 kv.map() 创建一个带作用域、带类型且自动加前缀的客户端：

const sessions = kv.map<Session>('sessions');

await sessions.put('abc', { userId: 1, token: '...' }, { ttl: 3600 });
// KV key: "sessions:abc"

const session = await sessions.get('abc');
// Session | null

await sessions.delete('abc');

Map 会自动为所有 key 加上 "sessions:" 前缀，并在列举时去掉该前缀：

const result = await sessions.list();
// keys: [{ name: "abc" }, { name: "def" }]（前缀已被去除）

Map 与基础客户端方法完全相同（get、put、delete、list、getWithMetadata），只是值类型被固定且前缀自动处理。