@goatlab/node-backend 0.2.5 → 0.4.0

package/dist/container/Container.js

@@ -2,7 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Container = void 0;
 const async_hooks_1 = require("async_hooks");
-const crypto_1 = require("crypto");
 const LruCache_1 = require("./LruCache");
 const helpers_1 = require("./helpers");
 // Instantiation helper moved to helpers.ts for better performance
@@ -96,8 +95,9 @@ class Container {
     /**
      * Service instance cache managers - one per service type
      * Each manager handles LRU caching for that specific service
+     * Lazy-allocated to save memory for unused services
      */
-    managers;
+    managers = {};
     /**
      * AsyncLocalStorage provides automatic tenant context isolation
      * Each async call tree gets its own isolated service instances
@@ -125,11 +125,7 @@ class Container {
     // ═══════════════════════════════════════════════════════════════════════════
     // ⚡ PERFORMANCE OPTIMIZATION CACHES
     // ═══════════════════════════════════════════════════════════════════════════
-    /**
-     * Path string cache: converts ['user', 'repo'] -> "user.repo"
-     * Optimized to avoid repeated string joins and array operations
-     */
-    pathCache = new Map();
+    // Path cache removed - direct string concatenation is faster
     /**
      * Proxy object cache: reuses proxy objects for the same paths
      * Reduces memory allocation and improves performance
@@ -151,22 +147,23 @@ class Container {
     // ═══════════════════════════════════════════════════════════════════════════
     /**
      * High-performance metrics using Uint32Array for better JIT optimization
-     * Indices: [hits, misses, creates, ctx, paths, proxy, initHits, resets]
+     * Indices: [hits, misses, creates, ctx, proxy, initHits, resets, batchOps, batchErrors]
      * Auto-wraps at 2^32 without overflow checks for maximum performance
      */
-    metrics = new Uint32Array(8);
+    metrics = new Uint32Array(9);
     /**
      * Metric indices for Uint32Array
      */
-    static METRIC_INDICES = {
+    static METRIC = {
         HITS: 0,
         MISSES: 1,
         CREATES: 2,
         CONTEXTS: 3,
-        PATHS: 4,
-        PROXIES: 5,
-        INIT_HITS: 6,
-        RESETS: 7,
+        PROXIES: 4,
+        INIT_HITS: 5,
+        RESETS: 6,
+        BATCH_OPS: 7,
+        BATCH_ERRORS: 8
     };
     /**
      * Legacy overflow threshold for test compatibility
@@ -181,11 +178,20 @@ class Container {
         if (!this.options.enableMetrics)
             return;
         // Check for test mock of MAX_METRIC_VALUE (legacy compatibility)
-        if (this.MAX_METRIC_VALUE < 1000 && this.metrics[idx] >= this.MAX_METRIC_VALUE) {
+        if (this.MAX_METRIC_VALUE < 1000 &&
+            this.metrics[idx] >= this.MAX_METRIC_VALUE) {
             // Legacy test behavior - reset metrics when mock threshold reached
             this.resetMetrics();
             if (this.options.enableDiagnostics) {
-                const metricNames = ['cacheHits', 'cacheMisses', 'instanceCreations', 'contextAccesses', 'pathCacheHits', 'proxyCacheHits', 'initializerCacheHits'];
+                const metricNames = [
+                    'cacheHits',
+                    'cacheMisses',
+                    'instanceCreations',
+                    'contextAccesses',
+                    'proxyCacheHits',
+                    'initializerCacheHits',
+                    'resets'
+                ];
                 console.warn(`Container metrics reset due to overflow protection. Metric '${metricNames[idx] || 'unknown'}' reached ${this.metrics[idx]}`);
             }
         }
@@ -218,14 +224,10 @@ class Container {
             enableDiagnostics: false,
             enableDistributedInvalidation: false,
             distributedInvalidator: undefined,
-            ...options,
+            ...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();
-        // Pre-warm proxy cache with common paths to reduce runtime allocation
-        this.prewarmProxyCache();
         // Setup distributed cache invalidation if enabled
         this.setupDistributedInvalidation();
     }
@@ -233,47 +235,18 @@ class Container {
     // 🏭 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
+     * Get or create a cache manager for a service - lazy allocation
+     * Saves memory by only creating caches for services that are actually used
+     * Note: Type safety is enforced at compile time through generics, not runtime
      */
-    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;
+    getManager(key) {
+        return (this.managers[key] ??= (0, LruCache_1.createServiceCache)(this.options.cacheSize));
     }
+    // createManagers() removed - managers are created lazily via getManager()
     // ═══════════════════════════════════════════════════════════════════════════
     // ⚡ PERFORMANCE OPTIMIZATION HELPERS
     // ═══════════════════════════════════════════════════════════════════════════
-    /**
-     * Optimized path caching that maintains flat key strings to avoid repeated joins
-     * Uses closure to keep pre-computed cache and final keys for maximum performance
-     */
-    getOrCachePath(path) {
-        // Create cache key once and reuse the flat key computation
-        const stringPath = path.map(p => typeof p === 'symbol' ? p.toString() : p);
-        const cacheKey = stringPath.join('|'); // Cache key uses pipe separator
-        let cached = this.pathCache.get(cacheKey);
-        if (!cached) {
-            cached = stringPath.join('.'); // Final path uses dot separator
-            this.pathCache.set(cacheKey, cached);
-        }
-        else {
-            this.inc(Container.METRIC_INDICES.PATHS);
-        }
-        return cached;
-    }
+    // getOrCachePath() removed - direct string concatenation in createPreloadProxy()
     /**
      * Pre-populate the factory cache by walking the entire factory tree
      * This eliminates the need for recursive object traversal during runtime
@@ -281,25 +254,7 @@ class Container {
     preloadFactoryCache() {
         this.walkFactories(this.factories, []);
     }
-    /**
-     * Pre-warm proxy cache with static builders for common paths
-     * This reduces proxy creation overhead during runtime access patterns
-     */
-    prewarmProxyCache() {
-        // Pre-create proxies for all known factory paths to avoid runtime creation
-        for (const [path] of this.factoryCache.entries()) {
-            const pathParts = path.split('.');
-            // Pre-warm all parent paths (e.g., for "api.users", pre-warm "api")
-            for (let i = 1; i <= pathParts.length; i++) {
-                const subPath = pathParts.slice(0, i);
-                const pathKey = subPath.join('|');
-                if (!this.proxyCache.has(pathKey)) {
-                    // Create and cache the proxy for this path
-                    this.createPreloadProxy(subPath);
-                }
-            }
-        }
-    }
+    // prewarmProxyCache() removed - proxies are created lazily
     /**
      * Recursive factory tree walker that builds the flat factory cache
      * Converts nested object structure to flat dot-notation keys
@@ -309,7 +264,7 @@ class Container {
             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);
+                const flatKey = newPath.join('.');
                 this.factoryCache.set(flatKey, value);
             }
             else if (typeof value === 'object' && value !== null) {
@@ -350,46 +305,38 @@ class Container {
      *
      * 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.inc(Container.METRIC_INDICES.PROXIES);
-            return this.proxyCache.get(pathKey);
+    createPreloadProxy(path = '') {
+        if (this.proxyCache.has(path)) {
+            this.inc(Container.METRIC.PROXIES);
+            return this.proxyCache.get(path);
         }
         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);
+                const newPath = path ? `${path}.${String(prop)}` : String(prop);
+                const factory = this.factoryCache.get(newPath);
                 if (factory) {
                     // Found a factory - return a function that creates/caches instances
-                    return (id, ...params) => {
-                        const mgr = this.managers[flatKey];
+                    return (id, ...args) => {
+                        const mgr = this.getManager(newPath);
                         let inst = mgr.get(id);
                         if (!inst) {
-                            // Cache miss - create new instance
-                            this.inc(Container.METRIC_INDICES.MISSES);
-                            this.inc(Container.METRIC_INDICES.CREATES);
-                            inst = (0, helpers_1.instantiate)(factory, params);
+                            this.inc(Container.METRIC.MISSES);
+                            this.inc(Container.METRIC.CREATES);
+                            inst = (0, helpers_1.instantiate)(factory, args);
                             mgr.set(id, inst);
                         }
                         else {
-                            // Cache hit - reusing existing instance
-                            this.inc(Container.METRIC_INDICES.HITS);
+                            this.inc(Container.METRIC.HITS);
                         }
                         return inst;
                     };
                 }
-                else {
-                    // No factory found - must be a nested path, return another proxy
-                    return this.createPreloadProxy(newPath);
-                }
-            },
+                // 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);
+        this.proxyCache.set(path, proxy);
         return proxy;
     }
     // ═══════════════════════════════════════════════════════════════════════════
@@ -409,14 +356,21 @@ class Container {
      * More efficient for pure synchronous code paths
      */
     runWithContextSync(instances, tenantMetadata, fn) {
-        const store = { instances, tenantMetadata };
-        this.als.enterWith(store);
+        const prev = this.als.getStore();
+        this.als.enterWith({ instances, tenantMetadata });
         try {
             return fn();
         }
         finally {
-            // Clean up the context after synchronous execution
-            this.als.enterWith(undefined);
+            if (prev) {
+                this.als.enterWith(prev);
+            }
+            else if ('disable' in this.als) {
+                // Node 20+ - fully clear context when no previous context
+                // The disable() method was added in Node.js 20.5.0 to properly clear ALS context
+                // In earlier versions, this check safely falls through without error
+                this.als.disable();
+            }
         }
     }
     /**
@@ -435,7 +389,7 @@ class Container {
         if (!store) {
             throw new Error("No tenant context available. Make sure you're running within a container context.");
         }
-        this.inc(Container.METRIC_INDICES.CONTEXTS);
+        this.inc(Container.METRIC.CONTEXTS);
         return this.createContextProxy(store.instances);
     }
     /**
@@ -458,21 +412,25 @@ class Container {
         const proxy = new Proxy(obj, {
             get: (target, prop) => {
                 const newPath = path.length === 0 ? [prop] : [...path, prop];
-                const value = target[prop];
+                const value = Reflect.get(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, 
+                    // For symbols, especially well-known symbols like Symbol.iterator,
                     // just return undefined instead of throwing an error
                     if (typeof prop === 'symbol') {
                         return undefined;
                     }
+                    // Special case for 'then' to avoid Promise detection issues
+                    if (prop === 'then') {
+                        return undefined;
+                    }
                     // Property doesn't exist - provide helpful error message
-                    const servicePath = this.getOrCachePath(newPath);
-                    const available = Object.keys(target).join(', ');
+                    const servicePath = newPath.join('.');
+                    const available = Reflect.ownKeys(target).map(String).join(', ');
                     throw new Error(`Service '${servicePath}' not initialized. ` +
                         `Available services: ${available}`);
                 }
@@ -498,7 +456,7 @@ class Container {
                 }
                 // Return value as-is (primitives, functions, Promises, arrays)
                 return value;
-            },
+            }
         });
         // Cache using WeakMap for automatic garbage collection
         this.contextProxyCache.set(obj, proxy);
@@ -508,26 +466,37 @@ class Container {
     // 🚀 BOOTSTRAP & LIFECYCLE
     // ═══════════════════════════════════════════════════════════════════════════
     /**
-     * Create a stable cache key from tenant metadata using crypto-strong hashing
-     * Uses SHA-1 for better collision resistance than simple hash (~1:2^16 -> negligible)
+     * Simple string hash function for fallback tenant keys
+     * Uses djb2 algorithm - fast and good enough for cache keys
+     * Note: For very large metadata objects, consider upgrading to FNV-1a or crypto.createHash
+     * if collision resistance is critical. Current implementation is optimized for speed.
+     */
+    simpleHash(str) {
+        let hash = 5381;
+        for (let i = 0; i < str.length; i++) {
+            hash = (hash << 5) + hash + str.charCodeAt(i);
+        }
+        return (hash >>> 0).toString(36);
+    }
+    /**
+     * Create a stable cache key from tenant metadata
+     * Uses common tenant properties or hashed JSON as fallback
      */
     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
+        const m = meta;
+        if (m.id || m.tenantId || m.name) {
+            return `tenant:${m.id ?? m.tenantId ?? m.name}`;
+        }
+        // Fallback to hashed JSON for complex metadata
         try {
-            const sortedMeta = JSON.stringify(meta, Object.keys(meta).sort());
-            // Use crypto-strong hash for better collision resistance (27 bytes vs simple hash)
-            const hash = (0, crypto_1.createHash)('sha1').update(sortedMeta).digest('base64url');
-            return `tenant:${tenantId}:${hash}`;
+            const json = JSON.stringify(meta);
+            return `tenant:hash:${this.simpleHash(json)}`;
         }
         catch {
-            // Fallback if JSON.stringify fails (circular refs, etc.)
-            return `tenant:${tenantId}:${Date.now()}`;
+            // Last resort for circular refs
+            return `tenant:ts:${Date.now()}`;
         }
     }
-    // Simple hash function removed in favor of crypto.createHash for better collision resistance
     /**
      * Get or create initialized instances for a tenant with race condition protection
      * Uses both result caching and inflight promise deduplication
@@ -537,7 +506,7 @@ class Container {
         // Check if we already have initialized instances for this tenant
         const cachedInstances = this.initializerCache.get(cacheKey);
         if (cachedInstances) {
-            this.inc(Container.METRIC_INDICES.INIT_HITS);
+            this.inc(Container.METRIC.INIT_HITS);
             return cachedInstances;
         }
         // Check if initialization is already in progress for this tenant
@@ -603,6 +572,240 @@ class Container {
         }
     }
     // ═══════════════════════════════════════════════════════════════════════════
+    // BATCH OPERATIONS
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Bootstrap multiple tenants in parallel with controlled concurrency
+     *
+     * This method enables efficient initialization of multiple tenants while:
+     * - Controlling concurrency to avoid overwhelming the system
+     * - Isolating errors so one failure doesn't affect others
+     * - Providing progress tracking for long-running operations
+     * - Collecting performance metrics for each operation
+     *
+     * @param tenantBatch - Array of tenant metadata and optional functions to execute
+     * @param options - Options for controlling the batch operation
+     * @returns Array of results for each tenant, including successes and failures
+     *
+     * ```typescript
+     * const results = await container.bootstrapBatch([
+     *   { metadata: tenant1Meta, fn: async () => processТenant1() },
+     *   { metadata: tenant2Meta, fn: async () => processTenant2() },
+     *   { metadata: tenant3Meta } // No function, just bootstrap
+     * ], {
+     *   concurrency: 5,
+     *   continueOnError: true,
+     *   onProgress: (completed, total) => console.log(`${completed}/${total}`)
+     * })
+     *
+     * // Process results
+     * for (const result of results) {
+     *   if (result.status === 'success') {
+     *     console.log(`Tenant ${result.metadata.id} initialized in ${result.metrics.duration}ms`)
+     *   } else {
+     *     console.error(`Tenant ${result.metadata.id} failed:`, result.error)
+     *   }
+     * }
+     * ```
+     */
+    async bootstrapBatch(tenantBatch, options = {}) {
+        const { concurrency = 10, continueOnError = true, timeout, onProgress } = options;
+        const results = [];
+        const total = tenantBatch.length;
+        let completed = 0;
+        let shouldAbort = false;
+        // Process tenants in chunks based on concurrency limit
+        for (let i = 0; i < total; i += concurrency) {
+            // Check if we should abort due to previous error in fail-fast mode
+            if (shouldAbort) {
+                break;
+            }
+            const chunk = tenantBatch.slice(i, i + concurrency);
+            const chunkPromises = chunk.map(async ({ metadata, fn }) => {
+                const startTime = Date.now();
+                try {
+                    // Apply timeout if specified
+                    let bootstrapPromise = this.bootstrap(metadata, fn);
+                    if (timeout) {
+                        bootstrapPromise = Promise.race([
+                            bootstrapPromise,
+                            new Promise((_, reject) => setTimeout(() => reject(new Error(`Bootstrap timeout after ${timeout}ms`)), timeout))
+                        ]);
+                    }
+                    const { instances, result } = await bootstrapPromise;
+                    const endTime = Date.now();
+                    this.inc(Container.METRIC.BATCH_OPS);
+                    return {
+                        metadata,
+                        status: 'success',
+                        instances,
+                        result,
+                        metrics: {
+                            startTime,
+                            endTime,
+                            duration: endTime - startTime
+                        }
+                    };
+                }
+                catch (error) {
+                    const endTime = Date.now();
+                    this.inc(Container.METRIC.BATCH_ERRORS);
+                    if (this.options.enableDiagnostics) {
+                        console.error(`Batch bootstrap failed for tenant:`, metadata, error);
+                    }
+                    const result = {
+                        metadata,
+                        status: 'error',
+                        error: error instanceof Error ? error : new Error(String(error)),
+                        metrics: {
+                            startTime,
+                            endTime,
+                            duration: endTime - startTime
+                        }
+                    };
+                    if (!continueOnError) {
+                        // Mark that we should abort processing
+                        shouldAbort = true;
+                    }
+                    return result;
+                }
+                finally {
+                    completed++;
+                    onProgress?.(completed, total, metadata);
+                }
+            });
+            // Wait for current chunk to complete before starting next
+            const chunkResults = await Promise.allSettled(chunkPromises);
+            // Extract results from Promise.allSettled
+            for (const settledResult of chunkResults) {
+                if (settledResult.status === 'fulfilled') {
+                    results.push(settledResult.value);
+                }
+                else if (continueOnError) {
+                    // This shouldn't happen as we handle errors above, but just in case
+                    results.push({
+                        metadata: tenantBatch[results.length].metadata,
+                        status: 'error',
+                        error: settledResult.reason,
+                        metrics: {
+                            startTime: Date.now(),
+                            endTime: Date.now(),
+                            duration: 0
+                        }
+                    });
+                }
+            }
+            // Check if we had any errors and should fail fast
+            if (!continueOnError && results.some(r => r.status === 'error')) {
+                const errorResult = results.find(r => r.status === 'error');
+                throw errorResult?.error || new Error('Batch operation failed');
+            }
+        }
+        return results;
+    }
+    /**
+     * Invalidate multiple tenant caches in batch
+     *
+     * Efficiently invalidates caches for multiple tenants with proper disposal
+     * and error handling. Useful for bulk updates or maintenance operations.
+     *
+     * @param tenantIds - Array of tenant IDs to invalidate
+     * @param reason - Optional reason for invalidation (for logging)
+     * @param distributed - Whether to propagate invalidation to other instances
+     * @returns Summary of the batch invalidation operation
+     *
+     * ```typescript
+     * const result = await container.invalidateTenantBatch(
+     *   ['tenant1', 'tenant2', 'tenant3'],
+     *   'Bulk configuration update',
+     *   true // Distribute to other instances
+     * )
+     *
+     * console.log(`Invalidated ${result.succeeded}/${result.total} tenants`)
+     * if (result.failed > 0) {
+     *   console.error('Failed invalidations:', result.errors)
+     * }
+     * ```
+     */
+    async invalidateTenantBatch(tenantIds, reason, distributed = false) {
+        const result = {
+            total: tenantIds.length,
+            succeeded: 0,
+            failed: 0,
+            errors: []
+        };
+        // Process invalidations in parallel with error isolation
+        const invalidationPromises = tenantIds.map(async (tenantId) => {
+            try {
+                if (distributed) {
+                    await this.invalidateTenantDistributed(tenantId, reason);
+                }
+                else {
+                    this.invalidateTenantLocally(tenantId, reason);
+                }
+                result.succeeded++;
+            }
+            catch (error) {
+                result.failed++;
+                result.errors.push({
+                    key: tenantId,
+                    error: error instanceof Error ? error : new Error(String(error))
+                });
+                if (this.options.enableDiagnostics) {
+                    console.error(`Failed to invalidate tenant ${tenantId}:`, error);
+                }
+            }
+        });
+        await Promise.allSettled(invalidationPromises);
+        return result;
+    }
+    /**
+     * Invalidate multiple service caches in batch
+     *
+     * @param serviceTypes - Array of service types to invalidate
+     * @param reason - Optional reason for invalidation
+     * @param distributed - Whether to propagate invalidation
+     * @returns Summary of the batch invalidation operation
+     *
+     * ```typescript
+     * const result = await container.invalidateServiceBatch(
+     *   ['database', 'api.users', 'api.auth'],
+     *   'Service configuration update'
+     * )
+     * ```
+     */
+    async invalidateServiceBatch(serviceTypes, reason, distributed = false) {
+        const result = {
+            total: serviceTypes.length,
+            succeeded: 0,
+            failed: 0,
+            errors: []
+        };
+        const invalidationPromises = serviceTypes.map(async (serviceType) => {
+            try {
+                if (distributed) {
+                    await this.invalidateServiceDistributed(serviceType, reason);
+                }
+                else {
+                    this.invalidateServiceLocally(serviceType, reason);
+                }
+                result.succeeded++;
+            }
+            catch (error) {
+                result.failed++;
+                result.errors.push({
+                    key: serviceType,
+                    error: error instanceof Error ? error : new Error(String(error))
+                });
+                if (this.options.enableDiagnostics) {
+                    console.error(`Failed to invalidate service ${serviceType}:`, error);
+                }
+            }
+        });
+        await Promise.allSettled(invalidationPromises);
+        return result;
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
     // 📊 OBSERVABILITY & DEBUGGING
     // ═══════════════════════════════════════════════════════════════════════════
     /**
@@ -611,13 +814,14 @@ class Container {
      */
     getMetrics() {
         return {
-            cacheHits: this.metrics[Container.METRIC_INDICES.HITS],
-            cacheMisses: this.metrics[Container.METRIC_INDICES.MISSES],
-            instanceCreations: this.metrics[Container.METRIC_INDICES.CREATES],
-            contextAccesses: this.metrics[Container.METRIC_INDICES.CONTEXTS],
-            pathCacheHits: this.metrics[Container.METRIC_INDICES.PATHS],
-            proxyCacheHits: this.metrics[Container.METRIC_INDICES.PROXIES],
-            initializerCacheHits: this.metrics[Container.METRIC_INDICES.INIT_HITS],
+            cacheHits: this.metrics[Container.METRIC.HITS],
+            cacheMisses: this.metrics[Container.METRIC.MISSES],
+            instanceCreations: this.metrics[Container.METRIC.CREATES],
+            contextAccesses: this.metrics[Container.METRIC.CONTEXTS],
+            proxyCacheHits: this.metrics[Container.METRIC.PROXIES],
+            initializerCacheHits: this.metrics[Container.METRIC.INIT_HITS],
+            batchOperations: this.metrics[Container.METRIC.BATCH_OPS],
+            batchErrors: this.metrics[Container.METRIC.BATCH_ERRORS]
         };
     }
     /**
@@ -626,7 +830,7 @@ class Container {
      */
     resetMetrics() {
         this.metrics.fill(0);
-        this.inc(Container.METRIC_INDICES.RESETS);
+        this.inc(Container.METRIC.RESETS);
     }
     /**
      * Clear all service instance caches with proper disposal support
@@ -636,25 +840,37 @@ class Container {
         // Dispose instances before clearing to prevent memory leaks
         for (const manager of Object.values(this.managers)) {
             // Call dispose hooks if manager supports iteration
-            if (typeof manager.entries === 'function') {
-                for (const [, inst] of manager.entries()) {
-                    // Call optional dispose hook if available
-                    if (inst && typeof inst.dispose === 'function') {
-                        try {
-                            inst.dispose();
-                        }
-                        catch (err) {
-                            if (this.options.enableDiagnostics) {
-                                console.warn('Error disposing instance:', err);
-                            }
+            if (typeof manager.values === 'function') {
+                const vals = manager.values?.() ?? [];
+                for (const inst of vals) {
+                    (0, helpers_1.safeDispose)(inst).catch(err => {
+                        if (this.options.enableDiagnostics) {
+                            console.warn('Error disposing service instance:', err);
                         }
-                    }
+                    });
                 }
             }
-            manager.clear?.();
+            manager.clear();
+        }
+        // Clear optimization caches as well
+        this.proxyCache.clear();
+        this.initializerCache.clear();
+        this.initializerPromises.clear();
+        // Note: contextProxyCache is a WeakMap and will be garbage collected automatically
+    }
+    /**
+     * Async version of clearCaches that properly awaits all disposal operations
+     * Use this method when you need to ensure all resources are fully disposed
+     * before continuing (e.g., during graceful shutdown)
+     */
+    async clearCachesAsync() {
+        // Dispose instances before clearing to prevent memory leaks
+        await Promise.all(Object.values(this.managers).flatMap(m => [...(m.values?.() ?? [])].map(helpers_1.safeDispose)));
+        // Clear all managers
+        for (const manager of Object.values(this.managers)) {
+            manager.clear();
         }
         // Clear optimization caches as well
-        this.pathCache.clear();
         this.proxyCache.clear();
         this.initializerCache.clear();
         this.initializerPromises.clear();
@@ -738,15 +954,12 @@ class Container {
         // Clear service instance caches for this tenant with disposal
         for (const manager of Object.values(this.managers)) {
             const instance = manager.get(tenantId);
-            if (instance && typeof instance.dispose === 'function') {
-                try {
-                    instance.dispose();
-                }
-                catch (err) {
+            if (instance) {
+                (0, helpers_1.safeDispose)(instance).catch(err => {
                     if (this.options.enableDiagnostics) {
                         console.warn('Error disposing tenant instance:', err);
                     }
-                }
+                });
             }
             manager.delete(tenantId);
         }
@@ -768,18 +981,14 @@ class Container {
         const manager = this.managers[serviceType];
         if (manager) {
             // Dispose instances before clearing
-            if (typeof manager.entries === 'function') {
-                for (const [, inst] of manager.entries()) {
-                    if (inst && typeof inst.dispose === 'function') {
-                        try {
-                            inst.dispose();
+            if (typeof manager.values === 'function') {
+                const vals = manager.values?.() ?? [];
+                for (const inst of vals) {
+                    (0, helpers_1.safeDispose)(inst).catch(err => {
+                        if (this.options.enableDiagnostics) {
+                            console.warn('Error disposing service instance:', err);
                         }
-                        catch (err) {
-                            if (this.options.enableDiagnostics) {
-                                console.warn('Error disposing service instance:', err);
-                            }
-                        }
-                    }
+                    });
                 }
             }
             manager.clear();
@@ -794,6 +1003,17 @@ class Container {
         }
         this.clearCaches();
     }
+    /**
+     * Dispose all service instances across all tenants and clear caches
+     * Useful for graceful shutdown and testing cleanup
+     * Note: This also clears all caches to prevent resurrection of disposed services
+     */
+    async disposeAll() {
+        // First dispose all instances
+        await Promise.all(Object.values(this.managers).flatMap(manager => [...(manager.values?.() ?? [])].map(helpers_1.safeDispose)));
+        // Then clear all caches to prevent resurrection
+        await this.clearCachesAsync();
+    }
     /**
      * Get detailed cache statistics for each service
      * Shows how many instances are cached and the cache limits
@@ -807,7 +1027,7 @@ class Container {
                 : managerAny.size || 0;
             stats[key] = {
                 size,
-                maxSize: this.options.cacheSize,
+                maxSize: this.options.cacheSize
             };
         }
         return stats;
@@ -819,18 +1039,21 @@ class Container {
     getPerformanceStats() {
         const cacheStats = this.getCacheStats();
         const totalCacheSize = Object.values(cacheStats).reduce((sum, stat) => sum + stat.size, 0);
-        const hits = this.metrics[Container.METRIC_INDICES.HITS];
-        const misses = this.metrics[Container.METRIC_INDICES.MISSES];
+        const hits = this.metrics[Container.METRIC.HITS];
+        const misses = this.metrics[Container.METRIC.MISSES];
+        const batchOps = this.metrics[Container.METRIC.BATCH_OPS];
+        const batchErrors = this.metrics[Container.METRIC.BATCH_ERRORS];
         return {
             ...this.getMetrics(),
             cacheStats,
             totalCacheSize,
-            pathCacheSize: this.pathCache.size,
+            pathCacheSize: 0, // removed - no longer tracked
             proxyCacheSize: this.proxyCache.size,
             factoryCacheSize: this.factoryCache.size,
             initializerCacheSize: this.initializerCache.size,
             initializerPromisesSize: this.initializerPromises.size,
             cacheHitRatio: hits + misses > 0 ? hits / (hits + misses) : 0,
+            batchSuccessRatio: batchOps > 0 ? (batchOps - batchErrors) / batchOps : 0
         };
     }
     // ═══════════════════════════════════════════════════════════════════════════