@rabstack/rab-api 1.8.0 → 1.8.1-next.1

package/index.cjs.js

@@ -518,7 +518,92 @@ var utils = /*#__PURE__*/Object.freeze({
     validateJoiSchema: validateJoiSchema
 });
 
+const DEFAULT_TTL = 900; // 15 minutes
+const DEFAULT_STRATEGY = 'url-params';
+/**
+ * Normalize cache config - handles `cache: true` shorthand
+ */ function normalizeCacheConfig(cache, defaultTtl) {
+    if (!cache) return null;
+    if (cache === true) {
+        return {
+            ttl: defaultTtl != null ? defaultTtl : DEFAULT_TTL,
+            strategy: DEFAULT_STRATEGY
+        };
+    }
+    var _cache_ttl, _ref, _cache_strategy;
+    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
+    };
+}
+/**
+ * Build cache key from request based on strategy
+ * - url-params: resolved path only (e.g., /stores/123/categories)
+ * - url-query: resolved path + sorted query (e.g., /stores/123/categories?lang=en&page=1)
+ */ function buildCacheKey(req, strategy) {
+    var _req_originalUrl;
+    // Get the resolved path (with params filled in)
+    const path = ((_req_originalUrl = req.originalUrl) == null ? void 0 : _req_originalUrl.split('?')[0]) || req.path;
+    // url-params: just the path
+    if (strategy === 'url-params') {
+        return path;
+    }
+    // url-query: path + sorted query string
+    const query = req.query;
+    if (query && Object.keys(query).length > 0) {
+        const sortedQuery = Object.keys(query).sort().map((key)=>`${key}=${query[key]}`).join('&');
+        return `${path}?${sortedQuery}`;
+    }
+    return path;
+}
+/**
+ * Resolve :param placeholders in a pattern using request params
+ */ function resolvePattern(pattern, params) {
+    return pattern.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, (_, paramName)=>{
+        const value = params[paramName];
+        if (value === undefined) {
+            // Keep original if param not found (might be a wildcard pattern)
+            return `:${paramName}`;
+        }
+        return value;
+    });
+}
+/**
+ * Resolve all invalidation patterns for a request
+ */ function resolveInvalidationPatterns(patterns, req) {
+    const resolved = [];
+    for (const pattern of patterns){
+        if (typeof pattern === 'function') {
+            const result = pattern(req);
+            if (Array.isArray(result)) {
+                resolved.push(...result);
+            } else {
+                resolved.push(result);
+            }
+        } else {
+            resolved.push(resolvePattern(pattern, req.params || {}));
+        }
+    }
+    return resolved;
+}
+/**
+ * Check if cache should be applied (has ttl, not just invalidation)
+ */ function shouldCache(config) {
+    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;
+}
+
 const controllerHandler = (controller, config)=>{
+    // Normalize cache config once at setup time
+    const cacheConfig = normalizeCacheConfig(config.cache, config.cacheDefaultTtl);
+    const cacheAdapter = config.cacheAdapter;
+    const isCacheEnabled = cacheConfig && cacheAdapter && shouldCache(cacheConfig);
+    const hasInvalidationPatterns = cacheConfig && hasInvalidations(cacheConfig);
     return async (req, res, next)=>{
         try {
             let query = req.query;
@@ -529,19 +614,45 @@ const controllerHandler = (controller, config)=>{
                     query = await config.validateQuery(req.query);
                 }
             }
+            // Check cache before executing handler
+            if (isCacheEnabled) {
+                const cacheKey = buildCacheKey(req, cacheConfig.strategy);
+                const cached = await cacheAdapter.get(cacheKey);
+                if (cached) {
+                    return res.status(200).json(cached);
+                }
+            }
             const response = await controller.handler(_extends({}, req, {
                 query,
                 body: req.body
             }));
-            var _response_statusCode, _response_statusCode1;
-            return res.status((_response_statusCode = response.statusCode) != null ? _response_statusCode : 200).json(response.excludeMetaData ? response.data : _extends({
+            var _response_statusCode;
+            const jsonResponse = response.excludeMetaData ? response.data : _extends({
                 message: 'successful',
-                statusCode: (_response_statusCode1 = response.statusCode) != null ? _response_statusCode1 : 200
+                statusCode: (_response_statusCode = response.statusCode) != null ? _response_statusCode : 200
             }, response.data ? {
                 data: response.data
             } : {
                 data: response
-            }));
+            });
+            // Cache the response after successful execution
+            if (isCacheEnabled) {
+                const cacheKey = buildCacheKey(req, cacheConfig.strategy);
+                // Don't await - cache in background
+                cacheAdapter.set(cacheKey, jsonResponse, cacheConfig.ttl).catch(()=>{
+                // 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
+                });
+            }
+            var _response_statusCode1;
+            return res.status((_response_statusCode1 = response.statusCode) != null ? _response_statusCode1 : 200).json(jsonResponse);
         } catch (error) {
             if (error instanceof RabApiError) {
                 return next(new RabApiError(error.message, error.statusCode, error.errorCode, error.errors));
@@ -984,11 +1095,13 @@ class AtomExpressApp {
         var _options_auth;
         this.collectedRoutes = [];
         this.setupRouteController = (expressRouter, route, parentOptions)=>{
-            var _config_docs;
+            var _this_options_cache, _this_options_cache1, _config_docs;
             const metaData = retrieveRouteMetaData(route);
             const { method, path, options } = metaData;
             const config = _extends({}, parentOptions, options, {
-                enforceBodyValidation: this.options.enforceBodyValidation
+                enforceBodyValidation: this.options.enforceBodyValidation,
+                cacheAdapter: (_this_options_cache = this.options.cache) == null ? void 0 : _this_options_cache.adapter,
+                cacheDefaultTtl: (_this_options_cache1 = this.options.cache) == null ? void 0 : _this_options_cache1.defaultTtl
             });
             if (method == 'get' && config.querySchema && !config.validateQuery) {
                 const querySchema = config.querySchema;
@@ -1101,8 +1214,14 @@ exports.UnauthorizedException = UnauthorizedException;
 exports.UnprocessableEntityException = UnprocessableEntityException;
 exports.authHandler = authHandler;
 exports.bodyValidatorWithContext = bodyValidatorWithContext;
+exports.buildCacheKey = buildCacheKey;
 exports.controllerHandler = controllerHandler;
 exports.errorHandler = errorHandler;
 exports.extractTokenFromHeader = extractTokenFromHeader;
+exports.hasInvalidations = hasInvalidations;
 exports.isCallBackPipe = isCallBackPipe;
 exports.isRouteAController = isRouteAController;
+exports.normalizeCacheConfig = normalizeCacheConfig;
+exports.resolveInvalidationPatterns = resolveInvalidationPatterns;
+exports.resolvePattern = resolvePattern;
+exports.shouldCache = shouldCache;

package/index.esm.d.ts

@@ -97,6 +97,8 @@ export declare type AtomExpressOptions = {
             }>;
         }>;
     };
+    /** Global cache configuration */
+    cache?: RabApiCacheOptions;
 };
 
 export declare namespace AtomHelpers {
@@ -152,10 +154,36 @@ export declare class BadRequestException extends RabApiError {
 
 export declare const bodyValidatorWithContext: (config: RouteHandleOptions) => (req: any, res: Response_2, next: NextFunction) => Promise<void>;
 
+/**
+ * Build cache key from request based on strategy
+ * - url-params: resolved path only (e.g., /stores/123/categories)
+ * - url-query: resolved path + sorted query (e.g., /stores/123/categories?lang=en&page=1)
+ */
+export declare function buildCacheKey(req: any, strategy: CacheStrategy): string;
+
 export declare type BuildRouterProps = CreateRouterProps & {
     fullPath?: string;
 };
 
+/**
+ * Cache configuration for route decorators
+ */
+export declare interface CacheConfig {
+    /** Time-to-live in seconds (default: 900 = 15 minutes) */
+    ttl?: number;
+    /** Key derivation strategy (default: 'url-params') */
+    strategy?: CacheStrategy;
+    /** URL patterns to invalidate after successful response */
+    invalidates?: InvalidationPattern[];
+}
+
+/**
+ * Cache key strategy
+ * - 'url-params': Uses resolved URL path (e.g., /stores/123/categories)
+ * - 'url-query': Uses resolved URL path + sorted query string
+ */
+export declare type CacheStrategy = 'url-params' | 'url-query';
+
 export declare interface CollectedRoute {
     method: string;
     path: string;
@@ -425,11 +453,26 @@ 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
+ */
+export declare function hasInvalidations(config: CacheConfig): boolean;
+
 /**
  * Supported HTTP methods for route decorators.
  */
 export declare type HttpMethod = 'get' | 'post' | 'put' | 'patch' | 'delete';
 
+/**
+ * Cache adapter interface - implement this to provide your own cache backend (Redis, Memory, etc.)
+ */
+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>;
+}
+
 /**
  * Controller class type definition.
  * Used to define the type shape for controller implementations.
@@ -495,6 +538,8 @@ export declare type InjectorsMetadata<TQuery = any, TBody = any, TResponse = any
     querySchema?: Joi.ObjectSchema<TParams>;
     excludeFromDocs?: boolean;
     docs?: OpenApiDocsMetadata;
+    /** Cache configuration - use `true` for defaults or provide config object */
+    cache?: true | CacheConfig;
 };
 
 /**
@@ -514,6 +559,12 @@ 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;
@@ -553,6 +604,11 @@ export declare class MethodNotAllowedException extends RabApiError {
     constructor(message?: string, errorCode?: string);
 }
 
+/**
+ * Normalize cache config - handles `cache: true` shorthand
+ */
+export declare function normalizeCacheConfig(cache: true | CacheConfig | undefined, defaultTtl?: number): CacheConfig | null;
+
 /**
  * Represents a 404 Not Found error.
  * Use this when a requested resource does not exist.
@@ -775,6 +831,16 @@ export declare class RabApi {
     static createApp(props: AtomExpressOptions): AtomExpressApp;
 }
 
+/**
+ * Global cache configuration for RabApi
+ */
+export declare interface RabApiCacheOptions {
+    /** Cache adapter implementation (Redis, Memory, etc.) */
+    adapter: ICacheAdapter;
+    /** Default TTL in seconds (default: 900 = 15 minutes) */
+    defaultTtl?: number;
+}
+
 /**
  * Base controller interface that all HTTP method controllers implement.
  * Defines the contract for request handlers.
@@ -877,9 +943,24 @@ export declare class RequestTimeoutException extends RabApiError {
     constructor(message?: string, errorCode?: string);
 }
 
+/**
+ * Resolve all invalidation patterns for a request
+ */
+export declare function resolveInvalidationPatterns(patterns: InvalidationPattern[], req: any): string[];
+
+/**
+ * Resolve :param placeholders in a pattern using request params
+ */
+export declare function resolvePattern(pattern: string, params: Record<string, string>): string;
+
 declare function retrieveRouteMetaData(route: ControllerClassType): ControllerRouteDefinition;
 
-export declare type RouteHandleOptions = InjectorsMetadata & Pick<AtomExpressOptions, 'enforceBodyValidation'>;
+export declare type RouteHandleOptions = InjectorsMetadata & Pick<AtomExpressOptions, 'enforceBodyValidation'> & {
+    /** Resolved cache adapter from global options */
+    cacheAdapter?: ICacheAdapter;
+    /** Default TTL from global options */
+    cacheDefaultTtl?: number;
+};
 
 /**
  * Represents a 503 Service Unavailable error.
@@ -898,6 +979,11 @@ export declare class ServiceUnavailableException extends RabApiError {
     constructor(message?: string, errorCode?: string);
 }
 
+/**
+ * Check if cache should be applied (has ttl, not just invalidation)
+ */
+export declare function shouldCache(config: CacheConfig): boolean;
+
 /**
  * Represents a 429 Too Many Requests error.
  * Use this when rate limiting is exceeded.

package/index.esm.js

@@ -516,7 +516,92 @@ var utils = /*#__PURE__*/Object.freeze({
     validateJoiSchema: validateJoiSchema
 });
 
+const DEFAULT_TTL = 900; // 15 minutes
+const DEFAULT_STRATEGY = 'url-params';
+/**
+ * Normalize cache config - handles `cache: true` shorthand
+ */ function normalizeCacheConfig(cache, defaultTtl) {
+    if (!cache) return null;
+    if (cache === true) {
+        return {
+            ttl: defaultTtl != null ? defaultTtl : DEFAULT_TTL,
+            strategy: DEFAULT_STRATEGY
+        };
+    }
+    var _cache_ttl, _ref, _cache_strategy;
+    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
+    };
+}
+/**
+ * Build cache key from request based on strategy
+ * - url-params: resolved path only (e.g., /stores/123/categories)
+ * - url-query: resolved path + sorted query (e.g., /stores/123/categories?lang=en&page=1)
+ */ function buildCacheKey(req, strategy) {
+    var _req_originalUrl;
+    // Get the resolved path (with params filled in)
+    const path = ((_req_originalUrl = req.originalUrl) == null ? void 0 : _req_originalUrl.split('?')[0]) || req.path;
+    // url-params: just the path
+    if (strategy === 'url-params') {
+        return path;
+    }
+    // url-query: path + sorted query string
+    const query = req.query;
+    if (query && Object.keys(query).length > 0) {
+        const sortedQuery = Object.keys(query).sort().map((key)=>`${key}=${query[key]}`).join('&');
+        return `${path}?${sortedQuery}`;
+    }
+    return path;
+}
+/**
+ * Resolve :param placeholders in a pattern using request params
+ */ function resolvePattern(pattern, params) {
+    return pattern.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, (_, paramName)=>{
+        const value = params[paramName];
+        if (value === undefined) {
+            // Keep original if param not found (might be a wildcard pattern)
+            return `:${paramName}`;
+        }
+        return value;
+    });
+}
+/**
+ * Resolve all invalidation patterns for a request
+ */ function resolveInvalidationPatterns(patterns, req) {
+    const resolved = [];
+    for (const pattern of patterns){
+        if (typeof pattern === 'function') {
+            const result = pattern(req);
+            if (Array.isArray(result)) {
+                resolved.push(...result);
+            } else {
+                resolved.push(result);
+            }
+        } else {
+            resolved.push(resolvePattern(pattern, req.params || {}));
+        }
+    }
+    return resolved;
+}
+/**
+ * Check if cache should be applied (has ttl, not just invalidation)
+ */ function shouldCache(config) {
+    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;
+}
+
 const controllerHandler = (controller, config)=>{
+    // Normalize cache config once at setup time
+    const cacheConfig = normalizeCacheConfig(config.cache, config.cacheDefaultTtl);
+    const cacheAdapter = config.cacheAdapter;
+    const isCacheEnabled = cacheConfig && cacheAdapter && shouldCache(cacheConfig);
+    const hasInvalidationPatterns = cacheConfig && hasInvalidations(cacheConfig);
     return async (req, res, next)=>{
         try {
             let query = req.query;
@@ -527,19 +612,45 @@ const controllerHandler = (controller, config)=>{
                     query = await config.validateQuery(req.query);
                 }
             }
+            // Check cache before executing handler
+            if (isCacheEnabled) {
+                const cacheKey = buildCacheKey(req, cacheConfig.strategy);
+                const cached = await cacheAdapter.get(cacheKey);
+                if (cached) {
+                    return res.status(200).json(cached);
+                }
+            }
             const response = await controller.handler(_extends({}, req, {
                 query,
                 body: req.body
             }));
-            var _response_statusCode, _response_statusCode1;
-            return res.status((_response_statusCode = response.statusCode) != null ? _response_statusCode : 200).json(response.excludeMetaData ? response.data : _extends({
+            var _response_statusCode;
+            const jsonResponse = response.excludeMetaData ? response.data : _extends({
                 message: 'successful',
-                statusCode: (_response_statusCode1 = response.statusCode) != null ? _response_statusCode1 : 200
+                statusCode: (_response_statusCode = response.statusCode) != null ? _response_statusCode : 200
             }, response.data ? {
                 data: response.data
             } : {
                 data: response
-            }));
+            });
+            // Cache the response after successful execution
+            if (isCacheEnabled) {
+                const cacheKey = buildCacheKey(req, cacheConfig.strategy);
+                // Don't await - cache in background
+                cacheAdapter.set(cacheKey, jsonResponse, cacheConfig.ttl).catch(()=>{
+                // 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
+                });
+            }
+            var _response_statusCode1;
+            return res.status((_response_statusCode1 = response.statusCode) != null ? _response_statusCode1 : 200).json(jsonResponse);
         } catch (error) {
             if (error instanceof RabApiError) {
                 return next(new RabApiError(error.message, error.statusCode, error.errorCode, error.errors));
@@ -982,11 +1093,13 @@ class AtomExpressApp {
         var _options_auth;
         this.collectedRoutes = [];
         this.setupRouteController = (expressRouter, route, parentOptions)=>{
-            var _config_docs;
+            var _this_options_cache, _this_options_cache1, _config_docs;
             const metaData = retrieveRouteMetaData(route);
             const { method, path, options } = metaData;
             const config = _extends({}, parentOptions, options, {
-                enforceBodyValidation: this.options.enforceBodyValidation
+                enforceBodyValidation: this.options.enforceBodyValidation,
+                cacheAdapter: (_this_options_cache = this.options.cache) == null ? void 0 : _this_options_cache.adapter,
+                cacheDefaultTtl: (_this_options_cache1 = this.options.cache) == null ? void 0 : _this_options_cache1.defaultTtl
             });
             if (method == 'get' && config.querySchema && !config.validateQuery) {
                 const querySchema = config.querySchema;
@@ -1070,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, controllerHandler, errorHandler, extractTokenFromHeader, isCallBackPipe, isRouteAController };
+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 };

package/package.json

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