@navios/core 0.6.0 → 0.7.1

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

@@ -1,4 +1,4 @@
-import type { ClassType, RequestContextHolder } from '@navios/di'
+import type { ClassType, ScopedContainer } from '@navios/di'
 
 import type { HandlerMetadata } from '../metadata/index.mjs'
 
@@ -9,5 +9,5 @@ export interface AbstractHttpHandlerAdapterInterface {
   provideHandler: (
     controller: ClassType,
     handlerMetadata: HandlerMetadata<any>,
-  ) => (context: RequestContextHolder, request: any, reply: any) => Promise<any>
+  ) => (context: ScopedContainer, request: any, reply: any) => Promise<any>
 }

package/src/interfaces/can-activate.mts

@@ -1,6 +1,37 @@
 import type { AbstractExecutionContext } from '../interfaces/index.mjs'
 
+/**
+ * Interface that guards must implement to control access to endpoints.
+ * 
+ * Guards are used for authentication, authorization, and request validation.
+ * They are executed before the endpoint handler and can prevent the request
+ * from proceeding by returning `false` or throwing an exception.
+ * 
+ * @example
+ * ```typescript
+ * @Injectable()
+ * export class AuthGuard implements CanActivate {
+ *   async canActivate(context: AbstractExecutionContext): Promise<boolean> {
+ *     const request = context.getRequest()
+ *     const token = request.headers.authorization
+ *     
+ *     if (!token) {
+ *       throw new UnauthorizedException('Authentication required')
+ *     }
+ *     
+ *     // Validate token
+ *     return true
+ *   }
+ * }
+ * ```
+ */
 export interface CanActivate {
+  /**
+   * Determines if the current request can proceed to the endpoint handler.
+   * 
+   * @param executionContext - The execution context containing request, reply, and metadata
+   * @returns `true` if the request can proceed, `false` otherwise. Can also throw an exception.
+   */
   canActivate(
     executionContext: AbstractExecutionContext,
   ): Promise<boolean> | boolean

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/navios-module.mts

@@ -1,3 +1,28 @@
+/**
+ * Interface that all Navios modules must implement.
+ * 
+ * Modules decorated with @Module() should implement this interface to receive
+ * lifecycle hooks.
+ * 
+ * @example
+ * ```typescript
+ * @Module({
+ *   controllers: [UserController],
+ * })
+ * export class AppModule implements NaviosModule {
+ *   async onModuleInit() {
+ *     console.log('AppModule initialized')
+ *     // Perform initialization logic
+ *   }
+ * }
+ * ```
+ */
 export interface NaviosModule {
+  /**
+   * Optional lifecycle hook called after the module is initialized.
+   * 
+   * This is called after all modules are loaded and the HTTP server is set up
+   * (if an adapter is configured), but before the server starts listening.
+   */
   onModuleInit?: () => Promise<void> | void
 }

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/__type-tests__/legacy-decorators.spec-d.mts

@@ -0,0 +1,420 @@
+// oxlint-disable no-unused-vars
+import { builder } from '@navios/builder'
+
+import { describe, expectTypeOf, test } from 'vitest'
+import { z } from 'zod/v4'
+
+import type {
+  EndpointParams,
+  EndpointResult,
+  MultipartParams,
+  MultipartResult,
+  StreamParams,
+} from '../index.mjs'
+
+import {
+  Controller,
+  Endpoint,
+  Header,
+  HttpCode,
+  Module,
+  Multipart,
+  Stream,
+  UseGuards,
+} from '../index.mjs'
+
+// Create a test API builder
+const api = builder()
+
+// Test schemas
+const responseSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+})
+
+const querySchema = z.object({
+  page: z.number(),
+  limit: z.number(),
+})
+
+const requestSchema = z.object({
+  name: z.string(),
+  email: z.string(),
+})
+
+const multipartRequestSchema = z.object({
+  file: z.instanceof(File),
+  description: z.string(),
+})
+
+// Test endpoint declarations
+const getUserEndpoint = api.declareEndpoint({
+  method: 'GET',
+  url: '/users/$userId',
+  querySchema,
+  responseSchema,
+})
+
+const createUserEndpoint = api.declareEndpoint({
+  method: 'POST',
+  url: '/users',
+  requestSchema,
+  responseSchema,
+})
+
+const uploadFileEndpoint = api.declareMultipart({
+  method: 'POST',
+  url: '/upload',
+  requestSchema: multipartRequestSchema,
+  responseSchema,
+})
+
+const downloadFileEndpoint = api.declareStream({
+  method: 'GET',
+  url: '/files/$fileId',
+  querySchema,
+})
+
+// Mock guard for testing
+class AuthGuard {
+  canActivate() {
+    return true
+  }
+}
+
+describe('Legacy Decorators Type Safety', () => {
+  describe('Module decorator', () => {
+    test('should accept valid module options', () => {
+      @Module({
+        controllers: [],
+        imports: [],
+        guards: [],
+      })
+      class TestModule {}
+
+      expectTypeOf(TestModule).toBeConstructibleWith()
+    })
+
+    test('should accept controllers in module', () => {
+      @Controller()
+      class TestController {}
+
+      @Module({
+        controllers: [TestController],
+      })
+      class TestModule {}
+
+      expectTypeOf(TestModule).toBeConstructibleWith()
+    })
+  })
+
+  describe('Controller decorator', () => {
+    test('should accept valid controller options', () => {
+      @Controller()
+      class TestController {}
+
+      expectTypeOf(TestController).toBeConstructibleWith()
+    })
+
+    test('should accept guards in controller', () => {
+      @Controller({
+        guards: [AuthGuard],
+      })
+      class TestController {}
+
+      expectTypeOf(TestController).toBeConstructibleWith()
+    })
+  })
+
+  describe('Endpoint decorator', () => {
+    test('should enforce correct parameter type', () => {
+      @Controller()
+      class UserController {
+        @Endpoint(getUserEndpoint)
+        async getUser(
+          request: EndpointParams<typeof getUserEndpoint>,
+        ): EndpointResult<typeof getUserEndpoint> {
+          // TypeScript should infer:
+          // - request.urlParams.userId: string | number
+          // - request.params.page: number
+          // - request.params.limit: number
+          expectTypeOf(request.urlParams.userId).toEqualTypeOf<
+            string | number
+          >()
+          expectTypeOf(request.params.page).toEqualTypeOf<number>()
+          expectTypeOf(request.params.limit).toEqualTypeOf<number>()
+          return {
+            id: request.urlParams.userId.toString(),
+            name: 'Test',
+          }
+        }
+      }
+
+      expectTypeOf(UserController).toBeConstructibleWith()
+    })
+
+    test('should enforce correct return type', () => {
+      @Controller()
+      class UserController {
+        @Endpoint(getUserEndpoint)
+        async getUser(
+          request: EndpointParams<typeof getUserEndpoint>,
+        ): EndpointResult<typeof getUserEndpoint> {
+          // Return type should match responseSchema
+          return {
+            id: '1',
+            name: 'John',
+          }
+        }
+      }
+
+      expectTypeOf(UserController).toBeConstructibleWith()
+    })
+
+    test('should reject incorrect parameter type', () => {
+      @Controller()
+      class UserController {
+        // @ts-expect-error - wrong parameter type
+        @Endpoint(getUserEndpoint)
+        async getUser(request: {
+          wrong: string
+        }): EndpointResult<typeof getUserEndpoint> {
+          return { id: '1', name: 'John' }
+        }
+      }
+    })
+
+    test('should reject incorrect return type', () => {
+      @Controller()
+      class UserController {
+        @Endpoint(getUserEndpoint)
+        async getUser(
+          request: EndpointParams<typeof getUserEndpoint>,
+        ): EndpointResult<typeof getUserEndpoint> {
+          // @ts-expect-error - wrong return type
+          return { wrong: 'value' }
+        }
+      }
+    })
+
+    test('should work with POST endpoint with request body', () => {
+      @Controller()
+      class UserController {
+        @Endpoint(createUserEndpoint)
+        async createUser(
+          request: EndpointParams<typeof createUserEndpoint>,
+        ): EndpointResult<typeof createUserEndpoint> {
+          // TypeScript should infer:
+          // - request.data.name: string
+          // - request.data.email: string
+          expectTypeOf(request.data.name).toEqualTypeOf<string>()
+          expectTypeOf(request.data.email).toEqualTypeOf<string>()
+          return {
+            id: '1',
+            name: request.data.name,
+          }
+        }
+      }
+
+      expectTypeOf(UserController).toBeConstructibleWith()
+    })
+  })
+
+  describe('Multipart decorator', () => {
+    test('should enforce correct parameter type', () => {
+      @Controller()
+      class FileController {
+        @Multipart(uploadFileEndpoint)
+        async uploadFile(
+          request: MultipartParams<typeof uploadFileEndpoint>,
+        ): MultipartResult<typeof uploadFileEndpoint> {
+          // TypeScript should infer:
+          // - request.data.file: File
+          // - request.data.description: string
+          expectTypeOf(request.data.file).toEqualTypeOf<File>()
+          expectTypeOf(request.data.description).toEqualTypeOf<string>()
+          return {
+            id: '1',
+            name: 'uploaded.jpg',
+          }
+        }
+      }
+
+      expectTypeOf(FileController).toBeConstructibleWith()
+    })
+
+    test('should reject incorrect parameter type', () => {
+      @Controller()
+      class FileController {
+        // @ts-expect-error - wrong parameter type
+        @Multipart(uploadFileEndpoint)
+        async uploadFile(request: {
+          wrong: string
+        }): MultipartResult<typeof uploadFileEndpoint> {
+          return { id: '1', name: 'test.jpg' }
+        }
+      }
+    })
+  })
+
+  describe('Stream decorator', () => {
+    test('should enforce correct parameter type', () => {
+      @Controller()
+      class FileController {
+        @Stream(downloadFileEndpoint)
+        async downloadFile(
+          request: StreamParams<typeof downloadFileEndpoint>,
+          reply: any,
+        ): Promise<void> {
+          // TypeScript should infer:
+          // - request.urlParams.fileId: string | number
+          // - request.params.page: number
+          // - request.params.limit: number
+          expectTypeOf(request.urlParams.fileId).toEqualTypeOf<
+            string | number
+          >()
+          expectTypeOf(request.params.page).toEqualTypeOf<number>()
+          expectTypeOf(request.params.limit).toEqualTypeOf<number>()
+        }
+      }
+
+      expectTypeOf(FileController).toBeConstructibleWith()
+    })
+
+    test('should require reply parameter', () => {
+      @Controller()
+      class FileController {
+        // @ts-expect-error - missing reply parameter
+        @Stream(downloadFileEndpoint)
+        async downloadFile(
+          request: StreamParams<typeof downloadFileEndpoint>,
+        ): Promise<void> {
+          // Stream methods must have reply parameter
+        }
+      }
+    })
+  })
+
+  describe('UseGuards decorator', () => {
+    test('should work on class level', () => {
+      @Controller()
+      @UseGuards(AuthGuard)
+      class ProtectedController {
+        @Endpoint(getUserEndpoint)
+        async getUser(
+          request: EndpointParams<typeof getUserEndpoint>,
+        ): EndpointResult<typeof getUserEndpoint> {
+          return { id: '1', name: 'John' }
+        }
+      }
+
+      expectTypeOf(ProtectedController).toBeConstructibleWith()
+    })
+
+    test('should work on method level', () => {
+      @Controller()
+      class UserController {
+        @Endpoint(getUserEndpoint)
+        @UseGuards(AuthGuard)
+        async getUser(
+          request: EndpointParams<typeof getUserEndpoint>,
+        ): EndpointResult<typeof getUserEndpoint> {
+          return { id: '1', name: 'John' }
+        }
+      }
+
+      expectTypeOf(UserController).toBeConstructibleWith()
+    })
+  })
+
+  describe('Header decorator', () => {
+    test('should work with string value', () => {
+      @Controller()
+      class UserController {
+        @Endpoint(getUserEndpoint)
+        @Header('Cache-Control', 'max-age=3600')
+        async getUser(
+          request: EndpointParams<typeof getUserEndpoint>,
+        ): EndpointResult<typeof getUserEndpoint> {
+          return { id: '1', name: 'John' }
+        }
+      }
+
+      expectTypeOf(UserController).toBeConstructibleWith()
+    })
+
+    test('should work with number value', () => {
+      @Controller()
+      class UserController {
+        @Endpoint(getUserEndpoint)
+        @Header('Content-Length', 100)
+        async getUser(
+          request: EndpointParams<typeof getUserEndpoint>,
+        ): EndpointResult<typeof getUserEndpoint> {
+          return { id: '1', name: 'John' }
+        }
+      }
+
+      expectTypeOf(UserController).toBeConstructibleWith()
+    })
+  })
+
+  describe('HttpCode decorator', () => {
+    test('should accept valid status codes', () => {
+      @Controller()
+      class UserController {
+        @Endpoint(createUserEndpoint)
+        @HttpCode(201)
+        async createUser(
+          request: EndpointParams<typeof createUserEndpoint>,
+        ): EndpointResult<typeof createUserEndpoint> {
+          return { id: '1', name: request.data.name }
+        }
+      }
+
+      expectTypeOf(UserController).toBeConstructibleWith()
+    })
+  })
+
+  describe('Integration test - full controller', () => {
+    test('should work with all decorators together', () => {
+      @Controller({
+        guards: [AuthGuard],
+      })
+      @UseGuards(AuthGuard)
+      class UserController {
+        @Endpoint(getUserEndpoint)
+        @UseGuards(AuthGuard)
+        @Header('Cache-Control', 'max-age=3600')
+        @HttpCode(200)
+        async getUser(
+          request: EndpointParams<typeof getUserEndpoint>,
+        ): EndpointResult<typeof getUserEndpoint> {
+          return {
+            id: request.urlParams.userId.toString(),
+            name: 'John',
+          }
+        }
+
+        @Endpoint(createUserEndpoint)
+        @HttpCode(201)
+        async createUser(
+          request: EndpointParams<typeof createUserEndpoint>,
+        ): EndpointResult<typeof createUserEndpoint> {
+          return {
+            id: '1',
+            name: request.data.name,
+          }
+        }
+      }
+
+      @Module({
+        controllers: [UserController],
+      })
+      class AppModule {}
+
+      expectTypeOf(UserController).toBeConstructibleWith()
+      expectTypeOf(AppModule).toBeConstructibleWith()
+    })
+  })
+})

package/src/legacy-compat/__type-tests__/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "extends": "../../../../../tsconfig.base.json",
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": false,
+    "outDir": "../../../dist/legacy-compat/__type-tests__"
+  },
+  "include": ["**/*.spec-d.mts"],
+  "exclude": [],
+  "references": [
+    {
+      "path": "../../../tsconfig.lib.json"
+    }
+  ]
+}