@expressots/core 3.0.0 → 4.0.0-preview.3

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

@@ -0,0 +1,352 @@
+/**
+ * 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); }
+};
+import { injectable, inject } from "../di/inversify.js";
+import { LazyModuleLoader } from "./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 {
+    loader;
+    startupTime = Date.now();
+    accessRecords = [];
+    loadTimes = new Map();
+    startupTimeSaved = 0;
+    constructor(loader) {
+        this.loader = loader;
+    }
+    // ============================================================================
+    // 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,
+        };
+    }
+};
+LazyLoadMetrics = __decorate([
+    injectable(),
+    __param(0, inject(LazyModuleLoader)),
+    __metadata("design:paramtypes", [LazyModuleLoader])
+], LazyLoadMetrics);
+export { LazyLoadMetrics };
+// ============================================================================
+// Factory Function
+// ============================================================================
+/**
+ * Create a new LazyLoadMetrics instance.
+ *
+ * @param loader - The LazyModuleLoader to use
+ * @returns LazyLoadMetrics instance
+ *
+ * @public API
+ */
+export function createLazyLoadMetrics(loader) {
+    return new LazyLoadMetrics(loader);
+}

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

@@ -0,0 +1,45 @@
+/**
+ * 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
+ */
+/**
+ * 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
+ */
+export 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
+ */
+export function withLazyConfig(module, config) {
+    return module.withLazyConfig(config);
+}

package/lib/esm/lazy-loading/lazy-module-loader.js

@@ -0,0 +1,305 @@
+/**
+ * LazyModuleLoader Implementation
+ *
+ * Service for loading lazy modules on-demand with dependency resolution.
+ *
+ * @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;
+};
+import { injectable } from "../di/inversify.js";
+import { isLazyModule } from "./lazy-module.js";
+// ============================================================================
+// Lazy Module Loader
+// ============================================================================
+/**
+ * Service for loading lazy modules on-demand.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept lazy-loading
+ *
+ * UNIQUE: Intelligent module loading with dependency resolution,
+ * parallel loading, and automatic container integration.
+ *
+ * @example
+ * ```typescript
+ * // Get the loader from container
+ * const loader = container.get(LazyModuleLoader);
+ *
+ * // Load a module by name
+ * await loader.load("AdminModule");
+ *
+ * // Load multiple modules in parallel
+ * await loader.loadAll(["ReportsModule", "AnalyticsModule"]);
+ *
+ * // Check if module is loaded
+ * if (!loader.isLoaded("AdminModule")) {
+ *   await loader.load("AdminModule");
+ * }
+ * ```
+ *
+ * @public API
+ */
+let LazyModuleLoader = class LazyModuleLoader {
+    modules = new Map();
+    container = null;
+    // ============================================================================
+    // Container Integration
+    // ============================================================================
+    /**
+     * Set the container for loading modules into.
+     * @internal
+     */
+    setContainer(container) {
+        this.container = container;
+    }
+    /**
+     * Get the container.
+     * @internal
+     */
+    getContainer() {
+        return this.container;
+    }
+    // ============================================================================
+    // Registration
+    // ============================================================================
+    /**
+     * Register a lazy module.
+     *
+     * @param module - The lazy module to register
+     *
+     * @example
+     * ```typescript
+     * loader.register(AdminModule);
+     * loader.register(ReportsModule);
+     * ```
+     */
+    register(module) {
+        if (!isLazyModule(module)) {
+            throw new Error("Invalid lazy module: must implement ILazyModule interface");
+        }
+        if (this.modules.has(module.name)) {
+            console.warn(`[LazyModuleLoader] Module '${module.name}' already registered, skipping`);
+            return;
+        }
+        this.modules.set(module.name, module);
+    }
+    /**
+     * Register multiple lazy modules.
+     *
+     * @param modules - Array of lazy modules to register
+     */
+    registerAll(modules) {
+        for (const module of modules) {
+            this.register(module);
+        }
+    }
+    // ============================================================================
+    // Loading
+    // ============================================================================
+    /**
+     * Load a module by name.
+     *
+     * @param moduleName - Name of the module to load
+     * @returns The loaded ContainerModule
+     * @throws Error if module not found or loading fails
+     *
+     * @example
+     * ```typescript
+     * const module = await loader.load("AdminModule");
+     * // Module is now loaded and bindings are available
+     * ```
+     */
+    async load(moduleName) {
+        const lazyModule = this.modules.get(moduleName);
+        if (!lazyModule) {
+            throw new Error(`Module '${moduleName}' not found. Did you register it?`);
+        }
+        // Check dependencies first
+        const dependencies = lazyModule.config.dependencies || [];
+        for (const depName of dependencies) {
+            if (!this.isLoaded(depName)) {
+                await this.load(depName);
+            }
+        }
+        // Load the module
+        const containerModule = await lazyModule.load();
+        // Load into container if available
+        if (this.container && containerModule) {
+            try {
+                this.container.load(containerModule);
+            }
+            catch (error) {
+                // Module bindings may already exist - that's okay
+                const message = error instanceof Error ? error.message : String(error);
+                if (!message.includes("already been declared")) {
+                    throw error;
+                }
+            }
+        }
+        return containerModule;
+    }
+    /**
+     * Load multiple modules in parallel.
+     *
+     * @param moduleNames - Names of modules to load
+     * @returns Array of loaded ContainerModules
+     *
+     * @example
+     * ```typescript
+     * const modules = await loader.loadAll([
+     *   "ReportsModule",
+     *   "AnalyticsModule",
+     *   "ExportModule"
+     * ]);
+     * ```
+     */
+    async loadAll(moduleNames) {
+        // Sort by dependencies to ensure correct load order
+        const sortedNames = this.topologicalSort(moduleNames);
+        const results = [];
+        for (const name of sortedNames) {
+            const module = await this.load(name);
+            results.push(module);
+        }
+        return results;
+    }
+    /**
+     * Load all modules matching a preload hint.
+     *
+     * @param hint - Preload hint to match
+     * @returns Array of loaded ContainerModules
+     */
+    async loadByHint(hint) {
+        const modules = this.getByHint(hint);
+        const names = modules.map((m) => m.name);
+        return this.loadAll(names);
+    }
+    // ============================================================================
+    // Status Queries
+    // ============================================================================
+    /**
+     * Check if a module is loaded.
+     *
+     * @param moduleName - Name of the module
+     * @returns True if the module is loaded
+     */
+    isLoaded(moduleName) {
+        const module = this.modules.get(moduleName);
+        return module?.isLoaded ?? false;
+    }
+    /**
+     * Get the load status of a module.
+     *
+     * @param moduleName - Name of the module
+     * @returns Module status or undefined if not registered
+     */
+    getStatus(moduleName) {
+        return this.modules.get(moduleName)?.status;
+    }
+    /**
+     * Get all registered lazy modules.
+     *
+     * @returns Array of all registered modules
+     */
+    getAll() {
+        return Array.from(this.modules.values());
+    }
+    /**
+     * Get modules by status.
+     *
+     * @param status - Status to filter by
+     * @returns Array of modules with matching status
+     */
+    getByStatus(status) {
+        return this.getAll().filter((m) => m.status === status);
+    }
+    /**
+     * Get modules by preload hint.
+     *
+     * @param hint - Preload hint to filter by
+     * @returns Array of modules with matching hint
+     */
+    getByHint(hint) {
+        return this.getAll().filter((m) => m.config.preloadHint === hint);
+    }
+    /**
+     * Get a module by name.
+     *
+     * @param name - Module name
+     * @returns The module or undefined
+     */
+    get(name) {
+        return this.modules.get(name);
+    }
+    // ============================================================================
+    // Private Helpers
+    // ============================================================================
+    /**
+     * Topological sort of module names based on dependencies.
+     * @private
+     */
+    topologicalSort(names) {
+        const visited = new Set();
+        const result = [];
+        const visiting = new Set(); // For cycle detection
+        const visit = (name) => {
+            if (visited.has(name))
+                return;
+            if (visiting.has(name)) {
+                throw new Error(`Circular dependency detected involving module '${name}'`);
+            }
+            visiting.add(name);
+            const module = this.modules.get(name);
+            if (module) {
+                const deps = module.config.dependencies || [];
+                for (const dep of deps) {
+                    if (names.includes(dep)) {
+                        visit(dep);
+                    }
+                }
+            }
+            visiting.delete(name);
+            visited.add(name);
+            result.push(name);
+        };
+        for (const name of names) {
+            visit(name);
+        }
+        return result;
+    }
+};
+LazyModuleLoader = __decorate([
+    injectable()
+], LazyModuleLoader);
+export { LazyModuleLoader };
+// ============================================================================
+// Factory Function
+// ============================================================================
+/**
+ * Create a new LazyModuleLoader instance.
+ *
+ * @param container - Optional container to load modules into
+ * @returns LazyModuleLoader instance
+ *
+ * @example
+ * ```typescript
+ * const loader = createLazyModuleLoader(container);
+ * loader.register(AdminModule);
+ * await loader.load("AdminModule");
+ * ```
+ *
+ * @public API
+ */
+export function createLazyModuleLoader(container) {
+    const loader = new LazyModuleLoader();
+    if (container) {
+        loader.setContainer(container);
+    }
+    return loader;
+}