@navios/di 0.4.1 → 0.5.0

package/src/request-context-manager.mts

@@ -0,0 +1,149 @@
+import type { RequestContextHolder } from './request-context-holder.mjs'
+
+import { DefaultRequestContextHolder } from './request-context-holder.mjs'
+
+/**
+ * RequestContextManager handles request context lifecycle management.
+ * Extracted from ServiceLocator to improve separation of concerns.
+ */
+export class RequestContextManager {
+  private readonly requestContexts = new Map<string, RequestContextHolder>()
+  private currentRequestContext: RequestContextHolder | null = null
+
+  constructor(private readonly logger: Console | null = null) {}
+
+  /**
+   * Begins a new request context with the given parameters.
+   * @param requestId Unique identifier for this request
+   * @param metadata Optional metadata for the request
+   * @param priority Priority for resolution (higher = more priority)
+   * @returns The created request context holder
+   */
+  beginRequest(
+    requestId: string,
+    metadata?: Record<string, any>,
+    priority: number = 100,
+  ): RequestContextHolder {
+    if (this.requestContexts.has(requestId)) {
+      throw new Error(
+        `[RequestContextManager] Request context ${requestId} already exists`,
+      )
+    }
+
+    const contextHolder = new DefaultRequestContextHolder(
+      requestId,
+      priority,
+      metadata,
+    )
+    this.requestContexts.set(requestId, contextHolder)
+    this.currentRequestContext = contextHolder
+
+    this.logger?.log(
+      `[RequestContextManager] Started request context: ${requestId}`,
+    )
+    return contextHolder
+  }
+
+  /**
+   * Ends a request context and cleans up all associated instances.
+   * @param requestId The request ID to end
+   */
+  async endRequest(requestId: string): Promise<void> {
+    const contextHolder = this.requestContexts.get(requestId)
+    if (!contextHolder) {
+      this.logger?.warn(
+        `[RequestContextManager] Request context ${requestId} not found`,
+      )
+      return
+    }
+
+    this.logger?.log(
+      `[RequestContextManager] Ending request context: ${requestId}`,
+    )
+
+    // Clean up all request-scoped instances
+    const cleanupPromises: Promise<any>[] = []
+    for (const [, holder] of contextHolder.holders) {
+      if (holder.destroyListeners.length > 0) {
+        cleanupPromises.push(
+          Promise.all(holder.destroyListeners.map((listener) => listener())),
+        )
+      }
+    }
+
+    await Promise.all(cleanupPromises)
+
+    // Clear the context
+    contextHolder.clear()
+    this.requestContexts.delete(requestId)
+
+    // Reset current context if it was the one being ended
+    if (this.currentRequestContext === contextHolder) {
+      this.currentRequestContext =
+        Array.from(this.requestContexts.values()).at(-1) ?? null
+    }
+
+    this.logger?.log(
+      `[RequestContextManager] Request context ${requestId} ended`,
+    )
+  }
+
+  /**
+   * Gets the current request context.
+   * @returns The current request context holder or null
+   */
+  getCurrentRequestContext(): RequestContextHolder | null {
+    return this.currentRequestContext
+  }
+
+  /**
+   * Sets the current request context.
+   * @param requestId The request ID to set as current
+   */
+  setCurrentRequestContext(requestId: string): void {
+    const contextHolder = this.requestContexts.get(requestId)
+    if (!contextHolder) {
+      throw new Error(
+        `[RequestContextManager] Request context ${requestId} not found`,
+      )
+    }
+    this.currentRequestContext = contextHolder
+  }
+
+  /**
+   * Gets all request contexts.
+   * @returns Map of request contexts
+   */
+  getRequestContexts(): Map<string, RequestContextHolder> {
+    return this.requestContexts
+  }
+
+  /**
+   * Clears all request contexts.
+   */
+  async clearAllRequestContexts(): Promise<void> {
+    const requestIds = Array.from(this.requestContexts.keys())
+
+    if (requestIds.length === 0) {
+      this.logger?.log('[RequestContextManager] No request contexts to clear')
+      return
+    }
+
+    this.logger?.log(
+      `[RequestContextManager] Clearing ${requestIds.length} request contexts: ${requestIds.join(', ')}`,
+    )
+
+    // Clear request contexts sequentially to avoid race conditions
+    for (const requestId of requestIds) {
+      try {
+        await this.endRequest(requestId)
+      } catch (error) {
+        this.logger?.error(
+          `[RequestContextManager] Error clearing request context ${requestId}:`,
+          error,
+        )
+        // Continue with other request contexts even if one fails
+      }
+    }
+  }
+}

package/src/service-invalidator.mts

@@ -0,0 +1,429 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import type { RequestContextManager } from './request-context-manager.mjs'
+import type { ServiceLocatorEventBus } from './service-locator-event-bus.mjs'
+import type { ServiceLocatorInstanceHolder } from './service-locator-instance-holder.mjs'
+import type { ServiceLocatorManager } from './service-locator-manager.mjs'
+
+import { ServiceLocatorInstanceHolderStatus } from './service-locator-instance-holder.mjs'
+
+export interface ClearAllOptions {
+  /** Whether to also clear request contexts (default: true) */
+  clearRequestContexts?: boolean
+  /** Maximum number of invalidation rounds to prevent infinite loops (default: 10) */
+  maxRounds?: number
+  /** Whether to wait for all services to settle before starting (default: true) */
+  waitForSettlement?: boolean
+}
+
+/**
+ * ServiceInvalidator handles service invalidation, cleanup, and graceful clearing.
+ * Extracted from ServiceLocator to improve separation of concerns.
+ */
+export class ServiceInvalidator {
+  constructor(
+    private readonly manager: ServiceLocatorManager,
+    private readonly requestContextManager: RequestContextManager,
+    private readonly eventBus: ServiceLocatorEventBus,
+    private readonly logger: Console | null = null,
+  ) {}
+
+  /**
+   * Invalidates a service and all its dependencies.
+   */
+  invalidate(service: string, round = 1): Promise<any> {
+    this.logger?.log(
+      `[ServiceInvalidator] Starting invalidation process for ${service}`,
+    )
+    const [, toInvalidate] = this.manager.get(service)
+
+    const promises = []
+    if (toInvalidate) {
+      promises.push(this.invalidateHolder(service, toInvalidate, round))
+    }
+
+    // Also invalidate request-scoped instances that depend on the service or match the service name
+    const requestContexts = this.requestContextManager.getRequestContexts()
+    for (const [requestId, requestContext] of requestContexts.entries()) {
+      const holder = requestContext.get(service)
+      if (holder) {
+        this.logger?.log(
+          `[ServiceInvalidator] Invalidating request-scoped instance ${service} in request ${requestId}`,
+        )
+        promises.push(
+          this.invalidateRequestHolder(requestId, service, holder, round),
+        )
+      }
+    }
+
+    return Promise.all(promises)
+  }
+
+  /**
+   * Gracefully clears all services in the ServiceLocator using invalidation logic.
+   * This method respects service dependencies and ensures proper cleanup order.
+   * Services that depend on others will be invalidated first, then their dependencies.
+   */
+  async clearAll(options: ClearAllOptions = {}): Promise<void> {
+    const {
+      clearRequestContexts = true,
+      maxRounds = 10,
+      waitForSettlement = true,
+    } = options
+
+    this.logger?.log(
+      '[ServiceInvalidator] Starting graceful clearing of all services',
+    )
+
+    // Wait for all services to settle if requested
+    if (waitForSettlement) {
+      this.logger?.log(
+        '[ServiceInvalidator] Waiting for all services to settle...',
+      )
+      await this.ready()
+    }
+
+    // Get all service names that need to be cleared
+    const allServiceNames = this.getAllServiceNames()
+
+    if (allServiceNames.length === 0) {
+      this.logger?.log('[ServiceInvalidator] No singleton services to clear')
+    } else {
+      this.logger?.log(
+        `[ServiceInvalidator] Found ${allServiceNames.length} services to clear: ${allServiceNames.join(', ')}`,
+      )
+
+      // Clear services using dependency-aware invalidation
+      await this.clearServicesWithDependencyAwareness(
+        allServiceNames,
+        maxRounds,
+      )
+    }
+
+    // Clear request contexts if requested
+    if (clearRequestContexts) {
+      await this.requestContextManager.clearAllRequestContexts()
+    }
+
+    this.logger?.log('[ServiceInvalidator] Graceful clearing completed')
+  }
+
+  /**
+   * Waits for all services to settle (either created, destroyed, or error state).
+   */
+  async ready(): Promise<void> {
+    const holders = Array.from(this.manager.filter(() => true)).map(
+      ([, holder]) => holder,
+    )
+    await Promise.all(
+      holders.map((holder) => this.waitForHolderToSettle(holder)),
+    )
+  }
+
+  /**
+   * Invalidates a single holder based on its current status.
+   */
+  private async invalidateHolder(
+    key: string,
+    holder: ServiceLocatorInstanceHolder<any>,
+    round: number,
+  ): Promise<void> {
+    await this.invalidateHolderByStatus(holder, round, {
+      context: key,
+      isRequestScoped: false,
+      onCreationError: () =>
+        this.logger?.error(
+          `[ServiceInvalidator] ${key} creation triggered too many invalidation rounds`,
+        ),
+      onRecursiveInvalidate: () => this.invalidate(key, round + 1),
+      onDestroy: () => this.destroyHolder(key, holder),
+    })
+  }
+
+  /**
+   * Invalidates a request-scoped holder based on its current status.
+   */
+  private async invalidateRequestHolder(
+    requestId: string,
+    instanceName: string,
+    holder: ServiceLocatorInstanceHolder<any>,
+    round: number,
+  ): Promise<void> {
+    await this.invalidateHolderByStatus(holder, round, {
+      context: `Request-scoped ${instanceName} in ${requestId}`,
+      isRequestScoped: true,
+      onCreationError: () =>
+        this.logger?.error(
+          `[ServiceInvalidator] Request-scoped ${instanceName} in ${requestId} creation triggered too many invalidation rounds`,
+        ),
+      onRecursiveInvalidate: () =>
+        this.invalidateRequestHolder(
+          requestId,
+          instanceName,
+          holder,
+          round + 1,
+        ),
+      onDestroy: () =>
+        this.destroyRequestHolder(requestId, instanceName, holder),
+    })
+  }
+
+  /**
+   * Common invalidation logic for holders based on their status.
+   */
+  private async invalidateHolderByStatus(
+    holder: ServiceLocatorInstanceHolder<any>,
+    round: number,
+    options: {
+      context: string
+      isRequestScoped: boolean
+      onCreationError: () => void
+      onRecursiveInvalidate: () => Promise<void>
+      onDestroy: () => Promise<void>
+    },
+  ): Promise<void> {
+    switch (holder.status) {
+      case ServiceLocatorInstanceHolderStatus.Destroying:
+        await holder.destroyPromise
+        break
+
+      case ServiceLocatorInstanceHolderStatus.Creating:
+        await holder.creationPromise
+        if (round > 3) {
+          options.onCreationError()
+          return
+        }
+        await options.onRecursiveInvalidate()
+        break
+
+      default:
+        await options.onDestroy()
+        break
+    }
+  }
+
+  /**
+   * Destroys a holder and cleans up its resources.
+   */
+  private async destroyHolder(
+    key: string,
+    holder: ServiceLocatorInstanceHolder<any>,
+  ): Promise<void> {
+    await this.destroyHolderWithCleanup(holder, {
+      context: key,
+      logMessage: `[ServiceInvalidator] Invalidating ${key} and notifying listeners`,
+      cleanup: () => this.manager.delete(key),
+      eventName: key,
+    })
+  }
+
+  /**
+   * Destroys a request-scoped holder and cleans up its resources.
+   */
+  private async destroyRequestHolder(
+    requestId: string,
+    instanceName: string,
+    holder: ServiceLocatorInstanceHolder<any>,
+  ): Promise<void> {
+    await this.destroyHolderWithCleanup(holder, {
+      context: `Request-scoped ${instanceName} in ${requestId}`,
+      logMessage: `[ServiceInvalidator] Invalidating request-scoped ${instanceName} in ${requestId} and notifying listeners`,
+      cleanup: () => {
+        const requestContext = this.requestContextManager
+          .getRequestContexts()
+          .get(requestId)
+        if (requestContext) {
+          requestContext.delete(instanceName)
+        }
+      },
+      eventName: instanceName,
+    })
+  }
+
+  /**
+   * Common destroy logic for holders with customizable cleanup.
+   */
+  private async destroyHolderWithCleanup(
+    holder: ServiceLocatorInstanceHolder<any>,
+    options: {
+      context: string
+      logMessage: string
+      cleanup: () => void
+      eventName: string
+    },
+  ): Promise<void> {
+    holder.status = ServiceLocatorInstanceHolderStatus.Destroying
+    this.logger?.log(options.logMessage)
+
+    holder.destroyPromise = Promise.all(
+      holder.destroyListeners.map((listener) => listener()),
+    ).then(async () => {
+      holder.destroyListeners = []
+      holder.deps.clear()
+      options.cleanup()
+      await this.emitInstanceEvent(options.eventName, 'destroy')
+    })
+
+    await holder.destroyPromise
+  }
+
+  /**
+   * Waits for a holder to settle (either created, destroyed, or error state).
+   */
+  private async waitForHolderToSettle(
+    holder: ServiceLocatorInstanceHolder<any>,
+  ): Promise<void> {
+    switch (holder.status) {
+      case ServiceLocatorInstanceHolderStatus.Creating:
+        await holder.creationPromise
+        break
+      case ServiceLocatorInstanceHolderStatus.Destroying:
+        await holder.destroyPromise
+        break
+      // Already settled states
+      case ServiceLocatorInstanceHolderStatus.Created:
+      case ServiceLocatorInstanceHolderStatus.Error:
+        break
+    }
+  }
+
+  /**
+   * Clears services with dependency awareness, ensuring proper cleanup order.
+   * Services with no dependencies are cleared first, then services that depend on them.
+   */
+  private async clearServicesWithDependencyAwareness(
+    serviceNames: string[],
+    maxRounds: number,
+  ): Promise<void> {
+    const clearedServices = new Set<string>()
+    let round = 1
+
+    while (clearedServices.size < serviceNames.length && round <= maxRounds) {
+      this.logger?.log(
+        `[ServiceInvalidator] Clearing round ${round}/${maxRounds}, ${clearedServices.size}/${serviceNames.length} services cleared`,
+      )
+
+      // Find services that can be cleared in this round
+      const servicesToClearThisRound = this.findServicesReadyForClearing(
+        serviceNames,
+        clearedServices,
+      )
+
+      if (servicesToClearThisRound.length === 0) {
+        // If no services can be cleared, try to clear remaining services anyway
+        // This handles circular dependencies or other edge cases
+        const remainingServices = serviceNames.filter(
+          (name) => !clearedServices.has(name),
+        )
+
+        if (remainingServices.length > 0) {
+          this.logger?.warn(
+            `[ServiceInvalidator] No services ready for clearing, forcing cleanup of remaining: ${remainingServices.join(', ')}`,
+          )
+          await this.forceClearServices(remainingServices)
+          remainingServices.forEach((name) => clearedServices.add(name))
+        }
+        break
+      }
+
+      // Clear services in this round
+      const clearPromises = servicesToClearThisRound.map(
+        async (serviceName) => {
+          try {
+            await this.invalidate(serviceName, round)
+            clearedServices.add(serviceName)
+            this.logger?.log(
+              `[ServiceInvalidator] Successfully cleared service: ${serviceName}`,
+            )
+          } catch (error) {
+            this.logger?.error(
+              `[ServiceInvalidator] Error clearing service ${serviceName}:`,
+              error,
+            )
+            // Still mark as cleared to avoid infinite loops
+            clearedServices.add(serviceName)
+          }
+        },
+      )
+
+      await Promise.all(clearPromises)
+      round++
+    }
+
+    if (clearedServices.size < serviceNames.length) {
+      this.logger?.warn(
+        `[ServiceInvalidator] Clearing completed after ${maxRounds} rounds, but ${serviceNames.length - clearedServices.size} services may not have been properly cleared`,
+      )
+    }
+  }
+
+  /**
+   * Finds services that are ready to be cleared in the current round.
+   * A service is ready if all its dependencies have already been cleared.
+   */
+  private findServicesReadyForClearing(
+    allServiceNames: string[],
+    clearedServices: Set<string>,
+  ): string[] {
+    return allServiceNames.filter((serviceName) => {
+      if (clearedServices.has(serviceName)) {
+        return false // Already cleared
+      }
+
+      // Check if this service has any dependencies that haven't been cleared yet
+      const [error, holder] = this.manager.get(serviceName)
+      if (error) {
+        return true // Service not found or in error state, can be cleared
+      }
+
+      // Check if all dependencies have been cleared
+      const hasUnclearedDependencies = Array.from(holder.deps).some(
+        (dep) => !clearedServices.has(dep),
+      )
+
+      return !hasUnclearedDependencies
+    })
+  }
+
+  /**
+   * Force clears services that couldn't be cleared through normal dependency resolution.
+   * This handles edge cases like circular dependencies.
+   */
+  private async forceClearServices(serviceNames: string[]): Promise<void> {
+    const promises = serviceNames.map(async (serviceName) => {
+      try {
+        // Directly destroy the holder without going through normal invalidation
+        const [error, holder] = this.manager.get(serviceName)
+        if (!error && holder) {
+          await this.destroyHolder(serviceName, holder)
+        }
+      } catch (error) {
+        this.logger?.error(
+          `[ServiceInvalidator] Error force clearing service ${serviceName}:`,
+          error,
+        )
+      }
+    })
+
+    await Promise.all(promises)
+  }
+
+  /**
+   * Gets all service names currently managed by the ServiceLocator.
+   */
+  private getAllServiceNames(): string[] {
+    return this.manager.getAllNames()
+  }
+
+  /**
+   * Emits events to listeners for instance lifecycle events.
+   */
+  private emitInstanceEvent(
+    name: string,
+    event: 'create' | 'destroy' = 'create',
+  ) {
+    this.logger?.log(
+      `[ServiceInvalidator]#emitInstanceEvent() Notifying listeners for ${name} with event ${event}`,
+    )
+    return this.eventBus.emit(name, event)
+  }
+}

package/src/service-locator-instance-holder.mts

@@ -22,7 +22,6 @@ export interface ServiceLocatorInstanceHolderCreating<Instance> {
   deps: Set<string>
   destroyListeners: ServiceLocatorInstanceDestroyListener[]
   createdAt: number
-  ttl: number
 }
 
 export interface ServiceLocatorInstanceHolderCreated<Instance> {
@@ -36,7 +35,6 @@ export interface ServiceLocatorInstanceHolderCreated<Instance> {
   deps: Set<string>
   destroyListeners: ServiceLocatorInstanceDestroyListener[]
   createdAt: number
-  ttl: number
 }
 
 export interface ServiceLocatorInstanceHolderDestroying<Instance> {
@@ -50,7 +48,6 @@ export interface ServiceLocatorInstanceHolderDestroying<Instance> {
   deps: Set<string>
   destroyListeners: ServiceLocatorInstanceDestroyListener[]
   createdAt: number
-  ttl: number
 }
 
 export interface ServiceLocatorInstanceHolderError {
@@ -64,7 +61,6 @@ export interface ServiceLocatorInstanceHolderError {
   deps: Set<string>
   destroyListeners: ServiceLocatorInstanceDestroyListener[]
   createdAt: number
-  ttl: number
 }
 
 export type ServiceLocatorInstanceHolder<Instance = unknown> =