@h-ai/cache 1.0.0-beta.2 → 1.0.0-beta.20
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 +202 -35
- package/README.ja.md +233 -68
- package/README.md +234 -69
- package/dist/index.d.ts +2 -1
- package/dist/index.js +258 -89
- package/dist/index.js.map +1 -1
- package/package.json +8 -8
package/README.en.md
CHANGED
|
@@ -4,36 +4,9 @@
|
|
|
4
4
|
|
|
5
5
|
[Framework home](../../README.en.md) · Related modules: [@h-ai/core](../core/README.en.md)
|
|
6
6
|
|
|
7
|
-
## Introduction
|
|
8
|
-
|
|
9
7
|
A unified cache module. The `cache` object provides KV / Hash / List / Set / ZSet / distributed lock operations with Memory and Redis backends.
|
|
10
8
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
Connections become available only after a successful health check. Failed initialization disposes its candidate; `error.ext.cleanupPending === true` identifies cleanup that still needs retry. `cache.close()` returns `Promise<HaiResult<void>>`, waits for initialization, and coalesces concurrent close calls. Once cleanup starts, `isInitialized` is false and configuration/operations are unavailable. A failed cleanup retains the resource: the next `close()` or `init()` retries disposal before allocating a replacement. Always inspect the close result.
|
|
14
|
-
|
|
15
|
-
```ts
|
|
16
|
-
const closed = await cache.close()
|
|
17
|
-
if (!closed.success) {
|
|
18
|
-
// Retry once after addressing the cleanup failure; report another failure.
|
|
19
|
-
const retried = await cache.close()
|
|
20
|
-
if (!retried.success)
|
|
21
|
-
throw new Error(retried.error.message)
|
|
22
|
-
}
|
|
23
|
-
```
|
|
24
|
-
|
|
25
|
-
Redis falls back to disconnect when QUIT fails, and reports success only after releasing the client.
|
|
26
|
-
|
|
27
|
-
## Core features
|
|
28
|
-
|
|
29
|
-
- In-memory caching for development and tests
|
|
30
|
-
- Redis caching in production (standalone, URL, Cluster, Sentinel)
|
|
31
|
-
- Set caches for IAM sessions and permissions
|
|
32
|
-
- Distributed locks for mutual exclusion across nodes
|
|
33
|
-
|
|
34
|
-
## Getting started
|
|
35
|
-
|
|
36
|
-
### Quick start
|
|
9
|
+
## Quick Start
|
|
37
10
|
|
|
38
11
|
```ts
|
|
39
12
|
import { cache } from '@h-ai/cache'
|
|
@@ -61,6 +34,188 @@ finally {
|
|
|
61
34
|
|
|
62
35
|
`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.
|
|
63
36
|
|
|
37
|
+
## Features
|
|
38
|
+
|
|
39
|
+
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.
|
|
40
|
+
|
|
41
|
+
Memory KV, Hash, List, Set, and ZSet share one key namespace. `exists/expire/expireAt/ttl/persist/keys/scan/del/type` cover every structure; structure operations also treat expired keys as absent. del counts logical keys actually removed, and structure operations on another key type fail.
|
|
42
|
+
|
|
43
|
+
Connections become available only after a successful health check. Failed initialization disposes its candidate; `error.ext.cleanupPending === true` identifies cleanup that still needs retry. `cache.close()` returns `Promise<HaiResult<void>>`, waits for initialization, and coalesces concurrent close calls. Once cleanup starts, `isInitialized` is false and configuration/operations are unavailable. A failed cleanup retains the resource: the next `close()` or `init()` retries disposal before allocating a replacement. Always inspect the close result.
|
|
44
|
+
|
|
45
|
+
```ts
|
|
46
|
+
const closed = await cache.close()
|
|
47
|
+
if (!closed.success) {
|
|
48
|
+
// Retry once after addressing the cleanup failure; report another failure.
|
|
49
|
+
const retried = await cache.close()
|
|
50
|
+
if (!retried.success)
|
|
51
|
+
throw new Error(retried.error.message)
|
|
52
|
+
}
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Redis falls back to disconnect when QUIT fails, and reports success only after releasing the client.
|
|
56
|
+
|
|
57
|
+
### Operations and results
|
|
58
|
+
|
|
59
|
+
Use the complete initialization flow in this section first. The host validates and authorizes example business values; check success before reading data from asynchronous domain results. Here void means completion without data, null means absent; synchronous factories/tools return the listed type directly.
|
|
60
|
+
|
|
61
|
+
key/keys identify business keys, field/fields hash fields, value/members JSON values; start/stop/index are indexes, min/max score bounds; seconds/ttl/timeout are seconds, timestamp Unix seconds; owner must come from acquire.
|
|
62
|
+
|
|
63
|
+
#### cache.kv
|
|
64
|
+
|
|
65
|
+
Cache JSON snapshots: get/mget yield values/null in input order; set takes TTL/NX/XX and returns applied boolean; mset takes [key,value][] and yields void.
|
|
66
|
+
|
|
67
|
+
| Entry | Input parameters | Successful result | Call example |
|
|
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
|
+
Versioned cross-node commit: key, expected, value and expiry atomically return applied; undefined means absent/delete, a mismatch preserves data and TTL.
|
|
77
|
+
|
|
78
|
+
| Entry | Input parameters | Successful result | Call example |
|
|
79
|
+
| ------------------------- | ----------------------------- | ----------------- | ------------------------------------------------ |
|
|
80
|
+
| `cache.kv.compareAndSwap` | key, expected, value, options | `boolean` | `await cache.kv.compareAndSwap('version', 1, 2)` |
|
|
81
|
+
|
|
82
|
+
#### cache.kv
|
|
83
|
+
|
|
84
|
+
Manage all structures by key: del/exists take keys and return deleted/existing counts; type takes one key and returns its structure name.
|
|
85
|
+
|
|
86
|
+
| Entry | Input parameters | Successful result | Call example |
|
|
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
|
+
Retention: relative seconds, Unix seconds or key set/read/remove TTL. Changes yield boolean; ttl yields seconds (-1 persistent, -2 absent).
|
|
95
|
+
|
|
96
|
+
| Entry | Input parameters | Successful result | Call example |
|
|
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
|
+
Counters take a key and optional integer delta and return the new safe integer; invalid type/overflow fails without changing data.
|
|
106
|
+
|
|
107
|
+
| Entry | Input parameters | Successful result | Call example |
|
|
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
|
+
Enumeration: keys takes a glob and yields keys; scan takes an opaque cursor and match/count and yields [nextCursor,keys], without snapshot or uniqueness guarantees.
|
|
117
|
+
|
|
118
|
+
| Entry | Input parameters | Successful result | Call example |
|
|
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
|
+
Field cache accepts key plus fields/object/delta. Reads yield value/null, object, field/value arrays or length; hset/hdel count additions/deletions, hexists yields boolean, hincrBy the new integer.
|
|
126
|
+
|
|
127
|
+
| Entry | Input parameters | Successful result | Call example |
|
|
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
|
+
Ordered queues use key, values and index/range: push returns length, pop/index value/null, range an array, set/trim void. Blocking pops take seconds and keys and return [key,value]/null.
|
|
143
|
+
|
|
144
|
+
| Entry | Input parameters | Successful result | Call example |
|
|
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
|
+
Deduplication/set operations: key+members add/remove/test with count/boolean; members returns an array, card a count, random/pop a member/array/null by count, intersections/unions/differences take keys and yield arrays.
|
|
161
|
+
|
|
162
|
+
| Entry | Input parameters | Successful result | Call example |
|
|
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
|
+
Rankings accept members/scores or rank/score ranges; adds/removals yield counts, score/rank number/null, ranges member/scored-object arrays, incrBy the new score, card/count counts.
|
|
178
|
+
|
|
179
|
+
| Entry | Input parameters | Successful result | Call example |
|
|
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
|
+
Short leases: acquire takes key/TTL and yields owner/null; release/extend require owner and yield boolean; isLocked only observes. A lease does not replace resource-side CAS.
|
|
198
|
+
|
|
199
|
+
| Entry | Input parameters | Successful result | Call example |
|
|
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
|
+
Health check with no arguments; returns the backend response string or a connection failure.
|
|
209
|
+
|
|
210
|
+
| Entry | Input parameters | Successful result | Call example |
|
|
211
|
+
| ------------ | ---------------- | ----------------- | -------------------- |
|
|
212
|
+
| `cache.ping` | No arguments | `string` | `await cache.ping()` |
|
|
213
|
+
|
|
214
|
+
- In-memory caching for development and tests
|
|
215
|
+
- Redis caching in production (standalone, URL, Cluster, Sentinel)
|
|
216
|
+
- Set caches for IAM sessions and permissions
|
|
217
|
+
- Distributed locks for mutual exclusion across nodes
|
|
218
|
+
|
|
64
219
|
### Initialization options
|
|
65
220
|
|
|
66
221
|
```ts
|
|
@@ -95,7 +250,9 @@ await cache.init({
|
|
|
95
250
|
await cache.init({
|
|
96
251
|
type: 'redis',
|
|
97
252
|
sentinel: {
|
|
98
|
-
sentinels: [
|
|
253
|
+
sentinels: [
|
|
254
|
+
{ host: 'sentinel1', port: 26379 }
|
|
255
|
+
],
|
|
99
256
|
name: 'mymaster',
|
|
100
257
|
},
|
|
101
258
|
})
|
|
@@ -154,7 +311,21 @@ if (acquired.success && acquired.data)
|
|
|
154
311
|
|
|
155
312
|
The owner token only protects lease renewal and release; it is not a resource fencing token. A paused task can resume after expiry. Final writes require CAS, generation predicates or transactional constraints in the resource store; renewal or returning a failure afterwards cannot prevent a stale commit.
|
|
156
313
|
|
|
157
|
-
###
|
|
314
|
+
### Production shared state
|
|
315
|
+
|
|
316
|
+
Production requires Redis (including Cluster); memory is for development/explicit tests. Redis errors fail rather than falling back locally. Initialization checks apply when NODE_ENV or HAI_CORE_ENV is production; only explicit HAI_E2E=1/HAI_E2E_MOCK=1 tests are exempt. [State, concurrency and recovery (Chinese)](../../.agents/instructions/distributed-state.md).
|
|
317
|
+
|
|
318
|
+
## Configuration
|
|
319
|
+
|
|
320
|
+
Lifecycle: init takes backend/business configuration; use the module only after success. Await close before releasing borrowed dependencies. Follow the quick-start example and public signatures for exact return values.
|
|
321
|
+
|
|
322
|
+
The host loads and validates configuration before passing it to this module. Keep secrets in private server environment files. Select the backend, capacity, deadlines and logging for the actual use case; reinitialize and check the result after changes.
|
|
323
|
+
|
|
324
|
+
[Per-option purpose, use cases and examples](../../docs/usage/configuration/data.md).
|
|
325
|
+
|
|
326
|
+
## Error Handling
|
|
327
|
+
|
|
328
|
+
Check result.success for domain operations. Handle failures with the module error definitions and safe messages; retain codes, correlation IDs and sanitized causes in server logs. Synchronous tools, factories, stream iteration and lifecycle calls follow their own signatures. A completed Promise alone is not business success. See each feature for recovery limits.
|
|
158
329
|
|
|
159
330
|
All operations return `HaiResult<T>`. Common error codes:
|
|
160
331
|
|
|
@@ -170,11 +341,7 @@ All operations return `HaiResult<T>`. Common error codes:
|
|
|
170
341
|
| `HaiCacheError.UNSUPPORTED_TYPE` | `hai:cache:011` | Unsupported cache type |
|
|
171
342
|
| `HaiCacheError.CONFIG_ERROR` | `hai:cache:012` | Invalid configuration |
|
|
172
343
|
|
|
173
|
-
##
|
|
174
|
-
|
|
175
|
-
Production requires Redis (including Cluster); memory is for development/explicit tests. Redis errors fail rather than falling back locally. Initialization checks apply when NODE_ENV or HAI_CORE_ENV is production; only explicit HAI_E2E=1/HAI_E2E_MOCK=1 tests are exempt. [State, concurrency and recovery (Chinese)](../../.agents/instructions/distributed-state.md)。
|
|
176
|
-
|
|
177
|
-
## Development and testing
|
|
344
|
+
## Development
|
|
178
345
|
|
|
179
346
|
```bash
|
|
180
347
|
pnpm --filter @h-ai/cache test
|
package/README.ja.md
CHANGED
|
@@ -4,36 +4,9 @@
|
|
|
4
4
|
|
|
5
5
|
[フレームワークのホーム](../../README.ja.md) · 関連モジュール:[@h-ai/core](../core/README.ja.md)
|
|
6
6
|
|
|
7
|
-
## 概要
|
|
8
|
-
|
|
9
7
|
統一されたキャッシュモジュールです。`cache` オブジェクトで KV / Hash / List / Set / ZSet / 分散ロックを操作し、メモリーと Redis のバックエンドに対応します。
|
|
10
8
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
接続はヘルスチェック成功後に公開します。初期化失敗時は候補リソースを解放し、解放にも失敗した場合は初期化エラーの `error.ext.cleanupPending` が `true` になります。`cache.close()` は `Promise<HaiResult<void>>` を返し、初期化を待機して並行する終了処理をまとめます。解放開始後は `isInitialized` が `false` となり、設定と操作は利用できません。解放に失敗したリソースは保持され、次の `close()` または `init()` で再試行します。解放が成功するまで代替接続は作成しません。終了結果を必ず確認してください。
|
|
14
|
-
|
|
15
|
-
```ts
|
|
16
|
-
const closed = await cache.close()
|
|
17
|
-
if (!closed.success) {
|
|
18
|
-
// 障害への対処後に一度再試行し、再失敗はアプリへ報告します。
|
|
19
|
-
const retried = await cache.close()
|
|
20
|
-
if (!retried.success)
|
|
21
|
-
throw new Error(retried.error.message)
|
|
22
|
-
}
|
|
23
|
-
```
|
|
24
|
-
|
|
25
|
-
Redis の QUIT が失敗した場合は disconnect で切断し、解放が完了した場合のみ成功を返します。
|
|
26
|
-
|
|
27
|
-
## 主な機能
|
|
28
|
-
|
|
29
|
-
- 開発・テスト用のメモリーキャッシュ
|
|
30
|
-
- 本番環境の Redis キャッシュ(単一ノード、URL、Cluster、Sentinel)
|
|
31
|
-
- IAM セッション・権限用の集合キャッシュ
|
|
32
|
-
- 複数ノード間の排他制御に使う分散ロック
|
|
33
|
-
|
|
34
|
-
## 使い始める
|
|
35
|
-
|
|
36
|
-
### クイックスタート
|
|
9
|
+
## クイックスタート
|
|
37
10
|
|
|
38
11
|
```ts
|
|
39
12
|
import { cache } from '@h-ai/cache'
|
|
@@ -61,49 +34,187 @@ finally {
|
|
|
61
34
|
|
|
62
35
|
`cache.config` は**機密情報をマスクした設定スナップショット**を返します。Redis の `password` / `url` などの認証情報は自動処理されるため、元の秘密情報を書き戻す用途には使わないでください。
|
|
63
36
|
|
|
64
|
-
|
|
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` は全構造を対象とし、期限切れ key は構造操作でも直ちに存在しないものとして扱います。del は実際に削除した論理 key を数え、異なる型の構造操作は失敗します。
|
|
42
|
+
|
|
43
|
+
接続はヘルスチェック成功後に公開します。初期化失敗時は候補リソースを解放し、解放にも失敗した場合は初期化エラーの `error.ext.cleanupPending` が `true` になります。`cache.close()` は `Promise<HaiResult<void>>` を返し、初期化を待機して並行する終了処理をまとめます。解放開始後は `isInitialized` が `false` となり、設定と操作は利用できません。解放に失敗したリソースは保持され、次の `close()` または `init()` で再試行します。解放が成功するまで代替接続は作成しません。終了結果を必ず確認してください。
|
|
65
44
|
|
|
66
45
|
```ts
|
|
67
|
-
|
|
68
|
-
|
|
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
|
+
```
|
|
69
54
|
|
|
70
|
-
|
|
71
|
-
await cache.init({
|
|
72
|
-
type: 'redis',
|
|
73
|
-
host: 'localhost',
|
|
74
|
-
port: 6379,
|
|
75
|
-
password: 'secret',
|
|
76
|
-
db: 0,
|
|
77
|
-
})
|
|
55
|
+
Redis の QUIT が失敗した場合は disconnect で切断し、解放が完了した場合のみ成功を返します。
|
|
78
56
|
|
|
79
|
-
|
|
80
|
-
await cache.init({
|
|
81
|
-
type: 'redis',
|
|
82
|
-
url: 'redis://:password@localhost:6379/0',
|
|
83
|
-
})
|
|
57
|
+
### 操作と入出力
|
|
84
58
|
|
|
85
|
-
|
|
86
|
-
await cache.init({
|
|
87
|
-
type: 'redis',
|
|
88
|
-
cluster: [
|
|
89
|
-
{ host: 'node1', port: 6379 },
|
|
90
|
-
{ host: 'node2', port: 6379 },
|
|
91
|
-
],
|
|
92
|
-
})
|
|
59
|
+
本節の完全な初期化手順を先に実行します。例の業務値はホストが検証・認可し、非同期領域結果は success を確認してから data を読みます。void はデータなし完了、null は不存在、同期ファクトリー/ツールは表の型を直接返します。
|
|
93
60
|
|
|
94
|
-
|
|
95
|
-
await cache.init({
|
|
96
|
-
type: 'redis',
|
|
97
|
-
sentinel: {
|
|
98
|
-
sentinels: [{ host: 'sentinel1', port: 26379 }],
|
|
99
|
-
name: 'mymaster',
|
|
100
|
-
},
|
|
101
|
-
})
|
|
102
|
-
```
|
|
61
|
+
key/keys は業務キー、field/fields はハッシュ項目、value/members は JSON 値。start/stop/index は添字、min/max は点数範囲、seconds/ttl/timeout は秒、timestamp は Unix 秒。owner は acquire の戻り値。
|
|
103
62
|
|
|
104
|
-
|
|
63
|
+
#### cache.kv
|
|
105
64
|
|
|
106
|
-
|
|
65
|
+
JSON スナップショットを保存。get/mget は値/null(入力順)、set は TTL/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
|
+
全構造をキー単位で管理。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
|
+
カウンターはキーと整数増分から更新後の安全な整数を返す。型不正・桁あふれは元値を変更せず失敗。
|
|
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
|
+
フィールド保存。キーとフィールド/配列/オブジェクト/増分を入力。読取は値/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
|
+
順序キュー。キー・値・添字/範囲を入力し 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
|
+
重複排除・集合演算。キーと要素の追加/削除/判定は件数/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、Cluster、Sentinel)
|
|
216
|
+
- IAM セッション・権限用の集合キャッシュ
|
|
217
|
+
- 複数ノード間の排他制御に使う分散ロック
|
|
107
218
|
|
|
108
219
|
### API 一覧
|
|
109
220
|
|
|
@@ -154,7 +265,65 @@ if (acquired.success && acquired.data)
|
|
|
154
265
|
|
|
155
266
|
owner はリース延長・解除の所有権であり、リソースの fencing token ではありません。停止した処理は期限切れ後も再開できるため、最終書込には保存先の CAS・世代条件・トランザクション制約が必要です。延長や処理後の失敗返却だけでは旧書込を防げません。
|
|
156
267
|
|
|
157
|
-
###
|
|
268
|
+
### 本番の共有状態
|
|
269
|
+
|
|
270
|
+
本番は Redis(Cluster を含む)が必須です。memory は開発・明示的テスト用であり、Redis 障害時もローカルへフォールバックしません。 NODE_ENV または HAI_CORE_ENV が production の場合、初期化成功前に検証します。明示的な HAI_E2E=1/HAI_E2E_MOCK=1 テストのみ除外します。 [状態・並行制御・復旧範囲(中国語)](../../.agents/instructions/distributed-state.md).
|
|
271
|
+
|
|
272
|
+
## 設定
|
|
273
|
+
|
|
274
|
+
ライフサイクル。init にバックエンド/業務設定を渡し成功後に使用します。借用依存先の解放前に close の完了を待ち、正確な戻り値は例と公開署名に従います。
|
|
275
|
+
|
|
276
|
+
```ts
|
|
277
|
+
// Memory(开发/测试)
|
|
278
|
+
await cache.init({ type: 'memory' })
|
|
279
|
+
|
|
280
|
+
// Redis 单机
|
|
281
|
+
await cache.init({
|
|
282
|
+
type: 'redis',
|
|
283
|
+
host: 'localhost',
|
|
284
|
+
port: 6379,
|
|
285
|
+
password: 'secret',
|
|
286
|
+
db: 0,
|
|
287
|
+
})
|
|
288
|
+
|
|
289
|
+
// Redis URL(优先级最高)
|
|
290
|
+
await cache.init({
|
|
291
|
+
type: 'redis',
|
|
292
|
+
url: 'redis://:password@localhost:6379/0',
|
|
293
|
+
})
|
|
294
|
+
|
|
295
|
+
// Redis 集群
|
|
296
|
+
await cache.init({
|
|
297
|
+
type: 'redis',
|
|
298
|
+
cluster: [
|
|
299
|
+
{ host: 'node1', port: 6379 },
|
|
300
|
+
{ host: 'node2', port: 6379 },
|
|
301
|
+
],
|
|
302
|
+
})
|
|
303
|
+
|
|
304
|
+
// Redis 哨兵
|
|
305
|
+
await cache.init({
|
|
306
|
+
type: 'redis',
|
|
307
|
+
sentinel: {
|
|
308
|
+
sentinels: [
|
|
309
|
+
{ host: 'sentinel1', port: 26379 }
|
|
310
|
+
],
|
|
311
|
+
name: 'mymaster',
|
|
312
|
+
},
|
|
313
|
+
})
|
|
314
|
+
```
|
|
315
|
+
|
|
316
|
+
`cache.init(config)` は組み込み memory/redis を選択します。Provider は内部契約であり、独自バックエンドの登録 API はありません。
|
|
317
|
+
|
|
318
|
+
`password` は単独・Cluster・Sentinel のデータノードに使用され、発見・リダイレクト後の接続にも適用します。`url` 指定時は URL 内の認証情報を使用し、独立した password フィールドでは上書きしません。
|
|
319
|
+
|
|
320
|
+
設定はホストが読込・検証してから渡します。秘密はサーバーの非公開環境に保存し、利用場面に応じてバックエンド・容量・期限・ログを選びます。変更後は再初期化の結果を確認してください。
|
|
321
|
+
|
|
322
|
+
[項目別の用途・適用場面・例](../../docs/usage/configuration/data.md).
|
|
323
|
+
|
|
324
|
+
## エラー処理
|
|
325
|
+
|
|
326
|
+
領域操作は result.success を確認し、失敗時はモジュールのエラー定義と安全な説明を使います。コード・関連 ID・秘匿した原因をサーバーログに残します。同期ツール・ファクトリー・ストリーム反復・ライフサイクルは各署名に従い、Promise 完了だけで成功と判断しません。回復条件は各機能を参照してください。
|
|
158
327
|
|
|
159
328
|
すべての操作は `HaiResult<T>` を返します。主なエラーコード:
|
|
160
329
|
|
|
@@ -170,10 +339,6 @@ owner はリース延長・解除の所有権であり、リソースの fencing
|
|
|
170
339
|
| `HaiCacheError.UNSUPPORTED_TYPE` | `hai:cache:011` | 未対応のキャッシュ種別 |
|
|
171
340
|
| `HaiCacheError.CONFIG_ERROR` | `hai:cache:012` | 設定エラー |
|
|
172
341
|
|
|
173
|
-
## 本番の共有状態
|
|
174
|
-
|
|
175
|
-
本番は Redis(Cluster を含む)が必須です。memory は開発・明示的テスト用であり、Redis 障害時もローカルへフォールバックしません。 NODE_ENV または HAI_CORE_ENV が production の場合、初期化成功前に検証します。明示的な HAI_E2E=1/HAI_E2E_MOCK=1 テストのみ除外します。 [状態・並行制御・復旧範囲(中国語)](../../.agents/instructions/distributed-state.md)。
|
|
176
|
-
|
|
177
342
|
## 開発とテスト
|
|
178
343
|
|
|
179
344
|
```bash
|