@h-ai/cache 1.0.0-beta.31 → 1.0.0-beta.33
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.en.md +1 -1
- package/README.ja.md +1 -1
- package/README.md +1 -1
- package/dist/index.d.ts +23 -19
- package/dist/index.js +626 -370
- package/dist/index.js.map +1 -1
- package/package.json +2 -2
package/README.en.md
CHANGED
|
@@ -32,7 +32,7 @@ See the [data reference](../../docs/usage/data/cache.en.md) for Redis and memory
|
|
|
32
32
|
pnpm --filter @h-ai/cache test
|
|
33
33
|
```
|
|
34
34
|
|
|
35
|
-
> Redis tests require Docker.
|
|
35
|
+
> Redis integration tests require a Docker API, provided by Docker or Podman with its Docker-compatible API enabled.
|
|
36
36
|
|
|
37
37
|
Public contracts and internal structures include typechecked examples; see the [JSDoc conventions (Chinese)](../../.agents/instructions/module-conventions.md#jsdoc-与示例验证).
|
|
38
38
|
|
package/README.ja.md
CHANGED
|
@@ -32,7 +32,7 @@ Redis とメモリの値型、キー、TTL、ロック所有者については[
|
|
|
32
32
|
pnpm --filter @h-ai/cache test
|
|
33
33
|
```
|
|
34
34
|
|
|
35
|
-
> Redis
|
|
35
|
+
> Redis の統合テストには Docker API が必要です。Docker、または Docker 互換 API を有効にした Podman を使用できます。
|
|
36
36
|
|
|
37
37
|
公開契約と内部構造には型検査できる例を用意しています。[JSDoc 規約(中国語)](../../.agents/instructions/module-conventions.md#jsdoc-与示例验证) を参照してください。
|
|
38
38
|
|
package/README.md
CHANGED
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 —
|
|
6
|
+
* @h-ai/cache — 配置 Schema
|
|
7
7
|
*
|
|
8
|
-
*
|
|
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
|
-
*
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
423
|
+
/** Redis 等待 timeout 秒后返回 null,传 0 持续等待。返回 [逻辑键, 值];关闭缓存会以失败结束等待。Cluster 多键须同 slot;memory 立即返回。 */
|
|
424
424
|
blpop: <T = CacheValue>(timeout: number, ...keys: string[]) => Promise<HaiResult<[string, T] | null>>;
|
|
425
|
-
/**
|
|
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
|
-
/**
|
|
453
|
+
/** 随机获取成员;省略 count 时返回单个值或 null。指定 count 返回数组,正数不重复,负数允许重复。 */
|
|
454
454
|
srandmember: <T = CacheValue>(key: string, count?: number) => Promise<HaiResult<T | T[] | null>>;
|
|
455
|
-
/**
|
|
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
|
-
*
|
|
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
|
-
*
|
|
532
|
-
* owner
|
|
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
|
|
538
|
+
* @returns 获锁或重入成功返回当前凭据,锁占用或重入被拒绝时返回 null。
|
|
538
539
|
*/
|
|
539
540
|
acquire: (key: string, options?: LockOptions) => Promise<HaiResult<string | null>>;
|
|
540
541
|
/**
|
|
541
542
|
* 释放分布式锁
|
|
542
543
|
*
|
|
543
|
-
*
|
|
544
|
+
* 当前持有者每调用一次释放一个持有层级,最后一层释放后其他调用方才能取得锁。
|
|
544
545
|
*
|
|
545
546
|
* @param key - 锁键名
|
|
546
547
|
* @param owner - 本次 acquire 返回的唯一凭据,不能使用节点 ID
|
|
547
|
-
* @returns true
|
|
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
|
-
/**
|
|
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'
|