ts-packages 1.0.0 → 3.0.0

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()
+	}
+}

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

@@ -0,0 +1,69 @@
+import type {
+	NextFunction,
+	Request,
+	RequestHandler,
+	Response,
+} from 'node_modules/@types/express'
+
+// Session middleware helper (attaches sessionStore and helpers to req)
+export function useSession(cookieName?: string): RequestHandler {
+	return async (req: Request, _res: Response, next: NextFunction) => {
+		try {
+			const store = req.app.locals.sessionStore as
+				| { get?: Function; create?: Function }
+				| undefined
+			if (!store) return next()
+
+			const name =
+				cookieName || (req.app.locals.sessionCookieName as string) || 'sid'
+			let sid: string | undefined = (
+				req.cookies as Record<string, string> | undefined
+			)?.[name]
+
+			if (!sid) {
+				const cookieHeader = req.headers.cookie
+				if (cookieHeader) {
+					const match = cookieHeader
+						.split(';')
+						.map((s) => s.trim())
+						.find((s) => s.startsWith(`${name}=`))
+					if (match) sid = match.split('=')[1]
+				}
+			}
+
+			req.sessionId = sid
+			req.sessionStore = store
+
+			req.getSession = async () => {
+				if (!sid) return null
+				try {
+					return await (store.get as Function)(sid)
+				} catch (error) {
+					console.error(`[Session] Failed to get session "${sid}":`, error)
+					throw error
+				}
+			}
+
+			req.createSession = async (
+				id: string,
+				data: Record<string, unknown>,
+				ttl?: number,
+			) => {
+				try {
+					return await (store.create as Function)(id, data, ttl)
+				} catch (error) {
+					console.error(`[Session] Failed to create session "${id}":`, error)
+					throw error
+				}
+			}
+
+			next()
+		} catch (error) {
+			console.error(
+				'[Session] Unexpected error in useSession middleware:',
+				error,
+			)
+			next()
+		}
+	}
+}

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

@@ -0,0 +1,100 @@
+import { ValidationError } from '@naman_deep_singh/errors-utils'
+import type {
+	NextFunction,
+	Request,
+	RequestHandler,
+	Response,
+} from 'node_modules/@types/express'
+
+// 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[],
+): RequestHandler {
+	return (req: Request, _res: Response, next: 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) {
+			// Use ValidationError from errors-utils and let error middleware handle response
+			const validationError = new ValidationError({
+				fieldErrors: errors,
+			})
+			return next(validationError)
+		}
+
+		next()
+	}
+}

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

@@ -0,0 +1,114 @@
+import type 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 integration (disabled by default)
+	cache?: {
+		enabled?: boolean
+		// adapter specific options passed to CacheFactory.create
+		adapter?: 'redis' | 'memcache' | 'memory'
+		options?: unknown
+		defaultTTL?: number
+	}
+	// Session integration (disabled by default)
+	session?: {
+		enabled?: boolean
+		// cookie name pattern will be generated as {servername}.sid unless overridden
+		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/packages/server-utils/src/utils/utils.ts

@@ -0,0 +1,43 @@
+export function getEnv(key: string, defaultValue?: string): string {
+	const value = process.env[key]
+	if (value === undefined) {
+		if (defaultValue === undefined) {
+			throw new Error(`Environment variable ${key} is required`)
+		}
+		return defaultValue
+	}
+	return value // empty string allowed
+}
+
+export function getEnvNumber(key: string, defaultValue?: number): number {
+	const value = process.env[key]
+	if (value === undefined) {
+		if (defaultValue === undefined) {
+			throw new Error(`Environment variable ${key} is required`)
+		}
+		return defaultValue
+	}
+
+	const parsed = Number(value)
+	if (Number.isNaN(parsed)) {
+		throw new Error(`Environment variable ${key} must be a valid number`)
+	}
+	return parsed
+}
+
+export function getEnvBoolean(key: string, defaultValue?: boolean): boolean {
+	const value = process.env[key]
+	if (value === undefined) {
+		if (defaultValue === undefined) {
+			throw new Error(`Environment variable ${key} is required`)
+		}
+		return defaultValue
+	}
+
+	const normalized = value.toLowerCase()
+	if (normalized !== 'true' && normalized !== 'false') {
+		throw new Error(`Environment variable ${key} must be 'true' or 'false'`)
+	}
+
+	return normalized === 'true'
+}

package/packages/server-utils/tsconfig.base.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "moduleResolution": "node",
+    "strict": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "baseUrl": ".",
+    "paths": {
+      "*": ["*", "*.ts", "*.js"]
+    }
+  },
+  "include": ["src/**/*"]
+}

package/packages/server-utils/tsconfig.cjs.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "module": "CommonJS",
+    "moduleResolution": "Node",
+    "rootDir": "./src",
+    "outDir": "./dist/cjs"
+  }
+}

package/packages/server-utils/tsconfig.esm.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "rootDir": "./src",
+    "outDir": "./dist/esm"
+  }
+}

package/packages/server-utils/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/packages/server-utils/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);
-}