@naman_deep_singh/server-utils 1.0.0

package/README.md

@@ -0,0 +1,238 @@
+# @naman_deep_singh/server-utils
+
+Extensible server utilities for Express.js microservices with TypeScript. Provides a plugin-based architecture for building consistent and maintainable server applications.
+
+## Features
+
+- 🚀 **Express Server Factory** - Quick server setup with sensible defaults
+- 🔌 **Plugin System** - Extensible architecture for custom functionality
+- 🏥 **Health Checks** - Built-in health monitoring with custom checks
+- 🛑 **Graceful Shutdown** - Proper cleanup and shutdown handling
+- 📝 **Logging Middleware** - Request logging with customizable formats
+- 🛡️ **Error Handling** - Centralized error handling middleware
+- 🆔 **Request ID** - Automatic request ID generation and tracking
+
+## Installation
+
+```bash
+npm install @naman_deep_singh/server-utils
+# or
+pnpm add @naman_deep_singh/server-utils
+```
+
+## Quick Start
+
+### Basic Server
+```typescript
+import { createServer, startServerWithShutdown } from '@naman_deep_singh/server-utils';
+
+const app = createServer({
+  cors: true,
+  helmet: true,
+  healthCheck: true
+});
+
+app.get('/', (req, res) => {
+  res.json({ message: 'Hello World!' });
+});
+
+startServerWithShutdown(app, 3000);
+```
+
+### Plugin-Based Architecture
+```typescript
+import { 
+  createServerWithPlugins, 
+  withHealthCheck, 
+  withLogging, 
+  withErrorHandler,
+  withGracefulShutdown,
+  startServerWithShutdown 
+} from '@naman_deep_singh/server-utils';
+
+const app = createServerWithPlugins(
+  { cors: true, helmet: true },
+  withLogging('detailed'),
+  withHealthCheck('/health', {
+    customChecks: [
+      {
+        name: 'database',
+        check: async () => {
+          // Your database health check
+          return true;
+        }
+      }
+    ]
+  }),
+  withErrorHandler(),
+  withGracefulShutdown({
+    timeout: 15000,
+    onShutdown: async () => {
+      console.log('Cleaning up resources...');
+      // Your cleanup logic
+    }
+  })
+);
+
+// Add your routes
+app.get('/api/users', (req, res) => {
+  res.json({ users: [] });
+});
+
+startServerWithShutdown(app, 3000);
+```
+
+## API Reference
+
+### Server Factory
+
+#### `createServer(config?: ServerConfig)`
+Creates an Express application with default middleware.
+
+```typescript
+interface ServerConfig {
+  port?: number;
+  cors?: boolean | CorsOptions;
+  helmet?: boolean;
+  json?: boolean;
+  customMiddleware?: express.RequestHandler[];
+  healthCheck?: boolean | string;
+  gracefulShutdown?: boolean;
+}
+```
+
+#### `createServerWithPlugins(config, ...plugins)`
+Creates a server and applies multiple plugins.
+
+### Health Checks
+
+#### `withHealthCheck(path?, config?)`
+Adds health check endpoint as a plugin.
+
+```typescript
+withHealthCheck('/health', {
+  customChecks: [
+    {
+      name: 'redis',
+      check: async () => await redis.ping()
+    }
+  ]
+})
+```
+
+#### `addHealthCheck(app, path?, config?)`
+Directly adds health check to existing app.
+
+### Graceful Shutdown
+
+#### `withGracefulShutdown(config?)`
+Adds graceful shutdown as a plugin.
+
+```typescript
+withGracefulShutdown({
+  timeout: 10000,
+  onShutdown: async () => {
+    await database.close();
+    await redis.disconnect();
+  }
+})
+```
+
+#### `startServerWithShutdown(app, port, config?)`
+Starts server with automatic graceful shutdown setup.
+
+### Middleware Plugins
+
+#### `withLogging(format?)`
+Adds request logging middleware.
+- `format`: 'simple' | 'detailed'
+
+#### `withErrorHandler()`
+Adds centralized error handling middleware.
+
+#### `withRequestId()`
+Adds request ID generation and tracking.
+
+### Custom Plugins
+
+Create your own plugins:
+
+```typescript
+import { ServerPlugin } from '@naman_deep_singh/server-utils';
+
+const withCustomAuth = (secretKey: string): ServerPlugin => {
+  return (app, config) => {
+    app.use((req, res, next) => {
+      // Your custom auth logic
+      next();
+    });
+  };
+};
+
+// Use it
+const app = createServerWithPlugins(
+  {},
+  withCustomAuth('my-secret'),
+  withLogging()
+);
+```
+
+## Examples
+
+### Microservice Template
+```typescript
+import { 
+  createServerWithPlugins,
+  withHealthCheck,
+  withLogging,
+  withErrorHandler,
+  withRequestId,
+  startServerWithShutdown
+} from '@naman_deep_singh/server-utils';
+
+const app = createServerWithPlugins(
+  {
+    cors: {
+      origin: process.env.ALLOWED_ORIGINS?.split(',') || '*',
+      credentials: true
+    },
+    helmet: true
+  },
+  withRequestId(),
+  withLogging(process.env.NODE_ENV === 'production' ? 'simple' : 'detailed'),
+  withHealthCheck('/health', {
+    customChecks: [
+      {
+        name: 'database',
+        check: async () => {
+          try {
+            await prisma.$queryRaw`SELECT 1`;
+            return true;
+          } catch {
+            return false;
+          }
+        }
+      }
+    ]
+  }),
+  withErrorHandler()
+);
+
+// Your routes
+app.use('/api', apiRoutes);
+
+const PORT = Number(process.env.PORT) || 3000;
+startServerWithShutdown(app, PORT, {
+  onShutdown: async () => {
+    await prisma.$disconnect();
+  }
+});
+```
+
+## TypeScript Support
+
+Full TypeScript support with comprehensive type definitions for all utilities and plugins.
+
+## License
+
+ISC

package/dist/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/health.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createHealthCheck = createHealthCheck;
+exports.withHealthCheck = withHealthCheck;
+exports.addHealthCheck = addHealthCheck;
+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'
+            });
+        }
+    };
+}
+function withHealthCheck(path = '/health', config = {}) {
+    return (app) => {
+        app.get(path, createHealthCheck(config));
+    };
+}
+// Convenience function for direct use
+function addHealthCheck(app, path = '/health', config = {}) {
+    app.get(path, createHealthCheck(config));
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { createServer, withPlugin, createServerWithPlugins } from './server';
+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 type { ServerConfig, HealthCheckConfig, HealthCheck, GracefulShutdownConfig, ServerPlugin } from './types';

package/dist/index.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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.createServerWithPlugins = exports.withPlugin = exports.createServer = void 0;
+// Core server utilities
+var server_1 = require("./server");
+Object.defineProperty(exports, "createServer", { enumerable: true, get: function () { return server_1.createServer; } });
+Object.defineProperty(exports, "withPlugin", { enumerable: true, get: function () { return server_1.withPlugin; } });
+Object.defineProperty(exports, "createServerWithPlugins", { enumerable: true, get: function () { return server_1.createServerWithPlugins; } });
+// Health check utilities
+var health_1 = require("./health");
+Object.defineProperty(exports, "createHealthCheck", { enumerable: true, get: function () { return health_1.createHealthCheck; } });
+Object.defineProperty(exports, "withHealthCheck", { enumerable: true, get: function () { return health_1.withHealthCheck; } });
+Object.defineProperty(exports, "addHealthCheck", { enumerable: true, get: function () { return health_1.addHealthCheck; } });
+// Graceful shutdown utilities
+var shutdown_1 = require("./shutdown");
+Object.defineProperty(exports, "createGracefulShutdown", { enumerable: true, get: function () { return shutdown_1.createGracefulShutdown; } });
+Object.defineProperty(exports, "withGracefulShutdown", { enumerable: true, get: function () { return shutdown_1.withGracefulShutdown; } });
+Object.defineProperty(exports, "startServerWithShutdown", { enumerable: true, get: function () { return shutdown_1.startServerWithShutdown; } });
+// Middleware utilities
+var middleware_1 = require("./middleware");
+Object.defineProperty(exports, "createLoggingMiddleware", { enumerable: true, get: function () { return middleware_1.createLoggingMiddleware; } });
+Object.defineProperty(exports, "createErrorHandler", { enumerable: true, get: function () { return middleware_1.createErrorHandler; } });
+Object.defineProperty(exports, "createRequestIdMiddleware", { enumerable: true, get: function () { return middleware_1.createRequestIdMiddleware; } });
+Object.defineProperty(exports, "createValidationMiddleware", { enumerable: true, get: function () { return middleware_1.createValidationMiddleware; } });
+Object.defineProperty(exports, "createRateLimitMiddleware", { enumerable: true, get: function () { return middleware_1.createRateLimitMiddleware; } });
+Object.defineProperty(exports, "createAuthMiddleware", { enumerable: true, get: function () { return middleware_1.createAuthMiddleware; } });
+Object.defineProperty(exports, "withLogging", { enumerable: true, get: function () { return middleware_1.withLogging; } });
+Object.defineProperty(exports, "withErrorHandler", { enumerable: true, get: function () { return middleware_1.withErrorHandler; } });
+Object.defineProperty(exports, "withRequestId", { enumerable: true, get: function () { return middleware_1.withRequestId; } });
+Object.defineProperty(exports, "withValidation", { enumerable: true, get: function () { return middleware_1.withValidation; } });
+Object.defineProperty(exports, "withRateLimit", { enumerable: true, get: function () { return middleware_1.withRateLimit; } });
+Object.defineProperty(exports, "withAuth", { enumerable: true, get: function () { return middleware_1.withAuth; } });
+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; } });
+// Utility functions
+var utils_1 = require("./utils");
+Object.defineProperty(exports, "getEnv", { enumerable: true, get: function () { return utils_1.getEnv; } });
+Object.defineProperty(exports, "getEnvNumber", { enumerable: true, get: function () { return utils_1.getEnvNumber; } });
+Object.defineProperty(exports, "getEnvBoolean", { enumerable: true, get: function () { return utils_1.getEnvBoolean; } });

package/dist/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: any) => 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<any> | any;
+    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;

package/dist/middleware.js

@@ -0,0 +1,217 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLoggingMiddleware = createLoggingMiddleware;
+exports.createErrorHandler = createErrorHandler;
+exports.createRequestIdMiddleware = createRequestIdMiddleware;
+exports.createValidationMiddleware = createValidationMiddleware;
+exports.createRateLimitMiddleware = createRateLimitMiddleware;
+exports.createAuthMiddleware = createAuthMiddleware;
+exports.withLogging = withLogging;
+exports.withErrorHandler = withErrorHandler;
+exports.withRequestId = withRequestId;
+exports.withValidation = withValidation;
+exports.withRateLimit = withRateLimit;
+exports.withAuth = withAuth;
+exports.validateFields = validateFields;
+exports.rateLimit = rateLimit;
+exports.requireAuth = requireAuth;
+// Logging middleware
+function createLoggingMiddleware(format = 'simple') {
+    return (req, res, next) => {
+        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
+function createErrorHandler() {
+    return (err, req, res, next) => {
+        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
+function createRequestIdMiddleware() {
+    return (req, res, next) => {
+        const requestId = Math.random().toString(36).substring(2, 15);
+        req.requestId = requestId;
+        res.setHeader('X-Request-ID', requestId);
+        next();
+    };
+}
+function createValidationMiddleware(rules) {
+    return (req, res, next) => {
+        const errors = [];
+        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();
+    };
+}
+const rateLimitStore = new Map();
+function createRateLimitMiddleware(config = {}) {
+    const { windowMs = 15 * 60 * 1000, maxRequests = 100, message = 'Too many requests, please try again later', keyGenerator = (req) => req.ip || 'unknown' } = config;
+    return (req, res, next) => {
+        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();
+    };
+}
+function createAuthMiddleware(config) {
+    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, res, next) => {
+        try {
+            const token = tokenExtractor(req);
+            if (!token) {
+                return res.status(401).json({
+                    status: false,
+                    message: unauthorizedMessage
+                });
+            }
+            const user = await tokenValidator(token);
+            req.user = user;
+            next();
+        }
+        catch (error) {
+            return res.status(401).json({
+                status: false,
+                message: unauthorizedMessage
+            });
+        }
+    };
+}
+// Plugin versions
+function withLogging(format = 'simple') {
+    return (app) => {
+        app.use(createLoggingMiddleware(format));
+    };
+}
+function withErrorHandler() {
+    return (app) => {
+        app.use(createErrorHandler());
+    };
+}
+function withRequestId() {
+    return (app) => {
+        app.use(createRequestIdMiddleware());
+    };
+}
+function withValidation(rules) {
+    return (app) => {
+        app.use(createValidationMiddleware(rules));
+    };
+}
+function withRateLimit(config = {}) {
+    return (app) => {
+        app.use(createRateLimitMiddleware(config));
+    };
+}
+function withAuth(config) {
+    return (app) => {
+        app.use(createAuthMiddleware(config));
+    };
+}
+// Convenience functions for route-specific middleware
+function validateFields(rules) {
+    return createValidationMiddleware(rules);
+}
+function rateLimit(config = {}) {
+    return createRateLimitMiddleware(config);
+}
+function requireAuth(config) {
+    return createAuthMiddleware(config);
+}

package/dist/server.d.ts

@@ -0,0 +1,5 @@
+import express from 'express';
+import { ServerConfig, ServerPlugin } from './types';
+export declare function createServer(config?: ServerConfig): express.Application;
+export declare function withPlugin(app: express.Application, plugin: ServerPlugin, config?: ServerConfig): express.Application;
+export declare function createServerWithPlugins(config?: ServerConfig, ...plugins: ServerPlugin[]): express.Application;

package/dist/server.js

@@ -0,0 +1,43 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+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);
+        });
+    }
+    return app;
+}
+function withPlugin(app, plugin, config = {}) {
+    plugin(app, config);
+    return app;
+}
+function createServerWithPlugins(config = {}, ...plugins) {
+    const app = createServer(config);
+    plugins.forEach(plugin => {
+        plugin(app, config);
+    });
+    return app;
+}

package/dist/shutdown.d.ts

@@ -0,0 +1,5 @@
+import { Server } from 'http';
+import { GracefulShutdownConfig, ServerPlugin } from './types';
+export declare function createGracefulShutdown(server: Server, config?: GracefulShutdownConfig): void;
+export declare function withGracefulShutdown(config?: GracefulShutdownConfig): ServerPlugin;
+export declare function startServerWithShutdown(app: any, port: number, shutdownConfig?: GracefulShutdownConfig): Server;