@jintianxiayu/cache-decorator 1.0.0 → 1.0.2

package/dist/core/cache-error.d.ts

@@ -0,0 +1,75 @@
+/** 异常缓存使用的固定 envelope 类型标识。 */
+declare const CACHE_ERROR_KIND = "@jintianxiayu/cache-decorator/error";
+/** 当前异常缓存 envelope 版本。 */
+declare const CACHE_ERROR_VERSION = 1;
+/**
+ * 异常缓存编解码器，将业务异常转换为可持久化 payload，并在命中时恢复异常语义。
+ */
+export interface CacheErrorCodec {
+    /**
+     * 编码本次业务异常。
+     * @param error 被装饰业务方法抛出或拒绝的值。
+     * @returns 可 JSON 往返的 payload。
+     */
+    encode(error: unknown): unknown;
+    /**
+     * 解码缓存中的 payload。
+     * @param payload 当前版本 envelope 中的 JSON payload。
+     * @returns 命中时应向调用方抛出的值。
+     */
+    decode(payload: unknown): unknown;
+}
+/**
+ * 业务异常持久化策略；提供该对象即显式启用异常缓存。
+ */
+export interface CacheErrorPolicy {
+    /** 独立于正常结果 TTL 的正整数秒级异常 TTL。 */
+    ttl: number;
+    /** 返回 true 时允许缓存本次业务异常；省略时接受全部业务异常。 */
+    shouldCache?: (error: unknown) => boolean;
+    /** 成对提供的异常编解码器；省略时使用标准 Error/JSON 值 codec。 */
+    codec?: CacheErrorCodec;
+}
+/** 装饰器求值时完成校验并绑定默认 codec 的内部策略。 */
+export interface NormalizedCacheErrorPolicy {
+    readonly ttl: number;
+    readonly shouldCache: ((error: unknown) => boolean) | undefined;
+    readonly codec: CacheErrorCodec;
+}
+/** Provider 中异常条目的版本化内容。 */
+export interface VersionedCacheErrorPayload {
+    readonly kind: typeof CACHE_ERROR_KIND;
+    readonly version: typeof CACHE_ERROR_VERSION;
+    readonly payload: unknown;
+}
+/**
+ * 在 legacy decorator 求值阶段校验外部异常策略并绑定默认 codec。
+ * @param policy 调用方传入的可选异常策略。
+ * @returns 禁用状态返回 undefined；启用状态返回不可变的内部策略快照。
+ * @throws TTL 非正有限整数时抛 RangeError；筛选器或 codec 结构非法时抛 TypeError。
+ */
+export declare function normalizeCacheErrorPolicy(policy: CacheErrorPolicy | undefined): NormalizedCacheErrorPolicy | undefined;
+/**
+ * 将业务异常编码为当前版本且已经 JSON 规范化的 envelope。
+ * @param error 本次业务方法产生的原始异常。
+ * @param policy 已在 decorator 求值阶段归一化的策略。
+ * @returns 可直接交给任意 CacheProvider 的版本化异常内容。
+ * @throws codec 或 JSON 往返失败时传播错误。
+ */
+export declare function encodeCacheError(error: unknown, policy: NormalizedCacheErrorPolicy): VersionedCacheErrorPayload;
+/**
+ * 判断 Provider 返回的 error 字段是否为当前版本 envelope。
+ * @param value Provider 返回的 error 字段。
+ * @returns kind、version 与 payload 完整匹配当前协议时返回 true。
+ */
+export declare function isCurrentCacheErrorPayload(value: unknown): value is VersionedCacheErrorPayload;
+/**
+ * 使用当前策略解码异常，并拒绝异步或不能安全表示的非 Error 结果。
+ * @param envelope 已识别为当前版本的异常内容。
+ * @param policy 当前装饰器启用的异常策略。
+ * @returns codec 产生的同一个异常结果。
+ * @throws codec 抛错或返回不受支持的结果时抛出。
+ */
+export declare function decodeCacheError(envelope: VersionedCacheErrorPayload, policy: NormalizedCacheErrorPolicy): unknown;
+export {};
+//# sourceMappingURL=cache-error.d.ts.map

package/dist/core/cache-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-error.d.ts","sourceRoot":"","sources":["../../src/core/cache-error.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,QAAA,MAAM,gBAAgB,wCAAwC,CAAC;AAE/D,0BAA0B;AAC1B,QAAA,MAAM,mBAAmB,IAAI,CAAC;AAE9B;;GAEG;AACH,MAAM,WAAW,eAAe;IAC5B;;;;OAIG;IACH,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;IAEhC;;;;OAIG;IACH,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC7B,gCAAgC;IAChC,GAAG,EAAE,MAAM,CAAC;IAEZ,uCAAuC;IACvC,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;IAE1C,8CAA8C;IAC9C,KAAK,CAAC,EAAE,eAAe,CAAC;CAC3B;AAED,mCAAmC;AACnC,MAAM,WAAW,0BAA0B;IACvC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,GAAG,SAAS,CAAC;IAChE,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;CACnC;AAED,4BAA4B;AAC5B,MAAM,WAAW,0BAA0B;IACvC,QAAQ,CAAC,IAAI,EAAE,OAAO,gBAAgB,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,OAAO,mBAAmB,CAAC;IAC7C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC7B;AA0GD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACrC,MAAM,EAAE,gBAAgB,GAAG,SAAS,GACrC,0BAA0B,GAAG,SAAS,CAqBxC;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,0BAA0B,GAAG,0BAA0B,CAO/G;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,0BAA0B,CAO9F;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,0BAA0B,EAAE,MAAM,EAAE,0BAA0B,GAAG,OAAO,CAOlH"}

package/dist/core/cache-error.js

@@ -0,0 +1,168 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeCacheErrorPolicy = normalizeCacheErrorPolicy;
+exports.encodeCacheError = encodeCacheError;
+exports.isCurrentCacheErrorPayload = isCurrentCacheErrorPayload;
+exports.decodeCacheError = decodeCacheError;
+/** 异常缓存使用的固定 envelope 类型标识。 */
+const CACHE_ERROR_KIND = '@jintianxiayu/cache-decorator/error';
+/** 当前异常缓存 envelope 版本。 */
+const CACHE_ERROR_VERSION = 1;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function isPlainObject(value) {
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+/**
+ * 递归校验值是否可以无损表示为 JSON，拒绝 JSON.stringify 会静默丢弃或改写的结构。
+ * @param value 待校验的 payload 或 envelope 节点。
+ * @param ancestors 当前递归路径上的对象，用于识别循环引用而不拒绝普通重复引用。
+ * @returns 无返回值。
+ * @throws 值包含非 JSON 类型、非有限数、稀疏数组、symbol key、特殊对象或循环引用时抛出 TypeError。
+ */
+function validateJsonValue(value, ancestors) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean') {
+        return;
+    }
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value)) {
+            throw new TypeError('Cache error payload numbers must be finite');
+        }
+        return;
+    }
+    if (!isRecord(value)) {
+        throw new TypeError('Cache error payload must contain only JSON-compatible values');
+    }
+    if ((!Array.isArray(value) && !isPlainObject(value)) || Object.getOwnPropertySymbols(value).length > 0) {
+        throw new TypeError('Cache error payload must use JSON objects and arrays');
+    }
+    if (ancestors.has(value)) {
+        throw new TypeError('Cache error payload must not contain circular references');
+    }
+    ancestors.add(value);
+    try {
+        if (Array.isArray(value)) {
+            for (let index = 0; index < value.length; index += 1) {
+                if (!Object.prototype.hasOwnProperty.call(value, index)) {
+                    throw new TypeError('Cache error payload arrays must not be sparse');
+                }
+                validateJsonValue(value[index], ancestors);
+            }
+            return;
+        }
+        for (const child of Object.values(value)) {
+            validateJsonValue(child, ancestors);
+        }
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+/**
+ * 校验并执行一次 JSON stringify/parse，以统一 Memory、Redis 与自定义 Provider 得到的表示。
+ * @param value codec 产生的完整版本化 envelope。
+ * @returns JSON 往返后的独立规范化值。
+ * @throws 无法安全 JSON 往返时抛出 TypeError 或底层序列化错误。
+ */
+function normalizeJsonValue(value) {
+    validateJsonValue(value, new Set());
+    const serialized = JSON.stringify(value);
+    if (typeof serialized !== 'string') {
+        throw new TypeError('Cache error payload must serialize to JSON');
+    }
+    return JSON.parse(serialized);
+}
+const defaultCacheErrorCodec = Object.freeze({
+    encode(error) {
+        if (error instanceof Error) {
+            return { type: 'error', name: error.name, message: error.message };
+        }
+        return { type: 'value', value: error };
+    },
+    decode(payload) {
+        if (!isRecord(payload)) {
+            throw new TypeError('Default cache error payload must be an object');
+        }
+        if (payload.type === 'error' && typeof payload.name === 'string' && typeof payload.message === 'string') {
+            const error = new Error(payload.message);
+            error.name = payload.name;
+            return error;
+        }
+        if (payload.type === 'value' && Object.prototype.hasOwnProperty.call(payload, 'value')) {
+            return payload.value;
+        }
+        throw new TypeError('Default cache error payload has an unsupported shape');
+    },
+});
+/**
+ * 在 legacy decorator 求值阶段校验外部异常策略并绑定默认 codec。
+ * @param policy 调用方传入的可选异常策略。
+ * @returns 禁用状态返回 undefined；启用状态返回不可变的内部策略快照。
+ * @throws TTL 非正有限整数时抛 RangeError；筛选器或 codec 结构非法时抛 TypeError。
+ */
+function normalizeCacheErrorPolicy(policy) {
+    if (policy === undefined) {
+        return undefined;
+    }
+    if (!isRecord(policy)) {
+        throw new TypeError('Cache error policy must be an object');
+    }
+    const ttl = policy.ttl;
+    const shouldCache = policy.shouldCache;
+    const configuredCodec = policy.codec;
+    if (typeof ttl !== 'number' || !Number.isFinite(ttl) || !Number.isInteger(ttl) || ttl < 1) {
+        throw new RangeError('Cache error TTL must be a positive finite integer');
+    }
+    if (shouldCache !== undefined && typeof shouldCache !== 'function') {
+        throw new TypeError('Cache error shouldCache must be a function');
+    }
+    const codec = configuredCodec === undefined ? defaultCacheErrorCodec : configuredCodec;
+    if (!isRecord(codec) || typeof codec.encode !== 'function' || typeof codec.decode !== 'function') {
+        throw new TypeError('Cache error codec must provide encode and decode functions');
+    }
+    return Object.freeze({ ttl, shouldCache, codec });
+}
+/**
+ * 将业务异常编码为当前版本且已经 JSON 规范化的 envelope。
+ * @param error 本次业务方法产生的原始异常。
+ * @param policy 已在 decorator 求值阶段归一化的策略。
+ * @returns 可直接交给任意 CacheProvider 的版本化异常内容。
+ * @throws codec 或 JSON 往返失败时传播错误。
+ */
+function encodeCacheError(error, policy) {
+    const envelope = {
+        kind: CACHE_ERROR_KIND,
+        version: CACHE_ERROR_VERSION,
+        payload: policy.codec.encode(error),
+    };
+    return normalizeJsonValue(envelope);
+}
+/**
+ * 判断 Provider 返回的 error 字段是否为当前版本 envelope。
+ * @param value Provider 返回的 error 字段。
+ * @returns kind、version 与 payload 完整匹配当前协议时返回 true。
+ */
+function isCurrentCacheErrorPayload(value) {
+    return (isRecord(value) &&
+        value.kind === CACHE_ERROR_KIND &&
+        value.version === CACHE_ERROR_VERSION &&
+        Object.prototype.hasOwnProperty.call(value, 'payload'));
+}
+/**
+ * 使用当前策略解码异常，并拒绝异步或不能安全表示的非 Error 结果。
+ * @param envelope 已识别为当前版本的异常内容。
+ * @param policy 当前装饰器启用的异常策略。
+ * @returns codec 产生的同一个异常结果。
+ * @throws codec 抛错或返回不受支持的结果时抛出。
+ */
+function decodeCacheError(envelope, policy) {
+    const decoded = policy.codec.decode(envelope.payload);
+    if (decoded instanceof Error) {
+        return decoded;
+    }
+    validateJsonValue(decoded, new Set());
+    return decoded;
+}
+//# sourceMappingURL=cache-error.js.map

package/dist/core/cache-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-error.js","sourceRoot":"","sources":["../../src/core/cache-error.ts"],"names":[],"mappings":";;AAmKA,8DAuBC;AASD,4CAOC;AAOD,gEAOC;AASD,4CAOC;AAxOD,+BAA+B;AAC/B,MAAM,gBAAgB,GAAG,qCAAqC,CAAC;AAE/D,0BAA0B;AAC1B,MAAM,mBAAmB,GAAG,CAAC,CAAC;AA4D9B,SAAS,QAAQ,CAAC,KAAc;IAC5B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC;AACvD,CAAC;AAED,SAAS,aAAa,CAAC,KAAa;IAChC,MAAM,SAAS,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAY,CAAC;IAC1D,OAAO,SAAS,KAAK,MAAM,CAAC,SAAS,IAAI,SAAS,KAAK,IAAI,CAAC;AAChE,CAAC;AAED;;;;;;GAMG;AACH,SAAS,iBAAiB,CAAC,KAAc,EAAE,SAAsB;IAC7D,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,SAAS,EAAE,CAAC;QAC5E,OAAO;IACX,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC5B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,SAAS,CAAC,4CAA4C,CAAC,CAAC;QACtE,CAAC;QACD,OAAO;IACX,CAAC;IACD,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACnB,MAAM,IAAI,SAAS,CAAC,8DAA8D,CAAC,CAAC;IACxF,CAAC;IACD,IAAI,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,IAAI,MAAM,CAAC,qBAAqB,CAAC,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrG,MAAM,IAAI,SAAS,CAAC,sDAAsD,CAAC,CAAC;IAChF,CAAC;IACD,IAAI,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,SAAS,CAAC,0DAA0D,CAAC,CAAC;IACpF,CAAC;IAED,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACrB,IAAI,CAAC;QACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACvB,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;gBACnD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,CAAC;oBACtD,MAAM,IAAI,SAAS,CAAC,+CAA+C,CAAC,CAAC;gBACzE,CAAC;gBACD,iBAAiB,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC,CAAC;YAC/C,CAAC;YACD,OAAO;QACX,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;YACvC,iBAAiB,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;QACxC,CAAC;IACL,CAAC;YAAS,CAAC;QACP,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC5B,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,SAAS,kBAAkB,CAAC,KAAc;IACtC,iBAAiB,CAAC,KAAK,EAAE,IAAI,GAAG,EAAU,CAAC,CAAC;IAC5C,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IACzC,IAAI,OAAO,UAAU,KAAK,QAAQ,EAAE,CAAC;QACjC,MAAM,IAAI,SAAS,CAAC,4CAA4C,CAAC,CAAC;IACtE,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,UAAU,CAAY,CAAC;AAC7C,CAAC;AAED,MAAM,sBAAsB,GAAoB,MAAM,CAAC,MAAM,CAAC;IAC1D,MAAM,CAAC,KAAc;QACjB,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;YACzB,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC;QACvE,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IAC3C,CAAC;IACD,MAAM,CAAC,OAAgB;QACnB,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YACrB,MAAM,IAAI,SAAS,CAAC,+CAA+C,CAAC,CAAC;QACzE,CAAC;QACD,IAAI,OAAO,CAAC,IAAI,KAAK,OAAO,IAAI,OAAO,OAAO,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;YACtG,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;YACzC,KAAK,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;YAC1B,OAAO,KAAK,CAAC;QACjB,CAAC;QACD,IAAI,OAAO,CAAC,IAAI,KAAK,OAAO,IAAI,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,CAAC;YACrF,OAAO,OAAO,CAAC,KAAK,CAAC;QACzB,CAAC;QACD,MAAM,IAAI,SAAS,CAAC,sDAAsD,CAAC,CAAC;IAChF,CAAC;CACJ,CAAC,CAAC;AAEH;;;;;GAKG;AACH,SAAgB,yBAAyB,CACrC,MAAoC;IAEpC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACvB,OAAO,SAAS,CAAC;IACrB,CAAC;IACD,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QACpB,MAAM,IAAI,SAAS,CAAC,sCAAsC,CAAC,CAAC;IAChE,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC;IACvB,MAAM,WAAW,GAAG,MAAM,CAAC,WAAW,CAAC;IACvC,MAAM,eAAe,GAAG,MAAM,CAAC,KAAK,CAAC;IACrC,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,EAAE,CAAC;QACxF,MAAM,IAAI,UAAU,CAAC,mDAAmD,CAAC,CAAC;IAC9E,CAAC;IACD,IAAI,WAAW,KAAK,SAAS,IAAI,OAAO,WAAW,KAAK,UAAU,EAAE,CAAC;QACjE,MAAM,IAAI,SAAS,CAAC,4CAA4C,CAAC,CAAC;IACtE,CAAC;IACD,MAAM,KAAK,GAAG,eAAe,KAAK,SAAS,CAAC,CAAC,CAAC,sBAAsB,CAAC,CAAC,CAAC,eAAe,CAAC;IACvF,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,OAAO,KAAK,CAAC,MAAM,KAAK,UAAU,IAAI,OAAO,KAAK,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;QAC/F,MAAM,IAAI,SAAS,CAAC,4DAA4D,CAAC,CAAC;IACtF,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,CAAC;AACtD,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,gBAAgB,CAAC,KAAc,EAAE,MAAkC;IAC/E,MAAM,QAAQ,GAAG;QACb,IAAI,EAAE,gBAAgB;QACtB,OAAO,EAAE,mBAAmB;QAC5B,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC;KACtC,CAAC;IACF,OAAO,kBAAkB,CAAC,QAAQ,CAA+B,CAAC;AACtE,CAAC;AAED;;;;GAIG;AACH,SAAgB,0BAA0B,CAAC,KAAc;IACrD,OAAO,CACH,QAAQ,CAAC,KAAK,CAAC;QACf,KAAK,CAAC,IAAI,KAAK,gBAAgB;QAC/B,KAAK,CAAC,OAAO,KAAK,mBAAmB;QACrC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,KAAK,EAAE,SAAS,CAAC,CACzD,CAAC;AACN,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,gBAAgB,CAAC,QAAoC,EAAE,MAAkC;IACrG,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IACtD,IAAI,OAAO,YAAY,KAAK,EAAE,CAAC;QAC3B,OAAO,OAAO,CAAC;IACnB,CAAC;IACD,iBAAiB,CAAC,OAAO,EAAE,IAAI,GAAG,EAAU,CAAC,CAAC;IAC9C,OAAO,OAAO,CAAC;AACnB,CAAC"}

package/dist/core/cache-logger.d.ts

@@ -1,4 +1,4 @@
-export type CacheLogEvent = 'cache.pending_hit' | 'cache.hit' | 'cache.miss' | 'cache.write_dispatched' | 'cache.evict_dispatched' | 'cache.evict_completed' | 'cache.key_fallback' | 'cache.evict_skipped' | 'cache.operation_failed';
+export type CacheLogEvent = 'cache.pending_hit' | 'cache.hit' | 'cache.miss' | 'cache.write_dispatched' | 'cache.error_cache_skipped' | 'cache.error_cache_failed' | 'cache.evict_dispatched' | 'cache.evict_completed' | 'cache.key_fallback' | 'cache.evict_skipped' | 'cache.operation_failed';
 /** 缓存日志只接受与决策相关的稳定字段，避免业务数据和 cache key 被意外带入输出。 */
 export interface CacheLogContext {
     readonly cacheName: string;
@@ -6,7 +6,8 @@ export interface CacheLogContext {
     readonly providerName: string;
     readonly entryType?: 'value' | 'error';
     readonly scope?: 'key' | 'allEntries';
-    readonly reason?: 'resolver_error' | 'business_error';
+    readonly reason?: 'resolver_error' | 'business_error' | 'disabled' | 'predicate_rejected' | 'legacy_entry' | 'disabled_entry';
+    readonly phase?: 'predicate' | 'encode' | 'decode';
     readonly operation?: 'provider_resolution' | 'read' | 'write' | 'evict';
     readonly error?: unknown;
 }

package/dist/core/cache-logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cache-logger.d.ts","sourceRoot":"","sources":["../../src/core/cache-logger.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,aAAa,GACnB,mBAAmB,GACnB,WAAW,GACX,YAAY,GACZ,wBAAwB,GACxB,wBAAwB,GACxB,uBAAuB,GACvB,oBAAoB,GACpB,qBAAqB,GACrB,wBAAwB,CAAC;AAS/B,mDAAmD;AACnD,MAAM,WAAW,eAAe;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;IACvC,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,YAAY,CAAC;IACtC,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,GAAG,gBAAgB,CAAC;IACtD,QAAQ,CAAC,SAAS,CAAC,EAAE,qBAAqB,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;IACxE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC5B;AA8CD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,eAAe,GAAG,IAAI,CAMlF;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAK3E"}
+{"version":3,"file":"cache-logger.d.ts","sourceRoot":"","sources":["../../src/core/cache-logger.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,aAAa,GACnB,mBAAmB,GACnB,WAAW,GACX,YAAY,GACZ,wBAAwB,GACxB,2BAA2B,GAC3B,0BAA0B,GAC1B,wBAAwB,GACxB,uBAAuB,GACvB,oBAAoB,GACpB,qBAAqB,GACrB,wBAAwB,CAAC;AAS/B,mDAAmD;AACnD,MAAM,WAAW,eAAe;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;IACvC,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,YAAY,CAAC;IACtC,QAAQ,CAAC,MAAM,CAAC,EACV,gBAAgB,GAChB,gBAAgB,GAChB,UAAU,GACV,oBAAoB,GACpB,cAAc,GACd,gBAAgB,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,GAAG,QAAQ,GAAG,QAAQ,CAAC;IACnD,QAAQ,CAAC,SAAS,CAAC,EAAE,qBAAqB,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;IACxE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC5B;AAgDD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,eAAe,GAAG,IAAI,CAMlF;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAK3E"}

package/dist/core/cache-logger.js

@@ -10,6 +10,8 @@ const CACHE_LOG_DEFINITIONS = {
     'cache.hit': { level: 'debug', message: 'Cache entry hit' },
     'cache.miss': { level: 'debug', message: 'Cache entry missed' },
     'cache.write_dispatched': { level: 'debug', message: 'Cache write dispatched' },
+    'cache.error_cache_skipped': { level: 'debug', message: 'Cache error entry skipped' },
+    'cache.error_cache_failed': { level: 'warn', message: 'Cache error policy failed' },
     'cache.evict_dispatched': { level: 'debug', message: 'Cache eviction dispatched' },
     'cache.evict_completed': { level: 'debug', message: 'Cache eviction completed' },
     'cache.key_fallback': { level: 'warn', message: 'Cache key resolver failed; using default key' },

package/dist/core/cache-logger.js.map

@@ -1 +1 @@
-{"version":3,"file":"cache-logger.js","sourceRoot":"","sources":["../../src/core/cache-logger.ts"],"names":[],"mappings":";;AAqFA,sCAMC;AAQD,gDAKC;AAxGD,iDAA2E;AAE3E,MAAM,iBAAiB,GAAG,+BAA+B,CAAC;AAgC1D,2CAA2C;AAC3C,MAAM,qBAAqB,GAAwD;IAC/E,mBAAmB,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,8BAA8B,EAAE;IAChF,WAAW,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE;IAC3D,YAAY,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,oBAAoB,EAAE;IAC/D,wBAAwB,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,wBAAwB,EAAE;IAC/E,wBAAwB,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,2BAA2B,EAAE;IAClF,uBAAuB,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,0BAA0B,EAAE;IAChF,oBAAoB,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,8CAA8C,EAAE;IAChG,qBAAqB,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,+CAA+C,EAAE;IAClG,wBAAwB,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,wBAAwB,EAAE;CAClF,CAAC;AAEF,IAAI,WAAwC,CAAC;AAE7C,SAAS,cAAc;IACnB,WAAW,KAAK,sBAAa,CAAC,SAAS,CAAC,iBAAiB,CAAC,CAAC;IAC3D,OAAO,WAAW,CAAC;AACvB,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,aAAa,CAClB,MAAuB,EACvB,UAA8B,EAC9B,QAA6D;IAE7D,IAAI,UAAU,CAAC,KAAK,KAAK,OAAO,EAAE,CAAC;QAC/B,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QAC3C,OAAO;IACX,CAAC;IACD,IAAI,UAAU,CAAC,KAAK,KAAK,MAAM,EAAE,CAAC;QAC9B,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QAC1C,OAAO;IACX,CAAC;IACD,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,aAAa,CAAC,KAAoB,EAAE,OAAwB;IACxE,IAAI,CAAC;QACD,aAAa,CAAC,cAAc,EAAE,EAAE,qBAAqB,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACzF,CAAC;IAAC,OAAO,MAAM,EAAE,CAAC;QACd,OAAO;IACX,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,SAAgB,kBAAkB,CAAC,YAAgC;IAC/D,IAAI,YAAY,KAAK,SAAS,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1D,OAAO,SAAS,CAAC;IACrB,CAAC;IACD,OAAO,YAAY,CAAC;AACxB,CAAC"}
+{"version":3,"file":"cache-logger.js","sourceRoot":"","sources":["../../src/core/cache-logger.ts"],"names":[],"mappings":";;AAgGA,sCAMC;AAQD,gDAKC;AAnHD,iDAA2E;AAE3E,MAAM,iBAAiB,GAAG,+BAA+B,CAAC;AAyC1D,2CAA2C;AAC3C,MAAM,qBAAqB,GAAwD;IAC/E,mBAAmB,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,8BAA8B,EAAE;IAChF,WAAW,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE;IAC3D,YAAY,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,oBAAoB,EAAE;IAC/D,wBAAwB,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,wBAAwB,EAAE;IAC/E,2BAA2B,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,2BAA2B,EAAE;IACrF,0BAA0B,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,2BAA2B,EAAE;IACnF,wBAAwB,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,2BAA2B,EAAE;IAClF,uBAAuB,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,0BAA0B,EAAE;IAChF,oBAAoB,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,8CAA8C,EAAE;IAChG,qBAAqB,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,+CAA+C,EAAE;IAClG,wBAAwB,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,wBAAwB,EAAE;CAClF,CAAC;AAEF,IAAI,WAAwC,CAAC;AAE7C,SAAS,cAAc;IACnB,WAAW,KAAK,sBAAa,CAAC,SAAS,CAAC,iBAAiB,CAAC,CAAC;IAC3D,OAAO,WAAW,CAAC;AACvB,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,aAAa,CAClB,MAAuB,EACvB,UAA8B,EAC9B,QAA6D;IAE7D,IAAI,UAAU,CAAC,KAAK,KAAK,OAAO,EAAE,CAAC;QAC/B,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QAC3C,OAAO;IACX,CAAC;IACD,IAAI,UAAU,CAAC,KAAK,KAAK,MAAM,EAAE,CAAC;QAC9B,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QAC1C,OAAO;IACX,CAAC;IACD,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,aAAa,CAAC,KAAoB,EAAE,OAAwB;IACxE,IAAI,CAAC;QACD,aAAa,CAAC,cAAc,EAAE,EAAE,qBAAqB,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACzF,CAAC;IAAC,OAAO,MAAM,EAAE,CAAC;QACd,OAAO;IACX,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,SAAgB,kBAAkB,CAAC,YAAgC;IAC/D,IAAI,YAAY,KAAK,SAAS,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1D,OAAO,SAAS,CAAC;IACrB,CAAC;IACD,OAAO,YAAY,CAAC;AACxB,CAAC"}

package/dist/decorators/cache-evict.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cache-evict.d.ts","sourceRoot":"","sources":["../../src/decorators/cache-evict.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAoB,YAAY,EAAE,MAAM,SAAS,CAAC;AAE9D;;GAEG;AACH,MAAM,WAAW,iBAAkB,SAAQ,IAAI,CAAC,YAAY,EAAE,KAAK,CAAC;IAChE;;OAEG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACzB;AA8DD;;;;;GAKG;AACH,wBAAgB,UAAU,CACtB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,iBAAiB,GAC5B,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,kBAAkB,KAAK,IAAI,CAoCjF;AAED,OAAO,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAC"}
+{"version":3,"file":"cache-evict.d.ts","sourceRoot":"","sources":["../../src/decorators/cache-evict.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAoB,YAAY,EAAE,MAAM,SAAS,CAAC;AAE9D;;GAEG;AACH,MAAM,WAAW,iBAAkB,SAAQ,IAAI,CAAC,YAAY,EAAE,KAAK,CAAC;IAChE;;OAEG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACzB;AAmED;;;;;GAKG;AACH,wBAAgB,UAAU,CACtB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,iBAAiB,GAC5B,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,kBAAkB,KAAK,IAAI,CAuCjF;AAED,OAAO,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAC"}

package/dist/decorators/cache-evict.js

@@ -28,11 +28,10 @@ function resolveCacheKey(keyResolver, args, logContext) {
     }
 }
 /**
- * 获取淘汰操作使用的 Provider，并在解析失败时记录原始注册表错误。
+ * 获取淘汰操作使用的 Provider，并把解析失败转换为缓存旁路。
  * @param providerName decorator 配置中的 Provider 名称。
  * @param logContext 当前方法的稳定日志上下文。
- * @returns 已注册的缓存 Provider。
- * @throws Provider 注册表抛出的原始错误。
+ * @returns 已注册的缓存 Provider；解析失败时返回 undefined。
  */
 function resolveCacheProvider(providerName, logContext) {
     try {
@@ -40,26 +39,29 @@ function resolveCacheProvider(providerName, logContext) {
     }
     catch (error) {
         (0, cache_logger_1.logCacheEvent)('cache.operation_failed', { ...logContext, operation: 'provider_resolution', error });
-        throw error;
+        return undefined;
     }
 }
 /**
- * 保持 fire-and-forget 语义发起单 key 删除，只处理调用当下可观察的同步失败。
+ * 保持 fire-and-forget 语义发起单 key 删除，并消费同步或异步 Provider 失败。
  * @param provider 当前淘汰使用的 Provider。
  * @param cacheKey 待删除的完整 key；不会进入日志元数据。
  * @param logContext 当前方法的稳定日志上下文。
- * @returns 无返回值；异步删除 Promise 不会被等待或消费。
- * @throws Provider delete 同步抛出的原始错误。
+ * @returns 无返回值；删除失败仅记录日志，不影响业务结果。
  */
 function dispatchCacheDelete(provider, cacheKey, logContext) {
+    let operation;
     try {
-        provider.delete(cacheKey);
+        operation = provider.delete(cacheKey);
     }
     catch (error) {
         (0, cache_logger_1.logCacheEvent)('cache.operation_failed', { ...logContext, operation: 'evict', error });
-        throw error;
+        return;
     }
     (0, cache_logger_1.logCacheEvent)('cache.evict_dispatched', { ...logContext, scope: 'key' });
+    void Promise.resolve(operation).catch((error) => {
+        (0, cache_logger_1.logCacheEvent)('cache.operation_failed', { ...logContext, operation: 'evict', error });
+    });
 }
 /**
  * 缓存清除装饰器
@@ -85,13 +87,16 @@ function CacheEvict(cacheName, options) {
                 throw error;
             }
             const provider = resolveCacheProvider(options?.providerName, logContext);
+            if (provider === undefined) {
+                return result;
+            }
             if (options?.allEntries) {
                 try {
                     await provider.deleteByPattern(cacheName + '*');
                 }
                 catch (error) {
                     (0, cache_logger_1.logCacheEvent)('cache.operation_failed', { ...logContext, operation: 'evict', error });
-                    throw error;
+                    return result;
                 }
                 (0, cache_logger_1.logCacheEvent)('cache.evict_completed', { ...logContext, scope: 'allEntries' });
             }

package/dist/decorators/cache-evict.js.map

@@ -1 +1 @@
-{"version":3,"file":"cache-evict.js","sourceRoot":"","sources":["../../src/decorators/cache-evict.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cache-evict.js","sourceRoot":"","sources":["../../src/decorators/cache-evict.ts"],"names":[],"mappings":"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"}

package/dist/decorators/cache.d.ts

@@ -1,4 +1,5 @@
 import 'reflect-metadata';
+import { type CacheErrorCodec, type CacheErrorPolicy } from '../core/cache-error';
 /**
  * 缓存 key 解析器类型
  * - null: 使用自动生成逻辑
@@ -6,6 +7,7 @@ import 'reflect-metadata';
  * - function: 接收方法参数数组，返回自定义字符串
  */
 export type CacheKeyResolver = null | string | ((...args: unknown[]) => string);
+export type { CacheErrorCodec, CacheErrorPolicy };
 /**
  * @Cache 装饰器配置项
  */
@@ -25,6 +27,10 @@ export interface CacheOptions {
      * - function: 调用函数后使用 KeyBuilder.build(cacheName, [result])
      */
     key?: CacheKeyResolver;
+    /**
+     * 业务异常缓存策略；省略时不向 Provider 持久化业务异常。
+     */
+    errorCache?: CacheErrorPolicy;
 }
 /**
  * 缓存装饰器

package/dist/decorators/cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/decorators/cache.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAO1B;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,IAAI,GAAG,MAAM,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,MAAM,CAAC,CAAC;AAEhF;;GAEG;AACH,MAAM,WAAW,YAAY;IACzB;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,gBAAgB,CAAC;CAC1B;AA0FD;;;;;GAKG;AACH,wBAAgB,KAAK,CACjB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,YAAY,GACvB,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,kBAAkB,KAAK,IAAI,CAiEjF;AAED,OAAO,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAC"}
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/decorators/cache.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAC1B,OAAO,EAKH,KAAK,eAAe,EACpB,KAAK,gBAAgB,EAExB,MAAM,qBAAqB,CAAC;AAO7B;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,IAAI,GAAG,MAAM,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,MAAM,CAAC,CAAC;AAEhF,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,CAAC;AAElD;;GAEG;AACH,MAAM,WAAW,YAAY;IACzB;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,gBAAgB,CAAC;IAEvB;;OAEG;IACH,UAAU,CAAC,EAAE,gBAAgB,CAAC;CACjC;AA6LD;;;;;GAKG;AACH,wBAAgB,KAAK,CACjB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,YAAY,GACvB,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,kBAAkB,KAAK,IAAI,CAsEjF;AAED,OAAO,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAC"}

package/dist/decorators/cache.js

@@ -3,17 +3,17 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.CacheProviderRegistry = void 0;
 exports.Cache = Cache;
 require("reflect-metadata");
+const cache_error_1 = require("../core/cache-error");
 const cache_logger_1 = require("../core/cache-logger");
 const cache_provider_registry_1 = require("../core/cache-provider-registry");
 const key_builder_1 = require("../core/key-builder");
 const pending_cache_1 = require("../core/pending-cache");
 const pendingCache = new pending_cache_1.PendingCache();
 /**
- * 获取配置指向的缓存 Provider，并在解析失败时记录原始错误。
+ * 获取配置指向的缓存 Provider，并把解析失败转换为缓存旁路。
  * @param providerName decorator 配置中的 Provider 名称。
  * @param logContext 当前方法的稳定日志上下文。
- * @returns 已注册的缓存 Provider。
- * @throws Provider 注册表抛出的原始错误。
+ * @returns 已注册的缓存 Provider；解析失败时返回 undefined。
  */
 function resolveCacheProvider(providerName, logContext) {
     try {
@@ -21,24 +21,98 @@ function resolveCacheProvider(providerName, logContext) {
     }
     catch (error) {
         (0, cache_logger_1.logCacheEvent)('cache.operation_failed', { ...logContext, operation: 'provider_resolution', error });
-        throw error;
+        return undefined;
     }
 }
 /**
- * 保持 fire-and-forget 语义提交缓存写入，仅捕获调用当下可观察的同步失败。
+ * 保持 fire-and-forget 语义提交缓存写入，并消费同步或异步 Provider 失败。
  * @param request 写入所需 Provider、entry 和无业务数据日志上下文。
- * @returns 无返回值；异步写入 Promise 不会被等待或消费。
- * @throws Provider set 同步抛出的原始错误。
+ * @returns 无返回值；写入失败仅记录日志，不影响业务结果。
  */
 function dispatchCacheWrite(request) {
+    let operation;
     try {
-        request.provider.set(request.cacheKey, request.entry, request.ttl);
+        operation = request.provider.set(request.cacheKey, request.entry, request.ttl);
     }
     catch (error) {
         (0, cache_logger_1.logCacheEvent)('cache.operation_failed', { ...request.logContext, operation: 'write', error });
-        throw error;
+        return;
     }
     (0, cache_logger_1.logCacheEvent)('cache.write_dispatched', { ...request.logContext, entryType: request.entryType });
+    void Promise.resolve(operation).catch((error) => {
+        (0, cache_logger_1.logCacheEvent)('cache.operation_failed', { ...request.logContext, operation: 'write', error });
+    });
+}
+function isErrorCacheEntry(entry) {
+    return typeof entry === 'object' && entry !== null && 'error' in entry;
+}
+/**
+ * 按当前异常策略分类 Provider 条目，并只把可成功解码的当前版本异常视为命中。
+ * @param entry Provider 返回的缓存联合条目。
+ * @param errorPolicy 当前装饰器归一化后的异常策略。
+ * @param logContext 当前方法的稳定日志上下文。
+ * @returns value/error 命中结果，或需要继续业务流程的 miss。
+ */
+function resolveCachedEntry(entry, errorPolicy, logContext) {
+    if (!isErrorCacheEntry(entry)) {
+        (0, cache_logger_1.logCacheEvent)('cache.hit', { ...logContext, entryType: 'value' });
+        return { type: 'value', value: entry.value };
+    }
+    if (!(0, cache_error_1.isCurrentCacheErrorPayload)(entry.error)) {
+        (0, cache_logger_1.logCacheEvent)('cache.error_cache_skipped', { ...logContext, reason: 'legacy_entry' });
+        return { type: 'miss' };
+    }
+    if (errorPolicy === undefined) {
+        (0, cache_logger_1.logCacheEvent)('cache.error_cache_skipped', { ...logContext, reason: 'disabled_entry' });
+        return { type: 'miss' };
+    }
+    try {
+        const error = (0, cache_error_1.decodeCacheError)(entry.error, errorPolicy);
+        (0, cache_logger_1.logCacheEvent)('cache.hit', { ...logContext, entryType: 'error' });
+        return { type: 'error', error };
+    }
+    catch (_error) {
+        (0, cache_logger_1.logCacheEvent)('cache.error_cache_failed', { ...logContext, phase: 'decode' });
+        return { type: 'miss' };
+    }
+}
+/**
+ * 按固定顺序评估筛选器、编码异常并发起独立 TTL 写入，任何策略失败都保留原业务异常。
+ * @param request 本次业务异常、当前策略、Provider、完整 key 与稳定日志上下文。
+ * @returns 无返回值。
+ */
+function handleBusinessError(request) {
+    const { error, errorPolicy, provider, cacheKey, logContext } = request;
+    if (errorPolicy === undefined) {
+        (0, cache_logger_1.logCacheEvent)('cache.error_cache_skipped', { ...logContext, reason: 'disabled' });
+        return;
+    }
+    if (errorPolicy.shouldCache !== undefined) {
+        let accepted;
+        try {
+            accepted = errorPolicy.shouldCache(error);
+            if (typeof accepted !== 'boolean') {
+                throw new TypeError('Cache error shouldCache must return a boolean');
+            }
+        }
+        catch (_error) {
+            (0, cache_logger_1.logCacheEvent)('cache.error_cache_failed', { ...logContext, phase: 'predicate' });
+            return;
+        }
+        if (!accepted) {
+            (0, cache_logger_1.logCacheEvent)('cache.error_cache_skipped', { ...logContext, reason: 'predicate_rejected' });
+            return;
+        }
+    }
+    let entry;
+    try {
+        entry = { error: (0, cache_error_1.encodeCacheError)(error, errorPolicy) };
+    }
+    catch (_error) {
+        (0, cache_logger_1.logCacheEvent)('cache.error_cache_failed', { ...logContext, phase: 'encode' });
+        return;
+    }
+    dispatchCacheWrite({ provider, cacheKey, entry, entryType: 'error', ttl: errorPolicy.ttl, logContext });
 }
 /**
  * 解析缓存 key
@@ -69,6 +143,7 @@ function resolveCacheKey(keyResolver, args, logContext) {
  * @param options 配置项
  */
 function Cache(cacheName, options) {
+    const errorPolicy = (0, cache_error_1.normalizeCacheErrorPolicy)(options?.errorCache);
     return function (_target, propertyKey, descriptor) {
         const originalMethod = descriptor.value;
         const logContext = {
@@ -85,46 +160,48 @@ function Cache(cacheName, options) {
             }
             const promise = (async () => {
                 const provider = resolveCacheProvider(options?.providerName, logContext);
-                let cached;
+                if (provider === undefined) {
+                    return (await originalMethod.apply(this, args));
+                }
+                let lookupResult;
                 try {
-                    cached = await provider.get(cacheKey);
+                    const entry = await provider.get(cacheKey);
+                    lookupResult = entry === undefined ? { type: 'miss', provider } : { type: 'hit', provider, entry };
                 }
                 catch (error) {
                     (0, cache_logger_1.logCacheEvent)('cache.operation_failed', { ...logContext, operation: 'read', error });
-                    throw error;
+                    lookupResult = { type: 'bypass' };
+                }
+                if (lookupResult.type === 'bypass') {
+                    return (await originalMethod.apply(this, args));
                 }
-                if (cached !== undefined) {
-                    if ('error' in cached) {
-                        (0, cache_logger_1.logCacheEvent)('cache.hit', { ...logContext, entryType: 'error' });
-                        throw cached.error;
+                if (lookupResult.type === 'hit') {
+                    const cachedResult = resolveCachedEntry(lookupResult.entry, errorPolicy, logContext);
+                    if (cachedResult.type === 'value') {
+                        return cachedResult.value;
+                    }
+                    if (cachedResult.type === 'error') {
+                        throw cachedResult.error;
                     }
-                    (0, cache_logger_1.logCacheEvent)('cache.hit', { ...logContext, entryType: 'value' });
-                    return cached.value;
                 }
                 (0, cache_logger_1.logCacheEvent)('cache.miss', logContext);
+                let result;
                 try {
-                    const result = (await originalMethod.apply(this, args));
-                    dispatchCacheWrite({
-                        provider,
-                        cacheKey,
-                        entry: { value: result },
-                        entryType: 'value',
-                        ttl: options?.ttl,
-                        logContext,
-                    });
-                    return result;
+                    result = (await originalMethod.apply(this, args));
                 }
                 catch (error) {
-                    dispatchCacheWrite({
-                        provider,
-                        cacheKey,
-                        entry: { error },
-                        entryType: 'error',
-                        ttl: options?.ttl,
-                        logContext,
-                    });
+                    handleBusinessError({ error, errorPolicy, provider, cacheKey, logContext });
                     throw error;
                 }
+                dispatchCacheWrite({
+                    provider,
+                    cacheKey,
+                    entry: { value: result },
+                    entryType: 'value',
+                    ttl: options?.ttl,
+                    logContext,
+                });
+                return result;
             })();
             pendingCache.set(cacheKey, promise);
             return promise;