@hile/cache 2.0.7 → 3.0.1

package/README.md

@@ -2,6 +2,8 @@
 
 基于 Redis 的类型安全读穿透缓存层。依赖 `ioredis`，构造时注入已连接的 `Redis` 实例（可与 `@hile/ioredis` 配合使用）。
 
+从 3.0.0 开始，新增或重构的 Hile 架构包统一进入 3.x 版本线，2.x 时代结束。
+
 ## 安装
 
 ```bash
@@ -23,6 +25,11 @@ 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}`],
 });
 ```
 
@@ -49,6 +56,9 @@ const exists = await has({ id: 'u-001' });
 
 // 删除
 await remove({ id: 'u-001' });
+
+// 按 tag 批量失效
+await cache.removeTag('users');
 ```
 
 ---
@@ -86,6 +96,31 @@ read(params)
     └─ false → write(params) → handler 回源 → SET/SETEX → 返回
 ```
 
+### Singleflight
+
+`singleflight` 使用 `@hile/redis-lock` 合并同一个 key 的并发 miss，避免热点 key 同时打到数据库。
+
+```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 参考
@@ -95,15 +130,20 @@ read(params)
 ```typescript
 function defineCache<T extends string = string, R = any>(
   key: T,
-  fn: (params: ExtractParams<T>) => Promise<Cache<R>>
+  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);
+  constructor(prefix: string, redis: Redis, options?: { locks?: RedisLock });
 
   loadCache<T extends string, R>(
     target: DefineCacheResult<T, R>
@@ -113,6 +153,8 @@ class RedisCache {
     remove(params: ExtractParams<T>): Promise<number>;
     has(params: ExtractParams<T>): Promise<boolean>;
   }>;
+
+  removeTag(tag: string): Promise<number>;
 }
 ```
 
@@ -122,6 +164,7 @@ class RedisCache {
 | `write` | `R \| undefined` | 强制执行回源并写入 Redis（data=undefined 则删除 key） |
 | `remove` | `number` | 删除缓存，返回 0/1 |
 | `has` | `boolean` | 检查 key 是否存在 |
+| `removeTag` | `number` | 删除某个 tag 下记录的所有缓存 key |
 
 ### Redis 中的 key 结构
 

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,12 +1,12 @@
 {
   "name": "@hile/cache",
-  "version": "2.0.7",
+  "version": "3.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"
+    "test": "vitest run && tsc -p tsconfig.typecheck.json"
   },
   "files": [
     "dist",
@@ -21,7 +21,8 @@
     "vitest": "^4.0.18"
   },
   "dependencies": {
+    "@hile/redis-lock": "^3.0.1",
     "ioredis": "^5.11.0"
   },
-  "gitHead": "a7615000fcb87e6bc0e573af760c814ec935bab2"
+  "gitHead": "88f52fb95743f86761778776aff23631fcf9d821"
 }