@navios/di 0.2.1 → 0.3.1

package/docs/examples/injection-tokens.mts

@@ -0,0 +1,225 @@
+/**
+ * Injection Tokens Example
+ *
+ * This example demonstrates:
+ * - Creating injection tokens with schemas
+ * - Using bound injection tokens
+ * - Using factory injection tokens
+ * - Token-based dependency resolution
+ */
+
+import { Container, Injectable, InjectionToken } from '@navios/di'
+
+import { z } from 'zod'
+
+const container = new Container()
+
+// 1. Define schemas for configuration
+const databaseConfigSchema = z.object({
+  host: z.string(),
+  port: z.number(),
+  database: z.string(),
+  username: z.string(),
+  password: z.string(),
+})
+
+const emailConfigSchema = z.object({
+  provider: z.enum(['smtp', 'sendgrid', 'ses']),
+  apiKey: z.string(),
+  fromEmail: z.string().email(),
+})
+
+// 2. Create injection tokens
+const DB_CONFIG_TOKEN = InjectionToken.create<
+  DatabaseConfigService,
+  typeof databaseConfigSchema
+>('DB_CONFIG', databaseConfigSchema)
+
+const EMAIL_CONFIG_TOKEN = InjectionToken.create<
+  EmailConfigService,
+  typeof emailConfigSchema
+>('EMAIL_CONFIG', emailConfigSchema)
+
+// 3. Create services that use injection tokens
+@Injectable({ token: DB_CONFIG_TOKEN })
+class DatabaseConfigService {
+  constructor(private config: z.infer<typeof databaseConfigSchema>) {}
+
+  getConnectionString() {
+    return `postgresql://${this.config.username}:${this.config.password}@${this.config.host}:${this.config.port}/${this.config.database}`
+  }
+
+  getHost() {
+    return this.config.host
+  }
+
+  getPort() {
+    return this.config.port
+  }
+}
+
+@Injectable({ token: EMAIL_CONFIG_TOKEN })
+class EmailConfigService {
+  constructor(private config: z.infer<typeof emailConfigSchema>) {}
+
+  getProvider() {
+    return this.config.provider
+  }
+
+  getApiKey() {
+    return this.config.apiKey
+  }
+
+  getFromEmail() {
+    return this.config.fromEmail
+  }
+}
+
+// 4. Create bound tokens for different environments
+const PRODUCTION_DB_CONFIG = InjectionToken.bound(DB_CONFIG_TOKEN, {
+  host: 'prod-db.example.com',
+  port: 5432,
+  database: 'production',
+  username: 'prod_user',
+  password: 'prod_password',
+})
+
+const DEVELOPMENT_DB_CONFIG = InjectionToken.bound(DB_CONFIG_TOKEN, {
+  host: 'localhost',
+  port: 5432,
+  database: 'development',
+  username: 'dev_user',
+  password: 'dev_password',
+})
+
+const PRODUCTION_EMAIL_CONFIG = InjectionToken.bound(EMAIL_CONFIG_TOKEN, {
+  provider: 'sendgrid',
+  apiKey: 'sg.prod_key',
+  fromEmail: 'noreply@example.com',
+})
+
+const DEVELOPMENT_EMAIL_CONFIG = InjectionToken.bound(EMAIL_CONFIG_TOKEN, {
+  provider: 'smtp',
+  apiKey: 'smtp_dev_key',
+  fromEmail: 'dev@example.com',
+})
+
+// 5. Create factory tokens for dynamic configuration
+const DYNAMIC_DB_CONFIG = InjectionToken.factory(DB_CONFIG_TOKEN, async () => {
+  const env = process.env.NODE_ENV || 'development'
+
+  if (env === 'production') {
+    return {
+      host: 'prod-db.example.com',
+      port: 5432,
+      database: 'production',
+      username: 'prod_user',
+      password: 'prod_password',
+    }
+  } else {
+    return {
+      host: 'localhost',
+      port: 5432,
+      database: 'development',
+      username: 'dev_user',
+      password: 'dev_password',
+    }
+  }
+})
+
+const DYNAMIC_EMAIL_CONFIG = InjectionToken.factory(
+  EMAIL_CONFIG_TOKEN,
+  async () => {
+    const env = process.env.NODE_ENV || 'development'
+
+    if (env === 'production') {
+      return {
+        provider: 'sendgrid' as const,
+        apiKey: 'sg.prod_key',
+        fromEmail: 'noreply@example.com',
+      }
+    } else {
+      return {
+        provider: 'smtp' as const,
+        apiKey: 'smtp_dev_key',
+        fromEmail: 'dev@example.com',
+      }
+    }
+  },
+)
+
+// 6. Usage examples
+async function demonstrateBoundTokens() {
+  console.log('=== Bound Tokens Example ===\n')
+
+  // Use production configuration
+  const prodDbConfig = await container.get(PRODUCTION_DB_CONFIG)
+  console.log('Production DB:', prodDbConfig.getConnectionString())
+
+  const prodEmailConfig = await container.get(PRODUCTION_EMAIL_CONFIG)
+  console.log('Production Email:', prodEmailConfig.getProvider())
+
+  // Use development configuration
+  const devDbConfig = await container.get(DEVELOPMENT_DB_CONFIG)
+  console.log('Development DB:', devDbConfig.getConnectionString())
+
+  const devEmailConfig = await container.get(DEVELOPMENT_EMAIL_CONFIG)
+  console.log('Development Email:', devEmailConfig.getProvider())
+}
+
+async function demonstrateFactoryTokens() {
+  console.log('\n=== Factory Tokens Example ===\n')
+
+  // Use dynamic configuration based on environment
+  const dbConfig = await container.get(DYNAMIC_DB_CONFIG)
+  console.log('Dynamic DB:', dbConfig.getConnectionString())
+
+  const emailConfig = await container.get(DYNAMIC_EMAIL_CONFIG)
+  console.log('Dynamic Email:', emailConfig.getProvider())
+}
+
+async function demonstrateDirectTokens() {
+  console.log('\n=== Direct Tokens Example ===\n')
+
+  // Use tokens directly with configuration
+  const dbConfig = await container.get(DB_CONFIG_TOKEN, {
+    host: 'custom-db.example.com',
+    port: 5432,
+    database: 'custom',
+    username: 'custom_user',
+    password: 'custom_password',
+  })
+  console.log('Custom DB:', dbConfig.getConnectionString())
+
+  const emailConfig = await container.get(EMAIL_CONFIG_TOKEN, {
+    provider: 'ses',
+    apiKey: 'aws_ses_key',
+    fromEmail: 'custom@example.com',
+  })
+  console.log('Custom Email:', emailConfig.getProvider())
+}
+
+// Main function
+async function main() {
+  await demonstrateBoundTokens()
+  await demonstrateFactoryTokens()
+  await demonstrateDirectTokens()
+}
+
+// Run the example
+if (require.main === module) {
+  main().catch(console.error)
+}
+
+export {
+  DB_CONFIG_TOKEN,
+  EMAIL_CONFIG_TOKEN,
+  PRODUCTION_DB_CONFIG,
+  DEVELOPMENT_DB_CONFIG,
+  PRODUCTION_EMAIL_CONFIG,
+  DEVELOPMENT_EMAIL_CONFIG,
+  DYNAMIC_DB_CONFIG,
+  DYNAMIC_EMAIL_CONFIG,
+  DatabaseConfigService,
+  EmailConfigService,
+}

package/docs/examples/request-scope-example.mts

@@ -0,0 +1,254 @@
+/**
+ * Example demonstrating the Request scope functionality in Navios DI.
+ *
+ * This example shows how to use request-scoped services for web applications
+ * where you need services that are shared within a request but isolated between requests.
+ */
+
+import { Container } from '../../src/container.mjs'
+import { Injectable } from '../../src/decorators/injectable.decorator.mjs'
+import { InjectableScope } from '../../src/enums/index.mjs'
+import { inject } from '../../src/injector.mjs'
+
+// ============================================================================
+// EXAMPLE SERVICES
+// ============================================================================
+
+/**
+ * Singleton service - shared across the entire application
+ */
+@Injectable({ scope: InjectableScope.Singleton })
+class DatabaseService {
+  private connectionCount = 0
+
+  async getConnection() {
+    this.connectionCount++
+    console.log(`[DatabaseService] Created connection #${this.connectionCount}`)
+    return {
+      id: this.connectionCount,
+      connected: true,
+      createdAt: new Date(),
+    }
+  }
+
+  getConnectionCount() {
+    return this.connectionCount
+  }
+}
+
+/**
+ * Request-scoped service - shared within a request, isolated between requests
+ */
+@Injectable({ scope: InjectableScope.Request })
+class UserContext {
+  public readonly requestId: string
+  public readonly userId: string
+  public readonly sessionId: string
+  public readonly startTime: number
+  private readonly database = inject(DatabaseService)
+
+  constructor({ userId, sessionId }: { userId: string; sessionId: string }) {
+    this.requestId = Math.random().toString(36).substring(2, 15)
+    this.userId = userId
+    this.sessionId = sessionId
+    this.startTime = Date.now()
+
+    console.log(
+      `[UserContext] Created for user ${userId} in request ${this.requestId}`,
+    )
+  }
+
+  async getDatabaseConnection() {
+    const db = await this.database
+    return await db.getConnection()
+  }
+
+  getRequestDuration() {
+    return Date.now() - this.startTime
+  }
+
+  async onServiceDestroy() {
+    console.log(
+      `[UserContext] Destroying context for user ${this.userId} (request ${this.requestId})`,
+    )
+  }
+}
+
+/**
+ * Request-scoped service that depends on UserContext
+ */
+@Injectable({ scope: InjectableScope.Request })
+class OrderService {
+  private readonly userContext = inject(UserContext)
+  private orders: string[] = []
+
+  async createOrder(productName: string) {
+    const userCtx = await this.userContext
+    const orderId = `order_${Math.random().toString(36).substring(2, 15)}`
+
+    this.orders.push(orderId)
+    console.log(
+      `[OrderService] Created order ${orderId} for user ${userCtx.userId}`,
+    )
+
+    return {
+      orderId,
+      userId: userCtx.userId,
+      productName,
+      requestId: userCtx.requestId,
+    }
+  }
+
+  getOrders() {
+    return [...this.orders]
+  }
+}
+
+/**
+ * Transient service - new instance for each injection
+ */
+@Injectable({ scope: InjectableScope.Transient })
+class LoggerService {
+  private readonly logId = Math.random().toString(36).substring(2, 15)
+
+  log(message: string) {
+    console.log(`[LoggerService:${this.logId}] ${message}`)
+  }
+}
+
+/**
+ * Service that uses all scopes
+ */
+@Injectable({ scope: InjectableScope.Singleton })
+class RequestHandler {
+  private readonly logger = inject(LoggerService)
+  private readonly userContext = inject(UserContext)
+  private readonly orderService = inject(OrderService)
+
+  async handleRequest(userId: string, sessionId: string) {
+    const logger = await this.logger
+    logger.log(`Handling request for user ${userId}`)
+
+    const userCtx = await this.userContext
+    logger.log(`User context request ID: ${userCtx.requestId}`)
+
+    const orderSvc = await this.orderService
+    const order = await orderSvc.createOrder('Sample Product')
+
+    logger.log(`Created order: ${order.orderId}`)
+    logger.log(`Request duration: ${userCtx.getRequestDuration()}ms`)
+
+    return {
+      userId: userCtx.userId,
+      requestId: userCtx.requestId,
+      orderId: order.orderId,
+      duration: userCtx.getRequestDuration(),
+    }
+  }
+}
+
+// ============================================================================
+// EXAMPLE USAGE
+// ============================================================================
+
+async function demonstrateRequestScope() {
+  console.log('🚀 Request Scope Example\n')
+
+  const container = new Container()
+
+  // Simulate multiple requests
+  const requests = [
+    { userId: 'user1', sessionId: 'session1' },
+    { userId: 'user2', sessionId: 'session2' },
+    { userId: 'user1', sessionId: 'session3' }, // Same user, different session
+  ]
+
+  for (let i = 0; i < requests.length; i++) {
+    const { userId, sessionId } = requests[i]
+
+    console.log(
+      `\n📝 Processing Request ${i + 1}: User ${userId}, Session ${sessionId}`,
+    )
+    console.log('─'.repeat(50))
+
+    // Begin request context
+    const requestId = `req_${i + 1}`
+    container.beginRequest(requestId, { userId, sessionId })
+
+    // Handle the request
+    const handler = await container.get(RequestHandler)
+    const result = await handler.handleRequest(userId, sessionId)
+
+    console.log(`✅ Request completed:`, result)
+
+    // End request context (cleans up request-scoped instances)
+    await container.endRequest(requestId)
+
+    console.log('─'.repeat(50))
+  }
+
+  // Show that singleton services persist across requests
+  const dbService = await container.get(DatabaseService)
+  console.log(
+    `\n📊 Total database connections created: ${dbService.getConnectionCount()}`,
+  )
+
+  console.log('\n✨ Example completed!')
+}
+
+// ============================================================================
+// PERFORMANCE COMPARISON
+// ============================================================================
+
+async function demonstratePerformanceBenefits() {
+  console.log('\n⚡ Performance Comparison\n')
+
+  const container = new Container()
+
+  // Without pre-preparation
+  console.log('🐌 Without pre-preparation:')
+  const start1 = Date.now()
+
+  container.beginRequest('perf-test-1')
+  const handler1 = await container.get(RequestHandler)
+  await handler1.handleRequest('user1', 'session1')
+  await container.endRequest('perf-test-1')
+
+  const time1 = Date.now() - start1
+  console.log(`   Time: ${time1}ms`)
+
+  // With pre-preparation
+  console.log('🚀 With pre-preparation:')
+  const start2 = Date.now()
+
+  container.beginRequest('perf-test-2')
+  const handler2 = await container.get(RequestHandler)
+  await handler2.handleRequest('user1', 'session1')
+  await container.endRequest('perf-test-2')
+
+  const time2 = Date.now() - start2
+  console.log(`   Time: ${time2}ms`)
+  console.log(
+    `   Improvement: ${(((time1 - time2) / time1) * 100).toFixed(1)}% faster`,
+  )
+}
+
+// ============================================================================
+// MAIN EXECUTION
+// ============================================================================
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  demonstrateRequestScope()
+    .then(() => demonstratePerformanceBenefits())
+    .catch(console.error)
+}
+
+export {
+  DatabaseService,
+  UserContext,
+  OrderService,
+  LoggerService,
+  RequestHandler,
+  demonstrateRequestScope,
+  demonstratePerformanceBenefits,
+}