@expressots/core 3.0.0 → 4.0.0-preview.3

package/lib/cjs/types/lazy-loading/lazy-load-metrics.d.ts

@@ -0,0 +1,139 @@
+/**
+ * LazyLoadMetrics Implementation
+ *
+ * Usage analytics and recommendations for lazy loading optimization.
+ *
+ * @module lazy-loading
+ */
+import { ILazyLoadMetrics, ModuleRecommendation, ApplyRecommendationsOptions } from "./lazy.interfaces.js";
+import { LazyModuleLoader } from "./lazy-module-loader.js";
+/**
+ * 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
+ */
+export declare class LazyLoadMetrics implements ILazyLoadMetrics {
+    private readonly loader;
+    private readonly startupTime;
+    private readonly accessRecords;
+    private readonly loadTimes;
+    private startupTimeSaved;
+    constructor(loader: LazyModuleLoader);
+    /**
+     * Record a module access event.
+     *
+     * @param moduleName - Name of the accessed module
+     *
+     * @internal Called automatically by the framework
+     */
+    recordAccess(moduleName: string): void;
+    /**
+     * 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: string, timeMs: number): void;
+    /**
+     * 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(): Record<string, ModuleRecommendation>;
+    /**
+     * Get recommendation for a specific module.
+     *
+     * @param moduleName - Name of the module
+     * @returns Recommendation or undefined if module not found
+     */
+    getRecommendation(moduleName: string): ModuleRecommendation | undefined;
+    /**
+     * Apply recommendations.
+     *
+     * @param options - Options for applying recommendations
+     *
+     * @example
+     * ```typescript
+     * await metrics.applyRecommendations({
+     *   autoOptimize: true,
+     *   maxStartupTime: 1000
+     * });
+     * ```
+     */
+    applyRecommendations(options: ApplyRecommendationsOptions): Promise<void>;
+    /**
+     * Get total startup time saved by lazy loading.
+     *
+     * @returns Time saved in milliseconds
+     */
+    getStartupTimeSaved(): number;
+    /**
+     * Reset all metrics.
+     */
+    reset(): void;
+    /**
+     * Export metrics as JSON.
+     *
+     * @returns JSON string of all metrics
+     */
+    export(): string;
+    /**
+     * Calculate metrics for each module.
+     * @private
+     */
+    private calculateModuleMetrics;
+    /**
+     * Generate recommendation for a module.
+     * @private
+     */
+    private generateRecommendation;
+}
+/**
+ * Create a new LazyLoadMetrics instance.
+ *
+ * @param loader - The LazyModuleLoader to use
+ * @returns LazyLoadMetrics instance
+ *
+ * @public API
+ */
+export declare function createLazyLoadMetrics(loader: LazyModuleLoader): LazyLoadMetrics;

package/lib/cjs/types/lazy-loading/lazy-module-helpers.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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
+ */
+import type { ILazyModule, LazyModuleConfig, PreloadHint } from "./lazy.interfaces.js";
+/**
+ * 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 declare function withPreloadHint(module: ILazyModule, hint: PreloadHint): ILazyModule;
+/**
+ * Merge the supplied partial config into the lazy module and return it.
+ *
+ * Equivalent to `module.withLazyConfig(config)`.
+ *
+ * @public API
+ */
+export declare function withLazyConfig(module: ILazyModule, config: Partial<LazyModuleConfig>): ILazyModule;

package/lib/cjs/types/lazy-loading/lazy-module-loader.d.ts

@@ -0,0 +1,169 @@
+/**
+ * LazyModuleLoader Implementation
+ *
+ * Service for loading lazy modules on-demand with dependency resolution.
+ *
+ * @module lazy-loading
+ */
+import { Container, ContainerModule } from "../di/inversify.js";
+import { ILazyModule, ILazyModuleLoader, ModuleLoadStatus, PreloadHint } from "./lazy.interfaces.js";
+/**
+ * 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
+ */
+export declare class LazyModuleLoader implements ILazyModuleLoader {
+    private readonly modules;
+    private container;
+    /**
+     * Set the container for loading modules into.
+     * @internal
+     */
+    setContainer(container: Container): void;
+    /**
+     * Get the container.
+     * @internal
+     */
+    getContainer(): Container | null;
+    /**
+     * Register a lazy module.
+     *
+     * @param module - The lazy module to register
+     *
+     * @example
+     * ```typescript
+     * loader.register(AdminModule);
+     * loader.register(ReportsModule);
+     * ```
+     */
+    register(module: ILazyModule): void;
+    /**
+     * Register multiple lazy modules.
+     *
+     * @param modules - Array of lazy modules to register
+     */
+    registerAll(modules: Array<ILazyModule>): void;
+    /**
+     * 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
+     * ```
+     */
+    load(moduleName: string): Promise<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"
+     * ]);
+     * ```
+     */
+    loadAll(moduleNames: Array<string>): Promise<Array<ContainerModule>>;
+    /**
+     * Load all modules matching a preload hint.
+     *
+     * @param hint - Preload hint to match
+     * @returns Array of loaded ContainerModules
+     */
+    loadByHint(hint: PreloadHint): Promise<Array<ContainerModule>>;
+    /**
+     * Check if a module is loaded.
+     *
+     * @param moduleName - Name of the module
+     * @returns True if the module is loaded
+     */
+    isLoaded(moduleName: string): boolean;
+    /**
+     * Get the load status of a module.
+     *
+     * @param moduleName - Name of the module
+     * @returns Module status or undefined if not registered
+     */
+    getStatus(moduleName: string): ModuleLoadStatus | undefined;
+    /**
+     * Get all registered lazy modules.
+     *
+     * @returns Array of all registered modules
+     */
+    getAll(): Array<ILazyModule>;
+    /**
+     * Get modules by status.
+     *
+     * @param status - Status to filter by
+     * @returns Array of modules with matching status
+     */
+    getByStatus(status: ModuleLoadStatus): Array<ILazyModule>;
+    /**
+     * Get modules by preload hint.
+     *
+     * @param hint - Preload hint to filter by
+     * @returns Array of modules with matching hint
+     */
+    getByHint(hint: PreloadHint): Array<ILazyModule>;
+    /**
+     * Get a module by name.
+     *
+     * @param name - Module name
+     * @returns The module or undefined
+     */
+    get(name: string): ILazyModule | undefined;
+    /**
+     * Topological sort of module names based on dependencies.
+     * @private
+     */
+    private topologicalSort;
+}
+/**
+ * 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 declare function createLazyModuleLoader(container?: Container): LazyModuleLoader;

package/lib/cjs/types/lazy-loading/lazy-module-manager.d.ts

@@ -0,0 +1,148 @@
+/**
+ * LazyModuleManager Implementation
+ *
+ * Runtime module management service for querying and controlling lazy modules.
+ *
+ * @module lazy-loading
+ */
+import { ILazyModuleManager, ModuleLoadStatistics, PreloadHint } from "./lazy.interfaces.js";
+import { LazyModuleLoader } from "./lazy-module-loader.js";
+/**
+ * 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
+ */
+export declare class LazyModuleManager implements ILazyModuleManager {
+    private readonly loader;
+    constructor(loader: LazyModuleLoader);
+    /**
+     * 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: string): boolean;
+    /**
+     * Get names of all loaded modules.
+     *
+     * @returns Array of loaded module names
+     *
+     * @example
+     * ```typescript
+     * const loaded = manager.getLoadedModules();
+     * // ["CoreModule", "AuthModule", "UserModule"]
+     * ```
+     */
+    getLoadedModules(): Array<string>;
+    /**
+     * Get names of all pending (unloaded) modules.
+     *
+     * @returns Array of pending module names
+     *
+     * @example
+     * ```typescript
+     * const pending = manager.getPendingModules();
+     * // ["AdminModule", "ReportsModule"]
+     * ```
+     */
+    getPendingModules(): Array<string>;
+    /**
+     * Get names of all modules that failed to load.
+     *
+     * @returns Array of failed module names
+     */
+    getFailedModules(): Array<string>;
+    /**
+     * Manually load a module.
+     *
+     * @param moduleName - Name of the module to load
+     *
+     * @example
+     * ```typescript
+     * // Preload module before it's needed
+     * await manager.load("AdminModule");
+     * ```
+     */
+    load(moduleName: string): Promise<void>;
+    /**
+     * 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");
+     * ```
+     */
+    loadByHint(hint: PreloadHint): Promise<void>;
+    /**
+     * 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(): ModuleLoadStatistics;
+    /**
+     * 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
+     */
+    unload(moduleName: string): Promise<boolean>;
+}
+/**
+ * Create a new LazyModuleManager instance.
+ *
+ * @param loader - The LazyModuleLoader to use
+ * @returns LazyModuleManager instance
+ *
+ * @public API
+ */
+export declare function createLazyModuleManager(loader: LazyModuleLoader): LazyModuleManager;

package/lib/cjs/types/lazy-loading/lazy-module-warmup.d.ts

@@ -0,0 +1,130 @@
+/**
+ * LazyModuleWarmup Implementation
+ *
+ * Service for warming up lazy modules in the background during idle time.
+ *
+ * @module lazy-loading
+ */
+import { ILazyModuleWarmup, WarmupConfig } from "./lazy.interfaces.js";
+import { LazyModuleLoader } from "./lazy-module-loader.js";
+/**
+ * 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
+ */
+export declare class LazyModuleWarmup implements ILazyModuleWarmup {
+    private readonly loader;
+    private running;
+    private warmedModules;
+    private totalToWarm;
+    private stopRequested;
+    private warmupTimer;
+    constructor(loader: LazyModuleLoader);
+    /**
+     * 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
+     * });
+     * ```
+     */
+    start(config?: Partial<WarmupConfig>): Promise<void>;
+    /**
+     * Stop the warmup process.
+     *
+     * @example
+     * ```typescript
+     * warmup.stop();
+     * console.log("Warmup stopped");
+     * ```
+     */
+    stop(): void;
+    /**
+     * Check if warmup is in progress.
+     *
+     * @returns True if warmup is running
+     */
+    isRunning(): boolean;
+    /**
+     * Get warmup progress (0-100).
+     *
+     * @returns Progress percentage
+     */
+    getProgress(): number;
+    /**
+     * Get list of modules that have been warmed up.
+     *
+     * @returns Array of warmed module names
+     */
+    getWarmedModules(): Array<string>;
+    /**
+     * Get modules to warm up based on configuration.
+     * @private
+     */
+    private getModulesToWarm;
+    /**
+     * Warm up modules with concurrency control.
+     * @private
+     */
+    private warmModules;
+    /**
+     * Split array into chunks.
+     * @private
+     */
+    private chunk;
+    /**
+     * Delay helper.
+     * @private
+     */
+    private delay;
+}
+/**
+ * Create a new LazyModuleWarmup instance.
+ *
+ * @param loader - The LazyModuleLoader to use
+ * @returns LazyModuleWarmup instance
+ *
+ * @public API
+ */
+export declare function createLazyModuleWarmup(loader: LazyModuleLoader): LazyModuleWarmup;