@expressots/core 3.0.0 → 4.0.0-preview.3

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

@@ -0,0 +1,352 @@
+/**
+ * LazyModule Implementation
+ *
+ * Provides the core LazyModule class and CreateLazyModule factory function.
+ *
+ * @module lazy-loading
+ */
+// ============================================================================
+// Lazy Module Metadata Key
+// ============================================================================
+/**
+ * Metadata key for lazy module configuration.
+ * @internal
+ */
+export const LAZY_MODULE_METADATA_KEY = Symbol.for("expressots:lazy-module");
+// ============================================================================
+// Lazy Module Implementation
+// ============================================================================
+/**
+ * A module that can be loaded on-demand.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept lazy-loading
+ *
+ * @example
+ * ```typescript
+ * // Create a lazy module with preload hint
+ * const AdminModule = CreateLazyModule(
+ *   [AdminController, AdminDashboardController],
+ *   { name: "AdminModule" }
+ * ).withPreloadHint("low");
+ *
+ * // The module won't load until first access to /admin/* routes
+ * ```
+ *
+ * @public API
+ */
+export class LazyModule {
+    _status = "pending";
+    _loadTime = null;
+    _error = null;
+    _module = null;
+    _loadPromise = null;
+    _config;
+    _name;
+    _factory;
+    constructor(factory, config = {}) {
+        this._factory = factory;
+        this._config = {
+            preloadHint: "low",
+            timeout: 30000,
+            ...config,
+        };
+        this._name =
+            config.name ||
+                `LazyModule_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+    }
+    // ============================================================================
+    // Public Properties
+    // ============================================================================
+    get name() {
+        return this._name;
+    }
+    get config() {
+        return { ...this._config };
+    }
+    get status() {
+        return this._status;
+    }
+    get isLoaded() {
+        return this._status === "loaded";
+    }
+    get loadTime() {
+        return this._loadTime;
+    }
+    get error() {
+        return this._error;
+    }
+    get module() {
+        return this._module;
+    }
+    get factory() {
+        return this._factory;
+    }
+    // ============================================================================
+    // Public Methods
+    // ============================================================================
+    /**
+     * Load the module. Idempotent - safe to call multiple times.
+     *
+     * @returns The loaded ContainerModule
+     * @throws Error if loading fails
+     */
+    async load() {
+        // Already loaded
+        if (this._module) {
+            return this._module;
+        }
+        // Loading in progress - return existing promise
+        if (this._loadPromise) {
+            return this._loadPromise;
+        }
+        // Start loading
+        this._status = "loading";
+        const startTime = performance.now();
+        this._loadPromise = this._loadWithTimeout()
+            .then((module) => {
+            this._module = module;
+            this._status = "loaded";
+            this._loadTime = Math.round(performance.now() - startTime);
+            this._loadPromise = null;
+            return module;
+        })
+            .catch((error) => {
+            this._status = "failed";
+            this._error = error instanceof Error ? error : new Error(String(error));
+            this._loadTime = Math.round(performance.now() - startTime);
+            this._loadPromise = null;
+            throw this._error;
+        });
+        return this._loadPromise;
+    }
+    /**
+     * Configure preload hint with fluent API.
+     */
+    withPreloadHint(hint) {
+        this._config.preloadHint = hint;
+        return this;
+    }
+    /**
+     * Configure lazy loading options with fluent API.
+     */
+    withLazyConfig(config) {
+        Object.assign(this._config, config);
+        return this;
+    }
+    // ============================================================================
+    // Private Methods
+    // ============================================================================
+    /**
+     * Load module with timeout.
+     * @private
+     */
+    async _loadWithTimeout() {
+        const timeout = this._config.timeout || 30000;
+        return new Promise((resolve, reject) => {
+            let completed = false;
+            // Set up timeout
+            const timeoutId = setTimeout(() => {
+                if (!completed) {
+                    completed = true;
+                    reject(new Error(`Module '${this._name}' load timeout after ${timeout}ms`));
+                }
+            }, timeout);
+            // Execute factory
+            try {
+                const result = this._factory();
+                Promise.resolve(result)
+                    .then((module) => {
+                    if (!completed) {
+                        completed = true;
+                        clearTimeout(timeoutId);
+                        resolve(module);
+                    }
+                })
+                    .catch((error) => {
+                    if (!completed) {
+                        completed = true;
+                        clearTimeout(timeoutId);
+                        reject(error);
+                    }
+                });
+            }
+            catch (error) {
+                // Handle synchronous factory errors
+                if (!completed) {
+                    completed = true;
+                    clearTimeout(timeoutId);
+                    reject(error);
+                }
+            }
+        });
+    }
+}
+// ============================================================================
+// Factory Functions
+// ============================================================================
+/**
+ * Metadata key for controller routes (must match adapter-express).
+ * @internal
+ */
+const CONTROLLER_METADATA_KEY = "inversify-express-utils:controller";
+/**
+ * Extract route prefixes from controller classes.
+ *
+ * @param controllers - Controller classes to analyze
+ * @returns Array of unique route prefixes
+ *
+ * @internal
+ */
+function extractControllerPaths(controllers) {
+    const paths = [];
+    for (const controller of controllers) {
+        try {
+            // Get controller metadata from @controller decorator
+            const metadata = Reflect.getMetadata(CONTROLLER_METADATA_KEY, controller);
+            if (metadata && typeof metadata === "object" && "path" in metadata) {
+                const path = metadata.path;
+                if (path && typeof path === "string") {
+                    // Normalize path
+                    const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+                    paths.push(normalizedPath);
+                }
+            }
+        }
+        catch {
+            // Controller doesn't have metadata - skip
+        }
+    }
+    // Return unique, sorted paths
+    return [...new Set(paths)].sort();
+}
+/**
+ * Create a lazy module from controllers.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept lazy-loading
+ *
+ * UNIQUE: Zero-configuration lazy loading with automatic route detection!
+ * Just wrap your controllers and routes are auto-discovered from @controller() decorators.
+ *
+ * @example
+ * ```typescript
+ * // Zero-config! Routes auto-detected from @controller("/admin")
+ * export const AdminModule = CreateLazyModule([
+ *   AdminController,        // @controller("/admin")
+ *   AdminDashboardController // @controller("/admin/dashboard")
+ * ]);
+ * // Auto-detected routes: ["/admin", "/admin/dashboard"]
+ *
+ * // With explicit name
+ * export const ReportsModule = CreateLazyModule(
+ *   [ReportsController],    // @controller("/reports")
+ *   { name: "ReportsModule" }
+ * ).withPreloadHint("low");
+ *
+ * // With prefetch hints
+ * export const AnalyticsModule = CreateLazyModule(
+ *   [AnalyticsController],
+ *   { name: "AnalyticsModule" }
+ * ).withLazyConfig({
+ *   preloadHint: "medium",
+ *   prefetchAfterIdle: 5000
+ * });
+ * ```
+ *
+ * @param controllers - Controller classes to include in the module
+ * @param config - Optional configuration
+ * @returns LazyModule instance
+ *
+ * @public API
+ */
+export function CreateLazyModule(controllers, config = {}) {
+    // Auto-detect route prefixes from @controller() decorators
+    const detectedPaths = extractControllerPaths(controllers);
+    // Merge with any explicit routePrefixes
+    const allPrefixes = [...(config.routePrefixes || []), ...detectedPaths];
+    const uniquePrefixes = [...new Set(allPrefixes)];
+    // Create config with auto-detected prefixes
+    const enhancedConfig = {
+        ...config,
+        routePrefixes: uniquePrefixes.length > 0 ? uniquePrefixes : undefined,
+    };
+    // Import CreateModule dynamically to avoid circular dependencies.
+    // `await import` works identically in both CJS and ESM compiled output
+    // and the factory type already accepts Promise<ContainerModule>.
+    const factory = async () => {
+        const { CreateModule } = await import("../container-module/container-module.js");
+        return CreateModule(controllers);
+    };
+    return new LazyModule(factory, enhancedConfig);
+}
+/**
+ * Create a lazy module from a ContainerModule factory.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept lazy-loading
+ *
+ * @example
+ * ```typescript
+ * // Lazy load with custom bindings
+ * export const CustomModule = createLazyModule(
+ *   () => new ContainerModule((bind) => {
+ *     bind<ICache>("ICache").to(RedisCache);
+ *     bind<ILogger>("ILogger").to(FileLogger);
+ *   }),
+ *   { name: "CustomModule" }
+ * );
+ *
+ * // Async factory (e.g., dynamic import)
+ * export const DynamicModule = createLazyModule(
+ *   async () => {
+ *     const { module } = await import("./heavy-module");
+ *     return module;
+ *   },
+ *   { name: "DynamicModule" }
+ * );
+ * ```
+ *
+ * @param factory - Factory function that creates the ContainerModule
+ * @param config - Optional configuration
+ * @returns LazyModule instance
+ *
+ * @public API
+ */
+export function createLazyModule(factory, config = {}) {
+    return new LazyModule(factory, config);
+}
+/**
+ * Check if a value is a LazyModule.
+ *
+ * @param value - Value to check
+ * @returns True if value is a LazyModule
+ *
+ * @public API
+ */
+export function isLazyModule(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        "load" in value &&
+        "withPreloadHint" in value &&
+        "status" in value &&
+        "isLoaded" in value);
+}
+/**
+ * Get module name from a module (lazy or regular).
+ *
+ * @param module - Module to get name from
+ * @returns Module name or undefined
+ *
+ * @internal
+ */
+export function getModuleName(module) {
+    if (isLazyModule(module)) {
+        return module.name;
+    }
+    // Regular ContainerModule doesn't have a name
+    return undefined;
+}

package/lib/esm/lazy-loading/lazy.interfaces.js

@@ -0,0 +1,17 @@
+/**
+ * Lazy-Loading Module - Core Interfaces and Types
+ *
+ * @module lazy-loading
+ *
+ * Type-safe lazy module loading with auto-detection, preloading hints,
+ * usage analytics, and runtime module management.
+ *
+ * Features:
+ * - On-demand module loading for improved startup time
+ * - Preload hints (high, medium, low, never)
+ * - Usage analytics and recommendations
+ * - Progressive loading with phases
+ * - Runtime module status queries
+ * - Background warmup during idle time
+ */
+export {};

package/lib/esm/lifecycle/index.js

@@ -0,0 +1,9 @@
+/**
+ * Lifecycle Module for ExpressoTS
+ *
+ * Provides auto-discovery lifecycle hooks for providers.
+ *
+ * @module lifecycle
+ */
+export { isBootstrap, isShutdown, } from "./lifecycle.interface.js";
+export { LifecycleRegistry } from "./lifecycle-registry.js";

package/lib/esm/lifecycle/lifecycle-registry.js

@@ -0,0 +1,298 @@
+/**
+ * Lifecycle Registry for ExpressoTS
+ *
+ * Discovers and manages providers implementing lifecycle interfaces.
+ * Similar to ExceptionFilterRegistry and GuardRegistry.
+ *
+ * @module lifecycle
+ */
+import { METADATA_KEY } from "../di/binding-decorator/constants.js";
+import { isBootstrap, isShutdown, } from "./lifecycle.interface.js";
+import { Logger } from "../provider/logger/logger.provider.js";
+/**
+ * Registry for discovering and executing lifecycle hooks on providers.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept lifecycle-registry
+ * @difficulty intermediate
+ *
+ * @summary Quick Start
+ * Automatically discovers and executes lifecycle hooks on providers.
+ *
+ * @example
+ * ```typescript
+ * const registry = new LifecycleRegistry(container);
+ * registry.discover();
+ * await registry.executeBootstrap();
+ * // ... later on shutdown
+ * await registry.executeShutdown('SIGTERM');
+ * ```
+ *
+ * **Auto-Discovery**
+ * The registry automatically discovers providers implementing `IBootstrap` and `IShutdown`
+ * interfaces via the `@provide()` decorator metadata. No manual registration required.
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
+ * **Internal Architecture**
+ *
+ * LifecycleRegistry:
+ * - Scans `@provide()` metadata for lifecycle interfaces
+ * - Stores providers in Sets for O(1) lookup
+ * - Executes hooks in parallel for performance
+ * - Handles errors gracefully (especially during shutdown)
+ *
+ * **Discovery Process**
+ * 1. Scan Reflect metadata for `@provide()` decorators
+ * 2. Check if provider implements `IBootstrap` or `IShutdown`
+ * 3. Store in appropriate Set
+ * 4. Execute hooks when requested
+ *
+ * **Design Decisions**
+ * - Auto-discovery reduces boilerplate
+ * - Parallel execution for performance
+ * - Error tolerance during shutdown
+ * - Singleton scope requirement enforced
+ *
+ * @see {@link IBootstrap} for bootstrap hooks
+ * @see {@link IShutdown} for shutdown hooks
+ *
+ * @layer advanced
+ * @audience power-users
+ *
+ * **Advanced Usage**
+ *
+ * Manual discovery and execution:
+ * ```typescript
+ * const registry = new LifecycleRegistry(container);
+ * registry.discover();
+ *
+ * // Check counts
+ * console.log(`Bootstrap providers: ${registry.getBootstrapCount()}`);
+ * console.log(`Shutdown providers: ${registry.getShutdownCount()}`);
+ *
+ * // Execute bootstrap
+ * await registry.executeBootstrap();
+ * ```
+ *
+ * @public API
+ */
+export class LifecycleRegistry {
+    logger = new Logger();
+    container;
+    bootstrapProviders = new Set();
+    shutdownProviders = new Set();
+    discovered = false;
+    /**
+     * Creates a new LifecycleRegistry instance.
+     *
+     * @param container - The InversifyJS container to discover providers from
+     */
+    constructor(container) {
+        this.container = container;
+    }
+    /**
+     * Discovers all providers implementing lifecycle interfaces.
+     *
+     * @layer public
+     * @audience application-developers
+     * @concept lifecycle-discovery
+     * @difficulty beginner
+     *
+     * Scans all `@provide()` decorated classes and checks if they implement
+     * `IBootstrap` or `IShutdown` interfaces.
+     *
+     * **Discovery Process**
+     * - Scans Reflect metadata for `@provide()` decorators
+     * - Checks prototype for `bootstrap()` or `shutdown()` methods
+     * - Stores providers in Sets for execution
+     * - Idempotent (safe to call multiple times)
+     *
+     * @layer internal
+     * @audience framework-developers
+     *
+     * **Internal Behavior**
+     * - Uses `METADATA_KEY.provide` to find all providers
+     * - Checks `target.prototype.bootstrap` and `target.prototype.shutdown`
+     * - Stores in Sets for O(1) lookup
+     * - Sets `discovered` flag to prevent re-discovery
+     *
+     * @public API
+     */
+    discover() {
+        if (this.discovered) {
+            return;
+        }
+        const provideMetadata = Reflect.getMetadata(METADATA_KEY.provide, Reflect) || [];
+        for (const metadata of provideMetadata) {
+            const target = metadata.implementationType;
+            if (!target || !target.prototype) {
+                continue;
+            }
+            // Check for IBootstrap implementation
+            if (typeof target.prototype.bootstrap === "function") {
+                this.bootstrapProviders.add(target);
+            }
+            // Check for IShutdown implementation
+            if (typeof target.prototype.shutdown === "function") {
+                this.shutdownProviders.add(target);
+            }
+        }
+        this.discovered = true;
+        // Note: Lifecycle discovery log is suppressed as this info is shown in the startup banner
+        // The banner displays "Lifecycle Hooks: ✅" when bootstrap/shutdown providers are detected
+    }
+    /**
+     * Executes all bootstrap lifecycle hooks.
+     *
+     * @layer public
+     * @audience application-developers
+     * @concept lifecycle-bootstrap-execution
+     * @difficulty beginner
+     *
+     * Called after the server is fully ready and listening.
+     * All bootstrap hooks are executed in parallel for performance.
+     *
+     * **Execution Behavior**
+     * - Executes all `IBootstrap.bootstrap()` methods in parallel
+     * - Waits for all hooks to complete before resolving
+     * - Throws error if any hook fails (fail-fast)
+     * - Gets instances from DI container
+     *
+     * @layer internal
+     * @audience framework-developers
+     *
+     * **Internal Behavior**
+     * - Gets provider instances from container
+     * - Validates with `isBootstrap()` type guard
+     * - Handles both sync and async hooks
+     * - Collects promises and waits with `Promise.all()`
+     * - Errors are logged and re-thrown
+     *
+     * @returns Promise that resolves when all bootstrap hooks complete
+     * @throws Error if any bootstrap hook fails
+     *
+     * @public API
+     */
+    async executeBootstrap() {
+        if (this.bootstrapProviders.size === 0) {
+            return;
+        }
+        const promises = [];
+        for (const Provider of this.bootstrapProviders) {
+            try {
+                // Get the instance from the container
+                const instance = this.container.get(Provider);
+                if (isBootstrap(instance)) {
+                    const result = instance.bootstrap();
+                    if (result instanceof Promise) {
+                        promises.push(result.catch((error) => {
+                            this.logger.error(`Bootstrap failed for ${Provider.name}: ${error.message}`, "lifecycle-registry");
+                            throw error;
+                        }));
+                    }
+                }
+            }
+            catch (error) {
+                this.logger.error(`Failed to execute bootstrap for ${Provider.name}: ${error.message}`, "lifecycle-registry");
+                throw error;
+            }
+        }
+        await Promise.all(promises);
+    }
+    /**
+     * Executes all shutdown lifecycle hooks.
+     *
+     * @layer public
+     * @audience application-developers
+     * @concept lifecycle-shutdown-execution
+     * @difficulty beginner
+     *
+     * Called when the application is shutting down.
+     * All shutdown hooks are executed in parallel.
+     * Errors are logged but don't prevent other hooks from executing.
+     *
+     * **Execution Behavior**
+     * - Executes all `IShutdown.shutdown()` methods in parallel
+     * - Passes shutdown signal to each hook
+     * - Errors are logged but don't stop execution (error-tolerant)
+     * - Waits for all hooks to complete
+     *
+     * @layer internal
+     * @audience framework-developers
+     *
+     * **Internal Behavior**
+     * - Gets provider instances from container
+     * - Validates with `isShutdown()` type guard
+     * - Handles both sync and async hooks
+     * - Errors are caught and logged, but not re-thrown
+     * - Uses `Promise.all()` to wait for completion
+     *
+     * **Design Decision: Error Tolerance**
+     * Unlike bootstrap hooks, shutdown hooks don't fail-fast. This ensures
+     * all cleanup operations have a chance to run, even if one fails.
+     *
+     * @param signal - The signal that triggered the shutdown (SIGTERM, SIGINT, etc.)
+     * @returns Promise that resolves when all shutdown hooks complete
+     *
+     * @public API
+     */
+    async executeShutdown(signal) {
+        if (this.shutdownProviders.size === 0) {
+            return;
+        }
+        const promises = [];
+        for (const Provider of this.shutdownProviders) {
+            try {
+                // Get the instance from the container
+                const instance = this.container.get(Provider);
+                if (isShutdown(instance)) {
+                    const result = instance.shutdown(signal);
+                    if (result instanceof Promise) {
+                        promises.push(result.catch((error) => {
+                            // Log error but don't throw - we want all shutdown hooks to run
+                            this.logger.error(`Shutdown failed for ${Provider.name}: ${error.message}`, "lifecycle-registry");
+                        }));
+                    }
+                }
+            }
+            catch (error) {
+                // Log error but continue with other providers
+                this.logger.error(`Failed to execute shutdown for ${Provider.name}: ${error.message}`, "lifecycle-registry");
+            }
+        }
+        // Wait for all shutdown hooks to complete
+        await Promise.all(promises);
+    }
+    /**
+     * Gets the count of discovered bootstrap providers.
+     *
+     * @returns Number of providers implementing IBootstrap
+     * @public API
+     */
+    getBootstrapCount() {
+        return this.bootstrapProviders.size;
+    }
+    /**
+     * Gets the count of discovered shutdown providers.
+     *
+     * @returns Number of providers implementing IShutdown
+     * @public API
+     */
+    getShutdownCount() {
+        return this.shutdownProviders.size;
+    }
+    /**
+     * Clears all discovered providers.
+     * Useful for testing.
+     *
+     * @internal
+     */
+    clear() {
+        this.bootstrapProviders.clear();
+        this.shutdownProviders.clear();
+        this.discovered = false;
+    }
+}

package/lib/esm/lifecycle/lifecycle.interface.js

@@ -0,0 +1,33 @@
+/**
+ * Lifecycle Interfaces for ExpressoTS
+ *
+ * These interfaces enable auto-discovery of provider lifecycle hooks.
+ * Providers implementing these interfaces will automatically have their
+ * lifecycle methods called at the appropriate times by the framework.
+ *
+ * @module lifecycle
+ */
+/**
+ * Type guard to check if an object implements IBootstrap
+ * @param obj - The object to check
+ * @returns true if the object implements IBootstrap
+ * @internal
+ */
+export function isBootstrap(obj) {
+    return (obj !== null &&
+        typeof obj === "object" &&
+        "bootstrap" in obj &&
+        typeof obj.bootstrap === "function");
+}
+/**
+ * Type guard to check if an object implements IShutdown
+ * @param obj - The object to check
+ * @returns true if the object implements IShutdown
+ * @internal
+ */
+export function isShutdown(obj) {
+    return (obj !== null &&
+        typeof obj === "object" &&
+        "shutdown" in obj &&
+        typeof obj.shutdown === "function");
+}