@tsed/platform-cache 8.23.0 → 8.24.0

package/lib/esm/interceptors/PlatformCacheInterceptor.js

@@ -1,7 +1,7 @@
 import { __decorate, __metadata } from "tslib";
 import { IncomingMessage, ServerResponse } from "node:http";
 import { isClass, isString, nameOf } from "@tsed/core";
-import { Constant, DIContext, Inject, Interceptor } from "@tsed/di";
+import { Constant, context, DIContext, Inject, Interceptor, runInContext } from "@tsed/di";
 import { deserialize, serialize } from "@tsed/json-mapper";
 import { Logger } from "@tsed/logger";
 import { PlatformCache } from "../services/PlatformCache.js";
@@ -30,20 +30,32 @@ let PlatformCacheInterceptor = class PlatformCacheInterceptor {
         }
         return this.cacheResponse(context, next);
     }
-    async canRefreshInBackground(key, { refreshThreshold, ttl }, next) {
+    async canRefreshInBackground(key, { refreshThreshold, ttl }, next, $ctx) {
         const inQueue = await this.hasKeyInQueue(key);
         if (refreshThreshold && !inQueue) {
             await this.addKeyToQueue(key);
             const currentTTL = await this.cache.ttl(key);
             const calculatedTTL = this.cache.calculateTTL(currentTTL, ttl);
-            if (currentTTL === undefined || currentTTL < calculatedTTL - refreshThreshold) {
-                await next();
+            try {
+                if (currentTTL === undefined || currentTTL < calculatedTTL - refreshThreshold) {
+                    if ($ctx) {
+                        await runInContext($ctx, () => next());
+                    }
+                    else {
+                        await next();
+                    }
+                }
+            }
+            finally {
+                await this.deleteKeyFromQueue(key);
             }
-            await this.deleteKeyFromQueue(key);
         }
     }
     async cacheMethod(context, next) {
-        const { key, type, ttl, collectionType, refreshThreshold, args, canCache } = this.getOptions(context);
+        const { key, type, ttl, collectionType, refreshThreshold, args, canCache, $ctx, byPass } = this.getOptions(context, false);
+        if (this.shouldByPassCache(byPass, args, $ctx)) {
+            return next();
+        }
         const set = (result) => {
             if (!canCache || (canCache && canCache(result))) {
                 const calculatedTTL = this.cache.calculateTTL(result, ttl);
@@ -62,7 +74,7 @@ let PlatformCacheInterceptor = class PlatformCacheInterceptor {
         this.canRefreshInBackground(key, { refreshThreshold, ttl }, async () => {
             const result = await next();
             await set(result);
-        }).catch((er) => this.logger.error({
+        }, $ctx).catch((er) => this.logger.error({
             event: "CACHE_ERROR",
             method: "cacheMethod",
             concerned_key: key,
@@ -74,31 +86,43 @@ let PlatformCacheInterceptor = class PlatformCacheInterceptor {
         const { data } = cachedObject;
         return deserialize(JSON.parse(data), { collectionType, type });
     }
-    async cacheResponse(context, next) {
-        const { request, response } = context.args[context.args.length - 1];
-        if (request.method !== "GET") {
+    async cacheResponse(interceptorContext, next) {
+        const { key, ttl, args, $ctx, byPass } = this.getOptions(interceptorContext, "no-cache");
+        const currentCtx = $ctx || context();
+        if (this.getMethod(currentCtx) !== "GET") {
             return next();
         }
-        const { key, ttl, args, $ctx } = this.getOptions(context);
-        const cachedObject = await this.cache.getCachedObject(key);
-        if (cachedObject && !(request.get("cache-control") === "no-cache")) {
-            return this.sendResponse(cachedObject, $ctx);
+        const shouldByPass = this.shouldByPassCache(byPass, args, currentCtx);
+        const useCache = !shouldByPass;
+        if (useCache) {
+            const cachedObject = await this.cache.getCachedObject(key);
+            if (cachedObject) {
+                return this.sendResponse(cachedObject);
+            }
         }
         const result = await next();
         const calculatedTTL = this.cache.calculateTTL(result, ttl);
-        $ctx.response.setHeaders({
+        currentCtx.response?.setHeaders({
             "cache-control": `max-age=${calculatedTTL}`
         });
-        // cache final response with his headers and body
-        response.onEnd(() => {
-            this.cache.setCachedObject(key, response.getBody(), {
+        currentCtx.response?.onEnd(() => {
+            if (!useCache) {
+                return;
+            }
+            this.cache.setCachedObject(key, currentCtx.response.getBody(), {
                 ttl: calculatedTTL,
                 args,
-                headers: cleanHeaders(response.getHeaders(), this.blacklist)
+                headers: cleanHeaders(currentCtx.response.getHeaders(), this.blacklist)
             });
         });
         return result;
     }
+    getMethod($ctx = context()) {
+        return $ctx.request?.method;
+    }
+    noCache($ctx = context()) {
+        return $ctx.request?.get("cache-control") === "no-cache" || $ctx.get("cache-control") === "no-cache";
+    }
     getArgs(context) {
         return context.args.reduce((args, arg) => {
             if (arg instanceof DIContext || arg instanceof IncomingMessage || arg instanceof ServerResponse) {
@@ -110,17 +134,17 @@ let PlatformCacheInterceptor = class PlatformCacheInterceptor {
             return args.concat(arg);
         }, []);
     }
-    getOptions(context) {
-        const $ctx = context.args[context.args.length - 1];
-        const { ttl, type, collectionType, key: k = this.cache.defaultKeyResolver(), refreshThreshold } = context.options || {};
-        let { canCache } = context.options || {};
-        const args = this.getArgs(context);
+    getOptions(interceptorContext, defaultByPass = false) {
+        const $ctx = this.getContextFromArgs(interceptorContext.args) || context();
+        const { ttl, type, collectionType, key: k = this.cache.defaultKeyResolver(), refreshThreshold, byPass = defaultByPass } = interceptorContext.options || {};
+        let { canCache } = interceptorContext.options || {};
+        const args = this.getArgs(interceptorContext);
         const keyArgs = isString(k) ? k : k(args, $ctx);
         if (canCache && canCache === "no-nullish") {
             canCache = (item) => ![null, undefined].includes(item);
         }
         return {
-            key: [...[this.prefix, ...getPrefix(context.target, context.propertyKey)].filter(Boolean), keyArgs].join(":"),
+            key: [...[this.prefix, ...getPrefix(interceptorContext.target, interceptorContext.propertyKey)].filter(Boolean), keyArgs].join(":"),
             refreshThreshold,
             ttl,
             type,
@@ -128,9 +152,22 @@ let PlatformCacheInterceptor = class PlatformCacheInterceptor {
             collectionType,
             keyArgs,
             canCache,
-            $ctx
+            $ctx,
+            byPass
         };
     }
+    getContextFromArgs(args) {
+        return args.find((arg) => arg instanceof DIContext);
+    }
+    shouldByPassCache(byPass, args, $ctx) {
+        if (!byPass) {
+            return false;
+        }
+        if (byPass === "no-cache") {
+            return this.noCache($ctx);
+        }
+        return typeof byPass === "function" ? byPass(args, $ctx) : !!byPass;
+    }
     async hasKeyInQueue(key) {
         return !!(await this.cache.get(`$$queue:${key}`));
     }
@@ -140,23 +177,26 @@ let PlatformCacheInterceptor = class PlatformCacheInterceptor {
     async deleteKeyFromQueue(key) {
         await this.cache.del(`$$queue:${key}`);
     }
-    sendResponse(cachedObject, $ctx) {
+    sendResponse(cachedObject) {
         const { headers, ttl } = cachedObject;
-        const { request, response } = $ctx;
-        const requestEtag = request.get("if-none-match");
-        if (requestEtag && headers.etag === requestEtag) {
-            response.status(304).setHeaders(headers).body(undefined);
-            return undefined;
+        const $ctx = context();
+        if ($ctx.request && $ctx.response) {
+            const requestEtag = $ctx.request.get("if-none-match");
+            if (requestEtag && headers?.etag === requestEtag) {
+                $ctx.response.status(304).setHeaders(headers).body(undefined);
+                return undefined;
+            }
+            const data = JSON.parse(cachedObject.data);
+            $ctx.response
+                .setHeaders({
+                ...headers,
+                "x-cached": "true",
+                "cache-control": `max-age=${ttl}`
+            })
+                .body(data);
+            return cachedObject.data;
         }
-        const data = JSON.parse(cachedObject.data);
-        $ctx.response
-            .setHeaders({
-            ...headers,
-            "x-cached": "true",
-            "cache-control": `max-age=${ttl}`
-        })
-            .body(data);
-        return data;
+        return cachedObject.data;
     }
 };
 __decorate([

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

@@ -1,8 +1,24 @@
-import { BaseContext, InterceptorContext, InterceptorMethods, InterceptorNext } from "@tsed/di";
+import { type BaseContext, DIContext, InterceptorContext, InterceptorMethods, InterceptorNext } from "@tsed/di";
 import { Logger } from "@tsed/logger";
 import { PlatformCachedObject } from "../interfaces/PlatformCachedObject.js";
 import { PlatformCacheOptions } from "../interfaces/PlatformCacheOptions.js";
 import { PlatformCache } from "../services/PlatformCache.js";
+interface Response {
+    setHeader(key: string, value: string): this;
+    setHeaders(headers: Record<string, unknown>): this;
+    body(data: unknown): this;
+    status(status: number): this;
+    onEnd(cb: any): void;
+    getBody(): unknown;
+    getHeaders(): Record<string, unknown>;
+}
+type Context = DIContext & {
+    request?: {
+        get(key: string): string | undefined;
+        method: string;
+    };
+    response?: Response;
+};
 /**
  * @platform
  */
@@ -15,23 +31,29 @@ export declare class PlatformCacheInterceptor implements InterceptorMethods {
     canRefreshInBackground(key: string, { refreshThreshold, ttl }: {
         refreshThreshold?: number;
         ttl: any;
-    }, next: Function): Promise<void>;
+    }, next: Function, $ctx?: Context): Promise<void>;
     cacheMethod(context: InterceptorContext<any, PlatformCacheOptions>, next: InterceptorNext): Promise<any>;
-    cacheResponse(context: InterceptorContext<any, PlatformCacheOptions>, next: InterceptorNext): Promise<any>;
-    protected getArgs(context: InterceptorContext<unknown, PlatformCacheOptions>): any;
-    protected getOptions(context: InterceptorContext<any, PlatformCacheOptions>): {
+    cacheResponse(interceptorContext: InterceptorContext<any, PlatformCacheOptions>, next: InterceptorNext): Promise<any>;
+    protected getMethod($ctx?: Context): string | undefined;
+    protected noCache($ctx?: Context): boolean;
+    protected getArgs(context: InterceptorContext<unknown, PlatformCacheOptions>): unknown[];
+    protected getOptions(interceptorContext: InterceptorContext<any, PlatformCacheOptions>, defaultByPass?: PlatformCacheOptions["byPass"]): {
         key: string;
         refreshThreshold: number | undefined;
         ttl: import("../services/PlatformCache.js").Ttl | undefined;
         type: any;
-        args: any;
+        args: unknown[];
         collectionType: any;
         keyArgs: string;
         canCache: ((item: any) => boolean) | undefined;
-        $ctx: any;
+        $ctx: Context;
+        byPass: false | "no-cache" | ((args: any[], $ctx?: BaseContext) => boolean);
     };
+    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 sendResponse(cachedObject: PlatformCachedObject, $ctx: BaseContext): any;
+    protected sendResponse(cachedObject: PlatformCachedObject): any;
 }
+export {};

package/lib/types/interfaces/PlatformCacheOptions.d.ts

@@ -22,4 +22,11 @@ export interface PlatformCacheOptions extends MetadataTypes {
      * The function determine if the result must be cached or not.
      */
     canCache?: ((item: any) => boolean) | "no-nullish";
+    /**
+     * Configure the bypass cache strategy.
+     * - `false` (default for services) never bypasses the cache.
+     * - `"no-cache"` (default for HTTP endpoints) bypasses when the `Cache-Control: no-cache` header is present.
+     * - Provide a function to decide dynamically based on the current call arguments/context.
+     */
+    byPass?: false | "no-cache" | ((args: any[], $ctx?: BaseContext) => boolean);
 }

package/package.json

@@ -2,7 +2,7 @@
   "name": "@tsed/platform-cache",
   "description": "Platform cache module for Ts.ED Framework",
   "type": "module",
-  "version": "8.23.0",
+  "version": "8.24.0",
   "source": "./src/index.ts",
   "main": "./lib/esm/index.js",
   "module": "./lib/esm/index.js",
@@ -28,12 +28,12 @@
     "tslib": "2.7.0"
   },
   "devDependencies": {
-    "@tsed/barrels": "8.23.0",
-    "@tsed/core": "8.23.0",
-    "@tsed/di": "8.23.0",
-    "@tsed/json-mapper": "8.23.0",
-    "@tsed/schema": "8.23.0",
-    "@tsed/typescript": "8.23.0",
+    "@tsed/barrels": "8.24.0",
+    "@tsed/core": "8.24.0",
+    "@tsed/di": "8.24.0",
+    "@tsed/json-mapper": "8.24.0",
+    "@tsed/schema": "8.24.0",
+    "@tsed/typescript": "8.24.0",
     "@types/micromatch": "^4.0.9",
     "eslint": "9.12.0",
     "typescript": "5.9.3",

package/readme.md

@@ -35,6 +35,16 @@ A package of Ts.ED framework. See website: https://tsed.devdocs/cache.html
 npm install --save @tsed/platform-cache
 ```
 
+## Force refresh
+
+Send the header `Cache-Control: no-cache` (or set it directly on the `PlatformContext`) to bypass
+`PlatformCacheInterceptor` for a single request. This is handy when you want a fresh response without wiping the cache.
+You can override or extend this behavior with the `byPass` option on `@UseCache`:
+
+- Service methods default to `byPass: false`, so they always consult the cache unless you explicitly return `true` from your predicate.
+- HTTP endpoints default to `byPass: "no-cache"`, which automatically honours the `Cache-Control: no-cache` header for one-off refreshes.
+- Provide a function (`byPass: (args, $ctx) => boolean`) to build custom strategies (e.g., bypass for admins or based on payload).
+
 ## Contributors
 
 Please read [contributing guidelines here](https://tsed.devcontributing.html).