@navios/core 0.7.0 → 0.7.1

package/src/navios.application.mts

@@ -6,6 +6,8 @@ import type {
   AbstractHttpAdapterInterface,
   AbstractHttpListenOptions,
   NaviosModule,
+  PluginContext,
+  PluginDefinition,
 } from './interfaces/index.mjs'
 import type { LoggerService, LogLevel } from './logger/index.mjs'
 import type { NaviosEnvironmentOptions } from './navios.environment.mjs'
@@ -22,7 +24,7 @@ import { ModuleLoaderService } from './services/index.mjs'
 export interface NaviosApplicationContextOptions {
   /**
    * Specifies the logger to use. Pass `false` to turn off logging.
-   * 
+   *
    * - `LoggerService` instance: Use a custom logger implementation
    * - `LogLevel[]`: Enable specific log levels (e.g., ['error', 'warn', 'log'])
    * - `false`: Disable logging completely
@@ -40,12 +42,11 @@ export interface NaviosApplicationContextOptions {
  * Complete options for creating a Navios application.
  * Extends NaviosApplicationContextOptions with adapter configuration.
  */
-export interface NaviosApplicationOptions
-  extends NaviosApplicationContextOptions {
+export interface NaviosApplicationOptions extends NaviosApplicationContextOptions {
   /**
    * HTTP adapter environment(s) to use for the application.
    * Can be a single adapter or an array of adapters.
-   * 
+   *
    * @example
    * ```typescript
    * adapter: defineFastifyEnvironment()
@@ -58,16 +59,16 @@ export interface NaviosApplicationOptions
 
 /**
  * Main application class for Navios.
- * 
+ *
  * This class represents a Navios application instance and provides methods
  * for initializing, configuring, and managing the HTTP server.
- * 
+ *
  * @example
  * ```typescript
  * const app = await NaviosFactory.create(AppModule, {
  *   adapter: defineFastifyEnvironment(),
  * })
- * 
+ *
  * app.setGlobalPrefix('/api')
  * app.enableCors({ origin: ['http://localhost:3000'] })
  * await app.init()
@@ -88,6 +89,7 @@ export class NaviosApplication {
   private options: NaviosApplicationOptions = {
     adapter: [],
   }
+  private plugins: PluginDefinition<any>[] = []
 
   /**
    * Indicates whether the application has been initialized.
@@ -98,7 +100,7 @@ export class NaviosApplication {
   /**
    * Sets up the application with the provided module and options.
    * This is called automatically by NaviosFactory.create().
-   * 
+   *
    * @param appModule - The root application module
    * @param options - Application configuration options
    * @internal
@@ -118,26 +120,50 @@ export class NaviosApplication {
 
   /**
    * Gets the dependency injection container used by this application.
-   * 
+   *
    * @returns The Container instance
    */
   getContainer() {
     return this.container
   }
 
+  /**
+   * Registers a plugin to be initialized after modules are loaded.
+   *
+   * Plugins are initialized in the order they are registered,
+   * after all modules are loaded but before the server starts listening.
+   *
+   * @param definition - Plugin definition with options
+   * @returns this for method chaining
+   *
+   * @example
+   * ```typescript
+   * import { defineOpenApiPlugin } from '@navios/openapi-fastify'
+   *
+   * app.usePlugin(defineOpenApiPlugin({
+   *   info: { title: 'My API', version: '1.0.0' },
+   * }))
+   * ```
+   */
+  usePlugin<TOptions>(definition: PluginDefinition<TOptions>): this {
+    this.plugins.push(definition)
+    return this
+  }
+
   /**
    * Initializes the application.
-   * 
+   *
    * This method:
    * - Loads all modules and their dependencies
    * - Sets up the HTTP server if an adapter is configured
    * - Calls onModuleInit hooks on all modules
+   * - Initializes registered plugins
    * - Marks the application as initialized
-   * 
+   *
    * Must be called before `listen()`.
-   * 
+   *
    * @throws Error if app module is not set
-   * 
+   *
    * @example
    * ```typescript
    * const app = await NaviosFactory.create(AppModule, {
@@ -155,6 +181,7 @@ export class NaviosApplication {
     if (this.environment.hasHttpSetup()) {
       await this.httpApplication?.setupHttpServer(this.options)
     }
+    await this.initPlugins()
     await this.initModules()
     if (this.environment.hasHttpSetup()) {
       await this.httpApplication?.ready()
@@ -169,12 +196,35 @@ export class NaviosApplication {
     await this.httpApplication?.onModulesInit(modules)
   }
 
+  private async initPlugins() {
+    if (this.plugins.length === 0) return
+
+    let server: any = null
+    try {
+      server = this.httpApplication?.getServer() ?? null
+    } catch {
+      // ignore
+    }
+    const context: PluginContext = {
+      modules: this.moduleLoader.getAllModules(),
+      server,
+      container: this.container,
+      globalPrefix: this.httpApplication?.getGlobalPrefix() ?? '',
+      moduleLoader: this.moduleLoader,
+    }
+
+    for (const { plugin, options } of this.plugins) {
+      this.logger.debug(`Initializing plugin: ${plugin.name}`)
+      await plugin.register(context, options)
+    }
+  }
+
   /**
    * Enables CORS (Cross-Origin Resource Sharing) for the application.
-   * 
+   *
    * @param options - CORS configuration options (adapter-specific)
    * @throws Error if HTTP application is not set
-   * 
+   *
    * @example
    * ```typescript
    * app.enableCors({
@@ -193,10 +243,10 @@ export class NaviosApplication {
 
   /**
    * Enables multipart/form-data support for file uploads.
-   * 
+   *
    * @param options - Multipart configuration options (adapter-specific)
    * @throws Error if HTTP application is not set
-   * 
+   *
    * @example
    * ```typescript
    * app.enableMultipart({
@@ -215,10 +265,10 @@ export class NaviosApplication {
 
   /**
    * Sets a global prefix for all routes.
-   * 
+   *
    * @param prefix - The prefix to prepend to all route URLs (e.g., '/api')
    * @throws Error if HTTP application is not set
-   * 
+   *
    * @example
    * ```typescript
    * app.setGlobalPrefix('/api/v1')
@@ -234,14 +284,14 @@ export class NaviosApplication {
 
   /**
    * Gets the underlying HTTP server instance.
-   * 
+   *
    * The type of the returned server depends on the adapter used:
    * - Fastify adapter: Returns FastifyInstance
    * - Bun adapter: Returns Bun.Server
-   * 
+   *
    * @returns The HTTP server instance
    * @throws Error if HTTP application is not set
-   * 
+   *
    * @example
    * ```typescript
    * const server = app.getServer()
@@ -257,10 +307,10 @@ export class NaviosApplication {
 
   /**
    * Starts the HTTP server and begins listening for requests.
-   * 
+   *
    * @param options - Listen options (port, host, etc.)
    * @throws Error if HTTP application is not set
-   * 
+   *
    * @example
    * ```typescript
    * await app.listen({ port: 3000, host: '0.0.0.0' })
@@ -275,7 +325,7 @@ export class NaviosApplication {
 
   /**
    * Disposes of application resources.
-   * 
+   *
    * Cleans up the HTTP server and module loader.
    * This method is called automatically by `close()`.
    */
@@ -290,9 +340,9 @@ export class NaviosApplication {
 
   /**
    * Closes the application and cleans up all resources.
-   * 
+   *
    * This is an alias for `dispose()`.
-   * 
+   *
    * @example
    * ```typescript
    * // Graceful shutdown

package/src/navios.factory.mts

@@ -18,21 +18,21 @@ import { NaviosEnvironment } from './navios.environment.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 +40,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 +53,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, {
@@ -119,6 +119,7 @@ export class NaviosFactory {
       loggerInstance?.setup({
         logLevels: logger,
       })
+      return
     }
     if ((logger as boolean) !== true && !isNil(logger)) {
       container

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,