@navios/core 1.0.0 → 1.1.0

package/lib/{navios.factory-CO5MB_OK.cjs → navios.factory-CUrO_p6K.cjs}

@@ -25,7 +25,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 }) : target, mod));
 
 //#endregion
-const require_tokens = require('./tokens-CWw9kyeD.cjs');
+const require_tokens = require('./tokens-BEuBMGGX.cjs');
 let _navios_di = require("@navios/di");
 let zod_v4 = require("zod/v4");
 zod_v4 = __toESM(zod_v4);
@@ -1157,6 +1157,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
 /**
@@ -2794,9 +2845,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.
@@ -2808,6 +2865,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(),
@@ -2907,6 +2965,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() {
@@ -3505,7 +3724,14 @@ var NaviosApplication = class {
 	container = (0, _navios_di.inject)(_navios_di.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.
@@ -3514,13 +3740,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(require_tokens.AdapterToken);
 	}
 	/**
 	* Gets the dependency injection container used by this application.
@@ -3539,35 +3767,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' } }))
+	*
+	* // Multiple plugins in one call
+	* app.usePlugin([
+	*   defineOtelPlugin({ serviceName: 'my-service' }),
+	*   defineOpenApiPlugin({ info: { title: 'My API', version: '1.0.0' } }),
+	* ])
 	*
-	* app.usePlugin(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()`.
 	*
@@ -3583,31 +3834,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(require_tokens.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);
@@ -3632,8 +3935,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;
 	}
 	/**
@@ -3651,8 +3959,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.
@@ -3669,8 +3982,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.
@@ -3684,8 +4002,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.
@@ -3912,6 +4235,24 @@ Object.defineProperty(exports, 'NotFoundResponderToken', {
     return NotFoundResponderToken;
   }
 });
+Object.defineProperty(exports, 'PLUGIN_STAGES_ORDER', {
+  enumerable: true,
+  get: function () {
+    return PLUGIN_STAGES_ORDER;
+  }
+});
+Object.defineProperty(exports, 'PluginStageBase', {
+  enumerable: true,
+  get: function () {
+    return PluginStageBase;
+  }
+});
+Object.defineProperty(exports, 'PluginStages', {
+  enumerable: true,
+  get: function () {
+    return PluginStages;
+  }
+});
 Object.defineProperty(exports, 'ValidationErrorResponderToken', {
   enumerable: true,
   get: function () {
@@ -3996,6 +4337,66 @@ Object.defineProperty(exports, 'clc', {
     return clc;
   }
 });
+Object.defineProperty(exports, 'definePostAdapterResolvePlugin', {
+  enumerable: true,
+  get: function () {
+    return definePostAdapterResolvePlugin;
+  }
+});
+Object.defineProperty(exports, 'definePostAdapterSetupPlugin', {
+  enumerable: true,
+  get: function () {
+    return definePostAdapterSetupPlugin;
+  }
+});
+Object.defineProperty(exports, 'definePostModulesInitPlugin', {
+  enumerable: true,
+  get: function () {
+    return definePostModulesInitPlugin;
+  }
+});
+Object.defineProperty(exports, 'definePostModulesTraversePlugin', {
+  enumerable: true,
+  get: function () {
+    return definePostModulesTraversePlugin;
+  }
+});
+Object.defineProperty(exports, 'definePostReadyPlugin', {
+  enumerable: true,
+  get: function () {
+    return definePostReadyPlugin;
+  }
+});
+Object.defineProperty(exports, 'definePreAdapterResolvePlugin', {
+  enumerable: true,
+  get: function () {
+    return definePreAdapterResolvePlugin;
+  }
+});
+Object.defineProperty(exports, 'definePreAdapterSetupPlugin', {
+  enumerable: true,
+  get: function () {
+    return definePreAdapterSetupPlugin;
+  }
+});
+Object.defineProperty(exports, 'definePreModulesInitPlugin', {
+  enumerable: true,
+  get: function () {
+    return definePreModulesInitPlugin;
+  }
+});
+Object.defineProperty(exports, 'definePreModulesTraversePlugin', {
+  enumerable: true,
+  get: function () {
+    return definePreModulesTraversePlugin;
+  }
+});
+Object.defineProperty(exports, 'definePreReadyPlugin', {
+  enumerable: true,
+  get: function () {
+    return definePreReadyPlugin;
+  }
+});
 Object.defineProperty(exports, 'filterLogLevels', {
   enumerable: true,
   get: function () {
@@ -4098,6 +4499,18 @@ Object.defineProperty(exports, 'normalizePath', {
     return normalizePath;
   }
 });
+Object.defineProperty(exports, 'postStage', {
+  enumerable: true,
+  get: function () {
+    return postStage;
+  }
+});
+Object.defineProperty(exports, 'preStage', {
+  enumerable: true,
+  get: function () {
+    return preStage;
+  }
+});
 Object.defineProperty(exports, 'runWithRequestId', {
   enumerable: true,
   get: function () {
@@ -4122,4 +4535,4 @@ Object.defineProperty(exports, 'yellow', {
     return yellow;
   }
 });
-//# sourceMappingURL=navios.factory-CO5MB_OK.cjs.map
+//# sourceMappingURL=navios.factory-CUrO_p6K.cjs.map