@navios/core 0.6.0 → 0.7.1

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,
@@ -38,18 +139,23 @@ export class ModuleLoaderService {
     if (this.modulesMetadata.has(moduleName)) {
       return
     }
-    this.modulesMetadata.set(moduleName, metadata)
-    const imports = metadata.imports ?? new Set()
-    const loadingPromises = Array.from(imports).map(async (importedModule) =>
-      this.traverseModules(importedModule, metadata),
-    )
-    await Promise.all(loadingPromises)
-    const instance = await this.container.get(module)
-    if (instance.onModuleInit) {
-      await instance.onModuleInit()
+    try {
+      this.modulesMetadata.set(moduleName, metadata)
+      const imports = metadata.imports ?? new Set()
+      const loadingPromises = Array.from(imports).map(async (importedModule) =>
+        this.traverseModules(importedModule, metadata),
+      )
+      await Promise.all(loadingPromises)
+      const instance = await this.container.get(module)
+      if (instance.onModuleInit) {
+        await instance.onModuleInit()
+      }
+      this.logger.debug(`Module ${moduleName} loaded`)
+      this.loadedModules.set(moduleName, instance)
+    } catch (error) {
+      this.logger.error(`Error loading module ${moduleName}`, error)
+      throw error
     }
-    this.logger.debug(`Module ${moduleName} loaded`)
-    this.loadedModules.set(moduleName, instance)
   }
 
   private mergeMetadata(

package/src/stores/index.mts

@@ -0,0 +1 @@
+export * from './request-id.store.mjs'

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

@@ -0,0 +1,43 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+
+/**
+ * AsyncLocalStorage store for the current request ID.
+ *
+ * This allows logging and other services to access the current request ID
+ * without explicitly passing it through the call stack.
+ *
+ * @example
+ * ```typescript
+ * import { requestIdStore, runWithRequestId, getRequestId } from '@navios/core'
+ *
+ * // Run code with a request ID in context
+ * runWithRequestId('req-123', () => {
+ *   // Inside this callback, getRequestId() returns 'req-123'
+ *   logger.log('Processing request') // Will include request ID if logger is configured
+ * })
+ *
+ * // Get current request ID (returns undefined if not in a request context)
+ * const currentId = getRequestId()
+ * ```
+ */
+export const requestIdStore = new AsyncLocalStorage<string>()
+
+/**
+ * Runs a function with a request ID in the async local storage context.
+ *
+ * @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)
+}
+
+/**
+ * Gets the current request ID from the async local storage context.
+ *
+ * @returns The current request ID, or undefined if not in a request context
+ */
+export function getRequestId(): string | undefined {
+  return requestIdStore.getStore()
+}

package/src/testing/index.mts

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

package/src/testing/testing-module.mts

@@ -0,0 +1,231 @@
+import type { ClassType, ClassTypeWithInstance, InjectionToken } from '@navios/di'
+import type { NaviosModule } from '../interfaces/index.mjs'
+import type { NaviosApplicationOptions } from '../navios.application.mjs'
+
+import { TestContainer } from '@navios/di/testing'
+
+import { NaviosApplication } from '../navios.application.mjs'
+import { NaviosFactory } from '../navios.factory.mjs'
+
+/**
+ * Configuration for overriding a provider in the testing module.
+ * 
+ * @typeParam T - The type of the provider being overridden
+ */
+export interface TestingModuleOverride<T = any> {
+  /**
+   * The injection token or class to override.
+   */
+  token: ClassType | InjectionToken<T, any>
+  /**
+   * Value to use instead of the original provider.
+   */
+  useValue?: T
+  /**
+   * Class to use instead of the original provider.
+   */
+  useClass?: ClassType
+}
+
+/**
+ * Options for creating a testing module.
+ * 
+ * Extends NaviosApplicationOptions but excludes the container option,
+ * as TestingModule manages its own TestContainer.
+ */
+export interface TestingModuleOptions
+  extends Omit<NaviosApplicationOptions, 'container'> {
+  /**
+   * Initial provider overrides to apply when creating the testing module.
+   * 
+   * You can also use `overrideProvider()` method for a fluent API.
+   */
+  overrides?: TestingModuleOverride[]
+}
+
+/**
+ * A testing-optimized wrapper around NaviosApplication.
+ * Provides utilities for setting up test environments with mock dependencies.
+ */
+export class TestingModule {
+  private app: NaviosApplication | null = null
+
+  constructor(
+    private readonly appModule: ClassTypeWithInstance<NaviosModule>,
+    private readonly container: TestContainer,
+    private readonly options: TestingModuleOptions,
+  ) {}
+
+  /**
+   * Compiles the testing module and returns the NaviosApplication.
+   * Call this after setting up all overrides.
+   */
+  async compile(): Promise<NaviosApplication> {
+    this.app = await NaviosFactory.create(this.appModule, {
+      ...this.options,
+      container: this.container,
+    })
+    return this.app
+  }
+
+  /**
+   * Initializes the application (loads modules, sets up HTTP if configured).
+   * This is equivalent to calling app.init() on the compiled application.
+   */
+  async init(): Promise<NaviosApplication> {
+    if (!this.app) {
+      await this.compile()
+    }
+    await this.app!.init()
+    return this.app!
+  }
+
+  /**
+   * Gets the underlying TestContainer for direct manipulation.
+   */
+  getContainer(): TestContainer {
+    return this.container
+  }
+
+  /**
+   * Gets the compiled application. Throws if not yet compiled.
+   */
+  getApplication(): NaviosApplication {
+    if (!this.app) {
+      throw new Error(
+        'TestingModule not compiled. Call compile() or init() first.',
+      )
+    }
+    return this.app
+  }
+
+  /**
+   * Override a provider with a mock value.
+   */
+  overrideProvider<T>(token: ClassType | InjectionToken<T, any>): {
+    useValue: (value: T) => TestingModule
+    useClass: (target: ClassType) => TestingModule
+  } {
+    return {
+      useValue: (value: T) => {
+        this.container.bind(token as any).toValue(value)
+        return this
+      },
+      useClass: (target: ClassType) => {
+        this.container.bind(token as any).toClass(target)
+        return this
+      },
+    }
+  }
+
+  /**
+   * Gets an instance from the container.
+   */
+  async get<T>(token: ClassTypeWithInstance<T> | InjectionToken<T, any>): Promise<T> {
+    return this.container.get(token as any)
+  }
+
+  /**
+   * Disposes the testing module and cleans up resources.
+   */
+  async close(): Promise<void> {
+    if (this.app) {
+      await this.app.close()
+    }
+    await this.container.dispose()
+  }
+}
+
+/**
+ * Fluent builder interface for TestingModule.
+ * 
+ * Provides a chainable API for configuring and using a testing module.
+ */
+export interface TestingModuleBuilder {
+  /**
+   * Override a provider with a mock value or class.
+   * 
+   * @param token - The injection token or class to override
+   * @returns An object with `useValue` and `useClass` methods for chaining
+   * 
+   * @example
+   * ```typescript
+   * const testingModule = await createTestingModule(AppModule)
+   *   .overrideProvider(DatabaseService)
+   *   .useValue(mockDatabaseService)
+   *   .compile()
+   * ```
+   */
+  overrideProvider<T>(token: ClassType | InjectionToken<T, any>): {
+    useValue: (value: T) => TestingModuleBuilder
+    useClass: (target: ClassType) => TestingModuleBuilder
+  }
+
+  /**
+   * Compiles the testing module and returns the NaviosApplication.
+   * 
+   * This creates the application instance but does not initialize it.
+   * Call `init()` if you need the application to be fully initialized.
+   */
+  compile(): Promise<NaviosApplication>
+
+  /**
+   * Initializes the application (loads modules, sets up HTTP if configured).
+   * 
+   * This is equivalent to calling `compile()` followed by `app.init()`.
+   */
+  init(): Promise<NaviosApplication>
+
+  /**
+   * Gets the underlying TestContainer for direct manipulation.
+   */
+  getContainer(): TestContainer
+
+  /**
+   * Gets an instance from the container.
+   * 
+   * @typeParam T - The type of the instance to retrieve
+   * @param token - The injection token or class
+   * @returns The resolved instance
+   */
+  get<T>(token: ClassTypeWithInstance<T> | InjectionToken<T, any>): Promise<T>
+
+  /**
+   * Disposes the testing module and cleans up resources.
+   */
+  close(): Promise<void>
+}
+
+/**
+ * Creates a testing module for the given app module.
+ * This is the main entry point for setting up tests.
+ *
+ * @example
+ * ```typescript
+ * const testingModule = await createTestingModule(AppModule, {
+ *   adapter: [],
+ * })
+ *   .overrideProvider(DatabaseService)
+ *   .useValue(mockDatabaseService)
+ *   .compile()
+ * ```
+ */
+export function createTestingModule(
+  appModule: ClassTypeWithInstance<NaviosModule>,
+  options: TestingModuleOptions = { adapter: [] },
+): TestingModule {
+  const container = new TestContainer()
+
+  // Apply initial overrides if provided
+  if (options.overrides) {
+    for (const override of options.overrides) {
+      if (override.useValue !== undefined) {
+        container.bind(override.token as any).toValue(override.useValue)
+      } else if (override.useClass) {
+        container.bind(override.token as any).toClass(override.useClass)
+      }
+    }
+  }
+
+  return new TestingModule(appModule, container, options)
+}

package/tsconfig.lib.json

@@ -4,5 +4,5 @@
     "outDir": "./dist"
   },
   "include": ["src/**/*"],
-  "exclude": ["src/**/*.spec.mts"]
+  "exclude": ["src/**/*.spec.mts", "src/**/*.spec-d.mts"]
 }

package/tsconfig.spec.json

@@ -7,6 +7,9 @@
   "references": [
     {
       "path": "./tsconfig.lib.json"
+    },
+    {
+      "path": "./src/legacy-compat/__type-tests__/tsconfig.json"
     }
   ]
 }

package/tsdown.config.mts

@@ -0,0 +1,35 @@
+import { withFilter } from 'rolldown/filter'
+import { defineConfig } from 'tsdown'
+import swc from 'unplugin-swc'
+
+export default defineConfig({
+  entry: ['src/index.mts', 'src/testing/index.mts', 'src/legacy-compat/index.mts'],
+  outDir: 'lib',
+  format: ['esm', 'cjs'],
+  clean: true,
+  tsconfig: 'tsconfig.lib.json',
+  treeshake: true,
+  sourcemap: true,
+  platform: 'node',
+  external: ['@navios/di'],
+  dts: true,
+  target: 'es2022',
+  plugins: [
+    withFilter(
+      swc.rolldown({
+        jsc: {
+          target: 'es2022',
+          parser: {
+            syntax: 'typescript',
+            decorators: true,
+          },
+          transform: {
+            decoratorVersion: '2022-03',
+          },
+        },
+      }),
+      // Only run this transform if the file contains a decorator.
+      { transform: { code: '@' } },
+    ),
+  ],
+})

package/vitest.config.mts

@@ -4,6 +4,12 @@ export default defineProject({
   test: {
     typecheck: {
       enabled: true,
+      tsconfig: './tsconfig.lib.json',
     },
+    include: [
+      'src/**/*.spec.mts',
+      'src/**/*.spec-d.mts',
+      'src/legacy-compat/__type-tests__/**/*.spec-d.mts',
+    ],
   },
 })