@navios/core 0.7.0 → 0.8.0

package/src/navios.factory.mts

@@ -15,24 +15,26 @@ import type {
 import { ConsoleLogger, isNil, LoggerOutput } from './logger/index.mjs'
 import { NaviosApplication } from './navios.application.mjs'
 import { NaviosEnvironment } from './navios.environment.mjs'
+import { setRequestIdEnabled } from './stores/index.mjs'
+import { NaviosOptionsToken } from './tokens/index.mjs'
 
 /**
  * Factory class for creating and configuring Navios applications.
- * 
+ *
  * This is the main entry point for bootstrapping a Navios application.
  * It handles dependency injection container setup, adapter registration,
  * and logger configuration.
- * 
+ *
  * @example
  * ```typescript
  * import { NaviosFactory } from '@navios/core'
  * import { defineFastifyEnvironment } from '@navios/adapter-fastify'
- * 
+ *
  * const app = await NaviosFactory.create(AppModule, {
  *   adapter: defineFastifyEnvironment(),
  *   logger: ['log', 'error', 'warn'],
  * })
- * 
+ *
  * await app.init()
  * await app.listen({ port: 3000 })
  * ```
@@ -40,10 +42,10 @@ import { NaviosEnvironment } from './navios.environment.mjs'
 export class NaviosFactory {
   /**
    * Creates a new Navios application instance.
-   * 
+   *
    * This method sets up the dependency injection container, registers the HTTP adapter,
    * configures logging, and initializes the application with the provided module.
-   * 
+   *
    * @param appModule - The root application module class decorated with @Module()
    * @param options - Configuration options for the application
    * @param options.adapter - HTTP adapter environment (required for HTTP server functionality)
@@ -53,20 +55,20 @@ export class NaviosFactory {
    *   - `false` to disable logging
    * @param options.container - Optional custom dependency injection container (useful for testing)
    * @returns A configured NaviosApplication instance ready to be initialized
-   * 
+   *
    * @example
    * ```typescript
    * // Basic setup with Fastify adapter
    * const app = await NaviosFactory.create(AppModule, {
    *   adapter: defineFastifyEnvironment(),
    * })
-   * 
+   *
    * // With custom logger configuration
    * const app = await NaviosFactory.create(AppModule, {
    *   adapter: defineFastifyEnvironment(),
    *   logger: ['error', 'warn', 'log'],
    * })
-   * 
+   *
    * // With custom container for testing
    * const container = new Container()
    * const app = await NaviosFactory.create(AppModule, {
@@ -82,6 +84,23 @@ export class NaviosFactory {
     },
   ) {
     const container = options.container ?? new Container()
+
+    // Set request ID flag early, before any adapters are registered
+    if (options.enableRequestId === true) {
+      setRequestIdEnabled(true)
+    }
+
+    // Store options in container for DI access by adapters
+    container
+      .getServiceLocator()
+      .getManager()
+      .storeCreatedHolder(
+        NaviosOptionsToken.toString(),
+        options,
+        InjectableType.Class,
+        InjectableScope.Singleton,
+      )
+
     await this.registerLoggerConfiguration(container, options)
     const adapters = Array.isArray(options.adapter)
       ? options.adapter
@@ -119,6 +138,7 @@ export class NaviosFactory {
       loggerInstance?.setup({
         logLevels: logger,
       })
+      return
     }
     if ((logger as boolean) !== true && !isNil(logger)) {
       container

package/src/services/guard-runner.service.mts

@@ -20,6 +20,11 @@ export class GuardRunnerService {
   private readonly logger = inject(Logger, {
     context: GuardRunnerService.name,
   })
+
+  /**
+   * Runs guards that need to be resolved from a scoped container.
+   * Use this when guards have request-scoped dependencies.
+   */
   async runGuards(
     allGuards: Set<
       | ClassTypeWithInstance<CanActivate>
@@ -28,16 +33,48 @@ export class GuardRunnerService {
     executionContext: AbstractExecutionContext,
     context: ScopedContainer,
   ) {
-    let canActivate = true
-    for (const guard of Array.from(allGuards).reverse()) {
-      const guardInstance = await context.get(
-        guard as InjectionToken<CanActivate, undefined>,
-      )
-      if (!guardInstance.canActivate) {
-        throw new Error(
-          `[Navios] Guard ${guard.name as string} does not implement canActivate()`,
+    // Reverse order: module guards run first, then controller, then endpoint
+    const guardsArray = Array.from(allGuards).reverse()
+
+    // Resolve all guards in parallel
+    const guardInstances = await Promise.all(
+      guardsArray.map(async (guard) => {
+        const guardInstance = await context.get(
+          guard as InjectionToken<CanActivate, undefined>,
         )
-      }
+        if (!guardInstance.canActivate) {
+          throw new Error(
+            `[Navios] Guard ${guard.name as string} does not implement canActivate()`,
+          )
+        }
+        return guardInstance
+      }),
+    )
+
+    return this.executeGuards(guardInstances, executionContext)
+  }
+
+  /**
+   * Runs pre-resolved guard instances.
+   * Use this when all guards are singletons and have been pre-resolved at startup.
+   */
+  async runGuardsStatic(
+    guardInstances: CanActivate[],
+    executionContext: AbstractExecutionContext,
+  ) {
+    return this.executeGuards(guardInstances, executionContext)
+  }
+
+  /**
+   * Shared guard execution logic.
+   * Iterates through guard instances and calls canActivate on each.
+   */
+  private async executeGuards(
+    guardInstances: CanActivate[],
+    executionContext: AbstractExecutionContext,
+  ): Promise<boolean> {
+    let canActivate = true
+    for (const guardInstance of guardInstances) {
       try {
         canActivate = await guardInstance.canActivate(executionContext)
         if (!canActivate) {

package/src/services/index.mts

@@ -1,2 +1,3 @@
+export * from './instance-resolver.service.mjs'
 export * from './guard-runner.service.mjs'
 export * from './module-loader.service.mjs'

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

@@ -0,0 +1,186 @@
+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,4 +1,4 @@
-import type { ClassTypeWithInstance } from '@navios/di'
+import type { ClassType, ClassTypeWithInstance } from '@navios/di'
 
 import { Container, inject, Injectable } from '@navios/di'
 
@@ -8,6 +8,30 @@ import type { ModuleMetadata } from '../metadata/index.mjs'
 import { Logger } from '../logger/index.mjs'
 import { extractModuleMetadata } from '../metadata/index.mjs'
 
+/**
+ * Extension definition for dynamically adding to the module tree.
+ * Used by plugins to inject controllers or entire modules.
+ */
+export interface ModuleExtension {
+  /**
+   * Module class to add. If provided, the module and all its
+   * controllers/imports will be processed.
+   */
+  module?: ClassTypeWithInstance<NaviosModule>
+
+  /**
+   * Controllers to add directly without a wrapper module.
+   * Will be registered under a synthetic module named after the plugin.
+   */
+  controllers?: ClassType[]
+
+  /**
+   * Name for the synthetic module when using controllers directly.
+   * Required if `controllers` is provided without `module`.
+   */
+  moduleName?: string
+}
+
 @Injectable()
 export class ModuleLoaderService {
   private logger = inject(Logger, {
@@ -26,6 +50,83 @@ export class ModuleLoaderService {
     this.initialized = true
   }
 
+  /**
+   * Extends the module tree with additional modules or controllers.
+   *
+   * This method is designed to be called by plugins during registration,
+   * which happens after initial module loading but before route registration.
+   *
+   * @param extensions - Array of module extensions to add
+   * @throws Error if not initialized (loadModules must be called first)
+   *
+   * @example
+   * ```typescript
+   * // In plugin registration
+   * const moduleLoader = await context.container.get(ModuleLoaderService)
+   * await moduleLoader.extendModules([{
+   *   controllers: [OpenApiJsonController, OpenApiYamlController],
+   *   moduleName: 'OpenApiBunModule',
+   * }])
+   * ```
+   */
+  async extendModules(extensions: ModuleExtension[]): Promise<void> {
+    if (!this.initialized) {
+      throw new Error(
+        'ModuleLoaderService must be initialized before extending. Call loadModules() first.',
+      )
+    }
+
+    for (const extension of extensions) {
+      if (extension.module) {
+        // Process a full module with its imports and controllers
+        await this.traverseModules(extension.module)
+      } else if (extension.controllers && extension.moduleName) {
+        // Create synthetic module metadata for loose controllers
+        await this.registerControllers(
+          extension.controllers,
+          extension.moduleName,
+        )
+      } else if (extension.controllers) {
+        throw new Error(
+          'moduleName is required when providing controllers without a module',
+        )
+      }
+    }
+  }
+
+  /**
+   * Registers controllers under a synthetic module.
+   * Used when plugins want to add controllers without a full module class.
+   */
+  private async registerControllers(
+    controllers: ClassType[],
+    moduleName: string,
+  ): Promise<void> {
+    if (this.modulesMetadata.has(moduleName)) {
+      // Merge controllers into existing module
+      const existing = this.modulesMetadata.get(moduleName)!
+      for (const controller of controllers) {
+        existing.controllers.add(controller)
+      }
+      this.logger.debug(
+        `Extended module ${moduleName} with ${controllers.length} controllers`,
+      )
+    } else {
+      // Create new synthetic module metadata
+      const metadata: ModuleMetadata = {
+        controllers: new Set(controllers),
+        imports: new Set(),
+        guards: new Set(),
+        customAttributes: new Map(),
+      }
+      this.modulesMetadata.set(moduleName, metadata)
+
+      this.logger.debug(
+        `Created module ${moduleName} with ${controllers.length} controllers`,
+      )
+    }
+  }
+
   private async traverseModules(
     module: ClassTypeWithInstance<NaviosModule>,
     parentMetadata?: ModuleMetadata,

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/tokens/index.mts

@@ -2,6 +2,7 @@ export * from './endpoint-adapter.token.mjs'
 export * from './execution-context.token.mjs'
 export * from './http-adapter.token.mjs'
 export * from './multipart-adapter.token.mjs'
+export * from './navios-options.token.mjs'
 export * from './reply.token.mjs'
 export * from './request.token.mjs'
 export * from './stream-adapter.token.mjs'

package/src/tokens/navios-options.token.mts

@@ -0,0 +1,6 @@
+import { InjectionToken } from '@navios/di'
+
+import type { NaviosApplicationOptions } from '../navios.application.mjs'
+
+export const NaviosOptionsToken =
+  InjectionToken.create<NaviosApplicationOptions>('NaviosOptionsToken')