@rabstack/rab-api 1.11.1 → 1.12.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rabstack/rab-api",
-  "version": "1.11.1",
+  "version": "1.12.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",