@hile/cache 2.1.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,201 +1,59 @@
 # @hile/cache
 
-基于 Redis 的类型安全读穿透缓存层。依赖 `ioredis`，构造时注入已连接的 `Redis` 实例（可与 `@hile/ioredis` 配合使用）。
+<!-- Generated by scripts/build-ai-context.mjs from docs/ai. Do not edit by hand. -->
 
-## 安装
+Build typed Redis read-through caches with TTL, tags, fieldable hashes, negative/stale options, and singleflight refreshes.
 
-```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
-});
-```
-
-### 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' });
-```
-
----
-
-## 核心概念
-
-### 类型安全 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 控制：
+This README is intentionally short and example-first. The complete AI-facing guide ships in `AI.md` in this package.
 
-| 方法 | 说明 |
-|------|------|
-| `new Cache(data)` | 创建缓存数据，expire=0 永不过期 |
-| `.setExpire(seconds)` | 设置 TTL（秒） |
+## When To Use
 
-### 读穿透（Read-Through）
+Use these packages for database connections, Redis connections, structured logging, typed Redis caches, scheduled jobs, and file-system loaders.
 
-`RedisCache._read` 的调用链路：
+## Install
 
-```
-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, redis: Redis);
-
-  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
+```bash
+pnpm add @hile/cache
 ```
 
----
+## Copy-Paste Example
 
-## 与 @hile/cli 集成
-
-在 `package.json` 中配置自动加载 Redis，在 boot 或服务工厂里注入客户端：
-
-```json
-{
-  "hile": {
-    "auto_load_packages": ["@hile/ioredis"]
-  }
-}
-```
+```ts
+import { loadService } from '@hile/core'
+import redisService from '@hile/ioredis'
+import { Cache, defineCache, RedisCache } from '@hile/cache'
 
-```typescript
-import { loadService } from '@hile/core';
-import redisService from '@hile/ioredis';
-import { defineCache, Cache, RedisCache } from '@hile/cache';
+const userProfile = defineCache('user:{id:string}:profile', async ({ id }) => {
+  const user = await loadUser(id)
+  return new Cache(user).setExpire(300)
+})
 
-// 在 defineService 工厂内
-const redis = await loadService(redisService);
-const cache = new RedisCache('myapp:', redis);
+const redis = await loadService(redisService)
+const cache = new RedisCache('app:', redis)
+const users = await cache.loadCache(userProfile)
+const user = await users.read({ id: 'u1' })
 ```
 
----
+## Boundaries
 
-## 完整示例
+- 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.
 
-```typescript
-import { loadService } from '@hile/core';
-import redisService from '@hile/ioredis';
-import { defineCache, Cache, RedisCache } from '@hile/cache';
+- 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 redis = await loadService(redisService);
-
-// 定义多条缓存
-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:', 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/dist/define.d.ts

@@ -11,9 +11,30 @@ export type ExtractParams<Template extends string> = string extends Template ? R
     [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 CacheTagResolver<T extends string = string, R = any> = string[] | ((params: ExtractParams<T>, data: R | undefined) => string[]);
+export type CacheSingleflightOptions = {
+    ttl?: number;
+    wait?: number;
+    pollInterval?: number;
+    maxPollInterval?: number;
+};
+export type CacheStaleOptions = {
+    ttl: number;
+};
+export type CacheNegativeOptions = {
+    ttl: number;
+};
+export type DefineCacheOptions<T extends string = string, R = any> = {
+    fieldable?: boolean;
+    singleflight?: boolean | CacheSingleflightOptions;
+    stale?: CacheStaleOptions;
+    negative?: CacheNegativeOptions;
+    tags?: CacheTagResolver<T, R>;
+};
 export type DefineCacheResult<T extends string = string, R = any> = {
     fn: DefineCacheHandler<T, R>;
-    key: string;
+    key: T;
     fieldable: boolean;
+    options: DefineCacheOptions<T, R>;
 };
-export declare function defineCache<T extends string = string, R = any>(key: T, fn: DefineCacheHandler<T, R>, fieldable?: boolean): DefineCacheResult<T, R>;
+export declare function defineCache<T extends string = string, R = any>(key: T, fn: DefineCacheHandler<T, R>, options?: boolean | DefineCacheOptions<T, R>): DefineCacheResult<T, R>;

package/dist/define.js

@@ -13,11 +13,26 @@ export class Cache {
         return this._expire;
     }
 }
-export function defineCache(key, fn, fieldable = false) {
+function normalizeDefineCacheOptions(options) {
+    return typeof options === 'boolean'
+        ? { fieldable: options }
+        : options;
+}
+function assertCompatibleCacheOptions(options) {
+    if (!options.fieldable)
+        return;
+    if (options.negative || options.stale) {
+        throw new TypeError('fieldable cache cannot be combined with negative or stale cache options');
+    }
+}
+export function defineCache(key, fn, options = false) {
+    const normalized = normalizeDefineCacheOptions(options);
+    assertCompatibleCacheOptions(normalized);
     return {
         fn,
         key,
-        fieldable,
+        fieldable: normalized.fieldable ?? false,
+        options: normalized,
     };
 }
 // defineCache('user:{id:string}:ddd:{x:number}:idsaf:{y:boolean}', async (params) => {

package/dist/index.d.ts

@@ -1,16 +1,34 @@
+import { RedisLock } from '@hile/redis-lock';
 import { DefineCacheResult, ExtractParams } from './define.js';
 import { ChainableCommander, Redis } from 'ioredis';
 export * from './define.js';
+export * from './options.js';
+export * from './payload.js';
+export * from './tags.js';
+export type RedisCacheOptions = {
+    locks?: RedisLock;
+};
 export declare class RedisCache {
     private readonly prefix;
     private readonly redis;
     private readonly _regexp;
-    constructor(prefix: string, redis: Redis);
+    private readonly locks;
+    private readonly tags;
+    constructor(prefix: string, redis: Redis, options?: RedisCacheOptions);
     private makeKey;
     private _multi;
     private _write;
+    private _writeWithKey;
+    private _storeCacheResult;
+    private rememberTags;
     private _read;
+    private _readExisting;
+    private _refreshStale;
     private _remove;
+    private withKeyTagMutationLock;
+    private withMutationLocks;
+    private makeKeyMutationLockKey;
+    private makeTagMutationLockKey;
     private _has;
     loadCache<T extends string, R>(target: DefineCacheResult<T, R>): Promise<{
         write: (params: ExtractParams<T>) => Promise<R | undefined>;
@@ -19,4 +37,5 @@ export declare class RedisCache {
         has: (params: ExtractParams<T>) => Promise<boolean>;
         multi: (params: ExtractParams<T>, callback: (multi: ChainableCommander, key: string) => unknown) => Promise<[error: Error | null, result: unknown][] | null>;
     }>;
+    removeTag(tag: string): Promise<number>;
 }

package/dist/index.js

@@ -1,11 +1,26 @@
+import { RedisLock } from '@hile/redis-lock';
+import { decodeCacheValue, encodeCacheValue, encodeNegative, resolveNegativeTtl, resolveRedisTtl, } from './payload.js';
+import { resolveSingleflightOptions } from './options.js';
+import { CacheTagIndex } from './tags.js';
 export * from './define.js';
+export * from './options.js';
+export * from './payload.js';
+export * from './tags.js';
+const TAG_MUTATION_LOCK_OPTIONS = {
+    ttl: 10_000,
+    wait: 10_000,
+};
 export class RedisCache {
     prefix;
     redis;
     _regexp = /\{([^\:]+):[^\}]+\}/g;
-    constructor(prefix, redis) {
+    locks;
+    tags;
+    constructor(prefix, redis, options = {}) {
         this.prefix = prefix;
         this.redis = redis;
+        this.locks = options.locks ?? new RedisLock(redis);
+        this.tags = new CacheTagIndex(prefix, redis);
     }
     makeKey(key, options) {
         return this.prefix + key.replace(this._regexp, (_, key) => String(options[key]));
@@ -15,23 +30,44 @@ export class RedisCache {
         const redis = this.redis;
         const exists = await redis.exists(key);
         if (!exists)
-            await this._write(target, params);
+            await this._writeWithKey(target, params, key);
         const multi = redis.multi();
         callback(multi, key);
         return await multi.exec();
     }
     async _write(target, params) {
         const key = this.makeKey(target.key, params);
+        return this._writeWithKey(target, params, key);
+    }
+    async _writeWithKey(target, params, key) {
         const cache = await target.fn(params);
-        if (cache.__$flag__ !== 'cache') {
+        if (!cache || cache.__$flag__ !== 'cache') {
             throw new Error('Cache result must be an instance of Cache');
         }
+        if (!target.options.tags) {
+            return this._storeCacheResult(target, params, key, cache);
+        }
+        const nextTags = cache.data === undefined && resolveNegativeTtl(target.options) === undefined
+            ? []
+            : this.tags.resolveTags(target, params, cache.data);
+        return this.withKeyTagMutationLock(target, params, key, nextTags, () => {
+            return this._storeCacheResult(target, params, key, cache, nextTags);
+        });
+    }
+    async _storeCacheResult(target, params, key, cache, resolvedTags) {
         const redis = this.redis;
         const exists = await redis.exists(key);
         if (cache.data === undefined) {
-            if (exists) {
-                await redis.del(key);
+            const negativeTtl = resolveNegativeTtl(target.options);
+            if (negativeTtl !== undefined) {
+                await redis.setex(key, negativeTtl, encodeNegative());
+                await this.rememberTags(target, params, undefined, key, resolvedTags);
+                return;
             }
+            if (exists)
+                await redis.del(key);
+            if (target.options.tags)
+                await this.tags.forget(target, params, key);
             return;
         }
         if (target.fieldable) {
@@ -39,40 +75,126 @@ export class RedisCache {
             if (cache.expire > 0) {
                 await redis.expire(key, cache.expire);
             }
+            else {
+                await redis.persist(key);
+            }
+            await this.rememberTags(target, params, cache.data, key, resolvedTags);
             return cache.data;
         }
-        const payload = JSON.stringify(cache.data);
-        if (cache.expire > 0) {
-            await redis.setex(key, cache.expire, payload);
+        const payload = encodeCacheValue(cache.data, cache.expire, target.options);
+        const ttl = resolveRedisTtl(cache.expire, target.options);
+        if (ttl > 0) {
+            await redis.setex(key, ttl, payload);
         }
         else {
             await redis.set(key, payload);
         }
+        await this.rememberTags(target, params, cache.data, key, resolvedTags);
         return cache.data;
     }
+    async rememberTags(target, params, data, key, resolvedTags) {
+        if (!target.options.tags)
+            return;
+        if (resolvedTags) {
+            await this.tags.rememberTags(key, resolvedTags);
+            return;
+        }
+        await this.tags.remember(target, params, data, key);
+    }
     async _read(target, params) {
         const key = this.makeKey(target.key, params);
-        const redis = this.redis;
+        const cached = await this._readExisting(target, key);
+        if (cached.hit) {
+            if (cached.stale) {
+                void this._refreshStale(target, params, key);
+            }
+            return cached.value;
+        }
+        const singleflight = resolveSingleflightOptions(target.options);
+        if (singleflight) {
+            return this.locks.withLock(`${key}:lock`, singleflight, async () => {
+                const current = await this._readExisting(target, key);
+                if (current.hit)
+                    return current.value;
+                return this._writeWithKey(target, params, key);
+            });
+        }
+        return await this._writeWithKey(target, params, key);
+    }
+    async _readExisting(target, key) {
         if (target.fieldable) {
-            const fields = await redis.hgetall(key);
-            if (!fields)
-                return await this._write(target, params);
-            if (Object.keys(fields).length === 0)
-                return await this._write(target, params);
-            return fields;
+            const fields = await this.redis.hgetall(key);
+            if (!fields || Object.keys(fields).length === 0)
+                return { hit: false };
+            return { hit: true, value: fields, stale: false };
         }
-        const text = await redis.get(key);
+        const text = await this.redis.get(key);
         if (!text)
-            return await this._write(target, params);
-        return JSON.parse(text);
+            return { hit: false };
+        return decodeCacheValue(text, target.options);
+    }
+    async _refreshStale(target, params, key) {
+        try {
+            const singleflight = resolveSingleflightOptions(target.options);
+            if (singleflight) {
+                await this.locks.withLock(`${key}:lock`, {
+                    ...singleflight,
+                    wait: 0,
+                }, async () => {
+                    await this._writeWithKey(target, params, key);
+                });
+                return;
+            }
+            await this._writeWithKey(target, params, key);
+        }
+        catch {
+            // stale cache should keep serving the previous value when refresh fails
+        }
     }
     async _remove(target, params) {
         const key = this.makeKey(target.key, params);
+        if (target.options.tags) {
+            return this.withKeyTagMutationLock(target, params, key, [], async () => {
+                const removed = await this.redis.del(key);
+                await this.tags.forget(target, params, key);
+                return removed;
+            });
+        }
         const redis = this.redis;
         const exists = await redis.exists(key);
         if (!exists)
             return 0;
-        return await redis.del(key);
+        const removed = await redis.del(key);
+        if (removed > 0)
+            await this.tags.forget(target, params, key);
+        return removed;
+    }
+    async withKeyTagMutationLock(target, params, key, nextTags, callback) {
+        return this.withMutationLocks([this.makeKeyMutationLockKey(key)], async () => {
+            const previousTags = await this.tags.readKeyTags(key);
+            const legacyTags = previousTags.length === 0
+                ? this.tags.resolveTags(target, params, undefined)
+                : [];
+            const tagLockKeys = [...previousTags, ...legacyTags, ...nextTags]
+                .map(tag => this.makeTagMutationLockKey(tag));
+            return this.withMutationLocks(tagLockKeys, callback);
+        });
+    }
+    async withMutationLocks(lockKeys, callback) {
+        const keys = [...new Set(lockKeys)].sort();
+        const run = async (index) => {
+            if (index >= keys.length)
+                return callback();
+            const lockKey = keys[index];
+            return this.locks.withLock(lockKey, TAG_MUTATION_LOCK_OPTIONS, async () => run(index + 1));
+        };
+        return run(0);
+    }
+    makeKeyMutationLockKey(key) {
+        return `${key}:hile-cache:mutation-lock`;
+    }
+    makeTagMutationLockKey(tag) {
+        return `${this.prefix}tag:${tag}:mutation-lock`;
     }
     async _has(target, params) {
         const key = this.makeKey(target.key, params);
@@ -99,4 +221,9 @@ export class RedisCache {
             }
         };
     }
+    async removeTag(tag) {
+        return this.withMutationLocks([this.makeTagMutationLockKey(tag)], () => {
+            return this.tags.removeTag(tag);
+        });
+    }
 }

package/dist/options.d.ts

@@ -0,0 +1,8 @@
+import type { DefineCacheOptions } from './define';
+export type ResolvedSingleflightOptions = {
+    ttl: number;
+    wait: number;
+    pollInterval?: number;
+    maxPollInterval?: number;
+};
+export declare function resolveSingleflightOptions<T extends string, R>(options: DefineCacheOptions<T, R>): ResolvedSingleflightOptions | undefined;

package/dist/options.js

@@ -0,0 +1,12 @@
+export function resolveSingleflightOptions(options) {
+    if (!options.singleflight)
+        return undefined;
+    const singleflight = options.singleflight === true ? {} : options.singleflight;
+    const ttl = singleflight.ttl ?? 10_000;
+    return {
+        ttl,
+        wait: singleflight.wait ?? ttl,
+        pollInterval: singleflight.pollInterval,
+        maxPollInterval: singleflight.maxPollInterval,
+    };
+}

package/dist/payload.d.ts

@@ -0,0 +1,13 @@
+import type { DefineCacheOptions } from './define';
+export type CacheReadResult<R> = {
+    hit: false;
+} | {
+    hit: true;
+    value: R | undefined;
+    stale: boolean;
+};
+export declare function resolveNegativeTtl<T extends string, R>(options: DefineCacheOptions<T, R>): number | undefined;
+export declare function resolveRedisTtl<T extends string, R>(expire: number, options: DefineCacheOptions<T, R>): number;
+export declare function encodeCacheValue<T extends string, R>(data: R, expire: number, options: DefineCacheOptions<T, R>): string;
+export declare function encodeNegative(): string;
+export declare function decodeCacheValue<R, T extends string = string>(text: string, options?: DefineCacheOptions<T, R>): CacheReadResult<R>;

package/dist/payload.js

@@ -0,0 +1,79 @@
+const PAYLOAD_FLAG = '__$hile_cache';
+const PAYLOAD_PREFIX = '\x1fhile-cache:v1:';
+function getPayloadFlag(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    return value[PAYLOAD_FLAG];
+}
+function isStoredValue(value) {
+    if (getPayloadFlag(value) !== 'value')
+        return false;
+    const record = value;
+    const keys = Object.keys(record);
+    return 'data' in record
+        && typeof record.freshUntil === 'number'
+        && keys.every(key => key === PAYLOAD_FLAG || key === 'data' || key === 'freshUntil');
+}
+function isStoredNegative(value) {
+    if (getPayloadFlag(value) !== 'negative')
+        return false;
+    return Object.keys(value).length === 1;
+}
+function encodePayload(value) {
+    return `${PAYLOAD_PREFIX}${JSON.stringify(value)}`;
+}
+function decodePrefixedPayload(text) {
+    if (!text.startsWith(PAYLOAD_PREFIX))
+        return undefined;
+    const stored = JSON.parse(text.slice(PAYLOAD_PREFIX.length));
+    if (stored.type === 'negative') {
+        return { hit: true, value: undefined, stale: false };
+    }
+    if (stored.type !== 'value') {
+        throw new Error('Invalid cache payload');
+    }
+    const freshUntil = typeof stored.freshUntil === 'number' ? stored.freshUntil : undefined;
+    return {
+        hit: true,
+        value: stored.data,
+        stale: freshUntil !== undefined && Date.now() > freshUntil,
+    };
+}
+export function resolveNegativeTtl(options) {
+    return options.negative?.ttl;
+}
+export function resolveRedisTtl(expire, options) {
+    if (expire <= 0)
+        return 0;
+    return expire + (options.stale?.ttl ?? 0);
+}
+export function encodeCacheValue(data, expire, options) {
+    if (!options.stale || expire <= 0)
+        return JSON.stringify(data);
+    return encodePayload({
+        type: 'value',
+        data,
+        freshUntil: Date.now() + expire * 1000,
+    });
+}
+export function encodeNegative() {
+    return encodePayload({ type: 'negative' });
+}
+export function decodeCacheValue(text, options = {}) {
+    const prefixed = decodePrefixedPayload(text);
+    if (prefixed)
+        return prefixed;
+    const parsed = JSON.parse(text);
+    if (options.negative && isStoredNegative(parsed)) {
+        return { hit: true, value: undefined, stale: false };
+    }
+    if (!options.stale || !isStoredValue(parsed)) {
+        return { hit: true, value: parsed, stale: false };
+    }
+    const freshUntil = typeof parsed.freshUntil === 'number' ? parsed.freshUntil : undefined;
+    return {
+        hit: true,
+        value: parsed.data,
+        stale: freshUntil !== undefined && Date.now() > freshUntil,
+    };
+}

package/dist/tag-scripts.d.ts

@@ -0,0 +1,3 @@
+export declare const REPLACE_CACHE_TAGS = "\n-- REPLACE_CACHE_TAGS\nlocal cacheKey = ARGV[1]\nlocal tagPrefix = ARGV[2]\nlocal next = {}\n\nfor i = 3, #ARGV do\n  next[ARGV[i]] = true\nend\n\nlocal previous = redis.call('SMEMBERS', KEYS[1])\nfor _, tag in ipairs(previous) do\n  if not next[tag] then\n    redis.call('SREM', tagPrefix .. tag, cacheKey)\n  end\nend\n\nredis.call('DEL', KEYS[1])\nfor i = 3, #ARGV do\n  redis.call('SADD', tagPrefix .. ARGV[i], cacheKey)\n  redis.call('SADD', KEYS[1], ARGV[i])\nend\n\nreturn #ARGV - 2\n";
+export declare const FORGET_CACHE_TAGS = "\n-- FORGET_CACHE_TAGS\nlocal cacheKey = ARGV[1]\nlocal tagPrefix = ARGV[2]\nlocal tags = redis.call('SMEMBERS', KEYS[1])\n\nfor _, tag in ipairs(tags) do\n  redis.call('SREM', tagPrefix .. tag, cacheKey)\nend\nredis.call('DEL', KEYS[1])\n\nreturn #tags\n";
+export declare const REMOVE_CACHE_TAG = "\n-- REMOVE_CACHE_TAG\nlocal tagPrefix = ARGV[1]\nlocal indexPrefix = ARGV[2]\nlocal cacheKeys = redis.call('SMEMBERS', KEYS[1])\nlocal removed = 0\n\nfor _, cacheKey in ipairs(cacheKeys) do\n  local indexKey = indexPrefix .. cacheKey\n  local tags = redis.call('SMEMBERS', indexKey)\n\n  for _, tag in ipairs(tags) do\n    redis.call('SREM', tagPrefix .. tag, cacheKey)\n  end\n\n  redis.call('DEL', indexKey)\n  removed = removed + redis.call('DEL', cacheKey)\nend\n\nredis.call('DEL', KEYS[1])\n\nreturn removed\n";

package/dist/tag-scripts.js

@@ -0,0 +1,61 @@
+export const REPLACE_CACHE_TAGS = `
+-- REPLACE_CACHE_TAGS
+local cacheKey = ARGV[1]
+local tagPrefix = ARGV[2]
+local next = {}
+
+for i = 3, #ARGV do
+  next[ARGV[i]] = true
+end
+
+local previous = redis.call('SMEMBERS', KEYS[1])
+for _, tag in ipairs(previous) do
+  if not next[tag] then
+    redis.call('SREM', tagPrefix .. tag, cacheKey)
+  end
+end
+
+redis.call('DEL', KEYS[1])
+for i = 3, #ARGV do
+  redis.call('SADD', tagPrefix .. ARGV[i], cacheKey)
+  redis.call('SADD', KEYS[1], ARGV[i])
+end
+
+return #ARGV - 2
+`;
+export const FORGET_CACHE_TAGS = `
+-- FORGET_CACHE_TAGS
+local cacheKey = ARGV[1]
+local tagPrefix = ARGV[2]
+local tags = redis.call('SMEMBERS', KEYS[1])
+
+for _, tag in ipairs(tags) do
+  redis.call('SREM', tagPrefix .. tag, cacheKey)
+end
+redis.call('DEL', KEYS[1])
+
+return #tags
+`;
+export const REMOVE_CACHE_TAG = `
+-- REMOVE_CACHE_TAG
+local tagPrefix = ARGV[1]
+local indexPrefix = ARGV[2]
+local cacheKeys = redis.call('SMEMBERS', KEYS[1])
+local removed = 0
+
+for _, cacheKey in ipairs(cacheKeys) do
+  local indexKey = indexPrefix .. cacheKey
+  local tags = redis.call('SMEMBERS', indexKey)
+
+  for _, tag in ipairs(tags) do
+    redis.call('SREM', tagPrefix .. tag, cacheKey)
+  end
+
+  redis.call('DEL', indexKey)
+  removed = removed + redis.call('DEL', cacheKey)
+end
+
+redis.call('DEL', KEYS[1])
+
+return removed
+`;

package/dist/tags.d.ts

@@ -0,0 +1,19 @@
+import type { Redis } from 'ioredis';
+import type { DefineCacheResult, ExtractParams } from './define';
+export declare class CacheTagIndex {
+    private readonly prefix;
+    private readonly redis;
+    constructor(prefix: string, redis: Redis);
+    remember<T extends string, R>(target: DefineCacheResult<T, R>, params: ExtractParams<T>, data: R | undefined, key: string): Promise<void>;
+    forget<T extends string, R>(target: DefineCacheResult<T, R>, params: ExtractParams<T>, key: string): Promise<void>;
+    removeTag(tag: string): Promise<number>;
+    readKeyTags(key: string): Promise<string[]>;
+    rememberTags(key: string, tags: string[]): Promise<void>;
+    resolveTags<T extends string, R>(target: DefineCacheResult<T, R>, params: ExtractParams<T>, data: R | undefined): string[];
+    private makeTagKey;
+    private makeTagPrefix;
+    private makeKeyTagsKey;
+    private makeKeyTagsPrefix;
+    private replaceKeyTags;
+    private forgetKeyTags;
+}

package/dist/tags.js

@@ -0,0 +1,58 @@
+import { FORGET_CACHE_TAGS, REMOVE_CACHE_TAG, REPLACE_CACHE_TAGS } from './tag-scripts.js';
+export class CacheTagIndex {
+    prefix;
+    redis;
+    constructor(prefix, redis) {
+        this.prefix = prefix;
+        this.redis = redis;
+    }
+    async remember(target, params, data, key) {
+        const tags = this.resolveTags(target, params, data);
+        await this.rememberTags(key, tags);
+    }
+    async forget(target, params, key) {
+        const forgotten = await this.forgetKeyTags(key);
+        if (forgotten > 0)
+            return;
+        const legacyTags = this.resolveTags(target, params, undefined);
+        if (legacyTags.length === 0)
+            return;
+        await Promise.all(legacyTags.map(tag => this.redis.srem(this.makeTagKey(tag), key)));
+    }
+    async removeTag(tag) {
+        const removed = await this.redis.eval(REMOVE_CACHE_TAG, 1, this.makeTagKey(tag), this.makeTagPrefix(), this.makeKeyTagsPrefix());
+        return Number(removed);
+    }
+    async readKeyTags(key) {
+        return this.redis.smembers(this.makeKeyTagsKey(key));
+    }
+    async rememberTags(key, tags) {
+        await this.replaceKeyTags(key, tags);
+    }
+    resolveTags(target, params, data) {
+        const tags = target.options.tags;
+        if (!tags)
+            return [];
+        const resolved = typeof tags === 'function' ? tags(params, data) : tags;
+        return [...new Set(resolved)];
+    }
+    makeTagKey(tag) {
+        return `${this.makeTagPrefix()}${tag}`;
+    }
+    makeTagPrefix() {
+        return `${this.prefix}tag:`;
+    }
+    makeKeyTagsKey(key) {
+        return `${this.makeKeyTagsPrefix()}${key}`;
+    }
+    makeKeyTagsPrefix() {
+        return `${this.prefix}tag-index:`;
+    }
+    async replaceKeyTags(key, nextTags) {
+        await this.redis.eval(REPLACE_CACHE_TAGS, 1, this.makeKeyTagsKey(key), key, this.makeTagPrefix(), ...nextTags);
+    }
+    async forgetKeyTags(key) {
+        const removed = await this.redis.eval(FORGET_CACHE_TAGS, 1, this.makeKeyTagsKey(key), key, this.makeTagPrefix());
+        return Number(removed);
+    }
+}

package/package.json

@@ -1,16 +1,17 @@
 {
   "name": "@hile/cache",
-  "version": "2.1.1",
+  "version": "3.0.2",
   "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"
+    "test": "vitest run && tsc -p tsconfig.typecheck.json"
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "AI.md"
   ],
   "license": "MIT",
   "publishConfig": {
@@ -21,7 +22,8 @@
     "vitest": "^4.0.18"
   },
   "dependencies": {
+    "@hile/redis-lock": "^3.0.2",
     "ioredis": "^5.11.0"
   },
-  "gitHead": "7903ae989bd001d1ed1437cb90c9e828a1909061"
+  "gitHead": "0985b6f8abc1f4de0a36324063585fdc3ac1375b"
 }