@navios/di 0.6.1 → 0.7.1

package/src/__tests__/library-findings.spec.mts

@@ -10,10 +10,11 @@
 
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
+import type { OnServiceDestroy } from '../interfaces/on-service-destroy.interface.mjs'
+
 import { Container } from '../container/container.mjs'
 import { Injectable } from '../decorators/injectable.decorator.mjs'
 import { InjectableScope } from '../enums/index.mjs'
-import type { OnServiceDestroy } from '../interfaces/on-service-destroy.interface.mjs'
 import { Registry } from '../token/registry.mjs'
 import { getInjectors } from '../utils/get-injectors.mjs'
 
@@ -244,19 +245,17 @@ describe('FINDING #3: Error Recovery', () => {
   })
 
   /**
-   * DOCUMENTED BEHAVIOR: Container caches constructor errors
+   * DOCUMENTED BEHAVIOR: Container allows retry after constructor errors
    *
    * When a service constructor throws on first attempt, the container
-   * caches the error state and re-throws the same error on subsequent
-   * attempts. It does NOT retry the constructor.
+   * removes the failed holder from storage. This allows subsequent
+   * attempts to retry creating the service.
    *
-   * This is important to understand for services that might fail due to
-   * transient errors (network issues, resource unavailability, etc.).
-   *
-   * IMPLICATION: If you need retry logic for transient failures, implement
-   * it inside the service (e.g., in onServiceInit) or use a factory pattern.
+   * This is useful for services that might fail due to transient errors
+   * (network issues, resource unavailability, etc.) - they can be
+   * successfully created on retry once the transient issue is resolved.
    */
-  it('caches constructor errors and re-throws on retry (documented behavior)', async () => {
+  it('allows retry after constructor errors (documented behavior)', async () => {
     let attemptCount = 0
     const shouldFail = { value: true }
 
@@ -283,12 +282,11 @@ describe('FINDING #3: Error Recovery', () => {
     // Allow success on retry
     shouldFail.value = false
 
-    // Second attempt - container caches the error and re-throws
-    // The constructor is NOT called again
-    await expect(container.get(FlakeyService)).rejects.toThrow(
-      'Transient failure',
-    )
-    expect(attemptCount).toBe(1) // Still 1, constructor was not retried
+    // Second attempt - container allows retry by removing the error holder
+    // The constructor IS called again
+    const instance = await container.get(FlakeyService)
+    expect(instance.getValue()).toBe('success')
+    expect(attemptCount).toBe(2) // Constructor was retried
   })
 
   /**
@@ -502,15 +500,19 @@ describe('FINDING #5: Cross-Storage Dependency Invalidation', () => {
 
     // Check that the singleton's holder has the request service in deps
     const manager = container.getServiceLocator().getManager()
-    const singletonHolders = Array.from(manager.filter((h) => h.scope === InjectableScope.Singleton).values())
+    const singletonHolders = Array.from(
+      manager.filter((h) => h.scope === InjectableScope.Singleton).values(),
+    )
 
     // Find the SingletonWithDep holder
-    const singletonHolder = singletonHolders.find(h => h.name.includes('SingletonWithDep'))
+    const singletonHolder = singletonHolders.find((h) =>
+      h.name.includes('SingletonWithDep'),
+    )
 
     if (singletonHolder) {
       // The deps should contain the RequestService instance name
-      const hasRequestDep = Array.from(singletonHolder.deps).some(dep =>
-        dep.includes('RequestService')
+      const hasRequestDep = Array.from(singletonHolder.deps).some((dep) =>
+        dep.includes('RequestService'),
       )
       expect(hasRequestDep).toBe(true)
     }
@@ -547,7 +549,7 @@ describe('FINDING #5: Cross-Storage Dependency Invalidation', () => {
  *      invalidated when the request ends
  *
  * EDGE CASES (documented behavior):
- * 3. Error recovery behavior - constructor errors are cached
+ * 3. Error recovery behavior - constructor errors are cached - FIXED
  *    - Priority: Low
  *    - Impact: May prevent retry after transient failures
  *    - Documented: This is intentional, use onServiceInit for retry logic

package/src/browser.mts

@@ -1,16 +1,11 @@
 /**
  * Browser-specific entry point for @navios/di.
  *
- * This entry point forces the use of SyncLocalStorage instead of
- * Node's AsyncLocalStorage, making it safe for browser environments.
- *
- * The browser build is automatically selected by bundlers that respect
+ * This entry point is automatically selected by bundlers that respect
  * the "browser" condition in package.json exports.
+ *
+ * The browser build uses SyncLocalStorage instead of Node's AsyncLocalStorage,
+ * which is sufficient for synchronous DI resolution in browser environments.
  */
 
-// Force sync mode before any other imports initialize the storage
-import { __testing__ } from './internal/context/async-local-storage.mjs'
-__testing__.forceSyncMode()
-
-// Re-export everything from the main entry
 export * from './index.mjs'

package/src/container/scoped-container.mts

@@ -302,15 +302,21 @@ export class ScopedContainer implements IContainer {
     // Check if we already have this instance (or one is being created)
     const existingHolder = this.requestContextHolder.get(instanceName)
     if (existingHolder) {
-      // Wait for the holder to be ready if it's still being created
-      // This prevents race conditions where multiple concurrent calls
-      // might try to create the same service
-      const [error, readyHolder] =
-        await BaseHolderManager.waitForHolderReady(existingHolder)
-      if (error) {
-        throw error
+      // If the holder is in error state, remove it so we can retry
+      if (existingHolder.status === InstanceStatus.Error) {
+        this.requestContextHolder.delete(instanceName)
+        // Fall through to create a new instance
+      } else {
+        // Wait for the holder to be ready if it's still being created
+        // This prevents race conditions where multiple concurrent calls
+        // might try to create the same service
+        const [error, readyHolder] =
+          await BaseHolderManager.waitForHolderReady(existingHolder)
+        if (error) {
+          throw error
+        }
+        return readyHolder.instance
       }
-      return readyHolder.instance
     }
 
     // Create new instance using parent's resolution mechanism

package/src/index.mts

@@ -36,7 +36,11 @@ export {
   type InjectionTokenSchemaType,
 } from './token/injection-token.mjs'
 
-export { Registry, globalRegistry, type FactoryRecord } from './token/registry.mjs'
+export {
+  Registry,
+  globalRegistry,
+  type FactoryRecord,
+} from './token/registry.mjs'
 
 // ============================================================================
 // PUBLIC API - Decorators
@@ -93,12 +97,6 @@ export {
   provideFactoryContext,
 } from './injectors.mjs'
 
-// ============================================================================
-// PUBLIC API - Testing
-// ============================================================================
-
-export * from './testing/index.mjs'
-
 // ============================================================================
 // INTERNAL API (exported for advanced use cases)
 // ============================================================================
@@ -113,7 +111,6 @@ export {
 } from './internal/context/request-context.mjs'
 export {
   type ResolutionContextData,
-  resolutionContext,
   withResolutionContext,
   getCurrentResolutionContext,
   withoutResolutionContext,

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

@@ -0,0 +1,19 @@
+/**
+ * Browser implementation using SyncLocalStorage.
+ *
+ * This module is used in browser environments where async_hooks is not available.
+ * It provides synchronous-only context tracking which is sufficient for
+ * browser-based DI resolution.
+ */
+
+import { SyncLocalStorage } from './sync-local-storage.mjs'
+
+export type { IAsyncLocalStorage } from './async-local-storage.types.mjs'
+
+export function createAsyncLocalStorage<T>() {
+  return new SyncLocalStorage<T>()
+}
+
+export function isUsingNativeAsyncLocalStorage(): boolean {
+  return false
+}

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

@@ -1,120 +1,68 @@
-/**
- * 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
-}
+import { AsyncLocalStorage } from 'node:async_hooks'
 
 /**
- * Detects if we're running in a Node.js-like environment with async_hooks support.
+ * Cross-platform AsyncLocalStorage switcher.
+ *
+ * Provides the appropriate implementation based on environment:
+ * - Production: No-op implementation (circular detection disabled)
+ * - Development: Native AsyncLocalStorage from node:async_hooks
+ *
+ * Browser environments use a separate entry point via package.json exports
+ * that directly uses SyncLocalStorage.
+ *
+ * Uses lazy initialization to avoid import overhead until first use,
+ * and works with both ESM and CJS builds.
  */
-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
-  }
+import type { IAsyncLocalStorage } from './async-local-storage.types.mjs'
 
-  // 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
-  }
+export type { IAsyncLocalStorage }
 
-  return false
-}
+const isProduction = process.env.NODE_ENV === 'production'
 
-// Cache for the AsyncLocalStorage class
-let AsyncLocalStorageClass: (new <T>() => IAsyncLocalStorage<T>) | null = null
-let initialized = false
-let forceSyncMode = false
+// Lazy-loaded module cache
+let loadedModule: {
+  createAsyncLocalStorage: <T>() => IAsyncLocalStorage<T>
+  isUsingNativeAsyncLocalStorage: () => boolean
+} | null = null
 
-/**
- * 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!
+function getModule() {
+  if (loadedModule) {
+    return loadedModule
   }
 
-  initialized = true
+  if (isProduction) {
+    // In production, use the noop implementation
+    // Inline to avoid any import overhead
+    class NoopLocalStorage<T> implements IAsyncLocalStorage<T> {
+      run<R>(_store: T, fn: () => R): R {
+        return fn()
+      }
+      getStore(): T | undefined {
+        return undefined
+      }
+    }
 
-  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
+    loadedModule = {
+      createAsyncLocalStorage: <T,>() => new NoopLocalStorage<T>(),
+      isUsingNativeAsyncLocalStorage: () => false,
     }
   } else {
-    AsyncLocalStorageClass = SyncLocalStorage as any
+    // In development, use native AsyncLocalStorage
+
+    loadedModule = {
+      createAsyncLocalStorage: <T,>() => new AsyncLocalStorage<T>(),
+      isUsingNativeAsyncLocalStorage: () => true,
+    }
   }
 
-  return AsyncLocalStorageClass!
+  return loadedModule
 }
 
-/**
- * Creates a new AsyncLocalStorage instance appropriate for the current environment.
- */
 export function createAsyncLocalStorage<T>(): IAsyncLocalStorage<T> {
-  const StorageClass = getAsyncLocalStorageClass()
-  return new StorageClass<T>()
+  return getModule().createAsyncLocalStorage<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
-  },
+  return getModule().isUsingNativeAsyncLocalStorage()
 }

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

@@ -0,0 +1,7 @@
+/**
+ * Interface matching the subset of AsyncLocalStorage API we use.
+ */
+export interface IAsyncLocalStorage<T> {
+  run<R>(store: T, fn: () => R): R
+  getStore(): T | undefined
+}

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

@@ -1,4 +1,5 @@
 import type { InstanceHolder } from '../holder/instance-holder.mjs'
+import type { IAsyncLocalStorage } from './async-local-storage.types.mjs'
 
 import { createAsyncLocalStorage } from './async-local-storage.mjs'
 
@@ -18,8 +19,20 @@ export interface ResolutionContextData {
  * 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.
+ *
+ * The actual implementation varies by environment:
+ * - Production: No-op (returns undefined, run() just calls fn directly)
+ * - Development: Real AsyncLocalStorage with full async tracking
+ * - Browser: SyncLocalStorage for synchronous-only tracking
  */
-export const resolutionContext = createAsyncLocalStorage<ResolutionContextData>()
+let resolutionContext: IAsyncLocalStorage<ResolutionContextData> | null = null
+
+function getResolutionContext(): IAsyncLocalStorage<ResolutionContextData> {
+  if (!resolutionContext) {
+    resolutionContext = createAsyncLocalStorage<ResolutionContextData>()
+  }
+  return resolutionContext
+}
 
 /**
  * Runs a function within a resolution context.
@@ -36,7 +49,7 @@ export function withResolutionContext<T>(
   getHolder: (name: string) => InstanceHolder | undefined,
   fn: () => T,
 ): T {
-  return resolutionContext.run({ waiterHolder, getHolder }, fn)
+  return getResolutionContext().run({ waiterHolder, getHolder }, fn)
 }
 
 /**
@@ -45,8 +58,10 @@ export function withResolutionContext<T>(
  * 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()
+export function getCurrentResolutionContext():
+  | ResolutionContextData
+  | undefined {
+  return getResolutionContext().getStore()
 }
 
 /**
@@ -59,5 +74,8 @@ export function getCurrentResolutionContext(): ResolutionContextData | undefined
  */
 export function withoutResolutionContext<T>(fn: () => T): T {
   // Run with undefined context to clear any current context
-  return resolutionContext.run(undefined as any, fn)
+  return getResolutionContext().run(
+    undefined as unknown as ResolutionContextData,
+    fn,
+  )
 }

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

@@ -1,3 +1,5 @@
+import type { IAsyncLocalStorage } from './async-local-storage.types.mjs'
+
 /**
  * A synchronous-only polyfill for AsyncLocalStorage.
  *
@@ -12,7 +14,7 @@
  * 1. Constructors are typically synchronous
  * 2. Circular dependency detection mainly needs sync tracking
  */
-export class SyncLocalStorage<T> {
+export class SyncLocalStorage<T> implements IAsyncLocalStorage<T> {
   private stack: T[] = []
 
   /**

package/src/internal/core/instance-resolver.mts

@@ -213,7 +213,14 @@ export class InstanceResolver {
         return null // Proceed with creation
 
       default:
-        return [error]
+        // For error states, remove the failed holder from storage so we can retry
+        if (holder) {
+          this.logger?.log(
+            `[InstanceResolver] Removing failed instance ${instanceName} from storage to allow retry`,
+          )
+          storage.delete(instanceName)
+        }
+        return null // Proceed with creation
     }
   }
 

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

@@ -1,11 +1,19 @@
 import type { InstanceHolder } from '../holder/instance-holder.mjs'
 
+/**
+ * Whether we're running in production mode.
+ * In production, circular dependency detection is skipped for performance.
+ */
+const isProduction = process.env.NODE_ENV === 'production'
+
 /**
  * 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.
+ *
+ * Note: In production (NODE_ENV === 'production'), detection is skipped for performance.
  */
 export class CircularDetector {
   /**
@@ -14,6 +22,8 @@ export class CircularDetector {
    * 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.
    *
+   * In production mode, this always returns null to skip the BFS traversal overhead.
+   *
    * @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
@@ -24,6 +34,11 @@ export class CircularDetector {
     targetName: string,
     getHolder: (name: string) => InstanceHolder | undefined,
   ): string[] | null {
+    // Skip circular dependency detection in production for performance
+    if (isProduction) {
+      return 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[] }> = [

package/src/token/registry.mts

@@ -49,6 +49,27 @@ export class Registry {
   delete(token: InjectionToken<any, any>) {
     this.factories.delete(token.id)
   }
+
+  /**
+   * Updates the scope of an already registered factory.
+   * This is useful when you need to dynamically change a service's scope
+   * (e.g., when a singleton controller has request-scoped dependencies).
+   *
+   * @param token The injection token to update
+   * @param scope The new scope to set
+   * @returns true if the scope was updated, false if the token was not found
+   */
+  updateScope(token: InjectionToken<any, any>, scope: InjectableScope): boolean {
+    const factory = this.factories.get(token.id)
+    if (factory) {
+      factory.scope = scope
+      return true
+    }
+    if (this.parent) {
+      return this.parent.updateScope(token, scope)
+    }
+    return false
+  }
 }
 
 export const globalRegistry = new Registry()

package/tsdown.config.mts

@@ -33,7 +33,7 @@ export default defineConfig([
       ),
     ],
   },
-  // Browser build - uses dedicated entry that forces SyncLocalStorage
+  // Browser build - uses SyncLocalStorage and skips async_hooks entirely
   {
     entry: {
       'browser/index': 'src/browser.mts',
@@ -45,6 +45,17 @@ export default defineConfig([
     platform: 'browser',
     dts: true,
     target: 'es2022',
+    inputOptions(options) {
+      return {
+        ...options,
+        resolve: {
+          ...options.resolve,
+          alias: {
+            './async-local-storage.mjs': './async-local-storage.browser.mjs',
+          },
+        },
+      }
+    },
     plugins: [
       withFilter(
         swc.rolldown({

package/vitest.config.mts

@@ -2,8 +2,30 @@ import { defineProject } from 'vitest/config'
 
 export default defineProject({
   test: {
-    typecheck: {
-      enabled: true,
-    },
+    projects: [
+      {
+        test: {
+          include: ['src/**/__tests__/**/*.spec.mts'],
+          exclude: ['src/**/__tests__/**/*.browser.spec.mts'],
+        },
+      },
+      {
+        test: {
+          include: ['src/**/__tests__/**/*.browser.spec.mts'],
+        },
+        resolve: {
+          alias: {
+            './async-local-storage.mjs': './async-local-storage.browser.mjs',
+          },
+        },
+      },
+      {
+        test: {
+          typecheck: {
+            enabled: true,
+          },
+        },
+      },
+    ],
   },
 })