@naman_deep_singh/server-utils 1.0.0 → 1.0.2

package/dist/server.js

@@ -3,41 +3,245 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExpressServer = void 0;
 exports.createServer = createServer;
-exports.withPlugin = withPlugin;
-exports.createServerWithPlugins = createServerWithPlugins;
 const express_1 = __importDefault(require("express"));
-const cors_1 = __importDefault(require("cors"));
-const helmet_1 = __importDefault(require("helmet"));
-function createServer(config = {}) {
-    const app = (0, express_1.default)();
-    // Apply default middleware
-    if (config.helmet !== false) {
-        app.use((0, helmet_1.default)());
-    }
-    if (config.cors !== false) {
-        const corsOptions = typeof config.cors === 'object' ? config.cors : undefined;
-        app.use((0, cors_1.default)(corsOptions));
-    }
-    if (config.json !== false) {
-        app.use(express_1.default.json());
-    }
-    // Apply custom middleware
-    if (config.customMiddleware) {
-        config.customMiddleware.forEach(middleware => {
-            app.use(middleware);
+const shutdown_1 = require("./shutdown");
+const crypto_1 = __importDefault(require("crypto"));
+class ExpressServer {
+    constructor(name = 'Express Server', version = '1.0.0', config = {}) {
+        this.status = 'stopped';
+        this.grpcServices = [];
+        this.rpcMethods = {};
+        this.app = (0, express_1.default)();
+        this.config = {
+            name,
+            version,
+            startTime: new Date(),
+            port: config.port || 3000,
+            cors: config.cors ?? true,
+            helmet: config.helmet ?? true,
+            json: config.json ?? true,
+            customMiddleware: config.customMiddleware || [],
+            healthCheck: config.healthCheck ?? true,
+            gracefulShutdown: config.gracefulShutdown ?? true,
+            socketIO: config.socketIO
+        };
+        // Apply middleware based on configuration
+        this.setupMiddleware();
+    }
+    setupMiddleware() {
+        // Apply CORS if enabled
+        if (this.config.cors) {
+            try {
+                const cors = require('cors');
+                const corsOptions = typeof this.config.cors === 'object' ? this.config.cors : undefined;
+                this.app.use(cors(corsOptions));
+            }
+            catch (error) {
+                console.warn('CORS middleware not available. Install cors package.');
+            }
+        }
+        // Apply Helmet if enabled
+        if (this.config.helmet) {
+            try {
+                const helmet = require('helmet');
+                this.app.use(helmet());
+            }
+            catch (error) {
+                console.warn('Helmet middleware not available. Install helmet package.');
+            }
+        }
+        // Apply JSON parser if enabled
+        if (this.config.json) {
+            this.app.use(express_1.default.json());
+        }
+        // Apply custom middleware
+        if (this.config.customMiddleware && this.config.customMiddleware.length > 0) {
+            this.config.customMiddleware.forEach(middleware => {
+                this.app.use(middleware);
+            });
+        }
+        // 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({
+                    status: 'healthy',
+                    service: this.config.name,
+                    version: this.config.version,
+                    uptime: Date.now() - this.config.startTime.getTime(),
+                    timestamp: new Date().toISOString()
+                });
+            });
+        }
+    }
+    async start() {
+        this.status = 'starting';
+        return new Promise((resolve, reject) => {
+            try {
+                this.server = this.app.listen(this.config.port, () => {
+                    this.status = 'running';
+                    console.log(`🚀 ${this.config.name} v${this.config.version} running on http://localhost:${this.config.port}`);
+                    if (this.config.gracefulShutdown) {
+                        (0, shutdown_1.createGracefulShutdown)(this.server, {
+                            onShutdown: async () => {
+                                this.status = 'stopping';
+                            }
+                        });
+                    }
+                    resolve(this);
+                });
+                this.server.on('error', reject);
+            }
+            catch (error) {
+                this.status = 'stopped';
+                reject(error);
+            }
         });
     }
-    return app;
-}
-function withPlugin(app, plugin, config = {}) {
-    plugin(app, config);
-    return app;
+    async stop() {
+        this.status = 'stopping';
+        // Stop gRPC server if running
+        if (this.grpcServer) {
+            this.grpcServer.forceShutdown();
+        }
+        // Stop Socket.IO server if running
+        if (this.socketIO) {
+            this.socketIO.close();
+        }
+        if (!this.server) {
+            this.status = 'stopped';
+            return;
+        }
+        return new Promise((resolve) => {
+            this.server.close(() => {
+                this.status = 'stopped';
+                console.log(`👋 ${this.config.name} stopped`);
+                resolve();
+            });
+        });
+    }
+    getInfo() {
+        return {
+            name: this.config.name,
+            version: this.config.version,
+            port: this.config.port,
+            uptime: Date.now() - this.config.startTime.getTime(),
+            status: this.status,
+            startTime: this.config.startTime
+        };
+    }
+    addGrpcService(service, implementation, port = 50051) {
+        this.grpcServices.push({ service, implementation });
+        // Lazy load gRPC to avoid dependency issues
+        if (!this.grpcServer) {
+            try {
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                const grpc = require('@grpc/grpc-js');
+                this.grpcServer = new grpc.Server();
+                // Add all services
+                this.grpcServices.forEach(({ service, implementation }) => {
+                    this.grpcServer.addService(service, implementation);
+                });
+                this.grpcServer.bindAsync(`0.0.0.0:${port}`, grpc.ServerCredentials.createInsecure(), () => {
+                    this.grpcServer.start();
+                    console.log(`🔗 gRPC server running on port ${port}`);
+                });
+            }
+            catch (error) {
+                console.warn('gRPC not available. Install @grpc/grpc-js to use gRPC features.');
+            }
+        }
+    }
+    addRpcMethods(methods, path = '/rpc') {
+        Object.assign(this.rpcMethods, methods);
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const jayson = require('jayson');
+            const rpcServer = jayson.server(this.rpcMethods);
+            this.app.use(path, rpcServer.middleware());
+            console.log(`📡 JSON-RPC server mounted on ${path}`);
+        }
+        catch (error) {
+            console.warn('JSON-RPC not available. Install jayson to use RPC features.');
+        }
+    }
+    addWebhook(config) {
+        this.app.post(config.path, express_1.default.raw({ type: 'application/json' }), async (req, res) => {
+            try {
+                // Verify signature if secret provided
+                if (config.secret) {
+                    const signature = req.headers['x-hub-signature-256'] || req.headers['x-signature-256'];
+                    if (signature) {
+                        const expectedSignature = crypto_1.default
+                            .createHmac('sha256', config.secret)
+                            .update(req.body)
+                            .digest('hex');
+                        const providedSignature = Array.isArray(signature) ? signature[0] : signature;
+                        if (!providedSignature.includes(expectedSignature)) {
+                            return res.status(401).json({ error: 'Invalid signature' });
+                        }
+                    }
+                }
+                // Parse JSON payload
+                const payload = JSON.parse(req.body.toString());
+                // Call handler
+                await config.handler(payload, req.headers);
+                res.status(200).json({ success: true });
+            }
+            catch (error) {
+                console.error('Webhook error:', error);
+                res.status(500).json({ error: 'Webhook processing failed' });
+            }
+        });
+        console.log(`🪝 Webhook registered at ${config.path}`);
+    }
+    addSocketIO(config = {}) {
+        if (!this.server) {
+            throw new Error('Server must be started before adding Socket.IO');
+        }
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const { Server } = require('socket.io');
+            // Configure CORS
+            const corsConfig = config.cors === true
+                ? { origin: '*', methods: ['GET', 'POST'] }
+                : config.cors || undefined;
+            // Create Socket.IO server
+            const io = new Server(this.server, {
+                cors: config.cors ? corsConfig : undefined,
+                path: config.path || '/socket.io'
+            });
+            // Store reference for cleanup
+            this.socketIO = io;
+            // Handle connections
+            io.on('connection', (socket) => {
+                const typedSocket = socket;
+                console.log(`🔌 Socket connected: ${typedSocket.id}`);
+                // Call user-defined connection handler
+                if (config.onConnection) {
+                    config.onConnection(socket);
+                }
+                // Handle disconnection
+                typedSocket.on('disconnect', (reason) => {
+                    console.log(`🔌 Socket disconnected: ${typedSocket.id} - ${reason}`);
+                    // Call user-defined disconnection handler
+                    if (config.onDisconnection) {
+                        config.onDisconnection(socket, reason);
+                    }
+                });
+            });
+            console.log(`🔌 Socket.IO server attached${config.path ? ` at ${config.path}` : ''}`);
+            return io;
+        }
+        catch (error) {
+            console.warn('Socket.IO not available. Install socket.io to use WebSocket features.');
+            return null;
+        }
+    }
 }
-function createServerWithPlugins(config = {}, ...plugins) {
-    const app = createServer(config);
-    plugins.forEach(plugin => {
-        plugin(app, config);
-    });
-    return app;
+exports.ExpressServer = ExpressServer;
+function createServer(name, version, config) {
+    return new ExpressServer(name, version, config);
 }

package/dist/types.d.ts

@@ -1,5 +1,14 @@
 import express from 'express';
-import { CorsOptions } from 'cors';
+export interface CorsOptions {
+    origin?: string | string[] | boolean | RegExp | ((origin: string | undefined, callback: (err: Error | null, allow?: boolean) => void) => void);
+    methods?: string | string[];
+    allowedHeaders?: string | string[];
+    exposedHeaders?: string | string[];
+    credentials?: boolean;
+    maxAge?: number;
+    preflightContinue?: boolean;
+    optionsSuccessStatus?: number;
+}
 export interface ServerConfig {
     port?: number;
     cors?: boolean | CorsOptions;
@@ -8,6 +17,20 @@ export interface ServerConfig {
     customMiddleware?: express.RequestHandler[];
     healthCheck?: boolean | string;
     gracefulShutdown?: boolean;
+    socketIO?: SocketIOConfig;
+    name?: string;
+    version?: string;
+}
+export interface SocketIOConfig {
+    enabled?: boolean;
+    cors?: boolean | {
+        origin?: string | string[] | boolean;
+        methods?: string[];
+        credentials?: boolean;
+    };
+    onConnection?: (socket: unknown) => void;
+    onDisconnection?: (socket: unknown, reason: string) => void;
+    path?: string;
 }
 export interface HealthCheckConfig {
     path?: string;
@@ -21,4 +44,13 @@ export interface GracefulShutdownConfig {
     timeout?: number;
     onShutdown?: () => Promise<void>;
 }
+export interface SocketInstance {
+    id: string;
+    emit: (event: string, data?: unknown) => void;
+    on: (event: string, handler: (...args: unknown[]) => void) => void;
+    broadcast: {
+        emit: (event: string, data?: unknown) => void;
+    };
+    disconnect: () => void;
+}
 export type ServerPlugin = (app: express.Application, config: ServerConfig) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naman_deep_singh/server-utils",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Extensible server utilities for Express.js microservices with TypeScript",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -18,15 +18,10 @@
   "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"
+    "express": "^4.21.1"
   },
   "devDependencies": {
-    "@types/express": "^5.0.5",
-    "@types/cors": "^2.8.19",
-    "@types/cookie-parser": "^1.4.7",
+    "@types/express": "^4.17.21",
     "typescript": "^5.9.3"
   }
 }

package/src/index.ts

@@ -1,5 +1,6 @@
 // Core server utilities
-export { createServer, withPlugin, createServerWithPlugins } from './server';
+export { ExpressServer, createServer } from './server';
+export type { ServerInstance, ServerInfo, GrpcService, RpcMethod, WebhookConfig } from './server';
 
 // Health check utilities
 export { createHealthCheck, withHealthCheck, addHealthCheck } from './health';
@@ -42,5 +43,71 @@ export type {
   HealthCheckConfig, 
   HealthCheck, 
   GracefulShutdownConfig, 
-  ServerPlugin 
-} from './types';
+  ServerPlugin,
+  SocketIOConfig,
+  SocketInstance 
+} from './types';
+
+// 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';
+
+// 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
+};
+
+export default ServerUtils;

package/src/middleware.ts

@@ -22,22 +22,25 @@ export function createLoggingMiddleware(format: 'simple' | 'detailed' = 'simple'
 
 // Error handling middleware
 export function createErrorHandler(): express.ErrorRequestHandler {
-  return (err: any, req: express.Request, res: express.Response, next: express.NextFunction) => {
+  return (err: unknown, 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;
+    // Type guard for error objects
+    const errorObj = err as { status?: number; statusCode?: number; message?: string; stack?: string };
+    
+    const status = errorObj.status || errorObj.statusCode || 500;
     const message = process.env.NODE_ENV === 'production' 
       ? 'Internal Server Error' 
-      : err.message;
+      : errorObj.message || 'Unknown error';
     
     res.status(status).json({
       status: false,
       message,
-      ...(process.env.NODE_ENV !== 'production' && { stack: err.stack })
+      ...(process.env.NODE_ENV !== 'production' && { stack: errorObj.stack })
     });
   };
 }
@@ -46,7 +49,7 @@ export function createErrorHandler(): express.ErrorRequestHandler {
 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;
+    (req as express.Request & { requestId: string }).requestId = requestId;
     res.setHeader('X-Request-ID', requestId);
     next();
   };
@@ -60,7 +63,7 @@ export interface ValidationRule {
   minLength?: number;
   maxLength?: number;
   pattern?: RegExp;
-  custom?: (value: any) => boolean | string;
+  custom?: (value: unknown) => boolean | string;
 }
 
 export function createValidationMiddleware(rules: ValidationRule[]): express.RequestHandler {
@@ -181,7 +184,7 @@ export function createRateLimitMiddleware(config: RateLimitConfig = {}): express
 // Authentication middleware helper
 export interface AuthConfig {
   tokenExtractor?: (req: express.Request) => string | null;
-  tokenValidator?: (token: string) => Promise<any> | any;
+  tokenValidator?: (token: string) => Promise<unknown> | unknown;
   unauthorizedMessage?: string;
 }
 
@@ -210,7 +213,7 @@ export function createAuthMiddleware(config: AuthConfig): express.RequestHandler
       }
       
       const user = await tokenValidator(token);
-      (req as any).user = user;
+      (req as express.Request & { user: unknown }).user = user;
       next();
     } catch (error) {
       return res.status(401).json({