@navios/core 0.7.1 → 0.9.0

package/src/services/instance-resolver.service.mts

@@ -0,0 +1,187 @@
+import type { ClassType, ScopedContainer } from '@navios/di'
+
+import {
+  Container,
+  getInjectableToken,
+  inject,
+  Injectable,
+  InjectableScope,
+} from '@navios/di'
+
+/**
+ * Result of instance resolution attempt.
+ * Contains either a cached singleton instance or a resolver function
+ * that can be used to get a fresh instance per request.
+ */
+export interface InstanceResolution<T = any> {
+  /**
+   * Whether the instance was successfully cached as a singleton.
+   * If true, `instance` contains the cached instance.
+   * If false, the class has request-scoped dependencies and
+   * must be resolved per-request using `resolve()`.
+   */
+  cached: boolean
+
+  /**
+   * The cached instance (only available if `cached` is true).
+   */
+  instance: T | null
+
+  /**
+   * Resolves the instance from a scoped container.
+   * Use this when `cached` is false to get a fresh instance per request.
+   */
+  resolve: (scoped: ScopedContainer) => Promise<T>
+}
+
+/**
+ * Result of resolving multiple instances.
+ * Contains either all cached singleton instances or a resolver function.
+ */
+export interface MultiInstanceResolution<T = any> {
+  /**
+   * Whether ALL instances were successfully cached as singletons.
+   * If true, `instances` contains all cached instances.
+   * If false, at least one class has request-scoped dependencies.
+   */
+  cached: boolean
+
+  /**
+   * The cached instances (only available if `cached` is true).
+   * Order matches the input array order.
+   */
+  instances: T[] | null
+
+  /**
+   * The original class types for dynamic resolution.
+   */
+  classTypes: ClassType[]
+
+  /**
+   * Resolves all instances from a scoped container.
+   * Use this when `cached` is false to get fresh instances per request.
+   */
+  resolve: (scoped: ScopedContainer) => Promise<T[]>
+}
+
+/**
+ * Service responsible for resolving class instances with automatic scope detection.
+ *
+ * This service attempts to resolve classes as singletons from the root container.
+ * If resolution fails (because the class has request-scoped dependencies),
+ * it automatically updates the class's scope to Request and provides a
+ * resolver function for per-request instantiation.
+ *
+ * This enables optimal performance:
+ * - Classes without request-scoped deps stay as singletons (faster)
+ * - Classes with request-scoped deps are automatically promoted to request scope
+ *
+ * @example
+ * ```ts
+ * const resolution = await instanceResolver.resolve(UserController)
+ *
+ * if (resolution.cached) {
+ *   // Use cached singleton
+ *   return resolution.instance.handleRequest(req)
+ * } else {
+ *   // Resolve per request
+ *   const controller = await resolution.resolve(scopedContainer)
+ *   return controller.handleRequest(req)
+ * }
+ * ```
+ */
+@Injectable()
+export class InstanceResolverService {
+  private container = inject(Container)
+
+  /**
+   * Attempts to resolve a class instance, automatically detecting if it needs
+   * request scope based on its dependencies.
+   *
+   * @param classType - The class to resolve
+   * @returns A resolution result containing either a cached instance or resolver function
+   */
+  async resolve<T>(classType: ClassType): Promise<InstanceResolution<T>> {
+    let cachedInstance: T | null = null
+
+    try {
+      cachedInstance = await this.container.get(classType)
+    } catch {
+      // Class has request-scoped dependencies, update its scope to Request
+      // so it will be resolved per-request from the scoped container
+      const token = getInjectableToken(classType)
+      this.container.getRegistry().updateScope(token, InjectableScope.Request)
+    }
+
+    return {
+      cached: cachedInstance !== null,
+      instance: cachedInstance,
+      resolve: (scoped: ScopedContainer) => scoped.get(classType) as Promise<T>,
+    }
+  }
+
+  /**
+   * Attempts to resolve multiple class instances, automatically detecting if any need
+   * request scope based on their dependencies.
+   *
+   * Returns `cached: true` only if ALL classes can be resolved as singletons.
+   * If any class has request-scoped dependencies, returns `cached: false`.
+   *
+   * @param classTypes - The classes to resolve
+   * @returns A resolution result containing either all cached instances or resolver function
+   */
+  async resolveMany<T>(
+    classTypes: ClassType[],
+  ): Promise<MultiInstanceResolution<T>> {
+    if (classTypes.length === 0) {
+      return {
+        cached: true,
+        instances: [],
+        classTypes: [],
+        resolve: async () => [],
+      }
+    }
+
+    // Resolve all classes in parallel
+    const results = await Promise.all(
+      classTypes.map(async (classType) => {
+        try {
+          const instance = await this.container.get(classType)
+          return { success: true, instance: instance as T }
+        } catch {
+          // Class has request-scoped dependencies, update its scope to Request
+          const token = getInjectableToken(classType)
+          this.container
+            .getRegistry()
+            .updateScope(token, InjectableScope.Request)
+          return { success: false, instance: null }
+        }
+      }),
+    )
+
+    const allCached = results.every((r) => r.success)
+    const cachedInstances = allCached
+      ? results.map((r) => r.instance as T)
+      : null
+
+    return {
+      cached: allCached,
+      instances: cachedInstances,
+      classTypes,
+      resolve: (scoped: ScopedContainer) =>
+        Promise.all(
+          classTypes.map((classType) => scoped.get(classType) as Promise<T>),
+        ),
+    }
+  }
+}
+
+/**
+ * @deprecated Use InstanceResolverService instead
+ */
+export const ControllerResolverService = InstanceResolverService
+
+/**
+ * @deprecated Use InstanceResolution instead
+ */
+export type ControllerResolution<T = any> = InstanceResolution<T>

package/src/services/module-loader.service.mts

@@ -1,6 +1,6 @@
 import type { ClassType, ClassTypeWithInstance } from '@navios/di'
 
-import { Container, inject, Injectable } from '@navios/di'
+import { Container, getInjectableToken, inject, Injectable } from '@navios/di'
 
 import type { NaviosModule } from '../interfaces/index.mjs'
 import type { ModuleMetadata } from '../metadata/index.mjs'
@@ -135,7 +135,8 @@ export class ModuleLoaderService {
     if (parentMetadata) {
       this.mergeMetadata(metadata, parentMetadata)
     }
-    const moduleName = module.name
+    const moduleToken = getInjectableToken(module)
+    const moduleName = moduleToken.id
     if (this.modulesMetadata.has(moduleName)) {
       return
     }

package/src/stores/request-id.store.mts

@@ -1,5 +1,17 @@
 import { AsyncLocalStorage } from 'node:async_hooks'
 
+let requestCounter = 0
+
+/**
+ * Generates a simple incremental request ID.
+ * Much faster than crypto.randomUUID() and sufficient for request tracking.
+ *
+ * @returns A unique request ID string (e.g., "req-1", "req-2", ...)
+ */
+export function generateRequestId(): string {
+  return `req-${++requestCounter}`
+}
+
 /**
  * AsyncLocalStorage store for the current request ID.
  *
@@ -20,17 +32,44 @@ import { AsyncLocalStorage } from 'node:async_hooks'
  * const currentId = getRequestId()
  * ```
  */
-export const requestIdStore = new AsyncLocalStorage<string>()
+let requestIdStore: AsyncLocalStorage<string> | null = null
+
+function getRequestIdStore(): AsyncLocalStorage<string> {
+  if (!requestIdStore) {
+    requestIdStore = new AsyncLocalStorage<string>()
+  }
+  return requestIdStore!
+}
+/**
+ * Whether request ID propagation is enabled.
+ * When disabled, runWithRequestId is a pass-through for better performance.
+ */
+let requestIdEnabled = false
+
+/**
+ * Enables or disables request ID propagation.
+ * Called by NaviosFactory based on the enableRequestId option.
+ *
+ * @param enabled - Whether to enable request ID propagation
+ */
+export function setRequestIdEnabled(enabled: boolean): void {
+  requestIdEnabled = enabled
+}
 
 /**
  * Runs a function with a request ID in the async local storage context.
+ * If request ID propagation is disabled, the function is called directly
+ * without AsyncLocalStorage overhead.
  *
  * @param requestId - The request ID to set for this context
  * @param fn - The function to run within this context
  * @returns The return value of the function
  */
 export function runWithRequestId<R>(requestId: string, fn: () => R): R {
-  return requestIdStore.run(requestId, fn)
+  if (!requestIdEnabled) {
+    return fn()
+  }
+  return getRequestIdStore().run(requestId, fn)
 }
 
 /**
@@ -39,5 +78,8 @@ export function runWithRequestId<R>(requestId: string, fn: () => R): R {
  * @returns The current request ID, or undefined if not in a request context
  */
 export function getRequestId(): string | undefined {
-  return requestIdStore.getStore()
+  if (!requestIdEnabled) {
+    return undefined
+  }
+  return getRequestIdStore().getStore()
 }

package/src/testing/index.mts

@@ -1,2 +1,3 @@
 export * from '@navios/di/testing'
 export * from './testing-module.mjs'
+export * from './unit-testing-module.mjs'