opticore-webapp 1.0.70 → 1.0.71

package/dist/index.d.cts

@@ -17,6 +17,7 @@ interface WebServerConstructorInterface {
 declare class WebServerCore {
     private serverUtility;
     private expressApp;
+    private container;
     private readonly localLanguage;
     private readonly loggerConfig;
     private readonly routerExpressApp;
@@ -25,9 +26,27 @@ declare class WebServerCore {
     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;
     /**
      *
@@ -54,6 +73,164 @@ declare class WebServerCore {
 
 declare const envPath: string;
 
+interface HotReloadConfig {
+    /**
+     * Entry point file to run (e.g. 'dist/index.js' or 'src/index.ts')
+     */
+    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;
+}
+
+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;
+    /**
+     * Startup banner — mirrors the infoServer() box style from CoreService.
+     *
+     *   ╔══════════════════════════════════════════╗
+     *   gradient title
+     *   ╔══ bgGreen box ════════════════════════╗
+     *    entry    dist/index.js
+     *    runtime  node  (IPC enabled)
+     *    root     ./src
+     *    watching .ts  .js  .json  .env
+     *    debounce 300ms
+     *   ╚══════════════════════════════════════════╝
+     */
+    private printBanner;
+    /**
+     * HOT event — in-process reload, no server restart.
+     *
+     *   ✔  [ 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;
+}
+
 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

@@ -17,6 +17,7 @@ interface WebServerConstructorInterface {
 declare class WebServerCore {
     private serverUtility;
     private expressApp;
+    private container;
     private readonly localLanguage;
     private readonly loggerConfig;
     private readonly routerExpressApp;
@@ -25,9 +26,27 @@ declare class WebServerCore {
     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;
     /**
      *
@@ -54,6 +73,164 @@ declare class WebServerCore {
 
 declare const envPath: string;
 
+interface HotReloadConfig {
+    /**
+     * Entry point file to run (e.g. 'dist/index.js' or 'src/index.ts')
+     */
+    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;
+}
+
+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;
+    /**
+     * Startup banner — mirrors the infoServer() box style from CoreService.
+     *
+     *   ╔══════════════════════════════════════════╗
+     *   gradient title
+     *   ╔══ bgGreen box ════════════════════════╗
+     *    entry    dist/index.js
+     *    runtime  node  (IPC enabled)
+     *    root     ./src
+     *    watching .ts  .js  .json  .env
+     *    debounce 300ms
+     *   ╚══════════════════════════════════════════╝
+     */
+    private printBanner;
+    /**
+     * HOT event — in-process reload, no server restart.
+     *
+     *   ✔  [ 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;
+}
+
 type KernelModuleType = [any[], () => void];
 
-export { type KernelModuleType, WebServerCore as WebServer, envPath };
+export { type HotReloadConfig, HotReloadWatcher, type KernelModuleType, WebServerCore as WebServer, envPath };