API Reference

// Complex configuration object factory
interface IConfig {
  apiUrl: string
  timeout: number
  retryStrategy: 'exponential' | 'linear'
}

class ApiService {
  constructor(
    private config: IConfig,
    private logger: ILogger
  ) {}
}

const container = new Builder()
  .registerType(ConsoleLogger).as<ILogger>().singleInstance()
  .registerType(ApiService)
    .autoWire({
      map: {
        // Factory creates config based on environment
        config: () => ({
          apiUrl: import.meta.env.PROD
            ? 'https://api.production.com'
            : 'http://localhost:3000',
          timeout: import.meta.env.PROD ? 10000 : 30000,
          retryStrategy: import.meta.env.PROD ? 'exponential' : 'linear'
        })
      }
    })
    .singleInstance()
  .build()

interface ICache {
  get(key: string): Promise<any>
  set(key: string, value: any): Promise<void>
}

class RedisCache implements ICache {
  async get(key: string) { /* Redis implementation */ }
  async set(key: string, value: any) { /* Redis implementation */ }
}

class InMemoryCache implements ICache {
  async get(key: string) { /* In-memory implementation */ }
  async set(key: string, value: any) { /* In-memory implementation */ }
}

class UserService {
  constructor(private cache: ICache) {}
}

const container = new Builder()
  .registerType(RedisCache).as<ICache>().named('redis').singleInstance()
  .registerType(InMemoryCache).as<ICache>().named('memory').singleInstance()
  .registerType(UserService)
    .autoWire({
      map: {
        // Conditional: Use Redis in production, in-memory for dev/test
        cache: (c) => {
          const env = import.meta.env.MODE
          return env === 'production'
            ? c.resolveTypeNamed<ICache>('redis')
            : c.resolveTypeNamed<ICache>('memory')
        }
      }
    })
    .singleInstance()
  .build()

interface IRequestContext {
  userId: string
  tenantId: string
}

class RequestContext implements IRequestContext {
  constructor(
    public userId: string,
    public tenantId: string
  ) {}
}

class TenantDatabase {
  constructor(
    private context: IRequestContext,
    private logger: ILogger
  ) {
    this.logger.log(`DB for tenant: ${context.tenantId}`)
  }

  query(sql: string) {
    // Use context.tenantId to route to correct database
  }
}

// Global container with singletons
const rootContainer = new Builder()
  .registerType(ConsoleLogger).as<ILogger>().singleInstance()
  .registerType(TenantDatabase).scoped()  // Scoped to child container
  .build()

// Per-request child container
function handleRequest(userId: string, tenantId: string) {
  const requestScope = rootContainer.createChild()

  // Register request-specific context
  requestScope.bindValue(
    { symbol: Symbol('IRequestContext') } as any,
    new RequestContext(userId, tenantId),
    { lifetime: 'scoped' }
  )

  // TenantDatabase gets scoped context + singleton logger
  const db = requestScope.resolveType<TenantDatabase>()
  db.query('SELECT * FROM users')

  requestScope.dispose()  // Clean up scoped instances
}

interface IHeavyService {
  process(): void
}

class HeavyService implements IHeavyService {
  constructor() {
    console.log('⚠️ Expensive initialization!')
  }
  process() { /* Heavy work */ }
}

// Instead of injecting the service directly, inject a factory
type ServiceFactory<T> = () => T

class OptimizedController {
  constructor(
    private serviceFactory: ServiceFactory<IHeavyService>,
    private logger: ILogger
  ) {}

  handleRequest(needsHeavyProcessing: boolean) {
    this.logger.log('Request received')

    if (needsHeavyProcessing) {
      // Only create HeavyService when actually needed!
      const service = this.serviceFactory()
      service.process()
    }
  }
}

const container = new Builder()
  .registerType(ConsoleLogger).as<ILogger>()
  .registerType(HeavyService).as<IHeavyService>().instancePerDependency()
  .registerType(OptimizedController)
    .autoWire({
      map: {
        // Inject a factory function instead of the service itself
        serviceFactory: (c) => () => c.resolveType<IHeavyService>()
      }
    })
  .build()

const controller = container.resolveType<OptimizedController>()
controller.handleRequest(false)  // ✅ No heavy initialization!
controller.handleRequest(true)   // ⚠️ Now it initializes

interface IDataService {
  getData(id: string): Promise<any>
}

class DataService implements IDataService {
  async getData(id: string) {
    // Fetch from database
    return { id, data: 'raw data' }
  }
}

// Decorator: Adds caching
class CachedDataService implements IDataService {
  private cache = new Map()

  constructor(
    private inner: IDataService,
    private logger: ILogger
  ) {}

  async getData(id: string) {
    if (this.cache.has(id)) {
      this.logger.log(`Cache hit: ${id}`)
      return this.cache.get(id)
    }

    const data = await this.inner.getData(id)
    this.cache.set(id, data)
    return data
  }
}

// Decorator: Adds logging
class LoggedDataService implements IDataService {
  constructor(
    private inner: IDataService,
    private logger: ILogger
  ) {}

  async getData(id: string) {
    this.logger.log(`Getting data: ${id}`)
    const result = await this.inner.getData(id)
    this.logger.log(`Got data: ${id}`)
    return result
  }
}

const container = new Builder()
  .registerType(ConsoleLogger).as<ILogger>()
  .registerType(DataService).named('core').instancePerDependency()

  // Wrap with caching decorator
  .registerType(CachedDataService)
    .named('cached')
    .autoWire({
      map: {
        inner: (c) => c.resolveTypeNamed<IDataService>('core')
      }
    })
    .instancePerDependency()

  // Wrap cached version with logging decorator
  .registerType(LoggedDataService)
    .as<IDataService>()  // This is the final service
    .autoWire({
      map: {
        inner: (c) => c.resolveTypeNamed<IDataService>('cached')
      }
    })
    .singleInstance()
  .build()

// Resolves: LoggedDataService → CachedDataService → DataService
const service = container.resolveType<IDataService>()
await service.getData('123')  // Logs + caches + fetches

interface IAnalytics {
  track(event: string): void
}

class GoogleAnalytics implements IAnalytics {
  track(event: string) {
    console.log(`📊 GA: ${event}`)
  }
}

class MixpanelAnalytics implements IAnalytics {
  track(event: string) {
    console.log(`📈 Mixpanel: ${event}`)
  }
}

class NoOpAnalytics implements IAnalytics {
  track(event: string) {
    // Do nothing (analytics disabled)
  }
}

// Feature flags from environment
const features = {
  analyticsProvider: import.meta.env.VITE_ANALYTICS_PROVIDER, // 'google' | 'mixpanel' | 'none'
  enablePremiumFeatures: import.meta.env.VITE_PREMIUM_FEATURES === 'true'
}

const container = new Builder()
  .registerType(GoogleAnalytics).named('google').singleInstance()
  .registerType(MixpanelAnalytics).named('mixpanel').singleInstance()
  .registerType(NoOpAnalytics).named('none').singleInstance()

  // Main app gets analytics based on feature flag
  .registerType(App)
    .autoWire({
      map: {
        analytics: (c) => {
          switch (features.analyticsProvider) {
            case 'google': return c.resolveTypeNamed<IAnalytics>('google')
            case 'mixpanel': return c.resolveTypeNamed<IAnalytics>('mixpanel')
            default: return c.resolveTypeNamed<IAnalytics>('none')
          }
        },
        premiumEnabled: () => features.enablePremiumFeatures
      }
    })
    .singleInstance()
  .build()