@navios/di 0.8.0 → 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-resolver.mts

@@ -0,0 +1,122 @@
+import type {
+  AnyInjectableType,
+  InjectionTokenType,
+} from '../../token/injection-token.mjs'
+
+import { DIError } from '../../errors/index.mjs'
+import {
+  BoundInjectionToken,
+  FactoryInjectionToken,
+  InjectionToken,
+} from '../../token/injection-token.mjs'
+import { getInjectableToken } from '../../utils/index.mjs'
+
+/**
+ * Handles token validation and resolution.
+ *
+ * Focuses on token validation, normalization, and argument validation.
+ * Name generation is handled by NameResolver.
+ */
+export class TokenResolver {
+  constructor(private readonly logger: Console | null = null) {}
+
+  // ============================================================================
+  // TOKEN NORMALIZATION
+  // ============================================================================
+
+  /**
+   * Normalizes a token to an InjectionToken.
+   * Handles class constructors by getting their injectable token.
+   *
+   * @param token A class constructor, InjectionToken, BoundInjectionToken, or FactoryInjectionToken
+   * @returns The normalized InjectionTokenType
+   */
+  normalizeToken(token: AnyInjectableType): InjectionTokenType {
+    if (typeof token === 'function') {
+      return getInjectableToken(token)
+    }
+    return token as InjectionTokenType
+  }
+
+  /**
+   * Gets the underlying "real" token from wrapped tokens.
+   * For BoundInjectionToken and FactoryInjectionToken, returns the wrapped token.
+   * For other tokens, returns the token itself.
+   *
+   * @param token The token to unwrap
+   * @returns The underlying InjectionToken
+   */
+  getRealToken<T = unknown>(token: InjectionTokenType): InjectionToken<T> {
+    if (
+      token instanceof BoundInjectionToken ||
+      token instanceof FactoryInjectionToken
+    ) {
+      return token.token as InjectionToken<T>
+    }
+    return token as InjectionToken<T>
+  }
+
+  /**
+   * Convenience method that normalizes a token and then gets the real token.
+   * Useful for checking registry entries where you need the actual registered token.
+   *
+   * @param token Any injectable type
+   * @returns The underlying InjectionToken
+   */
+  getRegistryToken<T = unknown>(token: AnyInjectableType): InjectionToken<T> {
+    return this.getRealToken(this.normalizeToken(token))
+  }
+
+  // ============================================================================
+  // TOKEN VALIDATION
+  // ============================================================================
+
+  /**
+   * 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,
+    args?: any,
+  ): [
+    DIError | undefined,
+    { actualToken: InjectionTokenType; validatedArgs?: any },
+  ] {
+    let actualToken = token as InjectionToken<any, any>
+    if (typeof token === 'function') {
+      actualToken = getInjectableToken(token)
+    }
+    let realArgs = args
+    if (actualToken instanceof BoundInjectionToken) {
+      realArgs = actualToken.value
+    } else if (actualToken instanceof FactoryInjectionToken) {
+      if (actualToken.resolved) {
+        realArgs = actualToken.value
+      } else {
+        return [DIError.factoryTokenNotResolved(token.name), { actualToken }]
+      }
+    }
+    if (!actualToken.schema) {
+      return [undefined, { actualToken, validatedArgs: realArgs }]
+    }
+    const validatedArgs = actualToken.schema?.safeParse(realArgs)
+    if (validatedArgs && !validatedArgs.success) {
+      this.logger?.error(
+        `[TokenResolver]#validateAndResolveTokenArgs(): Error validating args for ${actualToken.name.toString()}`,
+        validatedArgs.error,
+      )
+      return [
+        DIError.tokenValidationError(
+          `Validation failed for ${actualToken.name.toString()}`,
+          actualToken.schema,
+          realArgs,
+        ),
+        { actualToken },
+      ]
+    }
+    return [undefined, { actualToken, validatedArgs: validatedArgs?.data }]
+  }
+}

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
+