@navios/core 1.0.0-alpha.2 → 1.0.0-alpha.4

package/src/interfaces/abstract-adapter.interface.mts

@@ -0,0 +1,32 @@
+import type { ModuleMetadata } from '../metadata/index.mjs'
+
+/**
+ * Base interface for all Navios adapters (HTTP, CLI, etc.).
+ *
+ * Adapters implement this interface to provide runtime-specific functionality.
+ * This interface defines the common lifecycle methods shared across all adapter types.
+ */
+export interface AbstractAdapterInterface {
+  /**
+   * Sets up the adapter with the provided options.
+   * Called during application initialization before modules are initialized.
+   */
+  setupAdapter(options: unknown): Promise<void>
+
+  /**
+   * Called after all modules are loaded.
+   * Adapters use this to register routes, commands, or other module-based functionality.
+   */
+  onModulesInit(modules: Map<string, ModuleMetadata>): Promise<void>
+
+  /**
+   * Signals that the adapter is ready to handle requests/commands.
+   * Called after onModulesInit completes.
+   */
+  ready(): Promise<void>
+
+  /**
+   * Disposes of the adapter and cleans up resources.
+   */
+  dispose(): Promise<void>
+}

package/src/interfaces/abstract-http-adapter.interface.mts

@@ -1,28 +1,24 @@
 import type { ModuleMetadata } from '../metadata/index.mjs'
-import type { AbstractHttpCorsOptions } from './abstract-http-cors-options.interface.mjs'
-import type { AbstractHttpListenOptions } from './abstract-http-listen-options.interface.mjs'
+import type { AbstractAdapterInterface } from './abstract-adapter.interface.mjs'
+import type { HttpAdapterEnvironment } from './adapter-environment.interface.mjs'
 
 /**
- * Abstract interface for HTTP adapters.
+ * Interface for HTTP adapters extending the base adapter interface.
  *
  * Adapters implement this interface to provide runtime-specific HTTP server
  * functionality (Fastify, Bun, etc.).
  *
- * @typeParam ServerInstance - The underlying server type (e.g., FastifyInstance)
- * @typeParam CorsOptions - CORS configuration options type
- * @typeParam Options - Server setup options type
- * @typeParam MultipartOptions - Multipart form handling options type
+ * @typeParam Environment - The adapter environment providing type-safe access to
+ *                          server instance, CORS options, listen options, etc.
  */
 export interface AbstractHttpAdapterInterface<
-  ServerInstance,
-  CorsOptions = AbstractHttpCorsOptions,
-  Options = {},
-  MultipartOptions = {},
-> {
+  Environment extends HttpAdapterEnvironment = HttpAdapterEnvironment,
+> extends AbstractAdapterInterface {
   /**
-   * Sets up the HTTP server with the provided options.
+   * Sets up the adapter with the provided options.
+   * Called during application initialization before modules are initialized.
    */
-  setupHttpServer(options: Options): Promise<void>
+  setupAdapter(options: Environment['options']): Promise<void>
 
   /**
    * Called after all modules are loaded to register routes.
@@ -34,10 +30,15 @@ export interface AbstractHttpAdapterInterface<
    */
   ready(): Promise<void>
 
+  /**
+   * Disposes of the server and cleans up resources.
+   */
+  dispose(): Promise<void>
+
   /**
    * Returns the underlying HTTP server instance.
    */
-  getServer(): ServerInstance
+  getServer(): Environment['server']
 
   /**
    * Sets a global prefix for all routes.
@@ -53,20 +54,26 @@ export interface AbstractHttpAdapterInterface<
   /**
    * Enables CORS with the specified options.
    */
-  enableCors(options: CorsOptions): void
+  enableCors(options: Environment['corsOptions']): void
 
   /**
    * Enables multipart form data handling.
    */
-  enableMultipart(options: MultipartOptions): void
+  enableMultipart(options: Environment['multipartOptions']): void
 
   /**
    * Starts the server and listens for incoming requests.
    */
-  listen(options: AbstractHttpListenOptions): Promise<string>
+  listen(options: Environment['listenOptions']): Promise<string>
 
   /**
-   * Disposes of the server and cleans up resources.
+   * Configures the adapter with additional options before init.
+   *
+   * This method allows setting adapter-specific configuration options
+   * before the server is initialized. Options set via configure() are
+   * merged with options passed to setupAdapter().
+   *
+   * Must be called before setupAdapter().
    */
-  dispose(): Promise<void>
+  configure(options: Partial<Environment['options']>): void
 }

package/src/interfaces/abstract-http-handler-adapter.interface.mts

@@ -32,10 +32,94 @@ export type HandlerResult<TRequest = any, TReply = any> =
   | StaticHandler<TRequest, TReply>
   | DynamicHandler<TRequest, TReply>
 
-export interface AbstractHttpHandlerAdapterInterface {
+/**
+ * Function type for argument getters that extract data from requests.
+ * Each getter populates a target object with data from the request.
+ */
+export type ArgumentGetterFn<TRequest = any> = (
+  target: Record<string, any>,
+  request: TRequest,
+) => void | Promise<void>
+
+/**
+ * Function type for formatting arguments from a request.
+ * Built from argument getters, optimized for sync/async handling.
+ */
+export type FormatArgumentsFn<TRequest = any> = (
+  request: TRequest,
+) => Record<string, any> | Promise<Record<string, any>>
+
+/**
+ * Interface for HTTP handler adapter services.
+ *
+ * Adapters handle different types of HTTP requests (REST, streaming, multipart)
+ * and are responsible for:
+ * - Parsing and validating request data
+ * - Creating handler functions
+ * - Formatting responses
+ * - Providing schema information (for frameworks like Fastify)
+ */
+export interface AbstractHttpHandlerAdapterInterface<TRequest = any> {
+  /**
+   * Prepares argument getters for parsing request data.
+   *
+   * Creates functions that extract and validate data from the request,
+   * populating a target object with validated arguments.
+   *
+   * @param handlerMetadata - The handler metadata with schemas and configuration.
+   * @returns An array of getter functions that populate request arguments.
+   */
   prepareArguments?: (
     handlerMetadata: HandlerMetadata<any>,
-  ) => ((target: Record<string, any>, request: any) => Promise<void> | void)[]
+  ) => ArgumentGetterFn<TRequest>[]
+
+  /**
+   * Builds a formatArguments function from argument getters.
+   *
+   * Automatically detects sync vs async getters and optimizes accordingly:
+   * - If all getters are sync: returns sync function (no Promise overhead)
+   * - If any getter is async: returns async function with Promise.all
+   * - If no getters: returns frozen empty object (zero allocation)
+   *
+   * This method is useful for composition-based adapters that need to
+   * build formatArguments without duplicating the optimization logic.
+   *
+   * @param getters - Array of argument getter functions
+   * @returns Function to format arguments from request
+   */
+  buildFormatArguments?: (
+    getters: ArgumentGetterFn<TRequest>[],
+  ) => FormatArgumentsFn<TRequest>
+
+  /**
+   * Checks if the handler has any validation schemas defined.
+   *
+   * @param handlerMetadata - The handler metadata containing configuration.
+   * @returns `true` if the handler has any schemas (request, query, response).
+   */
+  hasSchema?: (handlerMetadata: HandlerMetadata<any>) => boolean
+
+  /**
+   * Provides schema information for the framework's validation system.
+   *
+   * For frameworks like Fastify, this returns route schema objects.
+   * For frameworks like Bun, this typically returns an empty object.
+   *
+   * @param handlerMetadata - The handler metadata containing configuration.
+   * @returns Schema information for framework registration.
+   */
+  provideSchema?: (handlerMetadata: HandlerMetadata<any>) => Record<string, any>
+
+  /**
+   * Creates a request handler function for the endpoint.
+   *
+   * This is the core method that generates the actual handler function
+   * that will be called when a request matches the endpoint.
+   *
+   * @param controller - The controller class containing the handler method.
+   * @param handlerMetadata - The handler metadata with configuration and schemas.
+   * @returns A handler result that is either static or dynamic.
+   */
   provideHandler: (
     controller: ClassType,
     handlerMetadata: HandlerMetadata<any>,

package/src/interfaces/adapter-environment.interface.mts

@@ -0,0 +1,74 @@
+import type { AbstractAdapterInterface } from './abstract-adapter.interface.mjs'
+
+/**
+ * Base interface for adapter environments.
+ *
+ * All adapter environments extend this interface to provide
+ * type-safe access to adapter-specific configuration options.
+ */
+export interface AdapterEnvironment {
+  /**
+   * Adapter setup/configuration options type
+   */
+  options: unknown
+  /**
+   * Adapter type
+   */
+  adapter: AbstractAdapterInterface
+}
+
+/**
+ * Environment interface for HTTP adapters.
+ *
+ * Each HTTP adapter (Fastify, Bun, etc.) implements this interface to provide
+ * type-safe access to HTTP-specific types throughout the application.
+ *
+ * @example
+ * ```typescript
+ * // Using with a specific adapter
+ * import { FastifyEnvironment } from '@navios/adapter-fastify'
+ *
+ * const app = await NaviosFactory.create<FastifyEnvironment>(AppModule, {
+ *   adapter: defineFastifyEnvironment(),
+ * })
+ *
+ * // All methods are now type-safe for Fastify
+ * app.configure({ trustProxy: true })
+ * app.enableCors({ origin: true }) // FastifyCorsOptions
+ * const server = app.getServer() // FastifyInstance
+ * await app.listen({ port: 3000 }) // FastifyListenOptions
+ * ```
+ */
+export interface HttpAdapterEnvironment extends AdapterEnvironment {
+  /**
+   * The underlying HTTP server instance type (e.g., FastifyInstance, Bun.Server)
+   */
+  server: unknown
+
+  /**
+   * CORS configuration options type
+   */
+  corsOptions: unknown
+
+  /**
+   * Multipart form data configuration options type
+   */
+  multipartOptions: unknown
+
+  /**
+   * Server listen options type (port, host, etc.)
+   */
+  listenOptions: unknown
+}
+
+/**
+ * Default environment with unknown types.
+ *
+ * Forces users to specify an Environment generic for type-safe adapter access.
+ * When no generic is provided to `NaviosApplication` or `NaviosFactory.create()`,
+ * this default is used, resulting in `unknown` types for all adapter-specific
+ * methods.
+ */
+export interface DefaultAdapterEnvironment extends AdapterEnvironment {
+  options: unknown
+}

package/src/interfaces/index.mts

@@ -1,4 +1,6 @@
+export * from './abstract-adapter.interface.mjs'
 export * from './abstract-execution-context.inteface.mjs'
+export * from './adapter-environment.interface.mjs'
 export * from './abstract-http-adapter.interface.mjs'
 export * from './abstract-http-cors-options.interface.mjs'
 export * from './abstract-http-handler-adapter.interface.mjs'

package/src/interfaces/plugin.interface.mts

@@ -2,14 +2,34 @@ import type { Container } from '@navios/di'
 
 import type { ModuleMetadata } from '../metadata/index.mjs'
 import type { ModuleLoaderService } from '../services/module-loader.service.mjs'
+import type { AbstractAdapterInterface } from './abstract-adapter.interface.mjs'
 
 /**
  * Context provided to plugins during registration.
  *
  * This context gives plugins access to the application's modules,
- * server instance, DI container, and configuration.
+ * adapter instance, DI container, and module loader.
+ *
+ * @typeParam TAdapter - The adapter type, defaults to AbstractAdapterInterface
+ *
+ * @example
+ * ```typescript
+ * // Generic plugin that works with any adapter
+ * async register(context: PluginContext) {
+ *   const modules = context.modules
+ *   // ...
+ * }
+ *
+ * // Adapter-specific plugin with typed adapter
+ * async register(context: PluginContext<BunApplicationService>) {
+ *   const server = context.adapter.getServer() // Typed as Bun.Server
+ *   // ...
+ * }
+ * ```
  */
-export interface PluginContext {
+export interface PluginContext<
+  TAdapter extends AbstractAdapterInterface = AbstractAdapterInterface,
+> {
   /**
    * All loaded modules with their metadata.
    * Keys are module class names, values are their metadata.
@@ -17,22 +37,16 @@ export interface PluginContext {
   modules: Map<string, ModuleMetadata>
 
   /**
-   * The underlying HTTP server instance.
-   * Type depends on the adapter used (Fastify, Bun, etc.)
+   * The current adapter instance.
+   * Use type guards or cast to adapter-specific types for HTTP methods.
    */
-  server: any
+  adapter: TAdapter
 
   /**
    * The dependency injection container.
    */
   container: Container
 
-  /**
-   * Global route prefix (e.g., '/api/v1').
-   * Empty string if no prefix is set.
-   */
-  globalPrefix: string
-
   /**
    * Module loader service for extending the module tree.
    * Use `moduleLoader.extendModules()` to add controllers dynamically.
@@ -47,9 +61,11 @@ export interface PluginContext {
  * after all modules are loaded but before the server starts listening.
  *
  * @typeParam TOptions - The type of options the plugin accepts
+ * @typeParam TAdapter - The adapter type the plugin requires
  *
  * @example
  * ```typescript
+ * // Generic plugin
  * const myPlugin: NaviosPlugin<{ enabled: boolean }> = {
  *   name: 'my-plugin',
  *   register: async (context, options) => {
@@ -58,9 +74,20 @@ export interface PluginContext {
  *     }
  *   },
  * }
+ *
+ * // Adapter-specific plugin
+ * const fastifyPlugin: NaviosPlugin<Options, FastifyApplicationService> = {
+ *   name: 'fastify-plugin',
+ *   register: async (context, options) => {
+ *     const fastify = context.adapter.getServer() // Typed!
+ *   },
+ * }
  * ```
  */
-export interface NaviosPlugin<TOptions = unknown> {
+export interface NaviosPlugin<
+  TOptions = unknown,
+  TAdapter extends AbstractAdapterInterface = AbstractAdapterInterface,
+> {
   /**
    * Plugin name for identification and logging.
    */
@@ -69,10 +96,13 @@ export interface NaviosPlugin<TOptions = unknown> {
   /**
    * Called after modules are loaded but before the server starts listening.
    *
-   * @param context - The plugin context with access to modules and server
+   * @param context - The plugin context with access to modules and adapter
    * @param options - Plugin-specific configuration options
    */
-  register(context: PluginContext, options: TOptions): Promise<void> | void
+  register(
+    context: PluginContext<TAdapter>,
+    options: TOptions,
+  ): Promise<void> | void
 }
 
 /**
@@ -81,6 +111,7 @@ export interface NaviosPlugin<TOptions = unknown> {
  * This is the type returned by plugin factory functions like `defineOpenApiPlugin()`.
  *
  * @typeParam TOptions - The type of options the plugin accepts
+ * @typeParam TAdapter - The adapter type the plugin requires
  *
  * @example
  * ```typescript
@@ -92,11 +123,14 @@ export interface NaviosPlugin<TOptions = unknown> {
  * }
  * ```
  */
-export interface PluginDefinition<TOptions = unknown> {
+export interface PluginDefinition<
+  TOptions = unknown,
+  TAdapter extends AbstractAdapterInterface = AbstractAdapterInterface,
+> {
   /**
    * The plugin instance.
    */
-  plugin: NaviosPlugin<TOptions>
+  plugin: NaviosPlugin<TOptions, TAdapter>
 
   /**
    * Options to pass to the plugin's register function.

package/src/legacy-compat/attribute.factory.mts

@@ -1,5 +1,6 @@
-import type { z, ZodType } from 'zod/v4'
 import type { ClassType } from '@navios/di'
+import { createClassContext, createMethodContext } from '@navios/di/legacy-compat'
+import type { z, ZodType } from 'zod/v4'
 
 import type {
   ControllerMetadata,
@@ -18,7 +19,6 @@ import {
   getManagedMetadata,
   hasManagedMetadata,
 } from '../metadata/navios-managed.metadata.mjs'
-import { createClassContext, createMethodContext } from './context-compat.mjs'
 
 /**
  * Type for a legacy class/method attribute decorator without a value.

package/src/legacy-compat/decorators/controller.decorator.mts

@@ -1,9 +1,9 @@
 import type { ClassType } from '@navios/di'
+import { createClassContext } from '@navios/di/legacy-compat'
 
 import type { ControllerOptions } from '../../decorators/controller.decorator.mjs'
 
 import { Controller as OriginalController } from '../../decorators/controller.decorator.mjs'
-import { createClassContext } from '../context-compat.mjs'
 
 /**
  * Legacy-compatible Controller decorator.

package/src/legacy-compat/decorators/endpoint.decorator.mts

@@ -3,10 +3,10 @@ import type {
   EndpointOptions,
   RequestArgs,
 } from '@navios/builder'
+import { createMethodContext } from '@navios/di/legacy-compat'
 import type { z } from 'zod/v4'
 
 import { Endpoint as OriginalEndpoint } from '../../decorators/endpoint.decorator.mjs'
-import { createMethodContext } from '../context-compat.mjs'
 
 /**
  * Type helper to constrain a PropertyDescriptor's value to match an endpoint signature.

package/src/legacy-compat/decorators/header.decorator.mts

@@ -1,7 +1,8 @@
+import { createMethodContext } from '@navios/di/legacy-compat'
+
 import type { HttpHeader } from '../../interfaces/index.mjs'
 
 import { Header as OriginalHeader } from '../../decorators/header.decorator.mjs'
-import { createMethodContext } from '../context-compat.mjs'
 
 /**
  * Legacy-compatible Header decorator.

package/src/legacy-compat/decorators/http-code.decorator.mts

@@ -1,5 +1,6 @@
+import { createMethodContext } from '@navios/di/legacy-compat'
+
 import { HttpCode as OriginalHttpCode } from '../../decorators/http-code.decorator.mjs'
-import { createMethodContext } from '../context-compat.mjs'
 
 /**
  * Legacy-compatible HttpCode decorator.

package/src/legacy-compat/decorators/index.mts

@@ -6,6 +6,6 @@ export * from './header.decorator.mjs'
 export * from './http-code.decorator.mjs'
 export * from './multipart.decorator.mjs'
 export * from './stream.decorator.mjs'
-export * from './injectable.decorator.mjs'
-export * from './factory.decorator.mjs'
 
+// Re-export DI decorators from @navios/di/legacy-compat
+export { Injectable, Factory, type InjectableOptions, type FactoryOptions } from '@navios/di/legacy-compat'

package/src/legacy-compat/decorators/module.decorator.mts

@@ -1,7 +1,7 @@
 import type { ClassType } from '@navios/di'
+import { createClassContext } from '@navios/di/legacy-compat'
 
 import { Module as OriginalModule, type ModuleOptions } from '../../decorators/module.decorator.mjs'
-import { createClassContext } from '../context-compat.mjs'
 
 /**
  * Legacy-compatible Module decorator.

package/src/legacy-compat/decorators/multipart.decorator.mts

@@ -3,10 +3,10 @@ import type {
   EndpointOptions,
   RequestArgs,
 } from '@navios/builder'
+import { createMethodContext } from '@navios/di/legacy-compat'
 import type { z } from 'zod/v4'
 
 import { Multipart as OriginalMultipart } from '../../decorators/multipart.decorator.mjs'
-import { createMethodContext } from '../context-compat.mjs'
 
 /**
  * Type helper to constrain a PropertyDescriptor's value to match a multipart endpoint signature.

package/src/legacy-compat/decorators/stream.decorator.mts

@@ -3,9 +3,9 @@ import type {
   RequestArgs,
   StreamHandler,
 } from '@navios/builder'
+import { createMethodContext } from '@navios/di/legacy-compat'
 
 import { Stream as OriginalStream } from '../../decorators/stream.decorator.mjs'
-import { createMethodContext } from '../context-compat.mjs'
 
 /**
  * Type helper to constrain a PropertyDescriptor's value to match a stream endpoint signature.

package/src/legacy-compat/decorators/use-guards.decorator.mts

@@ -3,11 +3,11 @@ import type {
   ClassTypeWithInstance,
   InjectionToken,
 } from '@navios/di'
+import { createClassContext, createMethodContext } from '@navios/di/legacy-compat'
 
 import type { CanActivate } from '../../interfaces/index.mjs'
 
 import { UseGuards as OriginalUseGuards } from '../../decorators/use-guards.decorator.mjs'
-import { createClassContext, createMethodContext } from '../context-compat.mjs'
 
 /**
  * Legacy-compatible UseGuards decorator.

package/src/legacy-compat/index.mts

@@ -26,7 +26,7 @@ export type {
   StreamParams,
 } from '../decorators/index.mjs'
 
-// Export legacy-compatible decorators
+// Export legacy-compatible decorators (core-specific)
 export {
   Module,
   Controller,
@@ -36,9 +36,17 @@ export {
   HttpCode,
   Multipart,
   Stream,
+} from './decorators/index.mjs'
+
+// Re-export DI decorators and context utilities from @navios/di/legacy-compat
+export {
   Injectable,
   Factory,
-} from './decorators/index.mjs'
+  createClassContext,
+  createMethodContext,
+  type InjectableOptions,
+  type FactoryOptions,
+} from '@navios/di/legacy-compat'
 
 // Export legacy-compatible AttributeFactory
 export {
@@ -47,6 +55,3 @@ export {
   type LegacyClassAttribute,
   type LegacyClassSchemaAttribute,
 } from './attribute.factory.mjs'
-
-// Export context compatibility utilities
-export * from './context-compat.mjs'