@naman_deep_singh/server-utils 1.1.0 → 1.2.0

package/README.md

@@ -1,8 +1,8 @@
 # @naman_deep_singh/server-utils
 
-**Version:** 1.1.0
+**Version:** 1.2.0 (with integrated cache & session support)
 
-Extensible server utilities for Express.js microservices with multi-protocol support and TypeScript.
+Extensible server utilities for Express.js microservices with multi-protocol support, integrated caching, session management, and TypeScript.
 
 ## Installation
 
@@ -13,13 +13,15 @@ npm install @naman_deep_singh/server-utils
 ## Features
 
 - ✅ **Multi-protocol support** - HTTP, gRPC, JSON-RPC, WebSockets, Webhooks
+- ✅ **Integrated caching** - Redis, Memcache, in-memory with automatic fallback
+- ✅ **Session management** - Distributed session store with configurable TTL
 - ✅ **Express.js integration** with middleware collection
-- ✅ **Graceful shutdown** handling
-- ✅ **Health checks** with custom checks support
+- ✅ **Graceful shutdown** handling with cache/session cleanup
+- ✅ **Health checks** with custom checks and cache health integration
 - ✅ **TypeScript support** with full type safety
 - ✅ **Hybrid exports** - use named imports or namespace imports
 - ✅ **Plugin architecture** for extensibility
-- ✅ **Built-in middleware** - logging, validation, rate limiting, auth
+- ✅ **Built-in middleware** - logging, validation, rate limiting, auth, caching, sessions
 
 ## Quick Start
 
@@ -418,4 +420,252 @@ server.app.get('/users', (req, res) => {
   const responder = (res as any).responder();
   return responder.okAndSend({ users: [] });
 });
+```
+
+## Cache & Session Integration
+
+Built-in support for distributed caching and session management (disabled by default).
+
+### Enable Redis Cache
+
+```typescript
+const server = createServer('My API', '1.0.0', {
+  port: 3000,
+  cache: {
+    enabled: true,
+    adapter: 'redis',
+    options: {
+      host: 'localhost',
+      port: 6379,
+      password: 'your_password'
+    },
+    defaultTTL: 3600 // seconds
+  }
+});
+
+// Access cache in routes
+server.app.get('/user/:id', async (req, res) => {
+  const key = `user:${req.params.id}`;
+  const cached = await (req as any).cache.get(key);
+  if (cached) return res.json(cached);
+
+  // Fetch from DB, then cache
+  const user = { id: req.params.id, name: 'John' };
+  await (req as any).cache.set(key, user, 3600);
+  return res.json(user);
+});
+```
+
+### Enable Redis Cluster Cache
+
+```typescript
+const server = createServer('My API', '1.0.0', {
+  port: 3000,
+  cache: {
+    enabled: true,
+    adapter: 'redis',
+    options: {
+      cluster: [
+        { host: 'redis-node-1', port: 6379 },
+        { host: 'redis-node-2', port: 6379 },
+        { host: 'redis-node-3', port: 6379 }
+      ]
+    }
+  }
+});
+```
+
+### Enable Memcache
+
+```typescript
+const server = createServer('My API', '1.0.0', {
+  port: 3000,
+  cache: {
+    enabled: true,
+    adapter: 'memcache',
+    options: {
+      servers: ['localhost:11211', 'localhost:11212']
+    }
+  }
+});
+```
+
+### Enable Sessions
+
+```typescript
+const server = createServer('My API', '1.0.0', {
+  port: 3000,
+  cache: {
+    enabled: true,
+    adapter: 'redis',
+    options: { host: 'localhost', port: 6379 }
+  },
+  session: {
+    enabled: true,
+    cookieName: 'my_app.sid', // Defaults to {servername}.sid
+    ttl: 3600, // 1 hour
+    cookieOptions: {
+      httpOnly: true,
+      secure: true, // HTTPS only
+      sameSite: 'strict'
+    }
+  }
+});
+
+// Use sessions in routes
+server.app.post('/login', async (req, res) => {
+  const sessionStore = (req.app as any).locals.sessionStore;
+  const sessionId = Math.random().toString(36).substring(7);
+
+  await sessionStore.create(sessionId, {
+    userId: 123,
+    username: 'john_doe',
+    loginTime: new Date()
+  });
+
+  res.cookie((req.app as any).locals.sessionCookieName, sessionId, {
+    httpOnly: true,
+    secure: true
+  });
+
+  return res.json({ message: 'Logged in' });
+});
+
+server.app.get('/profile', async (req, res) => {
+  const sessionId = (req as any).sessionId;
+  if (!sessionId) return res.status(401).json({ error: 'No session' });
+
+  const session = await (req as any).getSession();
+  if (!session) return res.status(401).json({ error: 'Session expired' });
+
+  return res.json({ user: session.username, loginTime: session.loginTime });
+});
+```
+
+### Per-Route Response Caching
+
+```typescript
+import { cacheResponse } from '@naman_deep_singh/server-utils';
+
+// Cache GET response for 1 hour (3600 seconds)
+server.app.get('/api/posts', cacheResponse(3600), (req, res) => {
+  // This endpoint's response is cached
+  res.json({ posts: [...] });
+});
+
+// Cache with default TTL from server config
+server.app.get('/api/trending', cacheResponse(), (req, res) => {
+  res.json({ trending: [...] });
+});
+```
+
+### Health Check with Cache Status
+
+```typescript
+const server = createServer('My API', '1.0.0', {
+  healthCheck: '/health', // Automatic health endpoint
+  cache: { enabled: true, adapter: 'redis', ... }
+});
+
+// Health endpoint now includes cache status
+// GET /health returns:
+// {
+//   "status": "healthy",
+//   "service": "My API",
+//   "version": "1.0.0",
+//   "uptime": 12345,
+//   "timestamp": "2025-12-12T...",
+//   "cache": {
+//     "isAlive": true,
+//     "adapter": "redis",
+//     "timestamp": "2025-12-12T..."
+//   }
+// }
+```
+
+### Cache Configuration Options
+
+All configuration is optional — cache and session are disabled by default:
+
+```typescript
+interface CacheConfig {
+  enabled?: boolean;          // Default: false
+  adapter?: 'redis' | 'memcache' | 'memory'; // Default: 'memory'
+  options?: {
+    // Redis single instance
+    host?: string;           // Default: 'localhost'
+    port?: number;           // Default: 6379
+    username?: string;
+    password?: string;
+    db?: number;             // 0-15
+    tls?: boolean;
+    
+    // Redis cluster
+    cluster?: Array<{ host: string; port: number }> | {
+      nodes: Array<{ host: string; port: number }>;
+      options?: { maxRedirections?: number; ... };
+    };
+    
+    // Memcache
+    servers?: string | string[]; // e.g., 'localhost:11211'
+    
+    namespace?: string;      // Key prefix
+    ttl?: number;           // Default TTL in seconds
+  };
+  defaultTTL?: number;        // Fallback TTL for routes
+}
+
+interface SessionConfig {
+  enabled?: boolean;          // Default: false
+  cookieName?: string;        // Default: {servername}.sid
+  ttl?: number;              // Default: 3600 (1 hour)
+  cookieOptions?: {
+    path?: string;
+    httpOnly?: boolean;      // Default: true
+    secure?: boolean;        // HTTPS only
+    sameSite?: 'lax' | 'strict' | 'none';
+  };
+}
+```
+
+### Graceful Shutdown
+
+Cache and session stores are automatically closed on graceful shutdown:
+
+```typescript
+const server = createServer('My API', '1.0.0', {
+  gracefulShutdown: true, // Enabled by default
+  cache: { enabled: true, adapter: 'redis', ... },
+  session: { enabled: true, ... }
+});
+
+// On SIGTERM/SIGINT, server will:
+// 1. Stop accepting requests
+// 2. Close cache connection (Redis/Memcache)
+// 3. Close session store
+// 4. Exit gracefully
+```
+
+## Feature Flags
+
+All major features can be toggled independently:
+
+```typescript
+const server = createServer('My API', '1.0.0', {
+  port: 3000,
+  cors: true,              // Default: true
+  helmet: true,            // Default: true
+  json: true,              // Default: true
+  cookieParser: false,     // Default: false
+  healthCheck: '/health',  // Default: true
+  gracefulShutdown: true,  // Default: true
+  cache: { enabled: false }, // Default: disabled
+  session: { enabled: false }, // Default: disabled
+  socketIO: { enabled: false }, // Default: disabled
+  periodicHealthCheck: { // Default: disabled
+    enabled: false,
+    interval: 30000,
+    services: [...]
+  }
+});
 ```

package/dist/cjs/index.d.ts

@@ -4,7 +4,7 @@ export { Request, Response, NextFunction, Router, Application } from 'express';
 export type { RequestHandler, ErrorRequestHandler } from 'express';
 export { createHealthCheck, withHealthCheck, addHealthCheck } from './health';
 export { createGracefulShutdown, withGracefulShutdown, startServerWithShutdown } from './shutdown';
-export { createLoggingMiddleware, createErrorHandler, createRequestIdMiddleware, createValidationMiddleware, createRateLimitMiddleware, createAuthMiddleware, withLogging, withErrorHandler, withRequestId, withValidation, withRateLimit, withAuth, validateFields, rateLimit, requireAuth, type ValidationRule, type RateLimitConfig, type AuthConfig } from './middleware';
+export { createLoggingMiddleware, createErrorHandler, createRequestIdMiddleware, createValidationMiddleware, createRateLimitMiddleware, createAuthMiddleware, withLogging, withErrorHandler, withRequestId, withValidation, withRateLimit, withAuth, validateFields, rateLimit, requireAuth, cacheResponse, useSession, type ValidationRule, type RateLimitConfig, type AuthConfig } from './middleware';
 export { getEnv, getEnvNumber, getEnvBoolean } from './utils';
 export { PeriodicHealthMonitor } from './periodic-health';
 export type { ServerConfig, HealthCheckConfig, HealthCheck, GracefulShutdownConfig, ServerPlugin, SocketIOConfig, SocketInstance, PeriodicHealthCheckConfig, HealthCheckService } from './types';

package/dist/cjs/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PeriodicHealthMonitor = exports.getEnvBoolean = exports.getEnvNumber = exports.getEnv = exports.requireAuth = exports.rateLimit = exports.validateFields = exports.withAuth = exports.withRateLimit = exports.withValidation = exports.withRequestId = exports.withErrorHandler = exports.withLogging = exports.createAuthMiddleware = exports.createRateLimitMiddleware = exports.createValidationMiddleware = exports.createRequestIdMiddleware = exports.createErrorHandler = exports.createLoggingMiddleware = exports.startServerWithShutdown = exports.withGracefulShutdown = exports.createGracefulShutdown = exports.addHealthCheck = exports.withHealthCheck = exports.createHealthCheck = exports.Router = exports.createServer = exports.ExpressServer = void 0;
+exports.PeriodicHealthMonitor = exports.getEnvBoolean = exports.getEnvNumber = exports.getEnv = exports.useSession = exports.cacheResponse = exports.requireAuth = exports.rateLimit = exports.validateFields = exports.withAuth = exports.withRateLimit = exports.withValidation = exports.withRequestId = exports.withErrorHandler = exports.withLogging = exports.createAuthMiddleware = exports.createRateLimitMiddleware = exports.createValidationMiddleware = exports.createRequestIdMiddleware = exports.createErrorHandler = exports.createLoggingMiddleware = exports.startServerWithShutdown = exports.withGracefulShutdown = exports.createGracefulShutdown = exports.addHealthCheck = exports.withHealthCheck = exports.createHealthCheck = exports.Router = exports.createServer = exports.ExpressServer = void 0;
 // Core server utilities
 var server_1 = require("./server");
 Object.defineProperty(exports, "ExpressServer", { enumerable: true, get: function () { return server_1.ExpressServer; } });
@@ -35,6 +35,8 @@ Object.defineProperty(exports, "withAuth", { enumerable: true, get: function ()
 Object.defineProperty(exports, "validateFields", { enumerable: true, get: function () { return middleware_1.validateFields; } });
 Object.defineProperty(exports, "rateLimit", { enumerable: true, get: function () { return middleware_1.rateLimit; } });
 Object.defineProperty(exports, "requireAuth", { enumerable: true, get: function () { return middleware_1.requireAuth; } });
+Object.defineProperty(exports, "cacheResponse", { enumerable: true, get: function () { return middleware_1.cacheResponse; } });
+Object.defineProperty(exports, "useSession", { enumerable: true, get: function () { return middleware_1.useSession; } });
 // Utility functions
 var utils_1 = require("./utils");
 Object.defineProperty(exports, "getEnv", { enumerable: true, get: function () { return utils_1.getEnv; } });

package/dist/cjs/middleware.d.ts

@@ -35,3 +35,5 @@ export declare function withAuth(config: AuthConfig): ServerPlugin;
 export declare function validateFields(rules: ValidationRule[]): express.RequestHandler;
 export declare function rateLimit(config?: RateLimitConfig): express.RequestHandler;
 export declare function requireAuth(config: AuthConfig): express.RequestHandler;
+export declare function cacheResponse(ttl?: number): express.RequestHandler;
+export declare function useSession(cookieName?: string): express.RequestHandler;

package/dist/cjs/middleware.js

@@ -15,6 +15,8 @@ exports.withAuth = withAuth;
 exports.validateFields = validateFields;
 exports.rateLimit = rateLimit;
 exports.requireAuth = requireAuth;
+exports.cacheResponse = cacheResponse;
+exports.useSession = useSession;
 // Logging middleware
 function createLoggingMiddleware(format = 'simple') {
     return (req, res, next) => {
@@ -244,3 +246,101 @@ function rateLimit(config = {}) {
 function requireAuth(config) {
     return createAuthMiddleware(config);
 }
+// Cache response middleware (per-route opt-in)
+function cacheResponse(ttl) {
+    return async (req, res, next) => {
+        try {
+            if (req.method !== 'GET')
+                return next();
+            const cache = req.cache || req.app.locals.cache;
+            const defaultTTL = req.app.locals.cacheDefaultTTL;
+            if (!cache)
+                return next();
+            const key = `${req.originalUrl}`;
+            try {
+                const cached = await cache.get(key);
+                if (cached !== null && cached !== undefined) {
+                    res.setHeader('X-Cache', 'HIT');
+                    return res.json(cached);
+                }
+            }
+            catch (cacheErr) {
+                console.error(`[Cache] Failed to retrieve key "${key}":`, cacheErr);
+                // Continue without cache hit
+            }
+            const originalJson = res.json.bind(res);
+            res.json = (body) => {
+                try {
+                    const expiry = ttl ?? defaultTTL;
+                    if (expiry && cache) {
+                        cache.set(key, body, expiry).catch((err) => {
+                            console.error(`[Cache] Failed to set key "${key}" with TTL ${expiry}:`, err);
+                        });
+                    }
+                    else if (cache) {
+                        cache.set(key, body).catch((err) => {
+                            console.error(`[Cache] Failed to set key "${key}":`, err);
+                        });
+                    }
+                }
+                catch (e) {
+                    console.error(`[Cache] Error during cache.set operation:`, e);
+                }
+                res.setHeader('X-Cache', 'MISS');
+                return originalJson(body);
+            };
+            next();
+        }
+        catch (err) {
+            console.error('[Cache] Unexpected error in cacheResponse middleware:', err);
+            next();
+        }
+    };
+}
+// Session middleware helper (attaches sessionStore and helpers to req)
+function useSession(cookieName) {
+    return async (req, res, next) => {
+        try {
+            const store = req.app.locals.sessionStore;
+            if (!store)
+                return next();
+            const name = cookieName || req.app.locals.sessionCookieName || 'sid';
+            let sid = req.cookies?.[name] || req.cookies?.[name];
+            if (!sid) {
+                const cookieHeader = req.headers.cookie;
+                if (cookieHeader) {
+                    const match = cookieHeader.split(';').map(s => s.trim()).find(s => s.startsWith(name + '='));
+                    if (match)
+                        sid = match.split('=')[1];
+                }
+            }
+            req.sessionId = sid;
+            req.sessionStore = store;
+            req.getSession = async () => {
+                if (!sid)
+                    return null;
+                try {
+                    return await store.get(sid);
+                }
+                catch (err) {
+                    console.error(`[Session] Failed to get session "${sid}":`, err);
+                    throw err;
+                }
+            };
+            req.createSession = async (id, data, ttl) => {
+                try {
+                    return await store.create(id, data, ttl);
+                }
+                catch (err) {
+                    console.error(`[Session] Failed to create session "${id}":`, err);
+                    throw err;
+                }
+            };
+            next();
+        }
+        catch (err) {
+            console.error('[Session] Unexpected error in useSession middleware:', err);
+            next();
+        }
+    };
+}

package/dist/cjs/server.d.ts

@@ -57,6 +57,7 @@ export declare class ExpressServer implements ServerInstance {
     private healthMonitor?;
     constructor(name?: string, version?: string, config?: ServerConfig);
     private setupMiddleware;
+    private setupCacheAndSession;
     private setupPeriodicHealthMonitoring;
     start(): Promise<ServerInstance>;
     stop(): Promise<void>;

package/dist/cjs/server.js

@@ -9,6 +9,7 @@ const express_1 = __importDefault(require("express"));
 const shutdown_1 = require("./shutdown");
 const periodic_health_1 = require("./periodic-health");
 const crypto_1 = __importDefault(require("crypto"));
+const cache_1 = require("@naman_deep_singh/cache");
 class ExpressServer {
     constructor(name = 'Express Server', version = '1.0.0', config = {}) {
         this.status = 'stopped';
@@ -28,8 +29,14 @@ class ExpressServer {
             healthCheck: config.healthCheck ?? true,
             gracefulShutdown: config.gracefulShutdown ?? true,
             socketIO: config.socketIO,
-            periodicHealthCheck: config.periodicHealthCheck || { enabled: false }
+            periodicHealthCheck: config.periodicHealthCheck || { enabled: false },
+            cache: config.cache || { enabled: false },
+            session: config.session || { enabled: false }
         };
+        // Initialize locals for cache/session
+        this.app.locals.cache = undefined;
+        this.app.locals.sessionStore = undefined;
+        this.app.locals.cacheDefaultTTL = config.cache?.defaultTTL;
         // Apply middleware based on configuration
         this.setupMiddleware();
         // Setup periodic health monitoring
@@ -80,17 +87,104 @@ class ExpressServer {
         // Add health check if enabled
         if (this.config.healthCheck) {
             const healthPath = typeof this.config.healthCheck === 'string' ? this.config.healthCheck : '/health';
-            this.app.get(healthPath, (req, res) => {
-                res.status(200).json({
+            this.app.get(healthPath, async (req, res) => {
+                const base = {
                     status: 'healthy',
                     service: this.config.name,
                     version: this.config.version,
                     uptime: Date.now() - this.config.startTime.getTime(),
                     timestamp: new Date().toISOString()
-                });
+                };
+                // If cache is enabled, include its health
+                const cache = req.app.locals.cache;
+                if (cache && typeof cache.isAlive === 'function') {
+                    try {
+                        base.cache = await cache.isAlive();
+                    }
+                    catch (e) {
+                        base.cache = { isAlive: false, adapter: 'unknown', timestamp: new Date(), error: e.message };
+                    }
+                }
+                res.status(200).json(base);
             });
         }
     }
+    async setupCacheAndSession(config, serverName) {
+        try {
+            // Initialize cache if enabled
+            if (config.cache && config.cache.enabled) {
+                try {
+                    const provided = config.cache.options;
+                    let cacheConfig = provided && typeof provided === 'object' ? provided : undefined;
+                    if (!cacheConfig) {
+                        cacheConfig = { adapter: config.cache.adapter || 'memory' };
+                    }
+                    console.log(`🔄 [${serverName}] Initializing cache adapter: ${config.cache.adapter || 'memory'}...`);
+                    // Use createWithFallback to prefer primary and fall back to memory when configured
+                    const cache = await cache_1.CacheFactory.createWithFallback({
+                        ...(cacheConfig || {}),
+                        ttl: cacheConfig?.ttl ?? config.cache?.defaultTTL
+                    });
+                    this.app.locals.cache = cache;
+                    this.cache = cache;
+                    this.app.locals.cacheDefaultTTL = config.cache?.defaultTTL;
+                    // attach per-request helper middleware
+                    this.app.use((req, _res, next) => {
+                        req.cache = cache;
+                        next();
+                    });
+                    console.log(`✅ [${serverName}] Cache initialized successfully (adapter: ${(cacheConfig.adapter || 'memory')})`);
+                }
+                catch (err) {
+                    console.error(`❌ [${serverName}] Failed to initialize cache (fallback to memory if enabled):`, err instanceof Error ? err.message : err);
+                    // Cache initialization error is critical but we continue to allow graceful fallback
+                }
+            }
+            // Initialize session if enabled
+            if (config.session && config.session.enabled) {
+                const cookieName = config.session.cookieName || `${serverName.replace(/\s+/g, '_').toLowerCase()}.sid`;
+                const ttl = config.session.ttl ?? 3600;
+                let cache = this.app.locals.cache;
+                if (!cache) {
+                    // fallback to in-memory cache for session store
+                    try {
+                        cache = cache_1.CacheFactory.create({ adapter: 'memory' });
+                        this.app.locals.cache = cache;
+                        this.cache = cache;
+                        console.log(`📝 [${serverName}] Session store using in-memory cache`);
+                    }
+                    catch (e) {
+                        console.error(`❌ [${serverName}] Failed to create in-memory cache for sessions:`, e instanceof Error ? e.message : e);
+                    }
+                }
+                else {
+                    console.log(`📝 [${serverName}] Session store initialized with configured cache adapter`);
+                }
+                if (!cache) {
+                    console.error(`❌ [${serverName}] CRITICAL: Session enabled but no cache available to store sessions. Session functionality will be unavailable.`);
+                }
+                else {
+                    const store = new cache_1.SessionStore(cache, { ttl });
+                    this.app.locals.sessionStore = store;
+                    this.app.locals.sessionCookieName = cookieName;
+                    this.sessionStore = store;
+                    // attach session middleware globally so req.sessionStore is available
+                    try {
+                        // eslint-disable-next-line @typescript-eslint/no-var-requires
+                        const { useSession } = require('./middleware');
+                        this.app.use(useSession(cookieName));
+                        console.log(`✅ [${serverName}] Session middleware enabled (cookie: ${cookieName}, TTL: ${ttl}s)`);
+                    }
+                    catch (err) {
+                        console.error(`❌ [${serverName}] Session middleware not available:`, err instanceof Error ? err.message : err);
+                    }
+                }
+            }
+        }
+        catch (err) {
+            console.error(`❌ [${serverName}] Error during cache/session setup:`, err instanceof Error ? err.message : err);
+        }
+    }
     setupPeriodicHealthMonitoring() {
         if (this.config.periodicHealthCheck?.enabled) {
             this.healthMonitor = new periodic_health_1.PeriodicHealthMonitor(this.config.periodicHealthCheck, this.config.name);
@@ -98,6 +192,8 @@ class ExpressServer {
     }
     async start() {
         this.status = 'starting';
+        // Initialize cache and session before starting the server
+        await this.setupCacheAndSession(this.config, this.config.name);
         return new Promise((resolve, reject) => {
             try {
                 this.server = this.app.listen(this.config.port, () => {
@@ -111,6 +207,25 @@ class ExpressServer {
                                 if (this.healthMonitor) {
                                     this.healthMonitor.stop();
                                 }
+                                // Close cache and session store if present
+                                try {
+                                    const cache = this.app.locals.cache;
+                                    if (cache && typeof cache.close === 'function') {
+                                        await cache.close();
+                                    }
+                                }
+                                catch (e) {
+                                    console.warn(`${this.config.name}: Error closing cache`, e);
+                                }
+                                try {
+                                    const store = this.app.locals.sessionStore;
+                                    if (store && typeof store.close === 'function') {
+                                        await store.close();
+                                    }
+                                }
+                                catch (e) {
+                                    // SessionStore may not have close; ignore
+                                }
                             }
                         });
                     }

package/dist/cjs/types.d.ts

@@ -22,6 +22,23 @@ export interface ServerConfig {
     periodicHealthCheck?: PeriodicHealthCheckConfig;
     name?: string;
     version?: string;
+    cache?: {
+        enabled?: boolean;
+        adapter?: 'redis' | 'memcache' | 'memory';
+        options?: unknown;
+        defaultTTL?: number;
+    };
+    session?: {
+        enabled?: boolean;
+        cookieName?: string;
+        ttl?: number;
+        cookieOptions?: {
+            path?: string;
+            httpOnly?: boolean;
+            secure?: boolean;
+            sameSite?: 'lax' | 'strict' | 'none';
+        };
+    };
 }
 export interface PeriodicHealthCheckConfig {
     enabled?: boolean;

package/dist/esm/index.d.ts

@@ -4,7 +4,7 @@ export { Request, Response, NextFunction, Router, Application } from 'express';
 export type { RequestHandler, ErrorRequestHandler } from 'express';
 export { createHealthCheck, withHealthCheck, addHealthCheck } from './health';
 export { createGracefulShutdown, withGracefulShutdown, startServerWithShutdown } from './shutdown';
-export { createLoggingMiddleware, createErrorHandler, createRequestIdMiddleware, createValidationMiddleware, createRateLimitMiddleware, createAuthMiddleware, withLogging, withErrorHandler, withRequestId, withValidation, withRateLimit, withAuth, validateFields, rateLimit, requireAuth, type ValidationRule, type RateLimitConfig, type AuthConfig } from './middleware';
+export { createLoggingMiddleware, createErrorHandler, createRequestIdMiddleware, createValidationMiddleware, createRateLimitMiddleware, createAuthMiddleware, withLogging, withErrorHandler, withRequestId, withValidation, withRateLimit, withAuth, validateFields, rateLimit, requireAuth, cacheResponse, useSession, type ValidationRule, type RateLimitConfig, type AuthConfig } from './middleware';
 export { getEnv, getEnvNumber, getEnvBoolean } from './utils';
 export { PeriodicHealthMonitor } from './periodic-health';
 export type { ServerConfig, HealthCheckConfig, HealthCheck, GracefulShutdownConfig, ServerPlugin, SocketIOConfig, SocketInstance, PeriodicHealthCheckConfig, HealthCheckService } from './types';

package/dist/esm/index.js

@@ -7,7 +7,7 @@ export { createHealthCheck, withHealthCheck, addHealthCheck } from './health';
 // Graceful shutdown utilities
 export { createGracefulShutdown, withGracefulShutdown, startServerWithShutdown } from './shutdown';
 // Middleware utilities
-export { createLoggingMiddleware, createErrorHandler, createRequestIdMiddleware, createValidationMiddleware, createRateLimitMiddleware, createAuthMiddleware, withLogging, withErrorHandler, withRequestId, withValidation, withRateLimit, withAuth, validateFields, rateLimit, requireAuth } from './middleware';
+export { createLoggingMiddleware, createErrorHandler, createRequestIdMiddleware, createValidationMiddleware, createRateLimitMiddleware, createAuthMiddleware, withLogging, withErrorHandler, withRequestId, withValidation, withRateLimit, withAuth, validateFields, rateLimit, requireAuth, cacheResponse, useSession } from './middleware';
 // Utility functions
 export { getEnv, getEnvNumber, getEnvBoolean } from './utils';
 // Periodic health monitoring

package/dist/esm/middleware.d.ts

@@ -35,3 +35,5 @@ export declare function withAuth(config: AuthConfig): ServerPlugin;
 export declare function validateFields(rules: ValidationRule[]): express.RequestHandler;
 export declare function rateLimit(config?: RateLimitConfig): express.RequestHandler;
 export declare function requireAuth(config: AuthConfig): express.RequestHandler;
+export declare function cacheResponse(ttl?: number): express.RequestHandler;
+export declare function useSession(cookieName?: string): express.RequestHandler;

package/dist/esm/middleware.js

@@ -227,3 +227,101 @@ export function rateLimit(config = {}) {
 export function requireAuth(config) {
     return createAuthMiddleware(config);
 }
+// Cache response middleware (per-route opt-in)
+export function cacheResponse(ttl) {
+    return async (req, res, next) => {
+        try {
+            if (req.method !== 'GET')
+                return next();
+            const cache = req.cache || req.app.locals.cache;
+            const defaultTTL = req.app.locals.cacheDefaultTTL;
+            if (!cache)
+                return next();
+            const key = `${req.originalUrl}`;
+            try {
+                const cached = await cache.get(key);
+                if (cached !== null && cached !== undefined) {
+                    res.setHeader('X-Cache', 'HIT');
+                    return res.json(cached);
+                }
+            }
+            catch (cacheErr) {
+                console.error(`[Cache] Failed to retrieve key "${key}":`, cacheErr);
+                // Continue without cache hit
+            }
+            const originalJson = res.json.bind(res);
+            res.json = (body) => {
+                try {
+                    const expiry = ttl ?? defaultTTL;
+                    if (expiry && cache) {
+                        cache.set(key, body, expiry).catch((err) => {
+                            console.error(`[Cache] Failed to set key "${key}" with TTL ${expiry}:`, err);
+                        });
+                    }
+                    else if (cache) {
+                        cache.set(key, body).catch((err) => {
+                            console.error(`[Cache] Failed to set key "${key}":`, err);
+                        });
+                    }
+                }
+                catch (e) {
+                    console.error(`[Cache] Error during cache.set operation:`, e);
+                }
+                res.setHeader('X-Cache', 'MISS');
+                return originalJson(body);
+            };
+            next();
+        }
+        catch (err) {
+            console.error('[Cache] Unexpected error in cacheResponse middleware:', err);
+            next();
+        }
+    };
+}
+// Session middleware helper (attaches sessionStore and helpers to req)
+export function useSession(cookieName) {
+    return async (req, res, next) => {
+        try {
+            const store = req.app.locals.sessionStore;
+            if (!store)
+                return next();
+            const name = cookieName || req.app.locals.sessionCookieName || 'sid';
+            let sid = req.cookies?.[name] || req.cookies?.[name];
+            if (!sid) {
+                const cookieHeader = req.headers.cookie;
+                if (cookieHeader) {
+                    const match = cookieHeader.split(';').map(s => s.trim()).find(s => s.startsWith(name + '='));
+                    if (match)
+                        sid = match.split('=')[1];
+                }
+            }
+            req.sessionId = sid;
+            req.sessionStore = store;
+            req.getSession = async () => {
+                if (!sid)
+                    return null;
+                try {
+                    return await store.get(sid);
+                }
+                catch (err) {
+                    console.error(`[Session] Failed to get session "${sid}":`, err);
+                    throw err;
+                }
+            };
+            req.createSession = async (id, data, ttl) => {
+                try {
+                    return await store.create(id, data, ttl);
+                }
+                catch (err) {
+                    console.error(`[Session] Failed to create session "${id}":`, err);
+                    throw err;
+                }
+            };
+            next();
+        }
+        catch (err) {
+            console.error('[Session] Unexpected error in useSession middleware:', err);
+            next();
+        }
+    };
+}

package/dist/esm/server.d.ts

@@ -57,6 +57,7 @@ export declare class ExpressServer implements ServerInstance {
     private healthMonitor?;
     constructor(name?: string, version?: string, config?: ServerConfig);
     private setupMiddleware;
+    private setupCacheAndSession;
     private setupPeriodicHealthMonitoring;
     start(): Promise<ServerInstance>;
     stop(): Promise<void>;

package/dist/esm/server.js

@@ -2,6 +2,7 @@ import express from 'express';
 import { createGracefulShutdown } from './shutdown';
 import { PeriodicHealthMonitor } from './periodic-health';
 import crypto from 'crypto';
+import { CacheFactory, SessionStore } from '@naman_deep_singh/cache';
 export class ExpressServer {
     constructor(name = 'Express Server', version = '1.0.0', config = {}) {
         this.status = 'stopped';
@@ -21,8 +22,14 @@ export class ExpressServer {
             healthCheck: config.healthCheck ?? true,
             gracefulShutdown: config.gracefulShutdown ?? true,
             socketIO: config.socketIO,
-            periodicHealthCheck: config.periodicHealthCheck || { enabled: false }
+            periodicHealthCheck: config.periodicHealthCheck || { enabled: false },
+            cache: config.cache || { enabled: false },
+            session: config.session || { enabled: false }
         };
+        // Initialize locals for cache/session
+        this.app.locals.cache = undefined;
+        this.app.locals.sessionStore = undefined;
+        this.app.locals.cacheDefaultTTL = config.cache?.defaultTTL;
         // Apply middleware based on configuration
         this.setupMiddleware();
         // Setup periodic health monitoring
@@ -73,17 +80,104 @@ export class ExpressServer {
         // Add health check if enabled
         if (this.config.healthCheck) {
             const healthPath = typeof this.config.healthCheck === 'string' ? this.config.healthCheck : '/health';
-            this.app.get(healthPath, (req, res) => {
-                res.status(200).json({
+            this.app.get(healthPath, async (req, res) => {
+                const base = {
                     status: 'healthy',
                     service: this.config.name,
                     version: this.config.version,
                     uptime: Date.now() - this.config.startTime.getTime(),
                     timestamp: new Date().toISOString()
-                });
+                };
+                // If cache is enabled, include its health
+                const cache = req.app.locals.cache;
+                if (cache && typeof cache.isAlive === 'function') {
+                    try {
+                        base.cache = await cache.isAlive();
+                    }
+                    catch (e) {
+                        base.cache = { isAlive: false, adapter: 'unknown', timestamp: new Date(), error: e.message };
+                    }
+                }
+                res.status(200).json(base);
             });
         }
     }
+    async setupCacheAndSession(config, serverName) {
+        try {
+            // Initialize cache if enabled
+            if (config.cache && config.cache.enabled) {
+                try {
+                    const provided = config.cache.options;
+                    let cacheConfig = provided && typeof provided === 'object' ? provided : undefined;
+                    if (!cacheConfig) {
+                        cacheConfig = { adapter: config.cache.adapter || 'memory' };
+                    }
+                    console.log(`🔄 [${serverName}] Initializing cache adapter: ${config.cache.adapter || 'memory'}...`);
+                    // Use createWithFallback to prefer primary and fall back to memory when configured
+                    const cache = await CacheFactory.createWithFallback({
+                        ...(cacheConfig || {}),
+                        ttl: cacheConfig?.ttl ?? config.cache?.defaultTTL
+                    });
+                    this.app.locals.cache = cache;
+                    this.cache = cache;
+                    this.app.locals.cacheDefaultTTL = config.cache?.defaultTTL;
+                    // attach per-request helper middleware
+                    this.app.use((req, _res, next) => {
+                        req.cache = cache;
+                        next();
+                    });
+                    console.log(`✅ [${serverName}] Cache initialized successfully (adapter: ${(cacheConfig.adapter || 'memory')})`);
+                }
+                catch (err) {
+                    console.error(`❌ [${serverName}] Failed to initialize cache (fallback to memory if enabled):`, err instanceof Error ? err.message : err);
+                    // Cache initialization error is critical but we continue to allow graceful fallback
+                }
+            }
+            // Initialize session if enabled
+            if (config.session && config.session.enabled) {
+                const cookieName = config.session.cookieName || `${serverName.replace(/\s+/g, '_').toLowerCase()}.sid`;
+                const ttl = config.session.ttl ?? 3600;
+                let cache = this.app.locals.cache;
+                if (!cache) {
+                    // fallback to in-memory cache for session store
+                    try {
+                        cache = CacheFactory.create({ adapter: 'memory' });
+                        this.app.locals.cache = cache;
+                        this.cache = cache;
+                        console.log(`📝 [${serverName}] Session store using in-memory cache`);
+                    }
+                    catch (e) {
+                        console.error(`❌ [${serverName}] Failed to create in-memory cache for sessions:`, e instanceof Error ? e.message : e);
+                    }
+                }
+                else {
+                    console.log(`📝 [${serverName}] Session store initialized with configured cache adapter`);
+                }
+                if (!cache) {
+                    console.error(`❌ [${serverName}] CRITICAL: Session enabled but no cache available to store sessions. Session functionality will be unavailable.`);
+                }
+                else {
+                    const store = new SessionStore(cache, { ttl });
+                    this.app.locals.sessionStore = store;
+                    this.app.locals.sessionCookieName = cookieName;
+                    this.sessionStore = store;
+                    // attach session middleware globally so req.sessionStore is available
+                    try {
+                        // eslint-disable-next-line @typescript-eslint/no-var-requires
+                        const { useSession } = require('./middleware');
+                        this.app.use(useSession(cookieName));
+                        console.log(`✅ [${serverName}] Session middleware enabled (cookie: ${cookieName}, TTL: ${ttl}s)`);
+                    }
+                    catch (err) {
+                        console.error(`❌ [${serverName}] Session middleware not available:`, err instanceof Error ? err.message : err);
+                    }
+                }
+            }
+        }
+        catch (err) {
+            console.error(`❌ [${serverName}] Error during cache/session setup:`, err instanceof Error ? err.message : err);
+        }
+    }
     setupPeriodicHealthMonitoring() {
         if (this.config.periodicHealthCheck?.enabled) {
             this.healthMonitor = new PeriodicHealthMonitor(this.config.periodicHealthCheck, this.config.name);
@@ -91,6 +185,8 @@ export class ExpressServer {
     }
     async start() {
         this.status = 'starting';
+        // Initialize cache and session before starting the server
+        await this.setupCacheAndSession(this.config, this.config.name);
         return new Promise((resolve, reject) => {
             try {
                 this.server = this.app.listen(this.config.port, () => {
@@ -104,6 +200,25 @@ export class ExpressServer {
                                 if (this.healthMonitor) {
                                     this.healthMonitor.stop();
                                 }
+                                // Close cache and session store if present
+                                try {
+                                    const cache = this.app.locals.cache;
+                                    if (cache && typeof cache.close === 'function') {
+                                        await cache.close();
+                                    }
+                                }
+                                catch (e) {
+                                    console.warn(`${this.config.name}: Error closing cache`, e);
+                                }
+                                try {
+                                    const store = this.app.locals.sessionStore;
+                                    if (store && typeof store.close === 'function') {
+                                        await store.close();
+                                    }
+                                }
+                                catch (e) {
+                                    // SessionStore may not have close; ignore
+                                }
                             }
                         });
                     }

package/dist/esm/types.d.ts

@@ -22,6 +22,23 @@ export interface ServerConfig {
     periodicHealthCheck?: PeriodicHealthCheckConfig;
     name?: string;
     version?: string;
+    cache?: {
+        enabled?: boolean;
+        adapter?: 'redis' | 'memcache' | 'memory';
+        options?: unknown;
+        defaultTTL?: number;
+    };
+    session?: {
+        enabled?: boolean;
+        cookieName?: string;
+        ttl?: number;
+        cookieOptions?: {
+            path?: string;
+            httpOnly?: boolean;
+            secure?: boolean;
+            sameSite?: 'lax' | 'strict' | 'none';
+        };
+    };
 }
 export interface PeriodicHealthCheckConfig {
     enabled?: boolean;

package/dist/types/index.d.ts

@@ -4,7 +4,7 @@ export { Request, Response, NextFunction, Router, Application } from 'express';
 export type { RequestHandler, ErrorRequestHandler } from 'express';
 export { createHealthCheck, withHealthCheck, addHealthCheck } from './health';
 export { createGracefulShutdown, withGracefulShutdown, startServerWithShutdown } from './shutdown';
-export { createLoggingMiddleware, createErrorHandler, createRequestIdMiddleware, createValidationMiddleware, createRateLimitMiddleware, createAuthMiddleware, withLogging, withErrorHandler, withRequestId, withValidation, withRateLimit, withAuth, validateFields, rateLimit, requireAuth, type ValidationRule, type RateLimitConfig, type AuthConfig } from './middleware';
+export { createLoggingMiddleware, createErrorHandler, createRequestIdMiddleware, createValidationMiddleware, createRateLimitMiddleware, createAuthMiddleware, withLogging, withErrorHandler, withRequestId, withValidation, withRateLimit, withAuth, validateFields, rateLimit, requireAuth, cacheResponse, useSession, type ValidationRule, type RateLimitConfig, type AuthConfig } from './middleware';
 export { getEnv, getEnvNumber, getEnvBoolean } from './utils';
 export { PeriodicHealthMonitor } from './periodic-health';
 export type { ServerConfig, HealthCheckConfig, HealthCheck, GracefulShutdownConfig, ServerPlugin, SocketIOConfig, SocketInstance, PeriodicHealthCheckConfig, HealthCheckService } from './types';

package/dist/types/middleware.d.ts

@@ -35,3 +35,5 @@ export declare function withAuth(config: AuthConfig): ServerPlugin;
 export declare function validateFields(rules: ValidationRule[]): express.RequestHandler;
 export declare function rateLimit(config?: RateLimitConfig): express.RequestHandler;
 export declare function requireAuth(config: AuthConfig): express.RequestHandler;
+export declare function cacheResponse(ttl?: number): express.RequestHandler;
+export declare function useSession(cookieName?: string): express.RequestHandler;

package/dist/types/server.d.ts

@@ -57,6 +57,7 @@ export declare class ExpressServer implements ServerInstance {
     private healthMonitor?;
     constructor(name?: string, version?: string, config?: ServerConfig);
     private setupMiddleware;
+    private setupCacheAndSession;
     private setupPeriodicHealthMonitoring;
     start(): Promise<ServerInstance>;
     stop(): Promise<void>;

package/dist/types/types.d.ts

@@ -22,6 +22,23 @@ export interface ServerConfig {
     periodicHealthCheck?: PeriodicHealthCheckConfig;
     name?: string;
     version?: string;
+    cache?: {
+        enabled?: boolean;
+        adapter?: 'redis' | 'memcache' | 'memory';
+        options?: unknown;
+        defaultTTL?: number;
+    };
+    session?: {
+        enabled?: boolean;
+        cookieName?: string;
+        ttl?: number;
+        cookieOptions?: {
+            path?: string;
+            httpOnly?: boolean;
+            secure?: boolean;
+            sameSite?: 'lax' | 'strict' | 'none';
+        };
+    };
 }
 export interface PeriodicHealthCheckConfig {
     enabled?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naman_deep_singh/server-utils",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Extensible server utilities for Express.js microservices with TypeScript",
   "type": "module",
   "main": "./dist/cjs/index.js",
@@ -27,16 +27,17 @@
   "author": "Naman Deep Singh",
   "license": "ISC",
   "dependencies": {
-    "express": "^5.1.0",
-    "cors": "^2.8.5",
-    "helmet": "^8.1.0",
+    "@naman_deep_singh/cache": "^1.2.0",
+    "@types/express": "^5.0.5",
     "cookie-parser": "^1.4.6",
-    "@types/express": "^5.0.5"
+    "cors": "^2.8.5",
+    "express": "^5.1.0",
+    "helmet": "^8.1.0"
   },
   "devDependencies": {
     "@types/cors": "^2.8.19",
-    "typescript": "^5.9.3",
-    "rimraf": "^5.0.5"
+    "rimraf": "^5.0.5",
+    "typescript": "^5.9.3"
   },
   "scripts": {
     "build": "pnpm run build:types && tsc -p tsconfig.cjs.json && tsc -p tsconfig.esm.json",