@navios/core 0.6.0 → 0.7.1

package/src/decorators/controller.decorator.mts

@@ -4,9 +4,37 @@ import { Injectable, InjectableScope, InjectionToken } from '@navios/di'
 
 import { getControllerMetadata } from '../metadata/index.mjs'
 
+/**
+ * Options for configuring a Navios controller.
+ */
 export interface ControllerOptions {
+  /**
+   * Guards to apply to all endpoints in this controller.
+   * Guards are executed in reverse order (last guard first).
+   */
   guards?: ClassType[] | Set<ClassType>
 }
+
+/**
+ * Decorator that marks a class as a Navios controller.
+ * 
+ * Controllers handle HTTP requests and define endpoints.
+ * They are request-scoped by default, meaning a new instance is created for each request.
+ * 
+ * @param options - Controller configuration options
+ * @returns A class decorator
+ * 
+ * @example
+ * ```typescript
+ * @Controller({ guards: [AuthGuard] })
+ * export class UserController {
+ *   @Endpoint(getUserEndpoint)
+ *   async getUser(request: EndpointParams<typeof getUserEndpoint>) {
+ *     // Handle request
+ *   }
+ * }
+ * ```
+ */
 export function Controller({ guards }: ControllerOptions = {}) {
   return function (target: ClassType, context: ClassDecoratorContext) {
     if (context.kind !== 'class') {

package/src/decorators/endpoint.decorator.mts

@@ -11,6 +11,30 @@ import { ZodDiscriminatedUnion } from 'zod/v4'
 import { getEndpointMetadata } from '../metadata/index.mjs'
 import { EndpointAdapterToken } from '../tokens/index.mjs'
 
+/**
+ * Extracts the typed parameters for an endpoint handler function.
+ *
+ * This utility type extracts URL parameters, query parameters, and request body
+ * from an endpoint declaration and flattens them into a single object.
+ *
+ * @typeParam EndpointDeclaration - The endpoint declaration from @navios/builder
+ *
+ * @example
+ * ```typescript
+ * const getUserEndpoint = api.declareEndpoint({
+ *   method: 'get',
+ *   url: '/users/$userId',
+ *   querySchema: z.object({ include: z.string().optional() }),
+ *   responseSchema: z.object({ id: z.string(), name: z.string() }),
+ * })
+ *
+ * @Endpoint(getUserEndpoint)
+ * async getUser(request: EndpointParams<typeof getUserEndpoint>) {
+ *   // request.urlParams.userId is typed as string
+ *   // request.query.include is typed as string | undefined
+ * }
+ * ```
+ */
 export type EndpointParams<
   EndpointDeclaration extends {
     config: BaseEndpointConfig<any, any, any, any, any>
@@ -39,6 +63,28 @@ export type EndpointParams<
       >
     : Util_FlatObject<EndpointFunctionArgs<Url, undefined, undefined, true>>
 
+/**
+ * Extracts the typed return value for an endpoint handler function.
+ *
+ * This utility type extracts the response schema from an endpoint declaration
+ * and returns the appropriate Promise type.
+ *
+ * @typeParam EndpointDeclaration - The endpoint declaration from @navios/builder
+ *
+ * @example
+ * ```typescript
+ * const getUserEndpoint = api.declareEndpoint({
+ *   method: 'get',
+ *   url: '/users/$userId',
+ *   responseSchema: z.object({ id: z.string(), name: z.string() }),
+ * })
+ *
+ * @Endpoint(getUserEndpoint)
+ * async getUser(request: EndpointParams<typeof getUserEndpoint>): EndpointResult<typeof getUserEndpoint> {
+ *   return { id: '1', name: 'John' } // Type-checked against responseSchema
+ * }
+ * ```
+ */
 export type EndpointResult<
   EndpointDeclaration extends {
     config: BaseEndpointConfig<any, any, any, any, any>
@@ -50,6 +96,36 @@ export type EndpointResult<
     ? Promise<z.input<Options[number]>>
     : Promise<z.input<EndpointDeclaration['config']['responseSchema']>>
 
+/**
+ * Decorator that marks a method as an HTTP endpoint.
+ *
+ * The endpoint must be defined using @navios/builder's `declareEndpoint` method.
+ * This ensures type safety and consistency between client and server.
+ *
+ * @param endpoint - The endpoint declaration from @navios/builder
+ * @returns A method decorator
+ *
+ * @example
+ * ```typescript
+ * import { builder } from '@navios/builder'
+ *
+ * const api = builder()
+ * const getUserEndpoint = api.declareEndpoint({
+ *   method: 'get',
+ *   url: '/users/$userId',
+ *   responseSchema: z.object({ id: z.string(), name: z.string() }),
+ * })
+ *
+ * @Controller()
+ * export class UserController {
+ *   @Endpoint(getUserEndpoint)
+ *   async getUser(request: EndpointParams<typeof getUserEndpoint>) {
+ *     const { userId } = request.urlParams
+ *     return { id: userId, name: 'John' }
+ *   }
+ * }
+ * ```
+ */
 export function Endpoint<
   Method extends HttpMethod = HttpMethod,
   Url extends string = string,

package/src/decorators/header.decorator.mts

@@ -2,6 +2,25 @@ import type { HttpHeader } from '../interfaces/index.mjs'
 
 import { getEndpointMetadata } from '../metadata/index.mjs'
 
+/**
+ * Decorator that sets a custom HTTP response header for an endpoint.
+ * 
+ * @param name - The header name (e.g., 'Content-Type', 'Cache-Control')
+ * @param value - The header value (string, number, or array of strings)
+ * @returns A method decorator
+ * 
+ * @example
+ * ```typescript
+ * @Controller()
+ * export class UserController {
+ *   @Endpoint(getUserEndpoint)
+ *   @Header('Cache-Control', 'max-age=3600')
+ *   async getUser() {
+ *     return { id: '1', name: 'John' }
+ *   }
+ * }
+ * ```
+ */
 export function Header(name: HttpHeader, value: string | number | string[]) {
   return <T extends Function>(
     target: T,

package/src/decorators/http-code.decorator.mts

@@ -1,5 +1,25 @@
 import { getEndpointMetadata } from '../metadata/index.mjs'
 
+/**
+ * Decorator that sets a custom HTTP status code for successful responses.
+ * 
+ * By default, endpoints return 200 OK. Use this decorator to return a different status code.
+ * 
+ * @param code - The HTTP status code to return (e.g., 201, 204, 202)
+ * @returns A method decorator
+ * 
+ * @example
+ * ```typescript
+ * @Controller()
+ * export class UserController {
+ *   @Endpoint(createUserEndpoint)
+ *   @HttpCode(201)
+ *   async createUser() {
+ *     return { id: '1', name: 'John' }
+ *   }
+ * }
+ * ```
+ */
 export function HttpCode(code: number) {
   return <T extends Function>(
     target: T,

package/src/decorators/module.decorator.mts

@@ -4,12 +4,46 @@ import { Injectable, InjectableScope, InjectionToken } from '@navios/di'
 
 import { getModuleMetadata } from '../metadata/index.mjs'
 
+/**
+ * Options for configuring a Navios module.
+ */
 export interface ModuleOptions {
+  /**
+   * Controllers to register in this module.
+   * Controllers handle HTTP requests and define endpoints.
+   */
   controllers?: ClassType[] | Set<ClassType>
+  /**
+   * Other modules to import into this module.
+   * Imported modules' controllers and services become available.
+   */
   imports?: ClassType[] | Set<ClassType>
+  /**
+   * Guards to apply to all controllers in this module.
+   * Guards are executed in reverse order (last guard first).
+   */
   guards?: ClassType[] | Set<ClassType>
 }
 
+/**
+ * Decorator that marks a class as a Navios module.
+ * 
+ * Modules are the basic building blocks of a Navios application.
+ * They organize controllers, services, and other modules into logical units.
+ * 
+ * @param options - Module configuration options
+ * @returns A class decorator
+ * 
+ * @example
+ * ```typescript
+ * @Module({
+ *   controllers: [UserController, AuthController],
+ *   imports: [DatabaseModule],
+ *   guards: [AuthGuard],
+ * })
+ * export class AppModule {}
+ * ```
+ */
 export function Module(
   { controllers = [], imports = [], guards = [] }: ModuleOptions = {
     controllers: [],

package/src/decorators/multipart.decorator.mts

@@ -11,6 +11,13 @@ import { ZodDiscriminatedUnion } from 'zod/v4'
 import { getEndpointMetadata } from '../metadata/index.mjs'
 import { MultipartAdapterToken } from '../tokens/index.mjs'
 
+/**
+ * Extracts the typed parameters for a multipart endpoint handler function.
+ * 
+ * Similar to `EndpointParams`, but specifically for multipart/form-data endpoints.
+ * 
+ * @typeParam EndpointDeclaration - The endpoint declaration from @navios/builder
+ */
 export type MultipartParams<
   EndpointDeclaration extends {
     config: BaseEndpointConfig<any, any, any, any, any>
@@ -39,6 +46,11 @@ export type MultipartParams<
       >
     : Util_FlatObject<EndpointFunctionArgs<Url, undefined, undefined, true>>
 
+/**
+ * Extracts the typed return value for a multipart endpoint handler function.
+ * 
+ * @typeParam EndpointDeclaration - The endpoint declaration from @navios/builder
+ */
 export type MultipartResult<
   EndpointDeclaration extends {
     config: BaseEndpointConfig<any, any, any, any, any>
@@ -50,6 +62,35 @@ export type MultipartResult<
     ? Promise<z.input<Options[number]>>
     : Promise<z.input<EndpointDeclaration['config']['responseSchema']>>
 
+/**
+ * Decorator that marks a method as a multipart/form-data endpoint.
+ * 
+ * Use this decorator for endpoints that handle file uploads or form data.
+ * The endpoint must be defined using @navios/builder's `declareMultipart` method.
+ * 
+ * @param endpoint - The multipart endpoint declaration from @navios/builder
+ * @returns A method decorator
+ * 
+ * @example
+ * ```typescript
+ * const uploadFileEndpoint = api.declareMultipart({
+ *   method: 'post',
+ *   url: '/upload',
+ *   requestSchema: z.object({ file: z.instanceof(File) }),
+ *   responseSchema: z.object({ url: z.string() }),
+ * })
+ * 
+ * @Controller()
+ * export class FileController {
+ *   @Multipart(uploadFileEndpoint)
+ *   async uploadFile(request: MultipartParams<typeof uploadFileEndpoint>) {
+ *     const { file } = request.data
+ *     // Handle file upload
+ *     return { url: 'https://example.com/file.jpg' }
+ *   }
+ * }
+ * ```
+ */
 export function Multipart<
   Method extends HttpMethod = HttpMethod,
   Url extends string = string,

package/src/decorators/stream.decorator.mts

@@ -9,6 +9,13 @@ import type { ZodObject, ZodType } from 'zod/v4'
 import { getEndpointMetadata } from '../metadata/index.mjs'
 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<
   EndpointDeclaration extends {
     config: BaseStreamConfig<any, any, any, any>
@@ -37,6 +44,32 @@ export type StreamParams<
       >
     : Util_FlatObject<EndpointFunctionArgs<Url, undefined, undefined, true>>
 
+/**
+ * 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)
+ *   async downloadFile(request: StreamParams<typeof downloadFileEndpoint>, reply: any) {
+ *     const { fileId } = request.urlParams
+ *     // Stream file data to reply
+ *   }
+ * }
+ * ```
+ */
 export function Stream<
   Method extends HttpMethod = HttpMethod,
   Url extends string = string,

package/src/decorators/use-guards.decorator.mts

@@ -11,6 +11,35 @@ import {
   getEndpointMetadata,
 } from '../metadata/index.mjs'
 
+/**
+ * Decorator that applies guards to a controller or endpoint.
+ * 
+ * Guards are used for authentication, authorization, and request validation.
+ * They implement the `CanActivate` interface and are executed before the endpoint handler.
+ * Guards can be applied at the module, controller, or endpoint level.
+ * 
+ * @param guards - Guard classes or injection tokens to apply
+ * @returns A class or method decorator
+ * 
+ * @example
+ * ```typescript
+ * // Apply to a controller
+ * @Controller()
+ * @UseGuards(AuthGuard, RoleGuard)
+ * export class UserController {
+ *   @Endpoint(getUserEndpoint)
+ *   async getUser() { }
+ * }
+ * 
+ * // Apply to a specific endpoint
+ * @Controller()
+ * export class UserController {
+ *   @Endpoint(getUserEndpoint)
+ *   @UseGuards(AuthGuard)
+ *   async getUser() { }
+ * }
+ * ```
+ */
 export function UseGuards(
   ...guards: (
     | ClassTypeWithInstance<CanActivate>

package/src/exceptions/bad-request.exception.mts

@@ -1,6 +1,27 @@
 import { HttpException } from './http.exception.mjs'
 
+/**
+ * Exception that represents a 400 Bad Request HTTP error.
+ * 
+ * Use this exception when the client's request is malformed or invalid.
+ * 
+ * @example
+ * ```typescript
+ * @Endpoint(createUserEndpoint)
+ * async createUser(request: EndpointParams<typeof createUserEndpoint>) {
+ *   if (!request.data.email) {
+ *     throw new BadRequestException('Email is required')
+ *   }
+ *   // ...
+ * }
+ * ```
+ */
 export class BadRequestException extends HttpException {
+  /**
+   * Creates a new BadRequestException.
+   * 
+   * @param message - Error message or response object
+   */
   constructor(message: string | object) {
     super(400, message)
   }

package/src/exceptions/conflict.exception.mts

@@ -1,6 +1,30 @@
 import { HttpException } from './http.exception.mjs'
 
+/**
+ * Exception that represents a 409 Conflict HTTP error.
+ * 
+ * Use this exception when the request conflicts with the current state of the resource
+ * (e.g., trying to create a resource that already exists).
+ * 
+ * @example
+ * ```typescript
+ * @Endpoint(createUserEndpoint)
+ * async createUser(request: EndpointParams<typeof createUserEndpoint>) {
+ *   const existing = await this.userService.findByEmail(request.data.email)
+ *   if (existing) {
+ *     throw new ConflictException('User with this email already exists')
+ *   }
+ *   // ...
+ * }
+ * ```
+ */
 export class ConflictException extends HttpException {
+  /**
+   * Creates a new ConflictException.
+   * 
+   * @param message - Error message or response object
+   * @param error - Optional underlying error for logging
+   */
   constructor(message: string | object, error?: Error) {
     super(409, message, error)
   }

package/src/exceptions/forbidden.exception.mts

@@ -1,6 +1,29 @@
 import { HttpException } from './http.exception.mjs'
 
+/**
+ * Exception that represents a 403 Forbidden HTTP error.
+ * 
+ * Use this exception when the client is authenticated but does not have
+ * permission to access the requested resource.
+ * 
+ * @example
+ * ```typescript
+ * @Endpoint(deleteUserEndpoint)
+ * @UseGuards(AuthGuard, RoleGuard)
+ * async deleteUser(request: EndpointParams<typeof deleteUserEndpoint>) {
+ *   if (!this.userService.hasPermission(request.user, 'delete')) {
+ *     throw new ForbiddenException('Insufficient permissions')
+ *   }
+ *   // ...
+ * }
+ * ```
+ */
 export class ForbiddenException extends HttpException {
+  /**
+   * Creates a new ForbiddenException.
+   * 
+   * @param message - Error message
+   */
   constructor(message: string) {
     super(403, message)
   }

package/src/exceptions/http.exception.mts

@@ -1,4 +1,30 @@
+/**
+ * Base exception class for all HTTP exceptions in Navios.
+ * 
+ * All HTTP exception classes extend this base class. When thrown from an endpoint handler,
+ * Navios will automatically convert it to an appropriate HTTP response with the specified
+ * status code and response body.
+ * 
+ * @example
+ * ```typescript
+ * @Endpoint(getUserEndpoint)
+ * async getUser(request: EndpointParams<typeof getUserEndpoint>) {
+ *   const user = await this.userService.findById(request.urlParams.userId)
+ *   if (!user) {
+ *     throw new HttpException(404, 'User not found')
+ *   }
+ *   return user
+ * }
+ * ```
+ */
 export class HttpException {
+  /**
+   * Creates a new HttpException instance.
+   * 
+   * @param statusCode - HTTP status code (e.g., 400, 404, 500)
+   * @param response - Response body (string or object)
+   * @param error - Optional underlying error for logging/debugging
+   */
   constructor(
     public readonly statusCode: number,
     public readonly response: string | object,

package/src/exceptions/internal-server-error.exception.mts

@@ -1,6 +1,32 @@
 import { HttpException } from './http.exception.mjs'
 
+/**
+ * Exception that represents a 500 Internal Server Error HTTP error.
+ * 
+ * Use this exception when an unexpected error occurs on the server.
+ * Generally, you should let unhandled errors bubble up rather than catching
+ * and rethrowing as InternalServerErrorException, as Navios will handle them appropriately.
+ * 
+ * @example
+ * ```typescript
+ * @Endpoint(processPaymentEndpoint)
+ * async processPayment(request: EndpointParams<typeof processPaymentEndpoint>) {
+ *   try {
+ *     return await this.paymentService.process(request.data)
+ *   } catch (error) {
+ *     this.logger.error('Payment processing failed', error)
+ *     throw new InternalServerErrorException('Payment processing failed', error)
+ *   }
+ * }
+ * ```
+ */
 export class InternalServerErrorException extends HttpException {
+  /**
+   * Creates a new InternalServerErrorException.
+   * 
+   * @param message - Error message or response object
+   * @param error - Optional underlying error for logging
+   */
   constructor(message: string | object, error?: Error) {
     super(500, message, error)
   }

package/src/exceptions/not-found.exception.mts

@@ -1,6 +1,29 @@
 import { HttpException } from './http.exception.mjs'
 
+/**
+ * Exception that represents a 404 Not Found HTTP error.
+ * 
+ * Use this exception when the requested resource does not exist.
+ * 
+ * @example
+ * ```typescript
+ * @Endpoint(getUserEndpoint)
+ * async getUser(request: EndpointParams<typeof getUserEndpoint>) {
+ *   const user = await this.userService.findById(request.urlParams.userId)
+ *   if (!user) {
+ *     throw new NotFoundException('User not found')
+ *   }
+ *   return user
+ * }
+ * ```
+ */
 export class NotFoundException extends HttpException {
+  /**
+   * Creates a new NotFoundException.
+   * 
+   * @param response - Error message or response object
+   * @param error - Optional underlying error for logging
+   */
   constructor(
     public readonly response: string | object,
     public readonly error?: Error,

package/src/exceptions/unauthorized.exception.mts

@@ -1,6 +1,29 @@
 import { HttpException } from './http.exception.mjs'
 
+/**
+ * Exception that represents a 401 Unauthorized HTTP error.
+ * 
+ * Use this exception when the client is not authenticated or authentication failed.
+ * 
+ * @example
+ * ```typescript
+ * @Endpoint(getUserEndpoint)
+ * @UseGuards(AuthGuard)
+ * async getUser(request: EndpointParams<typeof getUserEndpoint>) {
+ *   if (!request.headers.authorization) {
+ *     throw new UnauthorizedException('Authentication required')
+ *   }
+ *   // ...
+ * }
+ * ```
+ */
 export class UnauthorizedException extends HttpException {
+  /**
+   * Creates a new UnauthorizedException.
+   * 
+   * @param message - Error message or response object
+   * @param error - Optional underlying error for logging
+   */
   constructor(message: string | object, error?: Error) {
     super(401, message, error)
   }

package/src/index.mts

@@ -6,6 +6,7 @@ export * from './interfaces/index.mjs'
 export * from './logger/index.mjs'
 export * from './metadata/index.mjs'
 export * from './services/index.mjs'
+export * from './stores/index.mjs'
 export * from './tokens/index.mjs'
 export * from './attribute.factory.mjs'
 export * from './factories/index.mjs'

package/src/interfaces/abstract-execution-context.inteface.mts

@@ -4,10 +4,45 @@ import type {
   ModuleMetadata,
 } from '../metadata/index.mjs'
 
+/**
+ * Interface providing access to the execution context during request handling.
+ * 
+ * The execution context provides access to metadata and request/reply objects
+ * for the current request. It is available in guards and can be injected into
+ * services if needed.
+ * 
+ * @example
+ * ```typescript
+ * @Injectable()
+ * export class AuthGuard implements CanActivate {
+ *   async canActivate(context: AbstractExecutionContext): Promise<boolean> {
+ *     const request = context.getRequest()
+ *     const handler = context.getHandler()
+ *     // Access request and handler metadata
+ *     return true
+ *   }
+ * }
+ * ```
+ */
 export interface AbstractExecutionContext {
+  /**
+   * Gets the metadata for the module containing the current endpoint.
+   */
   getModule(): ModuleMetadata
+  /**
+   * Gets the metadata for the controller containing the current endpoint.
+   */
   getController(): ControllerMetadata
+  /**
+   * Gets the metadata for the current endpoint handler.
+   */
   getHandler(): HandlerMetadata
+  /**
+   * Gets the HTTP request object (adapter-specific).
+   */
   getRequest(): any
+  /**
+   * Gets the HTTP reply object (adapter-specific).
+   */
   getReply(): any
 }