@navios/core 0.9.3 → 1.0.0-alpha.2

package/CHANGELOG.md

@@ -5,6 +5,64 @@ 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).
 
+## [1.0.0-alpha.2] - 2026-01-07
+
+### Added
+
+- **Module Overrides**: New `overrides` option in `@Module()` decorator for service override classes
+  - Service override classes are imported for side effects to ensure their `@Injectable` decorators execute
+  - Overrides should use the same `InjectionToken` as the original service with a higher priority
+  - `ModuleLoaderService` validates overrides and logs warnings if override is not active or not registered
+  - Useful for testing and swapping implementations without modifying original modules
+
+### Changed
+
+- **Simplified Endpoint Type Utilities**: Refactored `EndpointParams<T>` type to use new `RequestArgs` type from `@navios/builder`
+  - Cleaner type inference with support for `urlParamsSchema`
+  - Server-side handlers receive `z.output` types (parsed/transformed values)
+  - Client-side receives `z.input` types (raw input values)
+- **Updated Builder Types**: All adapters and decorators now use `EndpointOptions` and `BaseEndpointOptions` from `@navios/builder` instead of legacy `BaseEndpointConfig`
+- **Legacy Decorator Improvements**: Simplified type definitions in legacy-compat decorators for better maintainability
+
+### Dependencies
+
+- Updated to support `@navios/builder` ^1.0.0-alpha.2 with new `RequestArgs` type system
+
+## [1.0.0-alpha.1] - 2026-01-22
+
+### Added
+
+- **RFC 7807 Problem Details Error Responses**: New standardized error response system using RFC 7807 Problem Details format
+  - `ErrorResponseProducerService` - Central service for producing standardized error responses
+  - `FrameworkError` enum - Explicit error type specification (NotFound, Forbidden, InternalServerError, ValidationError)
+  - Customizable error responders with dependency injection support:
+    - `NotFoundResponderService` - Handles 404 Not Found errors
+    - `ForbiddenResponderService` - Handles 403 Forbidden errors (used by guards)
+    - `InternalServerErrorResponderService` - Handles 500 Internal Server errors
+    - `ValidationErrorResponderService` - Handles 400 Validation errors with structured Zod error details
+  - All responders registered with low priority (-10) for easy override
+  - `ErrorResponder` interface for custom responder implementations
+  - `ProblemDetails` interface following RFC 7807 specification
+  - `ErrorResponse` interface with status code, payload, and headers
+- **Guard Error Handling Enhancement**: `GuardRunnerService` now uses `ErrorResponseProducerService` for standardized error responses
+  - Guard rejections now return RFC 7807 compliant responses
+  - Guard execution errors produce standardized internal server error responses
+
+### Changed
+
+- **Error Response Format**: Error responses now use RFC 7807 Problem Details format instead of simple JSON
+  - Content-Type header set to `application/problem+json`
+  - Responses include `type`, `title`, `status`, and `detail` fields
+  - Validation errors include structured `errors` field with Zod validation details
+  - HttpException responses remain backward compatible (preserved original format)
+
+### Breaking Changes
+
+- **Error Response Format**: Non-HttpException errors now return RFC 7807 Problem Details format
+  - Previous format: `{ message: "..." }`
+  - New format: `{ type: "about:blank", title: "...", status: 404, detail: "..." }`
+  - HttpException responses are unchanged for backward compatibility
+
 ## [0.9.3] - 2026-01-05
 
 ### Fixed

package/README.md

@@ -30,7 +30,7 @@ The adapter must be provided when creating your Navios application to define the
 - **Build with Navios Builder**: Navios Builder is a powerful HTTP client that simplifies API requests. By combining it with Navios, you can use the same API definition for both the client and server, ensuring consistency and reducing duplication.
 - **Declarative API**: The API is designed to be declarative, allowing you to define your API endpoints and their schemas in a clear and concise manner. This makes it easy to understand and maintain your API client.
 - **Customizable**: The package allows you to customize the behavior of the API client, such as using a custom client.
-- **Error Handling**: The package provides built-in error handling capabilities, allowing you to handle API errors gracefully and provide meaningful feedback to users.
+- **Error Handling**: The package provides built-in error handling capabilities with RFC 7807 Problem Details format for standardized error responses. Includes customizable error responders and comprehensive exception handling.
 
 ## Adapters
 
@@ -77,7 +77,7 @@ The choice of adapter depends on your deployment environment and performance req
 
 ## Main Concepts
 
-- **Module**: A module is a collection of controllers, and other modules. It is used to group related functionality together and provide a clear structure for your API. It also can define some shared guards and attributes.
+- **Module**: A module is a collection of controllers, and other modules. It is used to group related functionality together and provide a clear structure for your API. It also can define some shared guards, attributes, and service overrides.
 - **Controller**: A controller is a class that defines a set of endpoints for a specific resource. It is used to handle incoming requests and return responses. Controllers can also define guards and attributes that apply to all endpoints in the controller.
 - **Endpoint**: An endpoint is a specific route in your API that handles a specific request. It used original endpoint definition from Navios Builder, and a set of request and response schemas. Endpoints can also define guards and attributes that apply to the endpoint.
 - **Service**: A service is a class that defines the business logic for a specific resource. It is used to separate the business logic from the controller and provide a clear structure for your API.
@@ -204,6 +204,8 @@ import { AuthController } from './auth.controller.mjs'
 
 @Module({
   controllers: [AuthController],
+  // Optional: overrides for service implementations with higher priority
+  // overrides: [OverrideService],
 })
 export class AppModule {}
 ```

package/docs/README.md

@@ -200,7 +200,7 @@ Choose the appropriate adapter based on your deployment environment and requirem
 
 ## Error Handling
 
-Both adapters provide consistent error handling through Navios's exception system:
+Both adapters provide consistent error handling through Navios's exception system. Framework-level errors (validation errors, guard rejections, not found routes, unhandled errors) use **RFC 7807 Problem Details** format for standardized, machine-readable error responses. HttpException responses maintain backward compatibility with the original format.
 
 ```ts
 import { BadRequestException, NotFoundException } from '@navios/core'
@@ -225,6 +225,8 @@ export class UserController {
 }
 ```
 
+For more information on error handling, including custom error responders and RFC 7807 Problem Details, see the [Error Handling Guide](../../../apps/docs/docs/server/guides/error-handling.md).
+
 ## Configuration
 
 Both adapters support the same Navios configuration options:

package/docs/exceptions.md

@@ -168,7 +168,9 @@ export class UserController {
 
 ## Exception Response Format
 
-By default, Navios returns exceptions in this format:
+### HttpException Response Format
+
+`HttpException` and its subclasses (like `NotFoundException`, `BadRequestException`, etc.) maintain backward compatibility and return the original format:
 
 ```json
 {
@@ -197,6 +199,40 @@ For exceptions with additional data:
 }
 ```
 
+### RFC 7807 Problem Details Format
+
+Framework-level errors (validation errors, guard rejections, not found routes, unhandled errors) use **RFC 7807 Problem Details** format for standardized, machine-readable error responses:
+
+```json
+{
+  "type": "about:blank",
+  "title": "Not Found",
+  "status": 404,
+  "detail": "Route [GET] /api/users/999 not found"
+}
+```
+
+Validation errors include structured error details:
+
+```json
+{
+  "type": "about:blank",
+  "title": "Validation Error",
+  "status": 400,
+  "detail": "Request validation failed",
+  "errors": {
+    "email": {
+      "code": "invalid_string",
+      "validation": "email",
+      "message": "Invalid email",
+      "path": ["email"]
+    }
+  }
+}
+```
+
+All Problem Details responses include the `Content-Type: application/problem+json` header. For more information on customizing error responders, see the [Error Handling Guide](../../../apps/docs/docs/server/guides/error-handling.md).
+
 ## Best Practices
 
 ### 1. Use Specific Exceptions