@navios/di 0.4.1 → 0.5.0

package/src/testing/README.md

@@ -0,0 +1,80 @@
+# Testing Infrastructure
+
+The `@navios/di/testing` package provides a `TestContainer` class that extends the base `Container` with additional methods useful for testing.
+
+## Features
+
+- **TestContainer**: A specialized container for testing with simplified binding methods
+- **bind().toValue()**: Bind tokens to specific values (useful for mocks)
+- **bind().toClass()**: Bind tokens to class constructors
+- **clear()**: Clear all instances and bindings from the container
+- **Convenience methods**: `bindValue()`, `bindClass()`, `createChild()`
+
+## Usage
+
+```typescript
+import { Injectable, InjectionToken } from '@navios/di'
+import { TestContainer } from '@navios/di/testing'
+
+// Create a test container
+const container = new TestContainer()
+
+// Create injection tokens
+const API_URL_TOKEN = InjectionToken.create<string>('api-url')
+const HTTP_CLIENT_TOKEN = InjectionToken.create<HttpClient>('http-client')
+
+// Mock implementations
+class MockHttpClient implements HttpClient {
+  async get(url: string) {
+    return { data: 'mocked response' }
+  }
+}
+
+// Bind values for testing
+container.bindValue(API_URL_TOKEN, 'https://test-api.com')
+container.bindClass(HTTP_CLIENT_TOKEN, MockHttpClient)
+
+// Or use the fluent API
+container.bind(API_URL_TOKEN).toValue('https://test-api.com')
+
+container.bind(HTTP_CLIENT_TOKEN).toClass(MockHttpClient)
+
+// Bind a class to itself
+@Injectable()
+class UserService {
+  constructor(
+    @Inject(API_URL_TOKEN) private apiUrl: string,
+    @Inject(HTTP_CLIENT_TOKEN) private httpClient: HttpClient,
+  ) {}
+}
+
+container.bindSelf(UserService)
+
+// Clear the container between tests
+container.clear()
+
+// Create isolated child containers
+const childContainer = container.createChild()
+```
+
+## API Reference
+
+### TestContainer
+
+#### Methods
+
+- `bind<T>(token: InjectionToken<T, any>): TestBindingBuilder<T>` - Creates a binding builder
+- `bind<T>(token: ClassType): TestBindingBuilder<T>` - Creates a binding builder
+- `bindValue<T>(token: InjectionToken<T, any>, value: T): TestContainer` - Binds a value to a token
+- `bindValue<T>(token: ClassType, value: T): TestContainer` - Binds a value to a token
+- `bindClass<T>(token: InjectionToken<T, any>, target: ClassType): TestContainer` - Binds a class to a token
+- `bindClass<T>(token: ClassType, target: ClassType): TestContainer` - Binds a class to a token
+- `createChild(): TestContainer` - Creates a new isolated test container
+- `clear(): void` - Clears all instances and bindings
+
+### TestBindingBuilder
+
+#### Methods
+
+- `toValue(value: T): TestContainer` - Binds the token to a specific value
+- `toClass(target: ClassType): TestContainer` - Binds the token to a class constructor

package/src/testing/__tests__/test-container.spec.mts

@@ -0,0 +1,173 @@
+import { beforeEach, describe, expect, it } from 'vitest'
+
+import { Injectable } from '../../decorators/injectable.decorator.mjs'
+import { InjectionToken } from '../../injection-token.mjs'
+import { inject } from '../../injector.mjs'
+import { TestContainer } from '../test-container.mjs'
+
+describe('TestContainer', () => {
+  let container: TestContainer
+
+  beforeEach(() => {
+    container = new TestContainer()
+  })
+
+  describe('clear method', () => {
+    it('should clear all instances from the container', () => {
+      // This test verifies that the clear method exists and can be called
+      expect(() => container.clear()).not.toThrow()
+    })
+  })
+
+  describe('bind method', () => {
+    it('should create a TestBindingBuilder', () => {
+      const token = InjectionToken.create<string>('test-token')
+      const builder = container.bind(token)
+      expect(builder).toBeDefined()
+      expect(builder).toHaveProperty('toValue')
+      expect(builder).toHaveProperty('toClass')
+    })
+
+    it('should allow chaining bind operations', () => {
+      const token = InjectionToken.create<string>('test-token')
+      const result = container.bind(token).toValue('test-value')
+      expect(result).toBe(container)
+    })
+
+    it('should bind value and retrieve it correctly', async () => {
+      const token = InjectionToken.create<string>('test-token')
+      const testValue = 'test-value'
+
+      container.bind(token).toValue(testValue)
+
+      const retrievedValue = await container.get(token)
+      expect(retrievedValue).toBe(testValue)
+    })
+
+    it('should bind class and retrieve instance correctly', async () => {
+      @Injectable()
+      class TestService {
+        getValue() {
+          return 'test-service-value'
+        }
+      }
+
+      const token = InjectionToken.create<TestService>('test-service')
+
+      container.bind(token).toClass(TestService)
+
+      const instance = await container.get(token)
+      expect(instance).toBeInstanceOf(TestService)
+      expect(instance.getValue()).toBe('test-service-value')
+    })
+  })
+
+  describe('bindValue method', () => {
+    it('should bind a value to a token', () => {
+      const token = InjectionToken.create<string>('test-token')
+      const result = container.bindValue(token, 'test-value')
+      expect(result).toBe(container)
+    })
+
+    it('should bind value and retrieve it correctly', async () => {
+      const token = InjectionToken.create<number>('number-token')
+      const testValue = 42
+
+      container.bindValue(token, testValue)
+
+      const retrievedValue = await container.get(token)
+      expect(retrievedValue).toBe(testValue)
+    })
+
+    it('should bind object value and retrieve it correctly', async () => {
+      interface TestConfig {
+        apiUrl: string
+        timeout: number
+      }
+
+      const token = InjectionToken.create<TestConfig>('config-token')
+      const testConfig: TestConfig = {
+        apiUrl: 'https://api.example.com',
+        timeout: 5000,
+      }
+
+      container.bindValue(token, testConfig)
+
+      const retrievedConfig = await container.get(token)
+      expect(retrievedConfig).toEqual(testConfig)
+      expect(retrievedConfig.apiUrl).toBe('https://api.example.com')
+      expect(retrievedConfig.timeout).toBe(5000)
+    })
+  })
+
+  describe('bindClass method', () => {
+    it('should bind a class to a token', () => {
+      class TestClass {}
+      const token = InjectionToken.create<TestClass>('test-token')
+      const result = container.bindClass(token, TestClass)
+      expect(result).toBe(container)
+    })
+
+    it('should bind class and retrieve instance correctly', async () => {
+      @Injectable()
+      class UserService {
+        private users: string[] = ['alice', 'bob']
+
+        getUsers() {
+          return this.users
+        }
+
+        addUser(user: string) {
+          this.users.push(user)
+        }
+      }
+
+      const token = InjectionToken.create<UserService>('user-service')
+
+      container.bindClass(token, UserService)
+
+      const instance = await container.get(token)
+      expect(instance).toBeInstanceOf(UserService)
+      expect(instance.getUsers()).toEqual(['alice', 'bob'])
+
+      instance.addUser('charlie')
+      expect(instance.getUsers()).toEqual(['alice', 'bob', 'charlie'])
+    })
+
+    it('should bind class with dependencies and retrieve instance correctly', async () => {
+      @Injectable()
+      class DatabaseService {
+        connect() {
+          return 'connected'
+        }
+      }
+
+      @Injectable()
+      class UserRepository {
+        db = inject(DatabaseService)
+
+        findUser(id: string) {
+          return `User ${id} from ${this.db.connect()}`
+        }
+      }
+
+      const dbToken = InjectionToken.create<DatabaseService>('db-service')
+      const userRepoToken = InjectionToken.create<UserRepository>('user-repo')
+
+      container.bindClass(dbToken, DatabaseService)
+      container.bindClass(userRepoToken, UserRepository)
+
+      const userRepo = await container.get(userRepoToken)
+      expect(userRepo).toBeInstanceOf(UserRepository)
+      expect(userRepo.findUser('123')).toBe('User 123 from connected')
+    })
+  })
+
+  describe('createChild method', () => {
+    it('should create a new TestContainer instance', () => {
+      const child = container.createChild()
+      expect(child).toBeInstanceOf(TestContainer)
+      expect(child).not.toBe(container)
+    })
+  })
+})

package/src/testing/index.mts

@@ -0,0 +1 @@
+export * from './test-container.mjs'

package/src/testing/test-container.mts

@@ -0,0 +1,120 @@
+import type { ClassType, InjectionToken } from '../injection-token.mjs'
+import type { Registry } from '../registry.mjs'
+import type { Injectors } from '../utils/index.mjs'
+
+import { Container } from '../container.mjs'
+import { Injectable } from '../decorators/injectable.decorator.mjs'
+import { InjectableScope, InjectableType } from '../enums/index.mjs'
+import { globalRegistry } from '../registry.mjs'
+import { getInjectableToken } from '../utils/index.mjs'
+
+/**
+ * A binding builder for the TestContainer that allows chaining binding operations.
+ */
+export class TestBindingBuilder<T> {
+  constructor(
+    private readonly container: TestContainer,
+    private readonly token: InjectionToken<T, any>,
+  ) {}
+
+  /**
+   * Binds the token to a specific value.
+   * This is useful for testing with mock values or constants.
+   * @param value The value to bind to the token
+   */
+  toValue(value: T): TestContainer {
+    const instanceName = this.container
+      .getServiceLocator()
+      .getInstanceIdentifier(this.token)
+    this.container
+      .getServiceLocator()
+      .getManager()
+      .storeCreatedHolder(
+        instanceName,
+        value,
+        InjectableType.Class,
+        InjectableScope.Singleton,
+      )
+    return this.container
+  }
+
+  /**
+   * Binds the token to a class constructor.
+   * @param target The class constructor to bind to
+   */
+  toClass(target: ClassType): TestContainer {
+    this.container['registry'].set(
+      this.token,
+      InjectableScope.Singleton,
+      target,
+      InjectableType.Class,
+    )
+    return this.container
+  }
+}
+
+/**
+ * TestContainer extends the base Container with additional methods useful for testing.
+ * It provides a simplified API for binding values and classes during test setup.
+ */
+@Injectable()
+export class TestContainer extends Container {
+  constructor(
+    registry: Registry = globalRegistry,
+    logger: Console | null = null,
+    injectors: Injectors = undefined as any,
+  ) {
+    super(registry, logger, injectors)
+  }
+
+  /**
+   * Creates a binding builder for the given token.
+   * This allows chaining binding operations like bind(Token).toValue(value).
+   * @param token The injection token to bind
+   * @returns A TestBindingBuilder for chaining binding operations
+   */
+  bind<T>(token: ClassType): TestBindingBuilder<T>
+  bind<T>(token: InjectionToken<T, any>): TestBindingBuilder<T>
+  bind(token: any): TestBindingBuilder<any> {
+    let realToken = token
+    if (typeof token === 'function') {
+      realToken = getInjectableToken(token)
+    }
+    return new TestBindingBuilder(this, realToken)
+  }
+
+  /**
+   * Binds a value directly to a token.
+   * This is a convenience method equivalent to bind(token).toValue(value).
+   * @param token The injection token to bind
+   * @param value The value to bind to the token
+   * @returns The TestContainer instance for chaining
+   */
+  bindValue<T>(token: ClassType, value: T): TestContainer
+  bindValue<T>(token: InjectionToken<T, any>, value: T): TestContainer
+  bindValue(token: any, value: any): TestContainer {
+    return this.bind(token).toValue(value)
+  }
+
+  /**
+   * Binds a class to a token.
+   * This is a convenience method equivalent to bind(token).toClass(target).
+   * @param token The injection token to bind
+   * @param target The class constructor to bind to
+   * @returns The TestContainer instance for chaining
+   */
+  bindClass(token: ClassType, target: ClassType): TestContainer
+  bindClass<T>(token: InjectionToken<T, any>, target: ClassType): TestContainer
+  bindClass(token: any, target: any): TestContainer {
+    return this.bind(token).toClass(target)
+  }
+
+  /**
+   * Creates a new TestContainer instance with the same configuration.
+   * This is useful for creating isolated test containers.
+   * @returns A new TestContainer instance
+   */
+  createChild(): TestContainer {
+    return new TestContainer(this.registry, this.logger, this.injectors)
+  }
+}

package/src/token-processor.mts

@@ -0,0 +1,174 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/* eslint-disable @typescript-eslint/no-empty-object-type */
+
+import type { FactoryContext } from './factory-context.mjs'
+import type {
+  AnyInjectableType,
+  InjectionTokenType,
+} from './injection-token.mjs'
+import type { RequestContextHolder } from './request-context-holder.mjs'
+import type { ServiceLocator } from './service-locator.mjs'
+
+import { DIError } from './errors/index.mjs'
+import {
+  BoundInjectionToken,
+  FactoryInjectionToken,
+  InjectionToken,
+} from './injection-token.mjs'
+import { getInjectableToken } from './utils/index.mjs'
+
+/**
+ * TokenProcessor handles token validation, resolution, and instance name generation.
+ * Extracted from ServiceLocator to improve separation of concerns.
+ */
+export class TokenProcessor {
+  constructor(private readonly logger: Console | null = null) {}
+
+  /**
+   * Validates and resolves token arguments, handling factory token resolution and validation.
+   */
+  validateAndResolveTokenArgs(
+    token: AnyInjectableType,
+    args?: any,
+  ): [
+    DIError | undefined,
+    { actualToken: InjectionTokenType; validatedArgs?: any },
+  ] {
+    let actualToken = token as InjectionToken<any, any>
+    if (typeof token === 'function') {
+      actualToken = getInjectableToken(token)
+    }
+    let realArgs = args
+    if (actualToken instanceof BoundInjectionToken) {
+      realArgs = actualToken.value
+    } else if (actualToken instanceof FactoryInjectionToken) {
+      if (actualToken.resolved) {
+        realArgs = actualToken.value
+      } else {
+        return [DIError.factoryTokenNotResolved(token.name), { actualToken }]
+      }
+    }
+    if (!actualToken.schema) {
+      return [undefined, { actualToken, validatedArgs: realArgs }]
+    }
+    const validatedArgs = actualToken.schema?.safeParse(realArgs)
+    if (validatedArgs && !validatedArgs.success) {
+      this.logger?.error(
+        `[TokenProcessor]#validateAndResolveTokenArgs(): Error validating args for ${actualToken.name.toString()}`,
+        validatedArgs.error,
+      )
+      return [DIError.unknown(validatedArgs.error), { actualToken }]
+    }
+    return [undefined, { actualToken, validatedArgs: validatedArgs?.data }]
+  }
+
+  /**
+   * Generates a unique instance name based on token and arguments.
+   */
+  generateInstanceName(token: InjectionTokenType, args: any): string {
+    if (!args) {
+      return token.toString()
+    }
+
+    const formattedArgs = Object.entries(args)
+      .sort(([keyA], [keyB]) => keyA.localeCompare(keyB))
+      .map(([key, value]) => `${key}=${this.formatArgValue(value)}`)
+      .join(',')
+
+    return `${token.toString()}:${formattedArgs.replaceAll(/"/g, '').replaceAll(/:/g, '=')}`
+  }
+
+  /**
+   * Formats a single argument value for instance name generation.
+   */
+  formatArgValue(value: any): string {
+    if (typeof value === 'function') {
+      return `fn_${value.name}(${value.length})`
+    }
+    if (typeof value === 'symbol') {
+      return value.toString()
+    }
+    return JSON.stringify(value).slice(0, 40)
+  }
+
+  /**
+   * Creates a factory context for dependency injection during service instantiation.
+   * @param serviceLocator Reference to the service locator for dependency resolution
+   */
+  createFactoryContext(
+    serviceLocator: ServiceLocator, // ServiceLocator reference for dependency resolution
+  ): FactoryContext & {
+    getDestroyListeners: () => (() => void)[]
+    deps: Set<string>
+  } {
+    const destroyListeners = new Set<() => void>()
+    const deps = new Set<string>()
+
+    function addDestroyListener(listener: () => void) {
+      destroyListeners.add(listener)
+    }
+
+    function getDestroyListeners() {
+      return Array.from(destroyListeners)
+    }
+
+    return {
+      // @ts-expect-error This is correct type
+      async inject(token, args) {
+        // Fall back to normal resolution
+        const [error, instance] = await serviceLocator.getInstance(
+          token,
+          args,
+          ({ instanceName }: { instanceName: string }) => {
+            deps.add(instanceName)
+          },
+        )
+        if (error) {
+          throw error
+        }
+        return instance
+      },
+      addDestroyListener,
+      getDestroyListeners,
+      locator: serviceLocator,
+      deps,
+    }
+  }
+
+  /**
+   * Tries to get a pre-prepared instance from request contexts.
+   */
+  tryGetPrePreparedInstance(
+    instanceName: string,
+    contextHolder: RequestContextHolder | undefined,
+    deps: Set<string>,
+    currentRequestContext: RequestContextHolder | null,
+  ): any {
+    // Check provided context holder first (if has higher priority)
+    if (contextHolder && contextHolder.priority > 0) {
+      const prePreparedInstance = contextHolder.get(instanceName)?.instance
+      if (prePreparedInstance !== undefined) {
+        this.logger?.debug(
+          `[TokenProcessor] Using pre-prepared instance ${instanceName} from request context ${contextHolder.requestId}`,
+        )
+        deps.add(instanceName)
+        return prePreparedInstance
+      }
+    }
+
+    // Check current request context (if different from provided contextHolder)
+    if (currentRequestContext && currentRequestContext !== contextHolder) {
+      const prePreparedInstance =
+        currentRequestContext.get(instanceName)?.instance
+      if (prePreparedInstance !== undefined) {
+        this.logger?.debug(
+          `[TokenProcessor] Using pre-prepared instance ${instanceName} from current request context ${currentRequestContext.requestId}`,
+        )
+        deps.add(instanceName)
+        return prePreparedInstance
+      }
+    }
+
+    return undefined
+  }
+}