@navios/core 0.5.1 → 0.7.0

package/CHANGELOG.md

@@ -0,0 +1,93 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.7.0] - 2025-12-18
+
+### Added
+
+- **Testing Module**: New `TestingModule` class and `createTestingModule` function for easier testing setup with dependency overrides
+- **Config Service**: New `ConfigService` for managing application configuration with type-safe access
+- **Logger System**: Comprehensive logging system with multiple log levels (error, warn, log, debug, verbose, fatal) and customizable output
+- **Attribute Factory**: `AttributeFactory` for creating custom metadata decorators that can be applied to modules, controllers, and endpoints
+- **Exception Classes**: Complete set of HTTP exception classes:
+  - `HttpException` (base class)
+  - `BadRequestException`
+  - `UnauthorizedException`
+  - `ForbiddenException`
+  - `NotFoundException`
+  - `ConflictException`
+  - `InternalServerErrorException`
+- **Decorators**: Full set of decorators for building Navios applications:
+  - `@Module()` - Define application modules
+  - `@Controller()` - Define request controllers
+  - `@Endpoint()` - Define HTTP endpoints with type-safe request/response schemas
+  - `@Multipart()` - Define multipart/form-data endpoints for file uploads
+  - `@Stream()` - Define streaming endpoints
+  - `@UseGuards()` - Apply guards to controllers or endpoints
+  - `@Header()` - Set custom response headers
+  - `@HttpCode()` - Set custom HTTP status codes
+- **Legacy-Compatible Decorators**: Complete set of decorators compatible with TypeScript experimental decorators, available from `@navios/core/legacy-compat`:
+  - All standard decorators (`@Module`, `@Controller`, `@Endpoint`, `@Multipart`, `@Stream`, `@UseGuards`, `@Header`, `@HttpCode`) with legacy decorator API support
+  - Seamless conversion from experimental decorator format to Stage 3 format internally
+  - Full type safety and feature parity with standard decorators
+- **Core Application APIs**:
+  - `NaviosFactory.create()` - Factory method for creating Navios applications
+  - `NaviosApplication` - Main application class with methods for:
+    - `init()` - Initialize the application
+    - `listen()` - Start the HTTP server
+    - `setGlobalPrefix()` - Set a global URL prefix
+    - `enableCors()` - Enable CORS support
+    - `enableMultipart()` - Enable multipart/form-data support
+    - `getServer()` - Get the underlying HTTP server instance
+    - `getContainer()` - Get the dependency injection container
+    - `dispose()` / `close()` - Clean up resources
+- **Guards System**: `CanActivate` interface for implementing request guards (authentication, authorization, etc.)
+- **Type Utilities**: Type-safe utilities for endpoint parameters and results:
+  - `EndpointParams<T>` - Extract typed parameters from endpoint definitions
+  - `EndpointResult<T>` - Extract typed return values from endpoint definitions
+  - `MultipartParams<T>` - Extract typed parameters for multipart endpoints
+  - `StreamParams<T>` - Extract typed parameters for stream endpoints
+- **Dependency Injection**: Full integration with `@navios/di` for dependency injection
+- **Adapter Support**: Adapter-based architecture supporting multiple HTTP server implementations (Fastify, Bun)
+
+### Features
+
+- **Type Safety**: Full TypeScript support with type inference for endpoints, requests, and responses
+- **Zod Integration**: Built-in support for Zod schema validation for request/response validation
+- **Modular Architecture**: Organize code into modules with clear boundaries and dependency management
+- **Extensible**: Custom attributes system for adding metadata to modules, controllers, and endpoints
+- **Testing Support**: Comprehensive testing utilities for unit and integration tests
+
+### Documentation
+
+- Complete README with getting started guide
+- Comprehensive documentation in `/docs` covering:
+  - Quick Start Guide
+  - Application Setup and Configuration
+  - Modules, Controllers, and Endpoints
+  - Services and Dependency Injection
+  - Guards and Exception Handling
+  - Attributes System
+  - HTTP Server Adapters
+  - Testing Guide
+
+### Dependencies
+
+- `@navios/di` - Dependency injection container
+- `@navios/builder` (peer dependency) - Type-safe API definitions
+- `zod` (peer dependency) - Schema validation
+
+---
+
+## [Unreleased]
+
+### Planned
+
+- Additional adapter implementations
+- Enhanced middleware support
+- WebSocket support
+- Performance optimizations

package/README.md

@@ -84,6 +84,21 @@ The choice of adapter depends on your deployment environment and performance req
 - **Guard**: A guard is a class that is used to validate incoming requests and ensure that they meet certain criteria. Guards can be used to validate request parameters, headers, and body. They can also be used to check authentication and authorization.
 - **Attribute**: An attribute is a decorator that is used to add metadata to a class or method. Attributes can be used in guards, controllers, modules, and endpoints to provide additional information about the class or method.
 
+## Legacy-Compatible Decorators
+
+Navios provides legacy-compatible decorators for projects that use TypeScript's experimental decorator API. These decorators are available from `@navios/core/legacy-compat` and provide the same functionality as the standard decorators, but with compatibility for projects that cannot use Stage 3 decorators.
+
+```ts
+import { Controller, Endpoint, Module } from '@navios/core/legacy-compat'
+
+@Module({
+  controllers: [UserController],
+})
+export class AppModule {}
+```
+
+For more information, see the [Legacy-Compatible Decorators documentation](./docs/legacy-compat.md).
+
 ## Getting Started
 
 ### Define your API
@@ -91,7 +106,7 @@ The choice of adapter depends on your deployment environment and performance req
 Define your API in a shared location accessible to both the client and server. This allows you to use the same API definition for both the client and server, ensuring consistency and reducing duplication.
 
 ```ts
-import { builder } from '@navios/core'
+import { builder } from '@navios/builder'
 
 import { z } from 'zod/v4'
 
@@ -227,7 +242,9 @@ That's it! You have created your first Navios server. You can now run your serve
 - **[Quick Start Guide](./docs/quick-start.md)** - Get up and running quickly
 - **[Complete Documentation](./docs/README.md)** - Comprehensive framework documentation
 - **[Adapter Guide](./docs/adapters.md)** - Detailed adapter information and comparison
+- **[Legacy-Compatible Decorators](./docs/legacy-compat.md)** - Using Navios with TypeScript experimental decorators
 - **[API Examples](https://github.com/Arilas/navios/tree/main/examples)** - Working code examples
+- **[CHANGELOG](./CHANGELOG.md)** - Version history and release notes
 
 ## Related Packages
 

package/docs/README.md

@@ -16,6 +16,7 @@
 - [Guards](./guards.md) - Authentication, authorization, and request filtering
 - [Exception Handling](./exceptions.md) - Error handling and HTTP exceptions
 - [Attribute System](./attributes.md) - Metadata and custom decorators
+- [Legacy-Compatible Decorators](./legacy-compat.md) - Using Navios with TypeScript experimental decorators
 
 ### Infrastructure
 

package/docs/legacy-compat.md

@@ -0,0 +1,320 @@
+# Legacy-Compatible Decorators
+
+Navios provides a legacy-compatible decorator API for projects that cannot use Stage 3 decorators (the standard decorator proposal). These decorators use the TypeScript experimental decorator API and convert the arguments to Stage 3 format internally.
+
+## Overview
+
+The legacy-compat decorators are located in `@navios/core/legacy-compat` and provide the same functionality as the standard decorators, but with compatibility for TypeScript's experimental decorator system.
+
+## When to Use Legacy-Compatible Decorators
+
+Use legacy-compatible decorators if:
+
+- Your project uses TypeScript with `experimentalDecorators` enabled
+- You cannot migrate to Stage 3 decorators due to tooling or compatibility constraints
+- You need to maintain compatibility with older TypeScript versions or build tools
+
+## Installation and Setup
+
+No additional installation is required. The legacy-compat decorators are included in `@navios/core`.
+
+To use legacy-compatible decorators, import them from the `legacy-compat` subpath:
+
+```typescript
+import { Module, Controller, Endpoint, UseGuards, Header, HttpCode, Multipart, Stream } from '@navios/core/legacy-compat'
+```
+
+## Available Decorators
+
+All standard Navios decorators are available in legacy-compatible form:
+
+### Class Decorators
+
+#### `@Module(options?)`
+
+Defines an application module. Can be applied to classes.
+
+```typescript
+import { Module } from '@navios/core/legacy-compat'
+
+@Module({
+  controllers: [UserController, AuthController],
+  imports: [DatabaseModule],
+  guards: [AuthGuard],
+})
+export class AppModule {}
+```
+
+#### `@Controller(options?)`
+
+Defines a request controller. Can be applied to classes.
+
+```typescript
+import { Controller } from '@navios/core/legacy-compat'
+
+@Controller({ guards: [AuthGuard] })
+export class UserController {
+  // ...
+}
+```
+
+### Method Decorators
+
+#### `@Endpoint(endpoint)`
+
+Defines an HTTP endpoint with type-safe request/response schemas. Must be applied to methods.
+
+```typescript
+import { Controller, Endpoint, type EndpointParams, type EndpointResult } from '@navios/core/legacy-compat'
+
+@Controller()
+export class UserController {
+  @Endpoint(getUserEndpoint)
+  async getUser(request: EndpointParams<typeof getUserEndpoint>): Promise<EndpointResult<typeof getUserEndpoint>> {
+    const { id } = request
+    return { id, name: 'John Doe' }
+  }
+}
+```
+
+#### `@Multipart(endpoint)`
+
+Defines a multipart/form-data endpoint for file uploads. Must be applied to methods.
+
+```typescript
+import { Controller, Multipart, type MultipartParams, type MultipartResult } from '@navios/core/legacy-compat'
+
+@Controller()
+export class FileController {
+  @Multipart(uploadFileEndpoint)
+  async uploadFile(request: MultipartParams<typeof uploadFileEndpoint>): Promise<MultipartResult<typeof uploadFileEndpoint>> {
+    const { file } = request.data
+    return { url: 'https://example.com/file.jpg' }
+  }
+}
+```
+
+#### `@Stream(endpoint)`
+
+Defines a streaming endpoint. Must be applied to methods.
+
+```typescript
+import { Controller, Stream, type StreamParams } from '@navios/core/legacy-compat'
+
+@Controller()
+export class FileController {
+  @Stream(downloadFileEndpoint)
+  async downloadFile(request: StreamParams<typeof downloadFileEndpoint>, reply: any): Promise<void> {
+    const { fileId } = request.urlParams
+    // Stream file data to reply
+  }
+}
+```
+
+#### `@UseGuards(...guards)`
+
+Applies guards to controllers or endpoints. Can be applied to classes or methods.
+
+```typescript
+import { Controller, Endpoint, UseGuards } from '@navios/core/legacy-compat'
+
+// Apply to a controller
+@Controller()
+@UseGuards(AuthGuard, RoleGuard)
+export class UserController {
+  // All endpoints in this controller will use AuthGuard and RoleGuard
+}
+
+// Apply to a specific endpoint
+@Controller()
+export class UserController {
+  @Endpoint(getUserEndpoint)
+  @UseGuards(AuthGuard)
+  async getUser() {
+    // Only this endpoint uses AuthGuard
+  }
+}
+```
+
+#### `@Header(name, value)`
+
+Sets custom response headers. Must be applied to methods.
+
+```typescript
+import { Controller, Endpoint, Header } from '@navios/core/legacy-compat'
+
+@Controller()
+export class UserController {
+  @Endpoint(getUserEndpoint)
+  @Header('Cache-Control', 'max-age=3600')
+  async getUser() {
+    return { id: '1', name: 'John' }
+  }
+}
+```
+
+#### `@HttpCode(code)`
+
+Sets a custom HTTP status code for the response. Must be applied to methods.
+
+```typescript
+import { Controller, Endpoint, HttpCode } from '@navios/core/legacy-compat'
+
+@Controller()
+export class UserController {
+  @Endpoint(createUserEndpoint)
+  @HttpCode(201)
+  async createUser() {
+    return { id: '1', name: 'John' }
+  }
+}
+```
+
+## Type Utilities
+
+The legacy-compat module also exports type utilities for working with endpoints:
+
+```typescript
+import type {
+  ModuleOptions,
+  ControllerOptions,
+  EndpointParams,
+  EndpointResult,
+  MultipartParams,
+  MultipartResult,
+  StreamParams,
+} from '@navios/core/legacy-compat'
+```
+
+## Complete Example
+
+Here's a complete example using legacy-compatible decorators:
+
+```typescript
+import { builder } from '@navios/builder'
+import { Module, Controller, Endpoint, UseGuards, HttpCode, type EndpointParams, type EndpointResult } from '@navios/core/legacy-compat'
+import { Injectable, syncInject } from '@navios/core'
+import { z } from 'zod/v4'
+
+// Define API endpoints
+const api = builder()
+
+const getUserEndpoint = api.declareEndpoint({
+  method: 'get',
+  url: '/users/:id',
+  responseSchema: z.object({
+    id: z.string(),
+    name: z.string(),
+    email: z.string().email(),
+  }),
+})
+
+const createUserEndpoint = api.declareEndpoint({
+  method: 'post',
+  url: '/users',
+  requestSchema: z.object({
+    name: z.string(),
+    email: z.string().email(),
+  }),
+  responseSchema: z.object({
+    id: z.string(),
+    name: z.string(),
+    email: z.string().email(),
+  }),
+})
+
+// Service
+@Injectable()
+export class UserService {
+  async findById(id: string) {
+    // Implementation
+  }
+
+  async create(data: { name: string; email: string }) {
+    // Implementation
+  }
+}
+
+// Controller
+@Controller()
+@UseGuards(AuthGuard)
+export class UserController {
+  userService = syncInject(UserService)
+
+  @Endpoint(getUserEndpoint)
+  async getUser(request: EndpointParams<typeof getUserEndpoint>): Promise<EndpointResult<typeof getUserEndpoint>> {
+    const { id } = request.urlParams
+    return await this.userService.findById(id)
+  }
+
+  @Endpoint(createUserEndpoint)
+  @HttpCode(201)
+  async createUser(request: EndpointParams<typeof createUserEndpoint>): Promise<EndpointResult<typeof createUserEndpoint>> {
+    const { name, email } = request.body
+    return await this.userService.create({ name, email })
+  }
+}
+
+// Module
+@Module({
+  controllers: [UserController],
+})
+export class AppModule {}
+```
+
+## Migration from Standard Decorators
+
+If you're migrating from standard decorators to legacy-compatible decorators:
+
+1. Update your imports to use the `legacy-compat` subpath:
+
+```typescript
+// Before
+import { Module, Controller, Endpoint } from '@navios/core'
+
+// After
+import { Module, Controller, Endpoint } from '@navios/core/legacy-compat'
+```
+
+2. Ensure your `tsconfig.json` has `experimentalDecorators` enabled:
+
+```json
+{
+  "compilerOptions": {
+    "experimentalDecorators": true
+  }
+}
+```
+
+3. The decorator usage remains the same - no changes to how you apply them.
+
+## Differences from Standard Decorators
+
+The legacy-compatible decorators:
+
+- Use TypeScript's experimental decorator API instead of Stage 3 decorators
+- Convert decorator arguments internally to work with the standard Navios implementation
+- Provide the same functionality and type safety as standard decorators
+- May have slightly different type inference behavior in some edge cases
+
+## TypeScript Configuration
+
+To use legacy-compatible decorators, ensure your `tsconfig.json` includes:
+
+```json
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  }
+}
+```
+
+The `emitDecoratorMetadata` option is optional but recommended for better runtime behavior with dependency injection.
+
+## Notes
+
+- Legacy-compatible decorators are fully compatible with all Navios features including guards, attributes, dependency injection, and adapters
+- You can mix legacy-compatible decorators with standard decorators in the same project, but it's recommended to use one approach consistently
+- The legacy-compat module is maintained alongside the standard decorators and receives the same updates and bug fixes
+

package/docs/testing.md

@@ -1,9 +1,5 @@
 # Testing Guide
 
-> This guide is for future reference and may be updated over time
->
-> Not represent the final state of the testing strategy for Navios
-
 This guide covers testing strategies and best practices for Navios applications, including unit testing, integration testing, and end-to-end testing.
 
 ## Testing Philosophy
@@ -22,6 +18,132 @@ Navios promotes a testing-first approach with:
 npm install --save-dev vitest supertest @navios/builder
 ```
 
+## Testing Module
+
+Navios provides a dedicated testing module that simplifies setting up test environments with mock dependencies.
+
+### Creating a Testing Module
+
+The `createTestingModule` function is the main entry point for setting up tests:
+
+```typescript
+import { createTestingModule } from '@navios/core/testing'
+
+import { AppModule } from './app.module'
+import { DatabaseService } from './database.service'
+
+describe('AppModule', () => {
+  it('should create application with mocked dependencies', async () => {
+    const mockDatabase = {
+      query: vi.fn().mockResolvedValue([]),
+    }
+
+    const testingModule = createTestingModule(AppModule, {
+      adapter: [], // No HTTP adapter for unit tests
+    })
+      .overrideProvider(DatabaseService)
+      .useValue(mockDatabase)
+
+    const app = await testingModule.compile()
+
+    // App is ready to use with mocked DatabaseService
+    expect(app).toBeDefined()
+
+    await testingModule.close()
+  })
+})
+```
+
+### TestingModule API
+
+#### `createTestingModule(appModule, options)`
+
+Creates a new testing module builder.
+
+```typescript
+const testingModule = createTestingModule(AppModule, {
+  adapter: [], // Required: HTTP adapter configuration
+  logger: false, // Optional: Disable logging for tests
+  overrides: [ // Optional: Initial overrides
+    { token: SomeService, useValue: mockService },
+  ],
+})
+```
+
+#### `.overrideProvider(token)`
+
+Returns a builder for overriding a provider:
+
+```typescript
+testingModule
+  .overrideProvider(DatabaseService)
+  .useValue(mockDatabaseService) // Use a mock value
+
+testingModule
+  .overrideProvider(CacheService)
+  .useClass(MockCacheService) // Use a mock class
+```
+
+#### `.compile()`
+
+Compiles the testing module and returns the `NaviosApplication`:
+
+```typescript
+const app = await testingModule.compile()
+```
+
+#### `.init()`
+
+Compiles and initializes the application (equivalent to calling `compile()` then `app.init()`):
+
+```typescript
+const app = await testingModule.init()
+```
+
+#### `.get(token)`
+
+Gets an instance from the container:
+
+```typescript
+const userService = await testingModule.get(UserService)
+```
+
+#### `.getContainer()`
+
+Gets the underlying `TestContainer` for direct manipulation:
+
+```typescript
+const container = testingModule.getContainer()
+container.bind(SomeToken).toValue(someValue)
+```
+
+#### `.close()`
+
+Disposes the testing module and cleans up resources:
+
+```typescript
+await testingModule.close()
+```
+
+### Custom Container Support
+
+You can also pass a custom container directly to `NaviosFactory.create()`:
+
+```typescript
+import { NaviosFactory } from '@navios/core'
+import { TestContainer } from '@navios/core/testing'
+
+const container = new TestContainer()
+container.bind(DatabaseService).toValue(mockDatabase)
+
+const app = await NaviosFactory.create(AppModule, {
+  adapter: [],
+  container, // Use custom container
+})
+```
+
+This is useful when you need more control over the container setup or when integrating with existing test infrastructure.
+
 ## Unit Testing
 
 ### Testing Services
@@ -332,29 +454,31 @@ describe('AuthGuard', () => {
 ### Testing Module Integration
 
 ```typescript
-import { NaviosFactory } from '@navios/core'
+import { createTestingModule } from '@navios/core/testing'
+import { defineFastifyEnvironment } from '@navios/adapter-fastify'
 
 import { DatabaseService } from './database.service'
 import { UserModule } from './user.module'
 import { UserService } from './user.service'
 
 describe('UserModule', () => {
-  let module: TestingModule
+  let testingModule: ReturnType<typeof createTestingModule>
   let userService: UserService
   let databaseService: DatabaseService
 
   beforeAll(async () => {
-    module = await NaviosFactory.create(UserModule, {
+    testingModule = createTestingModule(UserModule, {
       adapter: defineFastifyEnvironment(),
     })
-    await module.init()
 
-    userService = module.get<UserService>(UserService)
-    databaseService = module.get<DatabaseService>(DatabaseService)
+    await testingModule.init()
+
+    userService = await testingModule.get(UserService)
+    databaseService = await testingModule.get(DatabaseService)
   })
 
   afterAll(async () => {
-    await module.close()
+    await testingModule.close()
   })
 
   it('should be defined', () => {
@@ -374,28 +498,27 @@ When testing HTTP endpoints, ensure your endpoints are defined using `@navios/bu
 
 ```typescript
 import { defineFastifyEnvironment } from '@navios/adapter-fastify'
-import { NaviosFactory } from '@navios/core'
+import { createTestingModule } from '@navios/core/testing'
 
 import * as request from 'supertest'
 
 import { AppModule } from '../app.module'
 
 describe('UserController (e2e)', () => {
-  let app: any
+  let testingModule: ReturnType<typeof createTestingModule>
   let httpServer: any
 
   beforeAll(async () => {
-    const moduleFixture = await NaviosFactory.create(AppModule, {
+    testingModule = createTestingModule(AppModule, {
       adapter: defineFastifyEnvironment(),
     })
-    await moduleFixture.init()
 
-    await app.init()
+    const app = await testingModule.init()
     httpServer = app.getServer()
   })
 
   afterAll(async () => {
-    await app.close()
+    await testingModule.close()
   })
 
   describe('/users (GET)', () => {