@navios/di 0.8.0 → 0.9.0

package/src/internal/core/token-processor.mts

@@ -1,252 +0,0 @@
-/* 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 {
-  BoundInjectionToken,
-  FactoryInjectionToken,
-  InjectionToken,
-} from '../../token/injection-token.mjs'
-import { getInjectableToken } from '../../utils/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()
-  }
-}
-
-/**
- * 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 {
-  private readonly instanceNameCache = new InstanceNameCache()
-
-  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.
-   */
-  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(
-        `[TokenProcessor]#validateAndResolveTokenArgs(): Error validating args for ${actualToken.name.toString()}`,
-        validatedArgs.error,
-      )
-      return [DIError.unknown(validatedArgs.error), { actualToken }]
-    }
-    return [undefined, { actualToken, validatedArgs: validatedArgs?.data }]
-  }
-
-  /**
-   * Generates a unique instance name based on token and arguments.
-   * Results are cached using an LRU cache for performance.
-   */
-  generateInstanceName(token: InjectionTokenType, args: any): string {
-    if (!args) {
-      return token.toString()
-    }
-
-    // Create a cache key from token id and args
-    const tokenStr = token.toString()
-    const cacheKey = `${tokenStr}:${JSON.stringify(args)}`
-
-    // Check cache first
-    const cached = this.instanceNameCache.get(cacheKey)
-    if (cached !== undefined) {
-      return cached
-    }
-
-    // Generate the instance name
-    const formattedArgs = Object.entries(args)
-      .sort(([keyA], [keyB]) => keyA.localeCompare(keyB))
-      .map(([key, value]) => `${key}=${this.formatArgValue(value)}`)
-      .join(',')
-
-    const result = `${tokenStr}:${formattedArgs.replaceAll(/"/g, '').replaceAll(/:/g, '=')}`
-
-    // Cache the result
-    this.instanceNameCache.set(cacheKey, result)
-
-    return result
-  }
-
-  /**
-   * 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/base-holder-manager.mts

@@ -1,334 +0,0 @@
-import type { InstanceHolder } from './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'
-
-/**
- * Result type for waitForHolderReady.
- * Returns either [undefined, holder] on success or [error] on failure.
- */
-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>
-  /**
-   * Reverse dependency index: maps a dependency name to the set of holder names that depend on it.
-   * This allows O(1) lookup of dependents instead of O(n) iteration.
-   */
-  protected readonly _dependents: Map<string, Set<string>>
-
-  constructor(protected readonly logger: Console | null = null) {
-    this._holders = new Map()
-    this._dependents = new Map()
-  }
-
-  /**
-   * Protected getter for accessing the holders map from subclasses.
-   */
-  protected get holders(): Map<string, InstanceHolder> {
-    return this._holders
-  }
-
-  /**
-   * Abstract method to get a holder by name. Each implementation defines its own return type
-   * based on their specific error handling and validation needs.
-   */
-  abstract get(name: string): any
-
-  /**
-   * Abstract method to set a holder by name. Each implementation may have different validation logic.
-   */
-  abstract set(name: string, holder: InstanceHolder): void
-
-  /**
-   * Abstract method to check if a holder exists. Each implementation may have different validation logic.
-   */
-  abstract has(name: string): any
-
-  /**
-   * Deletes a holder by name and cleans up the reverse dependency index.
-   * @param name The name of the holder to delete
-   * @returns true if the holder was deleted, false if it didn't exist
-   */
-  delete(name: string): boolean {
-    const holder = this._holders.get(name)
-    if (holder) {
-      // Remove this holder from the reverse index for all its dependencies
-      this.removeFromDependentsIndex(name, holder.deps)
-    }
-    return this._holders.delete(name)
-  }
-
-  /**
-   * Registers a holder's dependencies in the reverse index.
-   * Call this after creating a holder with dependencies.
-   * @param holderName The name of the holder that has dependencies
-   * @param deps The set of dependency names
-   */
-  registerDependencies(holderName: string, deps: Set<string>): void {
-    for (const dep of deps) {
-      let dependents = this._dependents.get(dep)
-      if (!dependents) {
-        dependents = new Set()
-        this._dependents.set(dep, dependents)
-      }
-      dependents.add(holderName)
-    }
-  }
-
-  /**
-   * Removes a holder from the reverse dependency index.
-   * @param holderName The name of the holder to remove
-   * @param deps The set of dependency names to clean up
-   */
-  protected removeFromDependentsIndex(holderName: string, deps: Set<string>): void {
-    for (const dep of deps) {
-      const dependents = this._dependents.get(dep)
-      if (dependents) {
-        dependents.delete(holderName)
-        if (dependents.size === 0) {
-          this._dependents.delete(dep)
-        }
-      }
-    }
-  }
-
-  /**
-   * Gets all holder names that depend on the given instance name.
-   * O(1) lookup using the reverse dependency index.
-   * @param instanceName The instance name to find dependents for
-   * @returns Array of holder names that depend on this instance
-   */
-  getDependents(instanceName: string): string[] {
-    const dependents = this._dependents.get(instanceName)
-    return dependents ? Array.from(dependents) : []
-  }
-
-  /**
-   * Filters holders based on a predicate function.
-   * @param predicate Function to test each holder
-   * @returns A new Map containing only the holders that match the predicate
-   * @deprecated Use forEachHolder() for iteration to avoid allocations
-   */
-  filter(
-    predicate: (value: InstanceHolder<any>, key: string) => boolean,
-  ): Map<string, InstanceHolder> {
-    const result = new Map<string, InstanceHolder>()
-    for (const [key, value] of this._holders) {
-      if (predicate(value, key)) {
-        result.set(key, value)
-      }
-    }
-    return result
-  }
-
-  /**
-   * Iterates over holders with a callback. More efficient than filter() as it
-   * avoids creating intermediate arrays and Maps.
-   * @param callback Function called for each holder with (holder, name)
-   */
-  forEachHolder(
-    callback: (holder: InstanceHolder<any>, name: string) => void,
-  ): void {
-    for (const [name, holder] of this._holders) {
-      callback(holder, name)
-    }
-  }
-
-  /**
-   * Finds the first holder matching a predicate. More efficient than filter()
-   * when only one result is needed.
-   * @param predicate Function to test each holder
-   * @returns The first matching holder or undefined
-   */
-  findHolder(
-    predicate: (holder: InstanceHolder<any>, name: string) => boolean,
-  ): InstanceHolder | undefined {
-    for (const [name, holder] of this._holders) {
-      if (predicate(holder, name)) {
-        return holder
-      }
-    }
-    return undefined
-  }
-
-  /**
-   * Clears all holders from this manager and the reverse dependency index.
-   */
-  clear(): void {
-    this._holders.clear()
-    this._dependents.clear()
-  }
-
-  /**
-   * Gets the number of holders currently managed.
-   */
-  size(): number {
-    return this._holders.size
-  }
-
-  /**
-   * Creates a new holder with Creating status and a deferred creation promise.
-   * This is useful for creating placeholder holders that can be fulfilled later.
-   * @param name The name of the instance
-   * @param type The injectable type
-   * @param scope The injectable scope
-   * @param deps Optional set of dependencies
-   * @returns A tuple containing the deferred promise and the holder
-   */
-  createCreatingHolder<Instance>(
-    name: string,
-    type: InjectableType,
-    scope: InjectableScope,
-    deps: Set<string> = new Set(),
-  ): [
-    ReturnType<typeof Promise.withResolvers<[undefined, Instance]>>,
-    InstanceHolder<Instance>,
-  ] {
-    const deferred = Promise.withResolvers<[undefined, Instance]>()
-
-    const holder: InstanceHolder<Instance> = {
-      status: InstanceStatus.Creating,
-      name,
-      instance: null,
-      creationPromise: deferred.promise,
-      destroyPromise: null,
-      type,
-      scope,
-      deps,
-      destroyListeners: [],
-      createdAt: Date.now(),
-      waitingFor: new Set(),
-    }
-
-    return [deferred, holder]
-  }
-
-  /**
-   * Creates a new holder with Created status and an actual instance.
-   * 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
-   */
-  protected createCreatedHolder<Instance>(
-    name: string,
-    instance: Instance,
-    type: InjectableType,
-    scope: InjectableScope,
-    deps: Set<string> = new Set(),
-  ): InstanceHolder<Instance> {
-    const holder: InstanceHolder<Instance> = {
-      status: InstanceStatus.Created,
-      name,
-      instance,
-      creationPromise: null,
-      destroyPromise: null,
-      type,
-      scope,
-      deps,
-      destroyListeners: [],
-      createdAt: Date.now(),
-      waitingFor: new Set(),
-    }
-
-    return holder
-  }
-
-  /**
-   * Gets all holder names currently managed.
-   */
-  getAllNames(): string[] {
-    return Array.from(this._holders.keys())
-  }
-
-  /**
-   * Gets all holders currently managed.
-   */
-  getAllHolders(): InstanceHolder[] {
-    return Array.from(this._holders.values())
-  }
-
-  /**
-   * Checks if this manager has any holders.
-   */
-  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)]
-          }
-
-          if (process.env.NODE_ENV !== 'production') {
-            // Track the waiting relationship
-            waiterHolder.waitingFor.add(holder.name)
-          }
-        }
-
-        try {
-          await holder.creationPromise
-        } finally {
-          if (process.env.NODE_ENV !== 'production') {
-            // 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

@@ -1,85 +0,0 @@
-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
-  }
-}