@naman_deep_singh/server-utils 1.0.8 → 1.2.0

package/dist/{server.d.ts → cjs/server.d.ts}

@@ -57,6 +57,7 @@ export declare class ExpressServer implements ServerInstance {
     private healthMonitor?;
     constructor(name?: string, version?: string, config?: ServerConfig);
     private setupMiddleware;
+    private setupCacheAndSession;
     private setupPeriodicHealthMonitoring;
     start(): Promise<ServerInstance>;
     stop(): Promise<void>;

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

@@ -9,6 +9,7 @@ const express_1 = __importDefault(require("express"));
 const shutdown_1 = require("./shutdown");
 const periodic_health_1 = require("./periodic-health");
 const crypto_1 = __importDefault(require("crypto"));
+const cache_1 = require("@naman_deep_singh/cache");
 class ExpressServer {
     constructor(name = 'Express Server', version = '1.0.0', config = {}) {
         this.status = 'stopped';
@@ -28,8 +29,14 @@ class ExpressServer {
             healthCheck: config.healthCheck ?? true,
             gracefulShutdown: config.gracefulShutdown ?? true,
             socketIO: config.socketIO,
-            periodicHealthCheck: config.periodicHealthCheck || { enabled: false }
+            periodicHealthCheck: config.periodicHealthCheck || { enabled: false },
+            cache: config.cache || { enabled: false },
+            session: config.session || { enabled: false }
         };
+        // Initialize locals for cache/session
+        this.app.locals.cache = undefined;
+        this.app.locals.sessionStore = undefined;
+        this.app.locals.cacheDefaultTTL = config.cache?.defaultTTL;
         // Apply middleware based on configuration
         this.setupMiddleware();
         // Setup periodic health monitoring
@@ -80,17 +87,104 @@ class ExpressServer {
         // 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({
+            this.app.get(healthPath, async (req, res) => {
+                const base = {
                     status: 'healthy',
                     service: this.config.name,
                     version: this.config.version,
                     uptime: Date.now() - this.config.startTime.getTime(),
                     timestamp: new Date().toISOString()
-                });
+                };
+                // If cache is enabled, include its health
+                const cache = req.app.locals.cache;
+                if (cache && typeof cache.isAlive === 'function') {
+                    try {
+                        base.cache = await cache.isAlive();
+                    }
+                    catch (e) {
+                        base.cache = { isAlive: false, adapter: 'unknown', timestamp: new Date(), error: e.message };
+                    }
+                }
+                res.status(200).json(base);
             });
         }
     }
+    async setupCacheAndSession(config, serverName) {
+        try {
+            // Initialize cache if enabled
+            if (config.cache && config.cache.enabled) {
+                try {
+                    const provided = config.cache.options;
+                    let cacheConfig = provided && typeof provided === 'object' ? provided : undefined;
+                    if (!cacheConfig) {
+                        cacheConfig = { adapter: config.cache.adapter || 'memory' };
+                    }
+                    console.log(`🔄 [${serverName}] Initializing cache adapter: ${config.cache.adapter || 'memory'}...`);
+                    // Use createWithFallback to prefer primary and fall back to memory when configured
+                    const cache = await cache_1.CacheFactory.createWithFallback({
+                        ...(cacheConfig || {}),
+                        ttl: cacheConfig?.ttl ?? config.cache?.defaultTTL
+                    });
+                    this.app.locals.cache = cache;
+                    this.cache = cache;
+                    this.app.locals.cacheDefaultTTL = config.cache?.defaultTTL;
+                    // attach per-request helper middleware
+                    this.app.use((req, _res, next) => {
+                        req.cache = cache;
+                        next();
+                    });
+                    console.log(`✅ [${serverName}] Cache initialized successfully (adapter: ${(cacheConfig.adapter || 'memory')})`);
+                }
+                catch (err) {
+                    console.error(`❌ [${serverName}] Failed to initialize cache (fallback to memory if enabled):`, err instanceof Error ? err.message : err);
+                    // Cache initialization error is critical but we continue to allow graceful fallback
+                }
+            }
+            // Initialize session if enabled
+            if (config.session && config.session.enabled) {
+                const cookieName = config.session.cookieName || `${serverName.replace(/\s+/g, '_').toLowerCase()}.sid`;
+                const ttl = config.session.ttl ?? 3600;
+                let cache = this.app.locals.cache;
+                if (!cache) {
+                    // fallback to in-memory cache for session store
+                    try {
+                        cache = cache_1.CacheFactory.create({ adapter: 'memory' });
+                        this.app.locals.cache = cache;
+                        this.cache = cache;
+                        console.log(`📝 [${serverName}] Session store using in-memory cache`);
+                    }
+                    catch (e) {
+                        console.error(`❌ [${serverName}] Failed to create in-memory cache for sessions:`, e instanceof Error ? e.message : e);
+                    }
+                }
+                else {
+                    console.log(`📝 [${serverName}] Session store initialized with configured cache adapter`);
+                }
+                if (!cache) {
+                    console.error(`❌ [${serverName}] CRITICAL: Session enabled but no cache available to store sessions. Session functionality will be unavailable.`);
+                }
+                else {
+                    const store = new cache_1.SessionStore(cache, { ttl });
+                    this.app.locals.sessionStore = store;
+                    this.app.locals.sessionCookieName = cookieName;
+                    this.sessionStore = store;
+                    // attach session middleware globally so req.sessionStore is available
+                    try {
+                        // eslint-disable-next-line @typescript-eslint/no-var-requires
+                        const { useSession } = require('./middleware');
+                        this.app.use(useSession(cookieName));
+                        console.log(`✅ [${serverName}] Session middleware enabled (cookie: ${cookieName}, TTL: ${ttl}s)`);
+                    }
+                    catch (err) {
+                        console.error(`❌ [${serverName}] Session middleware not available:`, err instanceof Error ? err.message : err);
+                    }
+                }
+            }
+        }
+        catch (err) {
+            console.error(`❌ [${serverName}] Error during cache/session setup:`, err instanceof Error ? err.message : err);
+        }
+    }
     setupPeriodicHealthMonitoring() {
         if (this.config.periodicHealthCheck?.enabled) {
             this.healthMonitor = new periodic_health_1.PeriodicHealthMonitor(this.config.periodicHealthCheck, this.config.name);
@@ -98,6 +192,8 @@ class ExpressServer {
     }
     async start() {
         this.status = 'starting';
+        // Initialize cache and session before starting the server
+        await this.setupCacheAndSession(this.config, this.config.name);
         return new Promise((resolve, reject) => {
             try {
                 this.server = this.app.listen(this.config.port, () => {
@@ -111,6 +207,25 @@ class ExpressServer {
                                 if (this.healthMonitor) {
                                     this.healthMonitor.stop();
                                 }
+                                // Close cache and session store if present
+                                try {
+                                    const cache = this.app.locals.cache;
+                                    if (cache && typeof cache.close === 'function') {
+                                        await cache.close();
+                                    }
+                                }
+                                catch (e) {
+                                    console.warn(`${this.config.name}: Error closing cache`, e);
+                                }
+                                try {
+                                    const store = this.app.locals.sessionStore;
+                                    if (store && typeof store.close === 'function') {
+                                        await store.close();
+                                    }
+                                }
+                                catch (e) {
+                                    // SessionStore may not have close; ignore
+                                }
                             }
                         });
                     }

package/dist/{types.d.ts → cjs/types.d.ts}

@@ -22,6 +22,23 @@ export interface ServerConfig {
     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;

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, cacheResponse, useSession, 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, cacheResponse, useSession } 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,39 @@
+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;
+export declare function cacheResponse(ttl?: number): express.RequestHandler;
+export declare function useSession(cookieName?: string): express.RequestHandler;