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

package/dist/index.d.ts

@@ -9,14 +9,35 @@ import { HaiResult } from '@h-ai/core';
  * @module cache-config
  */
 
-/** Redis 集群节点配置 */
+/**
+ * Redis 集群节点配置
+ * @example
+ * ```ts
+ * import { RedisClusterNodeSchema } from '@h-ai/cache'
+ * const config = RedisClusterNodeSchema.parse({ host: 'redis.internal', port: 6379 })
+ * ```
+ */
 declare const RedisClusterNodeSchema: z.ZodObject<{
     host: z.ZodString;
     port: z.ZodNumber;
 }, z.core.$strip>;
-/** Redis 集群节点类型 */
+/**
+ * Redis 集群节点类型
+ * @example
+ * ```ts
+ * import type { RedisClusterNode } from '@h-ai/cache'
+ * const options: RedisClusterNode = { host: 'redis.internal', port: 6379 }
+ * ```
+ */
 type RedisClusterNode = z.infer<typeof RedisClusterNodeSchema>;
-/** Redis 哨兵模式配置 */
+/**
+ * Redis 哨兵模式配置
+ * @example
+ * ```ts
+ * import { RedisSentinelConfigSchema } from '@h-ai/cache'
+ * const config = RedisSentinelConfigSchema.parse({ name: 'primary', sentinels: [{ host: 'sentinel.internal', port: 26379 }] })
+ * ```
+ */
 declare const RedisSentinelConfigSchema: z.ZodObject<{
     sentinels: z.ZodArray<z.ZodObject<{
         host: z.ZodString;
@@ -24,9 +45,23 @@ declare const RedisSentinelConfigSchema: z.ZodObject<{
     }, z.core.$strip>>;
     name: z.ZodString;
 }, z.core.$strip>;
-/** Redis 哨兵模式配置类型 */
+/**
+ * Redis 哨兵模式配置类型
+ * @example
+ * ```ts
+ * import type { RedisSentinelConfig } from '@h-ai/cache'
+ * const options: RedisSentinelConfig = { name: 'primary', sentinels: [{ host: 'sentinel.internal', port: 26379 }] }
+ * ```
+ */
 type RedisSentinelConfig = z.infer<typeof RedisSentinelConfigSchema>;
-/** 内存缓存配置（仅用于开发/测试，不支持跨进程共享） */
+/**
+ * 内存缓存配置（仅用于开发/测试，不支持跨进程共享）
+ * @example
+ * ```ts
+ * import { MemoryConfigSchema } from '@h-ai/cache'
+ * const config = MemoryConfigSchema.parse({ type: 'memory' })
+ * ```
+ */
 declare const MemoryConfigSchema: z.ZodObject<{
     type: z.ZodLiteral<"memory">;
 }, z.core.$strip>;
@@ -34,6 +69,11 @@ declare const MemoryConfigSchema: z.ZodObject<{
  * Redis 缓存配置
  *
  * 连接优先级：url > cluster > sentinel > host
+ * @example
+ * ```ts
+ * import { RedisConfigSchema } from '@h-ai/cache'
+ * const config = RedisConfigSchema.parse({ type: 'redis', host: 'redis.internal' })
+ * ```
  */
 declare const RedisConfigSchema: z.ZodObject<{
     type: z.ZodLiteral<"redis">;
@@ -61,7 +101,14 @@ declare const RedisConfigSchema: z.ZodObject<{
     retryDelay: z.ZodDefault<z.ZodNumber>;
     readOnly: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;
-/** 缓存配置 Schema；通过 type 字段区分 memory / redis */
+/**
+ * 缓存配置 Schema；通过 type 字段区分 memory / redis
+ * @example
+ * ```ts
+ * import { CacheConfigSchema } from '@h-ai/cache'
+ * const config = CacheConfigSchema.parse({ type: 'redis', host: 'redis.internal' })
+ * ```
+ */
 declare const CacheConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"memory">;
 }, z.core.$strip>, z.ZodObject<{
@@ -90,11 +137,35 @@ declare const CacheConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     retryDelay: z.ZodDefault<z.ZodNumber>;
     readOnly: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>], "type">;
-/** 缓存配置类型（Zod parse 后的完整类型，所有默认值已填充） */
+/**
+ * 缓存配置类型（Zod parse 后的完整类型，所有默认值已填充）
+ * @example
+ * ```ts
+ * import { CacheConfigSchema, type CacheConfig } from '@h-ai/cache'
+ * const config: CacheConfig = CacheConfigSchema.parse({ type: 'redis', host: 'redis.internal' })
+ * ```
+ */
 type CacheConfig = z.infer<typeof CacheConfigSchema>;
-/** 缓存配置输入类型（Zod parse 前，允许省略带默认值的字段） */
+/**
+ * 缓存配置输入类型（Zod parse 前，允许省略带默认值的字段）
+ * @example
+ * ```ts
+ * import type { CacheConfigInput } from '@h-ai/cache'
+ * const options: CacheConfigInput = { type: 'redis', host: 'redis.internal', keyPrefix: 'orders:' }
+ * ```
+ */
 type CacheConfigInput = z.input<typeof CacheConfigSchema>;
 
+/**
+ * 缓存连接、序列化、输入与分布式操作的稳定错误定义。
+ * @example
+ * ```ts
+ * import { HaiCacheError } from '@h-ai/cache'
+ * import { err } from '@h-ai/core'
+ * const failure = err(HaiCacheError.INVALID_SET_OPTIONS, 'Conflicting expiry options')
+ * if (!failure.success) failure.error.code
+ * ```
+ */
 declare const HaiCacheError: {
     readonly CONNECTION_FAILED: _h_ai_core.HaiErrorDef;
     readonly OPERATION_FAILED: _h_ai_core.HaiErrorDef;
@@ -105,38 +176,82 @@ declare const HaiCacheError: {
     readonly NOT_INITIALIZED: _h_ai_core.HaiErrorDef;
     readonly UNSUPPORTED_TYPE: _h_ai_core.HaiErrorDef;
     readonly CONFIG_ERROR: _h_ai_core.HaiErrorDef;
+    readonly INVALID_SCAN: _h_ai_core.HaiErrorDef;
+    readonly SCAN_TOPOLOGY_CHANGED: _h_ai_core.HaiErrorDef;
+    readonly CROSS_SLOT: _h_ai_core.HaiErrorDef;
+    readonly INVALID_SET_OPTIONS: _h_ai_core.HaiErrorDef;
 };
 /**
  * 可缓存的值类型
  *
  * 说明：`object` 包含普通对象与数组；函数、Symbol、BigInt 等不建议直接缓存。
+ * @example
+ * ```ts
+ * import type { CacheValue } from '@h-ai/cache'
+ * const options: CacheValue = { id: 'order-1', paid: false }
+ * ```
  */
 type CacheValue = string | number | boolean | object | null;
-/** 缓存设置选项 */
+/**
+ * SET 选项；四种期限彼此互斥且与 keepTtl 互斥，nx/xx 互斥。
+ * @example
+ * ```ts
+ * import type { SetOptions } from '@h-ai/cache'
+ * const options: SetOptions = { px: 60_000, nx: true }
+ * ```
+ */
 interface SetOptions {
-    /** 过期时间（秒） */
+    /** 过期时间（正安全整数秒），零/负数无效。 */
     ex?: number;
-    /** 过期时间（毫秒） */
+    /** 过期时间（正安全整数毫秒），零/负数无效。 */
     px?: number;
-    /** 过期时间点（Unix 时间戳，秒） */
+    /** Unix 正安全整数秒；过去时间会立即过期，乘1000后须仍为安全整数。 */
     exat?: number;
-    /** 过期时间点（Unix 时间戳，毫秒） */
+    /** Unix 正安全整数毫秒；过去时间会立即过期。 */
     pxat?: number;
     /** 仅在键不存在时设置 */
     nx?: boolean;
     /** 仅在键存在时设置 */
     xx?: boolean;
-    /** 保留原有的 TTL（与 ex/px/exat/pxat 互斥，冲突时以后端实现行为为准） */
+    /** 保留原 TTL；新键无 TTL，与所有显式期限互斥。 */
     keepTtl?: boolean;
 }
-/** 扫描选项 */
+/**
+ * 扫描选项
+ * @example
+ * ```ts
+ * import type { ScanOptions } from '@h-ai/cache'
+ * const options: ScanOptions = { match: 'orders:*', count: 100 }
+ * ```
+ */
 interface ScanOptions {
     /** 匹配模式 */
     match?: string;
     /** 每次扫描数量 */
     count?: number;
 }
-/** 有序集合成员（score + member 对） */
+/**
+ * 条件替换的过期策略；px 与 keepTtl 互斥，省略时新值永久保存。
+ * @example
+ * ```ts
+ * import type { CompareAndSwapOptions } from '@h-ai/cache'
+ * const options: CompareAndSwapOptions = { px: 60_000 }
+ * ```
+ */
+interface CompareAndSwapOptions {
+    /** 新值存续的正整数毫秒数。 */
+    px?: number;
+    /** 成功替换时保留已有 TTL；原键不存在时新值无 TTL。 */
+    keepTtl?: boolean;
+}
+/**
+ * 有序集合成员（score + member 对）
+ * @example
+ * ```ts
+ * import type { ZMember } from '@h-ai/cache'
+ * const options: ZMember = { score: 100, member: 'player-1' }
+ * ```
+ */
 interface ZMember {
     /** 分数，用于排序 */
     score: number;
@@ -145,21 +260,56 @@ interface ZMember {
 }
 /**
  * 基础键值操作接口
- *
  * @example
  * ```ts
- * await cache.kv.set('key', { name: '张三' }, { ex: 3600 })
- * const result = await cache.kv.get<{ name: string }>('key')
+ * import type { KvOperations } from '@h-ai/cache'
+ * // 传入已初始化 cache 的对应操作；连接生命周期由创建者管理。
+ * async function example(operations: KvOperations) {
+ *   const claimed = await operations.set('orders:claim', 'worker-1', { nx: true, px: 60_000 })
+ *   if (!claimed.success) return claimed
+ *   if (!claimed.data) return 'already claimed'
+ *   const read = await operations.get<string>('orders:claim')
+ *   return read.success ? read.data : read.error.message
+ * }
  * ```
  */
 interface KvOperations {
     /** 获取值；键不存在时返回 null */
     get: <T = CacheValue>(key: string) => Promise<HaiResult<T | null>>;
-    /** 设置值；可通过 options 控制过期时间、NX/XX 条件等 */
-    set: (key: string, value: CacheValue, options?: SetOptions) => Promise<HaiResult<void>>;
-    /** 删除一个或多个键；返回实际删除的数量 */
+    /**
+     * 设置 JSON 快照，返回实际是否写入；NX/XX 未命中为 success:true/data:false，原值与TTL不变。
+     * 参数非法返回 INVALID_SET_OPTIONS；省略期限永久保存，keepTtl 显式保留原期限。
+     * @example
+     * ```ts
+     * import type { KvOperations } from '@h-ai/cache'
+     * async function reserve(kv: KvOperations) {
+     *   const applied = await kv.set('orders:claim', 'worker-1', { nx: true, px: 1000 })
+     *   return applied.success ? applied.data : applied.error.message
+     * }
+     * ```
+     */
+    set: (key: string, value: CacheValue, options?: SetOptions) => Promise<HaiResult<boolean>>;
+    /**
+     * 对单个 key 原子比较 JSON 序列化值并替换；比较失败返回 false，不修改值/TTL。
+     * expected=undefined 表示键不存在；value=undefined 表示删除，null 是实际 JSON 值。
+     * 适合跨节点状态版本更新，Cluster 只涉及一个 slot；调用方必须检查 success 和 data。
+     * @example
+     * ```ts
+     * import type { KvOperations } from '@h-ai/cache'
+     * async function advance(kv: KvOperations) {
+     *   const read = await kv.get<number>('orders:version')
+     *   if (!read.success) return read
+     *   const expected = read.data ?? undefined
+     *   const changed = await kv.compareAndSwap('orders:version', expected, (expected ?? 0) + 1, { px: 60_000 })
+     *   // data=false 时需要重新读取后再决定是否重试，不能按成功提交处理。
+     *   return changed.success ? changed.data : changed.error.message
+     * }
+     * ```
+     */
+    compareAndSwap: (key: string, expected: CacheValue | undefined, value: CacheValue | undefined, options?: CompareAndSwapOptions) => Promise<HaiResult<boolean>>;
+    /** 删除一个或多个键；返回实际删除的数量。Cluster 跨 slot 按独立键有界执行，失败可能已有部分删除，重试幂等。 */
     del: (...keys: string[]) => Promise<HaiResult<number>>;
-    /** 检查一个或多个键是否存在；返回存在的数量 */
+    /** 检查一个或多个键是否存在；返回存在的数量。Cluster 跨 slot 独立读取，不保证同一时刻快照。 */
     exists: (...keys: string[]) => Promise<HaiResult<number>>;
     /** 设置过期时间（秒） */
     expire: (key: string, seconds: number) => Promise<HaiResult<boolean>>;
@@ -177,12 +327,25 @@ interface KvOperations {
     decr: (key: string) => Promise<HaiResult<number>>;
     /** 自减指定值；键不存在时从 0 开始 */
     decrBy: (key: string, decrement: number) => Promise<HaiResult<number>>;
-    /** 批量获取；不存在的键对应位置返回 null */
+    /** 批量获取；不存在的键对应位置返回 null。Cluster 跨 slot 保留输入顺序，不保证同一时刻快照。 */
     mget: <T = CacheValue>(...keys: string[]) => Promise<HaiResult<(T | null)[]>>;
-    /** 批量设置键值对 */
+    /** 原子批量设置；Cluster 中所有 key 必须同 slot，可使用共同的 {hash-tag}。 */
     mset: (entries: Array<[string, CacheValue]>) => Promise<HaiResult<void>>;
-    /** 游标扫描键；返回 [下一游标, 匹配的键列表]，游标为 0 时表示遍历完成 */
-    scan: (cursor: number, options?: ScanOptions) => Promise<HaiResult<[number, string[]]>>;
+    /**
+     * 游标扫描逻辑 key，首次传 '0'，后续原样传回不透明字符串；'0' 表示完成。
+     * Cluster 遍历全部主节点，拓扑/match/keyPrefix 变化返回 SCAN_TOPOLOGY_CHANGED，须重启遍历。
+     * 与 Redis SCAN 一致，不提供快照，可能返回重复项；调用方按需去重。
+     * @example
+     * ```ts
+     * import type { KvOperations } from '@h-ai/cache'
+     * async function readPage(kv: KvOperations, cursor = '0') {
+     *   const page = await kv.scan(cursor, { match: 'orders:*', count: 100 })
+     *   if (!page.success) return page
+     *   return { next: page.data[0], keys: page.data[1] }
+     * }
+     * ```
+     */
+    scan: (cursor: string, options?: ScanOptions) => Promise<HaiResult<[string, string[]]>>;
     /** 获取匹配模式的所有键（慎用，生产环境请用 scan 迭代） */
     keys: (pattern: string) => Promise<HaiResult<string[]>>;
     /** 获取键的数据类型；不存在时返回 "none" */
@@ -190,11 +353,16 @@ interface KvOperations {
 }
 /**
  * Hash 操作接口
- *
  * @example
  * ```ts
- * await cache.hash.hset('user:1', { name: '张三', age: 25 })
- * const name = await cache.hash.hget<string>('user:1', 'name')
+ * import type { HashOperations } from '@h-ai/cache'
+ * // 传入已初始化 cache 的对应操作；连接生命周期由创建者管理。
+ * async function example(operations: HashOperations) {
+ *   const written = await operations.hset('orders:1', { status: 'pending', version: 1 })
+ *   if (!written.success) return written
+ *   const status = await operations.hget<string>('orders:1', 'status')
+ *   return status.success ? status.data : status.error.message
+ * }
  * ```
  */
 interface HashOperations {
@@ -221,11 +389,16 @@ interface HashOperations {
 }
 /**
  * List 操作接口
- *
  * @example
  * ```ts
- * await cache.list.lpush('queue', 'task1', 'task2')
- * const item = await cache.list.rpop<string>('queue')
+ * import type { ListOperations } from '@h-ai/cache'
+ * // 传入已初始化 cache 的对应操作；连接生命周期由创建者管理。
+ * async function example(operations: ListOperations) {
+ *   const queued = await operations.rpush('orders:queue', 'order-1')
+ *   if (!queued.success) return queued
+ *   const next = await operations.lpop<string>('orders:queue')
+ *   return next.success ? next.data : next.error.message
+ * }
  * ```
  */
 interface ListOperations {
@@ -247,18 +420,23 @@ interface ListOperations {
     lset: (key: string, index: number, value: CacheValue) => Promise<HaiResult<void>>;
     /** 保留指定范围的元素，范围外的元素被删除 */
     ltrim: (key: string, start: number, stop: number) => Promise<HaiResult<void>>;
-    /** 阻塞式从左侧弹出；返回 [key, value] 或超时返回 null。memory 实现为非阻塞立即返回。 */
+    /** 阻塞式从左侧弹出；返回 [key, value] 或超时返回 null。Cluster 多键须同 slot；memory 非阻塞立即返回。 */
     blpop: <T = CacheValue>(timeout: number, ...keys: string[]) => Promise<HaiResult<[string, T] | null>>;
-    /** 阻塞式从右侧弹出；返回 [key, value] 或超时返回 null。memory 实现为非阻塞立即返回。 */
+    /** 阻塞式从右侧弹出；返回 [key, value] 或超时返回 null。Cluster 多键须同 slot；memory 非阻塞立即返回。 */
     brpop: <T = CacheValue>(timeout: number, ...keys: string[]) => Promise<HaiResult<[string, T] | null>>;
 }
 /**
  * Set 操作接口
- *
  * @example
  * ```ts
- * await cache.set_.sadd('tags', 'redis', 'cache')
- * const members = await cache.set_.smembers<string>('tags')
+ * import type { SetOperations } from '@h-ai/cache'
+ * // 传入已初始化 cache 的对应操作；连接生命周期由创建者管理。
+ * async function example(operations: SetOperations) {
+ *   const added = await operations.sadd('orders:tags', 'paid', 'priority')
+ *   if (!added.success) return added
+ *   const members = await operations.smembers<string>('orders:tags')
+ *   return members.success ? members.data : members.error.message
+ * }
  * ```
  */
 interface SetOperations {
@@ -276,20 +454,25 @@ interface SetOperations {
     srandmember: <T = CacheValue>(key: string, count?: number) => Promise<HaiResult<T | T[] | null>>;
     /** 随机弹出成员（会从集合中移除）；不指定 count 返回单个值，指定 count 返回数组；空集合返回 null */
     spop: <T = CacheValue>(key: string, count?: number) => Promise<HaiResult<T | T[] | null>>;
-    /** 集合交集；任一 key 不存在时返回空数组 */
+    /** 集合交集；任一 key 不存在时返回空数组。Cluster 多键须同 slot，否则返回 CROSS_SLOT。 */
     sinter: <T = CacheValue>(...keys: string[]) => Promise<HaiResult<T[]>>;
-    /** 集合并集 */
+    /** 集合并集；Cluster 多键须同 slot，否则返回 CROSS_SLOT。 */
     sunion: <T = CacheValue>(...keys: string[]) => Promise<HaiResult<T[]>>;
-    /** 集合差集（第一个集合减去其余集合） */
+    /** 集合差集（第一个集合减去其余集合）；Cluster 多键须同 slot，否则返回 CROSS_SLOT。 */
     sdiff: <T = CacheValue>(...keys: string[]) => Promise<HaiResult<T[]>>;
 }
 /**
  * 有序集合操作接口
- *
  * @example
  * ```ts
- * await cache.zset.zadd('rank', { score: 100, member: 'player1' })
- * const top = await cache.zset.zrevrange('rank', 0, 9, true)
+ * import type { ZSetOperations } from '@h-ai/cache'
+ * // 传入已初始化 cache 的对应操作；连接生命周期由创建者管理。
+ * async function example(operations: ZSetOperations) {
+ *   const added = await operations.zadd('orders:rank', { member: 'order-1', score: 100 })
+ *   if (!added.success) return added
+ *   const top = await operations.zrevrange('orders:rank', 0, 9, true)
+ *   return top.success ? top.data : top.error.message
+ * }
  * ```
  */
 interface ZSetOperations {
@@ -328,16 +511,16 @@ interface ZSetOperations {
  * 分布式锁操作接口
  *
  * 基于 SET NX EX 模式实现分布式互斥锁，适用于多节点部署场景。
- *
  * @example
  * ```ts
- * const acquired = await cache.lock.acquire('my-lock', { ttl: 30 })
- * if (acquired.success && acquired.data) {
- *   try {
- *     // 执行受保护操作
- *   } finally {
- *     await cache.lock.release('my-lock')
- *   }
+ * import type { LockOperations } from '@h-ai/cache'
+ * // 传入已初始化 cache 的对应操作；连接生命周期由创建者管理。
+ * async function example(operations: LockOperations) {
+ *   const acquired = await operations.acquire('orders:lock', { ttl: 30 })
+ *   if (!acquired.success || !acquired.data) return acquired
+ *   const released = await operations.release('orders:lock', acquired.data)
+ *   // owner 不是 fencing token；业务最终写入仍需自己的数据库/CAS条件。
+ *   return released.success ? released.data : released.error.message
  * }
  * ```
  */
@@ -345,23 +528,25 @@ interface LockOperations {
     /**
      * 尝试获取分布式锁
      *
-     * 通过 SET NX EX 原子操作实现。获锁成功返回 true，锁已被持有返回 false。
+     * 通过 SET NX EX 原子操作实现。每次生成不可复用的所有权凭据；占用时返回 null。
+     * owner 仅用于租约续期/释放，不是资源的 fencing token；暂停/超时后旧操作仍可能继续。
+     * 最终资源写入必须自行使用 CAS/代际条件或数据库事务约束，不能只检查续期或返回失败。
      *
      * @param key - 锁键名
      * @param options - 锁选项
-     * @returns true 表示获锁成功，false 表示锁已被其他持有者持有
+     * @returns 获锁成功返回唯一凭据，锁占用时返回 null
      */
-    acquire: (key: string, options?: LockOptions) => Promise<HaiResult<boolean>>;
+    acquire: (key: string, options?: LockOptions) => Promise<HaiResult<string | null>>;
     /**
      * 释放分布式锁
      *
      * 仅当锁由当前持有者持有时才释放（通过 owner 比对），防止误释放他人的锁。
      *
      * @param key - 锁键名
-     * @param owner - 锁持有者标识（须与 acquire 时一致）；未传则强制释放
+     * @param owner - 本次 acquire 返回的唯一凭据，不能使用节点 ID
      * @returns true 表示释放成功，false 表示锁不存在或非当前持有者
      */
-    release: (key: string, owner?: string) => Promise<HaiResult<boolean>>;
+    release: (key: string, owner: string) => Promise<HaiResult<boolean>>;
     /**
      * 检查锁是否被持有
      *
@@ -376,22 +561,38 @@ interface LockOperations {
      *
      * @param key - 锁键名
      * @param ttl - 新的过期时间（秒）
-     * @param owner - 锁持有者标识；未传则直接续期
+     * @param owner - 本次 acquire 返回的唯一凭据
      * @returns true 表示续期成功，false 表示锁不存在或非当前持有者
      */
-    extend: (key: string, ttl: number, owner?: string) => Promise<HaiResult<boolean>>;
+    extend: (key: string, ttl: number, owner: string) => Promise<HaiResult<boolean>>;
 }
-/** 分布式锁选项 */
+/**
+ * 分布式锁选项
+ * @example
+ * ```ts
+ * import type { LockOptions } from '@h-ai/cache'
+ * const options: LockOptions = { ttl: 30 }
+ * ```
+ */
 interface LockOptions {
     /** 锁过期时间（秒）；默认 30 */
     ttl?: number;
-    /** 锁持有者标识；默认 'default'（多节点部署时建议设置固定值以便审计） */
-    owner?: string;
 }
 /**
  * 复合缓存操作接口，聚合所有数据结构的操作子接口
  *
  * 通过 `cache.kv` / `cache.hash` / `cache.list` / `cache.set_` / `cache.zset` / `cache.lock` 分别访问
+ * @example
+ * ```ts
+ * import type { CacheCompositeOperations } from '@h-ai/cache'
+ * // 传入已初始化 cache 的对应操作；连接生命周期由创建者管理。
+ * async function example(operations: CacheCompositeOperations) {
+ *   const health = await operations.ping()
+ *   if (!health.success) return health
+ *   const result = await operations.kv.get<string>('orders:1')
+ *   return result.success ? result.data : result.error.message
+ * }
+ * ```
  */
 interface CacheCompositeOperations {
     /** KV 操作 */
@@ -411,15 +612,16 @@ interface CacheCompositeOperations {
 }
 /**
  * 缓存函数接口
- *
  * @example
  * ```ts
- * import { cache } from '@h-ai/cache'
- *
- * await cache.init({ type: 'redis', host: 'localhost' })
- * await cache.kv.set('key', 'value', { ex: 3600 })
- * const result = await cache.kv.get('key')
- * await cache.close()
+ * import type { CacheFunctions } from '@h-ai/cache'
+ * // 传入已初始化 cache 的对应操作；连接生命周期由创建者管理。
+ * async function example(operations: CacheFunctions) {
+ *   const initialized = await operations.init({ type: 'redis', host: 'localhost' })
+ *   if (!initialized.success) return initialized
+ *   try { return await operations.kv.get<string>('orders:1') }
+ *   finally { const closed = await operations.close(); if (!closed.success) return closed }
+ * }
  * ```
  */
 interface CacheFunctions extends CacheCompositeOperations {
@@ -429,23 +631,14 @@ interface CacheFunctions extends CacheCompositeOperations {
     readonly config: CacheConfig | null;
     /** 是否已初始化并连接 */
     readonly isInitialized: boolean;
-    /** 关闭连接并清理资源；未初始化时调用安全无副作用 */
-    close: () => Promise<void>;
-}
-/**
- * 缓存 Provider 接口
- *
- * 由具体实现（memory / redis）提供；上层通过 cache-main 统一管理生命周期。
- */
-interface CacheProvider extends CacheCompositeOperations {
-    /** Provider 名称（如 'memory' / 'redis'） */
-    readonly name: string;
-    /** 连接缓存服务；config 已经过 Zod Schema 校验 */
-    connect: (config: CacheConfig) => Promise<HaiResult<void>>;
-    /** 关闭连接并释放资源 */
-    close: () => Promise<void>;
-    /** 是否处于已连接状态 */
-    isConnected: () => boolean;
+    /**
+     * 关闭连接并清理资源；失败时停止提供业务操作并保留资源，可再次 close/init 重试。
+     * @returns 资源全部释放时成功；释放失败时返回 CONNECTION_FAILED。
+     * @example
+     * const result = await cache.close()
+     * if (!result.success) await cache.close()
+     */
+    close: () => Promise<HaiResult<void>>;
 }
 
 /**
@@ -457,17 +650,22 @@ interface CacheProvider extends CacheCompositeOperations {
 
 /**
  * 缓存服务对象
- *
  * @example
  * ```ts
  * import { cache } from '@h-ai/cache'
- *
- * await cache.init({ type: 'redis', host: 'localhost', port: 6379 })
- * await cache.kv.set('user:1', { name: '张三' }, { ex: 3600 })
- * const result = await cache.kv.get<{ name: string }>('user:1')
- * await cache.close()
+ * import { core } from '@h-ai/core'
+ * const initialized = await cache.init({ type: 'redis', host: 'localhost' })
+ * if (initialized.success) {
+ *   try {
+ *     const claimed = await cache.kv.set('orders:claim', 'worker-1', { nx: true, px: 60_000 })
+ *     if (claimed.success && claimed.data) core.logger.info('Claim created')
+ *   } finally {
+ *     const closed = await cache.close()
+ *     if (!closed.success) core.logger.error('Cache cleanup pending', { code: closed.error.code })
+ *   }
+ * }
  * ```
  */
 declare const cache: CacheFunctions;
 
-export { type CacheCompositeOperations, type CacheConfig, type CacheConfigInput, CacheConfigSchema, type CacheFunctions, type CacheProvider, type CacheValue, HaiCacheError, type HashOperations, type KvOperations, type ListOperations, type LockOperations, type LockOptions, MemoryConfigSchema, type RedisClusterNode, RedisClusterNodeSchema, RedisConfigSchema, type RedisSentinelConfig, RedisSentinelConfigSchema, type ScanOptions, type SetOperations, type SetOptions, type ZMember, type ZSetOperations, cache };
+export { type CacheCompositeOperations, type CacheConfig, type CacheConfigInput, CacheConfigSchema, type CacheFunctions, type CacheValue, type CompareAndSwapOptions, HaiCacheError, type HashOperations, type KvOperations, type ListOperations, type LockOperations, type LockOptions, MemoryConfigSchema, type RedisClusterNode, RedisClusterNodeSchema, RedisConfigSchema, type RedisSentinelConfig, RedisSentinelConfigSchema, type ScanOptions, type SetOperations, type SetOptions, type ZMember, type ZSetOperations, cache };