@navios/di 0.2.1 → 0.3.1

package/docs/injection-tokens.md

@@ -0,0 +1,400 @@
+# Injection Tokens
+
+Injection tokens provide a flexible way to identify and resolve dependencies in Navios DI. They allow you to decouple service implementations from their consumers, making your code more modular and testable.
+
+## Overview
+
+Injection tokens serve as unique identifiers for services and can be used with:
+
+- **Schemas**: Define the shape of configuration data
+- **Bound Values**: Pre-configure tokens with specific values
+- **Factories**: Dynamically resolve token values
+
+## Basic Usage
+
+### Creating Injection Tokens
+
+```typescript
+import { InjectionToken } from '@navios/di'
+
+// Token with schema
+import { z } from 'zod'
+
+// Simple token without schema
+const USER_SERVICE_TOKEN = InjectionToken.create<UserService>('UserService')
+
+const configSchema = z.object({
+  apiUrl: z.string(),
+  timeout: z.number(),
+})
+
+const CONFIG_TOKEN = InjectionToken.create<Config, typeof configSchema>(
+  'APP_CONFIG',
+  configSchema,
+)
+```
+
+### Using Injection Tokens
+
+```typescript
+import { Injectable } from '@navios/di'
+
+@Injectable({ token: USER_SERVICE_TOKEN })
+class UserService {
+  getUsers() {
+    return ['Alice', 'Bob', 'Charlie']
+  }
+}
+
+// Inject using the token
+const userService = await container.get(USER_SERVICE_TOKEN)
+console.log(userService.getUsers())
+```
+
+## Token Types
+
+### Basic Injection Token
+
+```typescript
+import { Injectable, InjectionToken } from '@navios/di'
+
+interface EmailService {
+  sendEmail(to: string, subject: string): Promise<void>
+}
+
+const EMAIL_SERVICE_TOKEN = InjectionToken.create<EmailService>('EmailService')
+
+@Injectable({ token: EMAIL_SERVICE_TOKEN })
+class SmtpEmailService implements EmailService {
+  async sendEmail(to: string, subject: string) {
+    console.log(`SMTP email sent to ${to}: ${subject}`)
+  }
+}
+
+// Usage
+const emailService = await container.get(EMAIL_SERVICE_TOKEN)
+await emailService.sendEmail('user@example.com', 'Hello')
+```
+
+### Token with Schema
+
+```typescript
+import { Injectable, InjectionToken } from '@navios/di'
+
+import { z } from 'zod'
+
+const databaseConfigSchema = z.object({
+  host: z.string(),
+  port: z.number(),
+  database: z.string(),
+  username: z.string(),
+  password: z.string(),
+})
+
+const DB_CONFIG_TOKEN = InjectionToken.create<
+  DatabaseConfig,
+  typeof databaseConfigSchema
+>('DB_CONFIG', databaseConfigSchema)
+
+@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}`
+  }
+}
+
+// Usage with configuration
+const dbConfig = await container.get(DB_CONFIG_TOKEN, {
+  host: 'localhost',
+  port: 5432,
+  database: 'myapp',
+  username: 'postgres',
+  password: 'password',
+})
+
+console.log(dbConfig.getConnectionString())
+```
+
+### Bound Injection Token
+
+Bound tokens allow you to pre-configure a token with specific values:
+
+```typescript
+import { InjectionToken } from '@navios/di'
+
+const configSchema = z.object({
+  apiUrl: z.string(),
+  timeout: z.number(),
+})
+
+const CONFIG_TOKEN = InjectionToken.create<Config, typeof configSchema>(
+  'APP_CONFIG',
+  configSchema,
+)
+
+// Create bound token with specific values
+const PRODUCTION_CONFIG = InjectionToken.bound(CONFIG_TOKEN, {
+  apiUrl: 'https://api.production.com',
+  timeout: 10000,
+})
+
+const DEVELOPMENT_CONFIG = InjectionToken.bound(CONFIG_TOKEN, {
+  apiUrl: 'https://api.dev.com',
+  timeout: 5000,
+})
+
+// Usage - no need to provide arguments
+const prodConfig = await container.get(PRODUCTION_CONFIG)
+const devConfig = await container.get(DEVELOPMENT_CONFIG)
+
+console.log(prodConfig.apiUrl) // 'https://api.production.com'
+console.log(devConfig.apiUrl) // 'https://api.dev.com'
+```
+
+### Factory Injection Token
+
+Factory tokens dynamically resolve values using a factory function:
+
+```typescript
+import { Injectable, InjectionToken } from '@navios/di'
+
+@Injectable()
+class EnvironmentService {
+  getEnvironment() {
+    return process.env.NODE_ENV || 'development'
+  }
+
+  getApiUrl() {
+    const env = this.getEnvironment()
+    switch (env) {
+      case 'production':
+        return 'https://api.production.com'
+      case 'staging':
+        return 'https://api.staging.com'
+      default:
+        return 'https://api.dev.com'
+    }
+  }
+}
+
+const configSchema = z.object({
+  apiUrl: z.string(),
+  timeout: z.number(),
+})
+
+const CONFIG_TOKEN = InjectionToken.create<Config, typeof configSchema>(
+  'APP_CONFIG',
+  configSchema,
+)
+
+// Create factory token
+const DYNAMIC_CONFIG = InjectionToken.factory(CONFIG_TOKEN, async (ctx) => {
+  const envService = await ctx.inject(EnvironmentService)
+
+  return {
+    apiUrl: envService.getApiUrl(),
+    timeout: envService.getEnvironment() === 'production' ? 10000 : 5000,
+  }
+})
+
+// Usage
+const config = await container.get(DYNAMIC_CONFIG)
+console.log(config.apiUrl) // Dynamically resolved based on environment
+```
+
+## Advanced Patterns
+
+### Multiple Implementations
+
+```typescript
+import { Injectable, InjectionToken } from '@navios/di'
+
+interface PaymentProcessor {
+  processPayment(amount: number): Promise<string>
+}
+
+const PAYMENT_PROCESSOR_TOKEN =
+  InjectionToken.create<PaymentProcessor>('PaymentProcessor')
+
+// Stripe implementation
+@Injectable({ token: PAYMENT_PROCESSOR_TOKEN })
+class StripePaymentProcessor implements PaymentProcessor {
+  async processPayment(amount: number) {
+    return `Processed $${amount} via Stripe`
+  }
+}
+
+// PayPal implementation
+@Injectable({ token: PAYMENT_PROCESSOR_TOKEN })
+class PayPalPaymentProcessor implements PaymentProcessor {
+  async processPayment(amount: number) {
+    return `Processed $${amount} via PayPal`
+  }
+}
+
+// Usage - the last registered implementation will be used
+const paymentProcessor = await container.get(PAYMENT_PROCESSOR_TOKEN)
+await paymentProcessor.processPayment(100)
+```
+
+### Token with Optional Schema
+
+```typescript
+import { Injectable, InjectionToken } from '@navios/di'
+
+const optionalConfigSchema = z.object({
+  apiUrl: z.string(),
+  timeout: z.number().optional(),
+  retries: z.number().optional(),
+})
+
+const OPTIONAL_CONFIG_TOKEN = InjectionToken.create<
+  OptionalConfigService,
+  typeof optionalConfigSchema
+>('OPTIONAL_CONFIG', optionalConfigSchema)
+
+@Injectable({ token: OPTIONAL_CONFIG_TOKEN })
+class OptionalConfigService {
+  constructor(private config: z.infer<typeof optionalConfigSchema>) {}
+
+  getApiUrl() {
+    return this.config.apiUrl
+  }
+
+  getTimeout() {
+    return this.config.timeout ?? 5000
+  }
+
+  getRetries() {
+    return this.config.retries ?? 3
+  }
+}
+
+// Usage with partial configuration
+const config = await container.get(OPTIONAL_CONFIG_TOKEN, {
+  apiUrl: 'https://api.example.com',
+  // timeout and retries are optional
+})
+
+console.log(config.getTimeout()) // 5000 (default)
+console.log(config.getRetries()) // 3 (default)
+```
+
+## Best Practices
+
+### 1. Use Descriptive Token Names
+
+```typescript
+// ✅ Good: Descriptive names
+const USER_REPOSITORY_TOKEN =
+  InjectionToken.create<UserRepository>('UserRepository')
+const EMAIL_SERVICE_TOKEN = InjectionToken.create<EmailService>('EmailService')
+
+// ❌ Avoid: Generic names
+const SERVICE_TOKEN = InjectionToken.create<Service>('Service')
+const TOKEN_1 = InjectionToken.create<Service>('Token1')
+```
+
+### 2. Define Schemas for Configuration Tokens
+
+```typescript
+// ✅ Good: Define schema for configuration
+const configSchema = z.object({
+  apiUrl: z.string().url(),
+  timeout: z.number().min(1000),
+  retries: z.number().min(0).max(10),
+})
+
+const CONFIG_TOKEN = InjectionToken.create<Config, typeof configSchema>(
+  'APP_CONFIG',
+  configSchema,
+)
+```
+
+### 3. Use Bound Tokens for Environment-Specific Configuration
+
+```typescript
+// ✅ Good: Environment-specific bound tokens
+const PRODUCTION_CONFIG = InjectionToken.bound(CONFIG_TOKEN, {
+  apiUrl: 'https://api.production.com',
+  timeout: 10000,
+  retries: 5,
+})
+
+const DEVELOPMENT_CONFIG = InjectionToken.bound(CONFIG_TOKEN, {
+  apiUrl: 'https://api.dev.com',
+  timeout: 5000,
+  retries: 3,
+})
+```
+
+### 4. Use Factory Tokens for Dynamic Resolution
+
+```typescript
+// ✅ Good: Factory for dynamic configuration
+const DYNAMIC_CONFIG = InjectionToken.factory(CONFIG_TOKEN, async () => {
+  const env = process.env.NODE_ENV || 'development'
+
+  return {
+    apiUrl:
+      env === 'production' ? 'https://api.prod.com' : 'https://api.dev.com',
+    timeout: env === 'production' ? 10000 : 5000,
+    retries: env === 'production' ? 5 : 3,
+  }
+})
+```
+
+### 5. Group Related Tokens
+
+```typescript
+// ✅ Good: Group related tokens
+export const DATABASE_TOKENS = {
+  CONFIG: InjectionToken.create<DatabaseConfig>('DatabaseConfig'),
+  CONNECTION: InjectionToken.create<DatabaseConnection>('DatabaseConnection'),
+  REPOSITORY: InjectionToken.create<UserRepository>('UserRepository'),
+} as const
+```
+
+## API Reference
+
+### InjectionToken.create
+
+```typescript
+// Simple token
+static create<T>(name: string | symbol): InjectionToken<T, undefined>
+
+// Token with schema
+static create<T, S extends InjectionTokenSchemaType>(
+  name: string | symbol,
+  schema: S
+): InjectionToken<T, S>
+```
+
+### InjectionToken.bound
+
+```typescript
+static bound<T, S extends InjectionTokenSchemaType>(
+  token: InjectionToken<T, S>,
+  value: z.input<S>
+): BoundInjectionToken<T, S>
+```
+
+### InjectionToken.factory
+
+```typescript
+static factory<T, S extends InjectionTokenSchemaType>(
+  token: InjectionToken<T, S>,
+  factory: (ctx: FactoryContext) => Promise<z.input<S>>
+): FactoryInjectionToken<T, S>
+```
+
+### Token Types
+
+```typescript
+type InjectionTokenType =
+  | InjectionToken<any, any>
+  | BoundInjectionToken<any, any>
+  | FactoryInjectionToken<any, any>
+```