@navios/core 1.0.0 → 1.1.0

package/src/navios.application.mts

@@ -19,15 +19,25 @@ import {
 import type {
   AbstractAdapterInterface,
   AdapterEnvironment,
+  AnyPluginDefinition,
+  ContainerOnlyContext,
   DefaultAdapterEnvironment,
+  FullPluginContext,
   HttpAdapterEnvironment,
+  ModulesLoadedContext,
   NaviosModule,
-  PluginContext,
-  PluginDefinition,
+  PluginStage,
 } from './interfaces/index.mjs'
 import type { LoggerService, LogLevel } from './logger/index.mjs'
 import type { NaviosEnvironmentOptions } from './navios.environment.mjs'
 
+import {
+  PLUGIN_STAGES_ORDER,
+  PluginStageBase,
+  PluginStages,
+  postStage,
+  preStage,
+} from './interfaces/index.mjs'
 import { Logger } from './logger/index.mjs'
 import { NaviosEnvironment } from './navios.environment.mjs'
 import { ModuleLoaderService } from './services/index.mjs'
@@ -122,7 +132,23 @@ export class NaviosApplication<
   private options: NaviosApplicationOptions = {
     adapter: [],
   }
-  private plugins: PluginDefinition<any, any>[] = []
+
+  /**
+   * Plugin storage organized by stage for efficient execution.
+   * Each stage has a Set of plugin definitions.
+   */
+  private plugins: Map<PluginStage, Set<AnyPluginDefinition>> = new Map(
+    PLUGIN_STAGES_ORDER.map((stage) => [stage, new Set()]),
+  )
+
+  /**
+   * Queue of adapter configuration methods to apply after adapter resolution.
+   * Allows calling methods like enableCors() before init().
+   */
+  private pendingAdapterCalls: Array<{
+    method: string
+    args: unknown[]
+  }> = []
 
   /**
    * Indicates whether the application has been initialized.
@@ -134,6 +160,9 @@ export class NaviosApplication<
    * Sets up the application with the provided module and options.
    * This is called automatically by NaviosFactory.create().
    *
+   * Note: Adapter resolution has been moved to init() to allow
+   * plugins to modify the container/registry before adapter instantiation.
+   *
    * @param appModule - The root application module
    * @param options - Application configuration options
    * @internal
@@ -146,11 +175,7 @@ export class NaviosApplication<
   ) {
     this.appModule = appModule
     this.options = options
-    if (this.environment.hasAdapterSetup()) {
-      this.adapter = (await this.container.get(
-        AdapterToken,
-      )) as Environment['adapter']
-    }
+    // Note: Adapter resolution moved to init() for plugin hooks
   }
 
   /**
@@ -176,39 +201,79 @@ export class NaviosApplication<
   }
 
   /**
-   * Registers a plugin to be initialized after modules are loaded.
+   * Registers one or more plugins for initialization during the application lifecycle.
    *
-   * Plugins are initialized in the order they are registered,
-   * after all modules are loaded but before the server starts listening.
+   * Plugins can target specific stages or use the legacy interface (defaults to post:modules-init).
+   * Plugins are executed in stage order, and within a stage in registration order.
    *
-   * @param definition - Plugin definition with options
+   * @param definitions - Single plugin definition or array of definitions
    * @returns this for method chaining
    *
    * @example
    * ```typescript
-   * import { defineOpenApiPlugin } from '@navios/openapi-fastify'
-   *
-   * app.usePlugin(defineOpenApiPlugin({
-   *   info: { title: 'My API', version: '1.0.0' },
-   * }))
+   * // Single plugin (legacy or staged)
+   * app.usePlugin(defineOpenApiPlugin({ info: { title: 'My API', version: '1.0.0' } }))
+   *
+   * // Multiple plugins in one call
+   * app.usePlugin([
+   *   defineOtelPlugin({ serviceName: 'my-service' }),
+   *   defineOpenApiPlugin({ info: { title: 'My API', version: '1.0.0' } }),
+   * ])
+   *
+   * // Staged plugin with explicit stage
+   * app.usePlugin(definePreAdapterResolvePlugin({
+   *   name: 'early-setup',
+   *   register: (ctx) => { ... },
+   * })({}))
    * ```
    */
   usePlugin<TOptions, TAdapter extends AbstractAdapterInterface>(
-    definition: PluginDefinition<TOptions, TAdapter>,
+    definitions:
+      | AnyPluginDefinition<TOptions, TAdapter>
+      | AnyPluginDefinition<TOptions, TAdapter>[],
   ): this {
-    this.plugins.push(definition)
+    const definitionsArray = Array.isArray(definitions)
+      ? definitions
+      : [definitions]
+
+    for (const definition of definitionsArray) {
+      const stage = this.resolvePluginStage(definition)
+      const stageSet = this.plugins.get(stage)
+
+      if (!stageSet) {
+        throw new Error(`Unknown plugin stage: ${stage}`)
+      }
+
+      stageSet.add(definition as AnyPluginDefinition)
+      this.logger.debug(
+        `Registered plugin "${definition.plugin.name}" for stage: ${stage}`,
+      )
+    }
+
     return this
   }
 
+  /**
+   * Resolves the stage for a plugin definition.
+   * Staged plugins use their explicit stage, legacy plugins default to post:modules-init.
+   */
+  private resolvePluginStage(definition: AnyPluginDefinition): PluginStage {
+    if ('stage' in definition.plugin) {
+      return definition.plugin.stage
+    }
+    // Legacy plugins default to post:modules-init for backward compatibility
+    return PluginStages.POST_MODULES_INIT
+  }
+
   /**
    * Initializes the application.
    *
-   * This method:
-   * - Loads all modules and their dependencies
-   * - Sets up the adapter if one is configured
-   * - Calls onModuleInit hooks on all modules
-   * - Initializes registered plugins
-   * - Marks the application as initialized
+   * This method executes the following lifecycle stages:
+   * 1. pre:modules-traverse → Load modules → post:modules-traverse
+   * 2. pre:adapter-resolve → Resolve adapter → post:adapter-resolve
+   * 3. pre:adapter-setup → Setup adapter → post:adapter-setup
+   * 4. pre:modules-init → Initialize modules → post:modules-init
+   * 5. pre:ready → Ready signal → post:ready
    *
    * Must be called before `listen()`.
    *
@@ -227,48 +292,161 @@ export class NaviosApplication<
     if (!this.appModule) {
       throw new Error('App module is not set. Call setAppModule() first.')
     }
-    await this.moduleLoader.loadModules(this.appModule)
 
-    if (this.environment.hasAdapterSetup() && this.adapter) {
-      await this.adapter.setupAdapter(this.options)
+    // Stage 1: Load modules
+    await this.wrapStage(PluginStageBase.MODULES_TRAVERSE, () =>
+      this.moduleLoader.loadModules(this.appModule!),
+    )
+
+    // Stage 2: Resolve adapter (moved from setup())
+    // Note: If no adapter configured, adapter stages are silently skipped
+    if (this.environment.hasAdapterSetup()) {
+      await this.wrapStage(PluginStageBase.ADAPTER_RESOLVE, async () => {
+        this.adapter = (await this.container.get(
+          AdapterToken,
+        )) as Environment['adapter']
+        // Apply any configuration calls that were queued before adapter resolution
+        this.applyPendingAdapterCalls()
+      })
+
+      // Stage 3: Setup adapter
+      if (this.adapter) {
+        await this.wrapStage(PluginStageBase.ADAPTER_SETUP, () =>
+          this.adapter!.setupAdapter(this.options),
+        )
+      }
     }
 
-    await this.initPlugins()
-    await this.initModules()
+    // Stage 4: Initialize modules (always runs)
+    await this.wrapStage(PluginStageBase.MODULES_INIT, () => this.initModules())
 
+    // Stage 5: Ready signal
     if (this.adapter) {
-      await this.adapter.ready()
+      await this.wrapStage(PluginStageBase.READY, () => this.adapter!.ready())
     }
 
     this.isInitialized = true
     this.logger.debug('Navios application initialized')
   }
 
-  private async initModules() {
-    const modules = this.moduleLoader.getAllModules()
-    if (this.adapter) {
-      await this.adapter.onModulesInit(modules)
+  /**
+   * Wraps an operation with pre/post plugin stage execution.
+   *
+   * @param baseName - The base stage name (e.g., 'modules-traverse')
+   * @param operation - The operation to execute between pre/post stages
+   */
+  private async wrapStage<T>(
+    baseName: PluginStageBase,
+    operation: () => Promise<T> | T,
+  ): Promise<T> {
+    await this.executePluginStage(preStage(baseName))
+    const result = await operation()
+    await this.executePluginStage(postStage(baseName))
+    return result
+  }
+
+  /**
+   * Executes all plugins registered for a specific stage.
+   *
+   * @param stage - The lifecycle stage to execute plugins for
+   */
+  private async executePluginStage(stage: PluginStage): Promise<void> {
+    const stagePlugins = this.plugins.get(stage)
+
+    if (!stagePlugins || stagePlugins.size === 0) {
+      return
+    }
+
+    const context = this.buildContextForStage(stage)
+
+    this.logger.debug(
+      `Executing ${stagePlugins.size} plugin(s) for stage: ${stage}`,
+    )
+
+    for (const { plugin, options } of stagePlugins) {
+      this.logger.debug(`Executing plugin: ${plugin.name} (stage: ${stage})`)
+
+      try {
+        await plugin.register(context as never, options)
+      } catch (error) {
+        this.logger.error(
+          `Plugin "${plugin.name}" failed at stage "${stage}"`,
+          error,
+        )
+        throw error
+      }
     }
   }
 
-  private async initPlugins() {
-    if (this.plugins.length === 0) return
+  /**
+   * Builds the appropriate context object for a given stage.
+   *
+   * @param stage - The lifecycle stage
+   * @returns Context object with stage-appropriate properties
+   */
+  private buildContextForStage(
+    stage: PluginStage,
+  ): ContainerOnlyContext | ModulesLoadedContext | FullPluginContext {
+    const baseContext: ContainerOnlyContext = {
+      container: this.container,
+    }
 
-    if (!this.adapter) {
-      throw new Error('Cannot initialize plugins without an adapter')
+    if (stage === PluginStages.PRE_MODULES_TRAVERSE) {
+      return baseContext
     }
 
-    const context: PluginContext = {
+    const modulesContext: ModulesLoadedContext = {
+      ...baseContext,
       modules: this.moduleLoader.getAllModules(),
-      adapter: this.adapter,
-      container: this.container,
       moduleLoader: this.moduleLoader,
     }
 
-    for (const { plugin, options } of this.plugins) {
-      this.logger.debug(`Initializing plugin: ${plugin.name}`)
-      await plugin.register(context, options)
+    const isPreAdapterStage =
+      stage === PluginStages.POST_MODULES_TRAVERSE ||
+      stage === PluginStages.PRE_ADAPTER_RESOLVE
+
+    if (isPreAdapterStage) {
+      return modulesContext
+    }
+
+    if (!this.adapter) {
+      throw new Error(`Cannot execute stage "${stage}" without adapter`)
+    }
+
+    return {
+      ...modulesContext,
+      adapter: this.adapter,
+    } as FullPluginContext
+  }
+
+  private async initModules() {
+    const modules = this.moduleLoader.getAllModules()
+    if (this.adapter) {
+      await this.adapter.onModulesInit(modules)
+    }
+  }
+
+  /**
+   * Applies any pending adapter configuration calls that were queued
+   * before the adapter was resolved.
+   */
+  private applyPendingAdapterCalls(): void {
+    if (!this.adapter || this.pendingAdapterCalls.length === 0) {
+      return
+    }
+
+    for (const { method, args } of this.pendingAdapterCalls) {
+      assertAdapterSupports(
+        this.adapter,
+        method as keyof AbstractAdapterInterface,
+      )
+      ;(this.adapter as Record<string, (...args: unknown[]) => unknown>)[method](
+        ...args,
+      )
     }
+
+    // Clear the queue after applying
+    this.pendingAdapterCalls = []
   }
 
   /**
@@ -334,8 +512,12 @@ export class NaviosApplication<
     if (this.isInitialized) {
       throw new Error('configure() must be called before init()')
     }
-    assertAdapterSupports(this.adapter, 'configure')
-    this.adapter.configure(options)
+    if (this.adapter) {
+      assertAdapterSupports(this.adapter, 'configure')
+      this.adapter.configure(options)
+    } else {
+      this.pendingAdapterCalls.push({ method: 'configure', args: [options] })
+    }
     return this
   }
 
@@ -359,8 +541,12 @@ export class NaviosApplication<
       ? Environment['corsOptions']
       : never,
   ): void {
-    assertAdapterSupports(this.adapter, 'enableCors')
-    this.adapter.enableCors(options)
+    if (this.adapter) {
+      assertAdapterSupports(this.adapter, 'enableCors')
+      this.adapter.enableCors(options)
+    } else {
+      this.pendingAdapterCalls.push({ method: 'enableCors', args: [options] })
+    }
   }
 
   /**
@@ -383,8 +569,12 @@ export class NaviosApplication<
       ? Environment['multipartOptions']
       : never,
   ): void {
-    assertAdapterSupports(this.adapter, 'enableMultipart')
-    this.adapter.enableMultipart(options)
+    if (this.adapter) {
+      assertAdapterSupports(this.adapter, 'enableMultipart')
+      this.adapter.enableMultipart(options)
+    } else {
+      this.pendingAdapterCalls.push({ method: 'enableMultipart', args: [options] })
+    }
   }
 
   /**
@@ -400,8 +590,12 @@ export class NaviosApplication<
    * ```
    */
   setGlobalPrefix(prefix: string): void {
-    assertAdapterSupports(this.adapter, 'setGlobalPrefix')
-    this.adapter.setGlobalPrefix(prefix)
+    if (this.adapter) {
+      assertAdapterSupports(this.adapter, 'setGlobalPrefix')
+      this.adapter.setGlobalPrefix(prefix)
+    } else {
+      this.pendingAdapterCalls.push({ method: 'setGlobalPrefix', args: [prefix] })
+    }
   }
 
   /**

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

@@ -78,19 +78,21 @@ export class ModuleLoaderService {
 
     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) {
+        continue
+      }
+
+      if (!extension.controllers) {
+        continue
+      }
+
+      if (!extension.moduleName) {
         throw new Error(
           'moduleName is required when providing controllers without a module',
         )
       }
+
+      await this.registerControllers(extension.controllers, extension.moduleName)
     }
   }
 
@@ -114,6 +116,7 @@ export class ModuleLoaderService {
     } else {
       // Create new synthetic module metadata
       const metadata: ModuleMetadata = {
+        name: moduleName,
         controllers: new Set(controllers),
         imports: new Set(),
         guards: new Set(),

package/src/utils/define-plugin.mts

@@ -0,0 +1,251 @@
+import type { AbstractAdapterInterface } from '../interfaces/abstract-adapter.interface.mjs'
+import type {
+  ContainerOnlyContext,
+  FullPluginContext,
+  ModulesLoadedContext,
+} from '../interfaces/plugin-context.mjs'
+import type { PluginStage } from '../interfaces/plugin-stage.mjs'
+import type { StagedPluginDefinition } from '../interfaces/staged-plugin.interface.mjs'
+
+import { PluginStages } from '../interfaces/plugin-stage.mjs'
+
+// ============ Plugin Config Type ============
+
+interface PluginConfig<TContext, TOptions> {
+  name: string
+  register: (context: TContext, options: TOptions) => Promise<void> | void
+}
+
+// ============ Internal Factory Creator ============
+
+/**
+ * Creates a curried plugin factory for a specific stage.
+ * Returns a function that takes config and returns a function that takes options.
+ */
+function createPluginFactory<TStage extends PluginStage, TContext>(
+  stage: TStage,
+) {
+  return <
+    TOptions,
+    TAdapter extends AbstractAdapterInterface = AbstractAdapterInterface,
+  >(
+    config: PluginConfig<TContext, TOptions>,
+  ) =>
+  (options: TOptions): StagedPluginDefinition<TStage, TOptions, TAdapter> => ({
+    plugin: {
+      name: config.name,
+      stage,
+      register: config.register as (
+        context: never,
+        options: TOptions,
+      ) => Promise<void> | void,
+    },
+    options,
+  })
+}
+
+// ============ Pre-Adapter Stages (No adapter in context) ============
+
+/**
+ * Define a plugin that runs before modules are traversed.
+ *
+ * Context: container only
+ *
+ * Use this stage for early DI setup before any modules are loaded.
+ *
+ * @example
+ * ```typescript
+ * export const defineEarlySetupPlugin = definePreModulesTraversePlugin({
+ *   name: 'early-setup',
+ *   register: (context, options: { key: string }) => {
+ *     context.container.addInstance(SomeToken, options.key)
+ *   },
+ * })
+ *
+ * // Usage
+ * app.usePlugin(defineEarlySetupPlugin({ key: 'value' }))
+ * ```
+ */
+export const definePreModulesTraversePlugin = createPluginFactory<
+  'pre:modules-traverse',
+  ContainerOnlyContext
+>(PluginStages.PRE_MODULES_TRAVERSE)
+
+/**
+ * Define a plugin that runs after modules are traversed.
+ *
+ * Context: container + modules + moduleLoader
+ *
+ * Use this stage to inspect loaded modules or extend the module tree.
+ *
+ * @example
+ * ```typescript
+ * export const defineModuleInspectorPlugin = definePostModulesTraversePlugin({
+ *   name: 'module-inspector',
+ *   register: (context, options) => {
+ *     console.log('Loaded modules:', context.modules.size)
+ *   },
+ * })
+ * ```
+ */
+export const definePostModulesTraversePlugin = createPluginFactory<
+  'post:modules-traverse',
+  ModulesLoadedContext
+>(PluginStages.POST_MODULES_TRAVERSE)
+
+/**
+ * Define a plugin that runs before adapter is resolved from container.
+ *
+ * Context: container + modules + moduleLoader (NO adapter yet!)
+ *
+ * Use this stage to modify registry/bindings before adapter instantiation.
+ * This is ideal for instrumentation, service wrapping, or changing DI bindings.
+ *
+ * @example
+ * ```typescript
+ * export const defineOtelPlugin = definePreAdapterResolvePlugin({
+ *   name: 'otel',
+ *   register: (context, options: OtelOptions) => {
+ *     const registry = context.container.getRegistry()
+ *     // Modify registry before adapter is created
+ *   },
+ * })
+ *
+ * // Usage
+ * app.usePlugin(defineOtelPlugin({ serviceName: 'my-app' }))
+ * ```
+ */
+export const definePreAdapterResolvePlugin = createPluginFactory<
+  'pre:adapter-resolve',
+  ModulesLoadedContext
+>(PluginStages.PRE_ADAPTER_RESOLVE)
+
+// ============ Post-Adapter Stages (Adapter available) ============
+
+/**
+ * Define a plugin that runs after adapter is resolved.
+ *
+ * Context: full (container + modules + moduleLoader + adapter)
+ *
+ * @example
+ * ```typescript
+ * export const defineAdapterConfigPlugin = definePostAdapterResolvePlugin<
+ *   { prefix: string },
+ *   BunApplicationServiceInterface
+ * >()({
+ *   name: 'adapter-config',
+ *   register: (context, options) => {
+ *     context.adapter.setGlobalPrefix(options.prefix)
+ *   },
+ * })
+ * ```
+ */
+export function definePostAdapterResolvePlugin<
+  TAdapter extends AbstractAdapterInterface = AbstractAdapterInterface,
+>() {
+  return createPluginFactory<'post:adapter-resolve', FullPluginContext<TAdapter>>(
+    PluginStages.POST_ADAPTER_RESOLVE,
+  )
+}
+
+/**
+ * Define a plugin that runs before adapter setup.
+ *
+ * Context: full
+ */
+export function definePreAdapterSetupPlugin<
+  TAdapter extends AbstractAdapterInterface = AbstractAdapterInterface,
+>() {
+  return createPluginFactory<'pre:adapter-setup', FullPluginContext<TAdapter>>(
+    PluginStages.PRE_ADAPTER_SETUP,
+  )
+}
+
+/**
+ * Define a plugin that runs after adapter setup.
+ *
+ * Context: full
+ */
+export function definePostAdapterSetupPlugin<
+  TAdapter extends AbstractAdapterInterface = AbstractAdapterInterface,
+>() {
+  return createPluginFactory<'post:adapter-setup', FullPluginContext<TAdapter>>(
+    PluginStages.POST_ADAPTER_SETUP,
+  )
+}
+
+/**
+ * Define a plugin that runs before modules init (route registration).
+ *
+ * Context: full
+ */
+export function definePreModulesInitPlugin<
+  TAdapter extends AbstractAdapterInterface = AbstractAdapterInterface,
+>() {
+  return createPluginFactory<'pre:modules-init', FullPluginContext<TAdapter>>(
+    PluginStages.PRE_MODULES_INIT,
+  )
+}
+
+/**
+ * Define a plugin that runs after modules init (route registration).
+ *
+ * Context: full
+ *
+ * This is the default stage for legacy NaviosPlugin implementations.
+ *
+ * @example
+ * ```typescript
+ * export const defineOpenApiPlugin = definePostModulesInitPlugin<
+ *   BunApplicationServiceInterface
+ * >()({
+ *   name: 'openapi',
+ *   register: async (context, options: OpenApiOptions) => {
+ *     // Routes are registered, can generate OpenAPI docs
+ *   },
+ * })
+ * ```
+ */
+export function definePostModulesInitPlugin<
+  TAdapter extends AbstractAdapterInterface = AbstractAdapterInterface,
+>() {
+  return createPluginFactory<'post:modules-init', FullPluginContext<TAdapter>>(
+    PluginStages.POST_MODULES_INIT,
+  )
+}
+
+/**
+ * Define a plugin that runs before adapter signals ready.
+ *
+ * Context: full
+ */
+export function definePreReadyPlugin<
+  TAdapter extends AbstractAdapterInterface = AbstractAdapterInterface,
+>() {
+  return createPluginFactory<'pre:ready', FullPluginContext<TAdapter>>(
+    PluginStages.PRE_READY,
+  )
+}
+
+/**
+ * Define a plugin that runs after adapter signals ready.
+ *
+ * Context: full - this is the final stage, app is fully initialized
+ *
+ * @example
+ * ```typescript
+ * export const defineStartupLogPlugin = definePostReadyPlugin()({
+ *   name: 'startup-log',
+ *   register: (context) => {
+ *     console.log('Application fully initialized!')
+ *   },
+ * })
+ * ```
+ */
+export function definePostReadyPlugin<
+  TAdapter extends AbstractAdapterInterface = AbstractAdapterInterface,
+>() {
+  return createPluginFactory<'post:ready', FullPluginContext<TAdapter>>(
+    PluginStages.POST_READY,
+  )
+}