@hile/cache 3.0.1 → 3.0.2

package/AI.md

@@ -0,0 +1,232 @@
+# AI Guide For @hile/cache
+
+
+
+<!-- Generated by scripts/build-ai-context.mjs from docs/ai. Do not edit by hand. -->
+
+
+
+Purpose: Build typed Redis read-through caches with TTL, tags, fieldable hashes, negative/stale options, and singleflight refreshes.
+
+
+
+Use this file when an AI agent installs the npm package and needs package-local examples, package selection rules, boundaries, and verification steps.
+
+
+
+## Package Selection
+
+
+
+| User asks for | Use | Also read |
+|---|---|---|
+| Add read-through Redis cache | `@hile/cache` | `packages/infrastructure.md`, `recipes/redis-cache-singleflight.md` |
+
+
+
+# Infrastructure Helpers
+
+Packages: `@hile/typeorm`, `@hile/ioredis`, `@hile/logger`, `@hile/cache`, `@hile/schedule`, `@hile/loader`.
+
+## Use When
+
+Use these packages for database connections, Redis connections, structured logging, typed Redis caches, scheduled jobs, and file-system loaders.
+
+## Do Not Use When
+
+- Do not use default TypeORM or Redis services for multiple connections.
+- Do not use `@hile/cache` without returning `new Cache(...)` from the loader function.
+- Do not use `@hile/schedule` distributed mode without Redis lock TTLs sized for job duration.
+
+## Install
+
+```bash
+pnpm add @hile/typeorm @hile/ioredis @hile/logger @hile/cache @hile/schedule @hile/loader
+```
+
+## Imports
+
+```ts
+import typeormService, { transaction } from '@hile/typeorm'
+import redisService from '@hile/ioredis'
+import { createLogger } from '@hile/logger'
+import { Cache, defineCache, RedisCache } from '@hile/cache'
+import { Scheduler, defineJob } from '@hile/schedule'
+import { scanDirectory, compileRoutePath, toRouterPath, normalizePath, Loader } from '@hile/loader'
+```
+
+## Copy-Paste Example
+
+```ts
+import { loadService } from '@hile/core'
+import redisService from '@hile/ioredis'
+import { Cache, defineCache, RedisCache } from '@hile/cache'
+
+const userProfile = defineCache('user:{id:string}:profile', async ({ id }) => {
+  const user = await loadUser(id)
+  return new Cache(user).setExpire(300)
+})
+
+const redis = await loadService(redisService)
+const cache = new RedisCache('app:', redis)
+const users = await cache.loadCache(userProfile)
+const user = await users.read({ id: 'u1' })
+```
+
+## More Examples
+
+TypeORM transaction with compensation:
+
+```ts
+await transaction(ds, async (runner, rollback) => {
+  const user = await runner.manager.save(User, input)
+  rollback(() => redis.del(`user:${user.id}`))
+  await runner.manager.save(AuditLog, { userId: user.id, action: 'create' })
+  return user
+})
+```
+
+Distributed scheduled job:
+
+```ts
+const scheduler = new Scheduler()
+scheduler.add('daily-report', '0 8 * * *', async () => {
+  await sendDailyReport()
+}, {
+  distributed: {
+    redis,
+    ttl: 60_000,
+    namespace: 'reports',
+    policy: 'skip-if-locked',
+  },
+})
+```
+
+## Compose With
+
+- Use `RedisCache` with `@hile/ioredis`.
+- Use `defineCache(..., { singleflight: true })` to reduce stampedes; internally it uses Redis locks.
+- Use scheduler distributed mode with `@hile/redis-lock`.
+- Use `Loader` only when building a new file-system based convention.
+
+## Runtime And Lifecycle Notes
+
+- `Cache(undefined)` removes the key unless negative caching is configured.
+- `Cache#setExpire(seconds)` uses seconds.
+- `defineCache` typed placeholders support `string`, `number`, and `boolean`.
+- `RedisCache.loadCache()` returns `read`, `write`, `remove`, `has`, and `multi`.
+- `RedisCache.removeTag(tag)` removes tagged cache entries.
+- `fieldable` caches use Redis hashes and cannot combine with stale or negative cache options.
+- `Scheduler.add()` supports cron strings and `{ delay }`.
+- `Scheduler.load()` reads default exports from `*.schedule.*` files produced by `defineJob()`.
+- `scanDirectory()` matches `.ts`, `.js`, `.tsx`, `.jsx`, and `.mjs`.
+
+## Anti-Patterns
+
+- Returning raw values from `defineCache` handlers instead of `new Cache(value)`.
+- Treating cache as source of truth.
+- Forgetting to destroy manually created Redis or TypeORM clients.
+- Scheduling jobs without idempotency when side effects can repeat.
+
+## Verification Checklist
+
+- Manual Redis clients call `disconnect()` during cleanup.
+- Manual TypeORM data sources call `destroy()` during cleanup.
+- Cache keys include app/tenant prefixes when shared Redis is used.
+- Scheduled jobs have clear duplicate-run policy.
+
+
+
+# Related Recipes
+
+
+
+# Redis Cache With Singleflight
+
+## Complete Example
+
+```ts
+import { loadService } from '@hile/core'
+import redisService from '@hile/ioredis'
+import { Cache, defineCache, RedisCache } from '@hile/cache'
+
+const userProfileCache = defineCache(
+  'user:{id:string}:profile',
+  async ({ id }) => {
+    const profile = await loadProfileFromDatabase(id)
+    if (!profile) return new Cache(undefined)
+    return new Cache(profile).setExpire(300)
+  },
+  {
+    singleflight: { ttl: 10_000, wait: 10_000 },
+    stale: { ttl: 60 },
+    negative: { ttl: 30 },
+    tags: (params, data) => data ? [`user:${params.id}`] : [],
+  },
+)
+
+const redis = await loadService(redisService)
+const cache = new RedisCache('app:', redis)
+const userProfiles = await cache.loadCache(userProfileCache)
+
+const profile = await userProfiles.read({ id: 'u1' })
+await userProfiles.remove({ id: 'u1' })
+await cache.removeTag('user:u1')
+```
+
+## File Layout
+
+```text
+src/
+  caches/user-profile.cache.ts
+  models/users/get-profile.model.ts
+```
+
+## User Intent
+
+Use this recipe when reads are expensive and Redis should provide read-through caching with stampede protection.
+
+## Packages To Use
+
+- `@hile/cache`
+- `@hile/ioredis`
+- `@hile/redis-lock` indirectly through cache singleflight
+
+## Implementation Steps
+
+1. Define a typed key with placeholders.
+2. Return `new Cache(value)` from the loader function.
+3. Add TTL with `setExpire(seconds)`.
+4. Enable `singleflight` for expensive reads.
+5. Remove cache entries after writes.
+
+## Failure And Cleanup Behavior
+
+- Stale cache serves previous values while refresh runs.
+- Negative cache stores missing values only when configured.
+- Cache is not source of truth; database writes should remove or refresh related keys.
+
+## Verification Checklist
+
+- Cache handler returns `Cache`.
+- Key params match placeholders.
+- Redis prefix is app-specific.
+- Update flows call `remove()` or `removeTag()`.
+
+
+
+# Global Guardrails
+
+
+
+## Never Generate These Patterns
+
+- Do not call `loadService()` at module top level; it starts resources during import.
+- Do not default-export plain functions from `*.boot.*` files; `hile start` expects a Hile service.
+- Do not set `ctx.body` and also return a controller value.
+- Do not assume `@hile/http` Zod validation mutates or coerces `ctx.query`, `ctx.params`, or `ctx.request.body`.
+- Do not put reusable business logic only in controllers, pages, queue workers, or message handlers.
+- Do not use old message examples that append a secondary response getter; current request APIs return promises directly.
+- Do not claim exactly-once delivery or execution from Redis locks, queues, idempotency, or rate limits.
+- Do not use queue `jobId` as the only side-effect idempotency boundary.
+- Do not log the entire async context by default.

package/README.md

@@ -1,244 +1,59 @@
 # @hile/cache
 
-基于 Redis 的类型安全读穿透缓存层。依赖 `ioredis`，构造时注入已连接的 `Redis` 实例（可与 `@hile/ioredis` 配合使用）。
+<!-- Generated by scripts/build-ai-context.mjs from docs/ai. Do not edit by hand. -->
 
-从 3.0.0 开始，新增或重构的 Hile 架构包统一进入 3.x 版本线，2.x 时代结束。
+Build typed Redis read-through caches with TTL, tags, fieldable hashes, negative/stale options, and singleflight refreshes.
 
-## 安装
+This README is intentionally short and example-first. The complete AI-facing guide ships in `AI.md` in this package.
 
-```bash
-pnpm add @hile/cache
-```
-
-运行时需提供 `ioredis` 的 `Redis` 实例；在 Hile 应用中通常通过 `@hile/ioredis` 的 `createRedis()` 或 `loadService(ioredisService)` 获取。
-
-## 快速开始
-
-### 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
-}, {
-  singleflight: true,
-  stale: { ttl: 60 },
-  negative: { ttl: 30 },
-  tags: ({ id }) => ['users', `user:${id}`],
-});
-```
-
-### 2. 使用缓存
-
-```typescript
-import { loadService } from '@hile/core';
-import redisService from '@hile/ioredis';
-import { RedisCache } from '@hile/cache';
-
-const redis = await loadService(redisService);
-const cache = new RedisCache('myapp:', redis); // 前缀 + Redis 实例
-
-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' });
-
-// 按 tag 批量失效
-await cache.removeTag('users');
-```
-
----
-
-## 核心概念
-
-### 类型安全 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 → 返回
-```
-
-### Singleflight
+## When To Use
 
-`singleflight` 使用 `@hile/redis-lock` 合并同一个 key 的并发 miss，避免热点 key 同时打到数据库。
+Use these packages for database connections, Redis connections, structured logging, typed Redis caches, scheduled jobs, and file-system loaders.
 
-```typescript
-const userCache = defineCache('user:{id:string}', fetchUser, {
-  singleflight: {
-    ttl: 10_000,
-    wait: 10_000,
-  },
-});
-```
-
-### Stale Cache
-
-`stale: { ttl }` 会在数据过了 `Cache#setExpire()` 的 fresh 时间后继续保留一段 stale 时间。读取 stale 数据时立即返回旧值，并在后台刷新。
-
-### Negative Cache
-
-默认 `new Cache(undefined)` 不写 Redis。配置 `negative: { ttl }` 后会写入一个短 TTL 哨兵，避免不存在的数据反复回源。
-
-### Tags
-
-`tags` 会把缓存 key 记录到 Redis set，之后可用 `cache.removeTag(tag)` 批量删除。
-
----
-
-## API 参考
-
-### defineCache
-
-```typescript
-function defineCache<T extends string = string, R = any>(
-  key: T,
-  fn: (params: ExtractParams<T>) => Promise<Cache<R>>,
-  options?: boolean | DefineCacheOptions<T, R>
-): DefineCacheResult<T, R>;
-```
-
-第三个参数仍兼容旧的 `boolean` fieldable 写法；新能力使用 options 对象。
-
-> `fieldable` 使用 Redis Hash 存储，不兼容 `stale` 和 `negative` 这类依赖字符串 payload 的策略；组合使用会在 `defineCache()` 阶段直接抛出配置错误。
-
-### RedisCache
-
-```typescript
-class RedisCache {
-  constructor(prefix: string, redis: Redis, options?: { locks?: RedisLock });
-
-  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>;
-  }>;
-
-  removeTag(tag: string): Promise<number>;
-}
-```
-
-| 方法 | 返回值 | 说明 |
-|------|--------|------|
-| `read` | `R \| undefined` | 读穿透：EXISTS → GET / miss 则回源写入 |
-| `write` | `R \| undefined` | 强制执行回源并写入 Redis（data=undefined 则删除 key） |
-| `remove` | `number` | 删除缓存，返回 0/1 |
-| `has` | `boolean` | 检查 key 是否存在 |
-| `removeTag` | `number` | 删除某个 tag 下记录的所有缓存 key |
-
-### Redis 中的 key 结构
+## Install
 
-```
-{prefix}{key模板渲染结果}
-```
-
-例如 `prefix = "myapp:"`、key 模板为 `user:{id:string}:info`、params 为 `{ id: "u-001" }` 时：
-```
-myapp:user:u-001:info
+```bash
+pnpm add @hile/cache
 ```
 
----
+## Copy-Paste Example
 
-## 与 @hile/cli 集成
+```ts
+import { loadService } from '@hile/core'
+import redisService from '@hile/ioredis'
+import { Cache, defineCache, RedisCache } from '@hile/cache'
 
-在 `package.json` 中配置自动加载 Redis，在 boot 或服务工厂里注入客户端：
+const userProfile = defineCache('user:{id:string}:profile', async ({ id }) => {
+  const user = await loadUser(id)
+  return new Cache(user).setExpire(300)
+})
 
-```json
-{
-  "hile": {
-    "auto_load_packages": ["@hile/ioredis"]
-  }
-}
+const redis = await loadService(redisService)
+const cache = new RedisCache('app:', redis)
+const users = await cache.loadCache(userProfile)
+const user = await users.read({ id: 'u1' })
 ```
 
-```typescript
-import { loadService } from '@hile/core';
-import redisService from '@hile/ioredis';
-import { defineCache, Cache, RedisCache } from '@hile/cache';
+## Boundaries
 
-// 在 defineService 工厂内
-const redis = await loadService(redisService);
-const cache = new RedisCache('myapp:', redis);
-```
-
----
-
-## 完整示例
-
-```typescript
-import { loadService } from '@hile/core';
-import redisService from '@hile/ioredis';
-import { defineCache, Cache, RedisCache } from '@hile/cache';
-
-const redis = await loadService(redisService);
+- Do not use default TypeORM or Redis services for multiple connections.
+- Do not use `@hile/cache` without returning `new Cache(...)` from the loader function.
+- Do not use `@hile/schedule` distributed mode without Redis lock TTLs sized for job duration.
 
-// 定义多条缓存
-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);
-});
+- Returning raw values from `defineCache` handlers instead of `new Cache(value)`.
+- Treating cache as source of truth.
+- Forgetting to destroy manually created Redis or TypeORM clients.
+- Scheduling jobs without idempotency when side effects can repeat.
 
-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:', redis);
-
-// 批量加载
-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' });
-```
+## Verify
 
----
+- Manual Redis clients call `disconnect()` during cleanup.
+- Manual TypeORM data sources call `destroy()` during cleanup.
+- Cache keys include app/tenant prefixes when shared Redis is used.
+- Scheduled jobs have clear duplicate-run policy.
 
-## License
+## More Context
 
-MIT
+- `AI.md` in this package: full package-local AI guide.
+- Root `llms-full.txt`: full monorepo AI context.
+- Root `references/`: source files copied from `docs/ai`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hile/cache",
-  "version": "3.0.1",
+  "version": "3.0.2",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -10,7 +10,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "AI.md"
   ],
   "license": "MIT",
   "publishConfig": {
@@ -21,8 +22,8 @@
     "vitest": "^4.0.18"
   },
   "dependencies": {
-    "@hile/redis-lock": "^3.0.1",
+    "@hile/redis-lock": "^3.0.2",
     "ioredis": "^5.11.0"
   },
-  "gitHead": "88f52fb95743f86761778776aff23631fcf9d821"
+  "gitHead": "0985b6f8abc1f4de0a36324063585fdc3ac1375b"
 }