@h-ai/cache 0.1.0-alpha.66 → 0.1.0-alpha.67

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.
Files changed (4) hide show
  1. package/README.en.md +11 -7
  2. package/README.ja.md +12 -8
  3. package/README.md +12 -8
  4. package/package.json +2 -2
package/README.en.md CHANGED
@@ -4,18 +4,22 @@
4
4
 
5
5
  [Framework home](../../README.en.md) · Related modules: [@h-ai/core](../core/README.en.md)
6
6
 
7
+ ## Introduction
8
+
7
9
  A unified cache module. The `cache` object provides KV / Hash / List / Set / ZSet / distributed lock operations with Memory and Redis backends.
8
10
 
9
11
  Memory KV entries expire at their expiration time. `incr/decr/incrBy/decrBy` accept only safe integers or integer strings; invalid increments and overflow return `OPERATION_FAILED` without changing the original value. Hash names such as `__proto__` / `constructor` remain ordinary fields and do not change the returned object's prototype.
10
12
 
11
- ## Use cases
13
+ ## Core features
12
14
 
13
15
  - In-memory caching for development and tests
14
16
  - Redis caching in production (standalone, URL, Cluster, Sentinel)
15
17
  - Set caches for IAM sessions and permissions
16
18
  - Distributed locks for mutual exclusion across nodes
17
19
 
18
- ## Quick start
20
+ ## Getting started
21
+
22
+ ### Quick start
19
23
 
20
24
  ```ts
21
25
  import { cache, HaiCacheError } from '@h-ai/cache'
@@ -53,7 +57,7 @@ await cache.close()
53
57
 
54
58
  `cache.config` returns a **redacted configuration snapshot**. Redis credential fields such as `password` / `url` are sanitized automatically; do not use the snapshot to write back original secrets.
55
59
 
56
- ## Initialization options
60
+ ### Initialization options
57
61
 
58
62
  ```ts
59
63
  // Memory（开发/测试）
@@ -93,7 +97,7 @@ await cache.init({
93
97
  })
94
98
  ```
95
99
 
96
- ## API overview
100
+ ### API overview
97
101
 
98
102
  - `cache.kv`: string/object key-value storage and TTL (`set/get/mget/mset/expire/ttl/...`).
99
103
  - `cache.hash`: hash structures (`hset/hget/hgetall/...`).
@@ -103,7 +107,7 @@ await cache.init({
103
107
  - `cache.lock`: distributed locks (`acquire/release/isLocked/extend`).
104
108
  - `CacheProvider`: a public provider contract for advanced integrations and custom backends.
105
109
 
106
- ## Distributed locks
110
+ ### Distributed locks
107
111
 
108
112
  Distributed mutual exclusion based on SET NX EX, suitable for deployments across multiple nodes.
109
113
 
@@ -130,7 +134,7 @@ await cache.lock.extend('my-lock', 60, 'node-1')
130
134
  - **Redis backend**: atomic locking with `SET NX EX`; Lua scripts verify the owner for safe release and renewal.
131
135
  - `owner` prevents accidental release of another owner's lock; a stable node identifier is recommended for multi-node deployments.
132
136
 
133
- ## Error codes
137
+ ### Error codes
134
138
 
135
139
  All operations return `HaiResult<T>`. Common error codes:
136
140
 
@@ -146,7 +150,7 @@ All operations return `HaiResult<T>`. Common error codes:
146
150
  | `HaiCacheError.UNSUPPORTED_TYPE` | `hai:cache:011` | Unsupported cache type |
147
151
  | `HaiCacheError.CONFIG_ERROR` | `hai:cache:012` | Invalid configuration |
148
152
 
149
- ## Tests
153
+ ## Development and testing
150
154
 
151
155
  ```bash
152
156
  pnpm --filter @h-ai/cache test
package/README.ja.md CHANGED
@@ -4,18 +4,22 @@
4
4
 
5
5
  [フレームワークのホーム](../../README.ja.md) · 関連モジュール：[@h-ai/core](../core/README.ja.md)
6
6
 
7
+ ## 概要
8
+
7
9
  統一されたキャッシュモジュールです。`cache` オブジェクトで KV / Hash / List / Set / ZSet / 分散ロックを操作し、メモリーと Redis のバックエンドに対応します。
8
10
 
9
11
  メモリー KV は有効期限に達した時点で無効になります。`incr/decr/incrBy/decrBy` は安全な整数値または整数文字列のみを受け付け、不正な増分やオーバーフローでは元の値を保持して `OPERATION_FAILED` を返します。Hash の `__proto__` / `constructor` などは通常のフィールドとして保持され、戻り値のオブジェクトのプロトタイプを変更しません。
10
12
 
11
- ## 用途
13
+ ## 主な機能
12
14
 
13
15
  - 開発・テスト用のメモリーキャッシュ
14
16
  - 本番環境の Redis キャッシュ（単一ノード、URL、Cluster、Sentinel）
15
17
  - IAM セッション・権限用の集合キャッシュ
16
18
  - 複数ノード間の排他制御に使う分散ロック
17
19
 
18
- ## クイックスタート
20
+ ## 使い始める
21
+
22
+ ### クイックスタート
19
23
 
20
24
  ```ts
21
25
  import { cache, HaiCacheError } from '@h-ai/cache'
@@ -53,7 +57,7 @@ await cache.close()
53
57
 
54
58
  `cache.config` は**機密情報をマスクした設定スナップショット**を返します。Redis の `password` / `url` などの認証情報は自動処理されるため、元の秘密情報を書き戻す用途には使わないでください。
55
59
 
56
- ## 初期化設定
60
+ ### 初期化設定
57
61
 
58
62
  ```ts
59
63
  // Memory（开发/测试）
@@ -93,7 +97,7 @@ await cache.init({
93
97
  })
94
98
  ```
95
99
 
96
- ## API 一覧
100
+ ### API 一覧
97
101
 
98
102
  - `cache.kv`：文字列・オブジェクトのキーと値、および TTL（`set/get/mget/mset/expire/ttl/...`）。
99
103
  - `cache.hash`：Hash 構造（`hset/hget/hgetall/...`）。
@@ -103,7 +107,7 @@ await cache.init({
103
107
  - `cache.lock`：分散ロック（`acquire/release/isLocked/extend`）。
104
108
  - `CacheProvider`：高度な統合や独自バックエンド用の公開 Provider 契約。
105
109
 
106
- ## 分散ロック
110
+ ### 分散ロック
107
111
 
108
112
  SET NX EX を利用する分散排他ロックで、複数ノードのデプロイに適しています。
109
113
 
@@ -130,7 +134,7 @@ await cache.lock.extend('my-lock', 60, 'node-1')
130
134
  - **Redis バックエンド**：`SET NX EX` でアトミックにロックを取得。Lua スクリプトで owner を検証して安全に解除・延長します。
131
135
  - `owner` は他の所有者のロックの誤解除を防ぎます。複数ノードのデプロイでは安定したノード識別子の指定を推奨します。
132
136
 
133
- ## エラーコード
137
+ ### エラーコード
134
138
 
135
139
  すべての操作は `HaiResult<T>` を返します。主なエラーコード：
136
140
 
@@ -146,7 +150,7 @@ await cache.lock.extend('my-lock', 60, 'node-1')
146
150
  | `HaiCacheError.UNSUPPORTED_TYPE` | `hai:cache:011` | 未対応のキャッシュ種別 |
147
151
  | `HaiCacheError.CONFIG_ERROR` | `hai:cache:012` | 設定エラー |
148
152
 
149
- ## テスト
153
+ ## 開発とテスト
150
154
 
151
155
  ```bash
152
156
  pnpm --filter @h-ai/cache test
@@ -154,6 +158,6 @@ pnpm --filter @h-ai/cache test
154
158
 
155
159
  > Redis 関連のテストには Docker が必要です。
156
160
 
157
- ## License
161
+ ## ライセンス
158
162
 
159
163
  Apache-2.0
package/README.md CHANGED
@@ -4,18 +4,22 @@
4
4
 
5
5
  [框架首页](../../README.md) · 相关模块：[@h-ai/core](../core/README.md)
6
6
 
7
+ ## 简介
8
+
7
9
  统一缓存模块，通过 `cache` 对象提供 KV / Hash / List / Set / ZSet / 分布式锁 操作，支持内存与 Redis 两种后端。
8
10
 
9
11
  内存 KV 在到期时间点即视为失效；`incr/decr/incrBy/decrBy` 只接受安全整数数值或整数字符串，非法增量和溢出返回 `OPERATION_FAILED` 并保留原值。Hash 的 `__proto__` / `constructor` 等名称按普通字段保留，不修改返回对象原型。
10
12
 
11
- ## 适用场景
13
+ ## 核心功能清单
12
14
 
13
15
  - 开发/测试场景下的内存缓存
14
16
  - 生产环境 Redis 缓存（单机、URL、集群、哨兵）
15
17
  - IAM 会话与权限相关的集合缓存
16
18
  - 分布式锁（多节点部署互斥控制）
17
19
 
18
- ## 快速开始
20
+ ## 使用入门
21
+
22
+ ### 快速开始
19
23
 
20
24
  ```ts
21
25
  import { cache, HaiCacheError } from '@h-ai/cache'
@@ -53,7 +57,7 @@ await cache.close()
53
57
 
54
58
  `cache.config` 返回的是**脱敏后的配置快照**：如后续接入 Redis `password` / `url` 等凭证字段，会自动做安全处理，不应用作回写原始密钥。
55
59
 
56
- ## 初始化配置
60
+ ### 初始化配置
57
61
 
58
62
  ```ts
59
63
  // Memory（开发/测试）
@@ -93,7 +97,7 @@ await cache.init({
93
97
  })
94
98
  ```
95
99
 
96
- ## API 概览
100
+ ### API 概览
97
101
 
98
102
  - `cache.kv`: 字符串/对象键值与 TTL（`set/get/mget/mset/expire/ttl/...`）
99
103
  - `cache.hash`: 哈希结构（`hset/hget/hgetall/...`）
@@ -103,7 +107,7 @@ await cache.init({
103
107
  - `cache.lock`: 分布式锁（`acquire/release/isLocked/extend`）
104
108
  - `CacheProvider`: 公开的 Provider 契约，供高级集成或自定义后端实现复用
105
109
 
106
- ## 分布式锁
110
+ ### 分布式锁
107
111
 
108
112
  基于 SET NX EX 模式实现的分布式互斥锁，适用于多节点部署场景。
109
113
 
@@ -130,7 +134,7 @@ await cache.lock.extend('my-lock', 60, 'node-1')
130
134
  - **Redis 后端**：使用 `SET NX EX` 原子获锁，Lua 脚本实现 owner 验证的安全释放/续期
131
135
  - `owner` 参数用于防止误释放他人锁，多节点部署时建议设置稳定的节点标识
132
136
 
133
- ## 错误码
137
+ ### 错误码
134
138
 
135
139
  所有操作返回 `HaiResult<T>`，常用错误码如下：
136
140
 
@@ -146,7 +150,7 @@ await cache.lock.extend('my-lock', 60, 'node-1')
146
150
  | `HaiCacheError.UNSUPPORTED_TYPE` | `hai:cache:011` | 不支持的缓存类型 |
147
151
  | `HaiCacheError.CONFIG_ERROR` | `hai:cache:012` | 配置错误 |
148
152
 
149
- ## 测试
153
+ ## 开发测试
150
154
 
151
155
  ```bash
152
156
  pnpm --filter @h-ai/cache test
@@ -154,6 +158,6 @@ pnpm --filter @h-ai/cache test
154
158
 
155
159
  > Redis 相关测试需要 Docker 环境。
156
160
 
157
- ## License
161
+ ## 许可证
158
162
 
159
163
  Apache-2.0
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@h-ai/cache",
3
3
  "type": "module",
4
- "version": "0.1.0-alpha.66",
4
+ "version": "0.1.0-alpha.67",
5
5
  "description": "Hai Framework cache module with memory and Redis backends.",
6
6
  "license": "Apache-2.0",
7
7
  "exports": {
@@ -23,7 +23,7 @@
23
23
  "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
24
24
  },
25
25
  "dependencies": {
26
- "@h-ai/core": "0.1.0-alpha.66",
26
+ "@h-ai/core": "0.1.0-alpha.67",
27
27
  "ioredis": "^6.0.0",
28
28
  "zod": "^4.6.5"
29
29
  },