@navios/core 0.7.0 → 0.8.0

package/src/decorators/stream.decorator.mts

@@ -11,9 +11,9 @@ import { StreamAdapterToken } from '../tokens/index.mjs'
 
 /**
  * Extracts the typed parameters for a stream endpoint handler function.
- * 
+ *
  * Similar to `EndpointParams`, but specifically for streaming endpoints.
- * 
+ *
  * @typeParam EndpointDeclaration - The stream endpoint declaration from @navios/builder
  */
 export type StreamParams<
@@ -46,20 +46,20 @@ export type StreamParams<
 
 /**
  * Decorator that marks a method as a streaming endpoint.
- * 
+ *
  * Use this decorator for endpoints that stream data (e.g., file downloads, SSE).
  * The endpoint must be defined using @navios/builder's `declareStream` method.
- * 
+ *
  * @param endpoint - The stream endpoint declaration from @navios/builder
  * @returns A method decorator
- * 
+ *
  * @example
  * ```typescript
  * const downloadFileEndpoint = api.declareStream({
  *   method: 'get',
  *   url: '/files/$fileId',
  * })
- * 
+ *
  * @Controller()
  * export class FileController {
  *   @Stream(downloadFileEndpoint)
@@ -70,6 +70,51 @@ export type StreamParams<
  * }
  * ```
  */
+export function Stream<
+  Method extends HttpMethod = HttpMethod,
+  Url extends string = string,
+  QuerySchema = undefined,
+  RequestSchema = ZodType,
+  Params = QuerySchema extends ZodObject
+    ? RequestSchema extends ZodType
+      ? EndpointFunctionArgs<Url, QuerySchema, RequestSchema, true>
+      : EndpointFunctionArgs<Url, QuerySchema, undefined, true>
+    : RequestSchema extends ZodType
+      ? EndpointFunctionArgs<Url, undefined, RequestSchema, true>
+      : EndpointFunctionArgs<Url, undefined, undefined, true>,
+>(endpoint: {
+  config: BaseStreamConfig<Method, Url, QuerySchema, RequestSchema>
+}): (
+  target: (params: Params, reply: any) => any,
+  context: ClassMethodDecoratorContext,
+) => void
+// Bun doesn't support reply parameter
+export function Stream<
+  Method extends HttpMethod = HttpMethod,
+  Url extends string = string,
+  QuerySchema = undefined,
+  RequestSchema = ZodType,
+  Params = QuerySchema extends ZodObject
+    ? RequestSchema extends ZodType
+      ? EndpointFunctionArgs<Url, QuerySchema, RequestSchema, true>
+      : EndpointFunctionArgs<Url, QuerySchema, undefined, true>
+    : RequestSchema extends ZodType
+      ? EndpointFunctionArgs<Url, undefined, RequestSchema, true>
+      : EndpointFunctionArgs<Url, undefined, undefined, true>,
+>(endpoint: {
+  config: BaseStreamConfig<Method, Url, QuerySchema, RequestSchema>
+}): (
+  target: (params: Params) => any,
+  context: ClassMethodDecoratorContext,
+) => void
+export function Stream<
+  Method extends HttpMethod = HttpMethod,
+  Url extends string = string,
+  QuerySchema = undefined,
+  RequestSchema = ZodType,
+>(endpoint: {
+  config: BaseStreamConfig<Method, Url, QuerySchema, RequestSchema>
+}): (target: () => any, context: ClassMethodDecoratorContext) => void
 export function Stream<
   Method extends HttpMethod = HttpMethod,
   Url extends string = string,
@@ -78,24 +123,20 @@ export function Stream<
 >(endpoint: {
   config: BaseStreamConfig<Method, Url, QuerySchema, RequestSchema>
 }) {
-  return (
-    target: (
-      params: QuerySchema extends ZodObject
-        ? RequestSchema extends ZodType
-          ? EndpointFunctionArgs<Url, QuerySchema, RequestSchema>
-          : EndpointFunctionArgs<Url, QuerySchema, undefined>
-        : RequestSchema extends ZodType
-          ? EndpointFunctionArgs<Url, undefined, RequestSchema>
-          : EndpointFunctionArgs<Url, undefined, undefined>,
-      reply: any,
-    ) => Promise<void>,
-    context: ClassMethodDecoratorContext,
-  ) => {
-    if (typeof target !== 'function') {
-      throw new Error(
-        '[Navios] Endpoint decorator can only be used on functions.',
-      )
-    }
+  type Params = QuerySchema extends ZodObject
+    ? RequestSchema extends ZodType
+      ? EndpointFunctionArgs<Url, QuerySchema, RequestSchema, true>
+      : EndpointFunctionArgs<Url, QuerySchema, undefined, true>
+    : RequestSchema extends ZodType
+      ? EndpointFunctionArgs<Url, undefined, RequestSchema, true>
+      : EndpointFunctionArgs<Url, undefined, undefined, true>
+
+  type Handler =
+    | ((params: Params, reply: any) => any)
+    | ((params: Params) => any)
+    | (() => any)
+
+  return (target: Handler, context: ClassMethodDecoratorContext) => {
     if (context.kind !== 'method') {
       throw new Error(
         '[Navios] Endpoint decorator can only be used on methods.',

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

@@ -2,19 +2,71 @@ 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'
 
+/**
+ * Abstract interface for HTTP adapters.
+ *
+ * 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
+ */
 export interface AbstractHttpAdapterInterface<
   ServerInstance,
   CorsOptions = AbstractHttpCorsOptions,
   Options = {},
   MultipartOptions = {},
 > {
+  /**
+   * Sets up the HTTP server with the provided options.
+   */
   setupHttpServer(options: Options): Promise<void>
+
+  /**
+   * Called after all modules are loaded to register routes.
+   */
   onModulesInit(modules: Map<string, ModuleMetadata>): Promise<void>
+
+  /**
+   * Signals that the server is ready to accept requests.
+   */
   ready(): Promise<void>
+
+  /**
+   * Returns the underlying HTTP server instance.
+   */
   getServer(): ServerInstance
+
+  /**
+   * Sets a global prefix for all routes.
+   */
   setGlobalPrefix(prefix: string): void
+
+  /**
+   * Gets the current global prefix.
+   * Returns empty string if no prefix is set.
+   */
+  getGlobalPrefix(): string
+
+  /**
+   * Enables CORS with the specified options.
+   */
   enableCors(options: CorsOptions): void
+
+  /**
+   * Enables multipart form data handling.
+   */
   enableMultipart(options: MultipartOptions): void
+
+  /**
+   * Starts the server and listens for incoming requests.
+   */
   listen(options: AbstractHttpListenOptions): Promise<string>
+
+  /**
+   * Disposes of the server and cleans up resources.
+   */
   dispose(): Promise<void>
 }

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

@@ -2,6 +2,36 @@ import type { ClassType, ScopedContainer } from '@navios/di'
 
 import type { HandlerMetadata } from '../metadata/index.mjs'
 
+/**
+ * Static handler result - handler can be called without a scoped container.
+ * Used when the controller and all its dependencies are singletons.
+ */
+export type StaticHandler<TRequest = any, TReply = any> = {
+  isStatic: true
+  handler: (request: TRequest, reply: TReply) => Promise<any>
+}
+
+/**
+ * Dynamic handler result - handler requires a scoped container for resolution.
+ * Used when the controller or its dependencies need per-request resolution.
+ */
+export type DynamicHandler<TRequest = any, TReply = any> = {
+  isStatic: false
+  handler: (
+    scoped: ScopedContainer,
+    request: TRequest,
+    reply: TReply,
+  ) => Promise<any>
+}
+
+/**
+ * Handler result returned by provideHandler.
+ * Can be either static (pre-resolved) or dynamic (needs scoped container).
+ */
+export type HandlerResult<TRequest = any, TReply = any> =
+  | StaticHandler<TRequest, TReply>
+  | DynamicHandler<TRequest, TReply>
+
 export interface AbstractHttpHandlerAdapterInterface {
   prepareArguments?: (
     handlerMetadata: HandlerMetadata<any>,
@@ -9,5 +39,5 @@ export interface AbstractHttpHandlerAdapterInterface {
   provideHandler: (
     controller: ClassType,
     handlerMetadata: HandlerMetadata<any>,
-  ) => (context: ScopedContainer, request: any, reply: any) => Promise<any>
+  ) => Promise<HandlerResult>
 }

package/src/interfaces/index.mts

@@ -6,3 +6,4 @@ export * from './abstract-http-listen-options.interface.mjs'
 export * from './can-activate.mjs'
 export * from './http-header.mjs'
 export * from './navios-module.mjs'
+export * from './plugin.interface.mjs'

package/src/interfaces/plugin.interface.mts

@@ -0,0 +1,105 @@
+import type { Container } from '@navios/di'
+
+import type { ModuleMetadata } from '../metadata/index.mjs'
+import type { ModuleLoaderService } from '../services/module-loader.service.mjs'
+
+/**
+ * Context provided to plugins during registration.
+ *
+ * This context gives plugins access to the application's modules,
+ * server instance, DI container, and configuration.
+ */
+export interface PluginContext {
+  /**
+   * All loaded modules with their metadata.
+   * Keys are module class names, values are their metadata.
+   */
+  modules: Map<string, ModuleMetadata>
+
+  /**
+   * The underlying HTTP server instance.
+   * Type depends on the adapter used (Fastify, Bun, etc.)
+   */
+  server: any
+
+  /**
+   * 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.
+   */
+  moduleLoader: ModuleLoaderService
+}
+
+/**
+ * Base interface for Navios plugins.
+ *
+ * Plugins are registered using `app.usePlugin()` and are initialized
+ * after all modules are loaded but before the server starts listening.
+ *
+ * @typeParam TOptions - The type of options the plugin accepts
+ *
+ * @example
+ * ```typescript
+ * const myPlugin: NaviosPlugin<{ enabled: boolean }> = {
+ *   name: 'my-plugin',
+ *   register: async (context, options) => {
+ *     if (options.enabled) {
+ *       // Register routes, services, etc.
+ *     }
+ *   },
+ * }
+ * ```
+ */
+export interface NaviosPlugin<TOptions = unknown> {
+  /**
+   * Plugin name for identification and logging.
+   */
+  name: string
+
+  /**
+   * Called after modules are loaded but before the server starts listening.
+   *
+   * @param context - The plugin context with access to modules and server
+   * @param options - Plugin-specific configuration options
+   */
+  register(context: PluginContext, options: TOptions): Promise<void> | void
+}
+
+/**
+ * Plugin definition combining a plugin with its options.
+ *
+ * This is the type returned by plugin factory functions like `defineOpenApiPlugin()`.
+ *
+ * @typeParam TOptions - The type of options the plugin accepts
+ *
+ * @example
+ * ```typescript
+ * function defineMyPlugin(options: MyPluginOptions): PluginDefinition<MyPluginOptions> {
+ *   return {
+ *     plugin: myPlugin,
+ *     options,
+ *   }
+ * }
+ * ```
+ */
+export interface PluginDefinition<TOptions = unknown> {
+  /**
+   * The plugin instance.
+   */
+  plugin: NaviosPlugin<TOptions>
+
+  /**
+   * Options to pass to the plugin's register function.
+   */
+  options: TOptions
+}

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

@@ -92,7 +92,7 @@ export function Endpoint<
     // @ts-expect-error - we don't need to type the value
     const result = originalDecorator(typedDescriptor.value, context)
     if (result !== typedDescriptor.value) {
-      typedDescriptor.value = result
+      typedDescriptor.value = result as any
     }
     return typedDescriptor
   }

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

@@ -86,7 +86,7 @@ export function Multipart<
     // @ts-expect-error - we don't need to type the value
     const result = originalDecorator(descriptor.value, context)
     if (result !== descriptor.value) {
-      descriptor.value = result
+      descriptor.value = result as any
     }
     return descriptor
   }

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

@@ -69,7 +69,7 @@ export function Stream<
     // @ts-expect-error - we don't need to type the value
     const result = originalDecorator(descriptor.value, context)
     if (result !== descriptor.value) {
-      descriptor.value = result
+      descriptor.value = result as any
     }
     return descriptor
   }

package/src/logger/logger.service.mts

@@ -7,16 +7,16 @@ import { Logger, LoggerOutput } from './logger.tokens.mjs'
 
 /**
  * Logger service instance that can be injected into services and controllers.
- * 
+ *
  * Provides contextualized logging with automatic context injection.
  * The context is set when the logger is injected using the `inject` function.
- * 
+ *
  * @example
  * ```typescript
  * @Injectable()
  * export class UserService {
  *   private logger = inject(Logger, { context: UserService.name })
- *   
+ *
  *   async findUser(id: string) {
  *     this.logger.log(`Finding user ${id}`)
  *     // Logs with context: [UserService]

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()
@@ -54,20 +55,34 @@ export interface NaviosApplicationOptions
    * ```
    */
   adapter: NaviosEnvironmentOptions | NaviosEnvironmentOptions[]
+
+  /**
+   * Whether to validate response schemas.
+   * When `false`, response schema validation is skipped for better performance.
+   * @default true
+   */
+  validateResponses?: boolean
+
+  /**
+   * Whether to enable request ID propagation via AsyncLocalStorage.
+   * When `true`, request IDs are available via `getRequestId()` throughout the request.
+   * @default false
+   */
+  enableRequestId?: boolean
 }
 
 /**
  * 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 +103,7 @@ export class NaviosApplication {
   private options: NaviosApplicationOptions = {
     adapter: [],
   }
+  private plugins: PluginDefinition<any>[] = []
 
   /**
    * Indicates whether the application has been initialized.
@@ -98,7 +114,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 +134,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 +195,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 +210,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 +257,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 +279,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 +298,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 +321,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 +339,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 +354,9 @@ export class NaviosApplication {
 
   /**
    * Closes the application and cleans up all resources.
-   * 
+   *
    * This is an alias for `dispose()`.
-   * 
+   *
    * @example
    * ```typescript
    * // Graceful shutdown