@naman_deep_singh/server-utils 1.0.0

package/dist/shutdown.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createGracefulShutdown = createGracefulShutdown;
+exports.withGracefulShutdown = withGracefulShutdown;
+exports.startServerWithShutdown = startServerWithShutdown;
+function createGracefulShutdown(server, config = {}) {
+    const { timeout = 10000, onShutdown } = config;
+    const shutdown = async (signal) => {
+        console.log(`🛑 Received ${signal}, shutting down gracefully...`);
+        const shutdownTimer = setTimeout(() => {
+            console.log('⏰ Shutdown timeout reached, forcing exit');
+            process.exit(1);
+        }, timeout);
+        try {
+            // Run custom shutdown logic
+            if (onShutdown) {
+                await onShutdown();
+            }
+            // Close server
+            server.close(() => {
+                clearTimeout(shutdownTimer);
+                console.log('👋 Server closed. Exiting now.');
+                process.exit(0);
+            });
+        }
+        catch (error) {
+            clearTimeout(shutdownTimer);
+            console.error('❌ Error during shutdown:', error);
+            process.exit(1);
+        }
+    };
+    process.on('SIGINT', () => shutdown('SIGINT'));
+    process.on('SIGTERM', () => shutdown('SIGTERM'));
+}
+function withGracefulShutdown(config = {}) {
+    return (app, serverConfig) => {
+        // This plugin needs to be applied after server.listen()
+        // Store config for later use
+        app.__gracefulShutdownConfig = config;
+    };
+}
+function startServerWithShutdown(app, port, shutdownConfig = {}) {
+    const server = app.listen(port, () => {
+        console.log(`🚀 Server running on http://localhost:${port}`);
+    });
+    // Apply graceful shutdown from stored config or provided config
+    const config = app.__gracefulShutdownConfig || shutdownConfig;
+    createGracefulShutdown(server, config);
+    return server;
+}

package/dist/types.d.ts

@@ -0,0 +1,24 @@
+import express from 'express';
+import { CorsOptions } from 'cors';
+export interface ServerConfig {
+    port?: number;
+    cors?: boolean | CorsOptions;
+    helmet?: boolean;
+    json?: boolean;
+    customMiddleware?: express.RequestHandler[];
+    healthCheck?: boolean | string;
+    gracefulShutdown?: boolean;
+}
+export interface HealthCheckConfig {
+    path?: string;
+    customChecks?: HealthCheck[];
+}
+export interface HealthCheck {
+    name: string;
+    check: () => Promise<boolean>;
+}
+export interface GracefulShutdownConfig {
+    timeout?: number;
+    onShutdown?: () => Promise<void>;
+}
+export type ServerPlugin = (app: express.Application, config: ServerConfig) => void;

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/utils.d.ts

@@ -0,0 +1,3 @@
+export declare function getEnv(key: string, defaultValue?: string): string;
+export declare function getEnvNumber(key: string, defaultValue?: number): number;
+export declare function getEnvBoolean(key: string, defaultValue?: boolean): boolean;

package/dist/utils.js

@@ -0,0 +1,37 @@
+"use strict";
+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`);
+    }
+    return value || defaultValue;
+}
+function getEnvNumber(key, defaultValue) {
+    const value = process.env[key];
+    if (value === undefined) {
+        if (defaultValue === undefined) {
+            throw new Error(`Environment variable ${key} is required`);
+        }
+        return defaultValue;
+    }
+    const parsed = parseInt(value, 10);
+    if (isNaN(parsed)) {
+        throw new Error(`Environment variable ${key} must be a number`);
+    }
+    return parsed;
+}
+function getEnvBoolean(key, defaultValue) {
+    const value = process.env[key];
+    if (value === undefined) {
+        if (defaultValue === undefined) {
+            throw new Error(`Environment variable ${key} is required`);
+        }
+        return defaultValue;
+    }
+    return value.toLowerCase() === 'true';
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@naman_deep_singh/server-utils",
+  "version": "1.0.0",
+  "description": "Extensible server utilities for Express.js microservices with TypeScript",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc"
+  },
+  "keywords": [
+    "server",
+    "express",
+    "microservices",
+    "utils",
+    "typescript"
+  ],
+  "author": "Naman Deep Singh",
+  "license": "ISC",
+  "packageManager": "pnpm@10.20.0",
+  "dependencies": {
+    "express": "^5.1.0",
+    "cors": "^2.8.5",
+    "helmet": "^8.1.0",
+    "cookie-parser": "^1.4.6"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.5",
+    "@types/cors": "^2.8.19",
+    "@types/cookie-parser": "^1.4.7",
+    "typescript": "^5.9.3"
+  }
+}

package/src/health.ts

@@ -0,0 +1,47 @@
+import express from 'express';
+import { HealthCheckConfig, HealthCheck, ServerPlugin } from './types';
+
+export function createHealthCheck(config: HealthCheckConfig = {}): express.RequestHandler {
+  const { customChecks = [] } = config;
+
+  return async (req: express.Request, res: express.Response) => {
+    try {
+      const checks: Record<string, boolean> = {
+        server: true,
+        timestamp: Date.now() as any
+      };
+
+      // 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: string = '/health', config: HealthCheckConfig = {}): ServerPlugin {
+  return (app: express.Application) => {
+    app.get(path, createHealthCheck(config));
+  };
+}
+
+// Convenience function for direct use
+export function addHealthCheck(app: express.Application, path: string = '/health', config: HealthCheckConfig = {}): void {
+  app.get(path, createHealthCheck(config));
+}

package/src/index.ts

@@ -0,0 +1,46 @@
+// Core server utilities
+export { createServer, withPlugin, createServerWithPlugins } from './server';
+
+// 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,
+  type ValidationRule,
+  type RateLimitConfig,
+  type AuthConfig
+} from './middleware';
+
+// Utility functions
+export {
+  getEnv,
+  getEnvNumber,
+  getEnvBoolean
+} from './utils';
+
+// Types
+export type { 
+  ServerConfig, 
+  HealthCheckConfig, 
+  HealthCheck, 
+  GracefulShutdownConfig, 
+  ServerPlugin 
+} from './types';

package/src/middleware.ts

@@ -0,0 +1,272 @@
+import express from 'express';
+import { ServerPlugin } from './types';
+
+// Logging middleware
+export function createLoggingMiddleware(format: 'simple' | 'detailed' = 'simple'): express.RequestHandler {
+  return (req: express.Request, res: express.Response, next: express.NextFunction) => {
+    const start = Date.now();
+    
+    res.on('finish', () => {
+      const duration = Date.now() - start;
+      
+      if (format === 'detailed') {
+        console.log(`${req.method} ${req.url} - ${res.statusCode} - ${duration}ms - ${req.ip}`);
+      } else {
+        console.log(`${req.method} ${req.url} - ${res.statusCode}`);
+      }
+    });
+    
+    next();
+  };
+}
+
+// Error handling middleware
+export function createErrorHandler(): express.ErrorRequestHandler {
+  return (err: any, req: express.Request, res: express.Response, next: express.NextFunction) => {
+    console.error('Error:', err);
+    
+    if (res.headersSent) {
+      return next(err);
+    }
+    
+    const status = err.status || err.statusCode || 500;
+    const message = process.env.NODE_ENV === 'production' 
+      ? 'Internal Server Error' 
+      : err.message;
+    
+    res.status(status).json({
+      status: false,
+      message,
+      ...(process.env.NODE_ENV !== 'production' && { stack: err.stack })
+    });
+  };
+}
+
+// Request ID middleware
+export function createRequestIdMiddleware(): express.RequestHandler {
+  return (req: express.Request, res: express.Response, next: express.NextFunction) => {
+    const requestId = Math.random().toString(36).substring(2, 15);
+    (req as any).requestId = requestId;
+    res.setHeader('X-Request-ID', requestId);
+    next();
+  };
+}
+
+// Validation middleware
+export interface ValidationRule {
+  field: string;
+  required?: boolean;
+  type?: 'string' | 'number' | 'email' | 'boolean';
+  minLength?: number;
+  maxLength?: number;
+  pattern?: RegExp;
+  custom?: (value: any) => boolean | string;
+}
+
+export function createValidationMiddleware(rules: ValidationRule[]): express.RequestHandler {
+  return (req: express.Request, res: express.Response, next: express.NextFunction) => {
+    const errors: string[] = [];
+    
+    for (const rule of rules) {
+      const value = req.body[rule.field];
+      
+      if (rule.required && (value === undefined || value === null || value === '')) {
+        errors.push(`${rule.field} is required`);
+        continue;
+      }
+      
+      if (value === undefined || value === null) continue;
+      
+      if (rule.type) {
+        switch (rule.type) {
+          case 'email':
+            const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+            if (!emailRegex.test(value)) {
+              errors.push(`${rule.field} must be a valid email`);
+            }
+            break;
+          case 'string':
+            if (typeof value !== 'string') {
+              errors.push(`${rule.field} must be a string`);
+            }
+            break;
+          case 'number':
+            if (typeof value !== 'number' && isNaN(Number(value))) {
+              errors.push(`${rule.field} must be a number`);
+            }
+            break;
+          case 'boolean':
+            if (typeof value !== 'boolean') {
+              errors.push(`${rule.field} must be a boolean`);
+            }
+            break;
+        }
+      }
+      
+      if (rule.minLength && value.length < rule.minLength) {
+        errors.push(`${rule.field} must be at least ${rule.minLength} characters`);
+      }
+      if (rule.maxLength && value.length > rule.maxLength) {
+        errors.push(`${rule.field} must be no more than ${rule.maxLength} characters`);
+      }
+      
+      if (rule.pattern && !rule.pattern.test(value)) {
+        errors.push(`${rule.field} format is invalid`);
+      }
+      
+      if (rule.custom) {
+        const result = rule.custom(value);
+        if (result !== true) {
+          errors.push(typeof result === 'string' ? result : `${rule.field} is invalid`);
+        }
+      }
+    }
+    
+    if (errors.length > 0) {
+      return res.status(400).json({
+        status: false,
+        message: 'Validation failed',
+        errors
+      });
+    }
+    
+    next();
+  };
+}
+
+// Rate limiting middleware
+export interface RateLimitConfig {
+  windowMs?: number;
+  maxRequests?: number;
+  message?: string;
+  keyGenerator?: (req: express.Request) => string;
+}
+
+const rateLimitStore = new Map<string, { count: number; resetTime: number }>();
+
+export function createRateLimitMiddleware(config: RateLimitConfig = {}): express.RequestHandler {
+  const {
+    windowMs = 15 * 60 * 1000,
+    maxRequests = 100,
+    message = 'Too many requests, please try again later',
+    keyGenerator = (req) => req.ip || 'unknown'
+  } = config;
+  
+  return (req: express.Request, res: express.Response, next: express.NextFunction) => {
+    const key = keyGenerator(req);
+    const now = Date.now();
+    const record = rateLimitStore.get(key);
+    
+    if (!record || now > record.resetTime) {
+      rateLimitStore.set(key, {
+        count: 1,
+        resetTime: now + windowMs
+      });
+      return next();
+    }
+    
+    if (record.count >= maxRequests) {
+      return res.status(429).json({
+        status: false,
+        message,
+        retryAfter: Math.ceil((record.resetTime - now) / 1000)
+      });
+    }
+    
+    record.count++;
+    next();
+  };
+}
+
+// Authentication middleware helper
+export interface AuthConfig {
+  tokenExtractor?: (req: express.Request) => string | null;
+  tokenValidator?: (token: string) => Promise<any> | any;
+  unauthorizedMessage?: string;
+}
+
+export function createAuthMiddleware(config: AuthConfig): express.RequestHandler {
+  const {
+    tokenExtractor = (req) => {
+      const authHeader = req.headers.authorization;
+      if (authHeader && authHeader.startsWith('Bearer ')) {
+        return authHeader.substring(7);
+      }
+      return req.cookies?.token || null;
+    },
+    tokenValidator = () => { throw new Error('Token validator not implemented'); },
+    unauthorizedMessage = 'Unauthorized access'
+  } = config;
+  
+  return async (req: express.Request, res: express.Response, next: express.NextFunction) => {
+    try {
+      const token = tokenExtractor(req);
+      
+      if (!token) {
+        return res.status(401).json({
+          status: false,
+          message: unauthorizedMessage
+        });
+      }
+      
+      const user = await tokenValidator(token);
+      (req as any).user = user;
+      next();
+    } catch (error) {
+      return res.status(401).json({
+        status: false,
+        message: unauthorizedMessage
+      });
+    }
+  };
+}
+
+// Plugin versions
+export function withLogging(format: 'simple' | 'detailed' = 'simple'): ServerPlugin {
+  return (app: express.Application) => {
+    app.use(createLoggingMiddleware(format));
+  };
+}
+
+export function withErrorHandler(): ServerPlugin {
+  return (app: express.Application) => {
+    app.use(createErrorHandler());
+  };
+}
+
+export function withRequestId(): ServerPlugin {
+  return (app: express.Application) => {
+    app.use(createRequestIdMiddleware());
+  };
+}
+
+export function withValidation(rules: ValidationRule[]): ServerPlugin {
+  return (app: express.Application) => {
+    app.use(createValidationMiddleware(rules));
+  };
+}
+
+export function withRateLimit(config: RateLimitConfig = {}): ServerPlugin {
+  return (app: express.Application) => {
+    app.use(createRateLimitMiddleware(config));
+  };
+}
+
+export function withAuth(config: AuthConfig): ServerPlugin {
+  return (app: express.Application) => {
+    app.use(createAuthMiddleware(config));
+  };
+}
+
+// Convenience functions for route-specific middleware
+export function validateFields(rules: ValidationRule[]): express.RequestHandler {
+  return createValidationMiddleware(rules);
+}
+
+export function rateLimit(config: RateLimitConfig = {}): express.RequestHandler {
+  return createRateLimitMiddleware(config);
+}
+
+export function requireAuth(config: AuthConfig): express.RequestHandler {
+  return createAuthMiddleware(config);
+}

package/src/server.ts

@@ -0,0 +1,46 @@
+import express from 'express';
+import cors from 'cors';
+import helmet from 'helmet';
+import { ServerConfig, ServerPlugin } from './types';
+
+export function createServer(config: ServerConfig = {}): express.Application {
+  const app = express();
+
+  // Apply default middleware
+  if (config.helmet !== false) {
+    app.use(helmet());
+  }
+
+  if (config.cors !== false) {
+    const corsOptions = typeof config.cors === 'object' ? config.cors : undefined;
+    app.use(cors(corsOptions));
+  }
+
+  if (config.json !== false) {
+    app.use(express.json());
+  }
+
+  // Apply custom middleware
+  if (config.customMiddleware) {
+    config.customMiddleware.forEach(middleware => {
+      app.use(middleware);
+    });
+  }
+
+  return app;
+}
+
+export function withPlugin(app: express.Application, plugin: ServerPlugin, config: ServerConfig = {}): express.Application {
+  plugin(app, config);
+  return app;
+}
+
+export function createServerWithPlugins(config: ServerConfig = {}, ...plugins: ServerPlugin[]): express.Application {
+  const app = createServer(config);
+  
+  plugins.forEach(plugin => {
+    plugin(app, config);
+  });
+
+  return app;
+}

package/src/shutdown.ts

@@ -0,0 +1,60 @@
+import { Server } from 'http';
+import { GracefulShutdownConfig, ServerPlugin } from './types';
+
+export function createGracefulShutdown(server: Server, config: GracefulShutdownConfig = {}): void {
+  const { timeout = 10000, onShutdown } = config;
+
+  const shutdown = async (signal: string) => {
+    console.log(`🛑 Received ${signal}, shutting down gracefully...`);
+    
+    const shutdownTimer = setTimeout(() => {
+      console.log('⏰ Shutdown timeout reached, forcing exit');
+      process.exit(1);
+    }, timeout);
+
+    try {
+      // Run custom shutdown logic
+      if (onShutdown) {
+        await onShutdown();
+      }
+
+      // Close server
+      server.close(() => {
+        clearTimeout(shutdownTimer);
+        console.log('👋 Server closed. Exiting now.');
+        process.exit(0);
+      });
+    } catch (error) {
+      clearTimeout(shutdownTimer);
+      console.error('❌ Error during shutdown:', error);
+      process.exit(1);
+    }
+  };
+
+  process.on('SIGINT', () => shutdown('SIGINT'));
+  process.on('SIGTERM', () => shutdown('SIGTERM'));
+}
+
+export function withGracefulShutdown(config: GracefulShutdownConfig = {}): ServerPlugin {
+  return (app, serverConfig) => {
+    // This plugin needs to be applied after server.listen()
+    // Store config for later use
+    (app as any).__gracefulShutdownConfig = config;
+  };
+}
+
+export function startServerWithShutdown(
+  app: any, 
+  port: number, 
+  shutdownConfig: GracefulShutdownConfig = {}
+): Server {
+  const server = app.listen(port, () => {
+    console.log(`🚀 Server running on http://localhost:${port}`);
+  });
+
+  // Apply graceful shutdown from stored config or provided config
+  const config = app.__gracefulShutdownConfig || shutdownConfig;
+  createGracefulShutdown(server, config);
+
+  return server;
+}

package/src/types.ts

@@ -0,0 +1,29 @@
+import express from 'express';
+import { CorsOptions } from 'cors';
+
+export interface ServerConfig {
+  port?: number;
+  cors?: boolean | CorsOptions;
+  helmet?: boolean;
+  json?: boolean;
+  customMiddleware?: express.RequestHandler[];
+  healthCheck?: boolean | string;
+  gracefulShutdown?: boolean;
+}
+
+export interface HealthCheckConfig {
+  path?: string;
+  customChecks?: HealthCheck[];
+}
+
+export interface HealthCheck {
+  name: string;
+  check: () => Promise<boolean>;
+}
+
+export interface GracefulShutdownConfig {
+  timeout?: number;
+  onShutdown?: () => Promise<void>;
+}
+
+export type ServerPlugin = (app: express.Application, config: ServerConfig) => void;

package/src/utils.ts

@@ -0,0 +1,34 @@
+// Environment utilities
+export function getEnv(key: string, defaultValue?: string): string {
+  const value = process.env[key];
+  if (value === undefined && defaultValue === undefined) {
+    throw new Error(`Environment variable ${key} is required`);
+  }
+  return value || defaultValue!;
+}
+
+export function getEnvNumber(key: string, defaultValue?: number): number {
+  const value = process.env[key];
+  if (value === undefined) {
+    if (defaultValue === undefined) {
+      throw new Error(`Environment variable ${key} is required`);
+    }
+    return defaultValue;
+  }
+  const parsed = parseInt(value, 10);
+  if (isNaN(parsed)) {
+    throw new Error(`Environment variable ${key} must be a number`);
+  }
+  return parsed;
+}
+
+export function getEnvBoolean(key: string, defaultValue?: boolean): boolean {
+  const value = process.env[key];
+  if (value === undefined) {
+    if (defaultValue === undefined) {
+      throw new Error(`Environment variable ${key} is required`);
+    }
+    return defaultValue;
+  }
+  return value.toLowerCase() === 'true';
+}