opticore-webapp 1.0.69 → 1.0.71

package/dist/index.d.ts

@@ -1,7 +1,7 @@
+import * as http from 'http';
 import { Server } from 'http';
-import { IEnvVariables } from 'opticore-env-access';
-import { TDependency } from 'opticore-dependency-inject';
 import { TFeatureRoutes } from 'opticore-router';
+import { TDependency } from 'opticore-dependency-inject';
 import { express } from 'opticore-express';
 import { LoggerCore } from 'opticore-logger';
 import { CorsOptions } from 'cors';
@@ -11,528 +11,226 @@ interface WebServerConstructorInterface {
     loggerConfig: LoggerCore;
     localLanguage: string;
     environmentPath: any;
-    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;
-    };
+    corsOriginOptions?: Partial<CorsOptions> | null;
 }
 
-/**
- * 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 readonly expressApp;
+    private expressApp;
+    private container;
     private readonly localLanguage;
     private readonly loggerConfig;
-    private readonly getEnvironment;
+    private readonly routerExpressApp;
+    private readonly getEnvironmentValue;
     private readonly environmentPath;
     private serverListenEvent;
-    private currentRoutes;
-    private currentDependencies;
-    private server;
-    private errorEmitter;
-    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" }
-     * });
-     * ```
-     */
+    private dependenciesRegistered;
     constructor(paramsConstructor: WebServerConstructorInterface);
     /**
-     * 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");
-     * }
-     * ```
+     * @param dependencies
      */
-    onStartServer(routers: TFeatureRoutes[], databaseCallback?: (env: IEnvVariables) => void, dependenciesProvider?: TDependency[]): Server | undefined;
+    registerDependencies(dependencies: TDependency[]): void;
     /**
-     * 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)
+     * @param routers
+     * @param databaseCallback
+     * @param dependenciesProvider
      */
-    private validateServerParameters;
+    onStartServer(routers: TFeatureRoutes[], databaseCallback: (env: any) => void, dependenciesProvider?: TDependency[]): Server<typeof http.IncomingMessage, typeof http.ServerResponse> | undefined;
     /**
-     * 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
+     * @param serverWeb
      */
-    private startHttpServer;
+    onListeningOnServerEvent(serverWeb: Server): void;
     /**
-     * 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
+     * @param serverWeb
      */
-    private configureServerComponents;
+    onRequestOnServerEvent(serverWeb: Server): void;
     /**
-     * Handles server configuration errors.
      *
-     * @method handleServerConfigurationError
      * @private
-     *
-     * @param {any} err - The error that occurred
-     *
-     * @returns {void}
      */
-    private handleServerConfigurationError;
+    private loadTranslationFiles;
     /**
-     * Handles general startup errors.
      *
-     * @method handleStartupError
+     * @param allFeatureRoutes
      * @private
-     *
-     * @param {any} error - The startup error
-     *
-     * @returns {void}
      */
-    private handleStartupError;
+    private registerRoutes;
     /**
-     * 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;
+    private stackTraceErrorHandling;
     /**
-     * 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;
+    private infoWebApp;
+}
+
+declare const envPath: string;
+
+interface HotReloadConfig {
     /**
-     * Sets up error handling middleware and event emitters.
-     *
-     * @method setupErrorHandling
-     * @private
-     *
-     * @returns {void}
+     * Entry point file to run (e.g. 'dist/index.js' or 'src/index.ts')
      */
-    private setupErrorHandling;
+    entry: string;
     /**
-     * Registers routes with the Express application.
-     *
-     * @method registerRoutes
-     * @private
-     *
-     * @param {any[]} allFeatureRoutes - Array of feature routes to register
-     *
-     * @returns {void}
+     * Runtime to use for spawning the child process.
+     * - 'node'    : compiled JS only, supports IPC hot reload for .env
+     * - 'tsx'     : runs TypeScript directly via tsx
+     * - 'ts-node' : runs TypeScript directly via ts-node
+     * @default 'node'
      */
-    private registerRoutes;
+    runtime?: 'node' | 'tsx' | 'ts-node';
     /**
-     * Displays server information.
-     *
-     * @method infoWebApp
-     * @private
-     *
-     * @returns {void}
+     * Extra arguments passed to the runtime before the entry file.
+     * Example: ['--experimental-specifier-resolution=node']
      */
-    private infoWebApp;
+    runtimeArgs?: string[];
     /**
-     * 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
+     * Root directory to watch for file changes.
+     * @default process.cwd()
      */
-    private startHMR;
+    rootDir?: string;
     /**
-     * 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.
+     * Additional directories or glob patterns to watch.
+     * Merged with the default watched extensions (.ts, .js, .env, .json).
+     * Example: ['config', 'locales']
      */
-    private handleFileChange;
+    watchDirs?: string[];
     /**
-     * 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
+     * File extensions to watch.
+     * @default ['.ts', '.js', '.mjs', '.cjs', '.json', '.env']
      */
-    private triggerHotReload;
+    watchExtensions?: string[];
     /**
-     * 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
+     * Patterns / file names to ignore in addition to the built-in ignores.
+     * Built-in ignores: node_modules, dist, .git, package.json, package-lock.json
+     * Example: ['coverage', 'tmp', 'myIgnored.json']
      */
-    private performHotReloadActions;
+    ignore?: string[];
     /**
-     * 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.
+     * Path to the .env file that should be hot-reloaded without restarting.
+     * @default '.env'
      */
-    private reloadRoutes;
+    envFile?: string;
     /**
-     * Reloads dependencies dynamically.
-     *
-     * @method reloadDependencies
-     * @private
-     *
-     * @returns {Promise<void>}
-     *
-     * @throws {Error} If dependency reloading fails
+     * File extensions that support in-process hot reload (no server restart).
+     * All other watched extensions trigger a full server restart.
+     * @default ['.env', '.json']
      */
-    private reloadDependencies;
+    hotReloadExtensions?: string[];
     /**
-     * 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
+     * Milliseconds to wait after the last change before acting (debounce).
+     * Prevents rapid successive restarts when many files change at once.
+     * @default 300
      */
-    private canProceedWithHMRRestart;
+    debounceMs?: number;
     /**
-     * Called when the HMR watcher is ready.
-     *
-     * @method onHMRWatcherReady
-     * @private
-     *
-     * @param {string[]} watchPatterns - Patterns being watched
-     * @param {string[]} ignorePatterns - Patterns being ignored
-     *
-     * @returns {void}
+     * Automatically restart the child process if it exits unexpectedly.
+     * @default true
      */
-    private onHMRWatcherReady;
+    restartOnCrash?: boolean;
     /**
-     * Handles HMR watcher errors.
-     *
-     * @method onHMRWatcherError
-     * @private
-     *
-     * @param {Error} error - The watcher error
-     *
-     * @returns {void}
+     * Maximum number of automatic restarts on crash before giving up.
+     * @default 5
      */
-    private onHMRWatcherError;
+    maxCrashRestarts?: number;
+}
+
+declare class HotReloadWatcher {
+    private readonly cfg;
+    private child;
+    private watchers;
+    private debounceTimer;
+    private isRestarting;
+    private crashRestartCount;
+    private started;
+    private restartStart;
+    constructor(config: HotReloadConfig);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private spawnChild;
+    private killChild;
+    private setupWatchers;
+    private watchDirectoryRecursive;
+    private onFileChange;
+    private doHotReload;
+    private scheduleRestart;
+    private sendIpc;
+    private shouldIgnoreDir;
+    private shouldIgnoreFile;
+    private isWatchedFile;
+    private isHotReloadable;
+    private isEnvFile;
+    private strip;
+    private ts;
     /**
-     * Stops the HMR system.
-     *
-     * @method stopHMR
-     * @private
+     * Startup banner — mirrors the infoServer() box style from CoreService.
      *
-     * @returns {void}
+     *   ╔══════════════════════════════════════════╗
+     *   gradient title
+     *   ╔══ bgGreen box ════════════════════════╗
+     *    entry    dist/index.js
+     *    runtime  node  (IPC enabled)
+     *    root     ./src
+     *    watching .ts  .js  .json  .env
+     *    debounce 300ms
+     *   ╚══════════════════════════════════════════╝
      */
-    private stopHMR;
+    private printBanner;
     /**
-     * Stops the server and HMR system cleanly.
-     *
-     * @method onStopServer
-     * @public
+     * HOT event — in-process reload, no server restart.
      *
-     * @returns {void}
+     *   ✔  [ HOT ]  14:23:45  |  .env                →  env variables reloaded
      */
-    onStopServer(): void;
+    private printHot;
     /**
-     * Gets the current server state information.
-     *
-     * @method getServerState
-     * @public
-     *
-     * @returns {IServerStateInfo} Server state information object
+     * RELOAD event — server restart triggered.
      *
-     * @remarks
-     * Includes:
-     * - Status, host, port
-     * - Route and dependency counts
-     * - Uptime and memory usage
-     * - HMR configuration and statistics
+     *   ⚡  [ RELOAD ]  14:24:03  |  src/routes/user.ts   →  restarting server...
      */
-    getServerState(): IServerStateInfo;
+    private printReloading;
     /**
-     * Gets the current server status.
+     * READY event — server successfully restarted.
+     * Uses the same full-width bgGreen border as infoServer().
      *
-     * @method getServerStatus
-     * @public
-     *
-     * @returns {TServerStatus} Current server status
+     *   ════════════════════════════════════════════
+     *    READY   server restarted in 245ms
+     *   ════════════════════════════════════════════
      */
-    getServerStatus(): TServerStatus;
+    private printReady;
     /**
-     * Gets detailed server statistics.
-     *
-     * @method getServerStats
-     * @public
+     * CRASH event — unexpected child process exit.
      *
-     * @returns {IServerStats} Server statistics object
-     *
-     * @remarks
-     * Includes:
-     * - Performance metrics (CPU, memory)
-     * - Uptime information
-     * - HMR statistics
+     *   ✘  [ CRASH ]  14:24:10  |  server exited with code 1
      */
-    getServerStats(): IServerStats;
+    private printCrash;
     /**
-     * Formats milliseconds into a human-readable uptime string.
+     * RETRY event — auto-restart after crash.
      *
-     * @method formatUptime
-     * @private
-     *
-     * @param {number} ms - Milliseconds to format
-     *
-     * @returns {string} Formatted uptime string
-     *
-     * @example
-     * formatUptime(3661000) // returns "1h 1m 1s"
+     *   ↺  [ RETRY ]  14:24:11  |  attempt 1 / 5
      */
-    private formatUptime;
+    private printCrashRetry;
     /**
-     * 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"
+     * LIMIT reached — give up restarting.
      */
-    private formatBytes;
+    private printCrashLimit;
     /**
-     * Checks if HMR is currently active.
-     *
-     * @method isHMRActive
-     * @public
-     *
-     * @returns {boolean} True if HMR is enabled and watching files, false otherwise
+     * Error — miscellaneous internal error.
      */
-    isHMRActive(): boolean;
+    private printError;
     /**
-     * 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
+     * Stopped — watcher shut down.
      */
-    getHMRInfo(): any;
+    private printStopped;
+    private setupProcessSignals;
 }
 
-declare const envPath: string;
-
 type KernelModuleType = [any[], () => void];
 
-export { type KernelModuleType, WebServerCore as WebServer, envPath };
+export { type HotReloadConfig, HotReloadWatcher, type KernelModuleType, WebServerCore as WebServer, envPath };