opticore-webapp 1.0.71 → 1.0.72

package/dist/index.d.cts

@@ -6,78 +6,12 @@ import { express } from 'opticore-express';
 import { LoggerCore } from 'opticore-logger';
 import { CorsOptions } from 'cors';
 
-interface WebServerConstructorInterface {
-    app: express.Application;
-    loggerConfig: LoggerCore;
-    localLanguage: string;
-    environmentPath: any;
-    corsOriginOptions?: Partial<CorsOptions> | null;
-}
-
-declare class WebServerCore {
-    private serverUtility;
-    private expressApp;
-    private container;
-    private readonly localLanguage;
-    private readonly loggerConfig;
-    private readonly routerExpressApp;
-    private readonly getEnvironmentValue;
-    private readonly environmentPath;
-    private serverListenEvent;
-    private dependenciesRegistered;
-    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;
-    /**
-     *
-     * @param allFeatureRoutes
-     * @private
-     */
-    private registerRoutes;
-    /**
-     *
-     * @private
-     */
-    private stackTraceErrorHandling;
-    /**
-     *
-     * @private
-     */
-    private infoWebApp;
-}
-
-declare const envPath: string;
-
 interface HotReloadConfig {
     /**
-     * Entry point file to run (e.g. 'dist/index.js' or 'src/index.ts')
+     * Entry point file to run.
+     * Reserved for future standalone mode — not used in integrated mode.
      */
-    entry: string;
+    entry?: string;
     /**
      * Runtime to use for spawning the child process.
      * - 'node'    : compiled JS only, supports IPC hot reload for .env
@@ -142,92 +76,155 @@ interface HotReloadConfig {
     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;
+    private readonly getEnvironmentValue;
+    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
+     * @private
+     */
+    private registerRoutes;
+    /**
+     *
+     * @private
+     */
+    private stackTraceErrorHandling;
+    /**
+     *
+     * @private
+     */
+    private infoWebApp;
+}
+
+declare const envPath: string;
+
 declare class HotReloadWatcher {
     private readonly cfg;
-    private child;
+    private server;
     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 restarting;
+    constructor(config?: HotReloadConfig);
+    attach(server: Server): Promise<void>;
     private setupWatchers;
-    private watchDirectoryRecursive;
+    private watchRecursive;
     private onFileChange;
     private doHotReload;
     private scheduleRestart;
-    private sendIpc;
+    /**
+     * 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 isWatchedFile;
+    private isWatched;
     private isHotReloadable;
     private isEnvFile;
     private strip;
     private ts;
     /**
-     * Startup banner — mirrors the infoServer() box style from CoreService.
+     * Startup banner — same bgGreen box style as CoreService.infoServer().
      *
-     *   ╔══════════════════════════════════════════╗
-     *   gradient title
-     *   ╔══ bgGreen box ════════════════════════╗
-     *    entry    dist/index.js
-     *    runtime  node  (IPC enabled)
-     *    root     ./src
-     *    watching .ts  .js  .json  .env
-     *    debounce 300ms
-     *   ╚══════════════════════════════════════════╝
+     *        OPTICORE  HOT  RELOAD       ← gradient
+     *   ████████████████████████████████  ← bgGreen border
+     *    root      ./src
+     *    watching  .ts  .js  .json  .env
+     *    debounce  300ms
+     *   ████████████████████████████████  ← bgGreen border
+     *    watching for changes...
      */
     private printBanner;
     /**
-     * HOT event — in-process reload, no server restart.
-     *
-     *   ✔  [ HOT ]  14:23:45  |  .env                →  env variables reloaded
+     *   ✔  [ HOT ]  14:23:45  |  .env                    →  env variables reloaded
      */
     private printHot;
     /**
-     * RELOAD event — server restart triggered.
-     *
      *   ⚡  [ RELOAD ]  14:24:03  |  src/routes/user.ts   →  restarting server...
      */
     private printReloading;
-    /**
-     * READY event — server successfully restarted.
-     * Uses the same full-width bgGreen border as infoServer().
-     *
-     *   ════════════════════════════════════════════
-     *    READY   server restarted in 245ms
-     *   ════════════════════════════════════════════
-     */
-    private printReady;
-    /**
-     * CRASH event — unexpected child process exit.
-     *
-     *   ✘  [ CRASH ]  14:24:10  |  server exited with code 1
-     */
-    private printCrash;
-    /**
-     * RETRY event — auto-restart after crash.
-     *
-     *   ↺  [ RETRY ]  14:24:11  |  attempt 1 / 5
-     */
-    private printCrashRetry;
-    /**
-     * LIMIT reached — give up restarting.
-     */
-    private printCrashLimit;
-    /**
-     * Error — miscellaneous internal error.
-     */
-    private printError;
-    /**
-     * Stopped — watcher shut down.
-     */
-    private printStopped;
     private setupProcessSignals;
 }
 

package/dist/index.d.ts

@@ -6,78 +6,12 @@ import { express } from 'opticore-express';
 import { LoggerCore } from 'opticore-logger';
 import { CorsOptions } from 'cors';
 
-interface WebServerConstructorInterface {
-    app: express.Application;
-    loggerConfig: LoggerCore;
-    localLanguage: string;
-    environmentPath: any;
-    corsOriginOptions?: Partial<CorsOptions> | null;
-}
-
-declare class WebServerCore {
-    private serverUtility;
-    private expressApp;
-    private container;
-    private readonly localLanguage;
-    private readonly loggerConfig;
-    private readonly routerExpressApp;
-    private readonly getEnvironmentValue;
-    private readonly environmentPath;
-    private serverListenEvent;
-    private dependenciesRegistered;
-    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;
-    /**
-     *
-     * @param allFeatureRoutes
-     * @private
-     */
-    private registerRoutes;
-    /**
-     *
-     * @private
-     */
-    private stackTraceErrorHandling;
-    /**
-     *
-     * @private
-     */
-    private infoWebApp;
-}
-
-declare const envPath: string;
-
 interface HotReloadConfig {
     /**
-     * Entry point file to run (e.g. 'dist/index.js' or 'src/index.ts')
+     * Entry point file to run.
+     * Reserved for future standalone mode — not used in integrated mode.
      */
-    entry: string;
+    entry?: string;
     /**
      * Runtime to use for spawning the child process.
      * - 'node'    : compiled JS only, supports IPC hot reload for .env
@@ -142,92 +76,155 @@ interface HotReloadConfig {
     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;
+    private readonly getEnvironmentValue;
+    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
+     * @private
+     */
+    private registerRoutes;
+    /**
+     *
+     * @private
+     */
+    private stackTraceErrorHandling;
+    /**
+     *
+     * @private
+     */
+    private infoWebApp;
+}
+
+declare const envPath: string;
+
 declare class HotReloadWatcher {
     private readonly cfg;
-    private child;
+    private server;
     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 restarting;
+    constructor(config?: HotReloadConfig);
+    attach(server: Server): Promise<void>;
     private setupWatchers;
-    private watchDirectoryRecursive;
+    private watchRecursive;
     private onFileChange;
     private doHotReload;
     private scheduleRestart;
-    private sendIpc;
+    /**
+     * 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 isWatchedFile;
+    private isWatched;
     private isHotReloadable;
     private isEnvFile;
     private strip;
     private ts;
     /**
-     * Startup banner — mirrors the infoServer() box style from CoreService.
+     * Startup banner — same bgGreen box style as CoreService.infoServer().
      *
-     *   ╔══════════════════════════════════════════╗
-     *   gradient title
-     *   ╔══ bgGreen box ════════════════════════╗
-     *    entry    dist/index.js
-     *    runtime  node  (IPC enabled)
-     *    root     ./src
-     *    watching .ts  .js  .json  .env
-     *    debounce 300ms
-     *   ╚══════════════════════════════════════════╝
+     *        OPTICORE  HOT  RELOAD       ← gradient
+     *   ████████████████████████████████  ← bgGreen border
+     *    root      ./src
+     *    watching  .ts  .js  .json  .env
+     *    debounce  300ms
+     *   ████████████████████████████████  ← bgGreen border
+     *    watching for changes...
      */
     private printBanner;
     /**
-     * HOT event — in-process reload, no server restart.
-     *
-     *   ✔  [ HOT ]  14:23:45  |  .env                →  env variables reloaded
+     *   ✔  [ HOT ]  14:23:45  |  .env                    →  env variables reloaded
      */
     private printHot;
     /**
-     * RELOAD event — server restart triggered.
-     *
      *   ⚡  [ RELOAD ]  14:24:03  |  src/routes/user.ts   →  restarting server...
      */
     private printReloading;
-    /**
-     * READY event — server successfully restarted.
-     * Uses the same full-width bgGreen border as infoServer().
-     *
-     *   ════════════════════════════════════════════
-     *    READY   server restarted in 245ms
-     *   ════════════════════════════════════════════
-     */
-    private printReady;
-    /**
-     * CRASH event — unexpected child process exit.
-     *
-     *   ✘  [ CRASH ]  14:24:10  |  server exited with code 1
-     */
-    private printCrash;
-    /**
-     * RETRY event — auto-restart after crash.
-     *
-     *   ↺  [ RETRY ]  14:24:11  |  attempt 1 / 5
-     */
-    private printCrashRetry;
-    /**
-     * LIMIT reached — give up restarting.
-     */
-    private printCrashLimit;
-    /**
-     * Error — miscellaneous internal error.
-     */
-    private printError;
-    /**
-     * Stopped — watcher shut down.
-     */
-    private printStopped;
     private setupProcessSignals;
 }