opticore-webapp 1.0.67 → 1.0.69

package/dist/index.d.cts

@@ -1,9 +1,10 @@
 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';
 import { LoggerCore } from 'opticore-logger';
 import { CorsOptions } from 'cors';
-import { TFeatureRoutes } from 'opticore-router';
 
 interface WebServerConstructorInterface {
     app: express.Application;
@@ -13,20 +14,75 @@ interface WebServerConstructorInterface {
     corsOriginOptions?: Partial<CorsOptions>;
 }
 
+type TServerStatus = "READY" | "RELOADING" | "BLOCKED" | "ERROR" | "STARTING" | "STOPPING" | "STOPPED";
+
+interface IServerStateInfo {
+    status: TServerStatus;
+    isRunning: boolean;
+    host: string;
+    port: number;
+    language: string;
+    routesCount: number;
+    dependenciesCount: number;
+    startTime?: Date;
+    currentTime?: Date;
+    uptime?: number;
+    uptimeFormatted?: string;
+    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;
+    };
+}
+
 /**
- * WebServerCore - Architecture Serveur-Autorité
+ * Main server class that handles HTTP server initialization, routing,
+ * error handling, file watching with hot reload capabilities, and HMR.
+ *
+ * @class WebServerCore
  *
- * Le serveur gère strictement ses états :
- * - READY : Prêt à recevoir des demandes de hot reload
- * - RELOADING : En cours de hot reload
- * - BLOCKED : Bloqué par une erreur, refuse les nouveaux reloads
+ * @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 readonly expressApp;
     private readonly localLanguage;
     private readonly loggerConfig;
-    private readonly routerExpressApp;
     private readonly getEnvironment;
     private readonly environmentPath;
     private serverListenEvent;
@@ -34,50 +90,445 @@ declare class WebServerCore {
     private currentDependencies;
     private server;
     private errorEmitter;
-    private serverState;
-    private lastError;
-    private hotReloadAttempts;
-    private hotReloadSuccesses;
-    private hotReloadFailures;
+    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;
     /**
-     * ✅✅✅ Configuration de la gestion d'erreurs
+     * 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");
+     * }
+     * ```
      */
-    private setupErrorHandling;
-    private setupServerEvents;
-    private notifyServerReady;
-    private setupSignalHandlers;
-    private setupIPCHandlers;
+    onStartServer(routers: TFeatureRoutes[], databaseCallback?: (env: IEnvVariables) => void, dependenciesProvider?: TDependency[]): Server | undefined;
     /**
-     * ✅✅✅ HOT RELOAD avec gestion d'état stricte
+     * 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 performTrueHotReload;
+    private validateServerParameters;
     /**
-     * Nettoie le cache des modules applicatifs
+     * 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 clearApplicationModulesCache;
-    private reloadConfigurations;
-    private reloadDependencies;
+    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;
     /**
-     * ✅✅✅ Notifier le watcher : SUCCÈS
+     * Handles server configuration errors.
+     *
+     * @method handleServerConfigurationError
+     * @private
+     *
+     * @param {any} err - The error that occurred
+     *
+     * @returns {void}
      */
-    private notifyWatcherReloadSuccess;
+    private handleServerConfigurationError;
     /**
-     * ✅✅✅ Notifier le watcher : BLOQUÉ PAR ERREUR TRANSFORM
+     * Handles general startup errors.
+     *
+     * @method handleStartupError
+     * @private
+     *
+     * @param {any} error - The startup error
+     *
+     * @returns {void}
      */
-    private notifyWatcherBlockedByError;
+    private handleStartupError;
     /**
-     * ✅✅✅ Notifier le watcher : ERREUR GÉNÉRIQUE
+     * 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 notifyWatcherReloadError;
+    private setupProcessEventListeners;
     /**
-     * ✅✅✅ Parser les détails d'une TransformError
+     * 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;
+    /**
+     * Registers routes with the Express application.
+     *
+     * @method registerRoutes
+     * @private
+     *
+     * @param {any[]} allFeatureRoutes - Array of feature routes to register
+     *
+     * @returns {void}
      */
-    private parseTransformError;
     private registerRoutes;
+    /**
+     * Displays server information.
+     *
+     * @method infoWebApp
+     * @private
+     *
+     * @returns {void}
+     */
     private infoWebApp;
-    private shutdown;
+    /**
+     * 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.
+     */
+    private handleFileChange;
+    /**
+     * 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
+     */
+    private reloadDependencies;
+    /**
+     * 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;
+    /**
+     * Gets the current server status.
+     *
+     * @method getServerStatus
+     * @public
+     *
+     * @returns {TServerStatus} Current server status
+     */
+    getServerStatus(): TServerStatus;
+    /**
+     * 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;
+    /**
+     * 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"
+     */
+    private formatBytes;
+    /**
+     * 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;