opticore-webapp 1.0.68 → 1.0.69

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { Server } from 'http';
+import { IEnvVariables } from 'opticore-env-access';
 import { TDependency } from 'opticore-dependency-inject';
 import { TFeatureRoutes } from 'opticore-router';
 import { express } from 'opticore-express';
@@ -13,7 +14,7 @@ interface WebServerConstructorInterface {
     corsOriginOptions?: Partial<CorsOptions>;
 }
 
-type TServerStatus = "READY" | "RELOADING" | "BLOCKED" | "ERROR" | "STARTING" | "STOPPING";
+type TServerStatus = "READY" | "RELOADING" | "BLOCKED" | "ERROR" | "STARTING" | "STOPPING" | "STOPPED";
 
 interface IServerStateInfo {
     status: TServerStatus;
@@ -21,28 +22,67 @@ interface IServerStateInfo {
     host: string;
     port: number;
     language: string;
-    watcherEnabled: boolean;
-    watcherActive?: boolean;
     routesCount: number;
     dependenciesCount: number;
     startTime?: Date;
     currentTime?: Date;
     uptime?: number;
-    memoryUsage?: NodeJS.MemoryUsage;
     uptimeFormatted?: string;
-    pid?: any;
-    platform?: any;
-    nodeVersion?: any;
-    cwd?: any;
+    memoryUsage?: NodeJS.MemoryUsage;
+    pid?: number;
+    platform?: string;
+    nodeVersion?: string;
+    cwd?: string;
+    hmrEnabled: boolean;
+    hmrWatchingFiles: number;
+    hmrRestartCount: number;
+}
+
+interface IServerStats {
+    status: TServerStatus;
+    uptime: string;
+    memory: {
+        rss: string;
+        heapTotal: string;
+        heapUsed: string;
+        external: string;
+    };
+    performance: {
+        cpuUsage: NodeJS.CpuUsage;
+        resourceUsage?: NodeJS.ResourceUsage;
+    };
+    hmrStats: {
+        enabled: boolean;
+        restartCount: number;
+        lastRestartTime: number;
+        watchingFiles: number;
+    };
 }
 
+/**
+ * Main server class that handles HTTP server initialization, routing,
+ * error handling, file watching with hot reload capabilities, and HMR.
+ *
+ * @class WebServerCore
+ *
+ * @example
+ * ```typescript
+ * const app = new WebServerCore({
+ *   app: express(),
+ *   loggerConfig: loggerConfig,
+ *   environmentPath: ".env",
+ *   localLanguage: "fr",
+ *   corsOriginOptions: corsConfig
+ * });
+ *
+ * app.onStartServer(routes, databaseCallback, dependencies);
+ * ```
+ */
 declare class WebServerCore {
     private serverUtility;
-    private expressApp;
-    private fileWatcher;
+    private readonly expressApp;
     private readonly localLanguage;
     private readonly loggerConfig;
-    private readonly routerExpressApp;
     private readonly getEnvironment;
     private readonly environmentPath;
     private serverListenEvent;
@@ -50,171 +90,445 @@ declare class WebServerCore {
     private currentDependencies;
     private server;
     private errorEmitter;
-    private isWatcherEnabled;
     private serverStatus;
     private serverStartTime;
+    private fileWatcher;
+    private hmrRestartPending;
+    private hmrDebounceTimeout;
+    private hmrRestartCount;
+    private lastHmrRestartTime;
+    /**
+     * Creates a new WebServerCore instance.
+     *
+     * @constructor
+     * @param {WebServerConstructorInterface} paramsConstructor - Configuration parameters
+     *
+     * @param {express.Application} paramsConstructor.app - Express application instance
+     * @param {LoggerCore} paramsConstructor.loggerConfig - Logger configuration
+     * @param {string} paramsConstructor.environmentPath - Path to environment file
+     * @param {string} paramsConstructor.localLanguage - Default language for translations
+     * @param {CorsOptions} paramsConstructor.corsOriginOptions - CORS configuration
+     *
+     * @returns {WebServerCore} New WebServerCore instance
+     *
+     * @throws {Error} If environment file cannot be loaded
+     *
+     * @example
+     * ```typescript
+     * const server = new WebServerCore({
+     *   app: express(),
+     *   loggerConfig: new LoggerCore(config),
+     *   environmentPath: ".env",
+     *   localLanguage: "fr",
+     *   corsOriginOptions: { origin: "http://localhost:3000" }
+     * });
+     * ```
+     */
     constructor(paramsConstructor: WebServerConstructorInterface);
-    onStartServer(routers: TFeatureRoutes[], databaseCallback?: (env: any) => void, dependenciesProvider?: TDependency[]): Server | undefined;
     /**
-     * Error handling configuration
+     * Starts the HTTP server and initializes all components including HMR if enabled.
+     *
+     * @method onStartServer
+     * @public
+     *
+     * @param {TFeatureRoutes[]} routers - Array of feature routes to register
+     * @param {(env: IEnvVariables) => void} [databaseCallback] - Optional database connection callback
+     * @param {TDependency[]} [dependenciesProvider] - Optional dependency injection providers
+     *
+     * @returns {serverWebApp | undefined} HTTP server instance or undefined if startup fails
+     *
+     * @throws {ServerListenEventError} If port/host configuration is invalid
+     * @throws {Error} If server initialization fails
+     *
+     * @fires WebServerCore#startHttpServer - When server successfully starts
+     * @fires WebServerCore#startHMR - When HMR is started (if enabled)
+     * @fires WebServerCore#serverError - When server fails to start
+     *
+     * @example
+     * ```typescript
+     * const server = app.onStartServer(
+     *   routes,
+     *   (env) => connectToDatabase(env),
+     *   dependencies
+     * );
+     *
+     * if (server) {
+     *   console.log("Server started successfully");
+     * }
+     * ```
+     */
+    onStartServer(routers: TFeatureRoutes[], databaseCallback?: (env: IEnvVariables) => void, dependenciesProvider?: TDependency[]): Server | undefined;
+    /**
+     * Validates server configuration parameters.
+     *
+     * @method validateServerParameters
+     * @private
+     *
+     * @returns {boolean} True if all parameters are valid, false otherwise
+     *
+     * @remarks
+     * Validates:
+     * - Port number is valid and positive
+     * - Host is not empty
+     * - Local language is specified
+     * - HMR configuration (if enabled)
+     */
+    private validateServerParameters;
+    /**
+     * Starts the HTTP server and sets up event listeners.
+     *
+     * @method startHttpServer
+     * @private
+     *
+     * @param {(env: IEnvVariables) => void} [databaseCallback] - Database connection callback
+     *
+     * @returns {serverWebApp | undefined} HTTP server instance or undefined if startup fails
+     *
+     * @throws {Error} If server fails to start
+     */
+    private startHttpServer;
+    /**
+     * Configures server components (database, dependencies, routes, etc.).
+     *
+     * @method configureServerComponents
+     * @private
+     *
+     * @param {(env: IEnvVariables) => void} [databaseCallback] - Database connection callback
+     *
+     * @returns {void}
+     *
+     * @throws {Error} If component configuration fails
+     */
+    private configureServerComponents;
+    /**
+     * Handles server configuration errors.
+     *
+     * @method handleServerConfigurationError
+     * @private
+     *
+     * @param {any} err - The error that occurred
+     *
+     * @returns {void}
+     */
+    private handleServerConfigurationError;
+    /**
+     * Handles general startup errors.
+     *
+     * @method handleStartupError
+     * @private
+     *
+     * @param {any} error - The startup error
+     *
+     * @returns {void}
+     */
+    private handleStartupError;
+    /**
+     * Sets up Node.js process event listeners.
+     *
+     * @method setupProcessEventListeners
+     * @private
+     *
+     * @returns {void}
+     *
+     * @remarks
+     * Listens for:
+     * - Process exit events
+     * - Uncaught exceptions
+     * - Unhandled rejections
+     * - System signals (SIGINT, SIGTERM)
+     */
+    private setupProcessEventListeners;
+    /**
+     * Sets up HTTP server event listeners.
+     *
+     * @method setupServerEventListeners
+     * @private
+     *
+     * @returns {void}
+     *
+     * @remarks
+     * Configures listeners for:
+     * - Server errors
+     * - Connection closing
+     * - Connection dropping
+     * - HTTP requests (for logging)
+     *
+     * @listens Server#error - Server error events
+     * @listens Server#close - Server closing events
+     * @listens Server#drop - Connection drop events
+     * @listens Server#request - HTTP request events
+     */
+    private setupServerEventListeners;
+    /**
+     * Sets up error handling middleware and event emitters.
+     *
+     * @method setupErrorHandling
+     * @private
+     *
+     * @returns {void}
      */
     private setupErrorHandling;
     /**
-     * Setup server events
-     */
-    private setupServerEvents;
-    /**
-     * Initialize file watcher
-     */
-    private initializeFileWatcher;
-    /**
-     * Setup watcher events
-     */
-    private setupWatcherEvents;
-    /**
-     * Handle file changes detected by watcher
-     */
-    private handleFileChange;
-    /**
-     * Handle hot reload requested by watcher
-     */
-    private handleHotReload;
-    /**
-     * Handle watcher errors
-     */
-    private handleWatcherError;
-    /**
-     * Notify file change without action
-     */
-    private notifyFileChange;
-    /**
-     * Reload environment configuration
-     */
-    private reloadEnvironmentConfig;
-    /**
-     * Execute hot reload for environment files
-     */
-    private executeHotReloadEnvironment;
-    /**
-     * Reload configuration files
-     */
-    private reloadConfigurationFiles;
-    /**
-     * Execute hot reload for config files
-     */
-    private executeHotReloadConfig;
-    /**
-     * Reload application routes
-     */
-    private reloadApplicationRoutes;
-    /**
-     * Execute hot reload for routes
-     */
-    private executeHotReloadRoutes;
-    /**
-     * Execute hot reload for dependencies
-     */
-    private executeHotReloadDependencies;
-    /**
-     * Notify environment reload
-     */
-    private notifyEnvironmentReload;
-    /**
-     * Reload specific route
-     */
-    private reloadSpecificRoute;
-    /**
-     * Reload router for specific file
-     */
-    private reloadRouterForFile;
-    /**
-     * Reload configurations
-     */
-    private reloadConfigurations;
-    /**
-     * Reload dependencies
-     */
-    private reloadDependencies;
-    /**
-     * Register routes
+     * Registers routes with the Express application.
+     *
+     * @method registerRoutes
+     * @private
+     *
+     * @param {any[]} allFeatureRoutes - Array of feature routes to register
+     *
+     * @returns {void}
      */
     private registerRoutes;
     /**
-     * Parse transform error
-     */
-    private parseTransformError;
-    /**
-     * Display server info
+     * Displays server information.
+     *
+     * @method infoWebApp
+     * @private
+     *
+     * @returns {void}
      */
     private infoWebApp;
     /**
-     * Stop file watcher
-     */
-    private stopFileWatcher;
-    /**
-     * Shutdown server
-     */
-    private shutdown;
-    /**
-     * Enable/disable watcher
+     * Starts the Hot Module Replacement (HMR) file watching system.
+     *
+     * @method startHMR
+     * @private
+     *
+     * @returns {void}
+     *
+     * @remarks
+     * Configures file watcher based on environment variables:
+     * - HMR_ENABLED: Enable/disable HMR
+     * - HMR_WATCH_PATTERNS: Files to watch
+     * - HMR_IGNORE_PATTERNS: Files to ignore
+     *
+     * @throws {Error} If HMR configuration is invalid
+     */
+    private startHMR;
+    /**
+     * Handles file change events with debouncing.
+     *
+     * @method handleFileChange
+     * @private
+     *
+     * @param {string} filePath - Path of the changed file
+     * @param {string} [action="modified"] - Type of file change (modified/added/deleted)
+     *
+     * @returns {void}
+     *
+     * @remarks
+     * Uses debouncing to prevent multiple rapid reloads.
+     * Debounce time configurable via HMR_DEBOUNCE_MS environment variable.
      */
-    setWatcherEnabled(enabled: boolean): void;
+    private handleFileChange;
     /**
-     * Get watcher status
+     * Triggers a hot reload operation.
+     *
+     * @method triggerHotReload
+     * @private
+     *
+     * @param {string} filePath - Path of the changed file
+     * @param {string} action - Type of file change
+     *
+     * @returns {Promise<void>}
+     *
+     * @remarks
+     * - Checks if reload is already in progress
+     * - Validates restart limits
+     * - Performs appropriate reload actions based on file type
+     * - Emits hotReload event
+     */
+    private triggerHotReload;
+    /**
+     * Performs appropriate hot reload actions based on file type.
+     *
+     * @method performHotReloadActions
+     * @private
+     *
+     * @param {string} filePath - Path of the changed file
+     *
+     * @returns {Promise<void>}
+     *
+     * @remarks
+     * Different actions for different file types:
+     * - .json/.env: Reload translations
+     * - routes/controller files: Reload routes
+     * - config/.env files: Reload dependencies
+     */
+    private performHotReloadActions;
+    /**
+     * Reloads routes dynamically.
+     *
+     * @method reloadRoutes
+     * @private
+     *
+     * @returns {Promise<void>}
+     *
+     * @throws {Error} If route reloading fails
+     *
+     * @remarks
+     * This method should be implemented based on your architecture.
+     * It should reload route modules from the filesystem.
+     */
+    private reloadRoutes;
+    /**
+     * Reloads dependencies dynamically.
+     *
+     * @method reloadDependencies
+     * @private
+     *
+     * @returns {Promise<void>}
+     *
+     * @throws {Error} If dependency reloading fails
      */
-    getWatcherStatus(): {
-        enabled: boolean;
-        active: boolean;
-    };
+    private reloadDependencies;
     /**
-     * Get server state information
+     * Checks if HMR restart can proceed based on configuration limits.
+     *
+     * @method canProceedWithHMRRestart
+     * @private
+     *
+     * @returns {boolean} True if restart can proceed, false otherwise
+     *
+     * @remarks
+     * Checks:
+     * - Auto-restart enabled/disabled
+     * - Maximum restarts per minute limit
+     */
+    private canProceedWithHMRRestart;
+    /**
+     * Called when the HMR watcher is ready.
+     *
+     * @method onHMRWatcherReady
+     * @private
+     *
+     * @param {string[]} watchPatterns - Patterns being watched
+     * @param {string[]} ignorePatterns - Patterns being ignored
+     *
+     * @returns {void}
+     */
+    private onHMRWatcherReady;
+    /**
+     * Handles HMR watcher errors.
+     *
+     * @method onHMRWatcherError
+     * @private
+     *
+     * @param {Error} error - The watcher error
+     *
+     * @returns {void}
+     */
+    private onHMRWatcherError;
+    /**
+     * Stops the HMR system.
+     *
+     * @method stopHMR
+     * @private
+     *
+     * @returns {void}
+     */
+    private stopHMR;
+    /**
+     * Stops the server and HMR system cleanly.
+     *
+     * @method onStopServer
+     * @public
+     *
+     * @returns {void}
+     */
+    onStopServer(): void;
+    /**
+     * Gets the current server state information.
+     *
+     * @method getServerState
+     * @public
+     *
+     * @returns {IServerStateInfo} Server state information object
+     *
+     * @remarks
+     * Includes:
+     * - Status, host, port
+     * - Route and dependency counts
+     * - Uptime and memory usage
+     * - HMR configuration and statistics
      */
     getServerState(): IServerStateInfo;
     /**
-     * Simple method to get just the status
+     * Gets the current server status.
+     *
+     * @method getServerStatus
+     * @public
+     *
+     * @returns {TServerStatus} Current server status
      */
     getServerStatus(): TServerStatus;
     /**
-     * Get server statistics for monitoring
-     */
-    getServerStats(): {
-        status: TServerStatus;
-        uptime: string;
-        memory: {
-            rss: string;
-            heapTotal: string;
-            heapUsed: string;
-            external: string;
-        };
-        performance: {
-            cpuUsage: NodeJS.CpuUsage;
-            resourceUsage?: NodeJS.ResourceUsage;
-        };
-    };
-    /**
-     * Format bytes to human readable string
-     */
-    private formatBytes;
-    /**
-     * Format uptime to human readable string
+     * Gets detailed server statistics.
+     *
+     * @method getServerStats
+     * @public
+     *
+     * @returns {IServerStats} Server statistics object
+     *
+     * @remarks
+     * Includes:
+     * - Performance metrics (CPU, memory)
+     * - Uptime information
+     * - HMR statistics
+     */
+    getServerStats(): IServerStats;
+    /**
+     * Formats milliseconds into a human-readable uptime string.
+     *
+     * @method formatUptime
+     * @private
+     *
+     * @param {number} ms - Milliseconds to format
+     *
+     * @returns {string} Formatted uptime string
+     *
+     * @example
+     * formatUptime(3661000) // returns "1h 1m 1s"
      */
     private formatUptime;
     /**
-     * Add watch directories
-     */
-    addWatchDirectories(directories: string[]): void;
-    /**
-     * Clear file cache
+     * Formats bytes into a human-readable size string.
+     *
+     * @method formatBytes
+     * @private
+     *
+     * @param {number} bytes - Bytes to format
+     *
+     * @returns {string} Formatted size string
+     *
+     * @example
+     * formatBytes(1048576) // returns "1.00 MB"
      */
-    clearFileCache(): void;
-    /**
-     * Force reload configurations
-     */
-    forceReloadConfig(): void;
+    private formatBytes;
     /**
-     * Restart watcher
-     */
-    restartWatcher(): void;
+     * Checks if HMR is currently active.
+     *
+     * @method isHMRActive
+     * @public
+     *
+     * @returns {boolean} True if HMR is enabled and watching files, false otherwise
+     */
+    isHMRActive(): boolean;
+    /**
+     * Gets detailed HMR information and status.
+     *
+     * @method getHMRInfo
+     * @public
+     *
+     * @returns {any} HMR information object
+     *
+     * @remarks
+     * Includes:
+     * - Configuration settings from .env
+     * - Current restart count
+     * - Watcher status
+     */
+    getHMRInfo(): any;
 }
 
 declare const envPath: string;