@naman_deep_singh/server-utils 1.0.8 → 1.2.0

package/README.md

@@ -1,6 +1,8 @@
 # @naman_deep_singh/server-utils
 
-Extensible server utilities for Express.js microservices with multi-protocol support and TypeScript.
+**Version:** 1.2.0 (with integrated cache & session support)
+
+Extensible server utilities for Express.js microservices with multi-protocol support, integrated caching, session management, and TypeScript.
 
 ## Installation
 
@@ -11,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
 
@@ -180,9 +184,24 @@ server.app.use('/protected', requireAuth({
 
 ## Health Checks
 
+### Basic Health Check
 ```typescript
-import { addHealthCheck } from '@naman_deep_singh/server-utils';
+import { addHealthCheck, createHealthCheck, withHealthCheck } from '@naman_deep_singh/server-utils';
+
+// Method 1: Direct addition
+addHealthCheck(server.app, '/health');
+
+// Method 2: As middleware
+server.app.get('/health', createHealthCheck());
+
+// Method 3: As plugin
+const server = createServerWithPlugins('My API', '1.0.0', [
+  withHealthCheck('/health')
+]);
+```
 
+### Advanced Health Checks
+```typescript
 addHealthCheck(server.app, '/health', {
   customChecks: [
     {
@@ -200,6 +219,17 @@ addHealthCheck(server.app, '/health', {
     }
   ]
 });
+
+// Response format:
+// {
+//   "status": "healthy",
+//   "checks": {
+//     "server": true,
+//     "timestamp": 1640995200000,
+//     "database": true,
+//     "redis": false
+//   }
+// }
 ```
 
 ## Server Management
@@ -246,12 +276,78 @@ interface ServerConfig {
 }
 ```
 
+## Environment Utilities
+
+```typescript
+import { getEnv, getEnvNumber, getEnvBoolean } from '@naman_deep_singh/server-utils';
+
+// Get string environment variable
+const dbUrl = getEnv('DATABASE_URL'); // Throws if missing
+const dbUrl = getEnv('DATABASE_URL', 'localhost'); // With default
+
+// Get number environment variable
+const port = getEnvNumber('PORT', 3000);
+const maxConnections = getEnvNumber('MAX_CONNECTIONS'); // Throws if missing
+
+// Get boolean environment variable
+const enableLogging = getEnvBoolean('ENABLE_LOGGING', true);
+const isProduction = getEnvBoolean('NODE_ENV'); // Must be 'true' or 'false'
+```
+
+## Periodic Health Monitoring
+
+```typescript
+import { PeriodicHealthMonitor } from '@naman_deep_singh/server-utils';
+
+const server = createServer('My API', '1.0.0', {
+  periodicHealthCheck: {
+    enabled: true,
+    interval: 30000, // 30 seconds
+    services: [
+      {
+        name: 'database',
+        url: 'http://localhost:5432/health',
+        timeout: 5000
+      },
+      {
+        name: 'redis',
+        url: 'http://localhost:6379/ping'
+      }
+    ]
+  }
+});
+
+// Manual health check
+const monitor = new PeriodicHealthMonitor(config, 'My Service');
+monitor.start();
+const status = await monitor.getHealthStatus();
+console.log(status); // { database: true, redis: false }
+```
+
+## Express Re-exports
+
+```typescript
+// Import Express types and classes directly from server-utils
+import { Request, Response, NextFunction, Router, Application } from '@naman_deep_singh/server-utils';
+import type { RequestHandler, ErrorRequestHandler } from '@naman_deep_singh/server-utils';
+
+// No need to install Express separately in your services
+```
+
 ## API Reference
 
 ### Core Functions
 - `createServer(name?, version?, config?)` - Create server instance
 - `ExpressServer` - Server class for advanced usage
 
+### Environment Utilities
+- `getEnv(key, defaultValue?)` - Get string environment variable
+- `getEnvNumber(key, defaultValue?)` - Get number environment variable  
+- `getEnvBoolean(key, defaultValue?)` - Get boolean environment variable
+
+### Health Monitoring
+- `PeriodicHealthMonitor` - Automated service health checking
+
 ### Middleware Functions
 - `createLoggingMiddleware(format?)` - Request logging
 - `createErrorHandler()` - Error handling
@@ -260,8 +356,10 @@ interface ServerConfig {
 - `createAuthMiddleware(config)` - Authentication
 
 ### Health & Monitoring
-- `createHealthCheck(config?)` - Health check endpoint
+- `createHealthCheck(config?)` - Create health check middleware
+- `withHealthCheck(path?, config?)` - Health check plugin
 - `addHealthCheck(app, path?, config?)` - Add health check to app
+- `PeriodicHealthMonitor` - Automated service health checking
 
 ### Graceful Shutdown
 - `createGracefulShutdown(server, config?)` - Setup graceful shutdown
@@ -270,12 +368,304 @@ interface ServerConfig {
 ## Dependencies
 
 ### Required
-- **express** - Web framework
-- **cors** - CORS middleware
-- **helmet** - Security middleware
-- **cookie-parser** - Cookie parsing
+- **express** - Web framework (v5.1.0+)
 
 ### Optional (for specific features)
+- **cors** - CORS middleware (if using CORS)
+- **helmet** - Security middleware (if using Helmet)
+- **cookie-parser** - Cookie parsing (if using cookies)
 - **@grpc/grpc-js** - For gRPC support
 - **jayson** - For JSON-RPC support
-- **socket.io** - For WebSocket support
+- **socket.io** - For WebSocket support
+
+## Response Format
+
+All middleware responses follow the consistent format:
+
+```json
+{
+  "success": true/false,
+  "message": "Operation message",
+  "data": {...} | undefined,
+  "error": {
+    "message": "Error message",
+    "details": {...}
+  } | null,
+  "meta": {...} | null
+}
+```
+
+### Integration with @naman_deep_singh/response-utils
+
+For advanced error handling, use with `@naman_deep_singh/errors-utils`:
+
+```typescript
+import { expressErrorHandler } from '@naman_deep_singh/errors-utils';
+
+// Replace basic error handler with advanced one
+server.app.use(expressErrorHandler);
+```
+
+### Integration with @naman_deep_singh/response-utils
+
+For consistent API responses, use with `@naman_deep_singh/response-utils`:
+
+```typescript
+import { responderMiddleware } from '@naman_deep_singh/response-utils';
+
+server.app.use(responderMiddleware());
+
+// Now use responder in routes
+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/{index.d.ts → 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/{index.js → 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/{middleware.d.ts → 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/{middleware.js → 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) => {
@@ -45,9 +47,14 @@ function createErrorHandler() {
             ? 'Internal Server Error'
             : errorObj.message || 'Unknown error';
         res.status(status).json({
-            status: false,
+            success: false,
             message,
-            ...(process.env.NODE_ENV !== 'production' && { stack: errorObj.stack })
+            data: undefined,
+            error: {
+                message,
+                ...(process.env.NODE_ENV !== 'production' && { details: { stack: errorObj.stack } })
+            },
+            meta: null
         });
     };
 }
@@ -114,9 +121,14 @@ function createValidationMiddleware(rules) {
         }
         if (errors.length > 0) {
             return res.status(400).json({
-                status: false,
+                success: false,
                 message: 'Validation failed',
-                errors
+                data: undefined,
+                error: {
+                    message: 'Validation failed',
+                    details: errors
+                },
+                meta: null
             });
         }
         next();
@@ -138,9 +150,16 @@ function createRateLimitMiddleware(config = {}) {
         }
         if (record.count >= maxRequests) {
             return res.status(429).json({
-                status: false,
+                success: false,
                 message,
-                retryAfter: Math.ceil((record.resetTime - now) / 1000)
+                data: undefined,
+                error: {
+                    message,
+                    details: {
+                        retryAfter: Math.ceil((record.resetTime - now) / 1000)
+                    }
+                },
+                meta: null
             });
         }
         record.count++;
@@ -160,8 +179,13 @@ function createAuthMiddleware(config) {
             const token = tokenExtractor(req);
             if (!token) {
                 return res.status(401).json({
-                    status: false,
-                    message: unauthorizedMessage
+                    success: false,
+                    message: unauthorizedMessage,
+                    data: undefined,
+                    error: {
+                        message: unauthorizedMessage
+                    },
+                    meta: null
                 });
             }
             const user = await tokenValidator(token);
@@ -170,8 +194,13 @@ function createAuthMiddleware(config) {
         }
         catch (error) {
             return res.status(401).json({
-                status: false,
-                message: unauthorizedMessage
+                success: false,
+                message: unauthorizedMessage,
+                data: undefined,
+                error: {
+                    message: unauthorizedMessage
+                },
+                meta: null
             });
         }
     };
@@ -217,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();
+        }
+    };
+}