opticore-webapp 1.0.70 → 1.0.72

package/dist/index.d.cts

@@ -6,17 +6,98 @@ import { express } from 'opticore-express';
 import { LoggerCore } from 'opticore-logger';
 import { CorsOptions } from 'cors';
 
+interface HotReloadConfig {
+    /**
+     * Entry point file to run.
+     * Reserved for future standalone mode — not used in integrated mode.
+     */
+    entry?: string;
+    /**
+     * 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'
+     */
+    runtime?: 'node' | 'tsx' | 'ts-node';
+    /**
+     * Extra arguments passed to the runtime before the entry file.
+     * Example: ['--experimental-specifier-resolution=node']
+     */
+    runtimeArgs?: string[];
+    /**
+     * Root directory to watch for file changes.
+     * @default process.cwd()
+     */
+    rootDir?: string;
+    /**
+     * Additional directories or glob patterns to watch.
+     * Merged with the default watched extensions (.ts, .js, .env, .json).
+     * Example: ['config', 'locales']
+     */
+    watchDirs?: string[];
+    /**
+     * File extensions to watch.
+     * @default ['.ts', '.js', '.mjs', '.cjs', '.json', '.env']
+     */
+    watchExtensions?: string[];
+    /**
+     * 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']
+     */
+    ignore?: string[];
+    /**
+     * Path to the .env file that should be hot-reloaded without restarting.
+     * @default '.env'
+     */
+    envFile?: string;
+    /**
+     * File extensions that support in-process hot reload (no server restart).
+     * All other watched extensions trigger a full server restart.
+     * @default ['.env', '.json']
+     */
+    hotReloadExtensions?: string[];
+    /**
+     * Milliseconds to wait after the last change before acting (debounce).
+     * Prevents rapid successive restarts when many files change at once.
+     * @default 300
+     */
+    debounceMs?: number;
+    /**
+     * Automatically restart the child process if it exits unexpectedly.
+     * @default true
+     */
+    restartOnCrash?: boolean;
+    /**
+     * Maximum number of automatic restarts on crash before giving up.
+     * @default 5
+     */
+    maxCrashRestarts?: number;
+}
+
 interface WebServerConstructorInterface {
     app: express.Application;
     loggerConfig: LoggerCore;
     localLanguage: string;
     environmentPath: any;
     corsOriginOptions?: Partial<CorsOptions> | null;
+    /**
+     * Enable hot reload in development mode.
+     * - true          → use all defaults
+     * - HotReloadConfig → custom configuration
+     * The watcher starts automatically when onStartServer() is called.
+     * On code changes the HTTP server is closed gracefully and the process
+     * exits (code 0) so your external runner restarts it:
+     *   tsx --watch src/index.ts  |  nodemon  |  node --watch dist/index.js
+     */
+    hotReload?: boolean | HotReloadConfig;
 }
 
 declare class WebServerCore {
     private serverUtility;
     private expressApp;
+    private container;
     private readonly localLanguage;
     private readonly loggerConfig;
     private readonly routerExpressApp;
@@ -24,16 +105,61 @@ declare class WebServerCore {
     private readonly environmentPath;
     private serverListenEvent;
     private dependenciesRegistered;
+    private readonly hotReloadCfg;
     constructor(paramsConstructor: WebServerConstructorInterface);
+    /**
+     *
+     * @param dependencies
+     */
     registerDependencies(dependencies: TDependency[]): void;
+    /**
+     *
+     * @param routers
+     * @param databaseCallback
+     * @param dependenciesProvider
+     */
     onStartServer(routers: TFeatureRoutes[], databaseCallback: (env: any) => void, dependenciesProvider?: TDependency[]): Server<typeof http.IncomingMessage, typeof http.ServerResponse> | undefined;
+    /**
+     *
+     * @param serverWeb
+     */
     onListeningOnServerEvent(serverWeb: Server): void;
+    /**
+     *
+     * @param serverWeb
+     */
     onRequestOnServerEvent(serverWeb: Server): void;
     /**
      *
      * @private
      */
     private loadTranslationFiles;
+    /**
+     * Resolve the final HotReloadConfig by merging constructor config with
+     * HMR environment variables.
+     *
+     * Priority (highest → lowest):
+     *   1. Constructor hotReload properties  (explicit code-level config)
+     *   2. HMR_* env variables               (runtime / per-environment config)
+     *   3. HotReloadWatcher internal defaults (built-in fallbacks)
+     *
+     * The watcher starts when:
+     *   - constructor passed hotReload: true | HotReloadConfig
+     *   - OR HMR_ENABLED=true in the .env file
+     */
+    private resolveHotReloadConfig;
+    /**
+     * Extract file extensions from glob patterns such as "src/** /*.ts".
+     * "src/** /*.ts"
+     * ".env"     skipped, handled natively by the watcher
+     */
+    private hmrExtractExtensions;
+    /**
+     * Extract ignore names from glob patterns such as "node_modules/**".
+     * "node_modules/**" → "node_modules"
+     * "dist/**"         → "dist"
+     */
+    private hmrExtractIgnore;
     /**
      *
      * @param allFeatureRoutes
@@ -54,6 +180,54 @@ declare class WebServerCore {
 
 declare const envPath: string;
 
+declare class HotReloadWatcher {
+    private readonly cfg;
+    private server;
+    private watchers;
+    private debounceTimer;
+    private restarting;
+    constructor(config?: HotReloadConfig);
+    attach(server: Server): Promise<void>;
+    private setupWatchers;
+    private watchRecursive;
+    private onFileChange;
+    private doHotReload;
+    private scheduleRestart;
+    /**
+     * Gracefully close the HTTP server so in-flight requests can finish,
+     * then exit with code 0 — the external runner restarts the process.
+     */
+    private closeAndExit;
+    private shouldIgnoreDir;
+    private shouldIgnoreFile;
+    private isWatched;
+    private isHotReloadable;
+    private isEnvFile;
+    private strip;
+    private ts;
+    /**
+     * Startup banner — same bgGreen box style as CoreService.infoServer().
+     *
+     *        OPTICORE  HOT  RELOAD       ← gradient
+     *   ████████████████████████████████  ← bgGreen border
+     *    root      ./src
+     *    watching  .ts  .js  .json  .env
+     *    debounce  300ms
+     *   ████████████████████████████████  ← bgGreen border
+     *    watching for changes...
+     */
+    private printBanner;
+    /**
+     *   ✔  [ HOT ]  14:23:45  |  .env                    →  env variables reloaded
+     */
+    private printHot;
+    /**
+     *   ⚡  [ RELOAD ]  14:24:03  |  src/routes/user.ts   →  restarting server...
+     */
+    private printReloading;
+    private setupProcessSignals;
+}
+
 type KernelModuleType = [any[], () => void];
 
-export { type KernelModuleType, WebServerCore as WebServer, envPath };
+export { type HotReloadConfig, HotReloadWatcher, type KernelModuleType, WebServerCore as WebServer, envPath };

package/dist/index.d.ts

@@ -6,17 +6,98 @@ import { express } from 'opticore-express';
 import { LoggerCore } from 'opticore-logger';
 import { CorsOptions } from 'cors';
 
+interface HotReloadConfig {
+    /**
+     * Entry point file to run.
+     * Reserved for future standalone mode — not used in integrated mode.
+     */
+    entry?: string;
+    /**
+     * 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'
+     */
+    runtime?: 'node' | 'tsx' | 'ts-node';
+    /**
+     * Extra arguments passed to the runtime before the entry file.
+     * Example: ['--experimental-specifier-resolution=node']
+     */
+    runtimeArgs?: string[];
+    /**
+     * Root directory to watch for file changes.
+     * @default process.cwd()
+     */
+    rootDir?: string;
+    /**
+     * Additional directories or glob patterns to watch.
+     * Merged with the default watched extensions (.ts, .js, .env, .json).
+     * Example: ['config', 'locales']
+     */
+    watchDirs?: string[];
+    /**
+     * File extensions to watch.
+     * @default ['.ts', '.js', '.mjs', '.cjs', '.json', '.env']
+     */
+    watchExtensions?: string[];
+    /**
+     * 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']
+     */
+    ignore?: string[];
+    /**
+     * Path to the .env file that should be hot-reloaded without restarting.
+     * @default '.env'
+     */
+    envFile?: string;
+    /**
+     * File extensions that support in-process hot reload (no server restart).
+     * All other watched extensions trigger a full server restart.
+     * @default ['.env', '.json']
+     */
+    hotReloadExtensions?: string[];
+    /**
+     * Milliseconds to wait after the last change before acting (debounce).
+     * Prevents rapid successive restarts when many files change at once.
+     * @default 300
+     */
+    debounceMs?: number;
+    /**
+     * Automatically restart the child process if it exits unexpectedly.
+     * @default true
+     */
+    restartOnCrash?: boolean;
+    /**
+     * Maximum number of automatic restarts on crash before giving up.
+     * @default 5
+     */
+    maxCrashRestarts?: number;
+}
+
 interface WebServerConstructorInterface {
     app: express.Application;
     loggerConfig: LoggerCore;
     localLanguage: string;
     environmentPath: any;
     corsOriginOptions?: Partial<CorsOptions> | null;
+    /**
+     * Enable hot reload in development mode.
+     * - true          → use all defaults
+     * - HotReloadConfig → custom configuration
+     * The watcher starts automatically when onStartServer() is called.
+     * On code changes the HTTP server is closed gracefully and the process
+     * exits (code 0) so your external runner restarts it:
+     *   tsx --watch src/index.ts  |  nodemon  |  node --watch dist/index.js
+     */
+    hotReload?: boolean | HotReloadConfig;
 }
 
 declare class WebServerCore {
     private serverUtility;
     private expressApp;
+    private container;
     private readonly localLanguage;
     private readonly loggerConfig;
     private readonly routerExpressApp;
@@ -24,16 +105,61 @@ declare class WebServerCore {
     private readonly environmentPath;
     private serverListenEvent;
     private dependenciesRegistered;
+    private readonly hotReloadCfg;
     constructor(paramsConstructor: WebServerConstructorInterface);
+    /**
+     *
+     * @param dependencies
+     */
     registerDependencies(dependencies: TDependency[]): void;
+    /**
+     *
+     * @param routers
+     * @param databaseCallback
+     * @param dependenciesProvider
+     */
     onStartServer(routers: TFeatureRoutes[], databaseCallback: (env: any) => void, dependenciesProvider?: TDependency[]): Server<typeof http.IncomingMessage, typeof http.ServerResponse> | undefined;
+    /**
+     *
+     * @param serverWeb
+     */
     onListeningOnServerEvent(serverWeb: Server): void;
+    /**
+     *
+     * @param serverWeb
+     */
     onRequestOnServerEvent(serverWeb: Server): void;
     /**
      *
      * @private
      */
     private loadTranslationFiles;
+    /**
+     * Resolve the final HotReloadConfig by merging constructor config with
+     * HMR environment variables.
+     *
+     * Priority (highest → lowest):
+     *   1. Constructor hotReload properties  (explicit code-level config)
+     *   2. HMR_* env variables               (runtime / per-environment config)
+     *   3. HotReloadWatcher internal defaults (built-in fallbacks)
+     *
+     * The watcher starts when:
+     *   - constructor passed hotReload: true | HotReloadConfig
+     *   - OR HMR_ENABLED=true in the .env file
+     */
+    private resolveHotReloadConfig;
+    /**
+     * Extract file extensions from glob patterns such as "src/** /*.ts".
+     * "src/** /*.ts"
+     * ".env"     skipped, handled natively by the watcher
+     */
+    private hmrExtractExtensions;
+    /**
+     * Extract ignore names from glob patterns such as "node_modules/**".
+     * "node_modules/**" → "node_modules"
+     * "dist/**"         → "dist"
+     */
+    private hmrExtractIgnore;
     /**
      *
      * @param allFeatureRoutes
@@ -54,6 +180,54 @@ declare class WebServerCore {
 
 declare const envPath: string;
 
+declare class HotReloadWatcher {
+    private readonly cfg;
+    private server;
+    private watchers;
+    private debounceTimer;
+    private restarting;
+    constructor(config?: HotReloadConfig);
+    attach(server: Server): Promise<void>;
+    private setupWatchers;
+    private watchRecursive;
+    private onFileChange;
+    private doHotReload;
+    private scheduleRestart;
+    /**
+     * Gracefully close the HTTP server so in-flight requests can finish,
+     * then exit with code 0 — the external runner restarts the process.
+     */
+    private closeAndExit;
+    private shouldIgnoreDir;
+    private shouldIgnoreFile;
+    private isWatched;
+    private isHotReloadable;
+    private isEnvFile;
+    private strip;
+    private ts;
+    /**
+     * Startup banner — same bgGreen box style as CoreService.infoServer().
+     *
+     *        OPTICORE  HOT  RELOAD       ← gradient
+     *   ████████████████████████████████  ← bgGreen border
+     *    root      ./src
+     *    watching  .ts  .js  .json  .env
+     *    debounce  300ms
+     *   ████████████████████████████████  ← bgGreen border
+     *    watching for changes...
+     */
+    private printBanner;
+    /**
+     *   ✔  [ HOT ]  14:23:45  |  .env                    →  env variables reloaded
+     */
+    private printHot;
+    /**
+     *   ⚡  [ RELOAD ]  14:24:03  |  src/routes/user.ts   →  restarting server...
+     */
+    private printReloading;
+    private setupProcessSignals;
+}
+
 type KernelModuleType = [any[], () => void];
 
-export { type KernelModuleType, WebServerCore as WebServer, envPath };
+export { type HotReloadConfig, HotReloadWatcher, type KernelModuleType, WebServerCore as WebServer, envPath };