@expressots/core 3.0.0-beta.4 → 4.0.0-preview.1

package/lib/esm/provider/logger/utils/log-levels.js

@@ -0,0 +1,100 @@
+/**
+ * Log levels enum with numeric values for comparison.
+ * Lower values = more verbose, higher values = less verbose.
+ * @public API
+ */
+export var LogLevel;
+(function (LogLevel) {
+    /** Ultra-detailed diagnostic information (function entry/exit) */
+    LogLevel[LogLevel["TRACE"] = 0] = "TRACE";
+    /** Detailed diagnostic information for debugging */
+    LogLevel[LogLevel["DEBUG"] = 1] = "DEBUG";
+    /** General informational messages */
+    LogLevel[LogLevel["INFO"] = 2] = "INFO";
+    /** Warning messages for potentially harmful situations */
+    LogLevel[LogLevel["WARN"] = 3] = "WARN";
+    /** Error messages for error events */
+    LogLevel[LogLevel["ERROR"] = 4] = "ERROR";
+    /** Fatal errors that cause the application to abort */
+    LogLevel[LogLevel["FATAL"] = 5] = "FATAL";
+    /** No logging */
+    LogLevel[LogLevel["SILENT"] = 6] = "SILENT";
+})(LogLevel || (LogLevel = {}));
+/**
+ * Legacy log level for backward compatibility.
+ * Maps to INFO level.
+ */
+export const LEGACY_LOG_LEVEL_NONE = "NONE";
+/**
+ * Convert string log level to enum.
+ * @param level - String log level
+ * @returns LogLevel enum value
+ * @public API
+ */
+export function parseLogLevel(level) {
+    if (typeof level === "number") {
+        return level;
+    }
+    const upperLevel = level.toUpperCase();
+    // Handle legacy "NONE" level
+    if (upperLevel === "NONE") {
+        return LogLevel.INFO;
+    }
+    switch (upperLevel) {
+        case "TRACE":
+            return LogLevel.TRACE;
+        case "DEBUG":
+            return LogLevel.DEBUG;
+        case "INFO":
+            return LogLevel.INFO;
+        case "WARN":
+            return LogLevel.WARN;
+        case "ERROR":
+            return LogLevel.ERROR;
+        case "FATAL":
+            return LogLevel.FATAL;
+        case "SILENT":
+            return LogLevel.SILENT;
+        default:
+            return LogLevel.INFO;
+    }
+}
+/**
+ * Get string representation of log level.
+ * @param level - LogLevel enum value
+ * @returns String representation
+ * @public API
+ */
+export function logLevelToString(level) {
+    switch (level) {
+        case LogLevel.TRACE:
+            return "TRACE";
+        case LogLevel.DEBUG:
+            return "DEBUG";
+        case LogLevel.INFO:
+            return "INFO";
+        case LogLevel.WARN:
+            return "WARN";
+        case LogLevel.ERROR:
+            return "ERROR";
+        case LogLevel.FATAL:
+            return "FATAL";
+        case LogLevel.SILENT:
+            return "SILENT";
+        default:
+            return "INFO";
+    }
+}
+/**
+ * Check if a log level should be logged based on configured level.
+ * @param messageLevel - The level of the message to log
+ * @param configuredLevel - The configured minimum log level
+ * @returns True if message should be logged
+ * @public API
+ */
+export function shouldLog(messageLevel, configuredLevel) {
+    if (configuredLevel === LogLevel.SILENT) {
+        return false;
+    }
+    return messageLevel >= configuredLevel;
+}

package/lib/esm/provider/provider-manager.js

@@ -0,0 +1,283 @@
+import { Scope } from "../di/inversify.js";
+import { Logger } from "./logger/logger.provider.js";
+import { ProviderRegistry } from "./provider-registry.js";
+/**
+ * Provider manager for dependency injection providers.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept provider-management
+ * @difficulty beginner
+ *
+ * @summary Quick Start
+ * Manage dependency injection providers with introspection, health checks, and metrics.
+ *
+ * @example
+ * ```typescript
+ * const manager = new ProviderManager(container);
+ *
+ * // Register a provider
+ * manager.register(MyProvider, Scope.Singleton);
+ *
+ * // Discover all providers
+ * manager.discover();
+ *
+ * // Get provider
+ * const provider = manager.get(MyProvider);
+ * ```
+ *
+ * **Features:**
+ * - Provider registration with scopes
+ * - Auto-discovery of providers
+ * - Health checks and metrics collection
+ * - Provider introspection
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
+ * **Internal Architecture**
+ *
+ * ProviderManager:
+ * - Wraps InversifyJS container
+ * - Delegates to ProviderRegistry for discovery
+ * - Provides high-level API for provider management
+ *
+ * **Design Decisions**
+ * - Thin wrapper around container and registry
+ * - Backward compatible with existing code
+ * - Enhanced with introspection capabilities
+ *
+ * @see {@link ProviderRegistry} for provider discovery
+ * @see {@link IProvider} for provider interface
+ *
+ * @public API
+ */
+export class ProviderManager {
+    container;
+    logger = new Logger();
+    registry;
+    constructor(container) {
+        this.container = container;
+        this.registry = new ProviderRegistry(container);
+    }
+    /**
+     * Discover all providers in the container.
+     * Call this after the container is fully initialized.
+     * @public API
+     */
+    discover() {
+        this.registry.discover();
+    }
+    /**
+     * Get the provider registry instance.
+     * @returns The provider registry
+     * @public API
+     */
+    getRegistry() {
+        return this.registry;
+    }
+    /**
+     * Register a provider with the container.
+     * @public API
+     */
+    register(serviceIdentifier, constructorOrScope, scope = Scope.Request) {
+        if (this.container.isBound(serviceIdentifier)) {
+            this.logger.warn(`${serviceIdentifier.name} already registered`, "provider-manager");
+            return;
+        }
+        let binding;
+        if (typeof constructorOrScope === "function") {
+            // Overload where constructor is provided
+            const constructor = constructorOrScope;
+            const scopeDefinition = scope || Scope.Transient;
+            binding = this.container.bind(serviceIdentifier).to(constructor);
+            this.applyScope(binding, scopeDefinition);
+        }
+        else {
+            const scopeDefinition = constructorOrScope || Scope.Transient;
+            binding = this.container.bind(serviceIdentifier).toSelf();
+            this.applyScope(binding, scopeDefinition);
+        }
+    }
+    /**
+     * Get a provider from the container.
+     * @param serviceIdentifier - The service identifier to get from the container.
+     * @returns An instance of the provider.
+     * @public API
+     */
+    get(serviceIdentifier) {
+        if (!this.container.isBound(serviceIdentifier)) {
+            this.logger.error(`${this.getServiceIdentifierName(serviceIdentifier)} not registered`, "ProviderManager");
+            throw new Error(`Provider ${this.getServiceIdentifierName(serviceIdentifier)} not registered`);
+        }
+        return this.container.get(serviceIdentifier);
+    }
+    /**
+     * Apply the scope to the binding.
+     * @param binding - The binding to apply the scope to.
+     * @param scope - The scope to apply (built-in or custom scope name).
+     * @private
+     */
+    applyScope(binding, scope) {
+        // Handle built-in scopes
+        switch (scope) {
+            case Scope.Singleton:
+                binding.inSingletonScope();
+                return;
+            case Scope.Request:
+                binding.inRequestScope();
+                return;
+            case Scope.Transient:
+                binding.inTransientScope();
+                return;
+        }
+        // Handle custom scopes (any string that's not a built-in scope)
+        if (typeof scope === "string" &&
+            scope !== Scope.Singleton &&
+            scope !== Scope.Request &&
+            scope !== Scope.Transient) {
+            binding.inScope(scope);
+        }
+        else {
+            // Default to transient if scope is invalid
+            binding.inTransientScope();
+        }
+    }
+    /**
+     * Get the name of the service identifier for logging purposes.
+     * @param serviceIdentifier - The service identifier.
+     * @returns The name of the service identifier.
+     * @private
+     */
+    getServiceIdentifierName(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    serviceIdentifier) {
+        if (typeof serviceIdentifier === "function") {
+            return serviceIdentifier.name;
+        }
+        else if (typeof serviceIdentifier === "symbol") {
+            return serviceIdentifier.toString();
+        }
+        else {
+            return serviceIdentifier;
+        }
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // INTROSPECTION METHODS
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Get all registered providers with metadata.
+     * @returns Array of provider information
+     * @public API
+     */
+    getAll() {
+        return this.registry.getAll();
+    }
+    /**
+     * Get providers by scope.
+     * @param scope - The scope to filter by
+     * @returns Array of providers with the specified scope
+     * @public API
+     */
+    getByScope(scope) {
+        return this.registry.getByScope(scope);
+    }
+    /**
+     * Get providers with a specific capability.
+     * @param capability - The capability to filter by
+     * @returns Array of providers with the capability
+     * @public API
+     */
+    getWithCapability(capability) {
+        return this.registry.getWithCapability(capability);
+    }
+    /**
+     * Get total provider count.
+     * @returns Number of registered providers
+     * @public API
+     */
+    getCount() {
+        return this.registry.getCount();
+    }
+    /**
+     * Check if a provider is registered.
+     * @param serviceIdentifier - The service identifier to check
+     * @returns true if registered
+     * @public API
+     */
+    has(serviceIdentifier) {
+        return this.container.isBound(serviceIdentifier);
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // HEALTH & METRICS
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Run health checks on all IHealthCheck providers.
+     * @returns Health dashboard with all results
+     * @public API
+     */
+    async checkHealth() {
+        return this.registry.checkHealth();
+    }
+    /**
+     * Collect metrics from all IMetrics providers.
+     * @returns Metrics dashboard with all metrics
+     * @public API
+     */
+    collectMetrics() {
+        return this.registry.collectMetrics();
+    }
+    /**
+     * Get providers that have lifecycle hooks (bootstrap/shutdown).
+     * @returns Array of providers with lifecycle hooks
+     * @public API
+     */
+    getLifecycleProviders() {
+        return this.registry.getLifecycleProviders();
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // SOURCE-BASED METHODS
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Get providers by source type.
+     * @param source - The provider source to filter by
+     * @returns Array of providers with the specified source
+     * @public API
+     */
+    getBySource(source) {
+        return this.registry.getBySource(source);
+    }
+    /**
+     * Get all built-in providers (core framework providers).
+     * @returns Array of built-in providers
+     * @public API
+     */
+    getBuiltinProviders() {
+        return this.registry.getBuiltinProviders();
+    }
+    /**
+     * Get all user-defined providers (application providers).
+     * @returns Array of user providers
+     * @public API
+     */
+    getUserProviders() {
+        return this.registry.getUserProviders();
+    }
+    /**
+     * Get all external providers (third-party plugins).
+     * @returns Array of external providers
+     * @public API
+     */
+    getExternalProviders() {
+        return this.registry.getExternalProviders();
+    }
+    /**
+     * Get a formatted view for banner display.
+     * @param maxDisplay - Maximum number of providers to show
+     * @returns Formatted provider view with source breakdown
+     * @public API
+     */
+    getFormattedView(maxDisplay = 5) {
+        return this.registry.getFormattedView(maxDisplay);
+    }
+}