@hile/cache 1.0.1

package/README.md

@@ -0,0 +1,186 @@
+# @hile/cache
+
+基于 Redis 的类型安全读穿透缓存层，构建在 `@hile/core`（DI 容器）与 `@hile/ioredis`（Redis 客户端）之上。
+
+## 安装
+
+```bash
+pnpm add @hile/cache
+```
+
+依赖：`@hile/core`、`@hile/ioredis`。
+
+## 快速开始
+
+### 1. 定义缓存
+
+使用 `defineCache` 定义一条缓存：指定 key 模板和回源函数。
+
+```typescript
+import { defineCache, Cache } from '@hile/cache';
+
+const userCache = defineCache('user:{id:string}:info', async (params) => {
+  // params 的类型自动推导为 { id: string }
+  const data = await fetchUserFromDB(params.id);
+  return new Cache(data).setExpire(300); // 5 分钟 TTL
+});
+```
+
+### 2. 使用缓存
+
+```typescript
+import { RedisCache } from '@hile/cache';
+
+const cache = new RedisCache('myapp:'); // 统一前缀
+
+const { read, write, remove, has } = await cache.loadCache(userCache);
+
+// 读穿透：miss 时自动回源并写入
+const user = await read({ id: 'u-001' });
+
+// 强制刷新
+await write({ id: 'u-001' });
+
+// 判断是否存在
+const exists = await has({ id: 'u-001' });
+
+// 删除
+await remove({ id: 'u-001' });
+```
+
+---
+
+## 核心概念
+
+### 类型安全 key 模板
+
+key 模板使用 `{name:type}` 占位符，编译期自动推导参数类型：
+
+```typescript
+defineCache('user:{id:string}:posts:{page:number}:{verified:boolean}', ...)
+// params → { id: string; page: number; verified: boolean }
+```
+
+支持的类型：`string`、`number`、`boolean`。
+
+### Cache 类
+
+`Cache<R>` 包装回源数据，提供 TTL 控制：
+
+| 方法 | 说明 |
+|------|------|
+| `new Cache(data)` | 创建缓存数据，expire=0 永不过期 |
+| `.setExpire(seconds)` | 设置 TTL（秒） |
+
+### 读穿透（Read-Through）
+
+`RedisCache._read` 的调用链路：
+
+```
+read(params)
+  → EXISTS key
+    ├─ true  → GET key → JSON.parse → 返回
+    └─ false → write(params) → handler 回源 → SET/SETEX → 返回
+```
+
+---
+
+## API 参考
+
+### defineCache
+
+```typescript
+function defineCache<T extends string = string, R = any>(
+  key: T,
+  fn: (params: ExtractParams<T>) => Promise<Cache<R>>
+): DefineCacheResult<T, R>;
+```
+
+### RedisCache
+
+```typescript
+class RedisCache {
+  constructor(prefix: string);
+
+  loadCache<T extends string, R>(
+    target: DefineCacheResult<T, R>
+  ): Promise<{
+    write(params: ExtractParams<T>): Promise<R | undefined>;
+    read(params: ExtractParams<T>): Promise<R | undefined>;
+    remove(params: ExtractParams<T>): Promise<number>;
+    has(params: ExtractParams<T>): Promise<boolean>;
+  }>;
+}
+```
+
+| 方法 | 返回值 | 说明 |
+|------|--------|------|
+| `read` | `R \| undefined` | 读穿透：EXISTS → GET / miss 则回源写入 |
+| `write` | `R \| undefined` | 强制执行回源并写入 Redis（data=undefined 则删除 key） |
+| `remove` | `number` | 删除缓存，返回 0/1 |
+| `has` | `boolean` | 检查 key 是否存在 |
+
+### Redis 中的 key 结构
+
+```
+{prefix}{key模板渲染结果}
+```
+
+例如 `prefix = "myapp:"`、key 模板为 `user:{id:string}:info`、params 为 `{ id: "u-001" }` 时：
+```
+myapp:user:u-001:info
+```
+
+---
+
+## 与 @hile/cli 集成
+
+可在 `package.json` 中配置自动加载 Redis：
+
+```json
+{
+  "hile": {
+    "auto_load_packages": ["@hile/ioredis"]
+  }
+}
+```
+
+然后任何地方通过 `loadService(ioredisService)` 获取 Redis 客户端，`@hile/cache` 内部已自动处理。
+
+---
+
+## 完整示例
+
+```typescript
+import { defineCache, Cache, RedisCache } from '@hile/cache';
+
+// 定义多条缓存
+const userCache = defineCache('user:{id:string}:info', async ({ id }) => {
+  const user = await db.query('SELECT * FROM users WHERE id = $1', [id]);
+  if (!user) return new Cache(undefined); // 不写入 Redis
+  return new Cache(user).setExpire(600);
+});
+
+const postCache = defineCache('post:{id:string}:detail', async ({ id }) => {
+  const post = await db.query('SELECT * FROM posts WHERE id = $1', [id]);
+  return new Cache(post).setExpire(3600);
+});
+
+const cache = new RedisCache('myapp:');
+
+// 批量加载
+const [userOps, postOps] = await Promise.all([
+  cache.loadCache(userCache),
+  cache.loadCache(postCache),
+]);
+
+// 使用
+const user = await userOps.read({ id: 'u-001' });
+const post = await postOps.read({ id: 'p-001' });
+```
+
+---
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,273 @@
+---
+name: cache
+description: Code generation and contribution rules for @hile/cache. Use when editing this package or when the user asks about @hile/cache API, types, patterns, or features.
+---
+
+# @hile/cache — AI Skill Reference
+
+本文档面向 **AI 编码模型**。在生成或修改 `@hile/cache` 代码前必读，保证与现有架构、API 约定、测试模式一致。
+
+---
+
+## 1. 架构总览
+
+### 依赖链
+
+```
+@hile/core (DI 容器)
+  └── @hile/ioredis (Redis 服务: 环境变量配置 + 单例 + 自动断连)
+        └── @hile/cache
+              ├── define.ts — 类型安全 key 模板 + Cache 数据包装 + defineCache
+              └── index.ts  — RedisCache 类: _read / _write / _remove / _has
+```
+
+### 分层职责
+
+| 模块 | 文件 | 职责 | 关键约束 |
+|------|------|------|---------|
+| `defineCache` | `define.ts` | 定义缓存 key 模板 + 回源 handler | 模板中 `{name:type}` 占位符；type 只支持 `string`/`number`/`boolean` |
+| `Cache<R>` | `define.ts` | 包装回源数据，携带 TTL | `expire: 0` 表示永不过期 |
+| `RedisCache` | `index.ts` | Redis 读写操作，读穿透/回源写入/删除/存在判断 | 每次操作通过 `loadService(ioredisService)` 获取客户端 |
+
+### 流程
+
+```
+read(params):
+  → EXISTS key
+    ├─ false → write(params): handler(params) → SET/SETEX → 返回
+    └─ true  → GET key → JSON.parse → 返回
+
+write(params):
+  → handler(params) → Cache<R>
+  ├─ cache.data === undefined → DEL key (若存在) → return
+  └─ cache.data !== undefined →
+       ├─ cache.expire > 0 → SETEX(key, expire, JSON.stringify(data))
+       └─ cache.expire === 0 → SET(key, JSON.stringify(data))
+
+remove(params):
+  → EXISTS key → DEL key → 返回删除数量
+
+has(params):
+  → EXISTS key → 返回 boolean
+```
+
+---
+
+## 2. 类型定义（代码生成时必须一致）
+
+### define.ts
+
+```typescript
+export class Cache<R> {
+  private _expire: number = 0; // 0: 永不过期
+  constructor(public readonly data: R) { }
+  public setExpire(seconds: number): this;
+  get expire(): number;
+}
+
+/** 字面量路径解析 `{k:type}`；`T` 为宽 `string` 时退化为宽松索引类型 */
+export type ExtractParams<Template extends string> =
+  string extends Template
+  ? Record<string, string | number | boolean>
+  : Template extends `${string}{${infer Key}:${infer Type}}${infer Rest}`
+  ? {
+    [K in Key]: Type extends "string"
+    ? string
+    : Type extends "number"
+    ? number
+    : Type extends "boolean"
+    ? boolean
+    : never
+  } & ExtractParams<Rest>
+  : {};
+
+export type DefineCacheHandler<T extends string = string, R = any> =
+  (opts: ExtractParams<T>) => Promise<Cache<R>>;
+
+export type DefineCacheResult<T extends string = string, R = any> = {
+  fn: DefineCacheHandler<T, R>;
+  key: string;
+};
+
+export function defineCache<T extends string = string, R = any>(
+  key: T,
+  fn: DefineCacheHandler<T, R>
+): DefineCacheResult<T, R>;
+```
+
+### index.ts
+
+```typescript
+export class RedisCache {
+  private readonly _regexp = /\{([^\:]+):[^\}]+\}/g;
+  constructor(private readonly prefix: string) { }
+
+  public loadCache<T extends string, R>(
+    target: DefineCacheResult<T, R>
+  ): Promise<{
+    write(params: ExtractParams<T>): Promise<R | undefined>;
+    read(params: ExtractParams<T>): Promise<R | undefined>;
+    remove(params: ExtractParams<T>): Promise<number>;
+    has(params: ExtractParams<T>): Promise<boolean>;
+  }>;
+}
+
+export { defineCache, Cache, ExtractParams, DefineCacheHandler, DefineCacheResult } from './define';
+```
+
+---
+
+## 3. 代码生成模板与规则
+
+### 3.1 defineCache 模板
+
+```typescript
+// 基本模板
+const myCache = defineCache('prefix:{id:string}:suffix', async (params) => {
+  const data = await fetchData(params.id);
+  if (!data) return new Cache(undefined); // 返回 undefined → Redis 中不存/删除
+  return new Cache(data).setExpire(300);  // 5 分钟 TTL
+});
+
+// 多参数模板
+const myCache = defineCache(
+  'user:{id:string}:posts:{page:number}:{verified:boolean}',
+  async ({ id, page, verified }) => {
+    // params 类型自动推导为 { id: string; page: number; verified: boolean }
+    const data = await db.query('SELECT * FROM posts WHERE ...');
+    return new Cache(data).setExpire(60);
+  }
+);
+```
+
+### 3.2 RedisCache 使用模板
+
+```typescript
+// 单条缓存
+const cache = new RedisCache('myapp:');
+const { read, write, remove, has } = await cache.loadCache(myCache);
+
+// 多条缓存
+const [ops1, ops2] = await Promise.all([
+  cache.loadCache(cache1),
+  cache.loadCache(cache2),
+]);
+```
+
+### 3.3 测试模板
+
+```typescript
+import { RedisCache, defineCache, Cache } from '@hile/cache';
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+
+// Mock Redis 的测试需要配合 @hile/ioredis 的 mock 或真实 Redis 实例
+// 以下为使用真实 Redis 的集成测试模板:
+describe('@hile/cache', () => {
+  const cache = new RedisCache('test:');
+
+  const testCache = defineCache('key:{id:string}', async ({ id }) => {
+    return new Cache({ id, value: `hello-${id}` }).setExpire(60);
+  });
+
+  it('read returns data on cache hit', async () => {
+    const { write, read, remove } = await cache.loadCache(testCache);
+
+    // 先写入
+    const written = await write({ id: '1' });
+    expect(written).toEqual({ id: '1', value: 'hello-1' });
+
+    // 读取
+    const result = await read({ id: '1' });
+    expect(result).toEqual({ id: '1', value: 'hello-1' });
+
+    await remove({ id: '1' });
+  });
+
+  it('write with undefined data deletes existing key', async () => {
+    const undefCache = defineCache('undef:{id:string}', async ({ id }) => {
+      return new Cache(undefined);
+    });
+    const { write, has } = await cache.loadCache(undefCache);
+    await write({ id: '1' });
+    const exists = await has({ id: '1' });
+    expect(exists).toBe(false);
+  });
+
+  it('remove returns 0 for non-existent key', async () => {
+    const { remove } = await cache.loadCache(testCache);
+    const count = await remove({ id: 'nonexistent' });
+    expect(count).toBe(0);
+  });
+
+  it('has returns correct boolean', async () => {
+    const { write, has, remove } = await cache.loadCache(testCache);
+    await write({ id: '1' });
+    expect(await has({ id: '1' })).toBe(true);
+    await remove({ id: '1' });
+    expect(await has({ id: '1' })).toBe(false);
+  });
+});
+```
+
+---
+
+## 4. Redis key 规则
+
+### key 渲染
+
+`makeKey` 使用正则 `/\{([^\:]+):[^\}]+\}/g` 匹配模板占位符并替换为实际参数值：
+
+```
+template: "user:{id:string}:posts:{page:number}"
+params:   { id: "u-001", page: 3 }
+result:   "user:u-001:posts:3"
+```
+
+### 真实 Redis key
+
+```
+{prefix}{渲染后的 key}
+```
+
+例如 `prefix = "myapp:"` + 上例 → `myapp:user:u-001:posts:3`
+
+---
+
+## 5. 设计约束（必须遵守）
+
+1. **每次操作都通过 `loadService(ioredisService)` 获取 Redis 客户端** — 不要缓存 `redis` 引用，由容器的并发合并和单例保证性能
+2. **`_write` 中的 EXISTS 检查是为了处理 `data === undefined` 的 DELETE 场景** — 正常写入（`data !== undefined`）可考虑不必先 EXISTS（SET 是幂等的），但目前实现统一检查
+3. **`_read` 的兜底逻辑 `if (!text) return this._write(...)`** — 防御 EXISTS 和 GET 之间的竞态删除，不可移除
+4. **序列化统一使用 `JSON.stringify` / `JSON.parse`** — 不支持 Buffer、BigInt 等特殊类型
+5. **Cache 的 `data` 为 `undefined` 时** — `_write` 会删除 Redis 中对应的 key（如果存在），且 `_write` 返回 `undefined`
+
+---
+
+## 6. 反模式（禁止）
+
+1. **不要绕过 `loadService(ioredisService)` 直接创建 Redis 连接** — 会破坏容器的单例管理和 shutdown 清理
+2. **不要假设 key 模板中参数顺序与渲染结果相同** — `makeKey` 使用正则替换，占位符可以出现在 key 的任何位置
+3. **不要在 `Cache` 构造后将数据存到 `Cache` 外部** — `Cache` 的 `data` 是 `public readonly`，但仅供读取；数据变更应创建新的 `Cache`
+4. **不要手动拼接 Redis key 字符串** — 必须使用 `defineCache` 的模板 + `makeKey` 渲染，保证一致性
+5. **不要在 loadCache 之外直接调用 `_read`/`_write`/`_remove`/`_has`** — 这些方法以 `_` 开头表示内部实现，外部统一通过 `loadCache` 返回的操作对象调用
+
+---
+
+## 7. 文件改动范围
+
+| 文件 | 可修改 | 说明 |
+|------|--------|------|
+| `packages/cache/src/index.ts` | ✅ | 核心 cache 操作 |
+| `packages/cache/src/define.ts` | ⚠️ | 类型定义（修改需同步更新 ExtractParams 类型推导） |
+| `packages/cache/src/index.test.ts` | ✅ | 测试 |
+| `packages/cache/README.md` | ✅ | 用户文档 |
+| `packages/cache/SKILL.md` | ✅ | AI 参考文档 |
+
+---
+
+## 8. 运行命令
+
+```bash
+pnpm --filter @hile/cache build    # 编译，必须通过
+pnpm --filter @hile/cache test     # 测试，修改行为时必须覆盖
+```

package/dist/define.d.ts

@@ -0,0 +1,17 @@
+export declare class Cache<R> {
+    readonly data: R;
+    private _expire;
+    constructor(data: R);
+    setExpire(seconds: number): this;
+    get expire(): number;
+}
+/** 字面量路径解析 `{k:type}`；`T` 为宽 `string` 时 `params` 退化为宽松索引类型。 */
+export type ExtractParams<Template extends string> = string extends Template ? Record<string, string | number | boolean> : Template extends `${string}{${infer Key}:${infer Type}}${infer Rest}` ? {
+    [K in Key]: Type extends "string" ? string : Type extends "number" ? number : Type extends "boolean" ? boolean : never;
+} & ExtractParams<Rest> : {};
+export type DefineCacheHandler<T extends string = string, R = any> = (opts: ExtractParams<T>) => Promise<Cache<R>>;
+export type DefineCacheResult<T extends string = string, R = any> = {
+    fn: DefineCacheHandler<T, R>;
+    key: string;
+};
+export declare function defineCache<T extends string = string, R = any>(key: T, fn: DefineCacheHandler<T, R>): DefineCacheResult<T, R>;

package/dist/define.js

@@ -0,0 +1,27 @@
+export class Cache {
+    data;
+    _expire = 0; // 0: 永不过期
+    constructor(data) {
+        this.data = data;
+    }
+    setExpire(seconds) {
+        this._expire = seconds;
+        return this;
+    }
+    get expire() {
+        return this._expire;
+    }
+}
+export function defineCache(key, fn) {
+    return {
+        fn,
+        key,
+    };
+}
+// defineCache('user:{id:string}:ddd:{x:number}:idsaf:{y:boolean}', async (params) => {
+//   return new Cache({
+//     id: params.id,
+//     x: params.x,
+//     y: params.y,
+//   }).setExpire(60);
+// });

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+import { DefineCacheResult, ExtractParams } from './define.js';
+export * from './define.js';
+export declare class RedisCache {
+    private readonly prefix;
+    private readonly _regexp;
+    constructor(prefix: string);
+    private makeKey;
+    private _write;
+    private _read;
+    private _remove;
+    private _has;
+    loadCache<T extends string, R>(target: DefineCacheResult<T, R>): Promise<{
+        write: (params: ExtractParams<T>) => Promise<R | undefined>;
+        read: (params: ExtractParams<T>) => Promise<R | undefined>;
+        remove: (params: ExtractParams<T>) => Promise<number>;
+        has: (params: ExtractParams<T>) => Promise<boolean>;
+    }>;
+}

package/dist/index.js

@@ -0,0 +1,78 @@
+import { loadService } from "@hile/core";
+import ioredisService from "@hile/ioredis";
+import { Cache } from './define.js';
+export * from './define.js';
+export class RedisCache {
+    prefix;
+    _regexp = /\{([^\:]+):[^\}]+\}/g;
+    constructor(prefix) {
+        this.prefix = prefix;
+    }
+    makeKey(key, options) {
+        return this.prefix + key.replace(this._regexp, (_, key) => String(options[key]));
+    }
+    async _write(target, params) {
+        const key = this.makeKey(target.key, params);
+        const cache = await target.fn(params);
+        if (!(cache instanceof Cache)) {
+            throw new Error('Cache result must be an instance of Cache');
+        }
+        const redis = await loadService(ioredisService);
+        const exists = await redis.exists(key);
+        if (cache.data === undefined) {
+            if (exists) {
+                await redis.del(key);
+            }
+            return;
+        }
+        const payload = JSON.stringify(cache.data);
+        if (cache.expire > 0) {
+            await redis.setex(key, cache.expire, payload);
+        }
+        else {
+            await redis.set(key, payload);
+        }
+        return cache.data;
+    }
+    async _read(target, params) {
+        const key = this.makeKey(target.key, params);
+        const redis = await loadService(ioredisService);
+        const exists = await redis.exists(key);
+        if (!exists)
+            return await this._write(target, params);
+        const text = await redis.get(key);
+        if (!text)
+            return await this._write(target, params);
+        return JSON.parse(text);
+    }
+    async _remove(target, params) {
+        const key = this.makeKey(target.key, params);
+        const redis = await loadService(ioredisService);
+        const exists = await redis.exists(key);
+        if (!exists)
+            return 0;
+        return await redis.del(key);
+    }
+    async _has(target, params) {
+        const key = this.makeKey(target.key, params);
+        const redis = await loadService(ioredisService);
+        const exists = await redis.exists(key);
+        return !!exists;
+    }
+    async loadCache(target) {
+        return {
+            write: async (params) => {
+                return await this._write(target, params);
+            },
+            read: async (params) => {
+                return await this._read(target, params);
+            },
+            remove: async (params) => {
+                return await this._remove(target, params);
+            },
+            has: async (params) => {
+                return await this._has(target, params);
+            }
+        };
+    }
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@hile/cache",
+  "version": "1.0.1",
+  "type": "module",
+  "main": "./dist/index.js",
+  "scripts": {
+    "build": "tsc -b && fix-esm-import-path --preserve-import-type ./dist",
+    "dev": "tsc -b --watch",
+    "test": "vitest run"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "SKILL.md"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "fix-esm-import-path": "^1.10.3",
+    "vitest": "^4.0.18"
+  },
+  "dependencies": {
+    "@hile/core": "^1.1.2",
+    "@hile/ioredis": "^1.1.2"
+  },
+  "gitHead": "35dc91ded2eb802fdd5edd1c6868b3b205a128bc"
+}