@navios/di 0.2.1 → 0.3.1

package/docs/container.md

@@ -0,0 +1,274 @@
+# Container
+
+The `Container` class is the main entry point for dependency injection in Navios DI. It provides a simplified, high-level API for managing services and their dependencies.
+
+## Overview
+
+The Container wraps a `ServiceLocator` instance and provides convenient methods for:
+
+- Getting service instances
+- Invalidating services and their dependencies
+- Managing service lifecycle
+- Accessing the underlying service locator for advanced usage
+
+## Basic Usage
+
+### Creating a Container
+
+```typescript
+import { Container } from '@navios/di'
+
+// Create with default registry
+const container = new Container()
+
+// Create with custom registry
+const customRegistry = new Registry()
+const container = new Container(customRegistry)
+
+// Create with custom registry and logger
+const mockLogger = {
+  log: console.log,
+  error: console.error,
+  warn: console.warn,
+  info: console.info,
+  debug: console.debug,
+}
+const container = new Container(customRegistry, mockLogger)
+```
+
+### Getting Service Instances
+
+The `get` method is the primary way to retrieve service instances:
+
+```typescript
+import { Container, Injectable } from '@navios/di'
+
+@Injectable()
+class UserService {
+  getUsers() {
+    return ['Alice', 'Bob', 'Charlie']
+  }
+}
+
+const container = new Container()
+const userService = await container.get(UserService)
+console.log(userService.getUsers()) // ['Alice', 'Bob', 'Charlie']
+```
+
+### Type-Safe Service Resolution
+
+The Container provides full type safety for service resolution:
+
+```typescript
+// Simple class injection
+const service: UserService = await container.get(UserService)
+
+// Injection token with schema
+const config = await container.get(CONFIG_TOKEN, {
+  apiUrl: 'https://api.example.com',
+  timeout: 5000,
+})
+
+// Bound injection token
+const boundService = await container.get(BoundConfigToken)
+
+// Factory injection token
+const factoryService = await container.get(FactoryConfigToken)
+```
+
+## Advanced Usage
+
+### Service Invalidation
+
+The `invalidate` method allows you to remove a service and its dependencies from the container:
+
+```typescript
+@Injectable()
+class CacheService {
+  private cache = new Map()
+
+  set(key: string, value: any) {
+    this.cache.set(key, value)
+  }
+
+  get(key: string) {
+    return this.cache.get(key)
+  }
+}
+
+const container = new Container()
+const cacheService = await container.get(CacheService)
+
+// Use the service
+cacheService.set('user:123', { name: 'Alice' })
+
+// Invalidate the service
+await container.invalidate(cacheService)
+
+// Next access will create a new instance
+const newCacheService = await container.get(CacheService)
+console.log(newCacheService.get('user:123')) // undefined (new instance)
+```
+
+### Waiting for Operations
+
+The `ready` method waits for all pending operations to complete:
+
+```typescript
+const container = new Container()
+
+// Start multiple async operations
+const promises = [
+  container.get(UserService),
+  container.get(EmailService),
+  container.get(DatabaseService),
+]
+
+// Wait for all to complete
+await container.ready()
+
+// All services are now ready
+const [userService, emailService, dbService] = await Promise.all(promises)
+```
+
+### Accessing the Service Locator
+
+For advanced usage, you can access the underlying `ServiceLocator`:
+
+```typescript
+const container = new Container()
+const serviceLocator = container.getServiceLocator()
+
+// Use advanced ServiceLocator methods
+const instance = await serviceLocator.getOrThrowInstance(UserService)
+```
+
+## Best Practices
+
+### 1. Use Container for Application Setup
+
+```typescript
+// app.ts
+import { Container } from '@navios/di'
+
+async function bootstrap() {
+  const container = new Container()
+
+  // Initialize core services
+  await container.get(DatabaseService)
+  await container.get(CacheService)
+  await container.get(EmailService)
+
+  // Start the application
+  const app = await container.get(ApplicationService)
+  await app.start()
+
+  return container
+}
+
+const container = await bootstrap()
+```
+
+### 2. Invalidate Services When Needed
+
+```typescript
+// When configuration changes
+await container.invalidate(configService)
+
+// When cache needs clearing
+await container.invalidate(cacheService)
+
+// When user logs out
+await container.invalidate(userSessionService)
+```
+
+### 3. Handle Errors Gracefully
+
+```typescript
+try {
+  const service = await container.get(NonExistentService)
+} catch (error) {
+  if (error instanceof InstanceNotFoundError) {
+    console.error('Service not registered:', error.message)
+  } else {
+    console.error('Unexpected error:', error)
+  }
+}
+```
+
+### 4. Use Custom Registries for Modularity
+
+```typescript
+// Create separate registries for different modules
+const userRegistry = new Registry()
+const paymentRegistry = new Registry()
+
+// Register services in their respective registries
+@Injectable({ registry: userRegistry })
+class UserService {}
+
+@Injectable({ registry: paymentRegistry })
+class PaymentService {}
+
+// Create containers with specific registries
+const userContainer = new Container(userRegistry)
+const paymentContainer = new Container(paymentRegistry)
+```
+
+## API Reference
+
+### Constructor
+
+```typescript
+constructor(registry?: Registry, logger?: Console | null)
+```
+
+- `registry`: Optional registry instance (defaults to global registry)
+- `logger`: Optional logger instance for debugging
+
+### Methods
+
+#### `get<T>(token: T): Promise<InstanceType<T>>`
+
+Gets a service instance from the container.
+
+**Overloads:**
+
+- `get<T extends ClassType>(token: T): Promise<InstanceType<T>>`
+- `get<T, S extends InjectionTokenSchemaType>(token: InjectionToken<T, S>, args: z.input<S>): Promise<T>`
+- `get<T>(token: InjectionToken<T, undefined>): Promise<T>`
+- `get<T>(token: BoundInjectionToken<T, any>): Promise<T>`
+- `get<T>(token: FactoryInjectionToken<T, any>): Promise<T>`
+
+#### `invalidate(service: unknown): Promise<void>`
+
+Invalidates a service and its dependencies.
+
+#### `ready(): Promise<void>`
+
+Waits for all pending operations to complete.
+
+#### `getServiceLocator(): ServiceLocator`
+
+Returns the underlying ServiceLocator instance.
+
+## Error Handling
+
+The Container can throw various errors:
+
+- `InstanceNotFoundError`: When a service is not registered
+- `InstanceExpiredError`: When a service instance has expired
+- `InstanceDestroyingError`: When trying to access a service being destroyed
+- `UnknownError`: For unexpected errors
+
+```typescript
+import { InstanceNotFoundError } from '@navios/di'
+
+try {
+  const service = await container.get(UnregisteredService)
+} catch (error) {
+  if (error instanceof InstanceNotFoundError) {
+    console.error('Service not found:', error.message)
+  }
+}
+```

package/docs/examples/basic-usage.mts

@@ -0,0 +1,97 @@
+/**
+ * Basic Usage Example
+ *
+ * This example demonstrates the fundamental concepts of Navios DI:
+ * - Service registration with @Injectable
+ * - Dependency injection with asyncInject and inject
+ * - Container usage
+ */
+
+import { asyncInject, Container, inject, Injectable } from '@navios/di'
+
+// 1. Create a simple service
+@Injectable()
+class LoggerService {
+  log(message: string) {
+    console.log(`[LOG] ${new Date().toISOString()} - ${message}`)
+  }
+}
+
+// 2. Create a service that depends on LoggerService
+@Injectable()
+class UserService {
+  private readonly logger = inject(LoggerService)
+
+  createUser(name: string, email: string) {
+    this.logger.log(`Creating user: ${name}`)
+    return { id: Math.random().toString(36), name, email }
+  }
+}
+
+// 3. Create a service that uses async injection
+@Injectable()
+class EmailService {
+  private readonly logger = asyncInject(LoggerService)
+
+  async sendEmail(to: string, subject: string, body: string) {
+    const logger = await this.logger
+    logger.log(`Sending email to ${to}`)
+
+    // Simulate email sending
+    await new Promise((resolve) => setTimeout(resolve, 100))
+
+    return { success: true, messageId: Math.random().toString(36) }
+  }
+}
+
+// 4. Create a service that orchestrates other services
+@Injectable()
+class UserRegistrationService {
+  private readonly userService = inject(UserService)
+  private readonly emailService = inject(EmailService)
+  private readonly logger = inject(LoggerService)
+
+  async registerUser(name: string, email: string) {
+    this.logger.log(`Starting user registration for ${name}`)
+
+    // Create user
+    const user = this.userService.createUser(name, email)
+
+    // Send welcome email
+    await this.emailService.sendEmail(
+      email,
+      'Welcome!',
+      `Hello ${name}, welcome to our platform!`,
+    )
+
+    this.logger.log(`User registration completed for ${name}`)
+
+    return user
+  }
+}
+
+// 5. Usage example
+async function main() {
+  console.log('=== Basic Usage Example ===\n')
+
+  // Create container
+  const container = new Container()
+
+  // Get the registration service (all dependencies will be automatically injected)
+  const registrationService = await container.get(UserRegistrationService)
+
+  // Register a user
+  const user = await registrationService.registerUser(
+    'Alice',
+    'alice@example.com',
+  )
+
+  console.log('\nRegistered user:', user)
+}
+
+// Run the example
+if (require.main === module) {
+  main().catch(console.error)
+}
+
+export { LoggerService, UserService, EmailService, UserRegistrationService }

package/docs/examples/factory-pattern.mts

@@ -0,0 +1,318 @@
+import type { Factorable, FactorableWithArgs, FactoryContext } from '@navios/di'
+
+import {
+  Container,
+  Factory,
+  inject,
+  Injectable,
+  InjectableScope,
+  InjectionToken,
+} from '@navios/di'
+
+import { z } from 'zod'
+
+const container = new Container()
+
+/**
+ * Factory Pattern Example
+ *
+ * This example demonstrates:
+ * - Using @Factory decorator
+ * - Factory with dependencies
+ * - Factory with configuration
+ * - Factory with different scopes
+ */
+
+// 1. Simple factory without dependencies
+@Factory()
+class RandomIdFactory {
+  create() {
+    return {
+      id: Math.random().toString(36).substr(2, 9),
+      createdAt: new Date(),
+    }
+  }
+}
+
+// 2. Factory with dependencies
+@Injectable()
+class LoggerService {
+  log(message: string) {
+    console.log(`[LOG] ${message}`)
+  }
+}
+
+@Factory()
+class DatabaseConnectionFactory {
+  private readonly logger = inject(LoggerService)
+
+  create() {
+    this.logger.log('Creating database connection...')
+
+    return {
+      host: 'localhost',
+      port: 5432,
+      connected: false,
+      connect: async () => {
+        this.logger.log('Connecting to database...')
+        await new Promise((resolve) => setTimeout(resolve, 100))
+        this.logger.log('Database connected successfully')
+        return { connected: true }
+      },
+      disconnect: async () => {
+        this.logger.log('Disconnecting from database...')
+        return { connected: false }
+      },
+    }
+  }
+}
+
+// 3. Factory with configuration schema
+const emailConfigSchema = z.object({
+  provider: z.enum(['smtp', 'sendgrid', 'ses']),
+  apiKey: z.string(),
+  fromEmail: z.string().email(),
+})
+
+type EmailConfig = z.infer<typeof emailConfigSchema>
+
+interface EmailService {
+  sendEmail(
+    to: string,
+    subject: string,
+    body: string,
+  ): Promise<{ success: boolean; provider: string }>
+}
+
+const EMAIL_CONFIG_TOKEN = InjectionToken.create<
+  EmailService,
+  typeof emailConfigSchema
+>('EMAIL_CONFIG', emailConfigSchema)
+
+@Factory({ token: EMAIL_CONFIG_TOKEN })
+class EmailServiceFactory
+  implements FactorableWithArgs<EmailService, typeof emailConfigSchema>
+{
+  create(ctx: FactoryContext, config: z.infer<typeof emailConfigSchema>) {
+    switch (config.provider) {
+      case 'smtp':
+        return new SmtpEmailService(config)
+      case 'sendgrid':
+        return new SendGridEmailService(config)
+      case 'ses':
+        return new SesEmailService(config)
+      default:
+        throw new Error(`Unsupported email provider: ${config.provider}`)
+    }
+  }
+}
+
+// Email service implementations
+class SmtpEmailService implements EmailService {
+  constructor(private config: EmailConfig) {}
+
+  async sendEmail(to: string, subject: string, body: string) {
+    console.log(`SMTP email sent to ${to}: ${subject}`)
+    return { success: true, provider: 'smtp' }
+  }
+}
+
+class SendGridEmailService {
+  constructor(private config: EmailConfig) {}
+
+  async sendEmail(to: string, subject: string, body: string) {
+    console.log(`SendGrid email sent to ${to}: ${subject}`)
+    return { success: true, provider: 'sendgrid' }
+  }
+}
+
+class SesEmailService {
+  constructor(private config: EmailConfig) {}
+
+  async sendEmail(to: string, subject: string, body: string) {
+    console.log(`SES email sent to ${to}: ${subject}`)
+    return { success: true, provider: 'ses' }
+  }
+}
+
+// 4. Factory with transient scope
+
+interface UserSession {
+  sessionId: string
+  userId: string | null
+  loginTime: Date
+  isActive: boolean
+  login(userId: string): void
+  logout(): void
+  getSessionInfo(): Pick<
+    UserSession,
+    'sessionId' | 'userId' | 'loginTime' | 'isActive'
+  >
+}
+
+@Factory({ scope: InjectableScope.Transient })
+class UserSessionFactory implements Factorable<UserSession> {
+  create() {
+    return {
+      sessionId: Math.random().toString(36),
+      userId: null,
+      loginTime: new Date(),
+      isActive: false,
+
+      login(userId: string) {
+        this.userId = userId
+        this.isActive = true
+        this.loginTime = new Date()
+      },
+
+      logout() {
+        this.userId = null
+        this.isActive = false
+      },
+
+      getSessionInfo() {
+        return {
+          sessionId: this.sessionId,
+          userId: this.userId,
+          loginTime: this.loginTime,
+          isActive: this.isActive,
+        }
+      },
+    } satisfies UserSession
+  }
+}
+
+// 5. Factory with complex object creation
+@Injectable()
+class ConfigService {
+  getDatabaseConfig() {
+    return {
+      host: 'localhost',
+      port: 5432,
+      database: 'myapp',
+    }
+  }
+
+  getCacheConfig() {
+    return {
+      host: 'localhost',
+      port: 6379,
+      ttl: 3600,
+    }
+  }
+}
+
+@Factory()
+class ApplicationContextFactory {
+  private readonly config = inject(ConfigService)
+
+  create() {
+    const dbConfig = this.config.getDatabaseConfig()
+    const cacheConfig = this.config.getCacheConfig()
+
+    return {
+      database: {
+        ...dbConfig,
+        connectionString: `postgresql://${dbConfig.host}:${dbConfig.port}/${dbConfig.database}`,
+      },
+      cache: {
+        ...cacheConfig,
+        connectionString: `redis://${cacheConfig.host}:${cacheConfig.port}`,
+      },
+      environment: process.env.NODE_ENV || 'development',
+      version: '1.0.0',
+      initializedAt: new Date(),
+    }
+  }
+}
+
+// 6. Usage examples
+async function demonstrateSimpleFactory() {
+  console.log('=== Simple Factory Example ===\n')
+
+  const idFactory = await container.get(RandomIdFactory)
+  console.log('Generated ID:', idFactory)
+}
+
+async function demonstrateFactoryWithDependencies() {
+  console.log('\n=== Factory with Dependencies Example ===\n')
+
+  const dbFactory = await container.get(DatabaseConnectionFactory)
+  console.log('Database connection:', dbFactory)
+
+  const connection = await dbFactory.connect()
+  console.log('Connection result:', connection)
+}
+
+async function demonstrateFactoryWithConfiguration() {
+  console.log('\n=== Factory with Configuration Example ===\n')
+
+  // Create different email services based on configuration
+  const smtpEmail = await container.get(EMAIL_CONFIG_TOKEN, {
+    provider: 'smtp',
+    apiKey: 'smtp_key',
+    fromEmail: 'noreply@example.com',
+  })
+
+  const sendgridEmail = await container.get(EMAIL_CONFIG_TOKEN, {
+    provider: 'sendgrid',
+    apiKey: 'sg_key',
+    fromEmail: 'noreply@example.com',
+  })
+
+  await smtpEmail.sendEmail('user@example.com', 'Test', 'Hello from SMTP')
+  await sendgridEmail.sendEmail(
+    'user@example.com',
+    'Test',
+    'Hello from SendGrid',
+  )
+}
+
+async function demonstrateTransientFactory() {
+  console.log('\n=== Transient Factory Example ===\n')
+
+  // Create multiple sessions
+  const session1 = await container.get(UserSessionFactory)
+  const session2 = await container.get(UserSessionFactory)
+
+  session1.login('user1')
+  session2.login('user2')
+
+  console.log('Session 1:', session1.getSessionInfo())
+  console.log('Session 2:', session2.getSessionInfo())
+
+  // Verify they are different instances
+  console.log('Different sessions:', session1.sessionId !== session2.sessionId)
+}
+
+async function demonstrateComplexFactory() {
+  console.log('\n=== Complex Factory Example ===\n')
+
+  const appContext = await container.get(ApplicationContextFactory)
+  console.log('Application context:', JSON.stringify(appContext, null, 2))
+}
+
+// Main function
+async function main() {
+  await demonstrateSimpleFactory()
+  await demonstrateFactoryWithDependencies()
+  await demonstrateFactoryWithConfiguration()
+  await demonstrateTransientFactory()
+  await demonstrateComplexFactory()
+}
+
+// Run the example
+if (require.main === module) {
+  main().catch(console.error)
+}
+
+export {
+  RandomIdFactory,
+  DatabaseConnectionFactory,
+  EmailServiceFactory,
+  UserSessionFactory,
+  ApplicationContextFactory,
+  SmtpEmailService,
+  SendGridEmailService,
+  SesEmailService,
+}