@expressots/core 3.0.0-beta.4 → 4.0.0-preview.1

package/lib/cjs/lazy-loading/lazy-module-manager.js

@@ -0,0 +1,244 @@
+"use strict";
+/**
+ * LazyModuleManager Implementation
+ *
+ * Runtime module management service for querying and controlling lazy modules.
+ *
+ * @module lazy-loading
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LazyModuleManager = void 0;
+exports.createLazyModuleManager = createLazyModuleManager;
+const inversify_js_1 = require("../di/inversify.js");
+const lazy_module_loader_js_1 = require("./lazy-module-loader.js");
+// ============================================================================
+// Lazy Module Manager
+// ============================================================================
+/**
+ * Runtime module management service.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept lazy-loading
+ *
+ * UNIQUE: Query module load status at runtime, get statistics,
+ * and manually control module loading.
+ *
+ * @example
+ * ```typescript
+ * const manager = container.get(LazyModuleManager);
+ *
+ * // Check if module is loaded
+ * if (!manager.isLoaded("AdminModule")) {
+ *   await manager.load("AdminModule");
+ * }
+ *
+ * // Get all loaded modules
+ * const loaded = manager.getLoadedModules();
+ * console.log(`Loaded: ${loaded.join(", ")}`);
+ *
+ * // Get statistics
+ * const stats = manager.getStatistics();
+ * console.log(`Average load time: ${stats.avgLoadTime}ms`);
+ * ```
+ *
+ * @public API
+ */
+let LazyModuleManager = class LazyModuleManager {
+    constructor(loader) {
+        this.loader = loader;
+    }
+    // ============================================================================
+    // Status Queries
+    // ============================================================================
+    /**
+     * Check if a module is loaded.
+     *
+     * @param moduleName - Name of the module
+     * @returns True if the module is loaded
+     *
+     * @example
+     * ```typescript
+     * if (manager.isLoaded("AdminModule")) {
+     *   // AdminModule is ready to use
+     * }
+     * ```
+     */
+    isLoaded(moduleName) {
+        return this.loader.isLoaded(moduleName);
+    }
+    /**
+     * Get names of all loaded modules.
+     *
+     * @returns Array of loaded module names
+     *
+     * @example
+     * ```typescript
+     * const loaded = manager.getLoadedModules();
+     * // ["CoreModule", "AuthModule", "UserModule"]
+     * ```
+     */
+    getLoadedModules() {
+        return this.loader
+            .getAll()
+            .filter((m) => m.isLoaded)
+            .map((m) => m.name);
+    }
+    /**
+     * Get names of all pending (unloaded) modules.
+     *
+     * @returns Array of pending module names
+     *
+     * @example
+     * ```typescript
+     * const pending = manager.getPendingModules();
+     * // ["AdminModule", "ReportsModule"]
+     * ```
+     */
+    getPendingModules() {
+        return this.loader
+            .getAll()
+            .filter((m) => m.status === "pending")
+            .map((m) => m.name);
+    }
+    /**
+     * Get names of all modules that failed to load.
+     *
+     * @returns Array of failed module names
+     */
+    getFailedModules() {
+        return this.loader
+            .getAll()
+            .filter((m) => m.status === "failed")
+            .map((m) => m.name);
+    }
+    // ============================================================================
+    // Loading Control
+    // ============================================================================
+    /**
+     * Manually load a module.
+     *
+     * @param moduleName - Name of the module to load
+     *
+     * @example
+     * ```typescript
+     * // Preload module before it's needed
+     * await manager.load("AdminModule");
+     * ```
+     */
+    async load(moduleName) {
+        await this.loader.load(moduleName);
+    }
+    /**
+     * Load all modules with a specific preload hint.
+     *
+     * @param hint - Preload hint to match
+     *
+     * @example
+     * ```typescript
+     * // Load all high-priority modules
+     * await manager.loadByHint("high");
+     * ```
+     */
+    async loadByHint(hint) {
+        await this.loader.loadByHint(hint);
+    }
+    // ============================================================================
+    // Statistics
+    // ============================================================================
+    /**
+     * Get module load statistics.
+     *
+     * @returns Statistics about module loading
+     *
+     * @example
+     * ```typescript
+     * const stats = manager.getStatistics();
+     * console.log({
+     *   totalModules: stats.totalModules,
+     *   loadedModules: stats.loadedModules,
+     *   avgLoadTime: stats.avgLoadTime + "ms",
+     *   memorySaved: (stats.estimatedMemorySaved / 1024 / 1024).toFixed(2) + "MB"
+     * });
+     * ```
+     */
+    getStatistics() {
+        const allModules = this.loader.getAll();
+        const loadedModules = allModules.filter((m) => m.isLoaded);
+        const pendingModules = allModules.filter((m) => m.status === "pending");
+        const failedModules = allModules.filter((m) => m.status === "failed");
+        const loadTimes = loadedModules
+            .map((m) => m.loadTime)
+            .filter((t) => t !== null);
+        const totalLoadTime = loadTimes.reduce((sum, t) => sum + t, 0);
+        const avgLoadTime = loadTimes.length > 0 ? totalLoadTime / loadTimes.length : 0;
+        // Estimate memory saved (rough estimate: 50KB per lazy module)
+        const estimatedMemorySaved = pendingModules.length * 50 * 1024;
+        return {
+            totalModules: allModules.length,
+            loadedModules: loadedModules.length,
+            lazyModules: pendingModules.length,
+            failedModules: failedModules.length,
+            avgLoadTime: Math.round(avgLoadTime),
+            totalLoadTime: Math.round(totalLoadTime),
+            estimatedMemorySaved,
+        };
+    }
+    // ============================================================================
+    // Advanced Operations
+    // ============================================================================
+    /**
+     * Attempt to unload a module.
+     *
+     * Note: Due to JavaScript's garbage collection, unloading may not
+     * immediately free memory. The module's bindings will be removed
+     * from the container, but cached instances may remain.
+     *
+     * @param moduleName - Name of the module to unload
+     * @returns True if unload was attempted, false if module not found
+     */
+    async unload(moduleName) {
+        const module = this.loader.get(moduleName);
+        if (!module) {
+            return false;
+        }
+        // For now, we can't truly unload modules in InversifyJS
+        // This would require container.unbind() for each binding
+        // We'll mark this as a limitation and return false
+        console.warn(`[LazyModuleManager] Module unloading is not fully supported. ` +
+            `Module '${moduleName}' bindings will remain in the container.`);
+        return false;
+    }
+};
+exports.LazyModuleManager = LazyModuleManager;
+exports.LazyModuleManager = LazyModuleManager = __decorate([
+    (0, inversify_js_1.injectable)(),
+    __param(0, (0, inversify_js_1.inject)(lazy_module_loader_js_1.LazyModuleLoader)),
+    __metadata("design:paramtypes", [lazy_module_loader_js_1.LazyModuleLoader])
+], LazyModuleManager);
+// ============================================================================
+// Factory Function
+// ============================================================================
+/**
+ * Create a new LazyModuleManager instance.
+ *
+ * @param loader - The LazyModuleLoader to use
+ * @returns LazyModuleManager instance
+ *
+ * @public API
+ */
+function createLazyModuleManager(loader) {
+    return new LazyModuleManager(loader);
+}

package/lib/cjs/lazy-loading/lazy-module-warmup.js

@@ -0,0 +1,294 @@
+"use strict";
+/**
+ * LazyModuleWarmup Implementation
+ *
+ * Service for warming up lazy modules in the background during idle time.
+ *
+ * @module lazy-loading
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LazyModuleWarmup = void 0;
+exports.createLazyModuleWarmup = createLazyModuleWarmup;
+const inversify_js_1 = require("../di/inversify.js");
+const lazy_module_loader_js_1 = require("./lazy-module-loader.js");
+// ============================================================================
+// Default Configuration
+// ============================================================================
+const DEFAULT_WARMUP_CONFIG = {
+    strategy: "idle",
+    maxConcurrent: 2,
+    delay: 5000, // 5 seconds after startup
+    hints: ["high", "medium"],
+};
+// ============================================================================
+// Lazy Module Warmup
+// ============================================================================
+/**
+ * Service for warming up lazy modules in the background.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept lazy-loading
+ *
+ * UNIQUE: Automatic module warmup during server idle time.
+ * Modules are loaded in the background without blocking requests.
+ *
+ * @example
+ * ```typescript
+ * const warmup = container.get(LazyModuleWarmup);
+ *
+ * // Start background warmup
+ * await warmup.start({
+ *   strategy: "idle",
+ *   maxConcurrent: 2,
+ *   priority: ["ReportsModule", "AnalyticsModule"]
+ * });
+ *
+ * // Check progress
+ * console.log(`Warmup progress: ${warmup.getProgress()}%`);
+ *
+ * // Get warmed modules
+ * console.log(`Warmed: ${warmup.getWarmedModules().join(", ")}`);
+ * ```
+ *
+ * @public API
+ */
+let LazyModuleWarmup = class LazyModuleWarmup {
+    constructor(loader) {
+        this.loader = loader;
+        this.running = false;
+        this.warmedModules = new Set();
+        this.totalToWarm = 0;
+        this.stopRequested = false;
+        this.warmupTimer = null;
+    }
+    // ============================================================================
+    // Control Methods
+    // ============================================================================
+    /**
+     * Start warming up modules in the background.
+     *
+     * @param config - Optional warmup configuration
+     *
+     * @example
+     * ```typescript
+     * // Start with defaults (idle strategy)
+     * await warmup.start();
+     *
+     * // Start immediately with priority list
+     * await warmup.start({
+     *   strategy: "immediate",
+     *   priority: ["CriticalModule", "ImportantModule"],
+     *   maxConcurrent: 3
+     * });
+     *
+     * // Start after delay
+     * await warmup.start({
+     *   strategy: "scheduled",
+     *   delay: 10000 // 10 seconds
+     * });
+     * ```
+     */
+    async start(config = {}) {
+        if (this.running) {
+            console.warn("[LazyModuleWarmup] Warmup already in progress");
+            return;
+        }
+        const fullConfig = { ...DEFAULT_WARMUP_CONFIG, ...config };
+        this.running = true;
+        this.stopRequested = false;
+        this.warmedModules.clear();
+        // Get modules to warm up
+        const modulesToWarm = this.getModulesToWarm(fullConfig);
+        this.totalToWarm = modulesToWarm.length;
+        if (modulesToWarm.length === 0) {
+            console.log("[LazyModuleWarmup] No modules to warm up");
+            this.running = false;
+            return;
+        }
+        console.log(`[LazyModuleWarmup] Starting warmup of ${modulesToWarm.length} modules ` +
+            `(strategy: ${fullConfig.strategy})`);
+        // Apply delay based on strategy
+        const delay = fullConfig.strategy === "immediate" ? 0 : (fullConfig.delay ?? 5000);
+        if (delay > 0) {
+            await this.delay(delay);
+        }
+        if (this.stopRequested) {
+            this.running = false;
+            return;
+        }
+        // Warm up modules
+        await this.warmModules(modulesToWarm, fullConfig.maxConcurrent ?? 2);
+        this.running = false;
+        console.log(`[LazyModuleWarmup] Warmup complete. Warmed ${this.warmedModules.size}/${this.totalToWarm} modules`);
+    }
+    /**
+     * Stop the warmup process.
+     *
+     * @example
+     * ```typescript
+     * warmup.stop();
+     * console.log("Warmup stopped");
+     * ```
+     */
+    stop() {
+        this.stopRequested = true;
+        if (this.warmupTimer) {
+            clearTimeout(this.warmupTimer);
+            this.warmupTimer = null;
+        }
+    }
+    // ============================================================================
+    // Status Methods
+    // ============================================================================
+    /**
+     * Check if warmup is in progress.
+     *
+     * @returns True if warmup is running
+     */
+    isRunning() {
+        return this.running;
+    }
+    /**
+     * Get warmup progress (0-100).
+     *
+     * @returns Progress percentage
+     */
+    getProgress() {
+        if (this.totalToWarm === 0) {
+            return 100;
+        }
+        return Math.round((this.warmedModules.size / this.totalToWarm) * 100);
+    }
+    /**
+     * Get list of modules that have been warmed up.
+     *
+     * @returns Array of warmed module names
+     */
+    getWarmedModules() {
+        return Array.from(this.warmedModules);
+    }
+    // ============================================================================
+    // Private Helpers
+    // ============================================================================
+    /**
+     * Get modules to warm up based on configuration.
+     * @private
+     */
+    getModulesToWarm(config) {
+        const allModules = this.loader.getAll();
+        let modulesToWarm = [];
+        // Filter by hints if specified
+        if (config.hints && config.hints.length > 0) {
+            const hintsSet = new Set(config.hints);
+            modulesToWarm = allModules
+                .filter((m) => !m.isLoaded && hintsSet.has(m.config.preloadHint))
+                .map((m) => m.name);
+        }
+        else {
+            modulesToWarm = allModules.filter((m) => !m.isLoaded).map((m) => m.name);
+        }
+        // Apply priority ordering if specified
+        if (config.priority && config.priority.length > 0) {
+            const prioritySet = new Set(config.priority);
+            const prioritized = [];
+            const others = [];
+            for (const name of modulesToWarm) {
+                if (prioritySet.has(name)) {
+                    prioritized.push(name);
+                }
+                else {
+                    others.push(name);
+                }
+            }
+            // Sort prioritized by their order in the priority array
+            prioritized.sort((a, b) => {
+                return config.priority.indexOf(a) - config.priority.indexOf(b);
+            });
+            modulesToWarm = [...prioritized, ...others];
+        }
+        return modulesToWarm;
+    }
+    /**
+     * Warm up modules with concurrency control.
+     * @private
+     */
+    async warmModules(moduleNames, maxConcurrent) {
+        const chunks = this.chunk(moduleNames, maxConcurrent);
+        for (const chunk of chunks) {
+            if (this.stopRequested) {
+                break;
+            }
+            // Load chunk in parallel
+            const promises = chunk.map(async (name) => {
+                try {
+                    await this.loader.load(name);
+                    this.warmedModules.add(name);
+                }
+                catch (error) {
+                    console.warn(`[LazyModuleWarmup] Failed to warm '${name}':`, error);
+                }
+            });
+            await Promise.all(promises);
+            // Small delay between chunks to not overwhelm the system
+            if (!this.stopRequested && chunks.indexOf(chunk) < chunks.length - 1) {
+                await this.delay(100);
+            }
+        }
+    }
+    /**
+     * Split array into chunks.
+     * @private
+     */
+    chunk(array, size) {
+        const chunks = [];
+        for (let i = 0; i < array.length; i += size) {
+            chunks.push(array.slice(i, i + size));
+        }
+        return chunks;
+    }
+    /**
+     * Delay helper.
+     * @private
+     */
+    delay(ms) {
+        return new Promise((resolve) => {
+            this.warmupTimer = setTimeout(() => {
+                this.warmupTimer = null;
+                resolve();
+            }, ms);
+        });
+    }
+};
+exports.LazyModuleWarmup = LazyModuleWarmup;
+exports.LazyModuleWarmup = LazyModuleWarmup = __decorate([
+    (0, inversify_js_1.injectable)(),
+    __param(0, (0, inversify_js_1.inject)(lazy_module_loader_js_1.LazyModuleLoader)),
+    __metadata("design:paramtypes", [lazy_module_loader_js_1.LazyModuleLoader])
+], LazyModuleWarmup);
+// ============================================================================
+// Factory Function
+// ============================================================================
+/**
+ * Create a new LazyModuleWarmup instance.
+ *
+ * @param loader - The LazyModuleLoader to use
+ * @returns LazyModuleWarmup instance
+ *
+ * @public API
+ */
+function createLazyModuleWarmup(loader) {
+    return new LazyModuleWarmup(loader);
+}