@navios/di 0.3.0 → 0.4.0

package/docs/container.md

@@ -143,6 +143,41 @@ const serviceLocator = container.getServiceLocator()
 const instance = await serviceLocator.getOrThrowInstance(UserService)
 ```
 
+## Request Context Management
+
+The Container provides built-in support for request contexts, allowing you to manage request-scoped services:
+
+```typescript
+const container = new Container()
+
+// Begin a request context
+const context = container.beginRequest('req-123', { userId: 456 }, 100)
+
+// Add request-specific instances
+const REQUEST_ID_TOKEN = InjectionToken.create<string>('REQUEST_ID')
+context.addInstance(REQUEST_ID_TOKEN, 'req-123')
+
+// Set as current context
+container.setCurrentRequestContext('req-123')
+
+// Services can now access request-scoped data
+@Injectable()
+class RequestService {
+  private readonly requestId = asyncInject(REQUEST_ID_TOKEN)
+
+  async process() {
+    const id = await this.requestId
+    console.log(`Processing in request: ${id}`)
+  }
+}
+
+const service = await container.get(RequestService)
+await service.process() // "Processing in request: req-123"
+
+// Clean up when done
+await container.endRequest('req-123')
+```
+
 ## Best Practices
 
 ### 1. Use Container for Application Setup
@@ -215,6 +250,26 @@ const userContainer = new Container(userRegistry)
 const paymentContainer = new Container(paymentRegistry)
 ```
 
+### 5. Manage Request Contexts Properly
+
+```typescript
+// Always clean up request contexts
+async function handleRequest(req, res) {
+  const requestId = generateRequestId()
+  const context = container.beginRequest(requestId, {
+    ip: req.ip,
+    userAgent: req.get('User-Agent'),
+  })
+
+  try {
+    container.setCurrentRequestContext(requestId)
+    await processRequest(req, res)
+  } finally {
+    await container.endRequest(requestId)
+  }
+}
+```
+
 ## API Reference
 
 ### Constructor
@@ -252,6 +307,26 @@ Waits for all pending operations to complete.
 
 Returns the underlying ServiceLocator instance.
 
+#### `beginRequest(requestId: string, metadata?: Record<string, any>, priority?: number): RequestContextHolder`
+
+Begins a new request context with the given parameters.
+
+- `requestId`: Unique identifier for this request
+- `metadata`: Optional metadata for the request
+- `priority`: Priority for resolution (higher = more priority, defaults to 100)
+
+#### `endRequest(requestId: string): Promise<void>`
+
+Ends a request context and cleans up all associated instances.
+
+#### `getCurrentRequestContext(): RequestContextHolder | null`
+
+Gets the current request context.
+
+#### `setCurrentRequestContext(requestId: string): void`
+
+Sets the current request context.
+
 ## Error Handling
 
 The Container can throw various errors:

package/docs/getting-started.md

@@ -66,13 +66,14 @@ class EmailService {
 // 2. Create a user service that depends on the email service
 @Injectable()
 class UserService {
-  private readonly emailService = inject(EmailService)
+  private readonly emailService = asyncInject(EmailService)
 
   async createUser(name: string, email: string) {
     console.log(`Creating user: ${name}`)
 
-    // Send welcome email
-    await this.emailService.sendEmail(
+    // Get the email service and send welcome email
+    const emailService = await this.emailService
+    await emailService.sendEmail(
       email,
       'Welcome!',
       `Hello ${name}, welcome to our platform!`,

package/docs/injectable.md

@@ -20,7 +20,7 @@ class UserService {
 ### Service with Dependencies
 
 ```typescript
-import { inject, Injectable } from '@navios/di'
+import { asyncInject, Injectable } from '@navios/di'
 
 @Injectable()
 class DatabaseService {
@@ -31,10 +31,11 @@ class DatabaseService {
 
 @Injectable()
 class UserService {
-  private readonly db = inject(DatabaseService)
+  private readonly db = asyncInject(DatabaseService)
 
   async getUsers() {
-    const connection = await this.db.connect()
+    const dbService = await this.db
+    const connection = await dbService.connect()
     return `Users from ${connection}`
   }
 }

package/docs/migration.md

@@ -0,0 +1,177 @@
+# Migration Guide
+
+This guide helps you migrate between different versions of Navios DI.
+
+## Migrating to v0.3.x
+
+### New Features
+
+#### Request Context Management
+
+The biggest addition in v0.3.x is request context management. This feature allows you to manage request-scoped services with automatic cleanup.
+
+**New APIs:**
+
+- `Container.beginRequest(requestId, metadata?, priority?)`
+- `Container.endRequest(requestId)`
+- `Container.getCurrentRequestContext()`
+- `Container.setCurrentRequestContext(requestId)`
+- `RequestContextHolder` interface
+
+**Example:**
+
+```typescript
+// New request context API
+const container = new Container()
+const context = container.beginRequest('req-123', { userId: 456 })
+container.setCurrentRequestContext('req-123')
+
+// Add request-scoped data
+const REQUEST_ID_TOKEN = InjectionToken.create<string>('REQUEST_ID')
+context.addInstance(REQUEST_ID_TOKEN, 'req-123')
+
+// Use in services
+@Injectable()
+class RequestService {
+  private readonly requestId = asyncInject(REQUEST_ID_TOKEN)
+
+  async process() {
+    const id = await this.requestId
+    console.log(`Processing request: ${id}`)
+  }
+}
+
+// Clean up when done
+await container.endRequest('req-123')
+```
+
+### Recommended Changes
+
+#### Prefer `asyncInject` over `inject`
+
+While `inject` still works, `asyncInject` is now the recommended approach for most use cases as it's safer and handles async dependencies better.
+
+**Before:**
+
+```typescript
+@Injectable()
+class UserService {
+  private readonly db = inject(DatabaseService)
+}
+```
+
+**After:**
+
+```typescript
+@Injectable()
+class UserService {
+  private readonly db = asyncInject(DatabaseService)
+
+  async getUsers() {
+    const database = await this.db
+    return database.query('SELECT * FROM users')
+  }
+}
+```
+
+### Breaking Changes
+
+None in v0.3.x - this is a feature release with full backward compatibility.
+
+## Migrating from v0.2.x to v0.3.x
+
+### New Dependencies
+
+No new peer dependencies were added.
+
+### Updated Type Definitions
+
+Some internal type definitions were improved for better TypeScript support, but no breaking changes to public APIs.
+
+## Future Migration Notes
+
+### Planned for v0.4.x
+
+- Enhanced request context lifecycle hooks
+- Performance optimizations for high-throughput scenarios
+- Additional factory pattern improvements
+
+### Best Practices for Forward Compatibility
+
+1. **Use `asyncInject` for new code** - This is the future-preferred injection method
+2. **Implement lifecycle hooks** - `OnServiceInit` and `OnServiceDestroy` for proper resource management
+3. **Use request contexts** - For web applications and request-scoped data
+4. **Prefer injection tokens** - For configuration and interface-based dependencies
+
+## Common Migration Issues
+
+### Issue: Services not found in request context
+
+**Problem:** Services can't be resolved when using request contexts.
+
+**Solution:** Make sure you've set the current request context:
+
+```typescript
+container.setCurrentRequestContext('your-request-id')
+```
+
+### Issue: Async dependencies not ready
+
+**Problem:** Using `inject` with dependencies that aren't immediately available.
+
+**Solution:** Switch to `asyncInject`:
+
+```typescript
+// Instead of this:
+private readonly service = inject(AsyncService)
+
+// Use this:
+private readonly service = asyncInject(AsyncService)
+```
+
+### Issue: Memory leaks with request contexts
+
+**Problem:** Request contexts not being cleaned up.
+
+**Solution:** Always call `endRequest()`:
+
+```typescript
+try {
+  const context = container.beginRequest('req-123')
+  // ... process request
+} finally {
+  await container.endRequest('req-123')
+}
+```
+
+## Getting Help
+
+If you encounter issues during migration:
+
+1. Check the [API Reference](./api-reference.md) for detailed method signatures
+2. Review the [examples](./examples/) for common patterns
+3. Check the GitHub issues for known migration problems
+4. Create a new issue if you find a bug or need help
+
+## Changelog Summary
+
+### v0.3.1
+
+- Added request context management
+- Improved TypeScript type definitions
+- Enhanced container API with request context methods
+- 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
+- Injectable and Factory decorators
+- Injection tokens with Zod validation
+- Service lifecycle hooks

package/docs/request-contexts.md

@@ -0,0 +1,364 @@
+# Request Contexts
+
+Request contexts in Navios DI provide a powerful way to manage request-scoped services with automatic cleanup and priority-based resolution. This is particularly useful in web applications where you need to maintain request-specific data and ensure proper cleanup after each request.
+
+## Overview
+
+A request context is a scoped container that can hold pre-prepared instances and metadata for a specific request. When a request context is active, services can access request-specific data through dependency injection.
+
+### Key Features
+
+- **Request-scoped instances**: Services that exist only for the duration of a request
+- **Automatic cleanup**: All request-scoped instances are automatically cleaned up when the request ends
+- **Priority-based resolution**: Multiple contexts can exist with different priorities
+- **Metadata support**: Attach arbitrary metadata to request contexts
+- **Thread-safe**: Safe to use in concurrent environments
+
+## Basic Usage
+
+### Creating and Managing Request Contexts
+
+```typescript
+import { Container, Injectable, InjectionToken } from '@navios/di'
+
+const container = new Container()
+
+// Begin a new request context
+const context = container.beginRequest('req-123', { userId: 456 }, 100)
+
+// Set it as the current context
+container.setCurrentRequestContext('req-123')
+
+// End the request context when done
+await container.endRequest('req-123')
+```
+
+### Using Request-Scoped Data
+
+```typescript
+const REQUEST_ID_TOKEN = InjectionToken.create<string>('REQUEST_ID')
+const USER_ID_TOKEN = InjectionToken.create<number>('USER_ID')
+
+@Injectable()
+class RequestLogger {
+  private readonly requestId = asyncInject(REQUEST_ID_TOKEN)
+  private readonly userId = asyncInject(USER_ID_TOKEN)
+
+  async log(message: string) {
+    const reqId = await this.requestId
+    const uid = await this.userId
+    console.log(`[${reqId}] User ${uid}: ${message}`)
+  }
+}
+
+// Setup request context
+const context = container.beginRequest('req-123')
+context.addInstance(REQUEST_ID_TOKEN, 'req-123')
+context.addInstance(USER_ID_TOKEN, 456)
+
+container.setCurrentRequestContext('req-123')
+
+// Use the service
+const logger = await container.get(RequestLogger)
+await logger.log('Processing request') // "[req-123] User 456: Processing request"
+```
+
+## Advanced Features
+
+### Priority-Based Resolution
+
+When multiple request contexts exist, the one with the highest priority is used:
+
+```typescript
+// High priority context (e.g., admin request)
+const adminContext = container.beginRequest('admin-req', {}, 200)
+
+// Normal priority context
+const userContext = container.beginRequest('user-req', {}, 100)
+
+// Admin context will be used due to higher priority
+container.setCurrentRequestContext('admin-req')
+```
+
+### Request Metadata
+
+Request contexts can carry metadata that services can access:
+
+```typescript
+@Injectable()
+class AuditService {
+  private readonly context = asyncInject(Container)
+
+  async logAction(action: string) {
+    const container = await this.context
+    const requestContext = container.getCurrentRequestContext()
+
+    if (requestContext) {
+      const userId = requestContext.getMetadata('userId')
+      const traceId = requestContext.getMetadata('traceId')
+
+      console.log(`User ${userId} performed ${action} (trace: ${traceId})`)
+    }
+  }
+}
+
+// Setup with metadata
+const context = container.beginRequest('req-123', {
+  userId: 456,
+  traceId: 'abc-123',
+  userAgent: 'Mozilla/5.0...',
+})
+```
+
+### Pre-prepared Instances
+
+You can add pre-prepared instances to a request context:
+
+```typescript
+@Injectable()
+class DatabaseConnection {
+  constructor(private connectionString: string) {}
+
+  async query(sql: string) {
+    return `Executing: ${sql} on ${this.connectionString}`
+  }
+}
+
+// Create a request-specific database connection
+const dbConnection = new DatabaseConnection('user-specific-db')
+const context = container.beginRequest('req-123')
+context.addInstance('DatabaseConnection', dbConnection)
+```
+
+## Web Framework Integration
+
+### Express.js Example
+
+```typescript
+import { Container, Injectable, InjectionToken } from '@navios/di'
+
+import express from 'express'
+
+const REQUEST_TOKEN = InjectionToken.create<express.Request>('REQUEST')
+const RESPONSE_TOKEN = InjectionToken.create<express.Response>('RESPONSE')
+
+@Injectable()
+class RequestHandler {
+  private readonly req = asyncInject(REQUEST_TOKEN)
+  private readonly res = asyncInject(RESPONSE_TOKEN)
+
+  async handleRequest() {
+    const request = await this.req
+    const response = await this.res
+
+    response.json({
+      message: 'Hello!',
+      path: request.path,
+      method: request.method,
+    })
+  }
+}
+
+const app = express()
+const container = new Container()
+
+app.use('*', async (req, res, next) => {
+  const requestId = `req-${Date.now()}-${Math.random()}`
+
+  // Create request context
+  const context = container.beginRequest(requestId, {
+    path: req.path,
+    method: req.method,
+    userAgent: req.get('User-Agent'),
+  })
+
+  // Add request-specific instances
+  context.addInstance(REQUEST_TOKEN, req)
+  context.addInstance(RESPONSE_TOKEN, res)
+
+  // Set as current context
+  container.setCurrentRequestContext(requestId)
+
+  try {
+    const handler = await container.get(RequestHandler)
+    await handler.handleRequest()
+  } finally {
+    // Clean up request context
+    await container.endRequest(requestId)
+  }
+})
+```
+
+### Fastify Example
+
+```typescript
+import { Container, Injectable, InjectionToken } from '@navios/di'
+
+import fastify from 'fastify'
+
+const REQUEST_TOKEN = InjectionToken.create<any>('FASTIFY_REQUEST')
+
+const app = fastify()
+const container = new Container()
+
+app.addHook('preHandler', async (request, reply) => {
+  const requestId = `req-${request.id}`
+
+  const context = container.beginRequest(requestId, {
+    ip: request.ip,
+    userAgent: request.headers['user-agent'],
+  })
+
+  context.addInstance(REQUEST_TOKEN, request)
+  container.setCurrentRequestContext(requestId)
+
+  // Store requestId for cleanup
+  request.requestId = requestId
+})
+
+app.addHook('onResponse', async (request, reply) => {
+  if (request.requestId) {
+    await container.endRequest(request.requestId)
+  }
+})
+```
+
+## Best Practices
+
+### 1. Always Clean Up
+
+Always ensure request contexts are properly cleaned up:
+
+```typescript
+const requestId = generateRequestId()
+const context = container.beginRequest(requestId)
+
+try {
+  // Process request
+  await processRequest()
+} finally {
+  // Always clean up, even on errors
+  await container.endRequest(requestId)
+}
+```
+
+### 2. Use Meaningful Request IDs
+
+Use descriptive request IDs that help with debugging:
+
+```typescript
+const requestId = `${req.method}-${req.path}-${Date.now()}-${Math.random().toString(36).slice(2)}`
+```
+
+### 3. Set Appropriate Priorities
+
+Use priorities to ensure correct resolution order:
+
+```typescript
+// System/admin requests - highest priority
+const adminContext = container.beginRequest('admin-req', {}, 1000)
+
+// Authenticated user requests
+const userContext = container.beginRequest('user-req', {}, 500)
+
+// Anonymous requests - lowest priority
+const anonContext = container.beginRequest('anon-req', {}, 100)
+```
+
+### 4. Leverage Metadata
+
+Use metadata for cross-cutting concerns:
+
+```typescript
+const context = container.beginRequest('req-123', {
+  traceId: generateTraceId(),
+  correlationId: req.headers['x-correlation-id'],
+  userId: req.user?.id,
+  tenantId: req.tenant?.id,
+  startTime: Date.now(),
+})
+```
+
+### 5. Combine with Lifecycle Hooks
+
+Use lifecycle hooks for request-scoped resource management:
+
+```typescript
+@Injectable()
+class DatabaseTransaction implements OnServiceInit, OnServiceDestroy {
+  private transaction: any = null
+
+  async onServiceInit() {
+    this.transaction = await db.beginTransaction()
+  }
+
+  async onServiceDestroy() {
+    if (this.transaction) {
+      await this.transaction.rollback()
+    }
+  }
+
+  async commit() {
+    await this.transaction.commit()
+  }
+}
+```
+
+## Error Handling
+
+Request contexts handle errors gracefully:
+
+```typescript
+try {
+  const context = container.beginRequest('req-123')
+  container.setCurrentRequestContext('req-123')
+
+  // If this throws, cleanup will still happen
+  await processRequest()
+} catch (error) {
+  console.error('Request failed:', error)
+  throw error
+} finally {
+  // Context cleanup happens automatically
+  await container.endRequest('req-123')
+}
+```
+
+## API Reference
+
+### Container Methods
+
+- `beginRequest(requestId: string, metadata?: Record<string, any>, priority?: number): RequestContextHolder`
+- `endRequest(requestId: string): Promise<void>`
+- `getCurrentRequestContext(): RequestContextHolder | null`
+- `setCurrentRequestContext(requestId: string): void`
+
+### RequestContextHolder Interface
+
+- `requestId: string` - Unique identifier for this request
+- `priority: number` - Priority for resolution
+- `metadata: Map<string, any>` - Request-specific metadata
+- `createdAt: number` - Timestamp when context was created
+- `addInstance(token: InjectionToken<any>, instance: any): void`
+- `getMetadata(key: string): any | undefined`
+- `setMetadata(key: string, value: any): void`
+- `clear(): void` - Clear all instances and metadata
+
+## Performance Considerations
+
+- Request contexts are lightweight and designed for high-throughput scenarios
+- Cleanup is asynchronous and won't block request processing
+- Use appropriate priorities to avoid unnecessary context switching
+- Consider pooling request contexts for very high-frequency scenarios
+
+## Troubleshooting
+
+### Common Issues
+
+**Context not found**: Make sure you've called `setCurrentRequestContext()` before accessing request-scoped services.
+
+**Wrong priority resolution**: Check that your priority values are set correctly (higher = more priority).
+
+**Memory leaks**: Always call `endRequest()` to clean up contexts, preferably in a `finally` block.
+
+**Service not found in context**: Ensure you've added the instance to the context with `addInstance()`.