@navios/core 1.0.0 → 1.1.0

package/lib/{navios.factory-D6Y94P9B.mjs → navios.factory-DjUOOVVL.mjs}

@@ -1,4 +1,4 @@
-import { a as NaviosOptionsToken, d as AdapterToken, p as extractModuleMetadata } from "./tokens-4J9sredA.mjs";
+import { a as NaviosOptionsToken, d as AdapterToken, p as extractModuleMetadata } from "./tokens-COyNGV1I.mjs";
 import { Container, Injectable, InjectableScope, InjectionToken, getInjectableToken, inject, optional } from "@navios/di";
 import z from "zod/v4";
 import { inspect } from "util";
@@ -1129,6 +1129,57 @@ var LoggerInstance = class {
 	}
 };
 
+//#endregion
+//#region src/interfaces/plugin-stage.mts
+/**
+* Base stage names (without pre:/post: prefix)
+*/
+const PluginStageBase = {
+	MODULES_TRAVERSE: "modules-traverse",
+	ADAPTER_RESOLVE: "adapter-resolve",
+	ADAPTER_SETUP: "adapter-setup",
+	MODULES_INIT: "modules-init",
+	READY: "ready"
+};
+/**
+* Helper to create pre stage name from base
+*/
+const preStage = (base) => `pre:${base}`;
+/**
+* Helper to create post stage name from base
+*/
+const postStage = (base) => `post:${base}`;
+/**
+* All stages as constants for direct access
+*/
+const PluginStages = {
+	PRE_MODULES_TRAVERSE: "pre:modules-traverse",
+	POST_MODULES_TRAVERSE: "post:modules-traverse",
+	PRE_ADAPTER_RESOLVE: "pre:adapter-resolve",
+	POST_ADAPTER_RESOLVE: "post:adapter-resolve",
+	PRE_ADAPTER_SETUP: "pre:adapter-setup",
+	POST_ADAPTER_SETUP: "post:adapter-setup",
+	PRE_MODULES_INIT: "pre:modules-init",
+	POST_MODULES_INIT: "post:modules-init",
+	PRE_READY: "pre:ready",
+	POST_READY: "post:ready"
+};
+/**
+* All stages in execution order
+*/
+const PLUGIN_STAGES_ORDER = [
+	PluginStages.PRE_MODULES_TRAVERSE,
+	PluginStages.POST_MODULES_TRAVERSE,
+	PluginStages.PRE_ADAPTER_RESOLVE,
+	PluginStages.POST_ADAPTER_RESOLVE,
+	PluginStages.PRE_ADAPTER_SETUP,
+	PluginStages.POST_ADAPTER_SETUP,
+	PluginStages.PRE_MODULES_INIT,
+	PluginStages.POST_MODULES_INIT,
+	PluginStages.PRE_READY,
+	PluginStages.POST_READY
+];
+
 //#endregion
 //#region src/responders/enums/framework-error.enum.mts
 /**
@@ -2766,9 +2817,15 @@ var ModuleLoaderService = class {
 	* ```
 	*/ async extendModules(extensions) {
 		if (!this.initialized) throw new Error("ModuleLoaderService must be initialized before extending. Call loadModules() first.");
-		for (const extension of extensions) if (extension.module) await this.traverseModules(extension.module);
-		else if (extension.controllers && extension.moduleName) await this.registerControllers(extension.controllers, extension.moduleName);
-		else if (extension.controllers) throw new Error("moduleName is required when providing controllers without a module");
+		for (const extension of extensions) {
+			if (extension.module) {
+				await this.traverseModules(extension.module);
+				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);
+		}
 	}
 	/**
 	* Registers controllers under a synthetic module.
@@ -2780,6 +2837,7 @@ var ModuleLoaderService = class {
 			this.logger.debug(`Extended module ${moduleName} with ${controllers.length} controllers`);
 		} else {
 			const metadata = {
+				name: moduleName,
 				controllers: new Set(controllers),
 				imports: /* @__PURE__ */ new Set(),
 				guards: /* @__PURE__ */ new Set(),
@@ -2879,6 +2937,167 @@ var ModuleLoaderService = class {
 	if (!adapterSupports(adapter, method)) throw new Error(`Current adapter does not implement '${method}()'`);
 }
 
+//#endregion
+//#region src/utils/define-plugin.mts
+/**
+* Creates a curried plugin factory for a specific stage.
+* Returns a function that takes config and returns a function that takes options.
+*/ function createPluginFactory(stage) {
+	return (config) => (options) => ({
+		plugin: {
+			name: config.name,
+			stage,
+			register: config.register
+		},
+		options
+	});
+}
+/**
+* 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' }))
+* ```
+*/ const definePreModulesTraversePlugin = createPluginFactory(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)
+*   },
+* })
+* ```
+*/ const definePostModulesTraversePlugin = createPluginFactory(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' }))
+* ```
+*/ const definePreAdapterResolvePlugin = createPluginFactory(PluginStages.PRE_ADAPTER_RESOLVE);
+/**
+* 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)
+*   },
+* })
+* ```
+*/ function definePostAdapterResolvePlugin() {
+	return createPluginFactory(PluginStages.POST_ADAPTER_RESOLVE);
+}
+/**
+* Define a plugin that runs before adapter setup.
+*
+* Context: full
+*/ function definePreAdapterSetupPlugin() {
+	return createPluginFactory(PluginStages.PRE_ADAPTER_SETUP);
+}
+/**
+* Define a plugin that runs after adapter setup.
+*
+* Context: full
+*/ function definePostAdapterSetupPlugin() {
+	return createPluginFactory(PluginStages.POST_ADAPTER_SETUP);
+}
+/**
+* Define a plugin that runs before modules init (route registration).
+*
+* Context: full
+*/ function definePreModulesInitPlugin() {
+	return createPluginFactory(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
+*   },
+* })
+* ```
+*/ function definePostModulesInitPlugin() {
+	return createPluginFactory(PluginStages.POST_MODULES_INIT);
+}
+/**
+* Define a plugin that runs before adapter signals ready.
+*
+* Context: full
+*/ function definePreReadyPlugin() {
+	return createPluginFactory(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!')
+*   },
+* })
+* ```
+*/ function definePostReadyPlugin() {
+	return createPluginFactory(PluginStages.POST_READY);
+}
+
 //#endregion
 //#region src/navios.environment.mts
 function applyDecs2203RFactory$1() {
@@ -3477,7 +3696,14 @@ var NaviosApplication = class {
 	container = inject(Container);
 	appModule = null;
 	options = { adapter: [] };
-	plugins = [];
+	/**
+	* Plugin storage organized by stage for efficient execution.
+	* Each stage has a Set of plugin definitions.
+	*/ plugins = new Map(PLUGIN_STAGES_ORDER.map((stage) => [stage, /* @__PURE__ */ new Set()]));
+	/**
+	* Queue of adapter configuration methods to apply after adapter resolution.
+	* Allows calling methods like enableCors() before init().
+	*/ pendingAdapterCalls = [];
 	/**
 	* Indicates whether the application has been initialized.
 	* Set to `true` after `init()` completes successfully.
@@ -3486,13 +3712,15 @@ var NaviosApplication = class {
 	* 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
 	*/ async setup(appModule, options = { adapter: [] }) {
 		this.appModule = appModule;
 		this.options = options;
-		if (this.environment.hasAdapterSetup()) this.adapter = await this.container.get(AdapterToken);
 	}
 	/**
 	* Gets the dependency injection container used by this application.
@@ -3511,35 +3739,58 @@ var NaviosApplication = class {
 		return this.adapter;
 	}
 	/**
-	* 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'
+	* // Single plugin (legacy or staged)
+	* app.usePlugin(defineOpenApiPlugin({ info: { title: 'My API', version: '1.0.0' } }))
 	*
-	* 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(definition) {
-		this.plugins.push(definition);
+	*/ usePlugin(definitions) {
+		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);
+			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.
+	*/ resolvePluginStage(definition) {
+		if ("stage" in definition.plugin) return definition.plugin.stage;
+		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()`.
 	*
@@ -3555,31 +3806,83 @@ var NaviosApplication = class {
 	* ```
 	*/ async init() {
 		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);
-		await this.initPlugins();
-		await this.initModules();
-		if (this.adapter) await this.adapter.ready();
+		await this.wrapStage(PluginStageBase.MODULES_TRAVERSE, () => this.moduleLoader.loadModules(this.appModule));
+		if (this.environment.hasAdapterSetup()) {
+			await this.wrapStage(PluginStageBase.ADAPTER_RESOLVE, async () => {
+				this.adapter = await this.container.get(AdapterToken);
+				this.applyPendingAdapterCalls();
+			});
+			if (this.adapter) await this.wrapStage(PluginStageBase.ADAPTER_SETUP, () => this.adapter.setupAdapter(this.options));
+		}
+		await this.wrapStage(PluginStageBase.MODULES_INIT, () => this.initModules());
+		if (this.adapter) await this.wrapStage(PluginStageBase.READY, () => this.adapter.ready());
 		this.isInitialized = true;
 		this.logger.debug("Navios application initialized");
 	}
-	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
+	*/ async wrapStage(baseName, operation) {
+		await this.executePluginStage(preStage(baseName));
+		const result = await operation();
+		await this.executePluginStage(postStage(baseName));
+		return result;
 	}
-	async initPlugins() {
-		if (this.plugins.length === 0) return;
-		if (!this.adapter) throw new Error("Cannot initialize plugins without an adapter");
-		const context = {
+	/**
+	* Executes all plugins registered for a specific stage.
+	*
+	* @param stage - The lifecycle stage to execute plugins for
+	*/ async executePluginStage(stage) {
+		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, options);
+			} catch (error) {
+				this.logger.error(`Plugin "${plugin.name}" failed at stage "${stage}"`, error);
+				throw error;
+			}
+		}
+	}
+	/**
+	* Builds the appropriate context object for a given stage.
+	*
+	* @param stage - The lifecycle stage
+	* @returns Context object with stage-appropriate properties
+	*/ buildContextForStage(stage) {
+		const baseContext = { container: this.container };
+		if (stage === PluginStages.PRE_MODULES_TRAVERSE) return baseContext;
+		const modulesContext = {
+			...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);
+		if (stage === PluginStages.POST_MODULES_TRAVERSE || stage === PluginStages.PRE_ADAPTER_RESOLVE) return modulesContext;
+		if (!this.adapter) throw new Error(`Cannot execute stage "${stage}" without adapter`);
+		return {
+			...modulesContext,
+			adapter: this.adapter
+		};
+	}
+	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.
+	*/ applyPendingAdapterCalls() {
+		if (!this.adapter || this.pendingAdapterCalls.length === 0) return;
+		for (const { method, args } of this.pendingAdapterCalls) {
+			assertAdapterSupports(this.adapter, method);
+			this.adapter[method](...args);
 		}
+		this.pendingAdapterCalls = [];
 	}
 	async get(token, args) {
 		return this.container.get(token, args);
@@ -3604,8 +3907,13 @@ var NaviosApplication = class {
 	* ```
 	*/ configure(options) {
 		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;
 	}
 	/**
@@ -3623,8 +3931,13 @@ var NaviosApplication = class {
 	* })
 	* ```
 	*/ enableCors(options) {
-		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]
+		});
 	}
 	/**
 	* Enables multipart/form-data support for file uploads.
@@ -3641,8 +3954,13 @@ var NaviosApplication = class {
 	* })
 	* ```
 	*/ enableMultipart(options) {
-		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]
+		});
 	}
 	/**
 	* Sets a global prefix for all routes.
@@ -3656,8 +3974,13 @@ var NaviosApplication = class {
 	* // All routes will be prefixed with /api/v1
 	* ```
 	*/ setGlobalPrefix(prefix) {
-		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]
+		});
 	}
 	/**
 	* Gets the underlying HTTP server instance.
@@ -3824,5 +4147,5 @@ var NaviosApplication = class {
 };
 
 //#endregion
-export { isNil as A, filterLogLevels as B, getRequestId as C, isConstructor as D, addLeadingSlash as E, isSymbol as F, LOG_LEVELS as H, isUndefined as I, normalizePath as L, isObject as M, isPlainObject as N, isEmpty as O, isString as P, stripEndSlash as R, generateRequestId as S, setRequestIdEnabled as T, clc as U, isLogLevel as V, yellow as W, _LoggerInstance as _, assertAdapterSupports as a, LoggerOutput as b, AbstractHandlerAdapterService as c, ForbiddenResponderToken as d, InternalServerErrorResponderToken as f, HttpException as g, FrameworkError as h, adapterSupports as i, isNumber as j, isFunction as k, _InstanceResolverService as l, ValidationErrorResponderToken as m, _NaviosApplication as n, _ModuleLoaderService as o, NotFoundResponderToken as p, _NaviosEnvironment as r, _GuardRunnerService as s, NaviosFactory as t, _ErrorResponseProducerService as u, _ConsoleLogger as v, runWithRequestId as w, loggerOptionsSchema as x, Logger as y, isLogLevelEnabled as z };
-//# sourceMappingURL=navios.factory-D6Y94P9B.mjs.map
+export { stripEndSlash as $, preStage as A, setRequestIdEnabled as B, NotFoundResponderToken as C, PluginStageBase as D, PLUGIN_STAGES_ORDER as E, LoggerOutput as F, isNil as G, isConstructor as H, loggerOptionsSchema as I, isPlainObject as J, isNumber as K, generateRequestId as L, _LoggerInstance as M, _ConsoleLogger as N, PluginStages as O, Logger as P, normalizePath as Q, getRequestId as R, InternalServerErrorResponderToken as S, FrameworkError as T, isEmpty as U, addLeadingSlash as V, isFunction as W, isSymbol as X, isString as Y, isUndefined as Z, _GuardRunnerService as _, definePostAdapterSetupPlugin as a, yellow as at, _ErrorResponseProducerService as b, definePostReadyPlugin as c, definePreModulesInitPlugin as d, isLogLevelEnabled as et, definePreModulesTraversePlugin as f, _ModuleLoaderService as g, assertAdapterSupports as h, definePostAdapterResolvePlugin as i, clc as it, HttpException as j, postStage as k, definePreAdapterResolvePlugin as l, adapterSupports as m, _NaviosApplication as n, isLogLevel as nt, definePostModulesInitPlugin as o, definePreReadyPlugin as p, isObject as q, _NaviosEnvironment as r, LOG_LEVELS as rt, definePostModulesTraversePlugin as s, NaviosFactory as t, filterLogLevels as tt, definePreAdapterSetupPlugin as u, AbstractHandlerAdapterService as v, ValidationErrorResponderToken as w, ForbiddenResponderToken as x, _InstanceResolverService as y, runWithRequestId as z };
+//# sourceMappingURL=navios.factory-DjUOOVVL.mjs.map