@naman_deep_singh/server-utils 1.0.8 → 1.1.0

package/README.md

@@ -1,5 +1,7 @@
 # @naman_deep_singh/server-utils
 
+**Version:** 1.1.0
+
 Extensible server utilities for Express.js microservices with multi-protocol support and TypeScript.
 
 ## Installation
@@ -180,9 +182,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 +217,17 @@ addHealthCheck(server.app, '/health', {
     }
   ]
 });
+
+// Response format:
+// {
+//   "status": "healthy",
+//   "checks": {
+//     "server": true,
+//     "timestamp": 1640995200000,
+//     "database": true,
+//     "redis": false
+//   }
+// }
 ```
 
 ## Server Management
@@ -246,12 +274,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 +354,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 +366,56 @@ 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: [] });
+});
+```

package/dist/{middleware.js → cjs/middleware.js}

@@ -45,9 +45,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 +119,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 +148,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 +177,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 +192,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
             });
         }
     };

package/dist/{utils.js → cjs/utils.js}

@@ -3,13 +3,15 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getEnv = getEnv;
 exports.getEnvNumber = getEnvNumber;
 exports.getEnvBoolean = getEnvBoolean;
-// Environment utilities
 function getEnv(key, defaultValue) {
     const value = process.env[key];
-    if (value === undefined && defaultValue === undefined) {
-        throw new Error(`Environment variable ${key} is required`);
+    if (value === undefined) {
+        if (defaultValue === undefined) {
+            throw new Error(`Environment variable ${key} is required`);
+        }
+        return defaultValue;
     }
-    return value || defaultValue;
+    return value; // empty string allowed
 }
 function getEnvNumber(key, defaultValue) {
     const value = process.env[key];
@@ -19,9 +21,9 @@ function getEnvNumber(key, defaultValue) {
         }
         return defaultValue;
     }
-    const parsed = parseInt(value, 10);
-    if (isNaN(parsed)) {
-        throw new Error(`Environment variable ${key} must be a number`);
+    const parsed = Number(value);
+    if (Number.isNaN(parsed)) {
+        throw new Error(`Environment variable ${key} must be a valid number`);
     }
     return parsed;
 }
@@ -33,5 +35,9 @@ function getEnvBoolean(key, defaultValue) {
         }
         return defaultValue;
     }
-    return value.toLowerCase() === 'true';
+    const normalized = value.toLowerCase();
+    if (normalized !== "true" && normalized !== "false") {
+        throw new Error(`Environment variable ${key} must be 'true' or 'false'`);
+    }
+    return normalized === "true";
 }

package/dist/esm/health.d.ts

@@ -0,0 +1,5 @@
+import express from 'express';
+import { HealthCheckConfig, ServerPlugin } from './types';
+export declare function createHealthCheck(config?: HealthCheckConfig): express.RequestHandler;
+export declare function withHealthCheck(path?: string, config?: HealthCheckConfig): ServerPlugin;
+export declare function addHealthCheck(app: express.Application, path?: string, config?: HealthCheckConfig): void;

package/dist/esm/health.js

@@ -0,0 +1,40 @@
+export function createHealthCheck(config = {}) {
+    const { customChecks = [] } = config;
+    return async (req, res) => {
+        try {
+            const checks = {
+                server: true,
+                timestamp: Date.now()
+            };
+            // Run custom health checks
+            for (const check of customChecks) {
+                try {
+                    checks[check.name] = await check.check();
+                }
+                catch (error) {
+                    checks[check.name] = false;
+                }
+            }
+            const isHealthy = Object.values(checks).every(status => status === true || typeof status === 'number');
+            res.status(isHealthy ? 200 : 503).json({
+                status: isHealthy ? 'healthy' : 'unhealthy',
+                checks
+            });
+        }
+        catch (error) {
+            res.status(503).json({
+                status: 'unhealthy',
+                error: 'Health check failed'
+            });
+        }
+    };
+}
+export function withHealthCheck(path = '/health', config = {}) {
+    return (app) => {
+        app.get(path, createHealthCheck(config));
+    };
+}
+// Convenience function for direct use
+export function addHealthCheck(app, path = '/health', config = {}) {
+    app.get(path, createHealthCheck(config));
+}

package/dist/esm/index.d.ts

@@ -0,0 +1,46 @@
+export { ExpressServer, createServer } from './server';
+export type { ServerInstance, ServerInfo, GrpcService, RpcMethod, WebhookConfig } from './server';
+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 { getEnv, getEnvNumber, getEnvBoolean } from './utils';
+export { PeriodicHealthMonitor } from './periodic-health';
+export type { ServerConfig, HealthCheckConfig, HealthCheck, GracefulShutdownConfig, ServerPlugin, SocketIOConfig, SocketInstance, PeriodicHealthCheckConfig, HealthCheckService } from './types';
+import { ExpressServer, createServer } from './server';
+import { createHealthCheck, withHealthCheck, addHealthCheck } from './health';
+import { createGracefulShutdown, withGracefulShutdown, startServerWithShutdown } from './shutdown';
+import { createLoggingMiddleware, createErrorHandler, createRequestIdMiddleware, createValidationMiddleware, createRateLimitMiddleware, createAuthMiddleware, withLogging, withErrorHandler, withRequestId, withValidation, withRateLimit, withAuth, validateFields, rateLimit, requireAuth } from './middleware';
+import { getEnv, getEnvNumber, getEnvBoolean } from './utils';
+import { PeriodicHealthMonitor } from './periodic-health';
+declare const ServerUtils: {
+    createServer: typeof createServer;
+    ExpressServer: typeof ExpressServer;
+    createHealthCheck: typeof createHealthCheck;
+    withHealthCheck: typeof withHealthCheck;
+    addHealthCheck: typeof addHealthCheck;
+    createGracefulShutdown: typeof createGracefulShutdown;
+    withGracefulShutdown: typeof withGracefulShutdown;
+    startServerWithShutdown: typeof startServerWithShutdown;
+    createLoggingMiddleware: typeof createLoggingMiddleware;
+    createErrorHandler: typeof createErrorHandler;
+    createRequestIdMiddleware: typeof createRequestIdMiddleware;
+    createValidationMiddleware: typeof createValidationMiddleware;
+    createRateLimitMiddleware: typeof createRateLimitMiddleware;
+    createAuthMiddleware: typeof createAuthMiddleware;
+    withLogging: typeof withLogging;
+    withErrorHandler: typeof withErrorHandler;
+    withRequestId: typeof withRequestId;
+    withValidation: typeof withValidation;
+    withRateLimit: typeof withRateLimit;
+    withAuth: typeof withAuth;
+    validateFields: typeof validateFields;
+    rateLimit: typeof rateLimit;
+    requireAuth: typeof requireAuth;
+    getEnv: typeof getEnv;
+    getEnvNumber: typeof getEnvNumber;
+    getEnvBoolean: typeof getEnvBoolean;
+    PeriodicHealthMonitor: typeof PeriodicHealthMonitor;
+};
+export default ServerUtils;

package/dist/esm/index.js

@@ -0,0 +1,58 @@
+// Core server utilities
+export { ExpressServer, createServer } from './server';
+// Express re-exports (to avoid direct Express dependency in services)
+export { Router } from 'express';
+// Health check utilities
+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';
+// Utility functions
+export { getEnv, getEnvNumber, getEnvBoolean } from './utils';
+// Periodic health monitoring
+export { PeriodicHealthMonitor } from './periodic-health';
+// Import all exports for default export
+import { ExpressServer, createServer } from './server';
+import { createHealthCheck, withHealthCheck, addHealthCheck } from './health';
+import { createGracefulShutdown, withGracefulShutdown, startServerWithShutdown } from './shutdown';
+import { createLoggingMiddleware, createErrorHandler, createRequestIdMiddleware, createValidationMiddleware, createRateLimitMiddleware, createAuthMiddleware, withLogging, withErrorHandler, withRequestId, withValidation, withRateLimit, withAuth, validateFields, rateLimit, requireAuth } from './middleware';
+import { getEnv, getEnvNumber, getEnvBoolean } from './utils';
+import { PeriodicHealthMonitor } from './periodic-health';
+// Default export for namespace usage
+const ServerUtils = {
+    // Server creation
+    createServer,
+    ExpressServer,
+    // Health checks
+    createHealthCheck,
+    withHealthCheck,
+    addHealthCheck,
+    // Graceful shutdown
+    createGracefulShutdown,
+    withGracefulShutdown,
+    startServerWithShutdown,
+    // Middleware
+    createLoggingMiddleware,
+    createErrorHandler,
+    createRequestIdMiddleware,
+    createValidationMiddleware,
+    createRateLimitMiddleware,
+    createAuthMiddleware,
+    withLogging,
+    withErrorHandler,
+    withRequestId,
+    withValidation,
+    withRateLimit,
+    withAuth,
+    validateFields,
+    rateLimit,
+    requireAuth,
+    // Utils
+    getEnv,
+    getEnvNumber,
+    getEnvBoolean,
+    // Periodic Health Monitoring
+    PeriodicHealthMonitor,
+};
+export default ServerUtils;

package/dist/esm/middleware.d.ts

@@ -0,0 +1,37 @@
+import express from 'express';
+import { ServerPlugin } from './types';
+export declare function createLoggingMiddleware(format?: 'simple' | 'detailed'): express.RequestHandler;
+export declare function createErrorHandler(): express.ErrorRequestHandler;
+export declare function createRequestIdMiddleware(): express.RequestHandler;
+export interface ValidationRule {
+    field: string;
+    required?: boolean;
+    type?: 'string' | 'number' | 'email' | 'boolean';
+    minLength?: number;
+    maxLength?: number;
+    pattern?: RegExp;
+    custom?: (value: unknown) => boolean | string;
+}
+export declare function createValidationMiddleware(rules: ValidationRule[]): express.RequestHandler;
+export interface RateLimitConfig {
+    windowMs?: number;
+    maxRequests?: number;
+    message?: string;
+    keyGenerator?: (req: express.Request) => string;
+}
+export declare function createRateLimitMiddleware(config?: RateLimitConfig): express.RequestHandler;
+export interface AuthConfig {
+    tokenExtractor?: (req: express.Request) => string | null;
+    tokenValidator?: (token: string) => Promise<unknown> | unknown;
+    unauthorizedMessage?: string;
+}
+export declare function createAuthMiddleware(config: AuthConfig): express.RequestHandler;
+export declare function withLogging(format?: 'simple' | 'detailed'): ServerPlugin;
+export declare function withErrorHandler(): ServerPlugin;
+export declare function withRequestId(): ServerPlugin;
+export declare function withValidation(rules: ValidationRule[]): ServerPlugin;
+export declare function withRateLimit(config?: RateLimitConfig): ServerPlugin;
+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;