@navios/di 0.4.2 → 0.5.0

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
+  }
+}

package/src/utils/get-injectors.mts

@@ -4,22 +4,45 @@ import type { FactoryContext } from '../factory-context.mjs'
 import type {
   BoundInjectionToken,
   ClassType,
+  ClassTypeWithArgument,
+  ClassTypeWithoutArguments,
   FactoryInjectionToken,
   InjectionToken,
   InjectionTokenSchemaType,
 } from '../injection-token.mjs'
-import type { Factorable } from '../interfaces/factory.interface.mjs'
-import type { InjectState, Join, UnionToArray } from './types.mjs'
+import type {
+  Factorable,
+  FactorableWithArgs,
+} from '../interfaces/factory.interface.mjs'
+import type {
+  InjectRequest,
+  InjectState,
+  Join,
+  UnionToArray,
+} from './types.mjs'
 
 import { InjectableTokenMeta } from '../symbols/index.mjs'
 
 export interface Injectors {
   // #1 Simple class
-  asyncInject<T extends ClassType>(
+  asyncInject<T extends ClassTypeWithoutArguments>(
     token: T,
   ): InstanceType<T> extends Factorable<infer R>
     ? Promise<R>
     : Promise<InstanceType<T>>
+  asyncInject<Args, T extends ClassTypeWithArgument<Args>>(
+    token: T,
+    args: Args,
+  ): Promise<InstanceType<T>>
+  asyncInject<
+    Schema extends InjectionTokenSchemaType,
+    R,
+    T extends FactorableWithArgs<R, Schema>,
+  >(
+    token: T,
+    args: z.input<Schema>,
+  ): Promise<R>
+
   // #2 Token with required Schema
   asyncInject<T, S extends InjectionTokenSchemaType>(
     token: InjectionToken<T, S>,
@@ -41,9 +64,22 @@ export interface Injectors {
   asyncInject<T>(token: BoundInjectionToken<T, any>): Promise<T>
   asyncInject<T>(token: FactoryInjectionToken<T, any>): Promise<T>
 
-  inject<T extends ClassType>(
+  inject<T extends ClassTypeWithoutArguments>(
     token: T,
   ): InstanceType<T> extends Factorable<infer R> ? R : InstanceType<T>
+  inject<Args, T extends ClassTypeWithArgument<Args>>(
+    token: T,
+    args: Args,
+  ): InstanceType<T>
+  inject<
+    Schema extends InjectionTokenSchemaType,
+    R,
+    T extends FactorableWithArgs<R, Schema>,
+  >(
+    token: T,
+    args: z.input<Schema>,
+  ): R
+
   inject<T, S extends InjectionTokenSchemaType>(
     token: InjectionToken<T, S>,
     args: z.input<S>,
@@ -63,6 +99,45 @@ export interface Injectors {
   inject<T>(token: BoundInjectionToken<T, any>): T
   inject<T>(token: FactoryInjectionToken<T, any>): T
 
+  /**
+   * Optional injection that returns null if the service fails to initialize
+   * or is not available. This is useful when you want to inject a service
+   * that may not be configured or may fail gracefully.
+   *
+   * @example
+   * ```ts
+   * class MyService {
+   *   constructor() {
+   *     const optionalService = optional(OptionalServiceToken)
+   *     // optionalService will be null if initialization fails
+   *     if (optionalService) {
+   *       optionalService.doSomething()
+   *     }
+   *   }
+   * }
+   * ```
+   */
+  optional<T extends ClassType>(
+    token: T,
+  ): (InstanceType<T> extends Factorable<infer R> ? R : InstanceType<T>) | null
+  optional<T, S extends InjectionTokenSchemaType>(
+    token: InjectionToken<T, S>,
+    args: z.input<S>,
+  ): T | null
+  optional<T, S extends InjectionTokenSchemaType, R extends boolean>(
+    token: InjectionToken<T, S, R>,
+  ): R extends false
+    ? T | null
+    : S extends ZodType<infer Type>
+      ? `Error: Your token requires args: ${Join<
+          UnionToArray<keyof Type>,
+          ', '
+        >}`
+      : 'Error: Your token requires args'
+  optional<T>(token: InjectionToken<T, undefined>): T | null
+  optional<T>(token: BoundInjectionToken<T, any>): T | null
+  optional<T>(token: FactoryInjectionToken<T, any>): T | null
+
   wrapSyncInit(
     cb: () => any,
   ): (injectState?: InjectState) => [any, Promise<any>[], InjectState]
@@ -92,17 +167,10 @@ export function getInjectors() {
   let promiseCollector: null | ((promise: Promise<any>) => void) = null
   let injectState: InjectState | null = null
 
-  function asyncInject(
-    token:
-      | ClassType
-      | InjectionToken<any>
-      | BoundInjectionToken<any, any>
-      | FactoryInjectionToken<any, any>,
-    args?: unknown,
-  ) {
+  function getRequest(token: InjectionToken<any>, args?: unknown) {
     if (!injectState) {
       throw new Error(
-        '[Injector] Trying to access inject outside of a injectable context',
+        '[Injector] Trying to make a request outside of a injectable context',
       )
     }
     if (injectState.isFrozen) {
@@ -113,17 +181,59 @@ export function getInjectors() {
           `[Injector] Wrong token order. Expected ${request.token.toString()} but got ${token.toString()}`,
         )
       }
-      return request.promise
+      return request
     }
-
-    const promise = getFactoryContext().inject(token as any, args as any)
-    injectState.requests.push({
+    let result: any = null
+    let error: Error | null = null
+    const promise = getFactoryContext()
+      .inject(token as any, args as any)
+      .then((r) => {
+        result = r
+        return r
+      })
+      .catch((e) => {
+        // We don't throw here because we have a mechanism to handle errors
+        error = e
+      })
+    const request: InjectRequest = {
       token,
       promise,
-    })
+      get result() {
+        return result
+      },
+      get error() {
+        return error
+      },
+    }
+    injectState.requests.push(request)
     injectState.currentIndex++
 
-    return promise
+    return request
+  }
+
+  function asyncInject(
+    token:
+      | ClassType
+      | InjectionToken<any>
+      | BoundInjectionToken<any, any>
+      | FactoryInjectionToken<any, any>,
+    args?: unknown,
+  ) {
+    if (!injectState) {
+      throw new Error(
+        '[Injector] Trying to access inject outside of a injectable context',
+      )
+    }
+    // @ts-expect-error In case we have a class
+    const realToken = token[InjectableTokenMeta] ?? token
+    const request = getRequest(realToken, args)
+    return request.promise.then((result) => {
+      if (request.error) {
+        // We throw here because we want to fail the asyncInject call if the dependency fails to initialize
+        throw request.error
+      }
+      return result
+    })
   }
 
   function wrapSyncInit(cb: () => any) {
@@ -166,23 +276,33 @@ export function getInjectors() {
     // @ts-expect-error In case we have a class
     const realToken = token[InjectableTokenMeta] ?? token
 
+    if (!injectState) {
+      throw new Error(
+        '[Injector] Trying to access inject outside of a injectable context',
+      )
+    }
+
     const instance = getFactoryContext().locator.getSyncInstance(
       realToken,
       args,
     )
     if (!instance) {
+      const request = getRequest(realToken, args)
+      if (request.error) {
+        throw request.error
+      } else if (request.result) {
+        return request.result
+      }
       if (promiseCollector) {
-        const promise = getFactoryContext().inject(realToken, args)
-        promiseCollector(promise)
-      } else {
-        throw new Error(`[Injector] Cannot initiate ${realToken.toString()}`)
+        promiseCollector(request.promise)
       }
+      // Return a dynamic proxy that looks up the instance when accessed
       return new Proxy(
         {},
         {
           get() {
             throw new Error(
-              `[Injector] Trying to access ${realToken.toString()} before it's initialized, please use asyncInject() instead of inject() or do not use the value outside of class methods`,
+              `[Injector] Trying to access ${realToken.toString()} before it's initialized, please move the code to a onServiceInit method`,
             )
           },
         },
@@ -191,9 +311,26 @@ export function getInjectors() {
     return instance as unknown as T
   }
 
+  function optional<
+    T,
+    Token extends
+      | InjectionToken<T>
+      | BoundInjectionToken<T, any>
+      | FactoryInjectionToken<T, any>,
+    S extends ZodObject | unknown = Token['schema'],
+  >(token: Token, args?: S extends ZodObject ? z.input<S> : never): T | null {
+    try {
+      return inject(token, args)
+    } catch {
+      // If injection fails, return null instead of throwing
+      return null
+    }
+  }
+
   const injectors: Injectors = {
     asyncInject,
     inject,
+    optional,
     wrapSyncInit,
     provideFactoryContext,
   } as Injectors

package/src/utils/index.mts

@@ -1,4 +1,3 @@
 export * from './get-injectors.mjs'
 export * from './get-injectable-token.mjs'
-export * from './defer.mjs'
 export * from './types.mjs'

package/src/utils/types.mts

@@ -37,16 +37,20 @@ export type UnionToArray<T, A extends unknown[] = []> =
     ? UnionToArray<Exclude<T, PopUnion<T>>, [PopUnion<T>, ...A]>
     : [T, ...A]
 
+export type InjectRequest = {
+  token:
+    | InjectionToken<any>
+    | BoundInjectionToken<any, any>
+    | FactoryInjectionToken<any, any>
+    | ClassType
+  promise: Promise<any>
+  readonly result: any
+  readonly error: Error | null
+}
+
 // InjectState interface for managing injection state
 export interface InjectState {
   currentIndex: number
   isFrozen: boolean
-  requests: {
-    token:
-      | InjectionToken<any>
-      | BoundInjectionToken<any, any>
-      | FactoryInjectionToken<any, any>
-      | ClassType
-    promise: Promise<any>
-  }[]
+  requests: InjectRequest[]
 }