@naman_deep_singh/server-utils 1.0.8 → 1.2.0

package/dist/types/periodic-health.d.ts

@@ -0,0 +1,11 @@
+import { PeriodicHealthCheckConfig } from './types';
+export declare class PeriodicHealthMonitor {
+    private intervals;
+    private config;
+    private serviceName;
+    constructor(config: PeriodicHealthCheckConfig, serviceName: string);
+    start(): void;
+    stop(): void;
+    private checkServiceHealth;
+    getHealthStatus(): Promise<Record<string, boolean>>;
+}

package/dist/types/server.d.ts

@@ -0,0 +1,70 @@
+import express from 'express';
+import { Server } from 'http';
+import { ServerConfig, SocketIOConfig } from './types';
+export interface GrpcService {
+    service: Record<string, unknown>;
+    implementation: Record<string, (...args: unknown[]) => unknown>;
+}
+export interface RpcMethod {
+    [key: string]: (params: unknown[], callback: (error: Error | null, result?: unknown) => void) => void;
+}
+export interface WebhookConfig {
+    path: string;
+    secret?: string;
+    handler: (payload: Record<string, unknown>, headers: Record<string, string | string[]>) => void | Promise<void>;
+}
+export interface GrpcServerInstance {
+    start(): void;
+    forceShutdown(): void;
+    addService(service: unknown, implementation: unknown): void;
+    bindAsync(address: string, credentials: unknown, callback: () => void): void;
+}
+export interface ServerInstanceConfig extends Required<Omit<ServerConfig, 'socketIO' | 'name' | 'version'>> {
+    name: string;
+    version: string;
+    startTime: Date;
+    socketIO?: SocketIOConfig;
+}
+export interface ServerInstance {
+    app: express.Application;
+    server?: Server;
+    config: ServerInstanceConfig;
+    start(): Promise<ServerInstance>;
+    stop(): Promise<void>;
+    getInfo(): ServerInfo;
+    addGrpcService(service: Record<string, unknown>, implementation: Record<string, (...args: unknown[]) => unknown>, port?: number): void;
+    addRpcMethods(methods: RpcMethod, path?: string): void;
+    addWebhook(config: WebhookConfig): void;
+    addSocketIO(config?: SocketIOConfig): unknown;
+}
+export interface ServerInfo {
+    name: string;
+    version: string;
+    port: number;
+    uptime: number;
+    status: 'starting' | 'running' | 'stopping' | 'stopped';
+    startTime: Date;
+}
+export declare class ExpressServer implements ServerInstance {
+    app: express.Application;
+    server?: Server;
+    config: ServerInstanceConfig;
+    private status;
+    private grpcServices;
+    private grpcServer?;
+    private rpcMethods;
+    private socketIO?;
+    private healthMonitor?;
+    constructor(name?: string, version?: string, config?: ServerConfig);
+    private setupMiddleware;
+    private setupCacheAndSession;
+    private setupPeriodicHealthMonitoring;
+    start(): Promise<ServerInstance>;
+    stop(): Promise<void>;
+    getInfo(): ServerInfo;
+    addGrpcService(service: Record<string, unknown>, implementation: Record<string, (...args: unknown[]) => unknown>, port?: number): void;
+    addRpcMethods(methods: RpcMethod, path?: string): void;
+    addWebhook(config: WebhookConfig): void;
+    addSocketIO(config?: SocketIOConfig): unknown;
+}
+export declare function createServer(name?: string, version?: string, config?: ServerConfig): ServerInstance;

package/dist/types/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, serverName?: string, serverVersion?: string): Server;

package/dist/types/types.d.ts

@@ -0,0 +1,87 @@
+import express from 'express';
+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;
+    helmet?: boolean;
+    json?: boolean;
+    cookieParser?: boolean;
+    customMiddleware?: express.RequestHandler[];
+    healthCheck?: boolean | string;
+    gracefulShutdown?: boolean;
+    socketIO?: SocketIOConfig;
+    periodicHealthCheck?: PeriodicHealthCheckConfig;
+    name?: string;
+    version?: string;
+    cache?: {
+        enabled?: boolean;
+        adapter?: 'redis' | 'memcache' | 'memory';
+        options?: unknown;
+        defaultTTL?: number;
+    };
+    session?: {
+        enabled?: boolean;
+        cookieName?: string;
+        ttl?: number;
+        cookieOptions?: {
+            path?: string;
+            httpOnly?: boolean;
+            secure?: boolean;
+            sameSite?: 'lax' | 'strict' | 'none';
+        };
+    };
+}
+export interface PeriodicHealthCheckConfig {
+    enabled?: boolean;
+    interval?: number;
+    services?: HealthCheckService[];
+}
+export interface HealthCheckService {
+    name: string;
+    url: string;
+    timeout?: number;
+}
+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;
+    customChecks?: HealthCheck[];
+}
+export interface HealthCheck {
+    name: string;
+    check: () => Promise<boolean>;
+}
+export interface GracefulShutdownConfig {
+    timeout?: number;
+    onShutdown?: () => Promise<void>;
+    serverName?: string;
+    serverVersion?: string;
+}
+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/dist/types/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/package.json

@@ -1,12 +1,22 @@
 {
   "name": "@naman_deep_singh/server-utils",
-  "version": "1.0.8",
+  "version": "1.2.0",
   "description": "Extensible server utilities for Express.js microservices with TypeScript",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "scripts": {
-    "build": "tsc"
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js",
+      "types": "./dist/types/index.d.ts"
+    }
   },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
   "keywords": [
     "server",
     "express",
@@ -16,16 +26,22 @@
   ],
   "author": "Naman Deep Singh",
   "license": "ISC",
-  "packageManager": "pnpm@10.20.0",
   "dependencies": {
-    "express": "^5.1.0",
-    "cors": "^2.8.5",
-    "helmet": "^8.1.0",
+    "@naman_deep_singh/cache": "^1.2.0",
+    "@types/express": "^5.0.5",
     "cookie-parser": "^1.4.6",
-    "@types/express": "^5.0.5"
+    "cors": "^2.8.5",
+    "express": "^5.1.0",
+    "helmet": "^8.1.0"
   },
   "devDependencies": {
     "@types/cors": "^2.8.19",
+    "rimraf": "^5.0.5",
     "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "pnpm run build:types && tsc -p tsconfig.cjs.json && tsc -p tsconfig.esm.json",
+    "build:types": "tsc -p tsconfig.base.json --emitDeclarationOnly --outDir dist/types",
+    "clean": "rimraf dist"
   }
 }

package/src/health.ts

@@ -1,47 +0,0 @@
-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

@@ -1,126 +0,0 @@
-// Core server utilities
-export { ExpressServer, createServer } from './server';
-export type { ServerInstance, ServerInfo, GrpcService, RpcMethod, WebhookConfig } from './server';
-
-// Express re-exports (to avoid direct Express dependency in services)
-export { Request, Response, NextFunction, Router, Application } from 'express';
-export type { RequestHandler, ErrorRequestHandler } 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,
-  type ValidationRule,
-  type RateLimitConfig,
-  type AuthConfig
-} from './middleware';
-
-// Utility functions
-export {
-  getEnv,
-  getEnvNumber,
-  getEnvBoolean
-} from './utils';
-
-// Periodic health monitoring
-export { PeriodicHealthMonitor } from './periodic-health';
-
-// Types
-export type {
-  ServerConfig,
-  HealthCheckConfig,
-  HealthCheck,
-  GracefulShutdownConfig,
-  ServerPlugin,
-  SocketIOConfig,
-  SocketInstance,
-  PeriodicHealthCheckConfig,
-  HealthCheckService
-} 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';
-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/src/middleware.ts

@@ -1,275 +0,0 @@
-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: unknown, req: express.Request, res: express.Response, next: express.NextFunction) => {
-    console.error('Error:', err);
-    
-    if (res.headersSent) {
-      return next(err);
-    }
-    
-    // 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' 
-      : errorObj.message || 'Unknown error';
-    
-    res.status(status).json({
-      status: false,
-      message,
-      ...(process.env.NODE_ENV !== 'production' && { stack: errorObj.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 express.Request & { requestId: string }).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: unknown) => 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<unknown> | unknown;
-  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 express.Request & { user: unknown }).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);
-}