@tsed/platform-cache 8.26.2 → 8.28.0

package/lib/esm/index.js

@@ -8,5 +8,6 @@ export * from "./interfaces/interfaces.js";
 export * from "./interfaces/PlatformCachedObject.js";
 export * from "./interfaces/PlatformCacheOptions.js";
 export * from "./services/PlatformCache.js";
+export * from "./services/PlatformCacheRefreshService.js";
 export * from "./utils/getPrefix.js";
 export * from "./utils/isEndpoint.js";

package/lib/esm/interceptors/PlatformCacheInterceptor.js

@@ -1,9 +1,9 @@
 import { IncomingMessage, ServerResponse } from "node:http";
 import { isClass, isString, nameOf } from "@tsed/core";
-import { constant, context, DIContext, inject, interceptor, logger, runInContext } from "@tsed/di";
+import { constant, context, DIContext, inject, interceptor, logger } from "@tsed/di";
 import { deserialize, serialize } from "@tsed/json-mapper";
 import { PlatformCache } from "../services/PlatformCache.js";
-import { getPrefix } from "../utils/getPrefix.js";
+import { PlatformCacheRefreshService } from "../services/PlatformCacheRefreshService.js";
 import { isEndpoint } from "../utils/isEndpoint.js";
 const cleanHeaders = (headers, blacklist) => {
     return Object.entries(headers)
@@ -21,6 +21,7 @@ const cleanHeaders = (headers, blacklist) => {
 export class PlatformCacheInterceptor {
     constructor() {
         this.cache = inject(PlatformCache);
+        this.refreshService = inject(PlatformCacheRefreshService);
         this.prefix = constant("cache.prefix", "");
         this.blacklist = constant("cache.ignoreHeaders", [
             "content-length",
@@ -30,7 +31,6 @@ export class PlatformCacheInterceptor {
             "content-encoding"
         ]);
     }
-    static #refreshLocks = new Map();
     intercept(context, next) {
         if (this.cache.disabled()) {
             return next();
@@ -40,40 +40,6 @@ export class PlatformCacheInterceptor {
         }
         return this.cacheResponse(context, next);
     }
-    async canRefreshInBackground(key, { refreshThreshold, ttl, cachedTTL }, next, $ctx) {
-        if (!refreshThreshold) {
-            return;
-        }
-        const release = await this.acquireRefreshLock(key);
-        try {
-            const inQueue = await this.hasKeyInQueue(key);
-            const inCooldown = await this.hasRefreshCooldown(key);
-            if (inQueue || inCooldown) {
-                return;
-            }
-            await this.addKeyToQueue(key);
-            const currentTTL = await this.cache.ttl(key);
-            const calculatedTTL = cachedTTL ?? (typeof ttl === "number" ? ttl : undefined);
-            const refreshThresholdWithJitter = this.getRefreshThresholdWithJitter(key, refreshThreshold);
-            try {
-                if (calculatedTTL !== undefined && (currentTTL === undefined || currentTTL < calculatedTTL - refreshThresholdWithJitter)) {
-                    await this.addRefreshCooldown(key, refreshThresholdWithJitter);
-                    if ($ctx) {
-                        await runInContext($ctx, () => next());
-                    }
-                    else {
-                        await next();
-                    }
-                }
-            }
-            finally {
-                await this.deleteKeyFromQueue(key);
-            }
-        }
-        finally {
-            release();
-        }
-    }
     async cacheMethod(context, next) {
         const { key, type, ttl, collectionType, refreshThreshold, args, canCache, $ctx, byPass } = this.getOptions(context, false);
         if (this.shouldByPassCache(byPass, args, $ctx)) {
@@ -94,10 +60,12 @@ export class PlatformCacheInterceptor {
             }
             return result;
         }
-        this.canRefreshInBackground(key, { refreshThreshold, ttl, cachedTTL: cachedObject.ttl }, async () => {
+        this.refreshService
+            .refreshInBackground(key, { refreshThreshold, ttl, cachedTTL: cachedObject.ttl }, async () => {
             const result = await next();
             await set(result);
-        }, $ctx).catch((er) => logger().error({
+        }, $ctx)
+            .catch((er) => logger().error({
             event: "CACHE_ERROR",
             method: "cacheMethod",
             concerned_key: key,
@@ -169,7 +137,7 @@ export class PlatformCacheInterceptor {
             canCache = (item) => ![null, undefined].includes(item);
         }
         return {
-            key: [...[this.prefix, ...getPrefix(interceptorContext.target, interceptorContext.propertyKey)].filter(Boolean), keyArgs].join(":"),
+            key: this.cache.buildEntryKey(interceptorContext.target, interceptorContext.propertyKey, keyArgs),
             refreshThreshold,
             ttl,
             type,
@@ -193,50 +161,6 @@ export class PlatformCacheInterceptor {
         }
         return typeof byPass === "function" ? byPass(args, $ctx) : !!byPass;
     }
-    async hasKeyInQueue(key) {
-        return !!(await this.cache.get(`$$queue:${key}`));
-    }
-    async addKeyToQueue(key) {
-        await this.cache.set(`$$queue:${key}`, true, { ttl: 120 });
-    }
-    async deleteKeyFromQueue(key) {
-        await this.cache.del(`$$queue:${key}`);
-    }
-    async acquireRefreshLock(key) {
-        for (;;) {
-            const lock = PlatformCacheInterceptor.#refreshLocks.get(key);
-            if (!lock) {
-                let releaseFn;
-                const currentLock = new Promise((resolve) => {
-                    releaseFn = resolve;
-                });
-                PlatformCacheInterceptor.#refreshLocks.set(key, currentLock);
-                return () => {
-                    if (PlatformCacheInterceptor.#refreshLocks.get(key) === currentLock) {
-                        PlatformCacheInterceptor.#refreshLocks.delete(key);
-                    }
-                    releaseFn?.();
-                };
-            }
-            await lock;
-        }
-    }
-    getRefreshCooldownKey(key) {
-        return `$$refresh-cooldown:${key}`;
-    }
-    getRefreshThresholdWithJitter(key, refreshThreshold) {
-        const maxJitter = Math.max(1, Math.floor(refreshThreshold * 0.1));
-        const hash = key.split("").reduce((acc, char) => (acc * 31 + char.charCodeAt(0)) | 0, 0);
-        const jitter = Math.abs(hash) % (maxJitter + 1);
-        return Math.max(1, refreshThreshold - jitter);
-    }
-    async hasRefreshCooldown(key) {
-        return !!(await this.cache.get(this.getRefreshCooldownKey(key)));
-    }
-    async addRefreshCooldown(key, refreshThreshold) {
-        const cooldownTTL = Math.max(1, Math.floor(refreshThreshold / 2));
-        await this.cache.set(this.getRefreshCooldownKey(key), true, { ttl: cooldownTTL });
-    }
     sendResponse(cachedObject) {
         const { headers, ttl } = cachedObject;
         const $ctx = context();

package/lib/esm/services/PlatformCache.js

@@ -24,8 +24,40 @@ export class PlatformCache {
         }
     }
     getKeysOf(target, propertyKey) {
-        const prefix = getPrefix(target, propertyKey);
-        return this.keys(`${prefix.join(":")}:*`);
+        return this.keys(this.buildEntryPattern(target, propertyKey));
+    }
+    /**
+     * Returns the global cache key prefix from settings (`cache.prefix`).
+     */
+    cachePrefix() {
+        return constant("cache.prefix", "");
+    }
+    /**
+     * Builds the stable namespace segments used by cached entries for a method.
+     * The namespace combines the global cache prefix (if configured) and the method prefix.
+     */
+    buildNamespace(target, propertyKey) {
+        return [this.cachePrefix(), ...getPrefix(target, propertyKey)].filter(Boolean);
+    }
+    /**
+     * Builds the final cache key for a method call.
+     */
+    buildEntryKey(target, propertyKey, keyArgs) {
+        return [...this.buildNamespace(target, propertyKey), keyArgs].join(":");
+    }
+    /**
+     * Builds a key pattern scoped to a cached method namespace.
+     * Useful for listing/invalidation of keys produced by the same cached method.
+     */
+    buildEntryPattern(target, propertyKey, suffix = "*") {
+        return [...this.buildNamespace(target, propertyKey), suffix].join(":");
+    }
+    /**
+     * Builds internal keys used by cache housekeeping features
+     * (refresh queue and refresh cooldown markers).
+     */
+    buildInternalKey(namespace, key) {
+        return `$$${namespace}:${key}`;
     }
     disabled() {
         return !constant("cache");

package/lib/esm/services/PlatformCacheRefreshService.js

@@ -0,0 +1,90 @@
+import { inject, injectable, ProviderScope, ProviderType, runInContext } from "@tsed/di";
+import { PlatformCache } from "./PlatformCache.js";
+/**
+ * @platform
+ */
+export class PlatformCacheRefreshService {
+    constructor() {
+        this.cache = inject(PlatformCache);
+    }
+    static #refreshLocks = new Map();
+    async hasKeyInQueue(key) {
+        return !!(await this.cache.get(this.cache.buildInternalKey("queue", key)));
+    }
+    async addKeyToQueue(key) {
+        await this.cache.set(this.cache.buildInternalKey("queue", key), true, { ttl: 120 });
+    }
+    async deleteKeyFromQueue(key) {
+        await this.cache.del(this.cache.buildInternalKey("queue", key));
+    }
+    getRefreshThresholdWithJitter(key, refreshThreshold) {
+        const maxJitter = Math.max(1, Math.floor(refreshThreshold * 0.1));
+        const hash = key.split("").reduce((acc, char) => (acc * 31 + char.charCodeAt(0)) | 0, 0);
+        const jitter = Math.abs(hash) % (maxJitter + 1);
+        return Math.max(1, refreshThreshold - jitter);
+    }
+    async hasRefreshCooldown(key) {
+        return !!(await this.cache.get(this.getRefreshCooldownKey(key)));
+    }
+    async addRefreshCooldown(key, refreshThreshold) {
+        const cooldownTTL = Math.max(1, Math.floor(refreshThreshold / 2));
+        await this.cache.set(this.getRefreshCooldownKey(key), true, { ttl: cooldownTTL });
+    }
+    async refreshInBackground(key, { refreshThreshold, ttl, cachedTTL }, next, $ctx) {
+        if (!refreshThreshold) {
+            return;
+        }
+        const release = await this.acquireRefreshLock(key);
+        try {
+            const inQueue = await this.hasKeyInQueue(key);
+            const inCooldown = await this.hasRefreshCooldown(key);
+            if (inQueue || inCooldown) {
+                return;
+            }
+            await this.addKeyToQueue(key);
+            const currentTTL = await this.cache.ttl(key);
+            const calculatedTTL = cachedTTL ?? (typeof ttl === "number" ? ttl : undefined);
+            const refreshThresholdWithJitter = this.getRefreshThresholdWithJitter(key, refreshThreshold);
+            try {
+                if (calculatedTTL !== undefined && (currentTTL === undefined || currentTTL < calculatedTTL - refreshThresholdWithJitter)) {
+                    await this.addRefreshCooldown(key, refreshThresholdWithJitter);
+                    if ($ctx) {
+                        await runInContext($ctx, () => next());
+                    }
+                    else {
+                        await next();
+                    }
+                }
+            }
+            finally {
+                await this.deleteKeyFromQueue(key);
+            }
+        }
+        finally {
+            release();
+        }
+    }
+    async acquireRefreshLock(key) {
+        for (;;) {
+            const lock = PlatformCacheRefreshService.#refreshLocks.get(key);
+            if (!lock) {
+                let releaseFn;
+                const currentLock = new Promise((resolve) => {
+                    releaseFn = resolve;
+                });
+                PlatformCacheRefreshService.#refreshLocks.set(key, currentLock);
+                return () => {
+                    if (PlatformCacheRefreshService.#refreshLocks.get(key) === currentLock) {
+                        PlatformCacheRefreshService.#refreshLocks.delete(key);
+                    }
+                    releaseFn?.();
+                };
+            }
+            await lock;
+        }
+    }
+    getRefreshCooldownKey(key) {
+        return this.cache.buildInternalKey("refresh-cooldown", key);
+    }
+}
+injectable(PlatformCacheRefreshService).type(ProviderType.MODULE).scope(ProviderScope.SINGLETON);

package/lib/types/index.d.ts

@@ -8,5 +8,6 @@ export * from "./interfaces/interfaces.js";
 export * from "./interfaces/PlatformCachedObject.js";
 export * from "./interfaces/PlatformCacheOptions.js";
 export * from "./services/PlatformCache.js";
+export * from "./services/PlatformCacheRefreshService.js";
 export * from "./utils/getPrefix.js";
 export * from "./utils/isEndpoint.js";

package/lib/types/interceptors/PlatformCacheInterceptor.d.ts

@@ -2,6 +2,7 @@ import { type BaseContext, DIContext, InterceptorContext, InterceptorMethods, In
 import { PlatformCachedObject } from "../interfaces/PlatformCachedObject.js";
 import { PlatformCacheOptions } from "../interfaces/PlatformCacheOptions.js";
 import { PlatformCache } from "../services/PlatformCache.js";
+import { PlatformCacheRefreshService } from "../services/PlatformCacheRefreshService.js";
 interface Response {
     setHeader(key: string, value: string): this;
     setHeaders(headers: Record<string, unknown>): this;
@@ -22,16 +23,11 @@ type Context = DIContext & {
  * @platform
  */
 export declare class PlatformCacheInterceptor implements InterceptorMethods {
-    #private;
     protected cache: PlatformCache;
+    protected refreshService: PlatformCacheRefreshService;
     protected prefix: string;
     protected blacklist: string[];
     intercept(context: InterceptorContext<any, PlatformCacheOptions>, next: InterceptorNext): unknown;
-    canRefreshInBackground(key: string, { refreshThreshold, ttl, cachedTTL }: {
-        refreshThreshold?: number;
-        ttl: any;
-        cachedTTL?: number;
-    }, next: Function, $ctx?: Context): Promise<void>;
     cacheMethod(context: InterceptorContext<any, PlatformCacheOptions>, next: InterceptorNext): Promise<any>;
     cacheResponse(interceptorContext: InterceptorContext<any, PlatformCacheOptions>, next: InterceptorNext): Promise<any>;
     protected getMethod($ctx?: Context): string | undefined;
@@ -51,14 +47,6 @@ export declare class PlatformCacheInterceptor implements InterceptorMethods {
     };
     protected getContextFromArgs(args: unknown[]): Context | undefined;
     protected shouldByPassCache(byPass: PlatformCacheOptions["byPass"], args: unknown[], $ctx?: Context): boolean;
-    protected hasKeyInQueue(key: string): Promise<boolean>;
-    protected addKeyToQueue(key: string): Promise<void>;
-    protected deleteKeyFromQueue(key: string): Promise<void>;
-    protected acquireRefreshLock(key: string): Promise<() => void>;
-    protected getRefreshCooldownKey(key: string): string;
-    protected getRefreshThresholdWithJitter(key: string, refreshThreshold: number): number;
-    protected hasRefreshCooldown(key: string): Promise<boolean>;
-    protected addRefreshCooldown(key: string, refreshThreshold: number): Promise<void>;
     protected sendResponse(cachedObject: PlatformCachedObject): any;
 }
 export {};

package/lib/types/services/PlatformCache.d.ts

@@ -13,6 +13,29 @@ export declare class PlatformCache {
     get cache(): CacheManager | undefined;
     $onInit(): Promise<void>;
     getKeysOf(target: Type<any>, propertyKey: string | symbol): Promise<string[]>;
+    /**
+     * Returns the global cache key prefix from settings (`cache.prefix`).
+     */
+    cachePrefix(): string;
+    /**
+     * Builds the stable namespace segments used by cached entries for a method.
+     * The namespace combines the global cache prefix (if configured) and the method prefix.
+     */
+    buildNamespace(target: Type<any>, propertyKey: string | symbol): (string | symbol)[];
+    /**
+     * Builds the final cache key for a method call.
+     */
+    buildEntryKey(target: Type<any>, propertyKey: string | symbol, keyArgs: string): string;
+    /**
+     * Builds a key pattern scoped to a cached method namespace.
+     * Useful for listing/invalidation of keys produced by the same cached method.
+     */
+    buildEntryPattern(target: Type<any>, propertyKey: string | symbol, suffix?: string): string;
+    /**
+     * Builds internal keys used by cache housekeeping features
+     * (refresh queue and refresh cooldown markers).
+     */
+    buildInternalKey(namespace: "queue" | "refresh-cooldown", key: string): string;
     disabled(): boolean;
     defaultKeyResolver(): (args: any[], ctx?: any) => string;
     defaultTtl(): Ttl | undefined;

package/lib/types/services/PlatformCacheRefreshService.d.ts

@@ -0,0 +1,22 @@
+import { BaseContext } from "@tsed/di";
+import { PlatformCache } from "./PlatformCache.js";
+/**
+ * @platform
+ */
+export declare class PlatformCacheRefreshService {
+    #private;
+    protected cache: PlatformCache;
+    hasKeyInQueue(key: string): Promise<boolean>;
+    addKeyToQueue(key: string): Promise<void>;
+    deleteKeyFromQueue(key: string): Promise<void>;
+    getRefreshThresholdWithJitter(key: string, refreshThreshold: number): number;
+    hasRefreshCooldown(key: string): Promise<boolean>;
+    addRefreshCooldown(key: string, refreshThreshold: number): Promise<void>;
+    refreshInBackground(key: string, { refreshThreshold, ttl, cachedTTL }: {
+        refreshThreshold?: number;
+        ttl: any;
+        cachedTTL?: number;
+    }, next: Function, $ctx?: BaseContext): Promise<void>;
+    acquireRefreshLock(key: string): Promise<() => void>;
+    protected getRefreshCooldownKey(key: string): string;
+}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@tsed/platform-cache",
   "description": "Platform cache module for Ts.ED Framework",
   "type": "module",
-  "version": "8.26.2",
+  "version": "8.28.0",
   "source": "./src/index.ts",
   "main": "./lib/esm/index.js",
   "module": "./lib/esm/index.js",
@@ -28,16 +28,16 @@
     "tslib": ">=2.7.0"
   },
   "devDependencies": {
-    "@tsed/barrels": "8.26.2",
-    "@tsed/core": "8.26.2",
-    "@tsed/di": "8.26.2",
-    "@tsed/json-mapper": "8.26.2",
-    "@tsed/schema": "8.26.2",
-    "@tsed/typescript": "8.26.2",
+    "@tsed/barrels": "8.28.0",
+    "@tsed/core": "8.28.0",
+    "@tsed/di": "8.28.0",
+    "@tsed/json-mapper": "8.28.0",
+    "@tsed/schema": "8.28.0",
+    "@tsed/typescript": "8.28.0",
     "@types/micromatch": "^4.0.9",
     "eslint": "9.12.0",
     "typescript": "6.0.2",
-    "vitest": "3.2.4"
+    "vitest": "4.1.4"
   },
   "peerDependencies": {
     "@tsed/core": ">=8.0.0",