@navios/di 0.5.1 → 0.6.1

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

@@ -0,0 +1,116 @@
+import type { InjectableScope, InjectableType } from '../../enums/index.mjs'
+import type { DIError } from '../../errors/index.mjs'
+import type { InstanceHolder } from './instance-holder.mjs'
+
+/**
+ * Result type for holder retrieval operations.
+ * - [undefined, holder] - Holder found successfully
+ * - [DIError, holder?] - Error occurred (holder may be available for waiting)
+ * - null - No holder exists
+ */
+export type HolderGetResult<T = unknown> =
+  | [undefined, InstanceHolder<T>]
+  | [DIError, InstanceHolder<T>?]
+  | null
+
+/**
+ * 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.
+ */
+export interface IHolderStorage {
+  /**
+   * The scope this storage handles.
+   */
+  readonly scope: InjectableScope
+
+  // ============================================================================
+  // BASIC OPERATIONS
+  // ============================================================================
+
+  /**
+   * Retrieves an existing holder by instance name.
+   *
+   * @param instanceName The unique identifier for the instance
+   * @returns
+   *   - [undefined, holder] if found and ready/creating
+   *   - [DIError, holder?] if found but in error/destroying state
+   *   - null if not found
+   */
+  get<T = unknown>(instanceName: string): HolderGetResult<T>
+
+  /**
+   * Stores a holder by instance name.
+   *
+   * @param instanceName The unique identifier for the instance
+   * @param holder The holder to store
+   */
+  set(instanceName: string, holder: InstanceHolder): void
+
+  /**
+   * Deletes a holder by instance name.
+   *
+   * @param instanceName The unique identifier for the instance
+   * @returns true if the holder was deleted, false if it didn't exist
+   */
+  delete(instanceName: string): boolean
+
+  /**
+   * Creates a new holder in "Creating" state with a deferred promise.
+   * The holder is NOT automatically stored - call set() to store it.
+   *
+   * @param instanceName The unique identifier for the instance
+   * @param type The injectable type
+   * @param deps The set of dependency names
+   * @returns A tuple containing the deferred promise resolver and the holder
+   */
+  createHolder<T>(
+    instanceName: string,
+    type: InjectableType,
+    deps: Set<string>,
+  ): [
+    ReturnType<typeof Promise.withResolvers<[undefined, T]>>,
+    InstanceHolder<T>,
+  ]
+
+  /**
+   * Checks if this storage should be used for the given scope.
+   */
+  handles(scope: InjectableScope): boolean
+
+  // ============================================================================
+  // ITERATION AND QUERY
+  // ============================================================================
+
+  /**
+   * Gets all instance names in this storage.
+   */
+  getAllNames(): string[]
+
+  /**
+   * Iterates over all holders with a callback.
+   *
+   * @param callback Function called for each holder with (name, holder)
+   */
+  forEach(
+    callback: (name: string, holder: InstanceHolder) => void,
+  ): void
+
+  /**
+   * Finds a holder by its instance value (reverse lookup).
+   *
+   * @param instance The instance to search for
+   * @returns The holder if found, null otherwise
+   */
+  findByInstance(instance: unknown): InstanceHolder | null
+
+  /**
+   * Finds all instance names that depend on the given instance name.
+   *
+   * @param instanceName The instance name to find dependents for
+   * @returns Array of instance names that have this instance as a dependency
+   */
+  findDependents(instanceName: string): string[]
+}

package/src/internal/holder/index.mts

@@ -0,0 +1,6 @@
+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'

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

@@ -0,0 +1,109 @@
+import type { InjectableScope, InjectableType } from '../../enums/index.mjs'
+
+/**
+ * Represents the lifecycle status of an instance holder.
+ */
+export enum InstanceStatus {
+  /** Instance has been successfully created and is ready for use */
+  Created = 'created',
+  /** Instance is currently being created (async initialization in progress) */
+  Creating = 'creating',
+  /** Instance is being destroyed (cleanup in progress) */
+  Destroying = 'destroying',
+  /** Instance creation failed with an error */
+  Error = 'error',
+}
+
+/** Callback function for instance effects */
+export type InstanceEffect = () => void
+
+/** Callback function for instance destruction listeners */
+export type InstanceDestroyListener = () => void | Promise<void>
+
+/**
+ * Instance holder in the Creating state.
+ * The instance is null while creation is in progress.
+ */
+export interface InstanceHolderCreating<Instance> {
+  status: InstanceStatus.Creating
+  name: string
+  instance: null
+  creationPromise: Promise<[undefined, Instance]> | null
+  destroyPromise: null
+  type: InjectableType
+  scope: InjectableScope
+  deps: Set<string>
+  destroyListeners: InstanceDestroyListener[]
+  createdAt: number
+  /** Tracks which services this holder is currently waiting for (for circular dependency detection) */
+  waitingFor: Set<string>
+}
+
+/**
+ * Instance holder in the Created state.
+ * The instance is available and ready for use.
+ */
+export interface InstanceHolderCreated<Instance> {
+  status: InstanceStatus.Created
+  name: string
+  instance: Instance
+  creationPromise: null
+  destroyPromise: null
+  type: InjectableType
+  scope: InjectableScope
+  deps: Set<string>
+  destroyListeners: InstanceDestroyListener[]
+  createdAt: number
+  /** Tracks which services this holder is currently waiting for (for circular dependency detection) */
+  waitingFor: Set<string>
+}
+
+/**
+ * Instance holder in the Destroying state.
+ * The instance may still be available but is being cleaned up.
+ */
+export interface InstanceHolderDestroying<Instance> {
+  status: InstanceStatus.Destroying
+  name: string
+  instance: Instance | null
+  creationPromise: null
+  destroyPromise: Promise<void>
+  type: InjectableType
+  scope: InjectableScope
+  deps: Set<string>
+  destroyListeners: InstanceDestroyListener[]
+  createdAt: number
+  /** Tracks which services this holder is currently waiting for (for circular dependency detection) */
+  waitingFor: Set<string>
+}
+
+/**
+ * Instance holder in the Error state.
+ * The instance field contains the error that occurred during creation.
+ */
+export interface InstanceHolderError {
+  status: InstanceStatus.Error
+  name: string
+  instance: Error
+  creationPromise: null
+  destroyPromise: null
+  type: InjectableType
+  scope: InjectableScope
+  deps: Set<string>
+  destroyListeners: InstanceDestroyListener[]
+  createdAt: number
+  /** Tracks which services this holder is currently waiting for (for circular dependency detection) */
+  waitingFor: Set<string>
+}
+
+/**
+ * Holds the state of a service instance throughout its lifecycle.
+ *
+ * Tracks creation/destruction promises, dependency relationships,
+ * destroy listeners, and current status (Creating, Created, Destroying, Error).
+ */
+export type InstanceHolder<Instance = unknown> =
+  | InstanceHolderCreating<Instance>
+  | InstanceHolderCreated<Instance>
+  | InstanceHolderDestroying<Instance>
+  | InstanceHolderError

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

@@ -0,0 +1,134 @@
+import type { RequestContext } from '../context/request-context.mjs'
+import type { BaseHolderManager } from './base-holder-manager.mjs'
+import type {
+  HolderGetResult,
+  IHolderStorage,
+} from './holder-storage.interface.mjs'
+import type { InstanceHolder } from './instance-holder.mjs'
+
+import { InjectableScope, InjectableType } from '../../enums/index.mjs'
+import { DIError } from '../../errors/index.mjs'
+import { InstanceStatus } from './instance-holder.mjs'
+
+/**
+ * Storage implementation for Request-scoped services.
+ *
+ * Wraps a RequestContext instance from a ScopedContainer and provides
+ * the IHolderStorage interface. This allows the InstanceResolver to work
+ * with request-scoped storage using the same interface as singleton storage.
+ */
+export class RequestStorage implements IHolderStorage {
+  readonly scope = InjectableScope.Request
+
+  constructor(
+    private readonly contextHolder: RequestContext,
+    private readonly holderManager: BaseHolderManager,
+  ) {}
+
+  get<T = unknown>(instanceName: string): HolderGetResult<T> {
+    const holder = this.contextHolder.get(instanceName)
+
+    if (!holder) {
+      return null
+    }
+
+    // Check holder status for error states
+    switch (holder.status) {
+      case InstanceStatus.Destroying:
+        return [
+          DIError.instanceDestroying(instanceName),
+          holder as InstanceHolder<T>,
+        ]
+
+      case InstanceStatus.Error:
+        return [
+          holder.instance as unknown as DIError,
+          holder as InstanceHolder<T>,
+        ]
+
+      case InstanceStatus.Creating:
+      case InstanceStatus.Created:
+        return [undefined, holder as InstanceHolder<T>]
+
+      default:
+        return null
+    }
+  }
+
+  set(instanceName: string, holder: InstanceHolder): void {
+    this.contextHolder.set(instanceName, holder)
+  }
+
+  delete(instanceName: string): boolean {
+    return this.contextHolder.delete(instanceName)
+  }
+
+  createHolder<T>(
+    instanceName: string,
+    type: InjectableType,
+    deps: Set<string>,
+  ): [
+    ReturnType<typeof Promise.withResolvers<[undefined, T]>>,
+    InstanceHolder<T>,
+  ] {
+    // Use the holderManager's createCreatingHolder method
+    // which is inherited from BaseHolderManager
+    return this.holderManager.createCreatingHolder<T>(
+      instanceName,
+      type,
+      this.scope,
+      deps,
+    )
+  }
+
+  handles(scope: InjectableScope): boolean {
+    return scope === InjectableScope.Request
+  }
+
+  // ============================================================================
+  // ITERATION AND QUERY
+  // ============================================================================
+
+  getAllNames(): string[] {
+    const names: string[] = []
+    for (const [name] of this.contextHolder.holders) {
+      names.push(name)
+    }
+    return names
+  }
+
+  forEach(callback: (name: string, holder: InstanceHolder) => void): void {
+    for (const [name, holder] of this.contextHolder.holders) {
+      callback(name, holder)
+    }
+  }
+
+  findByInstance(instance: unknown): InstanceHolder | null {
+    for (const holder of this.contextHolder.holders.values()) {
+      if (holder.instance === instance) {
+        return holder
+      }
+    }
+    return null
+  }
+
+  findDependents(instanceName: string): string[] {
+    const dependents: string[] = []
+
+    // Check request-scoped holders
+    for (const [name, holder] of this.contextHolder.holders) {
+      if (holder.deps.has(instanceName)) {
+        dependents.push(name)
+      }
+    }
+
+    // Also check singleton holders - a singleton may depend on this request-scoped service
+    for (const [name, holder] of this.holderManager.filter(() => true)) {
+      if (holder.deps.has(instanceName)) {
+        dependents.push(name)
+      }
+    }
+
+    return dependents
+  }
+}

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

@@ -0,0 +1,105 @@
+import type { HolderManager } from './holder-manager.mjs'
+import type {
+  HolderGetResult,
+  IHolderStorage,
+} from './holder-storage.interface.mjs'
+import type { InstanceHolder } from './instance-holder.mjs'
+
+import { InjectableScope, InjectableType } from '../../enums/index.mjs'
+import { DIErrorCode } from '../../errors/index.mjs'
+
+/**
+ * Storage implementation for Singleton-scoped services.
+ *
+ * Wraps a HolderManager instance and provides the IHolderStorage interface.
+ * This allows the InstanceResolver to work with singleton storage
+ * using the same interface as request-scoped storage.
+ */
+export class SingletonStorage implements IHolderStorage {
+  readonly scope = InjectableScope.Singleton
+
+  constructor(private readonly manager: HolderManager) {}
+
+  get<T = unknown>(instanceName: string): HolderGetResult<T> {
+    const [error, holder] = this.manager.get(instanceName)
+
+    if (!error) {
+      return [undefined, holder as InstanceHolder<T>]
+    }
+
+    // Handle different error types
+    switch (error.code) {
+      case DIErrorCode.InstanceNotFound:
+        return null
+
+      case DIErrorCode.InstanceDestroying:
+        return [error, holder as InstanceHolder<T> | undefined]
+
+      default:
+        return [error]
+    }
+  }
+
+  set(instanceName: string, holder: InstanceHolder): void {
+    this.manager.set(instanceName, holder)
+  }
+
+  delete(instanceName: string): boolean {
+    return this.manager.delete(instanceName)
+  }
+
+  createHolder<T>(
+    instanceName: string,
+    type: InjectableType,
+    deps: Set<string>,
+  ): [
+    ReturnType<typeof Promise.withResolvers<[undefined, T]>>,
+    InstanceHolder<T>,
+  ] {
+    return this.manager.createCreatingHolder<T>(
+      instanceName,
+      type,
+      this.scope,
+      deps,
+    )
+  }
+
+  handles(scope: InjectableScope): boolean {
+    return scope === InjectableScope.Singleton
+  }
+
+  // ============================================================================
+  // ITERATION AND QUERY
+  // ============================================================================
+
+  getAllNames(): string[] {
+    return this.manager.getAllNames()
+  }
+
+  forEach(
+    callback: (name: string, holder: InstanceHolder) => void,
+  ): void {
+    for (const [name, holder] of this.manager.filter(() => true)) {
+      callback(name, holder)
+    }
+  }
+
+  findByInstance(instance: unknown): InstanceHolder | null {
+    for (const [, holder] of this.manager.filter(
+      (h) => h.instance === instance,
+    )) {
+      return holder
+    }
+    return null
+  }
+
+  findDependents(instanceName: string): string[] {
+    const dependents: string[] = []
+    for (const [name, holder] of this.manager.filter(() => true)) {
+      if (holder.deps.has(instanceName)) {
+        dependents.push(name)
+      }
+    }
+    return dependents
+  }
+}

package/src/internal/index.mts

@@ -0,0 +1,4 @@
+export * from './core/index.mjs'
+export * from './holder/index.mjs'
+export * from './context/index.mjs'
+export * from './lifecycle/index.mjs'

package/src/internal/lifecycle/circular-detector.mts

@@ -0,0 +1,77 @@
+import type { InstanceHolder } from '../holder/instance-holder.mjs'
+
+/**
+ * Detects circular dependencies by analyzing the waitingFor relationships
+ * between service holders.
+ *
+ * Uses BFS to traverse the waitingFor graph starting from a target holder
+ * and checks if following the chain leads back to the waiter, indicating a circular dependency.
+ */
+export class CircularDetector {
+  /**
+   * Detects if waiting for `targetName` from `waiterName` would create a cycle.
+   *
+   * This works by checking if `targetName` (or any holder in its waitingFor chain)
+   * is currently waiting for `waiterName`. If so, waiting would create a deadlock.
+   *
+   * @param waiterName The name of the holder that wants to wait
+   * @param targetName The name of the holder being waited on
+   * @param getHolder Function to retrieve a holder by name
+   * @returns The cycle path if a cycle is detected, null otherwise
+   */
+  static detectCycle(
+    waiterName: string,
+    targetName: string,
+    getHolder: (name: string) => InstanceHolder | undefined,
+  ): string[] | null {
+    // Use BFS to find if there's a path from targetName back to waiterName
+    const visited = new Set<string>()
+    const queue: Array<{ name: string; path: string[] }> = [
+      { name: targetName, path: [waiterName, targetName] },
+    ]
+
+    while (queue.length > 0) {
+      const { name: currentName, path } = queue.shift()!
+
+      // If we've reached back to the waiter, we have a cycle
+      if (currentName === waiterName) {
+        return path
+      }
+
+      // Skip if already visited
+      if (visited.has(currentName)) {
+        continue
+      }
+      visited.add(currentName)
+
+      // Get the holder and check what it's waiting for
+      const holder = getHolder(currentName)
+      if (!holder) {
+        continue
+      }
+
+      // Add all services this holder is waiting for to the queue
+      for (const waitingForName of holder.waitingFor) {
+        if (!visited.has(waitingForName)) {
+          queue.push({
+            name: waitingForName,
+            path: [...path, waitingForName],
+          })
+        }
+      }
+    }
+
+    // No path found from target back to waiter, no cycle
+    return null
+  }
+
+  /**
+   * Formats a cycle path into a human-readable string.
+   *
+   * @param cycle The cycle path (array of service names)
+   * @returns Formatted string like "ServiceA -> ServiceB -> ServiceA"
+   */
+  static formatCycle(cycle: string[]): string {
+    return cycle.join(' -> ')
+  }
+}

package/src/internal/lifecycle/index.mts

@@ -0,0 +1,2 @@
+export * from './lifecycle-event-bus.mjs'
+export * from './circular-detector.mjs'

package/src/{service-locator-event-bus.mts → internal/lifecycle/lifecycle-event-bus.mts}

@@ -3,8 +3,15 @@
 
 type ListenersMap = Map<string, Map<string, Set<Function>>>
 
+/**
+ * Event bus for service lifecycle events (create, destroy, etc.).
+ *
+ * Enables loose coupling between services by allowing them to subscribe
+ * to lifecycle events of their dependencies without direct references.
+ * Used primarily for invalidation cascading.
+ */
 /* eslint-disable @typescript-eslint/no-non-null-assertion */
-export class ServiceLocatorEventBus {
+export class LifecycleEventBus {
   private listeners: ListenersMap = new Map()
   constructor(private readonly logger: Console | null = null) {}
 
@@ -13,7 +20,7 @@ export class ServiceLocatorEventBus {
     event: Event,
     listener: (event: Event) => void,
   ) {
-    this.logger?.debug(`[ServiceLocatorEventBus]#on(): ns:${ns} event:${event}`)
+    this.logger?.debug(`[LifecycleEventBus]#on(): ns:${ns} event:${event}`)
     if (!this.listeners.has(ns)) {
       this.listeners.set(ns, new Map())
     }
@@ -43,7 +50,7 @@ export class ServiceLocatorEventBus {
 
     const events = this.listeners.get(key)!
 
-    this.logger?.debug(`[ServiceLocatorEventBus]#emit(): ${key}:${event}`)
+    this.logger?.debug(`[LifecycleEventBus]#emit(): ${key}:${event}`)
 
     const res = await Promise.allSettled(
       [...(events.get(event) ?? [])!].map((listener) => listener(event)),
@@ -52,7 +59,7 @@ export class ServiceLocatorEventBus {
         .filter((result) => result.status === 'rejected')
         .map((result: PromiseRejectedResult) => {
           this.logger?.warn(
-            `[ServiceLocatorEventBus]#emit(): ${key}:${event} rejected with`,
+            `[LifecycleEventBus]#emit(): ${key}:${event} rejected with`,
             result.reason,
           )
           return result

package/src/testing/__tests__/test-container.spec.mts

@@ -1,8 +1,8 @@
 import { beforeEach, describe, expect, it } from 'vitest'
 
 import { Injectable } from '../../decorators/injectable.decorator.mjs'
-import { InjectionToken } from '../../injection-token.mjs'
-import { inject } from '../../injector.mjs'
+import { InjectionToken } from '../../token/injection-token.mjs'
+import { inject } from '../../injectors.mjs'
 import { TestContainer } from '../test-container.mjs'
 
 describe('TestContainer', () => {

package/src/testing/test-container.mts

@@ -1,11 +1,11 @@
-import type { ClassType, InjectionToken } from '../injection-token.mjs'
-import type { Registry } from '../registry.mjs'
+import type { ClassType, InjectionToken } from '../token/injection-token.mjs'
+import type { Registry } from '../token/registry.mjs'
 import type { Injectors } from '../utils/index.mjs'
 
-import { Container } from '../container.mjs'
+import { Container } from '../container/container.mjs'
 import { Injectable } from '../decorators/injectable.decorator.mjs'
 import { InjectableScope, InjectableType } from '../enums/index.mjs'
-import { globalRegistry } from '../registry.mjs'
+import { globalRegistry } from '../token/registry.mjs'
 import { getInjectableToken } from '../utils/index.mjs'
 
 /**

package/src/token/index.mts

@@ -0,0 +1,2 @@
+export * from './injection-token.mjs'
+export * from './registry.mjs'

package/src/{injection-token.mts → token/injection-token.mts}

@@ -1,6 +1,6 @@
 import type { z, ZodObject, ZodOptional, ZodRecord } from 'zod/v4'
 
-import type { FactoryContext } from './factory-context.mjs'
+import type { FactoryContext } from '../internal/context/factory-context.mjs'
 
 export type ClassType = new (...args: any[]) => any
 export type ClassTypeWithoutArguments = new () => any

package/src/{registry.mts → token/registry.mts}

@@ -1,6 +1,6 @@
 import type { ClassType, InjectionToken } from './injection-token.mjs'
 
-import { InjectableScope, InjectableType } from './enums/index.mjs'
+import { InjectableScope, InjectableType } from '../enums/index.mjs'
 
 export type FactoryRecord<Instance = any, Schema = any> = {
   scope: InjectableScope

package/src/utils/get-injectable-token.mts

@@ -1,4 +1,4 @@
-import type { ClassType, InjectionToken } from '../injection-token.mjs'
+import type { ClassType, InjectionToken } from '../token/injection-token.mjs'
 
 import { InjectableTokenMeta } from '../symbols/index.mjs'