@navios/di 0.5.1 → 0.6.1

package/docs/migration.md

@@ -2,49 +2,317 @@
 
 This guide helps you migrate between different versions of Navios DI.
 
-## Migrating to v0.3.x
+## Migrating to v0.6.0 (Circular Dependency Detection & Browser Support & ScopedContainer)
 
 ### New Features
 
-#### Request Context Management
+#### Circular Dependency Detection
 
-The biggest addition in v0.3.x is request context management. This feature allows you to manage request-scoped services with automatic cleanup.
+v0.5.x adds automatic circular dependency detection. When services form a circular dependency using `inject()`, the system now throws a clear error instead of hanging:
 
-**New APIs:**
+```typescript
+@Injectable()
+class ServiceA {
+  private serviceB = inject(ServiceB)
+}
 
-- `Container.beginRequest(requestId, metadata?, priority?)`
-- `Container.endRequest(requestId)`
-- `Container.getCurrentRequestContext()`
-- `Container.setCurrentRequestContext(requestId)`
-- `RequestContextHolder` interface
+@Injectable()
+class ServiceB {
+  private serviceA = inject(ServiceA)
+}
+
+// Error: Circular dependency detected: ServiceA -> ServiceB -> ServiceA
+await container.get(ServiceA)
+```
 
-**Example:**
+**Breaking circular dependencies** - Use `asyncInject()` on at least one side:
 
 ```typescript
-// New request context API
-const container = new Container()
-const context = container.beginRequest('req-123', { userId: 456 })
-container.setCurrentRequestContext('req-123')
+@Injectable()
+class ServiceA {
+  private serviceB = asyncInject(ServiceB) // Break cycle with asyncInject
 
-// Add request-scoped data
-const REQUEST_ID_TOKEN = InjectionToken.create<string>('REQUEST_ID')
-context.addInstance(REQUEST_ID_TOKEN, 'req-123')
+  async doSomething() {
+    const b = await this.serviceB
+    return b.process()
+  }
+}
 
-// Use in services
 @Injectable()
-class RequestService {
-  private readonly requestId = asyncInject(REQUEST_ID_TOKEN)
+class ServiceB {
+  private serviceA = inject(ServiceA) // This side can use inject()
+}
+```
 
-  async process() {
-    const id = await this.requestId
-    console.log(`Processing request: ${id}`)
-  }
+#### Browser Support
+
+The library now supports browser environments with a dedicated entry point:
+
+```typescript
+// Bundlers automatically select the browser entry via package.json exports
+import { Container, inject } from '@navios/di'
+```
+
+The browser build uses `SyncLocalStorage` instead of `AsyncLocalStorage`, which works for synchronous dependency tracking.
+
+#### Cross-Storage Invalidation
+
+Singletons that depend on request-scoped services are now properly invalidated when the request ends:
+
+```typescript
+@Injectable({ scope: InjectableScope.Request })
+class RequestData {}
+
+@Injectable({ scope: InjectableScope.Singleton })
+class SingletonConsumer {
+  private requestData = inject(RequestData)
 }
 
-// Clean up when done
+// When the request ends:
+await scopedContainer.endRequest()
+// SingletonConsumer is automatically invalidated
+```
+
+### Renamed Types (Deprecated Aliases Available)
+
+For cleaner naming, many internal types have been renamed. Deprecated aliases are provided for backward compatibility:
+
+| Old Name                                | New Name                  |
+| --------------------------------------- | ------------------------- |
+| `ServiceLocatorInstanceHolder`          | `InstanceHolder`          |
+| `ServiceLocatorInstanceHolderStatus`    | `InstanceStatus`          |
+| `ServiceLocatorInstanceEffect`          | `InstanceEffect`          |
+| `ServiceLocatorInstanceDestroyListener` | `InstanceDestroyListener` |
+| `BaseInstanceHolderManager`             | `BaseHolderManager`       |
+| `ServiceLocatorManager`                 | `HolderManager`           |
+| `SingletonHolderStorage`                | `SingletonStorage`        |
+| `RequestHolderStorage`                  | `RequestStorage`          |
+| `ServiceLocatorEventBus`                | `LifecycleEventBus`       |
+| `CircularDependencyDetector`            | `CircularDetector`        |
+| `ServiceInstantiator`                   | `Instantiator`            |
+| `RequestContextHolder`                  | `RequestContext`          |
+| `DefaultRequestContextHolder`           | `DefaultRequestContext`   |
+| `createRequestContextHolder`            | `createRequestContext`    |
+
+### Migration Steps
+
+1. **Update circular dependencies**: If your code hangs during startup, you likely have circular dependencies. Add `asyncInject()` to break the cycle.
+
+2. **Update type imports**: While deprecated aliases work, consider updating to new names:
+
+   ```typescript
+   // Before
+   // After
+   import { InstanceHolder, ServiceLocatorInstanceHolder } from '@navios/di'
+   ```
+
+3. **Browser builds**: No changes needed - bundlers automatically select the correct entry point.
+
+---
+
+## ScopedContainer
+
+### Breaking Changes
+
+v0.4.x introduces `ScopedContainer` for request context management. This is a **breaking change** that fixes race conditions in concurrent request handling.
+
+#### Removed Methods
+
+The following `Container` methods have been **removed**:
+
+- `Container.setCurrentRequestContext(requestId)` - removed
+- `Container.getCurrentRequestContext()` - removed
+- `Container.endRequest(requestId)` - removed (use `ScopedContainer.endRequest()`)
+
+#### Changed Return Type
+
+- `Container.beginRequest()` now returns a `ScopedContainer` instead of `RequestContextHolder`
+
+#### New API
+
+```typescript
+// OLD (v0.3.x) - no longer works
+const context = container.beginRequest('req-123')
+container.setCurrentRequestContext('req-123')
+const service = await container.get(RequestService)
+await container.endRequest('req-123')
+
+// NEW (v0.4.x) - use ScopedContainer
+const scoped = container.beginRequest('req-123')
+const service = await scoped.get(RequestService)
+await scoped.endRequest()
+```
+
+### Migration Steps
+
+#### 1. Update Request Context Creation
+
+**Before:**
+
+```typescript
+const context = container.beginRequest('req-123', { userId: 456 })
+container.setCurrentRequestContext('req-123')
+```
+
+**After:**
+
+```typescript
+const scoped = container.beginRequest('req-123', { userId: 456 })
+```
+
+#### 2. Update Service Resolution
+
+**Before:**
+
+```typescript
+container.setCurrentRequestContext('req-123')
+const service = await container.get(RequestService)
+```
+
+**After:**
+
+```typescript
+const scoped = container.beginRequest('req-123')
+const service = await scoped.get(RequestService)
+```
+
+#### 3. Update Cleanup
+
+**Before:**
+
+```typescript
 await container.endRequest('req-123')
 ```
 
+**After:**
+
+```typescript
+await scoped.endRequest()
+// or
+await scoped.dispose()
+```
+
+#### 4. Update Middleware (Express/Fastify)
+
+**Before:**
+
+```typescript
+app.use(async (req, res, next) => {
+  const requestId = `req-${Date.now()}`
+  const context = container.beginRequest(requestId)
+  container.setCurrentRequestContext(requestId)
+
+  res.on('finish', () => container.endRequest(requestId))
+  next()
+})
+
+app.get('/', async (req, res) => {
+  const service = await container.get(RequestService)
+  res.json(service.getData())
+})
+```
+
+**After:**
+
+```typescript
+app.use(async (req, res, next) => {
+  const requestId = `req-${Date.now()}`
+  const scoped = container.beginRequest(requestId)
+  ;(req as any).scoped = scoped
+
+  res.on('finish', () => scoped.endRequest())
+  next()
+})
+
+app.get('/', async (req, res) => {
+  const scoped = (req as any).scoped
+  const service = await scoped.get(RequestService)
+  res.json(service.getData())
+})
+```
+
+### Why This Change?
+
+The old API had a race condition:
+
+```typescript
+// Request A starts
+container.setCurrentRequestContext('req-A')
+const serviceA = await container.get(RequestService) // async...
+
+// Request B starts while A is still resolving
+container.setCurrentRequestContext('req-B')
+
+// Service A might get Request B's context! Bug!
+```
+
+The new API eliminates this by giving each request its own container:
+
+```typescript
+// Request A
+const scopedA = container.beginRequest('req-A')
+const serviceA = await scopedA.get(RequestService) // Always gets A's context
+
+// Request B
+const scopedB = container.beginRequest('req-B')
+const serviceB = await scopedB.get(RequestService) // Always gets B's context
+
+// No race condition possible
+```
+
+### New Features
+
+#### IContainer Interface
+
+Both `Container` and `ScopedContainer` implement `IContainer`:
+
+```typescript
+interface IContainer {
+  get<T>(token, args?): Promise<T>
+  invalidate(service: unknown): Promise<void>
+  isRegistered(token): boolean
+  dispose(): Promise<void>
+  ready(): Promise<void>
+  tryGetSync<T>(token, args?): T | null
+}
+```
+
+#### Request-Scoped Error Protection
+
+Attempting to get a request-scoped service from Container now throws a helpful error:
+
+```typescript
+await container.get(RequestService)
+// Error: Cannot resolve request-scoped service "RequestService" from Container.
+// Use beginRequest() to create a ScopedContainer for request-scoped services.
+```
+
+#### Active Request Tracking
+
+```typescript
+const scoped = container.beginRequest('req-123')
+container.hasActiveRequest('req-123') // true
+await scoped.endRequest()
+container.hasActiveRequest('req-123') // false
+```
+
+---
+
+## Migrating to v0.3.x
+
+### New Features
+
+#### Request Context Management (Legacy)
+
+> **Note:** This section documents the v0.3.x API which is deprecated in v0.4.x. See "Migrating to v0.4.x" above for the current API.
+
+**Old APIs (deprecated in v0.4.x):**
+
+- `Container.beginRequest(requestId, metadata?, priority?)` - returns `RequestContextHolder` in v0.3.x
+- `Container.endRequest(requestId)` - removed in v0.4.x
+- `Container.getCurrentRequestContext()` - removed in v0.4.x
+- `Container.setCurrentRequestContext(requestId)` - removed in v0.4.x
+
 ### Recommended Changes
 
 #### Prefer `asyncInject` over `inject`
@@ -109,10 +377,11 @@ Some internal type definitions were improved for better TypeScript support, but
 
 **Problem:** Services can't be resolved when using request contexts.
 
-**Solution:** Make sure you've set the current request context:
+**Solution:** Use a `ScopedContainer` for request-scoped services:
 
 ```typescript
-container.setCurrentRequestContext('your-request-id')
+const scoped = container.beginRequest('your-request-id')
+const service = await scoped.get(RequestService)
 ```
 
 ### Issue: Async dependencies not ready
@@ -133,14 +402,15 @@ private readonly service = asyncInject(AsyncService)
 
 **Problem:** Request contexts not being cleaned up.
 
-**Solution:** Always call `endRequest()`:
+**Solution:** Always call `endRequest()` on the ScopedContainer:
 
 ```typescript
+const scoped = container.beginRequest('req-123')
 try {
-  const context = container.beginRequest('req-123')
+  const service = await scoped.get(RequestService)
   // ... process request
 } finally {
-  await container.endRequest('req-123')
+  await scoped.endRequest()
 }
 ```
 
@@ -155,7 +425,24 @@ If you encounter issues during migration:
 
 ## Changelog Summary
 
-### v0.3.1
+### v0.5.x
+
+- **Circular Dependency Detection**: Automatic detection with clear error messages
+- **Browser Support**: Dedicated browser entry point with `SyncLocalStorage` polyfill
+- **Cross-Storage Invalidation**: Singletons depending on request-scoped services are properly invalidated
+- **Resolution Context**: Uses `AsyncLocalStorage` to track resolution across async boundaries
+- **Type Renames**: Cleaner names for internal types (with deprecated aliases)
+- **Platform Support**: Node.js, Bun, Deno, and browser environments
+
+### v0.4.x
+
+- **ScopedContainer**: New request context management API
+- **Race Condition Fix**: Eliminates concurrency issues with request-scoped services
+- **IContainer Interface**: Common interface for `Container` and `ScopedContainer`
+- **Request-Scoped Errors**: Clear error when resolving request-scoped from `Container`
+- **Active Request Tracking**: `hasActiveRequest()` and `getActiveRequestIds()` methods
+
+### v0.3.x
 
 - Added request context management
 - Improved TypeScript type definitions
@@ -163,12 +450,6 @@ If you encounter issues during migration:
 - New `RequestContextHolder` interface
 - Better error messages for injection failures
 
-### v0.3.0
-
-- Initial release with request context support
-- Container API improvements
-- Better async injection handling
-
 ### v0.2.x
 
 - Basic dependency injection functionality