@navios/di 0.5.1 → 0.6.0

package/src/interfaces/container.interface.mts

@@ -0,0 +1,82 @@
+import type { z, ZodType } from 'zod/v4'
+
+import type {
+  BoundInjectionToken,
+  ClassType,
+  ClassTypeWithArgument,
+  FactoryInjectionToken,
+  InjectionToken,
+  InjectionTokenSchemaType,
+} from '../token/injection-token.mjs'
+import type { Join, UnionToArray } from '../utils/types.mjs'
+import type { Factorable } from './factory.interface.mjs'
+
+/**
+ * Interface for dependency injection containers.
+ * Both Container and ScopedContainer implement this interface,
+ * allowing them to be used interchangeably in factory contexts.
+ */
+export interface IContainer {
+  /**
+   * Gets an instance from the container.
+   */
+  // #1 Simple class
+  get<T extends ClassType>(
+    token: T,
+  ): InstanceType<T> extends Factorable<infer R>
+    ? Promise<R>
+    : Promise<InstanceType<T>>
+  // #1.1 Simple class with args
+  get<T extends ClassTypeWithArgument<R>, R>(
+    token: T,
+    args: R,
+  ): Promise<InstanceType<T>>
+  // #2 Token with required Schema
+  get<T, S extends InjectionTokenSchemaType>(
+    token: InjectionToken<T, S>,
+    args: z.input<S>,
+  ): Promise<T>
+  // #3 Token with optional Schema
+  get<T, S extends InjectionTokenSchemaType, R extends boolean>(
+    token: InjectionToken<T, S, R>,
+  ): R extends false
+    ? Promise<T>
+    : S extends ZodType<infer Type>
+      ? `Error: Your token requires args: ${Join<
+          UnionToArray<keyof Type>,
+          ', '
+        >}`
+      : 'Error: Your token requires args'
+  // #4 Token with no Schema
+  get<T>(token: InjectionToken<T, undefined>): Promise<T>
+  get<T>(token: BoundInjectionToken<T, any>): Promise<T>
+  get<T>(token: FactoryInjectionToken<T, any>): Promise<T>
+
+  /**
+   * Invalidates a service and its dependencies.
+   */
+  invalidate(service: unknown): Promise<void>
+
+  /**
+   * Checks if a service is registered in the container.
+   */
+  isRegistered(token: any): boolean
+
+  /**
+   * Disposes the container and cleans up all resources.
+   */
+  dispose(): Promise<void>
+
+  /**
+   * Waits for all pending operations to complete.
+   */
+  ready(): Promise<void>
+
+  /**
+   * @internal
+   * Attempts to get an instance synchronously if it already exists.
+   * Returns null if the instance doesn't exist or is not ready.
+   * Used internally by the inject system for synchronous property initialization.
+   */
+  tryGetSync<T>(token: any, args?: any): T | null
+}

package/src/interfaces/factory.interface.mts

@@ -1,7 +1,7 @@
 import { z } from 'zod/v4'
 
-import type { FactoryContext } from '../factory-context.mjs'
-import type { InjectionTokenSchemaType } from '../injection-token.mjs'
+import type { FactoryContext } from '../internal/context/factory-context.mjs'
+import type { InjectionTokenSchemaType } from '../token/injection-token.mjs'
 
 export interface Factorable<T> {
   create(ctx?: FactoryContext): Promise<T> | T

package/src/interfaces/index.mts

@@ -1,3 +1,4 @@
+export * from './container.interface.mjs'
 export * from './factory.interface.mjs'
 export * from './on-service-init.interface.mjs'
 export * from './on-service-destroy.interface.mjs'

package/src/internal/context/async-local-storage.mts

@@ -0,0 +1,120 @@
+/**
+ * Cross-platform AsyncLocalStorage wrapper.
+ *
+ * Provides AsyncLocalStorage on Node.js/Bun and falls back to
+ * a synchronous-only polyfill in browser environments.
+ */
+
+import { SyncLocalStorage } from './sync-local-storage.mjs'
+
+/**
+ * Interface matching the subset of AsyncLocalStorage API we use.
+ */
+export interface IAsyncLocalStorage<T> {
+  run<R>(store: T, fn: () => R): R
+  getStore(): T | undefined
+}
+
+/**
+ * Detects if we're running in a Node.js-like environment with async_hooks support.
+ */
+function hasAsyncHooksSupport(): boolean {
+  // Check for Node.js
+  if (
+    typeof process !== 'undefined' &&
+    process.versions &&
+    process.versions.node
+  ) {
+    return true
+  }
+
+  // Check for Bun
+  if (typeof process !== 'undefined' && process.versions && 'bun' in process.versions) {
+    return true
+  }
+
+  // Check for Deno (also supports async_hooks via node compat)
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  if (typeof (globalThis as any).Deno !== 'undefined') {
+    return true
+  }
+
+  return false
+}
+
+// Cache for the AsyncLocalStorage class
+let AsyncLocalStorageClass: (new <T>() => IAsyncLocalStorage<T>) | null = null
+let initialized = false
+let forceSyncMode = false
+
+/**
+ * Gets the appropriate AsyncLocalStorage implementation for the current environment.
+ *
+ * - On Node.js/Bun/Deno: Returns the native AsyncLocalStorage
+ * - On browsers: Returns SyncLocalStorage polyfill
+ */
+function getAsyncLocalStorageClass(): new <T>() => IAsyncLocalStorage<T> {
+  if (initialized) {
+    return AsyncLocalStorageClass!
+  }
+
+  initialized = true
+
+  if (!forceSyncMode && hasAsyncHooksSupport()) {
+    try {
+      // Dynamic require to avoid bundler issues
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      const asyncHooks = require('node:async_hooks')
+      AsyncLocalStorageClass = asyncHooks.AsyncLocalStorage
+    } catch {
+      // Fallback if require fails (shouldn't happen in Node/Bun)
+      AsyncLocalStorageClass = SyncLocalStorage as any
+    }
+  } else {
+    AsyncLocalStorageClass = SyncLocalStorage as any
+  }
+
+  return AsyncLocalStorageClass!
+}
+
+/**
+ * Creates a new AsyncLocalStorage instance appropriate for the current environment.
+ */
+export function createAsyncLocalStorage<T>(): IAsyncLocalStorage<T> {
+  const StorageClass = getAsyncLocalStorageClass()
+  return new StorageClass<T>()
+}
+
+/**
+ * Returns true if we're using the real AsyncLocalStorage (Node/Bun/Deno).
+ * Returns false if we're using the sync-only polyfill (browser).
+ */
+export function isUsingNativeAsyncLocalStorage(): boolean {
+  getAsyncLocalStorageClass() // Ensure initialized
+  return AsyncLocalStorageClass !== (SyncLocalStorage as any)
+}
+
+/**
+ * Testing utilities for forcing specific modes.
+ * Only exported for testing purposes.
+ */
+export const __testing__ = {
+  /**
+   * Resets the initialization state and forces sync mode.
+   * Call this before creating new storage instances in tests.
+   */
+  forceSyncMode: () => {
+    initialized = false
+    forceSyncMode = true
+    AsyncLocalStorageClass = null
+  },
+
+  /**
+   * Resets to default behavior (auto-detect environment).
+   */
+  reset: () => {
+    initialized = false
+    forceSyncMode = false
+    AsyncLocalStorageClass = null
+  },
+}

package/src/internal/context/factory-context.mts

@@ -0,0 +1,18 @@
+import type { IContainer } from '../../interfaces/container.interface.mjs'
+import type { Injectors } from '../../utils/index.mjs'
+
+/**
+ * Context provided to factory functions during service instantiation.
+ *
+ * Provides access to dependency injection (via inject), the container,
+ * and lifecycle hooks for cleanup.
+ */
+export interface FactoryContext {
+  inject: Injectors['asyncInject']
+  /**
+   * The container instance for dependency resolution.
+   * This may be either a Container or ScopedContainer.
+   */
+  container: IContainer
+  addDestroyListener: (listener: () => void) => void
+}

package/src/internal/context/index.mts

@@ -0,0 +1,3 @@
+export * from './factory-context.mjs'
+export * from './resolution-context.mjs'
+export * from './request-context.mjs'

package/src/{request-context-holder.mts → internal/context/request-context.mts}

@@ -1,14 +1,16 @@
-import type { ServiceLocatorInstanceHolder } from './service-locator-instance-holder.mjs'
+import type { InstanceHolder } from '../holder/instance-holder.mjs'
 
-import { BaseInstanceHolderManager } from './base-instance-holder-manager.mjs'
-import { InjectableScope, InjectableType } from './enums/index.mjs'
-import { InjectionToken } from './injection-token.mjs'
+import { BaseHolderManager } from '../holder/base-holder-manager.mjs'
+import { InjectableScope, InjectableType } from '../../enums/index.mjs'
+import { InjectionToken } from '../../token/injection-token.mjs'
 
 /**
- * Request context holder that manages pre-prepared instances for a specific request.
- * This allows for efficient instantiation of request-scoped services.
+ * Interface for request context that manages pre-prepared instances for a specific request.
+ *
+ * Provides isolated storage for request-scoped services, enabling efficient
+ * instantiation and cleanup within the lifecycle of a single request.
  */
-export interface RequestContextHolder {
+export interface RequestContext {
   /**
    * Unique identifier for this request context.
    */
@@ -17,7 +19,7 @@ export interface RequestContextHolder {
   /**
    * Instance holders for request-scoped services.
    */
-  readonly holders: Map<string, ServiceLocatorInstanceHolder>
+  readonly holders: Map<string, InstanceHolder>
 
   /**
    * Priority for resolution in FactoryContext.inject method.
@@ -41,7 +43,7 @@ export interface RequestContextHolder {
   addInstance(
     instanceName: string,
     instance: any,
-    holder: ServiceLocatorInstanceHolder,
+    holder: InstanceHolder,
   ): void
 
   /**
@@ -52,7 +54,12 @@ export interface RequestContextHolder {
   /**
    * Gets an instance holder from this context.
    */
-  get(instanceName: string): ServiceLocatorInstanceHolder | undefined
+  get(instanceName: string): InstanceHolder | undefined
+
+  /**
+   * Sets an instance holder by name.
+   */
+  set(instanceName: string, holder: InstanceHolder): void
 
   /**
    * Checks if this context has a pre-prepared instance.
@@ -74,16 +81,16 @@ export interface RequestContextHolder {
    */
   setMetadata(key: string, value: any): void
 
-  // Methods inherited from BaseInstanceHolderManager
+  // Methods inherited from BaseHolderManager
   /**
    * Filters holders based on a predicate function.
    */
   filter(
     predicate: (
-      value: ServiceLocatorInstanceHolder<any>,
+      value: InstanceHolder<any>,
       key: string,
     ) => boolean,
-  ): Map<string, ServiceLocatorInstanceHolder>
+  ): Map<string, InstanceHolder>
 
   /**
    * Deletes a holder by name.
@@ -101,12 +108,18 @@ export interface RequestContextHolder {
   isEmpty(): boolean
 }
 
+/** @deprecated Use RequestContext instead */
+export type RequestContextHolder = RequestContext
+
 /**
- * Default implementation of RequestContextHolder.
+ * Default implementation of RequestContext.
+ *
+ * Extends BaseHolderManager to provide holder management functionality
+ * with request-specific metadata and lifecycle support.
  */
-export class DefaultRequestContextHolder
-  extends BaseInstanceHolderManager
-  implements RequestContextHolder
+export class DefaultRequestContext
+  extends BaseHolderManager
+  implements RequestContext
 {
   public readonly metadata = new Map<string, any>()
   public readonly createdAt = Date.now()
@@ -116,7 +129,7 @@ export class DefaultRequestContextHolder
     public readonly priority: number = 100,
     initialMetadata?: Record<string, any>,
   ) {
-    super(null) // RequestContextHolder doesn't need logging
+    super(null) // RequestContext doesn't need logging
     if (initialMetadata) {
       Object.entries(initialMetadata).forEach(([key, value]) => {
         this.metadata.set(key, value)
@@ -127,21 +140,21 @@ export class DefaultRequestContextHolder
   /**
    * Public getter for holders to maintain interface compatibility.
    */
-  get holders(): Map<string, ServiceLocatorInstanceHolder> {
+  get holders(): Map<string, InstanceHolder> {
     return this._holders
   }
 
   /**
-   * Gets a holder by name. For RequestContextHolder, this is a simple lookup.
+   * Gets a holder by name. For RequestContext, this is a simple lookup.
    */
-  get(name: string): ServiceLocatorInstanceHolder | undefined {
+  get(name: string): InstanceHolder | undefined {
     return this._holders.get(name)
   }
 
   /**
    * Sets a holder by name.
    */
-  set(name: string, holder: ServiceLocatorInstanceHolder): void {
+  set(name: string, holder: InstanceHolder): void {
     this._holders.set(name, holder)
   }
 
@@ -155,7 +168,7 @@ export class DefaultRequestContextHolder
   addInstance(
     instanceName: string | InjectionToken<any, undefined>,
     instance: any,
-    holder?: ServiceLocatorInstanceHolder,
+    holder?: InstanceHolder,
   ): void {
     if (instanceName instanceof InjectionToken) {
       const name = instanceName.toString()
@@ -190,12 +203,12 @@ export class DefaultRequestContextHolder
 }
 
 /**
- * Creates a new request context holder with the given parameters.
+ * Creates a new request context with the given parameters.
  */
-export function createRequestContextHolder(
+export function createRequestContext(
   requestId: string,
   priority: number = 100,
   initialMetadata?: Record<string, any>,
-): RequestContextHolder {
-  return new DefaultRequestContextHolder(requestId, priority, initialMetadata)
+): RequestContext {
+  return new DefaultRequestContext(requestId, priority, initialMetadata)
 }

package/src/internal/context/resolution-context.mts

@@ -0,0 +1,63 @@
+import type { InstanceHolder } from '../holder/instance-holder.mjs'
+
+import { createAsyncLocalStorage } from './async-local-storage.mjs'
+
+/**
+ * Data stored in the resolution context during service instantiation.
+ */
+export interface ResolutionContextData {
+  /** The holder that is currently being instantiated */
+  waiterHolder: InstanceHolder
+  /** Function to get a holder by name (for cycle detection) */
+  getHolder: (name: string) => InstanceHolder | undefined
+}
+
+/**
+ * AsyncLocalStorage for tracking the current resolution context.
+ *
+ * This allows tracking which service is being instantiated even across
+ * async boundaries (like when inject() is called inside a constructor).
+ * Essential for circular dependency detection.
+ */
+export const resolutionContext = createAsyncLocalStorage<ResolutionContextData>()
+
+/**
+ * Runs a function within a resolution context.
+ *
+ * The context tracks which holder is currently being instantiated,
+ * allowing circular dependency detection to work correctly.
+ *
+ * @param waiterHolder The holder being instantiated
+ * @param getHolder Function to retrieve holders by name
+ * @param fn The function to run within the context
+ */
+export function withResolutionContext<T>(
+  waiterHolder: InstanceHolder,
+  getHolder: (name: string) => InstanceHolder | undefined,
+  fn: () => T,
+): T {
+  return resolutionContext.run({ waiterHolder, getHolder }, fn)
+}
+
+/**
+ * Gets the current resolution context, if any.
+ *
+ * Returns undefined if we're not inside a resolution context
+ * (e.g., when resolving a top-level service that has no parent).
+ */
+export function getCurrentResolutionContext(): ResolutionContextData | undefined {
+  return resolutionContext.getStore()
+}
+
+/**
+ * Runs a function outside any resolution context.
+ *
+ * This is useful for async injections that should not participate
+ * in circular dependency detection since they don't block.
+ *
+ * @param fn The function to run without resolution context
+ */
+export function withoutResolutionContext<T>(fn: () => T): T {
+  // Run with undefined context to clear any current context
+  return resolutionContext.run(undefined as any, fn)
+}

package/src/internal/context/sync-local-storage.mts

@@ -0,0 +1,51 @@
+/**
+ * A synchronous-only polyfill for AsyncLocalStorage.
+ *
+ * This provides the same API as Node's AsyncLocalStorage but only works
+ * for synchronous code paths. It uses a simple stack-based approach.
+ *
+ * Limitations:
+ * - Context does NOT propagate across async boundaries (setTimeout, promises, etc.)
+ * - Only suitable for environments where DI resolution is synchronous
+ *
+ * This is acceptable for browser environments where:
+ * 1. Constructors are typically synchronous
+ * 2. Circular dependency detection mainly needs sync tracking
+ */
+export class SyncLocalStorage<T> {
+  private stack: T[] = []
+
+  /**
+   * Runs a function within the given store context.
+   * The context is only available synchronously within the function.
+   */
+  run<R>(store: T, fn: () => R): R {
+    this.stack.push(store)
+    try {
+      return fn()
+    } finally {
+      this.stack.pop()
+    }
+  }
+
+  /**
+   * Gets the current store value, or undefined if not in a context.
+   */
+  getStore(): T | undefined {
+    return this.stack.length > 0 ? this.stack[this.stack.length - 1] : undefined
+  }
+
+  /**
+   * Exits the current context and runs the function without any store.
+   * This matches AsyncLocalStorage.exit() behavior.
+   */
+  exit<R>(fn: () => R): R {
+    const savedStack = this.stack
+    this.stack = []
+    try {
+      return fn()
+    } finally {
+      this.stack = savedStack
+    }
+  }
+}

package/src/internal/core/index.mts

@@ -0,0 +1,5 @@
+export * from './service-locator.mjs'
+export * from './instance-resolver.mjs'
+export * from './instantiator.mjs'
+export * from './invalidator.mjs'
+export * from './token-processor.mjs'