@goatlab/node-backend 0.0.15 → 0.1.0

package/dist/container/Container.js

@@ -0,0 +1,895 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Container = void 0;
+const async_hooks_1 = require("async_hooks");
+const LruCache_1 = require("./LruCache");
+/**
+ * Smart instantiation helper that tries constructor first, then function
+ * This allows the container to work with both classes and factory functions
+ * without requiring the developer to specify which type they're using.
+ */
+function instantiate(factory, params) {
+    try {
+        // Try as class constructor first
+        return new factory(...params);
+    }
+    catch {
+        // Fall back to factory function
+        return factory(...params);
+    }
+}
+/**
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * 🏗️ MULTI-TENANT DEPENDENCY INJECTION CONTAINER
+ * ═══════════════════════════════════════════════════════════════════════════════
+ *
+ * This Container provides a   dependency injection system designed
+ * for multi-tenant applications. Each tenant gets their own isolated service
+ * instances while sharing the same factory definitions.
+ *
+ * Key Features:
+ * • 🔄 Tenant-isolated service instances using AsyncLocalStorage
+ * • ⚡ High-performance caching with LRU eviction
+ * • 🪞 Intelligent proxy system for lazy loading and error handling
+ * • 📊 Built-in performance metrics and debugging tools
+ * • 🛡️ Type-safe service resolution with full TypeScript support
+ * • 🔧 Support for both class constructors and factory functions
+ *
+ * Architecture Overview:
+ * ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+ * │   Factories     │ -> │   Container     │ -> │   Instances     │
+ * │ (Shared Defs)   │    │ (Per-tenant)    │    │ (Per-tenant)    │
+ * └─────────────────┘    └─────────────────┘    └─────────────────┘
+ *
+ * Flow:
+ * 1. Define factories once (shared across all tenants)
+ * 2. Bootstrap container with tenant metadata
+ * 3. Services are lazy-loaded and cached per tenant
+ * 4. AsyncLocalStorage provides automatic context isolation
+ * ═══════════════════════════════════════════════════════════════════════════════
+ */
+// ═══════════════════════════════════════════════════════════════════════════════
+// 🏛️ MAIN CONTAINER CLASS
+// ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * 🏗️ Multi-Tenant Dependency Injection Container
+ *
+ * The Container is the heart of the multi-tenant service architecture. It manages
+ * service instantiation, caching, and tenant isolation using AsyncLocalStorage.
+ *
+ * @template Defs - Factory definitions record (shared across tenants)
+ * @template TenantMetadata - Type of tenant-specific metadata (DB config, secrets, etc.)
+ *
+ * Key Responsibilities:
+ * 1. 🏭 **Factory Management**: Register and cache service factories
+ * 2. 🔄 **Tenant Isolation**: Each tenant gets isolated service instances
+ * 3. ⚡ **Performance**: Multi-level caching for optimal performance
+ * 4. 🪞 **Lazy Loading**: Services instantiated only when accessed
+ * 5. 🛡️ **Error Handling**: Clear error messages for missing services
+ * 6. 📊 **Observability**: Performance metrics and debugging tools
+ *
+ * Usage Pattern:
+ * ```typescript
+ * // 1. Define your services
+ * const factories = {
+ *   database: DatabaseService,
+ *   api: {
+ *     users: UserApiService,
+ *     auth: AuthApiService
+ *   }
+ * }
+ *
+ * // 2. Create container with initializer
+ * const container = new Container(factories, async (preload, meta) => {
+ *   const db = preload.database('main', meta.connectionString)
+ *   return {
+ *     database: db,
+ *     api: {
+ *       users: preload.api.users('users', db),
+ *       auth: preload.api.auth('auth', db, meta.jwtSecret)
+ *     }
+ *   }
+ * })
+ *
+ * // 3. Bootstrap for a tenant and run code
+ * await container.bootstrap(tenantMeta, async () => {
+ *   const { database, api } = container.context
+ *   const users = await api.users.getAll()
+ *   return users
+ * })
+ * ```
+ */
+class Container {
+    factories;
+    initializer;
+    // ═══════════════════════════════════════════════════════════════════════════
+    // 💾 CORE STORAGE SYSTEMS
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Service instance cache managers - one per service type
+     * Each manager handles LRU caching for that specific service
+     */
+    managers;
+    /**
+     * AsyncLocalStorage provides automatic tenant context isolation
+     * Each async call tree gets its own isolated service instances
+     * Also stores tenant metadata for introspection
+     */
+    als = new async_hooks_1.AsyncLocalStorage();
+    /**
+     * Pre-resolved factory lookup cache for performance
+     * Avoids recursive object traversal on every service access
+     */
+    factoryCache = new Map();
+    /**
+     * Cached preload proxy to avoid recreating the same proxy structure
+     */
+    preloadProxy = null;
+    /**
+     * Container configuration with sensible defaults
+     */
+    options;
+    // ═══════════════════════════════════════════════════════════════════════════
+    // ⚡ PERFORMANCE OPTIMIZATION CACHES
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Path string cache: converts ['user', 'repo'] -> "user.repo"
+     * Avoids repeated string joining operations
+     */
+    pathCache = new Map();
+    /**
+     * Proxy object cache: reuses proxy objects for the same paths
+     * Reduces memory allocation and improves performance
+     */
+    proxyCache = new Map();
+    /**
+     * Context proxy cache: reuses proxies for the same object instances
+     * Uses WeakMap for automatic garbage collection when objects are freed
+     */
+    contextProxyCache = new WeakMap();
+    /**
+     * Initializer cache: stores initialized instances per tenant
+     * Avoids re-running the expensive initializer function for the same tenant
+     * Key is a serialized version of tenant metadata, value is the initialized instances
+     */
+    initializerCache = new Map();
+    // ═══════════════════════════════════════════════════════════════════════════
+    // 📊 PERFORMANCE METRICS
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Performance metrics for monitoring and optimization
+     * Only collected when enableMetrics is true
+     * Includes overflow protection for long-running services
+     */
+    metrics = {
+        cacheHits: 0, // How many times we found an instance in cache
+        cacheMisses: 0, // How many times we had to create a new instance
+        instanceCreations: 0, // Total number of service instances created
+        contextAccesses: 0, // How many times container.context was accessed
+        pathCacheHits: 0, // Path string cache effectiveness
+        proxyCacheHits: 0, // Proxy object cache effectiveness
+        initializerCacheHits: 0, // How many times we reused cached initializer results
+    };
+    /**
+     * Maximum safe value for metrics before overflow protection kicks in
+     * Set to 90% of MAX_SAFE_INTEGER to provide buffer
+     */
+    MAX_METRIC_VALUE = Math.floor(Number.MAX_SAFE_INTEGER * 0.9);
+    /**
+     * Safely increment a metric with overflow protection
+     * When approaching MAX_SAFE_INTEGER, resets all metrics to prevent overflow
+     */
+    safeIncrementMetric(metricName) {
+        if (!this.options.enableMetrics)
+            return;
+        const currentValue = this.metrics[metricName];
+        // Check if we're approaching the overflow threshold
+        if (currentValue >= this.MAX_METRIC_VALUE) {
+            // Reset all metrics to prevent overflow
+            this.resetMetrics();
+            // Log the reset for monitoring
+            if (this.options.enableDiagnostics) {
+                console.warn(`Container metrics reset due to overflow protection. Metric '${metricName}' reached ${currentValue}`);
+            }
+        }
+        this.metrics[metricName]++;
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // 🏗️ CONSTRUCTOR & INITIALIZATION
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Create a new Container instance
+     *
+     * @param factories - Service factory definitions (shared across all tenants)
+     * @param initializer - Function that creates tenant-specific service instances
+     * @param options - Configuration options for performance and debugging
+     *
+     * The initializer function receives:
+     * - preload: Proxy object for creating service instances with parameters
+     * - meta: Tenant-specific metadata (DB config, secrets, etc.)
+     *
+     * And should return a structure matching your factory definitions but with
+     * actual service instances instead of factory functions.
+     */
+    constructor(factories, initializer, options = {}) {
+        this.factories = factories;
+        this.initializer = initializer;
+        // Apply default options
+        this.options = {
+            cacheSize: 100,
+            enableMetrics: false,
+            enableDiagnostics: false,
+            enableDistributedInvalidation: false,
+            distributedInvalidator: undefined,
+            ...options,
+        };
+        // Initialize cache managers for each service
+        this.managers = this.createManagers(this.factories, this.options.cacheSize);
+        // Pre-cache factory lookups for better performance
+        this.preloadFactoryCache();
+        // Setup distributed cache invalidation if enabled
+        this.setupDistributedInvalidation();
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // 🏭 CACHE MANAGER SETUP
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Recursively create cache managers for all services in the factory tree
+     * Each service gets its own LRU cache with the configured size limit
+     */
+    createManagers(defs, cacheSize, path = []) {
+        const managers = {};
+        for (const [key, value] of Object.entries(defs)) {
+            const newPath = path.length === 0 ? [key] : [...path, key];
+            if (typeof value === 'function') {
+                // This is a factory function/constructor - create a cache for it
+                const flatKey = this.getOrCachePath(newPath);
+                managers[flatKey] = (0, LruCache_1.createServiceCache)(cacheSize);
+            }
+            else if (typeof value === 'object' && value !== null) {
+                // This is a nested object - recurse into it
+                const subManagers = this.createManagers(value, cacheSize, newPath);
+                Object.assign(managers, subManagers);
+            }
+        }
+        return managers;
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // ⚡ PERFORMANCE OPTIMIZATION HELPERS
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Efficiently cache path string conversions
+     * Converts ['user', 'service'] to "user.service" and caches the result
+     *
+     * Uses different separators for cache key vs final path to avoid conflicts
+     */
+    getOrCachePath(path) {
+        // Convert symbols to strings
+        const stringPath = path.map(p => typeof p === 'symbol' ? p.toString() : p);
+        const pathKey = stringPath.join('|'); // Cache key uses pipe separator
+        let cached = this.pathCache.get(pathKey);
+        if (!cached) {
+            cached = stringPath.join('.'); // Final path uses dot separator
+            this.pathCache.set(pathKey, cached);
+        }
+        else {
+            this.safeIncrementMetric('pathCacheHits');
+        }
+        return cached;
+    }
+    /**
+     * Pre-populate the factory cache by walking the entire factory tree
+     * This eliminates the need for recursive object traversal during runtime
+     */
+    preloadFactoryCache() {
+        this.walkFactories(this.factories, []);
+    }
+    /**
+     * Recursive factory tree walker that builds the flat factory cache
+     * Converts nested object structure to flat dot-notation keys
+     */
+    walkFactories(obj, path) {
+        for (const [key, value] of Object.entries(obj)) {
+            const newPath = path.length === 0 ? [key] : [...path, key];
+            if (typeof value === 'function') {
+                // Found a factory - cache it with its full path
+                const flatKey = this.getOrCachePath(newPath);
+                this.factoryCache.set(flatKey, value);
+            }
+            else if (typeof value === 'object' && value !== null) {
+                // Found a nested object - recurse deeper
+                this.walkFactories(value, newPath);
+            }
+        }
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // 🪞 PRELOAD PROXY SYSTEM
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Get the preload proxy for service instantiation
+     * The preload proxy allows you to create services with parameters:
+     *
+     * ```typescript
+     * const db = preload.database('main', connectionString)
+     * const userApi = preload.api.users('users', db, config)
+     * ```
+     *
+     * This is used during the initialization phase to wire up dependencies
+     */
+    get preload() {
+        // Cache the preload proxy since it's expensive to create and never changes
+        if (!this.preloadProxy) {
+            this.preloadProxy = this.createPreloadProxy();
+        }
+        return this.preloadProxy;
+    }
+    /**
+     * Create a proxy that intercepts property access and provides factory functions
+     *
+     * The proxy works by:
+     * 1. Intercepting property access (e.g., preload.database)
+     * 2. Looking up the factory for that path
+     * 3. Returning a function that creates and caches instances
+     * 4. For nested paths, returning another proxy
+     *
+     * This enables natural dot-notation access while maintaining lazy loading
+     */
+    createPreloadProxy(path = []) {
+        const pathKey = path.join('|');
+        // Check cache first for performance
+        if (this.proxyCache.has(pathKey)) {
+            this.safeIncrementMetric('proxyCacheHits');
+            return this.proxyCache.get(pathKey);
+        }
+        const proxy = new Proxy({}, // Empty target object - all access is intercepted
+        {
+            get: (_, prop) => {
+                const newPath = path.length === 0 ? [prop] : [...path, prop];
+                const flatKey = this.getOrCachePath(newPath);
+                const factory = this.factoryCache.get(flatKey);
+                if (factory) {
+                    // Found a factory - return a function that creates/caches instances
+                    return (id, ...params) => {
+                        const mgr = this.managers[flatKey];
+                        let inst = mgr.get(id);
+                        if (!inst) {
+                            // Cache miss - create new instance
+                            this.safeIncrementMetric('cacheMisses');
+                            this.safeIncrementMetric('instanceCreations');
+                            inst = instantiate(factory, params);
+                            mgr.set(id, inst);
+                        }
+                        else {
+                            // Cache hit - reusing existing instance
+                            this.safeIncrementMetric('cacheHits');
+                        }
+                        return inst;
+                    };
+                }
+                else {
+                    // No factory found - must be a nested path, return another proxy
+                    return this.createPreloadProxy(newPath);
+                }
+            },
+        });
+        // Cache the proxy for reuse
+        this.proxyCache.set(pathKey, proxy);
+        return proxy;
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // 🔄 TENANT CONTEXT MANAGEMENT
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Run a function within a specific tenant context
+     * This is usually called internally by bootstrap, but can be used directly
+     * for testing or advanced use cases
+     */
+    async runWithContext(instances, tenantMetadata, fn) {
+        return await this.als.run({ instances, tenantMetadata }, fn);
+    }
+    /**
+     * Get the current tenant's service context
+     *
+     * This is the main way to access services within a tenant context:
+     * ```typescript
+     * const { database, api } = container.context
+     * const users = await api.users.getAll()
+     * ```
+     *
+     * Throws an error if called outside of a tenant context
+     */
+    get context() {
+        const store = this.als.getStore();
+        if (!store) {
+            throw new Error("No tenant context available. Make sure you're running within a container context.");
+        }
+        this.safeIncrementMetric('contextAccesses');
+        return this.createContextProxy(store.instances);
+    }
+    /**
+     * Create a proxy for the runtime context that provides intelligent error handling
+     *
+     * The context proxy:
+     * 1. Provides helpful error messages when services are missing
+     * 2. Handles nested object access gracefully
+     * 3. Avoids wrapping Promises or arrays (which would break them)
+     * 4. Uses WeakMap caching for automatic memory management
+     *
+     * This ensures that accessing container.context.someService either works
+     * or gives you a clear error message about what's available
+     */
+    createContextProxy(obj, path = []) {
+        // Use WeakMap cache to avoid memory leaks
+        if (this.contextProxyCache.has(obj)) {
+            return this.contextProxyCache.get(obj);
+        }
+        const proxy = new Proxy(obj, {
+            get: (target, prop) => {
+                const newPath = path.length === 0 ? [prop] : [...path, prop];
+                const value = target[prop];
+                if (value === undefined) {
+                    // Check if property exists but is undefined (vs completely missing)
+                    if (prop in target) {
+                        // Property exists but is undefined - this is valid (e.g., optional services)
+                        return undefined;
+                    }
+                    // For symbols, especially well-known symbols like Symbol.iterator, 
+                    // just return undefined instead of throwing an error
+                    if (typeof prop === 'symbol') {
+                        return undefined;
+                    }
+                    // Property doesn't exist - provide helpful error message
+                    const servicePath = this.getOrCachePath(newPath);
+                    const available = Object.keys(target).join(', ');
+                    throw new Error(`Service '${servicePath}' not initialized. ` +
+                        `Available services: ${available}`);
+                }
+                // Only wrap objects that are safe to wrap
+                // Avoid wrapping Promises, arrays, thenable objects, Prisma clients, or Redis clients
+                if (typeof value === 'object' &&
+                    value !== null &&
+                    !Array.isArray(value) &&
+                    !(value instanceof Promise) &&
+                    typeof value.then !== 'function' &&
+                    // Avoid wrapping Prisma clients (they have complex internal properties)
+                    !('_engine' in value &&
+                        '_extensions' in value &&
+                        '$connect' in value) &&
+                    // Avoid wrapping Redis clients (they have ioredis-specific properties)
+                    !('options' in value && 'status' in value && 'connector' in value) &&
+                    // Avoid wrapping cache service objects (Keyv instances with opts property)
+                    !('opts' in value) &&
+                    // Avoid wrapping cache store objects
+                    !('store' in value && 'namespace' in value)) {
+                    // Safe to wrap - create nested proxy
+                    return this.createContextProxy(value, newPath);
+                }
+                // Return value as-is (primitives, functions, Promises, arrays)
+                return value;
+            },
+        });
+        // Cache using WeakMap for automatic garbage collection
+        this.contextProxyCache.set(obj, proxy);
+        return proxy;
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // 🚀 BOOTSTRAP & LIFECYCLE
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Create a stable cache key from tenant metadata
+     * Uses a deterministic approach focusing on tenant identity
+     */
+    createTenantCacheKey(meta) {
+        // Try to extract a tenant ID from common properties
+        const metaObj = meta;
+        const tenantId = metaObj.id || metaObj.tenantId || metaObj.name || 'unknown';
+        // Create a stable hash from the metadata for complete uniqueness
+        // This handles cases where tenant config might change but tenant ID stays same
+        try {
+            const sortedMeta = JSON.stringify(meta, Object.keys(meta).sort());
+            // Use a simple hash to keep cache keys manageable
+            const hash = this.simpleHash(sortedMeta);
+            return `tenant:${tenantId}:${hash}`;
+        }
+        catch {
+            // Fallback if JSON.stringify fails (circular refs, etc.)
+            return `tenant:${tenantId}:${Date.now()}`;
+        }
+    }
+    /**
+     * Simple hash function for cache keys
+     * Not cryptographically secure, but good enough for cache key generation
+     */
+    simpleHash(str) {
+        let hash = 0;
+        for (let i = 0; i < str.length; i++) {
+            const char = str.charCodeAt(i);
+            // eslint-disable-next-line no-bitwise
+            hash = (hash << 5) - hash + char;
+            // eslint-disable-next-line no-bitwise
+            hash = hash & hash; // Convert to 32bit integer
+        }
+        return Math.abs(hash).toString(36);
+    }
+    /**
+     * Get or create initialized instances for a tenant
+     * Uses caching to avoid re-running the expensive initializer function
+     */
+    async getOrCreateInstances(meta) {
+        const cacheKey = this.createTenantCacheKey(meta);
+        // Check if we already have initialized instances for this tenant
+        const cachedInstances = this.initializerCache.get(cacheKey);
+        if (cachedInstances) {
+            this.safeIncrementMetric('initializerCacheHits');
+            return cachedInstances;
+        }
+        // No cached instances - run the initializer
+        const instances = await this.initializer(this.preload, meta);
+        // Cache the result for future use
+        this.initializerCache.set(cacheKey, instances);
+        return instances;
+    }
+    /**
+     * Bootstrap the container for a specific tenant and execute a function
+     *
+     * This is the main entry point for tenant-specific operations:
+     *
+     * @param meta - Tenant-specific metadata (DB config, secrets, etc.)
+     * @param fn - Function to execute within the tenant context (optional)
+     * @returns Object containing the initialized instances and function result
+     *
+     * ```typescript
+     * // Example: Process a user request for tenant "acme"
+     * const result = await container.bootstrap(acmeTenantMeta, async () => {
+     *   const { api } = container.context
+     *   return await api.users.getById(userId)
+     * })
+     *
+     * console.log(result.instances) // All initialized services
+     * console.log(result.result)    // Return value from the function
+     * ```
+     *
+     * The bootstrap process:
+     * 1. Gets or creates initialized services for this tenant (with caching)
+     * 2. Sets up AsyncLocalStorage context with the service instances
+     * 3. Executes your function within that context
+     * 4. Returns both the instances and your function's result
+     */
+    async bootstrap(meta, fn) {
+        try {
+            // Phase 1: Get or create services for this tenant (with caching)
+            const instances = await this.getOrCreateInstances(meta);
+            // Phase 2: Run user function within tenant context
+            const result = await this.runWithContext(instances, meta, fn || (async () => undefined));
+            // Type assertion: we trust that initializer provides all required services
+            // In practice, this is validated at runtime by the context proxy
+            return { instances: instances, result };
+        }
+        catch (err) {
+            if (this.options.enableDiagnostics) {
+                console.error('Container bootstrap failed:', err);
+            }
+            throw err;
+        }
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // 📊 OBSERVABILITY & DEBUGGING
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Get current performance metrics
+     * Useful for monitoring cache effectiveness and performance tuning
+     */
+    getMetrics() {
+        return { ...this.metrics };
+    }
+    /**
+     * Reset all performance metrics to zero
+     * Useful for benchmarking specific operations
+     */
+    resetMetrics() {
+        this.metrics = {
+            cacheHits: 0,
+            cacheMisses: 0,
+            instanceCreations: 0,
+            contextAccesses: 0,
+            pathCacheHits: 0,
+            proxyCacheHits: 0,
+            initializerCacheHits: 0,
+        };
+    }
+    /**
+     * Clear all service instance caches
+     * Forces fresh instantiation of all services on next access
+     * Useful for testing or when you need to ensure clean state
+     */
+    clearCaches() {
+        for (const manager of Object.values(this.managers)) {
+            manager.clear?.();
+        }
+        // Clear optimization caches as well
+        this.pathCache.clear();
+        this.proxyCache.clear();
+        this.initializerCache.clear();
+        // Note: contextProxyCache is a WeakMap and will be garbage collected automatically
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // 🌐 DISTRIBUTED CACHE INVALIDATION
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Setup distributed cache invalidation system
+     * Connects to Redis pub/sub for coordinating cache invalidation across instances
+     */
+    setupDistributedInvalidation() {
+        if (!this.options.enableDistributedInvalidation ||
+            !this.options.distributedInvalidator) {
+            return;
+        }
+        const invalidator = this.options.distributedInvalidator;
+        // Listen for invalidation events from other instances
+        invalidator.on('invalidate-tenant', (tenantId, reason) => {
+            this.invalidateTenantLocally(tenantId, reason);
+        });
+        invalidator.on('invalidate-service', (serviceType, reason) => {
+            this.invalidateServiceLocally(serviceType, reason);
+        });
+        invalidator.on('invalidate-all', (reason) => {
+            this.invalidateAllLocally(reason);
+        });
+        // Handle Redis connection issues
+        invalidator.on('redis-error', (error) => {
+            if (this.options.enableDiagnostics) {
+                console.warn('Distributed cache invalidation Redis error:', error);
+            }
+        });
+    }
+    /**
+     * Invalidate all cached data for a specific tenant across all instances
+     * This sends a distributed invalidation message via Redis pub/sub
+     */
+    async invalidateTenantDistributed(tenantId, reason) {
+        // First invalidate locally
+        this.invalidateTenantLocally(tenantId, reason);
+        // Then invalidate on other instances
+        if (this.options.enableDistributedInvalidation &&
+            this.options.distributedInvalidator) {
+            await this.options.distributedInvalidator.invalidateTenant(tenantId, reason);
+        }
+    }
+    /**
+     * Invalidate all cached data for a specific service type across all instances
+     */
+    async invalidateServiceDistributed(serviceType, reason) {
+        // First invalidate locally
+        this.invalidateServiceLocally(serviceType, reason);
+        // Then invalidate on other instances
+        if (this.options.enableDistributedInvalidation &&
+            this.options.distributedInvalidator) {
+            await this.options.distributedInvalidator.invalidateService(serviceType, reason);
+        }
+    }
+    /**
+     * Invalidate all cached data across all instances
+     */
+    async invalidateAllDistributed(reason) {
+        // First invalidate locally
+        this.invalidateAllLocally(reason);
+        // Then invalidate on other instances
+        if (this.options.enableDistributedInvalidation &&
+            this.options.distributedInvalidator) {
+            await this.options.distributedInvalidator.invalidateAll(reason);
+        }
+    }
+    /**
+     * Invalidate cached data for a specific tenant (local only)
+     * This only affects the current instance
+     */
+    invalidateTenantLocally(tenantId, reason) {
+        if (this.options.enableDiagnostics) {
+            console.log(`Invalidating tenant cache locally: ${tenantId}`, reason ? `(${reason})` : '');
+        }
+        // Clear service instance caches for this tenant
+        for (const manager of Object.values(this.managers)) {
+            manager.delete(tenantId);
+        }
+        // Clear initializer cache for this tenant
+        for (const [cacheKey] of this.initializerCache.entries()) {
+            if (cacheKey.includes(tenantId)) {
+                this.initializerCache.delete(cacheKey);
+            }
+        }
+    }
+    /**
+     * Invalidate cached data for a specific service type (local only)
+     */
+    invalidateServiceLocally(serviceType, reason) {
+        if (this.options.enableDiagnostics) {
+            console.log(`Invalidating service cache locally: ${serviceType}`, reason ? `(${reason})` : '');
+        }
+        // Clear service instance cache for this service type
+        const manager = this.managers[serviceType];
+        if (manager) {
+            manager.clear();
+        }
+    }
+    /**
+     * Invalidate all cached data (local only)
+     */
+    invalidateAllLocally(reason) {
+        if (this.options.enableDiagnostics) {
+            console.log('Invalidating all caches locally', reason ? `(${reason})` : '');
+        }
+        this.clearCaches();
+    }
+    /**
+     * Get detailed cache statistics for each service
+     * Shows how many instances are cached and the cache limits
+     */
+    getCacheStats() {
+        const stats = {};
+        for (const [key, manager] of Object.entries(this.managers)) {
+            const managerAny = manager;
+            const size = typeof managerAny.size === 'function'
+                ? managerAny.size()
+                : managerAny.size || 0;
+            stats[key] = {
+                size,
+                maxSize: this.options.cacheSize,
+            };
+        }
+        return stats;
+    }
+    /**
+     * Get comprehensive performance statistics
+     * Combines metrics, cache stats, and computed ratios for full observability
+     */
+    getPerformanceStats() {
+        const cacheStats = this.getCacheStats();
+        const totalCacheSize = Object.values(cacheStats).reduce((sum, stat) => sum + stat.size, 0);
+        return {
+            ...this.getMetrics(),
+            cacheStats,
+            totalCacheSize,
+            pathCacheSize: this.pathCache.size,
+            proxyCacheSize: this.proxyCache.size,
+            factoryCacheSize: this.factoryCache.size,
+            initializerCacheSize: this.initializerCache.size,
+            cacheHitRatio: this.metrics.cacheHits + this.metrics.cacheMisses > 0
+                ? this.metrics.cacheHits /
+                    (this.metrics.cacheHits + this.metrics.cacheMisses)
+                : 0,
+        };
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // 🔍 RUNTIME INTROSPECTION
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Check if there's an active tenant context
+     *
+     * @returns true if called within a tenant context, false otherwise
+     *
+     * ```typescript
+     * if (container.hasActiveContext()) {
+     *   const services = container.context
+     *   // Safe to access services
+     * }
+     * ```
+     */
+    hasActiveContext() {
+        return this.als.getStore() !== undefined;
+    }
+    /**
+     * Check if a service is available in the current tenant context
+     *
+     * @param servicePath - Dot-notation path to the service (e.g., "api.users")
+     * @returns true if the service exists and is initialized, false otherwise
+     *
+     * ```typescript
+     * if (container.hasService('api.users')) {
+     *   const users = container.context.api.users
+     *   // Safe to use users service
+     * }
+     * ```
+     */
+    hasService(servicePath) {
+        const store = this.als.getStore();
+        if (!store)
+            return false;
+        const parts = servicePath.split('.');
+        let current = store.instances;
+        for (const part of parts) {
+            if (typeof current !== 'object' ||
+                current === null ||
+                !(part in current)) {
+                return false;
+            }
+            current = current[part];
+        }
+        return current !== undefined;
+    }
+    /**
+     * Get the current tenant's metadata
+     *
+     * This allows access to tenant-specific configuration, credentials, and other
+     * metadata that was passed to the bootstrap method:
+     *
+     * ```typescript
+     * await container.bootstrap(tenantMeta, async () => {
+     *   const meta = container.getCurrentTenantMetadata()
+     *   console.log('Current tenant:', meta.id)
+     *   console.log('DB URL:', meta.connectionString)
+     * })
+     * ```
+     *
+     * @returns The tenant metadata that was passed to bootstrap
+     * @throws Error if called outside of a tenant context
+     */
+    getCurrentTenantMetadata() {
+        const store = this.als.getStore();
+        if (!store) {
+            throw new Error("No tenant context available. Make sure you're running within a container context.");
+        }
+        return store.tenantMetadata;
+    }
+    /**
+     * Get the current tenant ID from metadata
+     *
+     * This is a convenience method that extracts the tenant ID from the metadata.
+     * It assumes the metadata has an 'id' property (common pattern).
+     *
+     * ```typescript
+     * await container.bootstrap(tenantMeta, async () => {
+     *   const tenantId = container.getCurrentTenantId()
+     *   console.log('Processing request for tenant:', tenantId)
+     * })
+     * ```
+     *
+     * @returns The tenant ID if metadata has an 'id' property, undefined otherwise
+     * @throws Error if called outside of a tenant context
+     */
+    getCurrentTenantId() {
+        const metadata = this.getCurrentTenantMetadata();
+        // Check if metadata has an 'id' property (common pattern)
+        if (metadata && typeof metadata === 'object' && 'id' in metadata) {
+            const id = metadata.id;
+            return typeof id === 'string' ? id : String(id);
+        }
+        return undefined;
+    }
+    /**
+     * Get a list of all available services in the current tenant context
+     * Useful for debugging, testing, or dynamic service discovery
+     *
+     * @returns Array of dot-notation service paths (e.g., ["database", "api.users", "api.auth"])
+     */
+    getAvailableServices() {
+        const store = this.als.getStore();
+        if (!store)
+            return [];
+        const services = [];
+        this.collectServices(store.instances, services);
+        return services;
+    }
+    /**
+     * Recursively collect all service paths from the current context
+     * Helper method for getAvailableServices()
+     */
+    collectServices(obj, services, path = []) {
+        for (const [key, value] of Object.entries(obj)) {
+            if (value === undefined)
+                continue; // Skip undefined services (partial structure)
+            const currentPath = [...path, key];
+            if (typeof value === 'object' &&
+                value !== null &&
+                !Array.isArray(value)) {
+                // Nested object - recurse deeper
+                this.collectServices(value, services, currentPath);
+            }
+            else {
+                // Leaf service - add to list
+                services.push(currentPath.join('.'));
+            }
+        }
+    }
+}
+exports.Container = Container;
+//# sourceMappingURL=Container.js.map