@navios/di 0.7.1 → 0.9.0

package/src/internal/core/service-invalidator.mts

@@ -0,0 +1,290 @@
+import type { IHolderStorage } from '../holder/holder-storage.interface.mjs'
+import type { InstanceHolder } from '../holder/instance-holder.mjs'
+import type { LifecycleEventBus } from '../lifecycle/lifecycle-event-bus.mjs'
+
+import { InstanceStatus } from '../holder/instance-holder.mjs'
+
+export interface ClearAllOptions {
+  /** Whether to wait for all services to settle before starting (default: true) */
+  waitForSettlement?: boolean
+}
+
+export interface InvalidationOptions {
+  /** Whether to emit events after invalidation (default: true) */
+  emitEvents?: boolean
+  /** Custom event emitter function */
+  onInvalidated?: (instanceName: string) => Promise<void>
+  /** Whether to cascade invalidation to dependents (default: false - events handle it) */
+  cascade?: boolean
+}
+
+/**
+ * Manages graceful service cleanup with event-based invalidation.
+ *
+ * Uses event subscriptions instead of manual dependent finding.
+ * When a service is created, it subscribes to destroy events of its dependencies.
+ * When a dependency is destroyed, the event automatically invalidates dependents.
+ */
+export class ServiceInvalidator {
+  constructor(
+    private readonly eventBus: LifecycleEventBus | null,
+    private readonly logger: Console | null = null,
+  ) {}
+
+  /**
+   * Invalidates a service using a specific storage.
+   * Event-based invalidation means dependents are automatically invalidated
+   * via destroy event subscriptions - no need to manually find dependents.
+   *
+   * @param service The instance name to invalidate
+   * @param storage The storage to use for this invalidation
+   * @param options Additional options for invalidation behavior
+   */
+  async invalidateWithStorage(
+    service: string,
+    storage: IHolderStorage,
+    options: InvalidationOptions = {},
+  ): Promise<void> {
+    const { emitEvents = true, onInvalidated } = options
+
+    this.logger?.log(
+      `[ServiceInvalidator] Starting invalidation process for ${service}`,
+    )
+
+    const result = storage.get(service)
+    if (result === null) {
+      return
+    }
+
+    const [, holder] = result
+    if (holder) {
+      await this.invalidateHolderWithStorage(
+        service,
+        holder,
+        storage,
+        emitEvents,
+        onInvalidated,
+      )
+    }
+  }
+
+  /**
+   * Sets up destroy event subscriptions for a service's dependencies.
+   * Called when a service is successfully instantiated.
+   *
+   * @param serviceName The name of the service
+   * @param dependencies The set of dependency names
+   * @param storage The storage to use for invalidation
+   * @param holder The holder for the service (to add unsubscribe to destroy listeners)
+   */
+  setupDependencySubscriptions(
+    serviceName: string,
+    dependencies: Set<string>,
+    storage: IHolderStorage,
+    holder: InstanceHolder,
+  ): void {
+    if (!this.eventBus) {
+      return
+    }
+
+    for (const dependencyName of dependencies) {
+      // Subscribe to the dependency's destroy event
+      const unsubscribe = this.eventBus.on(dependencyName, 'destroy', () => {
+        this.logger?.log(
+          `[ServiceInvalidator] Dependency ${dependencyName} destroyed, invalidating ${serviceName}`,
+        )
+        // Automatically invalidate this service when dependency is destroyed
+        this.invalidateWithStorage(serviceName, storage).catch((error) => {
+          this.logger?.error(
+            `[ServiceInvalidator] Error invalidating ${serviceName} after dependency ${dependencyName} destroyed:`,
+            error,
+          )
+        })
+      })
+
+      // Store unsubscribe function in the service's destroy listeners
+      // so it's cleaned up when the service is destroyed
+      holder.destroyListeners.push(unsubscribe)
+    }
+  }
+
+  /**
+   * Gracefully clears all services in a specific storage.
+   * This allows clearing request-scoped services using a RequestStorage.
+   */
+  async clearAllWithStorage(
+    storage: IHolderStorage,
+    options: ClearAllOptions = {},
+  ): Promise<void> {
+    const { 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.readyWithStorage(storage)
+    }
+
+    // Get all service names that need to be cleared
+    const allServiceNames = storage.getAllNames()
+
+    if (allServiceNames.length === 0) {
+      this.logger?.log('[ServiceInvalidator] No services to clear')
+    } else {
+      this.logger?.log(
+        `[ServiceInvalidator] Found ${allServiceNames.length} services to clear: ${allServiceNames.join(', ')}`,
+      )
+
+      // Clear services - events will handle dependent invalidation
+      const clearPromises = allServiceNames.map((serviceName) =>
+        this.invalidateWithStorage(serviceName, storage),
+      )
+
+      await Promise.all(clearPromises)
+    }
+
+    this.logger?.log('[ServiceInvalidator] Graceful clearing completed')
+  }
+
+  /**
+   * Waits for all services in a specific storage to settle.
+   */
+  async readyWithStorage(storage: IHolderStorage): Promise<void> {
+    const holders: InstanceHolder<any>[] = []
+    storage.forEach((_: string, holder: InstanceHolder) => holders.push(holder))
+    await Promise.all(
+      holders.map((holder) => this.waitForHolderToSettle(holder)),
+    )
+  }
+
+  // ============================================================================
+  // INTERNAL INVALIDATION HELPERS
+  // ============================================================================
+
+  /**
+   * Invalidates a single holder using a specific storage.
+   */
+  private async invalidateHolderWithStorage(
+    key: string,
+    holder: InstanceHolder<any>,
+    storage: IHolderStorage,
+    emitEvents: boolean,
+    onInvalidated?: (instanceName: string) => Promise<void>,
+  ): Promise<void> {
+    await this.invalidateHolderByStatus(holder, {
+      context: key,
+      onDestroy: () =>
+        this.destroyHolderWithStorage(
+          key,
+          holder,
+          storage,
+          emitEvents,
+          onInvalidated,
+        ),
+    })
+  }
+
+  /**
+   * Common invalidation logic for holders based on their status.
+   */
+  private async invalidateHolderByStatus(
+    holder: InstanceHolder<any>,
+    options: {
+      context: string
+      onDestroy: () => Promise<void>
+    },
+  ): Promise<void> {
+    switch (holder.status) {
+      case InstanceStatus.Destroying:
+        await holder.destroyPromise
+        break
+
+      case InstanceStatus.Creating:
+        // Wait for creation to complete before destroying
+        await holder.creationPromise
+        await options.onDestroy()
+        break
+
+      default:
+        await options.onDestroy()
+        break
+    }
+  }
+
+  /**
+   * Destroys a holder using a specific storage.
+   */
+  private async destroyHolderWithStorage(
+    key: string,
+    holder: InstanceHolder<any>,
+    storage: IHolderStorage,
+    emitEvents: boolean,
+    onInvalidated?: (instanceName: string) => Promise<void>,
+  ): Promise<void> {
+    holder.status = InstanceStatus.Destroying
+    this.logger?.log(
+      `[ServiceInvalidator] Invalidating ${key} and notifying listeners`,
+    )
+
+    holder.destroyPromise = Promise.all(
+      holder.destroyListeners.map((listener) => listener()),
+    ).then(async () => {
+      holder.destroyListeners = []
+      holder.deps.clear()
+      storage.delete(key)
+
+      // Emit events if enabled and event bus exists
+      if (emitEvents && this.eventBus) {
+        await this.emitInstanceEvent(key, 'destroy')
+      }
+
+      // Call custom callback if provided
+      if (onInvalidated) {
+        await onInvalidated(key)
+      }
+    })
+
+    await holder.destroyPromise
+  }
+
+  /**
+   * Waits for a holder to settle (either created, destroyed, or error state).
+   */
+  private async waitForHolderToSettle(
+    holder: InstanceHolder<any>,
+  ): Promise<void> {
+    switch (holder.status) {
+      case InstanceStatus.Creating:
+        await holder.creationPromise
+        break
+      case InstanceStatus.Destroying:
+        await holder.destroyPromise
+        break
+      // Already settled states
+      case InstanceStatus.Created:
+      case InstanceStatus.Error:
+        break
+    }
+  }
+
+  /**
+   * Emits events to listeners for instance lifecycle events.
+   */
+  private emitInstanceEvent(
+    name: string,
+    event: 'create' | 'destroy' = 'create',
+  ) {
+    if (!this.eventBus) {
+      return Promise.resolve()
+    }
+    this.logger?.log(
+      `[ServiceInvalidator]#emitInstanceEvent() Notifying listeners for ${name} with event ${event}`,
+    )
+    return this.eventBus.emit(name, event)
+  }
+}

package/src/internal/core/{token-processor.mts → token-resolver.mts}

@@ -1,12 +1,7 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
-/* eslint-disable @typescript-eslint/no-empty-object-type */
-
-import type { FactoryContext } from '../context/factory-context.mjs'
 import type {
   AnyInjectableType,
   InjectionTokenType,
 } from '../../token/injection-token.mjs'
-import type { IContainer } from '../../interfaces/container.interface.mjs'
 
 import { DIError } from '../../errors/index.mjs'
 import {
@@ -17,12 +12,12 @@ import {
 import { getInjectableToken } from '../../utils/index.mjs'
 
 /**
- * Handles token validation, normalization, and instance name generation.
+ * Handles token validation and resolution.
  *
- * Provides utilities for resolving tokens to their underlying InjectionToken,
- * validating arguments against schemas, and generating unique instance identifiers.
+ * Focuses on token validation, normalization, and argument validation.
+ * Name generation is handled by NameResolver.
  */
-export class TokenProcessor {
+export class TokenResolver {
   constructor(private readonly logger: Console | null = null) {}
 
   // ============================================================================
@@ -78,6 +73,10 @@ export class TokenProcessor {
 
   /**
    * Validates and resolves token arguments, handling factory token resolution and validation.
+   *
+   * @param token The token to validate
+   * @param args Optional arguments
+   * @returns [error, { actualToken, validatedArgs }]
    */
   validateAndResolveTokenArgs(
     token: AnyInjectableType,
@@ -106,88 +105,18 @@ export class TokenProcessor {
     const validatedArgs = actualToken.schema?.safeParse(realArgs)
     if (validatedArgs && !validatedArgs.success) {
       this.logger?.error(
-        `[TokenProcessor]#validateAndResolveTokenArgs(): Error validating args for ${actualToken.name.toString()}`,
+        `[TokenResolver]#validateAndResolveTokenArgs(): Error validating args for ${actualToken.name.toString()}`,
         validatedArgs.error,
       )
-      return [DIError.unknown(validatedArgs.error), { actualToken }]
+      return [
+        DIError.tokenValidationError(
+          `Validation failed for ${actualToken.name.toString()}`,
+          actualToken.schema,
+          realArgs,
+        ),
+        { actualToken },
+      ]
     }
     return [undefined, { actualToken, validatedArgs: validatedArgs?.data }]
   }
-
-  /**
-   * Generates a unique instance name based on token and arguments.
-   */
-  generateInstanceName(token: InjectionTokenType, args: any): string {
-    if (!args) {
-      return token.toString()
-    }
-
-    const formattedArgs = Object.entries(args)
-      .sort(([keyA], [keyB]) => keyA.localeCompare(keyB))
-      .map(([key, value]) => `${key}=${this.formatArgValue(value)}`)
-      .join(',')
-
-    return `${token.toString()}:${formattedArgs.replaceAll(/"/g, '').replaceAll(/:/g, '=')}`
-  }
-
-  /**
-   * 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)
-  }
-
-  /**
-   * Creates a factory context for dependency injection during service instantiation.
-   * @param container The container instance (Container or ScopedContainer) for dependency resolution
-   * @param onDependencyResolved Callback when a dependency is resolved, receives the instance name
-   */
-  createFactoryContext(
-    container: IContainer,
-    onDependencyResolved?: (instanceName: string) => void,
-  ): FactoryContext & {
-    getDestroyListeners: () => (() => void)[]
-    deps: Set<string>
-  } {
-    const destroyListeners = new Set<() => void>()
-    const deps = new Set<string>()
-
-    function addDestroyListener(listener: () => void) {
-      destroyListeners.add(listener)
-    }
-
-    function getDestroyListeners() {
-      return Array.from(destroyListeners)
-    }
-
-    const self = this
-
-    return {
-      // @ts-expect-error This is correct type
-      async inject(token, args) {
-        // Get the instance name for dependency tracking
-        const actualToken =
-          typeof token === 'function' ? getInjectableToken(token) : token
-        const instanceName = self.generateInstanceName(actualToken, args)
-        deps.add(instanceName)
-
-        if (onDependencyResolved) {
-          onDependencyResolved(instanceName)
-        }
-
-        // Use the container's get method for resolution
-        return container.get(token, args)
-      },
-      addDestroyListener,
-      getDestroyListeners,
-      container,
-      deps,
-    }
-  }
 }

package/src/internal/holder/holder-storage.interface.mts

@@ -17,8 +17,7 @@ export type HolderGetResult<T = unknown> =
  * Interface for abstracting holder storage operations.
  *
  * Enables unified instance resolution logic regardless of where
- * holders are stored (singleton manager, request context, etc.).
- * This is the key abstraction for the Storage Strategy pattern.
+ * holders are stored. This is the key abstraction for the unified storage pattern.
  */
 export interface IHolderStorage {
   /**
@@ -94,9 +93,7 @@ export interface IHolderStorage {
    *
    * @param callback Function called for each holder with (name, holder)
    */
-  forEach(
-    callback: (name: string, holder: InstanceHolder) => void,
-  ): void
+  forEach(callback: (name: string, holder: InstanceHolder) => void): void
 
   /**
    * Finds a holder by its instance value (reverse lookup).
@@ -113,4 +110,13 @@ export interface IHolderStorage {
    * @returns Array of instance names that have this instance as a dependency
    */
   findDependents(instanceName: string): string[]
+
+  /**
+   * Updates dependency references when instance names change.
+   * Used during scope upgrades when instance names are regenerated with requestId.
+   *
+   * @param oldName The old instance name
+   * @param newName The new instance name
+   */
+  updateDependencyReference(oldName: string, newName: string): void
 }

package/src/internal/holder/index.mts

@@ -1,6 +1,3 @@
-export * from './instance-holder.mjs'
-export * from './base-holder-manager.mjs'
-export * from './holder-manager.mjs'
 export * from './holder-storage.interface.mjs'
-export * from './singleton-storage.mjs'
-export * from './request-storage.mjs'
+export * from './instance-holder.mjs'
+export * from './unified-storage.mjs'

package/src/internal/holder/instance-holder.mts

@@ -14,9 +14,6 @@ export enum InstanceStatus {
   Error = 'error',
 }
 
-/** Callback function for instance effects */
-export type InstanceEffect = () => void
-
 /** Callback function for instance destruction listeners */
 export type InstanceDestroyListener = () => void | Promise<void>
 
@@ -107,3 +104,4 @@ export type InstanceHolder<Instance = unknown> =
   | InstanceHolderCreated<Instance>
   | InstanceHolderDestroying<Instance>
   | InstanceHolderError
+