@h-ai/cache 1.0.0-beta.30 → 1.0.0-beta.32

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -8,347 +8,23 @@
8
8
 
9
9
  ## 快速开始
10
10
 
11
- ```ts
12
- import { cache } from '@h-ai/cache'
13
- import { core } from '@h-ai/core'
11
+ 使用 pnpm 安装:`pnpm add @h-ai/cache`。
14
12
 
15
- const initialized = await cache.init({ type: 'redis', host: 'localhost' })
16
- if (!initialized.success)
17
- throw new Error(initialized.error.message)
18
- try {
19
- const written = await cache.kv.set('user:1', { name: 'Alice' }, { ex: 3600 })
20
- if (!written.success)
21
- throw new Error(written.error.message)
22
- const user = await cache.kv.get<{ name: string }>('user:1')
23
- if (!user.success)
24
- throw new Error(user.error.message)
25
- if (user.data)
26
- core.logger.info('Cached user', { name: user.data.name })
27
- }
28
- finally {
29
- const closed = await cache.close()
30
- if (!closed.success)
31
- core.logger.error('Cache cleanup pending', { code: closed.error.code })
32
- }
33
- ```
34
-
35
- `cache.config` 返回的是**脱敏后的配置快照**:如后续接入 Redis `password` / `url` 等凭证字段,会自动做安全处理,不应用作回写原始密钥。
36
-
37
- ## 功能
38
-
39
- 内存 KV 在到期时间点即视为失效;`incr/decr/incrBy/decrBy` 只接受安全整数数值或整数字符串,非法增量和溢出返回 `OPERATION_FAILED` 并保留原值。Hash 的 `__proto__` / `constructor` 等名称按普通字段保留,不修改返回对象原型。
40
-
41
- Memory 的 KV、Hash、List、Set、ZSet 共用 key 命名空间。`exists/expire/expireAt/ttl/persist/keys/scan/del/type` 覆盖全部结构,期限到达后结构操作也立即视为不存在;del 按实际删除的逻辑 key 计数,错误类型的结构操作返回失败。
42
-
43
- 初始化只在健康检查成功后发布连接;失败时释放候选资源。若清理仍失败,初始化错误的 `error.ext.cleanupPending` 为 `true`。`cache.close()` 返回 `Promise<HaiResult<void>>`,等待正在进行的初始化,并合并并发关闭。开始清理后 `isInitialized` 为 `false`,配置与业务操作不再可用;清理失败仍保留资源,后续 `close()` 或 `init()` 先重试释放,成功前不会创建替代连接。调用方必须检查关闭结果。
44
-
45
- ```ts
46
- const closed = await cache.close()
47
- if (!closed.success) {
48
- // 处理清理故障后有限重试;再次失败应向应用报告。
49
- const retried = await cache.close()
50
- if (!retried.success)
51
- throw new Error(retried.error.message)
52
- }
53
- ```
54
-
55
- Redis 的 QUIT 失败后会强制 disconnect;只有实际释放成功才报告关闭成功。
56
-
57
- ### 功能输入输出
58
-
59
- 以下片段依赖本节完整初始化流程。示例中的业务值由宿主校验和授权后传入;异步领域结果先判断 success,再读取 data。表中 void 表示操作已完成且没有返回数据,null 表示不存在;同步工厂/工具直接返回表中类型。
60
-
61
- key/keys 是业务键,field/fields 是哈希字段,value/members 为 JSON 值;start/stop/index 为下标,min/max 为分数边界;seconds/ttl/timeout 为秒,timestamp 为 Unix 秒;owner 只能使用 acquire 返回值。
62
-
63
- #### cache.kv
64
-
65
- 缓存 JSON 快照。get/mget 返回值或 null(批量保序);set 输入期限/NX/XX,返回实际写入 boolean;mset 接收 [key,value][] 返回 void。
66
-
67
- | 入口 | 输入参数 | 成功结果 | 调用示例 |
68
- | --------------- | ------------------- | --------------- | ---------------------------------------------------------- |
69
- | `cache.kv.get` | key | `T \| null` | `await cache.kv.get('u:1')` |
70
- | `cache.kv.set` | key, value, options | `boolean` | `await cache.kv.set('u:1', { name: 'Alice' }, { ex: 60 })` |
71
- | `cache.kv.mget` | keys | `(T \| null)[]` | `await cache.kv.mget('u:1', 'u:2')` |
72
- | `cache.kv.mset` | entries | `void` | `await cache.kv.mset([['u:1', { name: 'Alice' }]])` |
73
-
74
- #### cache.kv
75
-
76
- 跨节点版本提交。key、expected、value 加期限选项原子比较后返回 applied;undefined 代表不存在/删除,比较失败不改原值或 TTL。
77
-
78
- | 入口 | 输入参数 | 成功结果 | 调用示例 |
79
- | ------------------------- | ----------------------------- | --------- | ------------------------------------------------ |
80
- | `cache.kv.compareAndSwap` | key, expected, value, options | `boolean` | `await cache.kv.compareAndSwap('version', 1, 2)` |
81
-
82
- #### cache.kv
83
-
84
- 按 key 管理全部数据结构;del/exists 输入一个或多个键,返回删除/存在数;type 输入单键返回结构类型。
85
-
86
- | 入口 | 输入参数 | 成功结果 | 调用示例 |
87
- | ----------------- | -------- | -------- | ------------------------------------- |
88
- | `cache.kv.del` | keys | `number` | `await cache.kv.del('u:1', 'u:2')` |
89
- | `cache.kv.exists` | keys | `number` | `await cache.kv.exists('u:1', 'u:2')` |
90
- | `cache.kv.type` | key | `string` | `await cache.kv.type('u:1')` |
91
-
92
- #### cache.kv
93
-
94
- 控制保存期限;相对秒数、Unix 秒数或键分别设置/查询/移除 TTL。修改返回 boolean,ttl 返回秒数(-1 无期限、-2 不存在)。
95
-
96
- | 入口 | 输入参数 | 成功结果 | 调用示例 |
97
- | ------------------- | -------------- | --------- | -------------------------------------------------------------------- |
98
- | `cache.kv.expire` | key, seconds | `boolean` | `await cache.kv.expire('u:1', 60)` |
99
- | `cache.kv.expireAt` | key, timestamp | `boolean` | `await cache.kv.expireAt('u:1', Math.floor(Date.now() / 1000) + 60)` |
100
- | `cache.kv.ttl` | key | `number` | `await cache.kv.ttl('u:1')` |
101
- | `cache.kv.persist` | key | `boolean` | `await cache.kv.persist('u:1')` |
102
-
103
- #### cache.kv
104
-
105
- 计数器输入 key 和可选整数增量,返回新安全整数;类型不符或溢出失败且不修改原值。
106
-
107
- | 入口 | 输入参数 | 成功结果 | 调用示例 |
108
- | ----------------- | -------------- | -------- | ----------------------------------- |
109
- | `cache.kv.incr` | key | `number` | `await cache.kv.incr('hits')` |
110
- | `cache.kv.incrBy` | key, increment | `number` | `await cache.kv.incrBy('hits', 2)` |
111
- | `cache.kv.decr` | key | `number` | `await cache.kv.decr('stock')` |
112
- | `cache.kv.decrBy` | key, decrement | `number` | `await cache.kv.decrBy('stock', 2)` |
113
-
114
- #### cache.kv
115
-
116
- 运维遍历。keys 接收 glob 返回键数组;scan 接收不透明游标和 match/count,返回 [新游标,键数组],不保证快照或无重复。
117
-
118
- | 入口 | 输入参数 | 成功结果 | 调用示例 |
119
- | --------------- | --------------- | -------------------- | -------------------------------------------------------- |
120
- | `cache.kv.keys` | pattern | `string[]` | `await cache.kv.keys('u:*')` |
121
- | `cache.kv.scan` | cursor, options | `[string, string[]]` | `await cache.kv.scan('0', { match: 'u:*', count: 100 })` |
122
-
123
- #### cache.hash
124
-
125
- 字段缓存输入 key、field/fields/对象或增量。读取返回值/null、对象、字段/值数组或长度;hset/hdel 返回新增/删除数,hexists 返回 boolean,hincrBy 返回新整数。
126
-
127
- | 入口 | 输入参数 | 成功结果 | 调用示例 |
128
- | -------------------- | --------------------- | --------------- | ----------------------------------------------- |
129
- | `cache.hash.hget` | key, field | `T \| null` | `await cache.hash.hget('u:1', 'name')` |
130
- | `cache.hash.hset` | key, field, value | `number` | `await cache.hash.hset('u:1', 'name', 'Alice')` |
131
- | `cache.hash.hdel` | key, fields | `number` | `await cache.hash.hdel('u:1', 'name')` |
132
- | `cache.hash.hexists` | key, field | `boolean` | `await cache.hash.hexists('u:1', 'name')` |
133
- | `cache.hash.hgetall` | key | `T` | `await cache.hash.hgetall('u:1')` |
134
- | `cache.hash.hkeys` | key | `string[]` | `await cache.hash.hkeys('u:1')` |
135
- | `cache.hash.hvals` | key | `T[]` | `await cache.hash.hvals('u:1')` |
136
- | `cache.hash.hlen` | key | `number` | `await cache.hash.hlen('u:1')` |
137
- | `cache.hash.hmget` | key, fields | `(T \| null)[]` | `await cache.hash.hmget('u:1', 'name', 'age')` |
138
- | `cache.hash.hincrBy` | key, field, increment | `number` | `await cache.hash.hincrBy('u:1', 'visits', 1)` |
139
-
140
- #### cache.list
141
-
142
- 有序队列输入 key、值、索引/区间;push 返回长度,pop/index 返回值/null,range 返回数组,set/trim 返回 void。阻塞 pop 输入秒数与键,返回 [key,value]/null。
143
-
144
- | 入口 | 输入参数 | 成功结果 | 调用示例 |
145
- | ------------------- | ----------------- | --------------------- | ------------------------------------------------- |
146
- | `cache.list.lpush` | key, values | `number` | `await cache.list.lpush('jobs', 'job-1')` |
147
- | `cache.list.rpush` | key, values | `number` | `await cache.list.rpush('jobs', 'job-2')` |
148
- | `cache.list.lpop` | key | `T \| null` | `await cache.list.lpop('jobs')` |
149
- | `cache.list.rpop` | key | `T \| null` | `await cache.list.rpop('jobs')` |
150
- | `cache.list.llen` | key | `number` | `await cache.list.llen('jobs')` |
151
- | `cache.list.lrange` | key, start, stop | `T[]` | `await cache.list.lrange('jobs', 0, 9)` |
152
- | `cache.list.lindex` | key, index | `T \| null` | `await cache.list.lindex('jobs', 0)` |
153
- | `cache.list.lset` | key, index, value | `void` | `await cache.list.lset('jobs', 0, 'replacement')` |
154
- | `cache.list.ltrim` | key, start, stop | `void` | `await cache.list.ltrim('jobs', 0, 99)` |
155
- | `cache.list.blpop` | timeout, keys | `[string, T] \| null` | `await cache.list.blpop(5, 'jobs')` |
156
- | `cache.list.brpop` | timeout, keys | `[string, T] \| null` | `await cache.list.brpop(5, 'jobs')` |
157
-
158
- #### cache.set_
159
-
160
- 去重/集合运算。key+成员用于增删/成员判定,返回数量/boolean;members 返回数组,card 返回基数,random/pop 按 count 返回成员/数组/null,交并差接收多个键返回数组。
161
-
162
- | 入口 | 输入参数 | 成功结果 | 调用示例 |
163
- | ------------------------ | ------------ | ------------------ | ----------------------------------------------- |
164
- | `cache.set_.sadd` | key, members | `number` | `await cache.set_.sadd('roles', 'editor')` |
165
- | `cache.set_.srem` | key, members | `number` | `await cache.set_.srem('roles', 'editor')` |
166
- | `cache.set_.smembers` | key | `T[]` | `await cache.set_.smembers('roles')` |
167
- | `cache.set_.sismember` | key, member | `boolean` | `await cache.set_.sismember('roles', 'editor')` |
168
- | `cache.set_.scard` | key | `number` | `await cache.set_.scard('roles')` |
169
- | `cache.set_.srandmember` | key, count | `T \| T[] \| null` | `await cache.set_.srandmember('roles', 2)` |
170
- | `cache.set_.spop` | key, count | `T \| T[] \| null` | `await cache.set_.spop('roles', 1)` |
171
- | `cache.set_.sinter` | keys | `T[]` | `await cache.set_.sinter('roles:a', 'roles:b')` |
172
- | `cache.set_.sunion` | keys | `T[]` | `await cache.set_.sunion('roles:a', 'roles:b')` |
173
- | `cache.set_.sdiff` | keys | `T[]` | `await cache.set_.sdiff('roles:a', 'roles:b')` |
174
-
175
- #### cache.zset
176
-
177
- 排行榜输入成员及 score、排序范围或分数范围;新增/删除返回数量,score/rank 返回数字/null,range 返回成员或带分数对象数组,incrBy 返回新分数,card/count 返回数量。
178
-
179
- | 入口 | 输入参数 | 成功结果 | 调用示例 |
180
- | ----------------------------- | ---------------------------- | ----------------------- | ------------------------------------------------------------------------- |
181
- | `cache.zset.zadd` | key, members | `number` | `await cache.zset.zadd('scores', { member: 'u1', score: 10 })` |
182
- | `cache.zset.zrem` | key, members | `number` | `await cache.zset.zrem('scores', 'u1')` |
183
- | `cache.zset.zscore` | key, member | `number \| null` | `await cache.zset.zscore('scores', 'u1')` |
184
- | `cache.zset.zrank` | key, member | `number \| null` | `await cache.zset.zrank('scores', 'u1')` |
185
- | `cache.zset.zrevrank` | key, member | `number \| null` | `await cache.zset.zrevrank('scores', 'u1')` |
186
- | `cache.zset.zrange` | key, start, stop, withScores | `string[] \| ZMember[]` | `await cache.zset.zrange('scores', 0, 9, true)` |
187
- | `cache.zset.zrevrange` | key, start, stop, withScores | `string[] \| ZMember[]` | `await cache.zset.zrevrange('scores', 0, 9, true)` |
188
- | `cache.zset.zrangeByScore` | key, min, max, options | `string[] \| ZMember[]` | `await cache.zset.zrangeByScore('scores', 10, 100, { withScores: true })` |
189
- | `cache.zset.zcard` | key | `number` | `await cache.zset.zcard('scores')` |
190
- | `cache.zset.zcount` | key, min, max | `number` | `await cache.zset.zcount('scores', 10, 100)` |
191
- | `cache.zset.zincrBy` | key, increment, member | `number` | `await cache.zset.zincrBy('scores', 5, 'u1')` |
192
- | `cache.zset.zremRangeByRank` | key, start, stop | `number` | `await cache.zset.zremRangeByRank('scores', 0, 9)` |
193
- | `cache.zset.zremRangeByScore` | key, min, max | `number` | `await cache.zset.zremRangeByScore('scores', 0, 10)` |
194
-
195
- #### cache.lock
196
-
197
- 短期互斥。acquire 输入键/TTL 返回 owner 或 null;release/extend 必须传 owner,返回 boolean;isLocked 仅观察占用。锁不替代业务存储的 CAS。
198
-
199
- | 入口 | 输入参数 | 成功结果 | 调用示例 |
200
- | --------------------- | --------------- | ---------------- | ------------------------------------------------ |
201
- | `cache.lock.acquire` | key, options | `string \| null` | `await cache.lock.acquire('daily', { ttl: 30 })` |
202
- | `cache.lock.release` | key, owner | `boolean` | `await cache.lock.release('daily', owner)` |
203
- | `cache.lock.isLocked` | key | `boolean` | `await cache.lock.isLocked('daily')` |
204
- | `cache.lock.extend` | key, ttl, owner | `boolean` | `await cache.lock.extend('daily', 60, owner)` |
205
-
206
- #### cache
207
-
208
- 健康检查,无参数;返回后端响应字符串,连接故障为失败。
209
-
210
- | 入口 | 输入参数 | 成功结果 | 调用示例 |
211
- | ------------ | -------- | -------- | -------------------- |
212
- | `cache.ping` | 无参数 | `string` | `await cache.ping()` |
213
-
214
- - 开发/测试场景下的内存缓存
215
- - 生产环境 Redis 缓存(单机、URL、集群、哨兵)
216
- - IAM 会话与权限相关的集合缓存
217
- - 分布式锁(多节点部署互斥控制)
218
-
219
- ### API 概览
220
-
221
- - `cache.kv`: 字符串/对象键值与 TTL(`set/get/mget/mset/expire/ttl/...`)
222
- - `cache.hash`: 哈希结构(`hset/hget/hgetall/...`)
223
- - `cache.list`: 列表结构(`lpush/rpush/lpop/rpop/...`)
224
- - `cache.set_`: 集合结构(`sadd/smembers/sismember/...`)
225
- - `cache.zset`: 有序集合(`zadd/zrange/zrevrange/...`)
226
- - `cache.lock`: 分布式锁(`acquire/release/isLocked/extend`)
227
-
228
- `kv.set` 返回 `HaiResult<boolean>`:`data=true` 表示实际写入,NX/XX 未命中返回 `success=true,data=false` 且不改变原值或 TTL。签发票据、会话或登记公钥前必须检查这两个字段。`ex/px/exat/pxat` 分别使用秒、毫秒、Unix 秒、Unix 毫秒,须为正安全整数且只能指定一种,与 `keepTtl=true` 互斥;`nx/xx` 也互斥。零、负数、小数、非有限值或溢出返回 `INVALID_SET_OPTIONS`(`cache:016`),不会写成永久键。过去的正绝对时间表示立即过期。省略期限会移除原 TTL;`keepTtl` 保留已有 TTL,新键仍永久保存。memory 和 Redis 都保存 JSON 快照。
229
-
230
- compareAndSwap 对一个 key 原子比较 JSON 值并替换/删除,返回 boolean applied;expected=undefined 表示不存在,value=undefined 表示删除,null 是实际 JSON 值。px 必须为正整数且与 keepTtl 互斥,省略过期策略会持久保存;比较失败不改 TTL。可用于跨节点版本提交,不能把进程锁当作提交条件。
231
-
232
- ### Cluster 多键与扫描
233
-
234
- `mget/del/exists` 支持跨 slot,按独立 key 有界执行,mget 保留输入顺序;不提供跨 slot 的原子性或快照。DEL 失败可能已有部分键被删除,重试幂等。`mset`、集合交/并/差和多键阻塞弹出要求同 slot;用共同的 `{hash-tag}` 分组,否则返回 `CROSS_SLOT`,MSET 不进行部分写入。
235
-
236
- `scan` 首次传字符串 `'0'`,返回不透明字符串游标,可在配置和拓扑一致的不同应用节点继续。Cluster 遍历全部主节点;拓扑、match 或 keyPrefix 变化返回 `SCAN_TOPOLOGY_CHANGED`,调用方从 `'0'` 重新遍历。返回 key 已去除 keyPrefix,前缀中的 glob 字符按字面量匹配;`keys` 也遵循此规则并去重。SCAN 无快照,允许重复项,count 是正整数提示值,不保证返回条数。无效游标/count 返回 `INVALID_SCAN`。
237
-
238
- ```ts
239
- let cursor = '0'
240
- do {
241
- const page = await cache.kv.scan(cursor, { match: 'users:*', count: 100 })
242
- if (!page.success)
243
- throw new Error(page.error.message)
244
- cursor = page.data[0]
245
- await consume(page.data[1])
246
- } while (cursor !== '0')
247
- ```
248
-
249
- ### 分布式锁
250
-
251
- 基于 SET NX EX 模式实现的分布式互斥锁,适用于多节点部署场景。
252
-
253
- ```ts
254
- // 获取锁(TTL 30 秒,owner 用于标识持有者)
255
- const acquired = await cache.lock.acquire('my-lock', { ttl: 30 })
256
- if (acquired.success && acquired.data) {
257
- try {
258
- // 执行受保护操作
259
- }
260
- finally {
261
- await cache.lock.release('my-lock', acquired.data)
262
- }
263
- }
264
-
265
- // 检查锁状态
266
- const locked = await cache.lock.isLocked('my-lock')
267
-
268
- // 续期锁
269
- if (acquired.success && acquired.data)
270
- await cache.lock.extend('my-lock', 60, acquired.data)
271
- ```
272
-
273
- - **Memory 后端**:基于 Map + TTL 过期机制
274
- - **Redis 后端**:使用 `SET NX EX` 原子获锁,Lua 脚本实现 owner 验证的安全释放/续期
275
- - `acquire` 返回本次获锁的唯一凭据,锁占用时为 `null`;释放/续租必须传回该凭据,禁止使用节点 ID 或无凭据强制操作。
276
-
277
- owner 只保护锁的续期与释放,不是资源 fencing token。进程暂停或租约到期后旧任务仍能继续;最终写入必须在资源存储中使用 CAS、代际条件或事务约束。续租成功或最后返回失败都不能代替提交条件。
278
-
279
- ### 生产共享状态
280
-
281
- 生产仅使用 Redis(含 Cluster);memory 只用于开发/明确测试。Redis 故障返回失败,不回退本机缓存。 NODE_ENV 或 HAI_CORE_ENV 为 production 时在初始化发布成功前校验;仅 HAI_E2E=1/HAI_E2E_MOCK=1 明确测试可豁免。 [状态、并发和恢复边界](../../.agents/instructions/distributed-state.md).
282
-
283
- ## 配置
284
-
285
- 生命周期:init 输入后端/业务配置,成功后才能使用;close 在释放借用依赖前等待完成。返回值以快速开始示例和公开签名为准。
286
-
287
- ```ts
288
- // Memory(开发/测试)
289
- await cache.init({ type: 'memory' })
290
-
291
- // Redis 单机
292
- await cache.init({
293
- type: 'redis',
294
- host: 'localhost',
295
- port: 6379,
296
- password: 'secret',
297
- db: 0,
298
- })
299
-
300
- // Redis URL(优先级最高)
301
- await cache.init({
302
- type: 'redis',
303
- url: 'redis://:password@localhost:6379/0',
304
- })
305
-
306
- // Redis 集群
307
- await cache.init({
308
- type: 'redis',
309
- cluster: [
310
- { host: 'node1', port: 6379 },
311
- { host: 'node2', port: 6379 },
312
- ],
313
- })
314
-
315
- // Redis 哨兵
316
- await cache.init({
317
- type: 'redis',
318
- sentinel: {
319
- sentinels: [
320
- { host: 'sentinel1', port: 26379 }
321
- ],
322
- name: 'mymaster',
323
- },
324
- })
325
- ```
326
-
327
- 内置后端由 `cache.init(config)` 选择 memory/redis;Provider 实现是内部契约,不提供自定义后端注册入口。
13
+ [跟着最小示例完成接入](../../docs/usage/function/cache.md#quick-start)。
328
14
 
329
- `password` 用于单机、Cluster 与 Sentinel 数据节点;Cluster 发现和重定向后的节点连接也携带密码。配置 `url` 时采用 URL 自身的认证信息,独立 password 字段不覆盖它。
15
+ ## 配置清单
330
16
 
331
- 配置由宿主加载和校验,再传入本模块;私密值放服务端私有环境,不传到浏览器。按实际使用场景逐项选择后端、容量、期限和日志策略,修改后重新初始化并核验成功结果。
17
+ 生成的项目在 `config/_cache.yml` 中设置后端类型和 Redis 连接参数。应用启动代码读取该文件,把配置对象传给 `cache.init(config)`。
332
18
 
333
- [逐项配置说明、适用场景和示例](../../docs/usage/configuration/data.md).
19
+ 在[模块配置清单](../../docs/usage/configuration/cache.md)中查阅配置入口、默认值、取值限制和生效条件。
334
20
 
335
- ## 错误处理
21
+ ## 功能说明
336
22
 
337
- 领域操作先判断 `result.success`,失败按本模块错误定义与安全提示处理,服务端保留错误码、关联编号和脱敏原因。同步工具、工厂、流迭代及生命周期按各自签名处理,不把 Promise 完成视为业务成功。具体失败与恢复边界见对应功能。
23
+ [查 API 清单](../../docs/usage/function/cache.md#api-reference),包含调用入口、输入、返回值和用法。
338
24
 
339
- 所有操作返回 `HaiResult<T>`,常用错误码如下:
25
+ ## 数据结构
340
26
 
341
- | 错误码 | code | 说明 |
342
- | -------------------------------------- | --------------- | ---------------- |
343
- | `HaiCacheError.CONNECTION_FAILED` | `hai:cache:001` | 连接失败 |
344
- | `HaiCacheError.OPERATION_FAILED` | `hai:cache:002` | 操作失败 |
345
- | `HaiCacheError.SERIALIZATION_FAILED` | `hai:cache:003` | 序列化失败 |
346
- | `HaiCacheError.DESERIALIZATION_FAILED` | `hai:cache:004` | 反序列化失败 |
347
- | `HaiCacheError.KEY_NOT_FOUND` | `hai:cache:005` | 键不存在 |
348
- | `HaiCacheError.TIMEOUT` | `hai:cache:006` | 超时 |
349
- | `HaiCacheError.NOT_INITIALIZED` | `hai:cache:010` | 未初始化 |
350
- | `HaiCacheError.UNSUPPORTED_TYPE` | `hai:cache:011` | 不支持的缓存类型 |
351
- | `HaiCacheError.CONFIG_ERROR` | `hai:cache:012` | 配置错误 |
27
+ 查看[数据结构](../../docs/usage/data/cache.md),了解Redis/内存的数据类型、键、TTL 和锁所有者。
352
28
 
353
29
  ## 开发测试
354
30
 
@@ -356,7 +32,7 @@ await cache.init({
356
32
  pnpm --filter @h-ai/cache test
357
33
  ```
358
34
 
359
- > Redis 相关测试需要 Docker 环境。
35
+ > Redis 集成测试需要可用的 Docker API,例如 Docker 或已启用 Docker 兼容 API 的 Podman。
360
36
 
361
37
  公开契约与内部结构均提供可类型检查的示例;见[模块 JSDoc 约定](../../.agents/instructions/module-conventions.md#jsdoc-与示例验证).
362
38
 
package/dist/index.d.ts CHANGED
@@ -3,9 +3,9 @@ import * as _h_ai_core from '@h-ai/core';
3
3
  import { HaiResult } from '@h-ai/core';
4
4
 
5
5
  /**
6
- * @h-ai/cache — 错误码 + 配置 Schema
6
+ * @h-ai/cache — 配置 Schema
7
7
  *
8
- * 定义缓存模块的错误码常量、Zod Schema 和配置类型。
8
+ * 定义缓存模块的 Zod Schema 和配置类型。
9
9
  * @module cache-config
10
10
  */
11
11
 
@@ -184,7 +184,7 @@ declare const HaiCacheError: {
184
184
  /**
185
185
  * 可缓存的值类型
186
186
  *
187
- * 说明:`object` 包含普通对象与数组;函数、Symbol、BigInt 等不建议直接缓存。
187
+ * `object` 包含普通对象与数组。值须能序列化为 JSON 文本,序列化失败返回 SERIALIZATION_FAILED。
188
188
  * @example
189
189
  * ```ts
190
190
  * import type { CacheValue } from '@h-ai/cache'
@@ -317,7 +317,7 @@ interface KvOperations {
317
317
  expireAt: (key: string, timestamp: number) => Promise<HaiResult<boolean>>;
318
318
  /** 获取剩余过期时间(秒);-1 永不过期,-2 不存在 */
319
319
  ttl: (key: string) => Promise<HaiResult<number>>;
320
- /** 移除过期时间 */
320
+ /** 移除过期时间;仅实际清除期限时返回 true。 */
321
321
  persist: (key: string) => Promise<HaiResult<boolean>>;
322
322
  /** 自增 1;键不存在时从 0 开始;值非数字时返回 OPERATION_FAILED */
323
323
  incr: (key: string) => Promise<HaiResult<number>>;
@@ -327,7 +327,7 @@ interface KvOperations {
327
327
  decr: (key: string) => Promise<HaiResult<number>>;
328
328
  /** 自减指定值;键不存在时从 0 开始 */
329
329
  decrBy: (key: string, decrement: number) => Promise<HaiResult<number>>;
330
- /** 批量获取;不存在的键对应位置返回 null。Cluster 跨 slot 保留输入顺序,不保证同一时刻快照。 */
330
+ /** 批量获取;不存在的键或集合类键在对应位置返回 null。Cluster 跨 slot 保留输入顺序,不保证同一时刻快照。 */
331
331
  mget: <T = CacheValue>(...keys: string[]) => Promise<HaiResult<(T | null)[]>>;
332
332
  /** 原子批量设置;Cluster 中所有 key 必须同 slot,可使用共同的 {hash-tag}。 */
333
333
  mset: (entries: Array<[string, CacheValue]>) => Promise<HaiResult<void>>;
@@ -420,9 +420,9 @@ interface ListOperations {
420
420
  lset: (key: string, index: number, value: CacheValue) => Promise<HaiResult<void>>;
421
421
  /** 保留指定范围的元素,范围外的元素被删除 */
422
422
  ltrim: (key: string, start: number, stop: number) => Promise<HaiResult<void>>;
423
- /** 阻塞式从左侧弹出;返回 [key, value] 或超时返回 null。Cluster 多键须同 slot;memory 非阻塞立即返回。 */
423
+ /** Redis 等待 timeout 秒后返回 null,传 0 持续等待。返回 [逻辑键, 值];关闭缓存会以失败结束等待。Cluster 多键须同 slot;memory 立即返回。 */
424
424
  blpop: <T = CacheValue>(timeout: number, ...keys: string[]) => Promise<HaiResult<[string, T] | null>>;
425
- /** 阻塞式从右侧弹出;返回 [key, value] 或超时返回 null。Cluster 多键须同 slot;memory 非阻塞立即返回。 */
425
+ /** 从右侧弹出。等待时间、返回键、关闭和 Cluster 约束与 blpop 相同。 */
426
426
  brpop: <T = CacheValue>(timeout: number, ...keys: string[]) => Promise<HaiResult<[string, T] | null>>;
427
427
  }
428
428
  /**
@@ -450,9 +450,9 @@ interface SetOperations {
450
450
  sismember: (key: string, member: CacheValue) => Promise<HaiResult<boolean>>;
451
451
  /** 获取成员数量;键不存在时返回 0 */
452
452
  scard: (key: string) => Promise<HaiResult<number>>;
453
- /** 随机获取成员;不指定 count 返回单个值,指定 count 返回数组;空集合返回 null */
453
+ /** 随机获取成员;省略 count 时返回单个值或 null。指定 count 返回数组,正数不重复,负数允许重复。 */
454
454
  srandmember: <T = CacheValue>(key: string, count?: number) => Promise<HaiResult<T | T[] | null>>;
455
- /** 随机弹出成员(会从集合中移除);不指定 count 返回单个值,指定 count 返回数组;空集合返回 null */
455
+ /** 随机弹出并移除成员;省略 count 时返回单个值或 null,指定非负 count 时返回最多 count 项的数组。 */
456
456
  spop: <T = CacheValue>(key: string, count?: number) => Promise<HaiResult<T | T[] | null>>;
457
457
  /** 集合交集;任一 key 不存在时返回空数组。Cluster 多键须同 slot,否则返回 CROSS_SLOT。 */
458
458
  sinter: <T = CacheValue>(...keys: string[]) => Promise<HaiResult<T[]>>;
@@ -510,7 +510,7 @@ interface ZSetOperations {
510
510
  /**
511
511
  * 分布式锁操作接口
512
512
  *
513
- * 基于 SET NX EX 模式实现分布式互斥锁,适用于多节点部署场景。
513
+ * Redis 多节点共享锁。同一个业务执行可凭本次 owner 重入,并按成功进入次数逐次释放。
514
514
  * @example
515
515
  * ```ts
516
516
  * import type { LockOperations } from '@h-ai/cache'
@@ -528,23 +528,24 @@ interface LockOperations {
528
528
  /**
529
529
  * 尝试获取分布式锁
530
530
  *
531
- * 通过 SET NX EX 原子操作实现。每次生成不可复用的所有权凭据;占用时返回 null。
532
- * owner 仅用于租约续期/释放,不是资源的 fencing token;暂停/超时后旧操作仍可能继续。
531
+ * 首次获取生成独立的 owner;锁被占用时返回 null。
532
+ * 携带有效 owner 时重入,返回原 owner 并保留过期时间。无效或过期的 owner 返回 null。
533
+ * owner 只校验租约重入、续期和释放;暂停/超时后旧操作仍可能继续。
533
534
  * 最终资源写入必须自行使用 CAS/代际条件或数据库事务约束,不能只检查续期或返回失败。
534
535
  *
535
536
  * @param key - 锁键名
536
537
  * @param options - 锁选项
537
- * @returns 获锁成功返回唯一凭据,锁占用时返回 null
538
+ * @returns 获锁或重入成功返回当前凭据,锁占用或重入被拒绝时返回 null。
538
539
  */
539
540
  acquire: (key: string, options?: LockOptions) => Promise<HaiResult<string | null>>;
540
541
  /**
541
542
  * 释放分布式锁
542
543
  *
543
- * 仅当锁由当前持有者持有时才释放(通过 owner 比对),防止误释放他人的锁。
544
+ * 当前持有者每调用一次释放一个持有层级,最后一层释放后其他调用方才能取得锁。
544
545
  *
545
546
  * @param key - 锁键名
546
547
  * @param owner - 本次 acquire 返回的唯一凭据,不能使用节点 ID
547
- * @returns true 表示释放成功,false 表示锁不存在或非当前持有者
548
+ * @returns true 表示成功释放一层,false 表示锁不存在或凭据不匹配。
548
549
  */
549
550
  release: (key: string, owner: string) => Promise<HaiResult<boolean>>;
550
551
  /**
@@ -557,10 +558,10 @@ interface LockOperations {
557
558
  /**
558
559
  * 续期锁的过期时间
559
560
  *
560
- * 仅当锁由当前持有者持有时才续期。
561
+ * 仅持有者可以更新过期时间,持有次数保持原值。
561
562
  *
562
563
  * @param key - 锁键名
563
- * @param ttl - 新的过期时间(秒)
564
+ * @param ttl - 新的过期时间(正安全整数秒,换算后的到期毫秒须为安全整数)
564
565
  * @param owner - 本次 acquire 返回的唯一凭据
565
566
  * @returns true 表示续期成功,false 表示锁不存在或非当前持有者
566
567
  */
@@ -575,13 +576,16 @@ interface LockOperations {
575
576
  * ```
576
577
  */
577
578
  interface LockOptions {
578
- /** 锁过期时间(秒);默认 30 */
579
+ /** 首次获取的锁过期时间(正安全整数秒,换算后的到期毫秒须为安全整数);默认 30。与 owner 互斥。 */
579
580
  ttl?: number;
581
+ /** 重入凭据,取自首次 acquire 成功返回的 owner。重入保留到期时间,与 ttl 同传失败。 */
582
+ owner?: string;
580
583
  }
581
584
  /**
582
585
  * 复合缓存操作接口,聚合所有数据结构的操作子接口
583
586
  *
584
- * 通过 `cache.kv` / `cache.hash` / `cache.list` / `cache.set_` / `cache.zset` / `cache.lock` 分别访问
587
+ * 通过 `cache.kv` / `cache.hash` / `cache.list` / `cache.set_` / `cache.zset` / `cache.lock` 分别访问。
588
+ * 开始清理原 Provider 后,已取出的操作对象和方法在再次调用时返回 NOT_INITIALIZED。
585
589
  * @example
586
590
  * ```ts
587
591
  * import type { CacheCompositeOperations } from '@h-ai/cache'