@expressots/core 3.0.0 → 4.0.0-preview.1

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

@@ -0,0 +1,380 @@
+"use strict";
+/**
+ * LazyModule Implementation
+ *
+ * Provides the core LazyModule class and CreateLazyModule factory function.
+ *
+ * @module lazy-loading
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LazyModule = exports.LAZY_MODULE_METADATA_KEY = void 0;
+exports.CreateLazyModule = CreateLazyModule;
+exports.createLazyModule = createLazyModule;
+exports.isLazyModule = isLazyModule;
+exports.getModuleName = getModuleName;
+// ============================================================================
+// Lazy Module Metadata Key
+// ============================================================================
+/**
+ * Metadata key for lazy module configuration.
+ * @internal
+ */
+exports.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
+ */
+class LazyModule {
+    constructor(factory, config = {}) {
+        this._status = "pending";
+        this._loadTime = null;
+        this._error = null;
+        this._module = null;
+        this._loadPromise = null;
+        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);
+                }
+            }
+        });
+    }
+}
+exports.LazyModule = LazyModule;
+// ============================================================================
+// 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
+ */
+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 Promise.resolve().then(() => __importStar(require("../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
+ */
+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
+ */
+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
+ */
+function getModuleName(module) {
+    if (isLazyModule(module)) {
+        return module.name;
+    }
+    // Regular ContainerModule doesn't have a name
+    return undefined;
+}

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

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/cjs/lifecycle/index.js

@@ -0,0 +1,15 @@
+"use strict";
+/**
+ * Lifecycle Module for ExpressoTS
+ *
+ * Provides auto-discovery lifecycle hooks for providers.
+ *
+ * @module lifecycle
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LifecycleRegistry = exports.isShutdown = exports.isBootstrap = void 0;
+var lifecycle_interface_js_1 = require("./lifecycle.interface.js");
+Object.defineProperty(exports, "isBootstrap", { enumerable: true, get: function () { return lifecycle_interface_js_1.isBootstrap; } });
+Object.defineProperty(exports, "isShutdown", { enumerable: true, get: function () { return lifecycle_interface_js_1.isShutdown; } });
+var lifecycle_registry_js_1 = require("./lifecycle-registry.js");
+Object.defineProperty(exports, "LifecycleRegistry", { enumerable: true, get: function () { return lifecycle_registry_js_1.LifecycleRegistry; } });