@navios/di 0.5.1 → 0.6.1

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

@@ -0,0 +1,202 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/* eslint-disable @typescript-eslint/no-empty-object-type */
+import type { z, ZodObject, ZodOptional } from 'zod/v4'
+
+import type {
+  AnyInjectableType,
+  InjectionTokenSchemaType,
+} from '../../token/injection-token.mjs'
+import type { IContainer } from '../../interfaces/container.interface.mjs'
+import type { Registry } from '../../token/registry.mjs'
+import type { ScopedContainer } from '../../container/scoped-container.mjs'
+import type { ClearAllOptions } from './invalidator.mjs'
+import type { Injectors } from '../../utils/index.mjs'
+
+import { defaultInjectors } from '../../injectors.mjs'
+import { InstanceResolver } from './instance-resolver.mjs'
+import { globalRegistry } from '../../token/registry.mjs'
+import { Instantiator } from './instantiator.mjs'
+import { Invalidator } from './invalidator.mjs'
+import { LifecycleEventBus } from '../lifecycle/lifecycle-event-bus.mjs'
+import { HolderManager } from '../holder/holder-manager.mjs'
+import { TokenProcessor } from './token-processor.mjs'
+
+/**
+ * Core DI engine that coordinates service instantiation, resolution, and lifecycle.
+ *
+ * Acts as the central orchestrator for dependency injection operations,
+ * delegating to specialized components (InstanceResolver, Instantiator, Invalidator)
+ * for specific tasks.
+ */
+export class ServiceLocator {
+  private readonly eventBus: LifecycleEventBus
+  private readonly manager: HolderManager
+  private readonly instantiator: Instantiator
+  private readonly tokenProcessor: TokenProcessor
+  private readonly invalidator: Invalidator
+  private readonly instanceResolver: InstanceResolver
+
+  constructor(
+    private readonly registry: Registry = globalRegistry,
+    private readonly logger: Console | null = null,
+    private readonly injectors: Injectors = defaultInjectors,
+  ) {
+    this.eventBus = new LifecycleEventBus(logger)
+    this.manager = new HolderManager(logger)
+    this.instantiator = new Instantiator(injectors)
+    this.tokenProcessor = new TokenProcessor(logger)
+    this.invalidator = new Invalidator(
+      this.manager,
+      this.eventBus,
+      logger,
+    )
+    this.instanceResolver = new InstanceResolver(
+      this.registry,
+      this.manager,
+      this.instantiator,
+      this.tokenProcessor,
+      logger,
+      this,
+    )
+  }
+
+  // ============================================================================
+  // PUBLIC METHODS
+  // ============================================================================
+
+  getEventBus() {
+    return this.eventBus
+  }
+
+  getManager() {
+    return this.manager
+  }
+
+  getInvalidator() {
+    return this.invalidator
+  }
+
+  getTokenProcessor() {
+    return this.tokenProcessor
+  }
+
+  public getInstanceIdentifier(token: AnyInjectableType, args?: any): string {
+    const [err, { actualToken, validatedArgs }] =
+      this.tokenProcessor.validateAndResolveTokenArgs(token, args)
+    if (err) {
+      throw err
+    }
+    return this.tokenProcessor.generateInstanceName(actualToken, validatedArgs)
+  }
+
+  /**
+   * Gets or creates an instance for the given token.
+   * @param token The injection token
+   * @param args Optional arguments
+   * @param contextContainer The container to use for creating FactoryContext
+   */
+  public async getInstance(
+    token: AnyInjectableType,
+    args: any,
+    contextContainer: IContainer,
+  ) {
+    const [err, data] = await this.instanceResolver.resolveInstance(
+      token,
+      args,
+      contextContainer,
+    )
+    if (err) {
+      return [err]
+    }
+
+    return [undefined, data]
+  }
+
+  /**
+   * Gets or throws an instance for the given token.
+   * @param token The injection token
+   * @param args Optional arguments
+   * @param contextContainer The container to use for creating FactoryContext
+   */
+  public async getOrThrowInstance<Instance>(
+    token: AnyInjectableType,
+    args: any,
+    contextContainer: IContainer,
+  ): Promise<Instance> {
+    const [error, instance] = await this.getInstance(token, args, contextContainer)
+    if (error) {
+      throw error
+    }
+    return instance
+  }
+
+  /**
+   * Resolves a request-scoped service for a ScopedContainer.
+   * The service will be stored in the ScopedContainer's request context.
+   *
+   * @param token The injection token
+   * @param args Optional arguments
+   * @param scopedContainer The ScopedContainer that owns the request context
+   */
+  public async resolveRequestScoped(
+    token: AnyInjectableType,
+    args: any,
+    scopedContainer: ScopedContainer,
+  ): Promise<any> {
+    const [err, data] = await this.instanceResolver.resolveRequestScopedInstance(
+      token,
+      args,
+      scopedContainer,
+    )
+    if (err) {
+      throw err
+    }
+    return data
+  }
+
+  public getSyncInstance<
+    Instance,
+    Schema extends InjectionTokenSchemaType | undefined,
+  >(
+    token: AnyInjectableType,
+    args: Schema extends ZodObject
+      ? z.input<Schema>
+      : Schema extends ZodOptional<ZodObject>
+        ? z.input<Schema> | undefined
+        : undefined,
+    contextContainer: IContainer,
+  ): Instance | null {
+    return this.instanceResolver.getSyncInstance(token, args as any, contextContainer)
+  }
+
+  invalidate(service: string, round = 1): Promise<any> {
+    return this.invalidator.invalidate(service, round)
+  }
+
+  /**
+   * 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.
+   *
+   * @param options Optional configuration for the clearing process
+   * @returns Promise that resolves when all services have been cleared
+   */
+  async clearAll(options: ClearAllOptions = {}): Promise<void> {
+    return this.invalidator.clearAll(options)
+  }
+
+  /**
+   * Waits for all services to settle (either created, destroyed, or error state).
+   */
+  async ready(): Promise<void> {
+    return this.invalidator.ready()
+  }
+
+  /**
+   * Helper method for InstanceResolver to generate instance names.
+   * This is needed for the factory context creation.
+   */
+  generateInstanceName(token: any, args: any): string {
+    return this.tokenProcessor.generateInstanceName(token, args)
+  }
+}

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

@@ -1,29 +1,81 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 /* eslint-disable @typescript-eslint/no-empty-object-type */
 
-import type { FactoryContext } from './factory-context.mjs'
+import type { FactoryContext } from '../context/factory-context.mjs'
 import type {
   AnyInjectableType,
   InjectionTokenType,
-} from './injection-token.mjs'
-import type { RequestContextHolder } from './request-context-holder.mjs'
-import type { ServiceLocator } from './service-locator.mjs'
+} from '../../token/injection-token.mjs'
+import type { IContainer } from '../../interfaces/container.interface.mjs'
 
-import { DIError } from './errors/index.mjs'
+import { DIError } from '../../errors/index.mjs'
 import {
   BoundInjectionToken,
   FactoryInjectionToken,
   InjectionToken,
-} from './injection-token.mjs'
-import { getInjectableToken } from './utils/index.mjs'
+} from '../../token/injection-token.mjs'
+import { getInjectableToken } from '../../utils/index.mjs'
 
 /**
- * TokenProcessor handles token validation, resolution, and instance name generation.
- * Extracted from ServiceLocator to improve separation of concerns.
+ * Handles token validation, normalization, and instance name generation.
+ *
+ * Provides utilities for resolving tokens to their underlying InjectionToken,
+ * validating arguments against schemas, and generating unique instance identifiers.
  */
 export class TokenProcessor {
   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.
    */
@@ -93,10 +145,12 @@ export class TokenProcessor {
 
   /**
    * Creates a factory context for dependency injection during service instantiation.
-   * @param serviceLocator Reference to the service locator for dependency resolution
+   * @param container The container instance (Container or ScopedContainer) for dependency resolution
+   * @param onDependencyResolved Callback when a dependency is resolved, receives the instance name
    */
   createFactoryContext(
-    serviceLocator: ServiceLocator, // ServiceLocator reference for dependency resolution
+    container: IContainer,
+    onDependencyResolved?: (instanceName: string) => void,
   ): FactoryContext & {
     getDestroyListeners: () => (() => void)[]
     deps: Set<string>
@@ -112,63 +166,28 @@ export class TokenProcessor {
       return Array.from(destroyListeners)
     }
 
+    const self = this
+
     return {
       // @ts-expect-error This is correct type
       async inject(token, args) {
-        // Fall back to normal resolution
-        const [error, instance] = await serviceLocator.getInstance(
-          token,
-          args,
-          ({ instanceName }: { instanceName: string }) => {
-            deps.add(instanceName)
-          },
-        )
-        if (error) {
-          throw error
+        // 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)
         }
-        return instance
+
+        // Use the container's get method for resolution
+        return container.get(token, args)
       },
       addDestroyListener,
       getDestroyListeners,
-      locator: serviceLocator,
+      container,
       deps,
     }
   }
-
-  /**
-   * Tries to get a pre-prepared instance from request contexts.
-   */
-  tryGetPrePreparedInstance(
-    instanceName: string,
-    contextHolder: RequestContextHolder | undefined,
-    deps: Set<string>,
-    currentRequestContext: RequestContextHolder | null,
-  ): any {
-    // Check provided context holder first (if has higher priority)
-    if (contextHolder && contextHolder.priority > 0) {
-      const prePreparedInstance = contextHolder.get(instanceName)?.instance
-      if (prePreparedInstance !== undefined) {
-        this.logger?.debug(
-          `[TokenProcessor] Using pre-prepared instance ${instanceName} from request context ${contextHolder.requestId}`,
-        )
-        deps.add(instanceName)
-        return prePreparedInstance
-      }
-    }
-
-    // Check current request context (if different from provided contextHolder)
-    if (currentRequestContext && currentRequestContext !== contextHolder) {
-      const prePreparedInstance =
-        currentRequestContext.get(instanceName)?.instance
-      if (prePreparedInstance !== undefined) {
-        this.logger?.debug(
-          `[TokenProcessor] Using pre-prepared instance ${instanceName} from current request context ${currentRequestContext.requestId}`,
-        )
-        deps.add(instanceName)
-        return prePreparedInstance
-      }
-    }
-
-    return undefined
-  }
 }

package/src/{base-instance-holder-manager.mts → internal/holder/base-holder-manager.mts}

@@ -1,14 +1,24 @@
-import type { ServiceLocatorInstanceHolder } from './service-locator-instance-holder.mjs'
+import type { InstanceHolder } from './instance-holder.mjs'
 
-import { InjectableScope, InjectableType } from './enums/index.mjs'
-import { ServiceLocatorInstanceHolderStatus } from './service-locator-instance-holder.mjs'
+import { InjectableScope, InjectableType } from '../../enums/index.mjs'
+import { DIError } from '../../errors/index.mjs'
+import { CircularDetector } from '../lifecycle/circular-detector.mjs'
+import { InstanceStatus } from './instance-holder.mjs'
 
 /**
- * Abstract base class that provides common functionality for managing ServiceLocatorInstanceHolder objects.
- * This class contains shared patterns used by both RequestContextHolder and ServiceLocatorManager.
+ * Result type for waitForHolderReady.
+ * Returns either [undefined, holder] on success or [error] on failure.
  */
-export abstract class BaseInstanceHolderManager {
-  protected readonly _holders: Map<string, ServiceLocatorInstanceHolder>
+export type HolderReadyResult<T> = [undefined, InstanceHolder<T>] | [DIError]
+
+/**
+ * Abstract base class providing common functionality for managing InstanceHolder objects.
+ *
+ * Provides shared patterns for holder storage, creation, and lifecycle management
+ * used by both singleton (HolderManager) and request-scoped (RequestContext) managers.
+ */
+export abstract class BaseHolderManager {
+  protected readonly _holders: Map<string, InstanceHolder>
 
   constructor(protected readonly logger: Console | null = null) {
     this._holders = new Map()
@@ -17,7 +27,7 @@ export abstract class BaseInstanceHolderManager {
   /**
    * Protected getter for accessing the holders map from subclasses.
    */
-  protected get holders(): Map<string, ServiceLocatorInstanceHolder> {
+  protected get holders(): Map<string, InstanceHolder> {
     return this._holders
   }
 
@@ -30,7 +40,7 @@ export abstract class BaseInstanceHolderManager {
   /**
    * Abstract method to set a holder by name. Each implementation may have different validation logic.
    */
-  abstract set(name: string, holder: ServiceLocatorInstanceHolder): void
+  abstract set(name: string, holder: InstanceHolder): void
 
   /**
    * Abstract method to check if a holder exists. Each implementation may have different validation logic.
@@ -52,11 +62,8 @@ export abstract class BaseInstanceHolderManager {
    * @returns A new Map containing only the holders that match the predicate
    */
   filter(
-    predicate: (
-      value: ServiceLocatorInstanceHolder<any>,
-      key: string,
-    ) => boolean,
-  ): Map<string, ServiceLocatorInstanceHolder> {
+    predicate: (value: InstanceHolder<any>, key: string) => boolean,
+  ): Map<string, InstanceHolder> {
     return new Map(
       [...this._holders].filter(([key, value]) => predicate(value, key)),
     )
@@ -92,12 +99,12 @@ export abstract class BaseInstanceHolderManager {
     deps: Set<string> = new Set(),
   ): [
     ReturnType<typeof Promise.withResolvers<[undefined, Instance]>>,
-    ServiceLocatorInstanceHolder<Instance>,
+    InstanceHolder<Instance>,
   ] {
     const deferred = Promise.withResolvers<[undefined, Instance]>()
 
-    const holder: ServiceLocatorInstanceHolder<Instance> = {
-      status: ServiceLocatorInstanceHolderStatus.Creating,
+    const holder: InstanceHolder<Instance> = {
+      status: InstanceStatus.Creating,
       name,
       instance: null,
       creationPromise: deferred.promise,
@@ -107,6 +114,7 @@ export abstract class BaseInstanceHolderManager {
       deps,
       destroyListeners: [],
       createdAt: Date.now(),
+      waitingFor: new Set(),
     }
 
     return [deferred, holder]
@@ -128,9 +136,9 @@ export abstract class BaseInstanceHolderManager {
     type: InjectableType,
     scope: InjectableScope,
     deps: Set<string> = new Set(),
-  ): ServiceLocatorInstanceHolder<Instance> {
-    const holder: ServiceLocatorInstanceHolder<Instance> = {
-      status: ServiceLocatorInstanceHolderStatus.Created,
+  ): InstanceHolder<Instance> {
+    const holder: InstanceHolder<Instance> = {
+      status: InstanceStatus.Created,
       name,
       instance,
       creationPromise: null,
@@ -140,6 +148,7 @@ export abstract class BaseInstanceHolderManager {
       deps,
       destroyListeners: [],
       createdAt: Date.now(),
+      waitingFor: new Set(),
     }
 
     return holder
@@ -155,7 +164,7 @@ export abstract class BaseInstanceHolderManager {
   /**
    * Gets all holders currently managed.
    */
-  getAllHolders(): ServiceLocatorInstanceHolder[] {
+  getAllHolders(): InstanceHolder[] {
     return Array.from(this._holders.values())
   }
 
@@ -165,4 +174,65 @@ export abstract class BaseInstanceHolderManager {
   isEmpty(): boolean {
     return this._holders.size === 0
   }
+
+  /**
+   * Waits for a holder to be ready and returns the appropriate result.
+   * This is a shared utility used by both singleton and request-scoped resolution.
+   *
+   * @param holder The holder to wait for
+   * @param waiterHolder Optional holder that is doing the waiting (for circular dependency detection)
+   * @param getHolder Optional function to retrieve holders by name (required if waiterHolder is provided)
+   * @returns A promise that resolves with [undefined, holder] on success or [DIError] on failure
+   */
+  static async waitForHolderReady<T>(
+    holder: InstanceHolder<T>,
+    waiterHolder?: InstanceHolder,
+    getHolder?: (name: string) => InstanceHolder | undefined,
+  ): Promise<HolderReadyResult<T>> {
+    switch (holder.status) {
+      case InstanceStatus.Creating: {
+        // Check for circular dependency before waiting
+        if (waiterHolder && getHolder) {
+          const cycle = CircularDetector.detectCycle(
+            waiterHolder.name,
+            holder.name,
+            getHolder,
+          )
+          if (cycle) {
+            return [DIError.circularDependency(cycle)]
+          }
+
+          // Track the waiting relationship
+          waiterHolder.waitingFor.add(holder.name)
+        }
+
+        try {
+          await holder.creationPromise
+        } finally {
+          // Clean up the waiting relationship
+          if (waiterHolder) {
+            waiterHolder.waitingFor.delete(holder.name)
+          }
+        }
+
+        return BaseHolderManager.waitForHolderReady(
+          holder,
+          waiterHolder,
+          getHolder,
+        )
+      }
+
+      case InstanceStatus.Destroying:
+        return [DIError.instanceDestroying(holder.name)]
+
+      case InstanceStatus.Error:
+        return [holder.instance as unknown as DIError]
+
+      case InstanceStatus.Created:
+        return [undefined, holder]
+
+      default:
+        return [DIError.instanceNotFound('unknown')]
+    }
+  }
 }

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

@@ -0,0 +1,85 @@
+import type { InstanceHolder } from './instance-holder.mjs'
+
+import { InjectableScope, InjectableType } from '../../enums/index.mjs'
+import { DIError, DIErrorCode } from '../../errors/index.mjs'
+import { BaseHolderManager } from './base-holder-manager.mjs'
+import { InstanceStatus } from './instance-holder.mjs'
+
+/**
+ * Manages the storage and retrieval of singleton instance holders.
+ *
+ * Provides CRUD operations and filtering for the holder map.
+ * Handles holder state validation (destroying, error states) on retrieval.
+ */
+export class HolderManager extends BaseHolderManager {
+  constructor(logger: Console | null = null) {
+    super(logger)
+  }
+
+  get(
+    name: string,
+  ): [DIError, InstanceHolder] | [DIError] | [undefined, InstanceHolder] {
+    const holder = this._holders.get(name)
+    if (holder) {
+      if (holder.status === InstanceStatus.Destroying) {
+        this.logger?.log(
+          `[HolderManager]#get() Instance ${holder.name} is destroying`,
+        )
+        return [DIError.instanceDestroying(holder.name), holder]
+      } else if (holder.status === InstanceStatus.Error) {
+        this.logger?.log(
+          `[HolderManager]#get() Instance ${holder.name} is in error state`,
+        )
+        return [holder.instance as unknown as DIError, holder]
+      }
+
+      return [undefined, holder]
+    } else {
+      this.logger?.log(`[HolderManager]#get() Instance ${name} not found`)
+      return [DIError.instanceNotFound(name)]
+    }
+  }
+
+  set(name: string, holder: InstanceHolder): void {
+    this._holders.set(name, holder)
+  }
+
+  has(name: string): [DIError] | [undefined, boolean] {
+    const [error, holder] = this.get(name)
+    if (!error) {
+      return [undefined, true]
+    }
+    if (error.code === DIErrorCode.InstanceDestroying) {
+      return [error]
+    }
+    return [undefined, !!holder]
+  }
+
+  // delete and filter methods are inherited from BaseHolderManager
+
+  // createCreatingHolder method is inherited from BaseHolderManager
+
+  /**
+   * Creates a new holder with Created status and stores it.
+   * This is useful for creating holders that already have their instance ready.
+   * @param name The name of the instance
+   * @param instance The actual instance to store
+   * @param type The injectable type
+   * @param scope The injectable scope
+   * @param deps Optional set of dependencies
+   * @returns The created holder
+   */
+  storeCreatedHolder<Instance>(
+    name: string,
+    instance: Instance,
+    type: InjectableType,
+    scope: InjectableScope,
+    deps: Set<string> = new Set(),
+  ): InstanceHolder<Instance> {
+    const holder = this.createCreatedHolder(name, instance, type, scope, deps)
+
+    this._holders.set(name, holder)
+
+    return holder
+  }
+}