@rabstack/rab-api 1.8.3 → 1.9.1

package/README.md

@@ -9,6 +9,7 @@ A TypeScript REST API framework built on Express.js with decorator-based routing
 - ✅ Request validation with Joi schemas
 - 💉 Dependency injection (TypeDI)
 - 🔐 Role-based access control
+- ⚡ Response caching with purge support
 - 📝 Full TypeScript type safety
 - 🚀 Production-ready
 
@@ -305,6 +306,113 @@ app.route({
 });
 ```
 
+## Caching
+
+Built-in response caching with cache invalidation (purge) support.
+
+### Setup
+
+```typescript
+const app = RabApi.createApp({
+  cache: {
+    adapter: myCacheAdapter, // Implement ICacheAdapter
+    defaultTtl: 900,         // 15 minutes default
+  },
+});
+```
+
+### Cache Adapter Interface
+
+```typescript
+interface ICacheAdapter {
+  get<T>(key: string): Promise<T | null>;
+  set<T>(key: string, data: T, ttlSeconds: number): Promise<void>;
+  del(key: string): Promise<void>;
+}
+```
+
+### Enable Caching
+
+```typescript
+// Simple - uses defaults (ttl: 900s, strategy: url-query)
+@Get('/products', { cache: true })
+export class ListProducts {}
+
+// With options
+@Get('/products', {
+  cache: {
+    ttl: 600,                    // 10 minutes
+    strategy: 'url-query',       // Include query params in cache key
+  }
+})
+export class ListProducts {}
+```
+
+### Cache Strategies
+
+- **`url-query`** (default): Cache key includes path + sorted query params
+  - `/products?page=1&limit=10` → key: `/products?limit=10&page=1`
+- **`url-params`**: Cache key is just the resolved path
+  - `/products?page=1&limit=10` → key: `/products`
+
+### Cache Purge
+
+Purge cache keys after mutations:
+
+```typescript
+@Post('/products', {
+  cache: {
+    purge: ['/products'],  // Purge this key after successful response
+  }
+})
+export class CreateProduct {}
+
+// With dynamic params
+@Put('/products/:id', {
+  cache: {
+    purge: [
+      '/products',
+      '/products/:id',  // :id is resolved from request params
+    ]
+  }
+})
+export class UpdateProduct {}
+
+// Function-based purge
+@Delete('/products/:id', {
+  cache: {
+    purge: [(req) => `/products/${req.params.id}`]
+  }
+})
+export class DeleteProduct {}
+```
+
+### Example: Redis Adapter
+
+```typescript
+import Redis from 'ioredis';
+import { ICacheAdapter } from 'rab-api';
+
+const redis = new Redis();
+
+const redisCacheAdapter: ICacheAdapter = {
+  async get(key) {
+    const data = await redis.get(key);
+    return data ? JSON.parse(data) : null;
+  },
+  async set(key, data, ttl) {
+    await redis.setex(key, ttl, JSON.stringify(data));
+  },
+  async del(key) {
+    await redis.del(key);
+  },
+};
+
+const app = RabApi.createApp({
+  cache: { adapter: redisCacheAdapter },
+});
+```
+
 ## Advanced Features
 
 ### Controller Type Helpers

package/index.cjs.js

@@ -519,7 +519,7 @@ var utils = /*#__PURE__*/Object.freeze({
 });
 
 const DEFAULT_TTL = 900; // 15 minutes
-const DEFAULT_STRATEGY = 'url-params';
+const DEFAULT_STRATEGY = 'url-query';
 /**
  * Normalize cache config - handles `cache: true` shorthand
  */ function normalizeCacheConfig(cache, defaultTtl) {
@@ -534,7 +534,7 @@ const DEFAULT_STRATEGY = 'url-params';
     return {
         ttl: (_ref = (_cache_ttl = cache.ttl) != null ? _cache_ttl : defaultTtl) != null ? _ref : DEFAULT_TTL,
         strategy: (_cache_strategy = cache.strategy) != null ? _cache_strategy : DEFAULT_STRATEGY,
-        invalidates: cache.invalidates
+        purge: cache.purge
     };
 }
 /**
@@ -570,8 +570,8 @@ const DEFAULT_STRATEGY = 'url-params';
     });
 }
 /**
- * Resolve all invalidation patterns for a request
- */ function resolveInvalidationPatterns(patterns, req) {
+ * Resolve all purge keys for a request
+ */ function resolvePurgeKeys(patterns, req) {
     const resolved = [];
     for (const pattern of patterns){
         if (typeof pattern === 'function') {
@@ -593,9 +593,9 @@ const DEFAULT_STRATEGY = 'url-params';
     return config.ttl !== undefined && config.ttl > 0;
 }
 /**
- * Check if there are invalidation patterns
- */ function hasInvalidations(config) {
-    return Array.isArray(config.invalidates) && config.invalidates.length > 0;
+ * Check if there are purge patterns
+ */ function hasPurgeKeys(config) {
+    return Array.isArray(config.purge) && config.purge.length > 0;
 }
 
 const controllerHandler = (controller, config)=>{
@@ -603,7 +603,7 @@ const controllerHandler = (controller, config)=>{
     const cacheConfig = normalizeCacheConfig(config.cache, config.cacheDefaultTtl);
     const cacheAdapter = config.cacheAdapter;
     const isCacheEnabled = cacheConfig && cacheAdapter && shouldCache(cacheConfig);
-    const hasInvalidationPatterns = cacheConfig && hasInvalidations(cacheConfig);
+    const hasPurge = cacheConfig && hasPurgeKeys(cacheConfig);
     return async (req, res, next)=>{
         try {
             let query = req.query;
@@ -643,12 +643,12 @@ const controllerHandler = (controller, config)=>{
                 // Silently ignore cache errors
                 });
             }
-            // Handle invalidations after successful mutation
-            if (hasInvalidationPatterns && cacheAdapter) {
-                const patterns = resolveInvalidationPatterns(cacheConfig.invalidates, req);
-                // Invalidate in background
-                Promise.all(patterns.map((pattern)=>pattern.includes('*') ? cacheAdapter.delPattern(pattern) : cacheAdapter.del(pattern))).catch(()=>{
-                // Silently ignore invalidation errors
+            // Handle purge after successful mutation
+            if (hasPurge && cacheAdapter) {
+                const keys = resolvePurgeKeys(cacheConfig.purge, req);
+                // Purge in background no await for promises you could use setImmediate if needed
+                Promise.all(keys.map((key)=>cacheAdapter.del(key))).catch(()=>{
+                // Silently ignore purge errors
                 });
             }
             var _response_statusCode1;
@@ -1218,10 +1218,10 @@ exports.buildCacheKey = buildCacheKey;
 exports.controllerHandler = controllerHandler;
 exports.errorHandler = errorHandler;
 exports.extractTokenFromHeader = extractTokenFromHeader;
-exports.hasInvalidations = hasInvalidations;
+exports.hasPurgeKeys = hasPurgeKeys;
 exports.isCallBackPipe = isCallBackPipe;
 exports.isRouteAController = isRouteAController;
 exports.normalizeCacheConfig = normalizeCacheConfig;
-exports.resolveInvalidationPatterns = resolveInvalidationPatterns;
 exports.resolvePattern = resolvePattern;
+exports.resolvePurgeKeys = resolvePurgeKeys;
 exports.shouldCache = shouldCache;

package/index.esm.d.ts

@@ -171,10 +171,10 @@ export declare type BuildRouterProps = CreateRouterProps & {
 export declare interface CacheConfig {
     /** Time-to-live in seconds (default: 900 = 15 minutes) */
     ttl?: number;
-    /** Key derivation strategy (default: 'url-params') */
+    /** Key derivation strategy (default: 'url-query') */
     strategy?: CacheStrategy;
-    /** URL patterns to invalidate after successful response */
-    invalidates?: InvalidationPattern[];
+    /** Keys to purge after successful response */
+    purge?: PurgePattern[];
 }
 
 /**
@@ -454,9 +454,9 @@ export declare function Get(path: string, options?: ControllerRouteDefinitionOpt
 export declare type GetController<TResponse, TQuery = any, TParams = any, TUser = any> = IControllerClass<TQuery, any, TResponse, TParams, TUser>;
 
 /**
- * Check if there are invalidation patterns
+ * Check if there are purge patterns
  */
-export declare function hasInvalidations(config: CacheConfig): boolean;
+export declare function hasPurgeKeys(config: CacheConfig): boolean;
 
 /**
  * Supported HTTP methods for route decorators.
@@ -470,7 +470,6 @@ export declare interface ICacheAdapter {
     get<T>(key: string): Promise<T | null>;
     set<T>(key: string, data: T, ttlSeconds: number): Promise<void>;
     del(key: string): Promise<void>;
-    delPattern(pattern: string): Promise<void>;
 }
 
 /**
@@ -559,12 +558,6 @@ export declare class InternalServerErrorException extends RabApiError {
     constructor(message?: string, errorCode?: string);
 }
 
-/**
- * Invalidation pattern - either a URL pattern string or a function that returns pattern(s)
- * URL patterns with :param placeholders are auto-resolved from request params
- */
-export declare type InvalidationPattern = string | ((req: any) => string | string[]);
-
 export declare const isCallBackPipe: (pipe: PipeFn | PipeFnCallBack) => pipe is PipeFnCallBack;
 
 export declare function isRouteAController(value: AppRoute): value is ControllerClassType;
@@ -796,6 +789,12 @@ export declare function Post(path: string, options?: ControllerRouteDefinitionOp
  */
 export declare type PostController<TBody = any, TResponse = any, TParams = any, TUser = any, TQuery = any> = IControllerClass<TQuery, TBody, TResponse, TParams, TUser>;
 
+/**
+ * Purge pattern - either a key string or a function that returns key(s)
+ * Patterns with :param placeholders are auto-resolved from request params
+ */
+export declare type PurgePattern = string | ((req: any) => string | string[]);
+
 /**
  * PUT route decorator.
  * Registers a controller class as a PUT endpoint handler.
@@ -944,14 +943,14 @@ export declare class RequestTimeoutException extends RabApiError {
 }
 
 /**
- * Resolve all invalidation patterns for a request
+ * Resolve :param placeholders in a pattern using request params
  */
-export declare function resolveInvalidationPatterns(patterns: InvalidationPattern[], req: any): string[];
+export declare function resolvePattern(pattern: string, params: Record<string, string>): string;
 
 /**
- * Resolve :param placeholders in a pattern using request params
+ * Resolve all purge keys for a request
  */
-export declare function resolvePattern(pattern: string, params: Record<string, string>): string;
+export declare function resolvePurgeKeys(patterns: PurgePattern[], req: any): string[];
 
 declare function retrieveRouteMetaData(route: ControllerClassType): ControllerRouteDefinition;
 

package/index.esm.js

@@ -517,7 +517,7 @@ var utils = /*#__PURE__*/Object.freeze({
 });
 
 const DEFAULT_TTL = 900; // 15 minutes
-const DEFAULT_STRATEGY = 'url-params';
+const DEFAULT_STRATEGY = 'url-query';
 /**
  * Normalize cache config - handles `cache: true` shorthand
  */ function normalizeCacheConfig(cache, defaultTtl) {
@@ -532,7 +532,7 @@ const DEFAULT_STRATEGY = 'url-params';
     return {
         ttl: (_ref = (_cache_ttl = cache.ttl) != null ? _cache_ttl : defaultTtl) != null ? _ref : DEFAULT_TTL,
         strategy: (_cache_strategy = cache.strategy) != null ? _cache_strategy : DEFAULT_STRATEGY,
-        invalidates: cache.invalidates
+        purge: cache.purge
     };
 }
 /**
@@ -568,8 +568,8 @@ const DEFAULT_STRATEGY = 'url-params';
     });
 }
 /**
- * Resolve all invalidation patterns for a request
- */ function resolveInvalidationPatterns(patterns, req) {
+ * Resolve all purge keys for a request
+ */ function resolvePurgeKeys(patterns, req) {
     const resolved = [];
     for (const pattern of patterns){
         if (typeof pattern === 'function') {
@@ -591,9 +591,9 @@ const DEFAULT_STRATEGY = 'url-params';
     return config.ttl !== undefined && config.ttl > 0;
 }
 /**
- * Check if there are invalidation patterns
- */ function hasInvalidations(config) {
-    return Array.isArray(config.invalidates) && config.invalidates.length > 0;
+ * Check if there are purge patterns
+ */ function hasPurgeKeys(config) {
+    return Array.isArray(config.purge) && config.purge.length > 0;
 }
 
 const controllerHandler = (controller, config)=>{
@@ -601,7 +601,7 @@ const controllerHandler = (controller, config)=>{
     const cacheConfig = normalizeCacheConfig(config.cache, config.cacheDefaultTtl);
     const cacheAdapter = config.cacheAdapter;
     const isCacheEnabled = cacheConfig && cacheAdapter && shouldCache(cacheConfig);
-    const hasInvalidationPatterns = cacheConfig && hasInvalidations(cacheConfig);
+    const hasPurge = cacheConfig && hasPurgeKeys(cacheConfig);
     return async (req, res, next)=>{
         try {
             let query = req.query;
@@ -641,12 +641,12 @@ const controllerHandler = (controller, config)=>{
                 // Silently ignore cache errors
                 });
             }
-            // Handle invalidations after successful mutation
-            if (hasInvalidationPatterns && cacheAdapter) {
-                const patterns = resolveInvalidationPatterns(cacheConfig.invalidates, req);
-                // Invalidate in background
-                Promise.all(patterns.map((pattern)=>pattern.includes('*') ? cacheAdapter.delPattern(pattern) : cacheAdapter.del(pattern))).catch(()=>{
-                // Silently ignore invalidation errors
+            // Handle purge after successful mutation
+            if (hasPurge && cacheAdapter) {
+                const keys = resolvePurgeKeys(cacheConfig.purge, req);
+                // Purge in background no await for promises you could use setImmediate if needed
+                Promise.all(keys.map((key)=>cacheAdapter.del(key))).catch(()=>{
+                // Silently ignore purge errors
                 });
             }
             var _response_statusCode1;
@@ -1183,4 +1183,4 @@ class AtomExpressApp {
     }
 }
 
-export { AtomExpressApp, utils as AtomHelpers, AtomRoute, BadRequestException, CONTROLLER_ROUTE_KEY, ConflictException, Controller, Delete, DiContainer, ForbiddenException, Get, Injectable, InternalServerErrorException, MethodNotAllowedException, NotFoundException, OpenApiGenerator, Patch, PayloadTooLargeException, Post, Put, RabApi, RabApiError, RequestTimeoutException, ServiceUnavailableException, TooManyRequestsException, UnauthorizedException, UnprocessableEntityException, authHandler, bodyValidatorWithContext, buildCacheKey, controllerHandler, errorHandler, extractTokenFromHeader, hasInvalidations, isCallBackPipe, isRouteAController, normalizeCacheConfig, resolveInvalidationPatterns, resolvePattern, shouldCache };
+export { AtomExpressApp, utils as AtomHelpers, AtomRoute, BadRequestException, CONTROLLER_ROUTE_KEY, ConflictException, Controller, Delete, DiContainer, ForbiddenException, Get, Injectable, InternalServerErrorException, MethodNotAllowedException, NotFoundException, OpenApiGenerator, Patch, PayloadTooLargeException, Post, Put, RabApi, RabApiError, RequestTimeoutException, ServiceUnavailableException, TooManyRequestsException, UnauthorizedException, UnprocessableEntityException, authHandler, bodyValidatorWithContext, buildCacheKey, controllerHandler, errorHandler, extractTokenFromHeader, hasPurgeKeys, isCallBackPipe, isRouteAController, normalizeCacheConfig, resolvePattern, resolvePurgeKeys, shouldCache };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rabstack/rab-api",
-  "version": "1.8.3",
+  "version": "1.9.1",
   "description": "A TypeScript REST API framework built on Express.js with decorator-based routing, dependency injection, and built-in validation",
   "author": "Softin",
   "license": "MIT",