@navios/core 0.6.0 → 0.7.1

package/src/logger/log-levels.mts

@@ -1,3 +1,6 @@
+/**
+ * Available log levels in order of severity (lowest to highest).
+ */
 export const LOG_LEVELS = [
   'verbose',
   'debug',
@@ -6,7 +9,13 @@ export const LOG_LEVELS = [
   'error',
   'fatal',
 ] as const satisfies string[]
+
 /**
+ * Log level type.
+ * 
+ * Represents the severity level of a log message.
+ * Levels are: 'verbose', 'debug', 'log', 'warn', 'error', 'fatal'
+ * 
  * @publicApi
  */
 export type LogLevel = (typeof LOG_LEVELS)[number]

package/src/logger/logger.service.mts

@@ -5,6 +5,25 @@ import type { LoggerOptions } from './logger.tokens.mjs'
 
 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]
+ *   }
+ * }
+ * ```
+ */
 @Injectable({
   token: Logger,
 })
@@ -41,6 +60,8 @@ export class LoggerInstance implements LoggerService {
     optionalParams = this.context
       ? optionalParams.concat(this.context)
       : optionalParams
+    console.log('log', message, optionalParams)
+    console.log('localInstance', this.localInstance)
     this.localInstance?.log(message, ...optionalParams)
   }
 

package/src/logger/logger.tokens.mts

@@ -5,16 +5,39 @@ import z from 'zod/v4'
 import type { LoggerService } from './logger-service.interface.mjs'
 import type { LoggerInstance } from './logger.service.mjs'
 
+/**
+ * Injection token for the logger output service.
+ * 
+ * This token is used to provide a custom logger implementation.
+ * By default, it's bound to ConsoleLogger.
+ */
 export const LoggerOutput = InjectionToken.create<LoggerService>('LoggerOutput')
 
+/**
+ * Schema for logger options.
+ */
 export const loggerOptionsSchema = z
   .object({
     context: z.string().optional(),
   })
   .optional()
 
+/**
+ * Options for creating a logger instance.
+ */
 export type LoggerOptions = z.infer<typeof loggerOptionsSchema>
 
+/**
+ * Injection token for the Logger service.
+ * 
+ * Use this token to inject a contextualized logger instance.
+ * 
+ * @example
+ * ```typescript
+ * const logger = inject(Logger, { context: 'MyService' })
+ * logger.log('Hello world') // Logs with context: [MyService]
+ * ```
+ */
 export const Logger = InjectionToken.create<
   LoggerInstance,
   typeof loggerOptionsSchema

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'
@@ -15,19 +17,64 @@ import { Logger } from './logger/index.mjs'
 import { NaviosEnvironment } from './navios.environment.mjs'
 import { ModuleLoaderService } from './services/index.mjs'
 
+/**
+ * Options for configuring the Navios application context.
+ * These options control dependency injection and logging behavior.
+ */
 export interface NaviosApplicationContextOptions {
   /**
-   * Specifies the logger to use.  Pass `false` to turn off logging.
+   * 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
    */
   logger?: LoggerService | LogLevel[] | false
+
+  /**
+   * Specifies a custom container to use. Useful for testing.
+   * If not provided, a new Container will be created.
+   */
+  container?: Container
 }
 
-export interface NaviosApplicationOptions
-  extends NaviosApplicationContextOptions {
-  // Fastify server options will be handled by FastifyApplicationService
+/**
+ * Complete options for creating a Navios application.
+ * Extends NaviosApplicationContextOptions with adapter configuration.
+ */
+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()
+   * // or
+   * adapter: [defineFastifyEnvironment(), defineBunEnvironment()]
+   * ```
+   */
   adapter: NaviosEnvironmentOptions | NaviosEnvironmentOptions[]
 }
 
+/**
+ * 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()
+ * await app.listen({ port: 3000, host: '0.0.0.0' })
+ * ```
+ */
 @Injectable()
 export class NaviosApplication {
   private environment = inject(NaviosEnvironment)
@@ -42,9 +89,22 @@ export class NaviosApplication {
   private options: NaviosApplicationOptions = {
     adapter: [],
   }
+  private plugins: PluginDefinition<any>[] = []
 
+  /**
+   * Indicates whether the application has been initialized.
+   * Set to `true` after `init()` completes successfully.
+   */
   isInitialized = false
 
+  /**
+   * 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
+   */
   async setup(
     appModule: ClassTypeWithInstance<NaviosModule>,
     options: NaviosApplicationOptions = {
@@ -58,10 +118,61 @@ 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, {
+   *   adapter: defineFastifyEnvironment(),
+   * })
+   * await app.init()
+   * await app.listen({ port: 3000 })
+   * ```
+   */
   async init() {
     if (!this.appModule) {
       throw new Error('App module is not set. Call setAppModule() first.')
@@ -70,6 +181,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()
@@ -84,6 +196,44 @@ 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({
+   *   origin: ['http://localhost:3000', 'https://example.com'],
+   *   methods: ['GET', 'POST', 'PUT', 'DELETE'],
+   *   credentials: true,
+   * })
+   * ```
+   */
   enableCors(options: any) {
     if (!this.httpApplication) {
       throw new Error('HTTP application is not set')
@@ -91,6 +241,21 @@ export class NaviosApplication {
     this.httpApplication.enableCors(options)
   }
 
+  /**
+   * 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({
+   *   limits: {
+   *     fileSize: 1024 * 1024 * 10, // 10MB
+   *   },
+   * })
+   * ```
+   */
   enableMultipart(options: any) {
     if (!this.httpApplication) {
       throw new Error('HTTP application is not set')
@@ -98,6 +263,18 @@ export class NaviosApplication {
     this.httpApplication.enableMultipart(options)
   }
 
+  /**
+   * 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')
+   * // All routes will be prefixed with /api/v1
+   * ```
+   */
   setGlobalPrefix(prefix: string) {
     if (!this.httpApplication) {
       throw new Error('HTTP application is not set')
@@ -105,6 +282,22 @@ export class NaviosApplication {
     this.httpApplication.setGlobalPrefix(prefix)
   }
 
+  /**
+   * 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()
+   * // Use adapter-specific server methods
+   * ```
+   */
   getServer() {
     if (!this.httpApplication) {
       throw new Error('HTTP application is not set')
@@ -112,6 +305,17 @@ export class NaviosApplication {
     return this.httpApplication.getServer()
   }
 
+  /**
+   * 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' })
+   * ```
+   */
   async listen(options: AbstractHttpListenOptions) {
     if (!this.httpApplication) {
       throw new Error('HTTP application is not set')
@@ -119,6 +323,12 @@ export class NaviosApplication {
     await this.httpApplication.listen(options)
   }
 
+  /**
+   * Disposes of application resources.
+   *
+   * Cleans up the HTTP server and module loader.
+   * This method is called automatically by `close()`.
+   */
   async dispose() {
     if (this.httpApplication) {
       await this.httpApplication.dispose()
@@ -128,6 +338,20 @@ export class NaviosApplication {
     }
   }
 
+  /**
+   * Closes the application and cleans up all resources.
+   *
+   * This is an alias for `dispose()`.
+   *
+   * @example
+   * ```typescript
+   * // Graceful shutdown
+   * process.on('SIGTERM', async () => {
+   *   await app.close()
+   *   process.exit(0)
+   * })
+   * ```
+   */
   async close() {
     await this.dispose()
   }

package/src/navios.factory.mts

@@ -16,14 +16,72 @@ import { ConsoleLogger, isNil, LoggerOutput } from './logger/index.mjs'
 import { NaviosApplication } from './navios.application.mjs'
 import { NaviosEnvironment } from './navios.environment.mjs'
 
+/**
+ * Factory class for creating and configuring Navios applications.
+ *
+ * This is the main entry point for bootstrapping a Navios application.
+ * It handles dependency injection container setup, adapter registration,
+ * and logger configuration.
+ *
+ * @example
+ * ```typescript
+ * import { NaviosFactory } from '@navios/core'
+ * import { defineFastifyEnvironment } from '@navios/adapter-fastify'
+ *
+ * const app = await NaviosFactory.create(AppModule, {
+ *   adapter: defineFastifyEnvironment(),
+ *   logger: ['log', 'error', 'warn'],
+ * })
+ *
+ * await app.init()
+ * await app.listen({ port: 3000 })
+ * ```
+ */
 export class NaviosFactory {
+  /**
+   * Creates a new Navios application instance.
+   *
+   * This method sets up the dependency injection container, registers the HTTP adapter,
+   * configures logging, and initializes the application with the provided module.
+   *
+   * @param appModule - The root application module class decorated with @Module()
+   * @param options - Configuration options for the application
+   * @param options.adapter - HTTP adapter environment (required for HTTP server functionality)
+   * @param options.logger - Logger configuration. Can be:
+   *   - A LoggerService instance for custom logging
+   *   - An array of LogLevel strings to enable specific log levels
+   *   - `false` to disable logging
+   * @param options.container - Optional custom dependency injection container (useful for testing)
+   * @returns A configured NaviosApplication instance ready to be initialized
+   *
+   * @example
+   * ```typescript
+   * // Basic setup with Fastify adapter
+   * const app = await NaviosFactory.create(AppModule, {
+   *   adapter: defineFastifyEnvironment(),
+   * })
+   *
+   * // With custom logger configuration
+   * const app = await NaviosFactory.create(AppModule, {
+   *   adapter: defineFastifyEnvironment(),
+   *   logger: ['error', 'warn', 'log'],
+   * })
+   *
+   * // With custom container for testing
+   * const container = new Container()
+   * const app = await NaviosFactory.create(AppModule, {
+   *   adapter: defineFastifyEnvironment(),
+   *   container,
+   * })
+   * ```
+   */
   static async create(
     appModule: ClassTypeWithInstance<NaviosModule>,
     options: NaviosApplicationOptions = {
       adapter: [],
     },
   ) {
-    const container = new Container()
+    const container = options.container ?? new Container()
     await this.registerLoggerConfiguration(container, options)
     const adapters = Array.isArray(options.adapter)
       ? options.adapter
@@ -61,6 +119,7 @@ export class NaviosFactory {
       loggerInstance?.setup({
         logLevels: logger,
       })
+      return
     }
     if ((logger as boolean) !== true && !isNil(logger)) {
       container

package/src/services/guard-runner.service.mts

@@ -1,6 +1,6 @@
-import type { ClassTypeWithInstance } from '@navios/di'
+import type { ClassTypeWithInstance, ScopedContainer } from '@navios/di'
 
-import { Container, inject, Injectable, InjectionToken } from '@navios/di'
+import { inject, Injectable, InjectionToken } from '@navios/di'
 
 import type {
   AbstractExecutionContext,
@@ -13,20 +13,24 @@ import type {
 } from '../metadata/index.mjs'
 
 import { HttpException } from '../exceptions/index.mjs'
+import { Logger } from '../logger/index.mjs'
 
 @Injectable()
 export class GuardRunnerService {
-  protected container = inject(Container)
+  private readonly logger = inject(Logger, {
+    context: GuardRunnerService.name,
+  })
   async runGuards(
     allGuards: Set<
       | ClassTypeWithInstance<CanActivate>
       | InjectionToken<CanActivate, undefined>
     >,
     executionContext: AbstractExecutionContext,
+    context: ScopedContainer,
   ) {
     let canActivate = true
     for (const guard of Array.from(allGuards).reverse()) {
-      const guardInstance = await this.container.get(
+      const guardInstance = await context.get(
         guard as InjectionToken<CanActivate, undefined>,
       )
       if (!guardInstance.canActivate) {
@@ -47,13 +51,10 @@ export class GuardRunnerService {
             .send(error.response)
           return false
         } else {
-          executionContext
-            .getReply()
-            .status(500)
-            .send({
-              message: 'Internal server error',
-              error: (error as Error).message,
-            })
+          this.logger.error('Error running guard', error)
+          executionContext.getReply().status(500).send({
+            message: 'Internal server error',
+          })
           return false
         }
       }