ts-packages 1.0.0 → 2.0.0

package/packages/server-utils/src/express-augment.d.ts

@@ -0,0 +1,35 @@
+// Express augmentation to type runtime properties we attach in middleware
+declare global {
+	namespace Express {
+		interface Request {
+			// cache instance attached at runtime (may be provided by server setup)
+			cache?: unknown
+			// session store attached at runtime
+			sessionStore?: unknown
+			// session id extracted from cookie/header
+			sessionId?: string | undefined
+			// user
+			user?: unknown
+			// request id
+			requestId?: string
+			// helper helpers
+			getSession?: () => Promise<unknown>
+			createSession?: (
+				id: string,
+				data: Record<string, unknown>,
+				ttl?: number,
+			) => Promise<unknown>
+		}
+
+		interface Application {
+			locals: Record<string, unknown> & {
+				cache?: unknown
+				cacheDefaultTTL?: number
+				sessionStore?: unknown
+				sessionCookieName?: string
+			}
+		}
+	}
+}
+
+export {}

package/packages/server-utils/src/index.ts

@@ -1,113 +1,150 @@
 // Core server utilities
-export { ExpressServer, createServer } from './server';
-export type { ServerInstance, ServerInfo, GrpcService, RpcMethod, WebhookConfig } from './server';
+export { ExpressServer, createServer } from './core/server'
+export type {
+	ServerInstance,
+	ServerInfo,
+	GrpcService,
+	RpcMethod,
+	WebhookConfig,
+} from './core/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';
+export {
+	createHealthCheck,
+	withHealthCheck,
+	addHealthCheck,
+} from './core/health'
 
 // Graceful shutdown utilities
-export { createGracefulShutdown, withGracefulShutdown, startServerWithShutdown } from './shutdown';
+export {
+	createGracefulShutdown,
+	withGracefulShutdown,
+	startServerWithShutdown,
+} from './core/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';
+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'
 
 // Utility functions
 export {
-  getEnv,
-  getEnvNumber,
-  getEnvBoolean
-} from './utils';
+	getEnv,
+	getEnvNumber,
+	getEnvBoolean,
+} from './utils/utils'
+
+// Periodic health monitoring
+export { PeriodicHealthMonitor } from './core/periodic-health'
 
 // Types
-export type { 
-  ServerConfig, 
-  HealthCheckConfig, 
-  HealthCheck, 
-  GracefulShutdownConfig, 
-  ServerPlugin,
-  SocketIOConfig,
-  SocketInstance 
-} from './types';
+export type {
+	ServerConfig,
+	HealthCheckConfig,
+	HealthCheck,
+	GracefulShutdownConfig,
+	ServerPlugin,
+	SocketIOConfig,
+	SocketInstance,
+	PeriodicHealthCheckConfig,
+	HealthCheckService,
+} from './types'
 
+import {
+	addHealthCheck,
+	createHealthCheck,
+	withHealthCheck,
+} from './core/health'
+import { PeriodicHealthMonitor } from './core/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 { ExpressServer, createServer } from './core/server'
+import {
+	createGracefulShutdown,
+	startServerWithShutdown,
+	withGracefulShutdown,
+} from './core/shutdown'
+import {
+	createAuthMiddleware,
+	createErrorHandler,
+	createLoggingMiddleware,
+	createRateLimitMiddleware,
+	createRequestIdMiddleware,
+	createValidationMiddleware,
+	rateLimit,
+	requireAuth,
+	validateFields,
+	withAuth,
+	withErrorHandler,
+	withLogging,
+	withRateLimit,
+	withRequestId,
+	withValidation,
+} from './middleware'
+import { getEnv, getEnvBoolean, getEnvNumber } from './utils/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
-};
+	// 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;
+export default ServerUtils

package/packages/server-utils/src/middleware/auth.middleware.ts

@@ -0,0 +1,66 @@
+import { UnauthorizedError } from '@naman_deep_singh/errors-utils'
+import { extractToken, safeVerifyToken } from '@naman_deep_singh/security'
+
+import type {
+	NextFunction,
+	Request,
+	RequestHandler,
+	Response,
+} from 'node_modules/@types/express'
+
+// Authentication middleware helper
+export interface AuthConfig {
+	secret: string
+	unauthorizedMessage?: string
+	tokenExtractor?: (req: Request) => string | null
+}
+
+export function createAuthMiddleware(config: AuthConfig): RequestHandler {
+	const {
+		secret,
+		unauthorizedMessage = 'Unauthorized access',
+
+		tokenExtractor = (req) =>
+			extractToken({
+				header: req.headers.authorization || undefined,
+				cookies: req.cookies,
+				query: req.query as Record<string, any>,
+				body: req.body,
+			}),
+	} = config
+
+	return async (req: Request, _res: Response, next: NextFunction) => {
+		try {
+			// Extract token from request
+			const token = tokenExtractor(req)
+
+			if (!token) {
+				const error = new UnauthorizedError(unauthorizedMessage, {
+					reason: 'No token provided',
+				})
+				return next(error)
+			}
+
+			// Use safe verify token from security package
+			const result = safeVerifyToken(token, secret)
+
+			if (!result.valid) {
+				const error = new UnauthorizedError(unauthorizedMessage, {
+					reason: 'Invalid or expired token',
+					originalError: result.error?.message,
+				})
+				return next(error)
+			}
+
+			// Attach the verified payload as user
+			req.user = result.payload
+			next()
+		} catch (error) {
+			const unauthorizedError = new UnauthorizedError(
+				unauthorizedMessage,
+				error instanceof Error ? { originalError: error.message } : error,
+			)
+			return next(unauthorizedError)
+		}
+	}
+}

package/packages/server-utils/src/middleware/cache.middleware.ts

@@ -0,0 +1,68 @@
+import type {
+	NextFunction,
+	Request,
+	RequestHandler,
+	Response,
+} from 'node_modules/@types/express'
+
+// Cache response middleware (per-route opt-in)
+export function cacheResponse(ttl?: number): RequestHandler {
+	return async (req: Request, res: Response, next: NextFunction) => {
+		try {
+			if (req.method !== 'GET') return next()
+
+			const cache = (req.cache ?? req.app.locals.cache) as
+				| { get?: Function; set?: Function }
+				| undefined
+			const defaultTTL = req.app.locals.cacheDefaultTTL as number | undefined
+			if (!cache || typeof cache.get !== 'function') return next()
+
+			const key = `${req.originalUrl}`
+			try {
+				const cached = await (cache.get as Function)(key)
+				if (cached !== null && cached !== undefined) {
+					res.setHeader('X-Cache', 'HIT')
+					return res.json(cached)
+				}
+			} catch (cacheErr) {
+				console.error(`[Cache] Failed to retrieve key "${key}":`, cacheErr)
+				// Continue without cache hit
+			}
+
+			const originalJson = res.json.bind(res)
+			res.json = (body: unknown) => {
+				try {
+					const expiry = ttl ?? defaultTTL
+					if (expiry && cache && typeof cache.set === 'function') {
+						;(cache.set as Function)(key, body, expiry).catch(
+							(err: unknown) => {
+								console.error(
+									`[Cache] Failed to set key "${key}" with TTL ${expiry}:`,
+									err,
+								)
+							},
+						)
+					} else if (cache) {
+						if (typeof cache.set === 'function') {
+							;(cache.set as Function)(key, body).catch((err: unknown) => {
+								console.error(`[Cache] Failed to set key "${key}":`, err)
+							})
+						}
+					}
+				} catch (e) {
+					console.error(`[Cache] Error during cache.set operation:`, e)
+				}
+				res.setHeader('X-Cache', 'MISS')
+				return originalJson(body)
+			}
+
+			next()
+		} catch (err) {
+			console.error(
+				'[Cache] Unexpected error in cacheResponse middleware:',
+				err,
+			)
+			next()
+		}
+	}
+}

package/packages/server-utils/src/middleware/errorHandler.middleware.ts

@@ -0,0 +1,44 @@
+import type {
+	ErrorRequestHandler,
+	NextFunction,
+	Request,
+	Response,
+} from 'node_modules/@types/express'
+
+// Error handling middleware
+export function createErrorHandler(): ErrorRequestHandler {
+	return (err: unknown, _req: Request, res: Response, next: 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({
+			success: false,
+			message,
+			data: undefined,
+			error: {
+				message,
+				...(process.env.NODE_ENV !== 'production' && {
+					details: { stack: errorObj.stack },
+				}),
+			},
+			meta: null,
+		})
+	}
+}

package/packages/server-utils/src/middleware/index.ts

@@ -0,0 +1,46 @@
+// Authentication Middleware
+export { AuthConfig, createAuthMiddleware } from './auth.middleware'
+
+// Cache Middleware
+export { cacheResponse } from './cache.middleware'
+
+// Error Handler Middleware
+export { createErrorHandler } from './errorHandler.middleware'
+
+// Logging Middleware
+export { createLoggingMiddleware } from './logging.middleware'
+
+// Rate Limiter Middleware
+export {
+	RateLimitConfig,
+	createRateLimitMiddleware,
+} from './rateLimiter.middleware'
+
+// Request ID Middleware
+export { createRequestIdMiddleware } from './requestId.middleware'
+
+// Session Middleware
+export { useSession } from './session.middleware'
+
+// Validation Middleware
+export {
+	ValidationRule,
+	createValidationMiddleware,
+} from './validation.middleware'
+
+// Plugin middleware functions (for application-level middleware)
+export {
+	withLogging,
+	withErrorHandler,
+	withRequestId,
+	withValidation,
+	withRateLimit,
+	withAuth,
+} from './plugins.middleware'
+
+// Convenience middleware functions (for route-level middleware)
+export {
+	validateFields,
+	rateLimit,
+	requireAuth,
+} from './plugins.middleware'

package/packages/server-utils/src/middleware/logging.middleware.ts

@@ -0,0 +1,29 @@
+import type {
+	NextFunction,
+	Request,
+	RequestHandler,
+	Response,
+} from 'node_modules/@types/express'
+
+// Logging middleware
+export function createLoggingMiddleware(
+	format: 'simple' | 'detailed' = 'simple',
+): RequestHandler {
+	return (req: Request, res: Response, next: 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()
+	}
+}

package/packages/server-utils/src/middleware/plugins.middleware.ts

@@ -0,0 +1,64 @@
+import { createAuthMiddleware } from './auth.middleware'
+import { createErrorHandler } from './errorHandler.middleware'
+import { createLoggingMiddleware } from './logging.middleware'
+import { createRateLimitMiddleware } from './rateLimiter.middleware'
+import { createRequestIdMiddleware } from './requestId.middleware'
+import { createValidationMiddleware } from './validation.middleware'
+
+import type { Application, RequestHandler } from 'express'
+import type { ServerPlugin } from '../types'
+import type { AuthConfig } from './auth.middleware'
+import type { RateLimitConfig } from './rateLimiter.middleware'
+import type { ValidationRule } from './validation.middleware'
+
+// Plugin versions
+export function withLogging(
+	format: 'simple' | 'detailed' = 'simple',
+): ServerPlugin {
+	return (app: Application) => {
+		app.use(createLoggingMiddleware(format))
+	}
+}
+
+export function withErrorHandler(): ServerPlugin {
+	return (app: Application) => {
+		app.use(createErrorHandler())
+	}
+}
+
+export function withRequestId(): ServerPlugin {
+	return (app: Application) => {
+		app.use(createRequestIdMiddleware())
+	}
+}
+
+export function withValidation(rules: ValidationRule[]): ServerPlugin {
+	return (app: Application) => {
+		app.use(createValidationMiddleware(rules))
+	}
+}
+
+export function withRateLimit(config: RateLimitConfig = {}): ServerPlugin {
+	return (app: Application) => {
+		app.use(createRateLimitMiddleware(config))
+	}
+}
+
+export function withAuth(config: AuthConfig): ServerPlugin {
+	return (app: Application) => {
+		app.use(createAuthMiddleware(config))
+	}
+}
+
+// Convenience functions for route-specific middleware
+export function validateFields(rules: ValidationRule[]): RequestHandler {
+	return createValidationMiddleware(rules)
+}
+
+export function rateLimit(config: RateLimitConfig = {}): RequestHandler {
+	return createRateLimitMiddleware(config)
+}
+
+export function requireAuth(config: AuthConfig): RequestHandler {
+	return createAuthMiddleware(config)
+}

package/packages/server-utils/src/middleware/rateLimiter.middleware.ts

@@ -0,0 +1,59 @@
+import type {
+	NextFunction,
+	Request,
+	RequestHandler,
+	Response,
+} from 'node_modules/@types/express'
+
+// Rate limiting middleware
+export interface RateLimitConfig {
+	windowMs?: number
+	maxRequests?: number
+	message?: string
+	keyGenerator?: (req: Request) => string
+}
+
+const rateLimitStore = new Map<string, { count: number; resetTime: number }>()
+
+export function createRateLimitMiddleware(
+	config: RateLimitConfig = {},
+): RequestHandler {
+	const {
+		windowMs = 15 * 60 * 1000,
+		maxRequests = 100,
+		message = 'Too many requests, please try again later',
+		keyGenerator = (req) => req.ip || 'unknown',
+	} = config
+
+	return (req: Request, res: Response, next: 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({
+				success: false,
+				message,
+				data: undefined,
+				error: {
+					message,
+					details: {
+						retryAfter: Math.ceil((record.resetTime - now) / 1000),
+					},
+				},
+				meta: null,
+			})
+		}
+
+		record.count++
+		next()
+	}
+}

package/packages/server-utils/src/middleware/requestId.middleware.ts

@@ -0,0 +1,16 @@
+import type {
+	NextFunction,
+	Request,
+	RequestHandler,
+	Response,
+} from 'node_modules/@types/express'
+
+// Request ID middleware
+export function createRequestIdMiddleware(): RequestHandler {
+	return (req: Request, res: Response, next: NextFunction) => {
+		const requestId = Math.random().toString(36).substring(2, 15)
+		req.requestId = requestId
+		res.setHeader('X-Request-ID', requestId)
+		next()
+	}
+}