@rabstack/rab-api 1.11.1 → 1.13.0

package/README.md

@@ -355,38 +355,154 @@ export class ListProducts {}
 - **`url-params`**: Cache key is just the resolved path
   - `/products?page=1&limit=10` → key: `/products`
 
+### How Cache Keys Work
+
+Cache keys are deterministically generated from the request URL to ensure consistent cache hits. Understanding how keys are built helps you design effective caching and purge strategies.
+
+#### Key Generation Process
+
+1. **Extract the path**: The resolved path (with route params filled in) is extracted from the request
+2. **Apply strategy**: Based on the configured strategy, query parameters may be included
+3. **Sort & encode**: Query params are sorted alphabetically and URL-encoded to prevent collisions
+
+```
+Request: GET /stores/123/products?page=2&limit=10&sort=name
+
+url-params strategy → /stores/123/products
+url-query strategy  → /stores/123/products?limit=10&page=2&sort=name
+                      ↑ params sorted alphabetically
+```
+
+#### Why Sorting Matters
+
+Query parameters are sorted alphabetically to ensure the same cache key regardless of parameter order:
+
+```typescript
+// These requests produce the SAME cache key:
+GET /products?limit=10&page=1
+GET /products?page=1&limit=10
+// Both → /products?limit=10&page=1
+```
+
+#### URL Encoding for Safety
+
+Special characters in query values are URL-encoded to prevent cache key collisions:
+
+```typescript
+// Different requests, different cache keys:
+GET /search?q=a&b=2     → /search?b=2&q=a
+GET /search?q=a%26b=2   → /search?q=a%26b%3D2
+```
+
+#### Strategy Selection Guide
+
+| Strategy | Use When | Cache Key Example |
+|----------|----------|-------------------|
+| `url-query` | Response varies by query params (pagination, filters) | `/products?limit=10&page=1` |
+| `url-params` | Response is the same regardless of query params | `/products/123` |
+
 ### Cache Purge
 
-Purge cache keys after mutations:
+Purge (invalidate) cache keys after mutations to keep cached data fresh.
+
+#### How Purge Works
+
+1. **After successful response**: Purge runs only after the handler returns successfully
+2. **Pattern resolution**: `:param` placeholders are replaced with actual request param values
+3. **Background execution**: Purge operations run asynchronously (non-blocking)
+4. **Silent failures**: Purge errors are caught and ignored to avoid breaking the main response
+
+#### Purge Patterns
+
+**Static patterns** - Exact cache keys to invalidate:
 
 ```typescript
 @Post('/products', {
   cache: {
-    purge: ['/products'],  // Purge this key after successful response
+    purge: ['/products'],  // Purge the list endpoint
   }
 })
 export class CreateProduct {}
+```
 
-// With dynamic params
+**Dynamic patterns** - Use `:param` placeholders resolved from request params:
+
+```typescript
 @Put('/products/:id', {
   cache: {
     purge: [
-      '/products',
-      '/products/:id',  // :id is resolved from request params
+      '/products',      // Purge the list
+      '/products/:id',  // :id → resolved to actual value (e.g., /products/123)
     ]
   }
 })
 export class UpdateProduct {}
+```
 
-// Function-based purge
+**Function patterns** - Full control with access to the request object:
+
+```typescript
 @Delete('/products/:id', {
   cache: {
-    purge: [(req) => `/products/${req.params.id}`]
+    purge: [
+      (req) => `/products/${req.params.id}`,
+      (req) => `/categories/${req.body.categoryId}/products`,  // Access body
+      (req) => [  // Return multiple keys
+        `/products/${req.params.id}`,
+        `/products/${req.params.id}/reviews`,
+      ],
+    ]
   }
 })
 export class DeleteProduct {}
 ```
 
+#### Purge Flow Diagram
+
+```
+Request: DELETE /stores/123/products/456
+
+1. Handler executes successfully
+2. Purge patterns resolved:
+   - '/stores/:storeId/products' → '/stores/123/products'
+   - '/stores/:storeId/products/:id' → '/stores/123/products/456'
+3. cacheAdapter.del() called for each key (async, non-blocking)
+4. Response returned to client immediately
+```
+
+#### Common Purge Patterns
+
+```typescript
+// List + detail invalidation
+@Put('/products/:id', {
+  cache: {
+    purge: ['/products', '/products/:id']
+  }
+})
+
+// Hierarchical invalidation
+@Delete('/stores/:storeId/products/:id', {
+  cache: {
+    purge: [
+      '/stores/:storeId/products',           // List
+      '/stores/:storeId/products/:id',       // Detail
+      '/stores/:storeId',                    // Parent
+    ]
+  }
+})
+
+// Cross-entity invalidation
+@Post('/orders', {
+  cache: {
+    purge: [
+      '/orders',
+      (req) => `/users/${req.auth.userId}/orders`,  // User's orders
+      (req) => req.body.items.map(i => `/products/${i.productId}/stock`),
+    ]
+  }
+})
+```
+
 ### Example: Redis Adapter
 
 ```typescript

package/index.cjs.js

@@ -688,22 +688,28 @@ const controllerHandler = (controller, config)=>{
 };
 
 const authHandler = (isProtected, config)=>(req, res, next)=>{
-        console.log('authHandler:', req.path, ':isProtected:', isProtected);
+        var _config_debug;
+        const debug = (_config_debug = config.debug) != null ? _config_debug : false;
+        if (debug) console.log('authHandler:', req.path, ':isProtected:', isProtected);
         const token = extractTokenFromHeader(req);
         // If not protected and no token, just continue
         if (!isProtected && !token) return next();
         // If no token but route is protected, throw error
         if (!token) {
-            console.log('authHandler:UnauthorizedException:Token Not Found');
+            if (debug) console.log('authHandler:UnauthorizedException:Token Not Found');
             throw new UnauthorizedException('Unauthorized', config.errorCode);
         }
-        // Token exists - verify it (must be valid regardless of protection)
+        // Token exists - verify it
         try {
-            const payload = jwt.verify(token, config.jwt.secret_key);
+            const payload = jwt.verify(token, config.jwt.secret_key, {
+                algorithms: config.jwt.algorithms
+            });
             req['auth'] = payload;
             return next();
         } catch (err) {
-            console.error('authHandler:JWT Error:', err.message);
+            // If route is not protected, silently continue without auth
+            if (!isProtected) return next();
+            if (debug) console.error('authHandler:JWT Error:', err.message);
             throw new UnauthorizedException('Unauthorized', config.errorCode);
         }
     };
@@ -1131,7 +1137,9 @@ class AtomExpressApp {
             //auth middleware
             if (this.options.auth) {
                 var _config_isProtected;
-                allPipes.unshift(authHandler((_config_isProtected = config.isProtected) != null ? _config_isProtected : this.options.enforceRouteProtection, this.options.auth));
+                allPipes.unshift(authHandler((_config_isProtected = config.isProtected) != null ? _config_isProtected : this.options.enforceRouteProtection, _extends({}, this.options.auth, {
+                    debug: this.options.debug
+                })));
             }
             //add body validation to validate the schema and inject request context
             if (config.bodySchema && !config.disableBodyValidation) {

package/index.esm.d.ts

@@ -78,6 +78,7 @@ export declare type AtomExpressOptions = {
     errorHandler?: (err: any, req: Request_2, res: Response_2, next: NextFunction) => any;
     enforceBodyValidation?: boolean;
     enforceRouteProtection?: boolean;
+    debug?: boolean;
     auth?: AuthHandlerOptions;
     openapi?: {
         enabled?: boolean;
@@ -124,6 +125,7 @@ export declare const authHandler: (isProtected: boolean, config: AuthHandlerOpti
 
 export declare type AuthHandlerOptions = {
     errorCode?: string;
+    debug?: boolean;
     jwt: {
         secret_key: string;
         algorithms: any;

package/index.esm.js

@@ -686,22 +686,28 @@ const controllerHandler = (controller, config)=>{
 };
 
 const authHandler = (isProtected, config)=>(req, res, next)=>{
-        console.log('authHandler:', req.path, ':isProtected:', isProtected);
+        var _config_debug;
+        const debug = (_config_debug = config.debug) != null ? _config_debug : false;
+        if (debug) console.log('authHandler:', req.path, ':isProtected:', isProtected);
         const token = extractTokenFromHeader(req);
         // If not protected and no token, just continue
         if (!isProtected && !token) return next();
         // If no token but route is protected, throw error
         if (!token) {
-            console.log('authHandler:UnauthorizedException:Token Not Found');
+            if (debug) console.log('authHandler:UnauthorizedException:Token Not Found');
             throw new UnauthorizedException('Unauthorized', config.errorCode);
         }
-        // Token exists - verify it (must be valid regardless of protection)
+        // Token exists - verify it
         try {
-            const payload = jwt.verify(token, config.jwt.secret_key);
+            const payload = jwt.verify(token, config.jwt.secret_key, {
+                algorithms: config.jwt.algorithms
+            });
             req['auth'] = payload;
             return next();
         } catch (err) {
-            console.error('authHandler:JWT Error:', err.message);
+            // If route is not protected, silently continue without auth
+            if (!isProtected) return next();
+            if (debug) console.error('authHandler:JWT Error:', err.message);
             throw new UnauthorizedException('Unauthorized', config.errorCode);
         }
     };
@@ -1129,7 +1135,9 @@ class AtomExpressApp {
             //auth middleware
             if (this.options.auth) {
                 var _config_isProtected;
-                allPipes.unshift(authHandler((_config_isProtected = config.isProtected) != null ? _config_isProtected : this.options.enforceRouteProtection, this.options.auth));
+                allPipes.unshift(authHandler((_config_isProtected = config.isProtected) != null ? _config_isProtected : this.options.enforceRouteProtection, _extends({}, this.options.auth, {
+                    debug: this.options.debug
+                })));
             }
             //add body validation to validate the schema and inject request context
             if (config.bodySchema && !config.disableBodyValidation) {

package/package.json

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