KVStorage
持久保存字符串键值,设置过期时间并按前缀分页。
KVStorage 提供持久化字符串键值存储,支持过期时间和前缀分页,适合保存配置、缓存值和 JSON 文本。
先创建并关联资源;关联与共享规则见模块概览。
import { KVStorage } from 'lexmount:storage';
const kv = await KVStorage.open('cache');KVStorage.storages()
功能: 列出当前实例已关联的 KV 资源。
参数: 无。
返回值: Promise<{ id: string; name: string }[]>。
KVStorage.open(name)
功能: 按名称打开已有且已关联的 KV 资源。
参数: name: string 必填,名称规则见资源与关联。
返回值: Promise<Readonly<NamedKVStorage>>,含只读 name: string 和下列方法,句柄绑定选中的资源 ID。
kv.put(key, value, options?)
功能: 保存字符串,替换同一 key 的旧值和过期配置。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
key | string | 是 | 非空有效 Unicode,无 NUL,最多 1024 UTF-8 字节 |
value | string | 是 | 可为空,有效 Unicode,无 NUL,最多 1 MiB UTF-8 文本 |
options.expirationTtl | number | 否 | 正安全整数秒,从存储服务端时钟计算有效期 |
options.expiration | number | 否 | 未来的 Unix 秒时间戳,须为安全整数 |
过期选项只能提供其中一个,省略两者则永久保存并清除旧 TTL。每次 put 都重新设置过期配置。
返回值: Promise<void>,写入提交后完成。值按字符串保存;非字符串的自动转换遵循 String(value),不会自动 JSON 序列化。保存 JSON 应先使用 JSON.stringify()。
kv.get(key)
功能: 读取未过期值。
参数: key: string 必填,规则与 put 相同。
返回值: Promise<string | null>,不存在或已过期时为 null,允许返回空字符串;JSON 需自行解析,不要把空字符串当作缺失。
kv.delete(key)
功能: 删除一个 key,不删除 KV 资源本身。
参数: key: string 必填,规则与 put 相同。
返回值: Promise<void>,不存在时也成功。
kv.list(options?)
功能: 按 UTF-8 字节顺序分页列出未过期 key。
| 参数 | 类型 | 默认值与说明 |
|---|---|---|
options.prefix | string | 空字符串;字面前缀,% 和 _ 不是通配符 |
options.cursor | string | 可选,必须来自相同资源和 prefix |
options.limit | number | 1000;1~1000 的整数 |
返回值: Promise<KVPage>,含 keys: { name: string; expiration?: number }[]、truncated: boolean 和 cursor: string | null。expiration 为存在时的 Unix 秒时间戳,最后一页 cursor 为 null。
Get 和 list 立即隐藏过期记录。并发修改时分页不保证快照;每次操作独立提交,不提供多键事务或 compare-and-swap。完整用法见 KV 示例。
错误处理见 StorageError,声明见 storage.d.ts。
