xypriss 2.1.1 → 2.2.0

package/dist/index.d.ts

@@ -1571,315 +1571,94 @@ interface RouteSecurityConfig {
 }
 
 /**
- * @fileoverview Core type definitions for XyPrissJS Express integration
+ * @fileoverview Performance-related type definitions for XyPrissJS Express integration
  *
- * This module contains fundamental types and utilities used throughout
- * the Express integration system.
+ * This module contains all performance-related types including monitoring,
+ * optimization, metrics, and configuration.
  *
  * @version 4.5.11
  * @author XyPrissJS Team
  * @since 2025-01-06
  */
-
-/**
- * Deep partial utility type that makes all properties optional recursively.
- *
- * This utility type is used throughout the configuration system to allow
- * partial configuration objects while maintaining type safety.
- *
- * @template T - The type to make deeply partial
- *
- * @example
- * ```typescript
- * interface Config {
- *   server: {
- *     port: number;
- *     host: string;
- *   };
- * }
- *
- * type PartialConfig = DeepPartial<Config>;
- * // Result: { server?: { port?: number; host?: string; } }
- * ```
- */
-type DeepPartial<T> = {
-    [K in keyof T]?: T[K] extends infer U ? U extends object ? U extends readonly any[] ? U extends readonly (infer V)[] ? readonly DeepPartial<V>[] : U : U extends Function ? U : DeepPartial<U> : U : never;
-};
 /**
- * Validation result interface for request validation operations.
- *
- * Used by validation middleware and request handlers to provide
- * structured validation feedback.
- *
- * @interface ValidationResult
- *
- * @example
- * ```typescript
- * const result: ValidationResult = {
- *   valid: false,
- *   errors: ['Email is required', 'Password too short'],
- *   data: { email: '', password: '123' }
- * };
- * ```
- */
-interface ValidationResult$1 {
-    /** Whether the validation passed */
-    valid: boolean;
-    /** Array of validation error messages */
-    errors: string[];
-    /** The validated/sanitized data */
-    data: any;
-}
-/**
- * User context information for authenticated requests.
- *
- * Contains user identity, permissions, and metadata for
- * authorization and audit purposes.
- *
- * @interface UserContext
- *
- * @example
- * ```typescript
- * const user: UserContext = {
- *   id: 'user-123',
- *   roles: ['admin', 'user'],
- *   permissions: ['read:users', 'write:posts'],
- *   metadata: { department: 'engineering', level: 'senior' }
- * };
- * ```
- */
-interface UserContext {
-    /** Unique user identifier */
-    id: string;
-    /** Array of user roles */
-    roles: string[];
-    /** Array of specific permissions */
-    permissions: string[];
-    /** Additional user metadata */
-    metadata: Record<string, any>;
-}
-/**
- * Session data structure for user sessions.
- *
- * Contains session information including expiration and
- * custom session data.
- *
- * @interface SessionData
- *
- * @example
- * ```typescript
- * const session: SessionData = {
- *   id: 'session-abc123',
- *   userId: 'user-123',
- *   data: { theme: 'dark', language: 'en' },
- *   expires: new Date(Date.now() + 3600000) // 1 hour
- * };
- * ```
- */
-interface SessionData {
-    /** Unique session identifier */
-    id: string;
-    /** Associated user ID (optional) */
-    userId?: string;
-    /** Custom session data */
-    data: Record<string, any>;
-    /** Session expiration date */
-    expires: Date;
-}
-/**
- * Pagination information for paginated responses.
- *
- * Used by API endpoints that return paginated data to provide
- * navigation information to clients.
- *
- * @interface PaginationInfo
- *
- * @example
- * ```typescript
- * const pagination: PaginationInfo = {
- *   page: 2,
- *   limit: 20,
- *   total: 150,
- *   pages: 8
- * };
- * ```
- */
-interface PaginationInfo {
-    /** Current page number (1-based) */
-    page: number;
-    /** Number of items per page */
-    limit: number;
-    /** Total number of items */
-    total: number;
-    /** Total number of pages */
-    pages: number;
-}
-/**
- * Enhanced Express request interface with additional utilities.
+ * Performance configuration interface.
  *
- * Extends the standard Express Request with caching, security,
- * performance, and validation utilities.
+ * Comprehensive configuration for performance monitoring,
+ * optimization, and metrics collection.
  *
- * @interface EnhancedRequest
- * @extends Request
+ * @interface PerformanceConfig
  *
  * @example
  * ```typescript
- * app.get('/api/users', async (req: EnhancedRequest, res: EnhancedResponse) => {
- *   // Use enhanced features
- *   const cached = await req.cache.get('users');
- *   const encrypted = await req.security.encrypt(sensitiveData);
- *   req.performance.start();
- *
- *   // Validation
- *   const validation = req.validation.query(userQuerySchema);
- *   if (!validation.valid) {
- *     return res.error('Invalid query parameters');
+ * const perfConfig: PerformanceConfig = {
+ *   enabled: true,
+ *   metrics: ['response_time', 'memory_usage', 'cpu_usage'],
+ *   interval: 30000, // 30 seconds
+ *   alerts: [
+ *     {
+ *       metric: 'response_time',
+ *       threshold: 1000, // 1 second
+ *       action: 'log',
+ *       cooldown: 300000 // 5 minutes
+ *     }
+ *   ],
+ *   dashboard: true,
+ *   export: {
+ *     custom: (metrics) => {
+ *       console.log('Custom metrics export:', metrics);
+ *     }
  *   }
- * });
- * ```
- */
-interface EnhancedRequest extends Request {
-    /** Cache utilities for request-level caching */
-    cache: {
-        /** Get cached value by key */
-        get: (key: string) => Promise<any>;
-        /** Set cached value with optional TTL */
-        set: (key: string, value: any, ttl?: number) => Promise<void>;
-        /** Delete cached value */
-        del: (key: string) => Promise<void>;
-        /** Tag cache entries for bulk invalidation */
-        tags: (tags: string[]) => Promise<void>;
-    };
-    /** Security utilities for encryption and authentication */
-    security: {
-        /** Encrypt data using configured algorithm */
-        encrypt: (data: any) => Promise<string>;
-        /** Decrypt data using configured algorithm */
-        decrypt: (data: string) => Promise<any>;
-        /** Hash data using secure algorithm */
-        hash: (data: string) => string;
-        /** Verify data against hash */
-        verify: (data: string, hash: string) => boolean;
-        /** Generate secure token */
-        generateToken: () => string;
-        /** Session encryption key */
-        sessionKey: string;
-    };
-    /** Performance monitoring utilities */
-    performance: {
-        /** Start performance timer */
-        start: () => void;
-        /** End performance timer and return duration */
-        end: () => number;
-        /** Mark a performance point */
-        mark: (name: string) => void;
-        /** Measure time between marks */
-        measure: (name: string, start: string, end: string) => number;
-    };
-    /** Request validation utilities */
-    validation: {
-        /** Validate request body against schema */
-        body: (schema: any) => ValidationResult$1;
-        /** Validate query parameters against schema */
-        query: (schema: any) => ValidationResult$1;
-        /** Validate route parameters against schema */
-        params: (schema: any) => ValidationResult$1;
-    };
-    /** User context (available after authentication) */
-    user?: UserContext;
-    /** Session data (available when sessions are enabled) */
-    session?: SessionData;
-}
-/**
- * Enhanced Express response interface with additional utilities.
- *
- * Extends the standard Express Response with caching, security,
- * performance, and convenience methods.
- *
- * @interface EnhancedResponse
- * @extends Response
- *
- * @example
- * ```typescript
- * app.get('/api/users', async (req: EnhancedRequest, res: EnhancedResponse) => {
- *   const users = await getUsersFromDB();
- *
- *   // Use enhanced response methods
- *   res.cache.set(3600, ['users']); // Cache for 1 hour with 'users' tag
- *   res.performance.timing('db_query', 150);
- *   res.success(users, 'Users retrieved successfully');
- * });
+ * };
  * ```
  */
-interface EnhancedResponse extends Response {
-    /** Cache utilities for response caching */
-    cache: {
-        /** Set cache headers and TTL for response */
-        set: (ttl?: number, tags?: string[]) => void;
-        /** Invalidate cache entries by tags */
-        invalidate: (tags: string[]) => Promise<void>;
-    };
-    /** Security utilities for response encryption */
-    security: {
-        /** Encrypt response data */
-        encrypt: (data: any) => EnhancedResponse;
-        /** Sign response data */
-        sign: (data: any) => EnhancedResponse;
-    };
-    /** Performance utilities for response metrics */
-    performance: {
-        /** Record timing metric */
-        timing: (name: string, value: number) => void;
-        /** Record custom metric */
-        metric: (name: string, value: number) => void;
+interface PerformanceConfig {
+    /** Enable performance monitoring */
+    enabled?: boolean;
+    /** Metrics to collect */
+    metrics?: string[];
+    /** Collection interval in milliseconds */
+    interval?: number;
+    /** Alert configurations */
+    alerts?: AlertConfig[];
+    /** Enable performance dashboard */
+    dashboard?: boolean;
+    /** Export configuration */
+    export?: {
+        /** Custom export function */
+        custom?: (metrics: any) => void;
     };
-    /** Send successful response with optional message */
-    success: (data?: any, message?: string) => void;
-    /** Send error response with message and status code */
-    error: (error: string | Error, code?: number) => void;
-    /** Send paginated response with pagination info */
-    paginated: (data: any[], pagination: PaginationInfo) => void;
 }
 /**
- * Route handler function type with enhanced request/response.
- *
- * @template T - Return type of the handler
- *
- * @example
- * ```typescript
- * const getUserHandler: RouteHandler = async (req, res, next) => {
- *   try {
- *     const user = await getUserById(req.params.id);
- *     res.success(user);
- *   } catch (error) {
- *     next(error);
- *   }
- * };
- * ```
- */
-type RouteHandler = (req: EnhancedRequest, res: EnhancedResponse, next: NextFunction$1) => Promise<any> | any;
-/**
- * Middleware function type with enhanced request/response.
- *
- * @example
- * ```typescript
- * const authMiddleware: MiddlewareFunction = async (req, res, next) => {
- *   const token = req.headers.authorization;
- *   if (!token) {
- *     return res.error('Authorization required', 401);
- *   }
+ * Alert configuration interface.
  *
- *   try {
- *     req.user = await verifyToken(token);
- *     next();
- *   } catch (error) {
- *     res.error('Invalid token', 401);
- *   }
+ * Configuration for performance alerts including thresholds,
+ * actions, and cooldown periods.
+ *
+ * @interface AlertConfig
+ *
+ * @example
+ * ```typescript
+ * const alertConfig: AlertConfig = {
+ *   metric: 'memory_usage',
+ *   threshold: 0.85, // 85%
+ *   action: 'webhook',
+ *   target: 'https://alerts.example.com/webhook',
+ *   cooldown: 600000 // 10 minutes
  * };
  * ```
  */
-type MiddlewareFunction = (req: EnhancedRequest, res: EnhancedResponse, next: NextFunction$1) => Promise<void> | void;
+interface AlertConfig {
+    /** Metric name to monitor */
+    metric: string;
+    /** Threshold value that triggers alert */
+    threshold: number;
+    /** Action to take when alert triggers */
+    action: "log" | "email" | "webhook" | "custom";
+    /** Target for the action (email, webhook URL, etc.) */
+    target?: string;
+    /** Cooldown period in milliseconds */
+    cooldown?: number;
+}
 
 /**
  * @fileoverview Cache-related type definitions for XyPrissJS Express integration
@@ -2253,94 +2032,315 @@ interface CacheStrategy {
 }
 
 /**
- * @fileoverview Performance-related type definitions for XyPrissJS Express integration
+ * @fileoverview Core type definitions for XyPrissJS Express integration
  *
- * This module contains all performance-related types including monitoring,
- * optimization, metrics, and configuration.
+ * This module contains fundamental types and utilities used throughout
+ * the Express integration system.
  *
  * @version 4.5.11
  * @author XyPrissJS Team
  * @since 2025-01-06
  */
+
+/**
+ * Deep partial utility type that makes all properties optional recursively.
+ *
+ * This utility type is used throughout the configuration system to allow
+ * partial configuration objects while maintaining type safety.
+ *
+ * @template T - The type to make deeply partial
+ *
+ * @example
+ * ```typescript
+ * interface Config {
+ *   server: {
+ *     port: number;
+ *     host: string;
+ *   };
+ * }
+ *
+ * type PartialConfig = DeepPartial<Config>;
+ * // Result: { server?: { port?: number; host?: string; } }
+ * ```
+ */
+type DeepPartial<T> = {
+    [K in keyof T]?: T[K] extends infer U ? U extends object ? U extends readonly any[] ? U extends readonly (infer V)[] ? readonly DeepPartial<V>[] : U : U extends Function ? U : DeepPartial<U> : U : never;
+};
+/**
+ * Validation result interface for request validation operations.
+ *
+ * Used by validation middleware and request handlers to provide
+ * structured validation feedback.
+ *
+ * @interface ValidationResult
+ *
+ * @example
+ * ```typescript
+ * const result: ValidationResult = {
+ *   valid: false,
+ *   errors: ['Email is required', 'Password too short'],
+ *   data: { email: '', password: '123' }
+ * };
+ * ```
+ */
+interface ValidationResult$1 {
+    /** Whether the validation passed */
+    valid: boolean;
+    /** Array of validation error messages */
+    errors: string[];
+    /** The validated/sanitized data */
+    data: any;
+}
+/**
+ * User context information for authenticated requests.
+ *
+ * Contains user identity, permissions, and metadata for
+ * authorization and audit purposes.
+ *
+ * @interface UserContext
+ *
+ * @example
+ * ```typescript
+ * const user: UserContext = {
+ *   id: 'user-123',
+ *   roles: ['admin', 'user'],
+ *   permissions: ['read:users', 'write:posts'],
+ *   metadata: { department: 'engineering', level: 'senior' }
+ * };
+ * ```
+ */
+interface UserContext {
+    /** Unique user identifier */
+    id: string;
+    /** Array of user roles */
+    roles: string[];
+    /** Array of specific permissions */
+    permissions: string[];
+    /** Additional user metadata */
+    metadata: Record<string, any>;
+}
+/**
+ * Session data structure for user sessions.
+ *
+ * Contains session information including expiration and
+ * custom session data.
+ *
+ * @interface SessionData
+ *
+ * @example
+ * ```typescript
+ * const session: SessionData = {
+ *   id: 'session-abc123',
+ *   userId: 'user-123',
+ *   data: { theme: 'dark', language: 'en' },
+ *   expires: new Date(Date.now() + 3600000) // 1 hour
+ * };
+ * ```
+ */
+interface SessionData {
+    /** Unique session identifier */
+    id: string;
+    /** Associated user ID (optional) */
+    userId?: string;
+    /** Custom session data */
+    data: Record<string, any>;
+    /** Session expiration date */
+    expires: Date;
+}
+/**
+ * Pagination information for paginated responses.
+ *
+ * Used by API endpoints that return paginated data to provide
+ * navigation information to clients.
+ *
+ * @interface PaginationInfo
+ *
+ * @example
+ * ```typescript
+ * const pagination: PaginationInfo = {
+ *   page: 2,
+ *   limit: 20,
+ *   total: 150,
+ *   pages: 8
+ * };
+ * ```
+ */
+interface PaginationInfo {
+    /** Current page number (1-based) */
+    page: number;
+    /** Number of items per page */
+    limit: number;
+    /** Total number of items */
+    total: number;
+    /** Total number of pages */
+    pages: number;
+}
+/**
+ * Enhanced Express request interface with additional utilities.
+ *
+ * Extends the standard Express Request with caching, security,
+ * performance, and validation utilities.
+ *
+ * @interface EnhancedRequest
+ * @extends Request
+ *
+ * @example
+ * ```typescript
+ * app.get('/api/users', async (req: EnhancedRequest, res: EnhancedResponse) => {
+ *   // Use enhanced features
+ *   const cached = await req.cache.get('users');
+ *   const encrypted = await req.security.encrypt(sensitiveData);
+ *   req.performance.start();
+ *
+ *   // Validation
+ *   const validation = req.validation.query(userQuerySchema);
+ *   if (!validation.valid) {
+ *     return res.error('Invalid query parameters');
+ *   }
+ * });
+ * ```
+ */
+interface EnhancedRequest extends Request {
+    /** Cache utilities for request-level caching */
+    cache: {
+        /** Get cached value by key */
+        get: (key: string) => Promise<any>;
+        /** Set cached value with optional TTL */
+        set: (key: string, value: any, ttl?: number) => Promise<void>;
+        /** Delete cached value */
+        del: (key: string) => Promise<void>;
+        /** Tag cache entries for bulk invalidation */
+        tags: (tags: string[]) => Promise<void>;
+    };
+    /** Security utilities for encryption and authentication */
+    security: {
+        /** Encrypt data using configured algorithm */
+        encrypt: (data: any) => Promise<string>;
+        /** Decrypt data using configured algorithm */
+        decrypt: (data: string) => Promise<any>;
+        /** Hash data using secure algorithm */
+        hash: (data: string) => string;
+        /** Verify data against hash */
+        verify: (data: string, hash: string) => boolean;
+        /** Generate secure token */
+        generateToken: () => string;
+        /** Session encryption key */
+        sessionKey: string;
+    };
+    /** Performance monitoring utilities */
+    performance: {
+        /** Start performance timer */
+        start: () => void;
+        /** End performance timer and return duration */
+        end: () => number;
+        /** Mark a performance point */
+        mark: (name: string) => void;
+        /** Measure time between marks */
+        measure: (name: string, start: string, end: string) => number;
+    };
+    /** Request validation utilities */
+    validation: {
+        /** Validate request body against schema */
+        body: (schema: any) => ValidationResult$1;
+        /** Validate query parameters against schema */
+        query: (schema: any) => ValidationResult$1;
+        /** Validate route parameters against schema */
+        params: (schema: any) => ValidationResult$1;
+    };
+    /** User context (available after authentication) */
+    user?: UserContext;
+    /** Session data (available when sessions are enabled) */
+    session?: SessionData;
+}
+/**
+ * Enhanced Express response interface with additional utilities.
+ *
+ * Extends the standard Express Response with caching, security,
+ * performance, and convenience methods.
+ *
+ * @interface EnhancedResponse
+ * @extends Response
+ *
+ * @example
+ * ```typescript
+ * app.get('/api/users', async (req: EnhancedRequest, res: EnhancedResponse) => {
+ *   const users = await getUsersFromDB();
+ *
+ *   // Use enhanced response methods
+ *   res.cache.set(3600, ['users']); // Cache for 1 hour with 'users' tag
+ *   res.performance.timing('db_query', 150);
+ *   res.success(users, 'Users retrieved successfully');
+ * });
+ * ```
+ */
+interface EnhancedResponse extends Response {
+    /** Cache utilities for response caching */
+    cache: {
+        /** Set cache headers and TTL for response */
+        set: (ttl?: number, tags?: string[]) => void;
+        /** Invalidate cache entries by tags */
+        invalidate: (tags: string[]) => Promise<void>;
+    };
+    /** Security utilities for response encryption */
+    security: {
+        /** Encrypt response data */
+        encrypt: (data: any) => EnhancedResponse;
+        /** Sign response data */
+        sign: (data: any) => EnhancedResponse;
+    };
+    /** Performance utilities for response metrics */
+    performance: {
+        /** Record timing metric */
+        timing: (name: string, value: number) => void;
+        /** Record custom metric */
+        metric: (name: string, value: number) => void;
+    };
+    /** Send successful response with optional message */
+    success: (data?: any, message?: string) => void;
+    /** Send error response with message and status code */
+    error: (error: string | Error, code?: number) => void;
+    /** Send paginated response with pagination info */
+    paginated: (data: any[], pagination: PaginationInfo) => void;
+}
 /**
- * Performance configuration interface.
- *
- * Comprehensive configuration for performance monitoring,
- * optimization, and metrics collection.
+ * Route handler function type with enhanced request/response.
  *
- * @interface PerformanceConfig
+ * @template T - Return type of the handler
  *
  * @example
  * ```typescript
- * const perfConfig: PerformanceConfig = {
- *   enabled: true,
- *   metrics: ['response_time', 'memory_usage', 'cpu_usage'],
- *   interval: 30000, // 30 seconds
- *   alerts: [
- *     {
- *       metric: 'response_time',
- *       threshold: 1000, // 1 second
- *       action: 'log',
- *       cooldown: 300000 // 5 minutes
- *     }
- *   ],
- *   dashboard: true,
- *   export: {
- *     custom: (metrics) => {
- *       console.log('Custom metrics export:', metrics);
- *     }
+ * const getUserHandler: RouteHandler = async (req, res, next) => {
+ *   try {
+ *     const user = await getUserById(req.params.id);
+ *     res.success(user);
+ *   } catch (error) {
+ *     next(error);
  *   }
  * };
  * ```
  */
-interface PerformanceConfig {
-    /** Enable performance monitoring */
-    enabled?: boolean;
-    /** Metrics to collect */
-    metrics?: string[];
-    /** Collection interval in milliseconds */
-    interval?: number;
-    /** Alert configurations */
-    alerts?: AlertConfig[];
-    /** Enable performance dashboard */
-    dashboard?: boolean;
-    /** Export configuration */
-    export?: {
-        /** Custom export function */
-        custom?: (metrics: any) => void;
-    };
-}
+type RouteHandler = (req: EnhancedRequest, res: EnhancedResponse, next: NextFunction$1) => Promise<any> | any;
 /**
- * Alert configuration interface.
- *
- * Configuration for performance alerts including thresholds,
- * actions, and cooldown periods.
- *
- * @interface AlertConfig
+ * Middleware function type with enhanced request/response.
  *
  * @example
  * ```typescript
- * const alertConfig: AlertConfig = {
- *   metric: 'memory_usage',
- *   threshold: 0.85, // 85%
- *   action: 'webhook',
- *   target: 'https://alerts.example.com/webhook',
- *   cooldown: 600000 // 10 minutes
+ * const authMiddleware: MiddlewareFunction = async (req, res, next) => {
+ *   const token = req.headers.authorization;
+ *   if (!token) {
+ *     return res.error('Authorization required', 401);
+ *   }
+ *
+ *   try {
+ *     req.user = await verifyToken(token);
+ *     next();
+ *   } catch (error) {
+ *     res.error('Invalid token', 401);
+ *   }
  * };
  * ```
  */
-interface AlertConfig {
-    /** Metric name to monitor */
-    metric: string;
-    /** Threshold value that triggers alert */
-    threshold: number;
-    /** Action to take when alert triggers */
-    action: "log" | "email" | "webhook" | "custom";
-    /** Target for the action (email, webhook URL, etc.) */
-    target?: string;
-    /** Cooldown period in milliseconds */
-    cooldown?: number;
-}
+type MiddlewareFunction = (req: EnhancedRequest, res: EnhancedResponse, next: NextFunction$1) => Promise<void> | void;
 
 /**
  * @fileoverview Routing-related type definitions for XyPrissJS Express integration
@@ -2599,6 +2599,11 @@ interface RouteOptions {
  * Comprehensive types for the fluent middleware management API
  */
 type MiddlewarePriority = "critical" | "high" | "normal" | "low";
+interface MiddlewareConfiguration {
+    enabled?: boolean;
+    priority?: MiddlewarePriority;
+    order?: number;
+}
 interface SecurityMiddlewareConfig {
     helmet?: boolean | {
         contentSecurityPolicy?: boolean | object;
@@ -2722,17 +2727,217 @@ interface XyPrissMiddlewareAPI {
     /**
      * Clear all middleware
      */
-    clear(): XyPrissMiddlewareAPI;
+    clear(): XyPrissMiddlewareAPI;
+    /**
+     * Optimize middleware order by priority
+     */
+    optimize(): XyPrissMiddlewareAPI;
+    unregister(id: string): XyPrissMiddlewareAPI;
+    enable(id: string): XyPrissMiddlewareAPI;
+    disable(id: string): XyPrissMiddlewareAPI;
+    getInfo(id?: string): any;
+    getStats(): any;
+    getConfig(): any;
+}
+
+/**
+ * Centralized Logger for FastApi.ts Server
+ * Provides granular control over logging output with enhanced robustness
+ */
+
+declare class Logger {
+    private config;
+    private static instance;
+    private buffer;
+    private flushTimer?;
+    private isDisposed;
+    private logQueue;
+    private isProcessingQueue;
+    private errorCount;
+    private lastErrorTime;
+    private suppressedComponents;
+    constructor(config?: ServerOptions["logging"]);
+    /**
+     * Initialize log buffer system
+     */
+    private initializeBuffer;
+    /**
+     * Setup error handling and recovery mechanisms
+     */
+    private setupErrorHandling;
+    /**
+     * Emergency logging that bypasses normal filtering
+     */
+    private emergencyLog;
+    /**
+     * Start auto-flush timer for buffered logging
+     */
+    private startAutoFlush;
+    /**
+     * Flush buffered log entries
+     */
+    flush(): void;
+    /**
+     * Get or create singleton instance
+     */
+    static getInstance(config?: ServerOptions["logging"]): Logger;
+    /**
+     * Deep merge two objects
+     */
+    private deepMerge;
+    /**
+     * Update logger configuration
+     */
+    updateConfig(config: ServerOptions["logging"]): void;
+    /**
+     * Get current logger configuration (for debugging)
+     */
+    getConfig(): ServerOptions["logging"];
+    /**
+     * Check if we should suppress this log due to error rate limiting
+     */
+    private shouldSuppressError;
+    /**
+     * Check if logging is enabled for a specific component and type
+     */
+    private shouldLog;
+    /**
+     * Get memory usage information
+     */
+    private getMemoryInfo;
+    /**
+     * Get process ID
+     */
+    private getProcessId;
+    /**
+     * Truncate message if it exceeds max line length
+     */
+    private truncateMessage;
+    /**
+     * Format log message
+     */
+    private formatMessage;
+    /**
+     * Write log entry to output
+     */
+    private writeLog;
+    /**
+     * Process log queue
+     */
+    private processLogQueue;
+    /**
+     * Log a message
+     */
+    private log;
+    error(component: LogComponent, message: string, ...args: any[]): void;
+    warn(component: LogComponent, message: string, ...args: any[]): void;
+    info(component: LogComponent, message: string, ...args: any[]): void;
+    debug(component: LogComponent, message: string, ...args: any[]): void;
+    verbose(component: LogComponent, message: string, ...args: any[]): void;
+    startup(component: LogComponent, message: string, ...args: any[]): void;
+    performance(component: LogComponent, message: string, ...args: any[]): void;
+    hotReload(component: LogComponent, message: string, ...args: any[]): void;
+    portSwitching(component: LogComponent, message: string, ...args: any[]): void;
+    securityWarning(message: string, ...args: any[]): void;
+    isEnabled(): boolean;
+    getLevel(): LogLevel;
+    isComponentEnabled(component: LogComponent): boolean;
+    isTypeEnabled(type: LogType): boolean;
+    /**
+     * Get logging statistics
+     */
+    getStats(): {
+        errorCount: number;
+        lastErrorTime: number;
+        suppressedComponents: string[];
+        bufferSize: number;
+        queueSize: number;
+    };
+    /**
+     * Clear suppressed components
+     */
+    clearSuppression(): void;
+    /**
+     * Dispose logger and cleanup resources
+     */
+    dispose(): void;
     /**
-     * Optimize middleware order by priority
+     * Create a child logger with component-specific configuration
      */
-    optimize(): XyPrissMiddlewareAPI;
-    unregister(id: string): XyPrissMiddlewareAPI;
-    enable(id: string): XyPrissMiddlewareAPI;
-    disable(id: string): XyPrissMiddlewareAPI;
-    getInfo(id?: string): any;
-    getStats(): any;
-    getConfig(): any;
+    child(component: LogComponent, config?: Partial<ServerOptions["logging"]>): Logger;
+}
+
+/**
+ * File Upload Manager for XyPriss Server
+ * Handles multer configuration and file upload middleware setup
+ */
+
+interface FileUploadConfig {
+    /** Enable file upload handling */
+    enabled?: boolean;
+    /** Maximum file size in bytes */
+    maxFileSize?: number;
+    /** Maximum number of files per request */
+    maxFiles?: number;
+    /** Allowed MIME types */
+    allowedMimeTypes?: string[];
+    /** Allowed file extensions */
+    allowedExtensions?: string[];
+    /** Upload destination directory */
+    destination?: string;
+    /** Custom filename function */
+    filename?: (req: any, file: any, callback: (error: Error | null, filename: string) => void) => void;
+    /** Detailed limits configuration */
+    limits?: {
+        /** Max field name size in bytes */
+        fieldNameSize?: number;
+        /** Max field value size in bytes */
+        fieldSize?: number;
+        /** Max number of non-file fields */
+        fields?: number;
+        /** Max file size in bytes */
+        fileSize?: number;
+        /** Max number of file fields */
+        files?: number;
+        /** Max number of header key=>value pairs */
+        headerPairs?: number;
+    };
+    /** Preserve full paths instead of just filenames */
+    preservePath?: boolean;
+    /** Custom file filter function */
+    fileFilter?: (req: any, file: any, callback: (error: Error | null, acceptFile: boolean) => void) => void;
+    /** Storage type */
+    storage?: 'disk' | 'memory' | 'custom';
+    /** Create parent directories if they don't exist */
+    createParentPath?: boolean;
+    /** Abort request on limit reached */
+    abortOnLimit?: boolean;
+    /** Response message when limit is reached */
+    responseOnLimit?: string;
+    /** Use temporary files for large uploads */
+    useTempFiles?: boolean;
+    /** Temporary file directory */
+    tempFileDir?: string;
+    /** Parse nested objects in multipart data */
+    parseNested?: boolean;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Custom multer options */
+    multerOptions?: {
+        dest?: string;
+        storage?: any;
+        limits?: {
+            fieldNameSize?: number;
+            fieldSize?: number;
+            fields?: number;
+            fileSize?: number;
+            files?: number;
+            headerPairs?: number;
+        };
+        preservePath?: boolean;
+        fileFilter?: (req: any, file: any, callback: (error: Error | null, acceptFile: boolean) => void) => void;
+        [key: string]: any;
+    };
 }
 
 /**
@@ -2757,6 +2962,47 @@ interface XyPrissMiddlewareAPI {
 
 type RequestHandler = (req: XyPrisRequest, res: XyPrisResponse, next?: NextFunction) => void | Promise<void>;
 
+/**
+ * Configuration for individual servers in multi-server mode
+ *
+ * @interface MultiServerConfig
+ * @version 4.5.11
+ * @author XyPrissJS Team
+ * @since 2025-01-06
+ */
+interface MultiServerConfig {
+    /** Unique identifier for this server instance */
+    id: string;
+    /** Port number for this server */
+    port: number;
+    /** Host for this server (optional, defaults to main config) */
+    host?: string;
+    /** Route prefix that this server should handle */
+    routePrefix?: string;
+    /** Array of allowed route patterns for this server */
+    allowedRoutes?: string[];
+    /** Server-specific overrides */
+    server?: {
+        host?: string;
+        trustProxy?: boolean;
+        jsonLimit?: string;
+        urlEncodedLimit?: string;
+        enableMiddleware?: boolean;
+        autoParseJson?: boolean;
+    };
+    /** Security overrides for this server */
+    security?: SecurityConfig;
+    /** Performance overrides for this server */
+    performance?: PerformanceConfig;
+    /** Cache overrides for this server */
+    cache?: CacheConfig;
+    /** File upload overrides for this server */
+    fileUpload?: FileUploadConfig;
+    /** Middleware configuration specific to this server */
+    middleware?: MiddlewareConfiguration;
+    /** Logging configuration specific to this server */
+    logging?: ComponentLogConfig;
+}
 /**
  * @fileoverview Comprehensive server options interface for XyPrissJS Express integration
  *
@@ -2996,6 +3242,45 @@ interface ServerOptions {
             onPortSwitch?: (originalPort: number, newPort: number) => void;
         };
     };
+    /**
+     * Multi-server configuration for creating multiple server instances
+     *
+     * Allows running multiple server instances with different configurations,
+     * ports, and route scopes from a single configuration.
+     *
+     * @example
+     * ```typescript
+     * multiServer: {
+     *   enabled: true,
+     *   servers: [
+     *     {
+     *       id: "api-server",
+     *       port: 3001,
+     *       routePrefix: "/api/v1",
+     *       allowedRoutes: ["/api/v1/*"],
+     *       server: {
+     *         host: "localhost"
+     *       }
+     *     },
+     *     {
+     *       id: "admin-server",
+     *       port: 3002,
+     *       routePrefix: "/admin",
+     *       allowedRoutes: ["/admin/*"],
+     *       security: {
+     *         level: "maximum"
+     *       }
+     *     }
+     *   ]
+     * }
+     * ```
+     */
+    multiServer?: {
+        /** Enable multi-server mode */
+        enabled?: boolean;
+        /** Array of server configurations */
+        servers?: MultiServerConfig[];
+    };
     /**
      * Request management configuration for handling timeouts, network quality, and request lifecycle
      *
@@ -3116,6 +3401,49 @@ interface ServerOptions {
             customValidator?: (req: any) => boolean | Promise<boolean>;
         };
     };
+    /**
+     * File upload configuration for handling multipart/form-data requests.
+     *
+     * Comprehensive file upload settings including size limits, allowed types,
+     * storage options, and security features for file handling.
+     *
+     * @example
+     * ```typescript
+     * fileUpload: {
+     *   enabled: true,
+     *   maxFileSize: 10 * 1024 * 1024, // 10MB
+     *   maxFiles: 5,
+     *   allowedMimeTypes: ['image/jpeg', 'image/png', 'application/pdf'],
+     *   allowedExtensions: ['.jpg', '.jpeg', '.png', '.pdf'],
+     *   destination: './uploads',
+     *   filename: (req, file, callback) => {
+     *     callback(null, `${Date.now()}-${file.originalname}`);
+     *   },
+     *   limits: {
+     *     fieldNameSize: 100,
+     *     fieldSize: 1024,
+     *     fields: 10,
+     *     fileSize: 10 * 1024 * 1024,
+     *     files: 5,
+     *     headerPairs: 2000
+     *   },
+     *   preservePath: false,
+     *   fileFilter: (req, file, callback) => {
+     *     // Custom file validation logic
+     *     callback(null, true);
+     *   },
+     *   storage: 'disk', // 'disk' | 'memory' | 'custom'
+     *   createParentPath: true,
+     *   abortOnLimit: false,
+     *   responseOnLimit: 'File too large',
+     *   useTempFiles: false,
+     *   tempFileDir: '/tmp',
+     *   parseNested: true,
+     *   debug: false
+     * }
+     * ```
+     */
+    fileUpload?: FileUploadConfig;
     /**
      * Security configuration for the server.
      *
@@ -4019,6 +4347,73 @@ interface UltraFastApp {
      * ```
      */
     middleware: () => XyPrissMiddlewareAPI;
+    /**
+     * Multer instance for file uploads (available when fileUpload.enabled is true)
+     */
+    upload?: any;
+    /**
+     * Create single file upload middleware
+     *
+     * @param fieldname - Name of the form field
+     * @returns Multer middleware for single file upload
+     *
+     * @example
+     * ```typescript
+     * app.post('/upload', app.uploadSingle('file'), (req, res) => {
+     *   console.log(req.file);
+     *   res.send('File uploaded');
+     * });
+     * ```
+     */
+    uploadSingle: (fieldname: string) => any;
+    /**
+     * Create array file upload middleware
+     *
+     * @param fieldname - Name of the form field
+     * @param maxCount - Maximum number of files (optional)
+     * @returns Multer middleware for array file upload
+     *
+     * @example
+     * ```typescript
+     * app.post('/upload', app.uploadArray('files', 5), (req, res) => {
+     *   console.log(req.files);
+     *   res.send('Files uploaded');
+     * });
+     * ```
+     */
+    uploadArray?: (fieldname: string, maxCount?: number) => any;
+    /**
+     * Create fields file upload middleware
+     *
+     * @param fields - Array of field configurations
+     * @returns Multer middleware for multiple fields upload
+     *
+     * @example
+     * ```typescript
+     * app.post('/upload', app.uploadFields([
+     *   { name: 'avatar', maxCount: 1 },
+     *   { name: 'gallery', maxCount: 8 }
+     * ]), (req, res) => {
+     *   console.log(req.files);
+     *   res.send('Files uploaded');
+     * });
+     * ```
+     */
+    uploadFields?: (fields: any[]) => any;
+    /**
+     * Create any file upload middleware
+     *
+     * @returns Multer middleware that accepts any files
+     *
+     * @example
+     * ```typescript
+     * app.post('/upload', app.uploadAny(), (req, res) => {
+     *   console.log(req.files);
+     *   res.send('Files uploaded');
+     * });
+     * ```
+     */
+    uploadAny?: () => any;
     /**
      * Scale up the cluster by adding workers.
      *
@@ -4502,133 +4897,6 @@ declare class ClusterManager extends EventEmitter implements RobustClusterManage
     private closePersistenceManager;
 }
 
-/**
- * Centralized Logger for FastApi.ts Server
- * Provides granular control over logging output with enhanced robustness
- */
-
-declare class Logger {
-    private config;
-    private static instance;
-    private buffer;
-    private flushTimer?;
-    private isDisposed;
-    private logQueue;
-    private isProcessingQueue;
-    private errorCount;
-    private lastErrorTime;
-    private suppressedComponents;
-    constructor(config?: ServerOptions["logging"]);
-    /**
-     * Initialize log buffer system
-     */
-    private initializeBuffer;
-    /**
-     * Setup error handling and recovery mechanisms
-     */
-    private setupErrorHandling;
-    /**
-     * Emergency logging that bypasses normal filtering
-     */
-    private emergencyLog;
-    /**
-     * Start auto-flush timer for buffered logging
-     */
-    private startAutoFlush;
-    /**
-     * Flush buffered log entries
-     */
-    flush(): void;
-    /**
-     * Get or create singleton instance
-     */
-    static getInstance(config?: ServerOptions["logging"]): Logger;
-    /**
-     * Deep merge two objects
-     */
-    private deepMerge;
-    /**
-     * Update logger configuration
-     */
-    updateConfig(config: ServerOptions["logging"]): void;
-    /**
-     * Get current logger configuration (for debugging)
-     */
-    getConfig(): ServerOptions["logging"];
-    /**
-     * Check if we should suppress this log due to error rate limiting
-     */
-    private shouldSuppressError;
-    /**
-     * Check if logging is enabled for a specific component and type
-     */
-    private shouldLog;
-    /**
-     * Get memory usage information
-     */
-    private getMemoryInfo;
-    /**
-     * Get process ID
-     */
-    private getProcessId;
-    /**
-     * Truncate message if it exceeds max line length
-     */
-    private truncateMessage;
-    /**
-     * Format log message
-     */
-    private formatMessage;
-    /**
-     * Write log entry to output
-     */
-    private writeLog;
-    /**
-     * Process log queue
-     */
-    private processLogQueue;
-    /**
-     * Log a message
-     */
-    private log;
-    error(component: LogComponent, message: string, ...args: any[]): void;
-    warn(component: LogComponent, message: string, ...args: any[]): void;
-    info(component: LogComponent, message: string, ...args: any[]): void;
-    debug(component: LogComponent, message: string, ...args: any[]): void;
-    verbose(component: LogComponent, message: string, ...args: any[]): void;
-    startup(component: LogComponent, message: string, ...args: any[]): void;
-    performance(component: LogComponent, message: string, ...args: any[]): void;
-    hotReload(component: LogComponent, message: string, ...args: any[]): void;
-    portSwitching(component: LogComponent, message: string, ...args: any[]): void;
-    securityWarning(message: string, ...args: any[]): void;
-    isEnabled(): boolean;
-    getLevel(): LogLevel;
-    isComponentEnabled(component: LogComponent): boolean;
-    isTypeEnabled(type: LogType): boolean;
-    /**
-     * Get logging statistics
-     */
-    getStats(): {
-        errorCount: number;
-        lastErrorTime: number;
-        suppressedComponents: string[];
-        bufferSize: number;
-        queueSize: number;
-    };
-    /**
-     * Clear suppressed components
-     */
-    clearSuppression(): void;
-    /**
-     * Dispose logger and cleanup resources
-     */
-    dispose(): void;
-    /**
-     * Create a child logger with component-specific configuration
-     */
-    child(component: LogComponent, config?: Partial<ServerOptions["logging"]>): Logger;
-}
-
 /**
  * Ultra-Fast Plugin System Types
  *
@@ -5484,11 +5752,16 @@ declare class XyPrissServer {
     private fileWatcherManager;
     private consoleInterceptor;
     private workerPoolComponent;
+    private fileUploadManager;
     private notFoundHandler;
     private serverPluginManager;
     private securityMiddleware?;
     private lifecycleManager;
     constructor(userOptions?: ServerOptions);
+    /**
+     * Initialize file upload methods synchronously for immediate availability
+     */
+    private initializeFileUploadMethodsSync;
     /**
      * Initialize the ServerLifecycleManager
      */
@@ -5629,6 +5902,19 @@ declare class XyPrissServer {
     stop(): Promise<void>;
 }
 
+/**
+ * Multi-Server Manager for XyPriss
+ * Handles creation and management of multiple server instances
+ */
+
+interface MultiServerInstance {
+    id: string;
+    server: XyPrissServer;
+    config: MultiServerConfig;
+    port: number;
+    host: string;
+}
+
 /**
  * Safe JSON Middleware for Express
  * Automatically handles circular references in JSON responses
@@ -5728,8 +6014,9 @@ declare const expressStringify: (obj: any) => string;
 /**
  * Create ultra-fast Express server (zero-async)
  * Returns app instance ready to use immediately
+ * If multi-server mode is enabled, returns a MultiServerApp interface
  */
-declare function createServer(options?: ServerOptions): UltraFastApp;
+declare function createServer(options?: ServerOptions): UltraFastApp | MultiServerApp;
 /**
  * Create ultra-fast Express server class instance
  */
@@ -5739,6 +6026,41 @@ declare function createServerInstance(options?: ServerOptions): XyPrissServer;
  */
 declare function createCacheMiddleware(cache: SecureCacheAdapter, options?: RouteOptions): RequestHandler;
 
+/**
+ * Multi-Server App interface for managing multiple server instances
+ * Extends UltraFastApp to maintain API compatibility
+ */
+interface MultiServerApp extends Omit<UltraFastApp, 'start'> {
+    /**
+     * Start all server instances (simple API - hides complexity)
+     */
+    start(): Promise<void>;
+    /**
+     * Start all servers (alias for start - more explicit)
+     */
+    startAllServers(): Promise<void>;
+    /**
+     * Stop all server instances
+     */
+    stop(): Promise<void>;
+    /**
+     * Stop all servers (alias for stop - more explicit)
+     */
+    stopAllServers(): Promise<void>;
+    /**
+     * Get all server instances
+     */
+    getServers(): MultiServerInstance[];
+    /**
+     * Get a specific server instance by ID
+     */
+    getServer(id: string): MultiServerInstance | undefined;
+    /**
+     * Get multi-server statistics
+     */
+    getStats(): any;
+}
+
 /**
  * XyPrissJS Smart Routes
  * Intelligent route handlers with automatic optimization, caching, and security
@@ -10430,7 +10752,7 @@ declare class PluginDevelopmentHelpers {
 /**
  * Quick development server with sensible defaults
  */
-declare function quickServer(port?: number): UltraFastApp;
+declare function quickServer(port?: number): UltraFastApp | MultiServerApp;
 
 /***************************************************************************
  * XyPrissJS - Advanced JavaScript Security Library
@@ -10465,4 +10787,4 @@ declare function quickServer(port?: number): UltraFastApp;
 declare function Router(): XyPrissRouter;
 
 export { CachePlugin as CachePluginBase, CompressionPlugin, ConnectionPlugin, DEFAULT_PLUGIN_CONFIG, JWTAuthPlugin, NetworkCategory, NetworkPlugin, NetworkPluginFactory, NetworkPluginUtils, PERFORMANCE_TARGETS, PLUGIN_SYSTEM_NAME, PLUGIN_SYSTEM_VERSION, PerformanceMonitor, PerformancePlugin as PerformancePluginBase, PluginDevelopmentHelpers, PluginEngine, PluginEventType, PluginPriority, PluginRegistry, PluginSystemFactory, PluginSystemUtils, PluginType, ProxyPlugin, RateLimitPlugin, ResponseTimePlugin, Route, Router, SecurityMiddleware, SecurityPlugin as SecurityPluginBase, SmartCachePlugin, XyPrissRouter, createCacheMiddleware, createCircularRefDebugger, createOptimalCache, createSafeJsonMiddleware, createServer, createServerInstance, expressStringify, fastStringify, quickServer, safeJsonStringify, safeStringify, sendSafeJson, setupSafeJson };
-export type { BasePlugin, CacheConfig, CachePlugin$1 as CachePlugin, CompressionAlgorithm, CompressionConfig, ConnectionConfig, FailoverConfig, HTTPCacheConfig, HealthCheckConfig, CachePlugin$1 as ICachePlugin, PerformancePlugin$1 as IPerformancePlugin, SecurityPlugin$1 as ISecurityPlugin, LoadBalancingStrategy, NativePlugin, NetworkExecutionContext, NetworkExecutionResult, NetworkHealthStatus, NetworkPluginConfig, NetworkSecurityConfig, NextFunction, PerformanceConfig, PerformanceMetrics, PerformancePlugin$1 as PerformancePlugin, PluginConfiguration, PluginEvent, PluginExecutionContext, PluginExecutionResult, PluginExecutionStats, PluginInitializationContext, PluginRegistryConfig, ProxyConfig, RateLimitConfig, RateLimitRule, RateLimitStrategy, RedisConfig, XyPrisRequest as Request, RequestHandler, XyPrisResponse as Response, RouteConfig, RouteOptions, SecurityConfig, SecurityPlugin$1 as SecurityPlugin, ServerOptions, SmartRouteConfig, UltraFastApp, UpstreamServer, WebSocketConfig };
+export type { BasePlugin, CacheConfig, CachePlugin$1 as CachePlugin, CompressionAlgorithm, CompressionConfig, ConnectionConfig, FailoverConfig, HTTPCacheConfig, HealthCheckConfig, CachePlugin$1 as ICachePlugin, PerformancePlugin$1 as IPerformancePlugin, SecurityPlugin$1 as ISecurityPlugin, LoadBalancingStrategy, MultiServerApp, MultiServerConfig, NativePlugin, NetworkExecutionContext, NetworkExecutionResult, NetworkHealthStatus, NetworkPluginConfig, NetworkSecurityConfig, NextFunction, PerformanceConfig, PerformanceMetrics, PerformancePlugin$1 as PerformancePlugin, PluginConfiguration, PluginEvent, PluginExecutionContext, PluginExecutionResult, PluginExecutionStats, PluginInitializationContext, PluginRegistryConfig, ProxyConfig, RateLimitConfig, RateLimitRule, RateLimitStrategy, RedisConfig, XyPrisRequest as Request, RequestHandler, XyPrisResponse as Response, RouteConfig, RouteOptions, SecurityConfig, SecurityPlugin$1 as SecurityPlugin, ServerOptions, SmartRouteConfig, UltraFastApp, UpstreamServer, WebSocketConfig, MultiServerApp as XyPMS };