@navios/di 0.5.0 → 0.6.0

package/src/__tests__/async-local-storage.browser.spec.mts

@@ -0,0 +1,240 @@
+/**
+ * Browser environment tests for AsyncLocalStorage.
+ *
+ * These tests verify that:
+ * 1. The SyncLocalStorage polyfill works correctly
+ * 2. All DI functionality works correctly with the polyfill
+ * 3. The resolution context pattern works for synchronous operations
+ *
+ * Note: We use __testing__.forceSyncMode() to simulate browser behavior
+ * since happy-dom still runs on Node.js and has process.versions.node.
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+
+import {
+  createAsyncLocalStorage,
+  isUsingNativeAsyncLocalStorage,
+  __testing__,
+} from '../internal/context/async-local-storage.mjs'
+import {
+  getCurrentResolutionContext,
+  withResolutionContext,
+  withoutResolutionContext,
+} from '../internal/context/resolution-context.mjs'
+import type { InstanceHolder } from '../internal/holder/instance-holder.mjs'
+import { InstanceStatus } from '../internal/holder/instance-holder.mjs'
+import { InjectableScope } from '../enums/index.mjs'
+
+// Force sync mode for all tests in this file to simulate browser behavior
+beforeAll(() => {
+  __testing__.forceSyncMode()
+})
+
+afterAll(() => {
+  __testing__.reset()
+})
+
+// ============================================================================
+// SECTION 1: Environment Detection
+// ============================================================================
+
+describe('Browser Environment Detection (forced sync mode)', () => {
+  it('should use sync polyfill when forced', () => {
+    // After forcing sync mode, native AsyncLocalStorage should not be used
+    expect(isUsingNativeAsyncLocalStorage()).toBe(false)
+  })
+
+  it('should create a working storage instance', () => {
+    const storage = createAsyncLocalStorage<{ value: number }>()
+    expect(storage).toBeDefined()
+    expect(typeof storage.run).toBe('function')
+    expect(typeof storage.getStore).toBe('function')
+  })
+})
+
+// ============================================================================
+// SECTION 2: SyncLocalStorage Behavior in Browser
+// ============================================================================
+
+describe('SyncLocalStorage in Browser', () => {
+  it('should store and retrieve context synchronously', () => {
+    const storage = createAsyncLocalStorage<{ name: string }>()
+
+    expect(storage.getStore()).toBeUndefined()
+
+    storage.run({ name: 'test' }, () => {
+      expect(storage.getStore()?.name).toBe('test')
+    })
+
+    expect(storage.getStore()).toBeUndefined()
+  })
+
+  it('should handle nested contexts', () => {
+    const storage = createAsyncLocalStorage<{ depth: number }>()
+
+    storage.run({ depth: 1 }, () => {
+      expect(storage.getStore()?.depth).toBe(1)
+
+      storage.run({ depth: 2 }, () => {
+        expect(storage.getStore()?.depth).toBe(2)
+
+        storage.run({ depth: 3 }, () => {
+          expect(storage.getStore()?.depth).toBe(3)
+        })
+
+        expect(storage.getStore()?.depth).toBe(2)
+      })
+
+      expect(storage.getStore()?.depth).toBe(1)
+    })
+
+    expect(storage.getStore()).toBeUndefined()
+  })
+
+  it('should restore context after exceptions', () => {
+    const storage = createAsyncLocalStorage<{ value: number }>()
+
+    storage.run({ value: 1 }, () => {
+      try {
+        storage.run({ value: 2 }, () => {
+          throw new Error('test error')
+        })
+      } catch {
+        // Expected
+      }
+
+      // Should be back to outer context
+      expect(storage.getStore()?.value).toBe(1)
+    })
+  })
+})
+
+// ============================================================================
+// SECTION 3: Resolution Context Integration
+// ============================================================================
+
+describe('Resolution Context in Browser', () => {
+  function createMockHolder(name: string): InstanceHolder {
+    return {
+      status: InstanceStatus.Creating,
+      name,
+      instance: null,
+      creationPromise: null,
+      destroyPromise: null,
+      type: class {} as unknown as InstanceHolder['type'],
+      scope: InjectableScope.Singleton,
+      deps: new Set(),
+      destroyListeners: [],
+      createdAt: Date.now(),
+      waitingFor: new Set(),
+    }
+  }
+
+  it('should track resolution context correctly', () => {
+    const holderA = createMockHolder('ServiceA')
+    const getHolder = () => undefined
+
+    expect(getCurrentResolutionContext()).toBeUndefined()
+
+    withResolutionContext(holderA, getHolder, () => {
+      const ctx = getCurrentResolutionContext()
+      expect(ctx).toBeDefined()
+      expect(ctx?.waiterHolder).toBe(holderA)
+    })
+
+    expect(getCurrentResolutionContext()).toBeUndefined()
+  })
+
+  it('should handle nested resolution contexts', () => {
+    const holderA = createMockHolder('ServiceA')
+    const holderB = createMockHolder('ServiceB')
+    const getHolder = () => undefined
+
+    withResolutionContext(holderA, getHolder, () => {
+      expect(getCurrentResolutionContext()?.waiterHolder.name).toBe('ServiceA')
+
+      withResolutionContext(holderB, getHolder, () => {
+        expect(getCurrentResolutionContext()?.waiterHolder.name).toBe(
+          'ServiceB',
+        )
+      })
+
+      expect(getCurrentResolutionContext()?.waiterHolder.name).toBe('ServiceA')
+    })
+  })
+
+  it('should clear context with withoutResolutionContext', () => {
+    const holderA = createMockHolder('ServiceA')
+    const getHolder = () => undefined
+
+    withResolutionContext(holderA, getHolder, () => {
+      expect(getCurrentResolutionContext()).toBeDefined()
+
+      withoutResolutionContext(() => {
+        expect(getCurrentResolutionContext()).toBeUndefined()
+      })
+
+      expect(getCurrentResolutionContext()).toBeDefined()
+    })
+  })
+})
+
+// ============================================================================
+// SECTION 4: Async Limitations in Browser
+// ============================================================================
+
+describe('Async Limitations in Browser (expected behavior)', () => {
+  it('should NOT propagate context across microtasks', async () => {
+    const storage = createAsyncLocalStorage<{ value: number }>()
+
+    let valueInMicrotask: number | undefined
+
+    storage.run({ value: 42 }, () => {
+      // Queue a microtask
+      Promise.resolve().then(() => {
+        // In browser with SyncLocalStorage, context is lost
+        valueInMicrotask = storage.getStore()?.value
+      })
+    })
+
+    // Wait for microtask to complete
+    await Promise.resolve()
+    await Promise.resolve()
+
+    // Context should be undefined because SyncLocalStorage doesn't propagate
+    expect(valueInMicrotask).toBeUndefined()
+  })
+
+  it('should NOT propagate context across setTimeout', async () => {
+    const storage = createAsyncLocalStorage<{ value: number }>()
+
+    const valuePromise = new Promise<number | undefined>((resolve) => {
+      storage.run({ value: 42 }, () => {
+        setTimeout(() => {
+          resolve(storage.getStore()?.value)
+        }, 0)
+      })
+    })
+
+    const value = await valuePromise
+    // Context should be undefined
+    expect(value).toBeUndefined()
+  })
+
+  it('should still work for synchronous code in async functions', () => {
+    const storage = createAsyncLocalStorage<{ value: number }>()
+
+    // This is the key behavior: even in browser, synchronous access works
+    storage.run({ value: 42 }, () => {
+      // Synchronous access within the run callback works
+      expect(storage.getStore()?.value).toBe(42)
+
+      // Nested synchronous calls work
+      function nestedCall() {
+        return storage.getStore()?.value
+      }
+      expect(nestedCall()).toBe(42)
+    })
+  })
+})

package/src/__tests__/async-local-storage.spec.mts

@@ -0,0 +1,333 @@
+/**
+ * Tests for the cross-platform AsyncLocalStorage implementation.
+ *
+ * These tests verify:
+ * 1. SyncLocalStorage polyfill works correctly for synchronous code
+ * 2. The runtime detection correctly identifies the environment
+ * 3. Both implementations provide consistent behavior for sync use cases
+ */
+
+import { describe, expect, it } from 'vitest'
+
+import { SyncLocalStorage } from '../internal/context/sync-local-storage.mjs'
+import {
+  createAsyncLocalStorage,
+  isUsingNativeAsyncLocalStorage,
+} from '../internal/context/async-local-storage.mjs'
+
+// ============================================================================
+// SECTION 1: SyncLocalStorage Unit Tests
+// ============================================================================
+
+describe('SyncLocalStorage', () => {
+  it('should return undefined when no context is active', () => {
+    const storage = new SyncLocalStorage<{ value: number }>()
+    expect(storage.getStore()).toBeUndefined()
+  })
+
+  it('should return the store within a run() call', () => {
+    const storage = new SyncLocalStorage<{ value: number }>()
+    const store = { value: 42 }
+
+    storage.run(store, () => {
+      expect(storage.getStore()).toBe(store)
+    })
+  })
+
+  it('should return undefined after run() completes', () => {
+    const storage = new SyncLocalStorage<{ value: number }>()
+    const store = { value: 42 }
+
+    storage.run(store, () => {
+      // Inside context
+    })
+
+    expect(storage.getStore()).toBeUndefined()
+  })
+
+  it('should handle nested run() calls correctly', () => {
+    const storage = new SyncLocalStorage<{ value: number }>()
+    const outer = { value: 1 }
+    const inner = { value: 2 }
+
+    storage.run(outer, () => {
+      expect(storage.getStore()).toBe(outer)
+
+      storage.run(inner, () => {
+        expect(storage.getStore()).toBe(inner)
+      })
+
+      // After inner run completes, should be back to outer
+      expect(storage.getStore()).toBe(outer)
+    })
+
+    // After all runs complete
+    expect(storage.getStore()).toBeUndefined()
+  })
+
+  it('should handle deeply nested run() calls', () => {
+    const storage = new SyncLocalStorage<{ depth: number }>()
+    const stores = Array.from({ length: 5 }, (_, i) => ({ depth: i }))
+
+    function nest(depth: number): void {
+      if (depth >= stores.length) return
+
+      storage.run(stores[depth], () => {
+        expect(storage.getStore()).toBe(stores[depth])
+        nest(depth + 1)
+        expect(storage.getStore()).toBe(stores[depth])
+      })
+    }
+
+    nest(0)
+    expect(storage.getStore()).toBeUndefined()
+  })
+
+  it('should return the value from run()', () => {
+    const storage = new SyncLocalStorage<{ value: number }>()
+    const store = { value: 42 }
+
+    const result = storage.run(store, () => {
+      return 'hello'
+    })
+
+    expect(result).toBe('hello')
+  })
+
+  it('should propagate errors and still restore context', () => {
+    const storage = new SyncLocalStorage<{ value: number }>()
+    const store = { value: 42 }
+
+    expect(() => {
+      storage.run(store, () => {
+        throw new Error('test error')
+      })
+    }).toThrow('test error')
+
+    // Context should be restored even after error
+    expect(storage.getStore()).toBeUndefined()
+  })
+
+  it('should restore context after error in nested run()', () => {
+    const storage = new SyncLocalStorage<{ value: number }>()
+    const outer = { value: 1 }
+    const inner = { value: 2 }
+
+    storage.run(outer, () => {
+      try {
+        storage.run(inner, () => {
+          throw new Error('inner error')
+        })
+      } catch {
+        // Catch the error
+      }
+
+      // Should be back to outer context
+      expect(storage.getStore()).toBe(outer)
+    })
+  })
+
+  it('exit() should clear the context temporarily', () => {
+    const storage = new SyncLocalStorage<{ value: number }>()
+    const store = { value: 42 }
+
+    storage.run(store, () => {
+      expect(storage.getStore()).toBe(store)
+
+      storage.exit(() => {
+        expect(storage.getStore()).toBeUndefined()
+      })
+
+      // After exit, should be back to the original context
+      expect(storage.getStore()).toBe(store)
+    })
+  })
+
+  it('exit() should restore context after error', () => {
+    const storage = new SyncLocalStorage<{ value: number }>()
+    const store = { value: 42 }
+
+    storage.run(store, () => {
+      try {
+        storage.exit(() => {
+          throw new Error('exit error')
+        })
+      } catch {
+        // Catch the error
+      }
+
+      // Context should be restored
+      expect(storage.getStore()).toBe(store)
+    })
+  })
+})
+
+// ============================================================================
+// SECTION 2: createAsyncLocalStorage Tests
+// ============================================================================
+
+describe('createAsyncLocalStorage', () => {
+  it('should create a storage instance', () => {
+    const storage = createAsyncLocalStorage<{ value: number }>()
+    expect(storage).toBeDefined()
+    expect(typeof storage.run).toBe('function')
+    expect(typeof storage.getStore).toBe('function')
+  })
+
+  it('should work with run() and getStore()', () => {
+    const storage = createAsyncLocalStorage<{ value: number }>()
+    const store = { value: 42 }
+
+    storage.run(store, () => {
+      expect(storage.getStore()).toBe(store)
+    })
+
+    expect(storage.getStore()).toBeUndefined()
+  })
+
+  it('should handle nested contexts', () => {
+    const storage = createAsyncLocalStorage<{ name: string }>()
+
+    storage.run({ name: 'outer' }, () => {
+      expect(storage.getStore()?.name).toBe('outer')
+
+      storage.run({ name: 'inner' }, () => {
+        expect(storage.getStore()?.name).toBe('inner')
+      })
+
+      expect(storage.getStore()?.name).toBe('outer')
+    })
+  })
+})
+
+// ============================================================================
+// SECTION 3: Environment Detection Tests
+// ============================================================================
+
+describe('isUsingNativeAsyncLocalStorage', () => {
+  it('should return a boolean', () => {
+    const result = isUsingNativeAsyncLocalStorage()
+    expect(typeof result).toBe('boolean')
+  })
+
+  it('should return true in Node.js environment', () => {
+    // Since we're running in Node.js (vitest), this should be true
+    expect(isUsingNativeAsyncLocalStorage()).toBe(true)
+  })
+})
+
+// ============================================================================
+// SECTION 4: Integration with resolution context pattern
+// ============================================================================
+
+describe('Resolution Context Pattern', () => {
+  interface ResolutionContextData {
+    waiterName: string
+    depth: number
+  }
+
+  it('should work with the resolution context pattern', () => {
+    const resolutionContext = createAsyncLocalStorage<ResolutionContextData>()
+
+    function withResolutionContext<T>(
+      waiterName: string,
+      depth: number,
+      fn: () => T,
+    ): T {
+      return resolutionContext.run({ waiterName, depth }, fn)
+    }
+
+    function getCurrentContext(): ResolutionContextData | undefined {
+      return resolutionContext.getStore()
+    }
+
+    // Simulate nested service resolution
+    withResolutionContext('ServiceA', 0, () => {
+      const ctxA = getCurrentContext()
+      expect(ctxA?.waiterName).toBe('ServiceA')
+      expect(ctxA?.depth).toBe(0)
+
+      withResolutionContext('ServiceB', 1, () => {
+        const ctxB = getCurrentContext()
+        expect(ctxB?.waiterName).toBe('ServiceB')
+        expect(ctxB?.depth).toBe(1)
+      })
+
+      // Back to ServiceA context
+      const ctxAfter = getCurrentContext()
+      expect(ctxAfter?.waiterName).toBe('ServiceA')
+    })
+
+    // Outside all contexts
+    expect(getCurrentContext()).toBeUndefined()
+  })
+
+  it('should handle withoutResolutionContext pattern', () => {
+    const resolutionContext = createAsyncLocalStorage<ResolutionContextData>()
+
+    function withoutResolutionContext<T>(fn: () => T): T {
+      return resolutionContext.run(undefined as any, fn)
+    }
+
+    resolutionContext.run({ waiterName: 'Service', depth: 0 }, () => {
+      expect(resolutionContext.getStore()?.waiterName).toBe('Service')
+
+      withoutResolutionContext(() => {
+        // Context should be cleared (undefined-ish)
+        const store = resolutionContext.getStore()
+        expect(store === undefined || store === null).toBe(true)
+      })
+
+      // Context should be restored
+      expect(resolutionContext.getStore()?.waiterName).toBe('Service')
+    })
+  })
+})
+
+// ============================================================================
+// SECTION 5: Async behavior tests (Node.js native only)
+// ============================================================================
+
+describe('Async behavior (native AsyncLocalStorage)', () => {
+  it('should propagate context through async/await in Node.js', async () => {
+    // Skip if not using native (though in Node.js vitest, it should be native)
+    if (!isUsingNativeAsyncLocalStorage()) {
+      return
+    }
+
+    const storage = createAsyncLocalStorage<{ value: number }>()
+    const store = { value: 42 }
+
+    await storage.run(store, async () => {
+      // Sync check
+      expect(storage.getStore()).toBe(store)
+
+      // After await
+      await Promise.resolve()
+      expect(storage.getStore()).toBe(store)
+
+      // After setTimeout wrapped in promise
+      await new Promise((resolve) => setTimeout(resolve, 10))
+      expect(storage.getStore()).toBe(store)
+    })
+  })
+
+  it('should propagate context through Promise.all in Node.js', async () => {
+    if (!isUsingNativeAsyncLocalStorage()) {
+      return
+    }
+
+    const storage = createAsyncLocalStorage<{ value: number }>()
+    const store = { value: 42 }
+
+    await storage.run(store, async () => {
+      const results = await Promise.all([
+        Promise.resolve().then(() => storage.getStore()?.value),
+        Promise.resolve().then(() => storage.getStore()?.value),
+        Promise.resolve().then(() => storage.getStore()?.value),
+      ])
+
+      expect(results).toEqual([42, 42, 42])
+    })
+  })
+})