@navios/di 0.8.0 → 0.9.0

package/src/internal/core/name-resolver.mts

@@ -0,0 +1,196 @@
+import type { InjectionTokenType } from '../../token/injection-token.mjs'
+
+import { InjectableScope } from '../../enums/index.mjs'
+
+/**
+ * Simple LRU cache for instance name generation.
+ * Uses a Map which maintains insertion order for efficient LRU eviction.
+ */
+class InstanceNameCache {
+  private readonly cache = new Map<string, string>()
+  private readonly maxSize: number
+
+  constructor(maxSize = 1000) {
+    this.maxSize = maxSize
+  }
+
+  get(key: string): string | undefined {
+    const value = this.cache.get(key)
+    if (value !== undefined) {
+      // Move to end (most recently used)
+      this.cache.delete(key)
+      this.cache.set(key, value)
+    }
+    return value
+  }
+
+  set(key: string, value: string): void {
+    if (this.cache.has(key)) {
+      this.cache.delete(key)
+    } else if (this.cache.size >= this.maxSize) {
+      // Remove least recently used (first item)
+      const firstKey = this.cache.keys().next().value
+      if (firstKey !== undefined) {
+        this.cache.delete(firstKey)
+      }
+    }
+    this.cache.set(key, value)
+  }
+
+  clear(): void {
+    this.cache.clear()
+  }
+}
+
+/**
+ * Simple hash function for deterministic hashing of arguments
+ */
+function hashArgs(args: any): string {
+  const str = JSON.stringify(args, Object.keys(args || {}).sort())
+  let hash = 0
+  for (let i = 0; i < str.length; i++) {
+    const char = str.charCodeAt(i)
+    hash = (hash << 5) - hash + char
+    hash = hash & hash // Convert to 32-bit integer
+  }
+  return Math.abs(hash).toString(36)
+}
+
+/**
+ * Handles instance name generation with support for requestId and scope.
+ *
+ * Generates unique instance identifiers based on token, arguments, and scope.
+ * Request-scoped services MUST include requestId in their name for proper isolation.
+ */
+export class NameResolver {
+  private readonly instanceNameCache = new InstanceNameCache()
+
+  constructor(private readonly logger: Console | null = null) {}
+
+  /**
+   * Generates a unique instance name based on token, arguments, requestId, and scope.
+   *
+   * Name formats:
+   * - Singleton/Transient without args: `${tokenId}`
+   * - Singleton/Transient with args: `${tokenId}:${argsHash}`
+   * - Request without args: `${tokenId}:requestId=${requestId}`
+   * - Request with args: `${tokenId}:requestId=${requestId}:${argsHash}`
+   *
+   * @param token The injection token
+   * @param args Optional arguments
+   * @param requestId Optional request ID (required for request-scoped services)
+   * @param scope Optional scope (used to determine if requestId should be included)
+   * @returns The generated instance name
+   */
+  generateInstanceName(
+    token: InjectionTokenType,
+    args?: any,
+    requestId?: string,
+    scope?: InjectableScope,
+  ): string {
+    const tokenStr = token.toString()
+    const isRequest = scope === InjectableScope.Request
+
+    // For request-scoped services, requestId is required
+    if (isRequest && !requestId) {
+      throw new Error(
+        `[NameResolver] requestId is required for request-scoped services`,
+      )
+    }
+
+    // Build cache key
+    const cacheKey = `${tokenStr}:${scope}:${requestId || ''}:${args ? JSON.stringify(args) : ''}`
+
+    // Check cache first
+    const cached = this.instanceNameCache.get(cacheKey)
+    if (cached !== undefined) {
+      return cached
+    }
+
+    // Generate the instance name
+    let result = tokenStr
+
+    // Add requestId for request-scoped services
+    if (isRequest && requestId) {
+      result = `${result}:requestId=${requestId}`
+    }
+
+    // Add args hash if args are provided
+    if (args) {
+      const argsHash = hashArgs(args)
+      result = `${result}:${argsHash}`
+    }
+
+    // Cache the result
+    this.instanceNameCache.set(cacheKey, result)
+
+    return result
+  }
+
+  /**
+   * Upgrades an existing instance name to include requestId.
+   * Preserves any args hash that might already be in the name.
+   *
+   * Examples:
+   * - `TokenName` → `TokenName:requestId=req-123`
+   * - `TokenName:abc123` → `TokenName:requestId=req-123:abc123`
+   *
+   * @param existingName The existing instance name (without requestId)
+   * @param requestId The request ID to add
+   * @returns The upgraded instance name with requestId
+   */
+  upgradeInstanceNameToRequest(
+    existingName: string,
+    requestId: string,
+  ): string {
+    // Check if requestId is already in the name
+    if (existingName.includes(`:requestId=${requestId}`)) {
+      return existingName
+    }
+
+    // Find where to insert requestId
+    // Format: TokenName or TokenName:argsHash
+    // We want: TokenName:requestId=req-123 or TokenName:requestId=req-123:argsHash
+
+    // Check if there's an args hash (starts after first colon, but not requestId=)
+    const requestIdPattern = /:requestId=/
+    const hasRequestId = requestIdPattern.test(existingName)
+
+    if (hasRequestId) {
+      // Already has a requestId, don't upgrade
+      return existingName
+    }
+
+    // Find the token part (everything before first colon, or entire string if no colon)
+    const colonIndex = existingName.indexOf(':')
+    if (colonIndex === -1) {
+      // No colon, just token name: TokenName → TokenName:requestId=req-123
+      return `${existingName}:requestId=${requestId}`
+    }
+
+    // Has colon, means there's an args hash: TokenName:abc123 → TokenName:requestId=req-123:abc123
+    const tokenPart = existingName.substring(0, colonIndex)
+    const argsPart = existingName.substring(colonIndex + 1)
+
+    // Check if argsPart looks like an args hash (not requestId=)
+    if (argsPart.startsWith('requestId=')) {
+      // Already has requestId, return as is
+      return existingName
+    }
+
+    return `${tokenPart}:requestId=${requestId}:${argsPart}`
+  }
+
+  /**
+   * Formats a single argument value for instance name generation.
+   */
+  formatArgValue(value: any): string {
+    if (typeof value === 'function') {
+      return `fn_${value.name}(${value.length})`
+    }
+    if (typeof value === 'symbol') {
+      return value.toString()
+    }
+    return JSON.stringify(value).slice(0, 40)
+  }
+}

package/src/internal/core/scope-tracker.mts

@@ -0,0 +1,242 @@
+import type { InjectableScope } from '../../enums/index.mjs'
+import type { InjectionToken } from '../../token/injection-token.mjs'
+import type { IHolderStorage } from '../holder/holder-storage.interface.mjs'
+
+import { InjectableScope as Scope } from '../../enums/index.mjs'
+import { DIError } from '../../errors/index.mjs'
+import { InstanceStatus } from '../holder/instance-holder.mjs'
+import { Registry } from '../../token/registry.mjs'
+import { NameResolver } from './name-resolver.mjs'
+
+/**
+ * Component for tracking and handling scope upgrades.
+ *
+ * Detects when a Singleton service needs to be upgraded to Request scope
+ * and coordinates the scope upgrade process atomically.
+ */
+export class ScopeTracker {
+  constructor(
+    private readonly registry: Registry,
+    private readonly nameResolver: NameResolver,
+    private readonly logger: Console | null = null,
+  ) {}
+
+  /**
+   * Checks if a dependency requires scope upgrade and performs it if needed.
+   * Called during service resolution when a dependency is resolved.
+   *
+   * @param currentServiceName - Name of the service being created
+   * @param currentServiceScope - Current scope of the service being created
+   * @param dependencyName - Name of the dependency being resolved
+   * @param dependencyScope - Scope of the dependency
+   * @param dependencyToken - Token of the dependency
+   * @param singletonStorage - Singleton storage instance
+   * @param requestStorage - Request storage instance (if in request context)
+   * @param requestId - Request ID (if in request context)
+   * @returns [needsUpgrade: boolean, newName?: string] - whether upgrade occurred and new name
+   */
+  checkAndUpgradeScope(
+    currentServiceName: string,
+    currentServiceScope: InjectableScope,
+    dependencyName: string,
+    dependencyScope: InjectableScope,
+    dependencyToken: InjectionToken<any, any>,
+    singletonStorage: IHolderStorage,
+    requestStorage?: IHolderStorage,
+    requestId?: string,
+  ): [boolean, string?] {
+    // Only upgrade if current service is Singleton and dependency is Request
+    if (
+      currentServiceScope !== Scope.Singleton ||
+      dependencyScope !== Scope.Request
+    ) {
+      return [false]
+    }
+
+    // Need request storage and requestId for upgrade
+    if (!requestStorage || !requestId) {
+      this.logger?.warn(
+        `[ScopeTracker] Cannot upgrade scope for ${currentServiceName}: missing requestStorage or requestId`,
+      )
+      return [false]
+    }
+
+    // Perform the upgrade
+    this.logger?.log(
+      `[ScopeTracker] Upgrading ${currentServiceName} from Singleton to Request scope`,
+    )
+
+    try {
+      const [success, newName] = this.upgradeScopeToRequestSync(
+        currentServiceName,
+        dependencyToken,
+        singletonStorage,
+        requestStorage,
+        requestId,
+      )
+
+      if (success && newName) {
+        return [true, newName]
+      }
+    } catch (error) {
+      this.logger?.error(
+        `[ScopeTracker] Error upgrading scope for ${currentServiceName}:`,
+        error,
+      )
+    }
+
+    return [false]
+  }
+
+  /**
+   * Performs the actual scope upgrade from Singleton to Request.
+   * This is the core migration logic.
+   *
+   * @param serviceName - Current service name (without requestId)
+   * @param token - Service injection token
+   * @param singletonStorage - Source storage
+   * @param requestStorage - Target storage
+   * @param requestId - Request ID to include in new name
+   * @returns [success: boolean, newName?: string, error?: DIError]
+   */
+  async upgradeScopeToRequest(
+    serviceName: string,
+    token: InjectionToken<any, any>,
+    singletonStorage: IHolderStorage,
+    requestStorage: IHolderStorage,
+    requestId: string,
+  ): Promise<[boolean, string?, DIError?]> {
+    try {
+      const [success, newName] = this.upgradeScopeToRequestSync(
+        serviceName,
+        token,
+        singletonStorage,
+        requestStorage,
+        requestId,
+      )
+
+      if (success && newName) {
+        return [true, newName]
+      }
+      return [
+        false,
+        undefined,
+        DIError.storageError(
+          'Scope upgrade failed',
+          'upgradeScopeToRequest',
+          serviceName,
+        ),
+      ]
+    } catch (error) {
+      return [
+        false,
+        undefined,
+        error instanceof DIError ? error : DIError.unknown(error as Error),
+      ]
+    }
+  }
+
+  /**
+   * Synchronous part of scope upgrade - handles immediate updates.
+   * Async operations (like waiting for holder creation) should be done separately.
+   */
+  private upgradeScopeToRequestSync(
+    serviceName: string,
+    token: InjectionToken<any, any>,
+    singletonStorage: IHolderStorage,
+    requestStorage: IHolderStorage,
+    requestId: string,
+  ): [boolean, string?] {
+    // 1. Upgrade existing instance name to include requestId
+    // This preserves any args hash that might be in the original name
+    const newName = this.nameResolver.upgradeInstanceNameToRequest(
+      serviceName,
+      requestId,
+    )
+
+    // 2. Update Registry scope to Request (synchronous)
+    const updated = this.registry.updateScope(token, Scope.Request)
+    if (!updated) {
+      this.logger?.warn(
+        `[ScopeTracker] Could not update scope in registry for ${serviceName}`,
+      )
+      return [false]
+    }
+
+    // 3. Check if holder exists in singleton storage
+    const holderResult = singletonStorage.get(serviceName)
+    if (holderResult === null) {
+      // No holder exists yet - just update registry, future resolutions will use request storage
+      return [true, newName]
+    }
+
+    const [error, holder] = holderResult
+    if (error) {
+      this.logger?.warn(
+        `[ScopeTracker] Holder for ${serviceName} is in error state: ${error.message}`,
+      )
+      return [false]
+    }
+
+    if (!holder) {
+      return [false]
+    }
+
+    // 4. If holder is in "Creating" state, we need to wait for it before migrating
+    // For now, we'll update the name and move it, but the caller should wait for creation
+    if (holder.status === InstanceStatus.Creating) {
+      // Update holder name
+      holder.name = newName
+      // Move to request storage
+      requestStorage.set(newName, holder)
+      // Remove from singleton storage
+      singletonStorage.delete(serviceName)
+      // Update parent dependencies
+      this.updateParentDependencies(
+        serviceName,
+        newName,
+        singletonStorage,
+        requestStorage,
+      )
+      return [true, newName]
+    }
+
+    // 5. Move holder from singleton to request storage
+    holder.name = newName
+    requestStorage.set(newName, holder)
+    singletonStorage.delete(serviceName)
+
+    // 6. Update all parent dependencies
+    this.updateParentDependencies(
+      serviceName,
+      newName,
+      singletonStorage,
+      requestStorage,
+    )
+
+    return [true, newName]
+  }
+
+  /**
+   * Updates all parent dependencies to reference the new service name.
+   *
+   * @param oldName - Original service name
+   * @param newName - New service name with requestId
+   * @param singletonStorage - Singleton storage to check
+   * @param requestStorage - Request storage to check
+   */
+  updateParentDependencies(
+    oldName: string,
+    newName: string,
+    singletonStorage: IHolderStorage,
+    requestStorage?: IHolderStorage,
+  ): void {
+    // Update dependencies in singleton storage
+    singletonStorage.updateDependencyReference(oldName, newName)
+
+    // Update dependencies in request storage if provided
+    if (requestStorage) {
+      requestStorage.updateDependencyReference(oldName, newName)
+    }
+  }
+}

package/src/internal/core/{instantiator.mts → service-initializer.mts}

@@ -1,6 +1,6 @@
 import type { FactoryRecord } from '../../token/registry.mjs'
-import type { Injectors } from '../../utils/get-injectors.mjs'
-import type { FactoryContext } from '../context/factory-context.mjs'
+import type { Injectors } from '../../utils/index.mjs'
+import type { ServiceInitializationContext } from '../context/service-initialization-context.mjs'
 
 import { InjectableType } from '../../enums/index.mjs'
 import { DIError } from '../../errors/index.mjs'
@@ -9,10 +9,9 @@ import { DIError } from '../../errors/index.mjs'
  * Creates service instances from registry records.
  *
  * Handles both class-based (@Injectable) and factory-based (@Factory) services,
- * managing the instantiation lifecycle including sync initialization retries
- * and lifecycle hook invocation (onServiceInit, onServiceDestroy).
+ * managing the instantiation lifecycle including lifecycle hook invocation.
  */
-export class Instantiator {
+export class ServiceInitializer {
   constructor(private readonly injectors: Injectors) {}
 
   /**
@@ -23,7 +22,7 @@ export class Instantiator {
    * @returns Promise resolving to [undefined, instance] or [error]
    */
   async instantiateService<T>(
-    ctx: FactoryContext,
+    ctx: ServiceInitializationContext,
     record: FactoryRecord<T, any>,
     args: any = undefined,
   ): Promise<[undefined, T] | [DIError]> {
@@ -35,11 +34,15 @@ export class Instantiator {
           return this.instantiateFactory(ctx, record, args)
         default:
           throw DIError.unknown(
-            `[Instantiator] Unknown service type: ${record.type}`,
+            `[ServiceInitializer] Unknown service type: ${record.type}`,
           )
       }
     } catch (error) {
-      return [error instanceof DIError ? error : DIError.unknown(String(error))]
+      return [
+        error instanceof DIError
+          ? error
+          : DIError.initializationError(record.target.name, error as Error),
+      ]
     }
   }
 
@@ -51,13 +54,15 @@ export class Instantiator {
    * @returns Promise resolving to [undefined, instance] or [error]
    */
   private async instantiateClass<T>(
-    ctx: FactoryContext,
+    ctx: ServiceInitializationContext,
     record: FactoryRecord<T, any>,
     args: any,
   ): Promise<[undefined, T] | [DIError]> {
     try {
       const tryLoad = this.injectors.wrapSyncInit(() => {
-        const original = this.injectors.provideFactoryContext(ctx)
+        const original = this.injectors.provideFactoryContext(
+          ctx as ServiceInitializationContext,
+        )
         let result = new record.target(...(args ? [args] : []))
         this.injectors.provideFactoryContext(original)
         return result
@@ -67,8 +72,9 @@ export class Instantiator {
       if (promises.length > 0) {
         const results = await Promise.allSettled(promises)
         if (results.some((result) => result.status === 'rejected')) {
-          throw DIError.unknown(
-            `[Instantiator] Service ${record.target.name} cannot be instantiated.`,
+          throw DIError.initializationError(
+            record.target.name,
+            new Error('Service cannot be instantiated'),
           )
         }
         const newRes = tryLoad(injectState)
@@ -77,13 +83,16 @@ export class Instantiator {
       }
 
       if (promises.length > 0) {
-        console.error(`[Instantiator] ${record.target.name} has problem with it's definition.
+        console.error(
+          `[ServiceInitializer] ${record.target.name} has problem with it's definition.
 
-       One or more of the dependencies are registered as a InjectableScope.Instance and are used with inject.
+       One or more of the dependencies are registered as a InjectableScope.Transient and are used with inject.
 
-       Please use inject asyncInject of inject to load those dependencies.`)
-        throw DIError.unknown(
-          `[Instantiator] Service ${record.target.name} cannot be instantiated.`,
+       Please use asyncInject instead of inject to load those dependencies.`,
+        )
+        throw DIError.initializationError(
+          record.target.name,
+          new Error('Service cannot be instantiated'),
         )
       }
 
@@ -99,7 +108,11 @@ export class Instantiator {
 
       return [undefined, instance]
     } catch (error) {
-      return [error instanceof DIError ? error : DIError.unknown(String(error))]
+      return [
+        error instanceof DIError
+          ? error
+          : DIError.initializationError(record.target.name, error as Error),
+      ]
     }
   }
 
@@ -111,7 +124,7 @@ export class Instantiator {
    * @returns Promise resolving to [undefined, instance] or [error]
    */
   private async instantiateFactory<T>(
-    ctx: FactoryContext,
+    ctx: ServiceInitializationContext,
     record: FactoryRecord<T, any>,
     args: any,
   ): Promise<[undefined, T] | [DIError]> {
@@ -127,8 +140,9 @@ export class Instantiator {
       if (promises.length > 0) {
         const results = await Promise.allSettled(promises)
         if (results.some((result) => result.status === 'rejected')) {
-          throw DIError.unknown(
-            `[Instantiator] Service ${record.target.name} cannot be instantiated.`,
+          throw DIError.initializationError(
+            record.target.name,
+            new Error('Service cannot be instantiated'),
           )
         }
         const newRes = tryLoad(injectState)
@@ -137,26 +151,34 @@ export class Instantiator {
       }
 
       if (promises.length > 0) {
-        console.error(`[Instantiator] ${record.target.name} has problem with it's definition.
+        console.error(
+          `[ServiceInitializer] ${record.target.name} has problem with it's definition.
 
-       One or more of the dependencies are registered as a InjectableScope.Instance and are used with inject.
+       One or more of the dependencies are registered as a InjectableScope.Transient and are used with inject.
 
-       Please use asyncInject instead of inject to load those dependencies.`)
-        throw DIError.unknown(
-          `[Instantiator] Service ${record.target.name} cannot be instantiated.`,
+       Please use asyncInject instead of inject to load those dependencies.`,
+        )
+        throw DIError.initializationError(
+          record.target.name,
+          new Error('Service cannot be instantiated'),
         )
       }
 
       if (typeof builder.create !== 'function') {
-        throw DIError.unknown(
-          `[Instantiator] Factory ${record.target.name} does not implement the create method.`,
+        throw DIError.initializationError(
+          record.target.name,
+          new Error('Factory does not implement the create method'),
         )
       }
 
       const instance = await builder.create(ctx, args)
       return [undefined, instance]
     } catch (error) {
-      return [error instanceof DIError ? error : DIError.unknown(String(error))]
+      return [
+        error instanceof DIError
+          ? error
+          : DIError.initializationError(record.target.name, error as Error),
+      ]
     }
   }
 }