@expressots/core 3.0.0 → 4.0.0-preview.3

package/lib/cjs/lazy-loading/lazy-load-metrics.js

@@ -0,0 +1,355 @@
+"use strict";
+/**
+ * LazyLoadMetrics Implementation
+ *
+ * Usage analytics and recommendations for lazy loading optimization.
+ *
+ * @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.LazyLoadMetrics = void 0;
+exports.createLazyLoadMetrics = createLazyLoadMetrics;
+const inversify_js_1 = require("../di/inversify.js");
+const lazy_module_loader_js_1 = require("./lazy-module-loader.js");
+// ============================================================================
+// Lazy Load Metrics
+// ============================================================================
+/**
+ * Usage analytics and recommendations for lazy loading.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept lazy-loading
+ *
+ * UNIQUE: Framework tracks module load times and provides actionable
+ * recommendations based on actual usage patterns.
+ *
+ * @example
+ * ```typescript
+ * const metrics = container.get(LazyLoadMetrics);
+ *
+ * // Get recommendations for all modules
+ * const recommendations = metrics.getRecommendations();
+ * console.log(recommendations);
+ *
+ * // Apply recommendations automatically
+ * await metrics.applyRecommendations({
+ *   autoOptimize: true,
+ *   maxStartupTime: 1000 // Max 1s startup
+ * });
+ *
+ * // Export metrics for analysis
+ * const json = metrics.export();
+ * ```
+ *
+ * @public API
+ */
+let LazyLoadMetrics = class LazyLoadMetrics {
+    constructor(loader) {
+        this.loader = loader;
+        this.startupTime = Date.now();
+        this.accessRecords = [];
+        this.loadTimes = new Map();
+        this.startupTimeSaved = 0;
+    }
+    // ============================================================================
+    // Recording
+    // ============================================================================
+    /**
+     * Record a module access event.
+     *
+     * @param moduleName - Name of the accessed module
+     *
+     * @internal Called automatically by the framework
+     */
+    recordAccess(moduleName) {
+        const now = Date.now();
+        this.accessRecords.push({
+            moduleName,
+            timestamp: now,
+            timeSinceStartup: now - this.startupTime,
+        });
+    }
+    /**
+     * Record module load time.
+     *
+     * @param moduleName - Name of the module
+     * @param timeMs - Time taken to load (ms)
+     *
+     * @internal Called automatically by the framework
+     */
+    recordLoadTime(moduleName, timeMs) {
+        this.loadTimes.set(moduleName, timeMs);
+    }
+    // ============================================================================
+    // Recommendations
+    // ============================================================================
+    /**
+     * Get recommendations for all modules.
+     *
+     * @returns Object mapping module names to recommendations
+     *
+     * @example
+     * ```typescript
+     * const recommendations = metrics.getRecommendations();
+     * // {
+     * //   "AdminModule": {
+     * //     currentStrategy: "lazy",
+     * //     loadTime: "234ms",
+     * //     suggestion: "Keep lazy - rarely accessed early",
+     * //     ...
+     * //   }
+     * // }
+     * ```
+     */
+    getRecommendations() {
+        const recommendations = {};
+        const moduleMetrics = this.calculateModuleMetrics();
+        for (const metrics of moduleMetrics) {
+            recommendations[metrics.moduleName] =
+                this.generateRecommendation(metrics);
+        }
+        return recommendations;
+    }
+    /**
+     * Get recommendation for a specific module.
+     *
+     * @param moduleName - Name of the module
+     * @returns Recommendation or undefined if module not found
+     */
+    getRecommendation(moduleName) {
+        const recommendations = this.getRecommendations();
+        return recommendations[moduleName];
+    }
+    /**
+     * Apply recommendations.
+     *
+     * @param options - Options for applying recommendations
+     *
+     * @example
+     * ```typescript
+     * await metrics.applyRecommendations({
+     *   autoOptimize: true,
+     *   maxStartupTime: 1000
+     * });
+     * ```
+     */
+    async applyRecommendations(options) {
+        if (!options.autoOptimize) {
+            return;
+        }
+        const recommendations = this.getRecommendations();
+        const maxStartup = options.maxStartupTime ?? 2000;
+        // Find modules that should be preloaded based on access patterns
+        const modulesToPreload = [];
+        let estimatedStartupTime = 0;
+        for (const [moduleName, rec] of Object.entries(recommendations)) {
+            if (rec.currentStrategy === "lazy" &&
+                rec.suggestion.includes("preloading")) {
+                const loadTimeMs = parseInt(rec.loadTime) || 0;
+                if (estimatedStartupTime + loadTimeMs <= maxStartup) {
+                    modulesToPreload.push(moduleName);
+                    estimatedStartupTime += loadTimeMs;
+                }
+            }
+        }
+        // Preload recommended modules
+        if (modulesToPreload.length > 0) {
+            console.log(`[LazyLoadMetrics] Auto-optimizing: preloading ${modulesToPreload.length} modules`);
+            for (const moduleName of modulesToPreload) {
+                try {
+                    await this.loader.load(moduleName);
+                }
+                catch (error) {
+                    console.warn(`[LazyLoadMetrics] Failed to preload '${moduleName}':`, error);
+                }
+            }
+        }
+    }
+    // ============================================================================
+    // Statistics
+    // ============================================================================
+    /**
+     * Get total startup time saved by lazy loading.
+     *
+     * @returns Time saved in milliseconds
+     */
+    getStartupTimeSaved() {
+        // Calculate based on load times of modules that weren't loaded at startup
+        const pendingModules = this.loader.getByStatus("pending");
+        let totalSaved = 0;
+        for (const module of pendingModules) {
+            const loadTime = this.loadTimes.get(module.name);
+            if (loadTime) {
+                totalSaved += loadTime;
+            }
+            else {
+                // Estimate based on average
+                totalSaved += 100; // Default estimate
+            }
+        }
+        return totalSaved + this.startupTimeSaved;
+    }
+    /**
+     * Reset all metrics.
+     */
+    reset() {
+        this.accessRecords.length = 0;
+        this.loadTimes.clear();
+        this.startupTimeSaved = 0;
+    }
+    /**
+     * Export metrics as JSON.
+     *
+     * @returns JSON string of all metrics
+     */
+    export() {
+        const moduleMetrics = this.calculateModuleMetrics();
+        const recommendations = this.getRecommendations();
+        return JSON.stringify({
+            startupTime: this.startupTime,
+            currentTime: Date.now(),
+            uptimeMs: Date.now() - this.startupTime,
+            startupTimeSaved: this.getStartupTimeSaved(),
+            totalAccessRecords: this.accessRecords.length,
+            modules: moduleMetrics,
+            recommendations,
+        }, null, 2);
+    }
+    // ============================================================================
+    // Private Helpers
+    // ============================================================================
+    /**
+     * Calculate metrics for each module.
+     * @private
+     */
+    calculateModuleMetrics() {
+        const allModules = this.loader.getAll();
+        const metricsMap = new Map();
+        // Initialize metrics for all modules
+        for (const module of allModules) {
+            metricsMap.set(module.name, {
+                moduleName: module.name,
+                accessCount: 0,
+                firstAccessTime: null,
+                avgTimeSinceStartup: 0,
+                loadTime: module.loadTime,
+                isLazy: module.config.preloadHint !== "high",
+            });
+        }
+        // Process access records
+        for (const record of this.accessRecords) {
+            const metrics = metricsMap.get(record.moduleName);
+            if (metrics) {
+                metrics.accessCount++;
+                if (metrics.firstAccessTime === null) {
+                    metrics.firstAccessTime = record.timeSinceStartup;
+                }
+                metrics.avgTimeSinceStartup =
+                    (metrics.avgTimeSinceStartup * (metrics.accessCount - 1) +
+                        record.timeSinceStartup) /
+                        metrics.accessCount;
+            }
+        }
+        return Array.from(metricsMap.values());
+    }
+    /**
+     * Generate recommendation for a module.
+     * @private
+     */
+    generateRecommendation(metrics) {
+        const loadTimeMs = metrics.loadTime ?? 100; // Default estimate
+        const loadTimeStr = `${loadTimeMs}ms`;
+        const currentStrategy = metrics.isLazy ? "lazy" : "eager";
+        // Determine access frequency description
+        let accessFrequency;
+        if (metrics.accessCount === 0) {
+            accessFrequency = "Never accessed";
+        }
+        else if (metrics.firstAccessTime !== null &&
+            metrics.firstAccessTime < 5000) {
+            const percentage = Math.round((metrics.accessCount / Math.max(this.accessRecords.length, 1)) * 100);
+            accessFrequency = `${percentage}% within 5s of startup`;
+        }
+        else if (metrics.firstAccessTime !== null &&
+            metrics.firstAccessTime < 60000) {
+            accessFrequency = "Accessed within first minute";
+        }
+        else {
+            accessFrequency = "Rarely accessed early";
+        }
+        // Generate suggestion
+        let suggestion;
+        let estimatedSavings;
+        if (currentStrategy === "lazy") {
+            if (metrics.accessCount === 0) {
+                suggestion = "Keep lazy - never accessed";
+                estimatedSavings = `+${loadTimeMs}ms startup saved`;
+            }
+            else if (metrics.firstAccessTime !== null &&
+                metrics.firstAccessTime < 2000) {
+                suggestion = "Consider preloading - frequently accessed early";
+                estimatedSavings = `-${loadTimeMs}ms startup, +${loadTimeMs}ms first access`;
+            }
+            else {
+                suggestion = "Keep lazy - rarely accessed early";
+                estimatedSavings = `+${loadTimeMs}ms startup saved`;
+            }
+        }
+        else {
+            if (metrics.accessCount === 0) {
+                suggestion = "Consider lazy loading - never accessed";
+                estimatedSavings = `+${loadTimeMs}ms startup if lazy`;
+            }
+            else if (metrics.firstAccessTime !== null &&
+                metrics.firstAccessTime > 30000) {
+                suggestion = "Consider lazy loading - accessed late";
+                estimatedSavings = `+${loadTimeMs}ms startup, -${loadTimeMs}ms on access`;
+            }
+            else {
+                suggestion = "Keep eager - frequently accessed";
+                estimatedSavings = "Optimal";
+            }
+        }
+        return {
+            currentStrategy,
+            loadTime: loadTimeStr,
+            firstAccessDelay: metrics.isLazy ? loadTimeStr : "0ms",
+            accessFrequency,
+            suggestion,
+            estimatedSavings,
+        };
+    }
+};
+exports.LazyLoadMetrics = LazyLoadMetrics;
+exports.LazyLoadMetrics = LazyLoadMetrics = __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])
+], LazyLoadMetrics);
+// ============================================================================
+// Factory Function
+// ============================================================================
+/**
+ * Create a new LazyLoadMetrics instance.
+ *
+ * @param loader - The LazyModuleLoader to use
+ * @returns LazyLoadMetrics instance
+ *
+ * @public API
+ */
+function createLazyLoadMetrics(loader) {
+    return new LazyLoadMetrics(loader);
+}

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

@@ -0,0 +1,49 @@
+"use strict";
+/**
+ * Standalone (free-function) wrappers around `LazyModule` chain methods.
+ *
+ * The fluent API (`module.withPreloadHint(...).withLazyConfig(...)`) remains
+ * the recommended style. These helpers exist so users can compose lazy
+ * configurations with point-free style or apply the same hint to a list of
+ * modules:
+ *
+ * ```ts
+ * import { CreateLazyModule, withPreloadHint, withLazyConfig } from "@expressots/core";
+ *
+ * const Admin = withPreloadHint(
+ *   CreateLazyModule([AdminController]),
+ *   "low",
+ * );
+ *
+ * const Analytics = withLazyConfig(
+ *   CreateLazyModule([AnalyticsController]),
+ *   { preloadHint: "medium", prefetchAfterIdle: 5000 },
+ * );
+ * ```
+ *
+ * @public API
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withPreloadHint = withPreloadHint;
+exports.withLazyConfig = withLazyConfig;
+/**
+ * Set a preload hint on the supplied lazy module and return it.
+ *
+ * Equivalent to `module.withPreloadHint(hint)`. Returned reference is the same
+ * instance — no copy is made.
+ *
+ * @public API
+ */
+function withPreloadHint(module, hint) {
+    return module.withPreloadHint(hint);
+}
+/**
+ * Merge the supplied partial config into the lazy module and return it.
+ *
+ * Equivalent to `module.withLazyConfig(config)`.
+ *
+ * @public API
+ */
+function withLazyConfig(module, config) {
+    return module.withLazyConfig(config);
+}