@navios/core 0.9.3 → 1.0.0-alpha.2

package/src/legacy-compat/decorators/endpoint.decorator.mts

@@ -1,9 +1,9 @@
 import type {
-  BaseEndpointConfig,
-  EndpointFunctionArgs,
-  HttpMethod,
+  EndpointHandler,
+  EndpointOptions,
+  RequestArgs,
 } from '@navios/builder'
-import type { z, ZodType } from 'zod/v4'
+import type { z } from 'zod/v4'
 
 import { Endpoint as OriginalEndpoint } from '../../decorators/endpoint.decorator.mjs'
 import { createMethodContext } from '../context-compat.mjs'
@@ -13,22 +13,18 @@ import { createMethodContext } from '../context-compat.mjs'
  * Note: In legacy decorators, type constraints are checked when the decorator is applied,
  * but may not be preserved perfectly when decorators are stacked.
  */
-type EndpointMethodDescriptor<
-  Url extends string,
-  QuerySchema,
-  RequestSchema,
-  ResponseSchema extends ZodType,
-> = TypedPropertyDescriptor<
-  (
-    params: QuerySchema extends ZodType
-      ? RequestSchema extends ZodType
-        ? EndpointFunctionArgs<Url, QuerySchema, RequestSchema, true>
-        : EndpointFunctionArgs<Url, QuerySchema, undefined, true>
-      : RequestSchema extends ZodType
-        ? EndpointFunctionArgs<Url, undefined, RequestSchema, true>
-        : EndpointFunctionArgs<Url, undefined, undefined, true>,
-  ) => Promise<z.input<ResponseSchema>>
->
+type EndpointMethodDescriptor<Config extends EndpointOptions> =
+  TypedPropertyDescriptor<
+    (
+      params: RequestArgs<
+        Config['url'],
+        Config['querySchema'],
+        Config['requestSchema'],
+        Config['urlParamsSchema'],
+        true
+      >,
+    ) => Promise<z.input<Config['responseSchema']>>
+  >
 
 /**
  * Legacy-compatible Endpoint decorator.
@@ -50,30 +46,13 @@ type EndpointMethodDescriptor<
  * }
  * ```
  */
-export function Endpoint<
-  Method extends HttpMethod = HttpMethod,
-  Url extends string = string,
-  QuerySchema = undefined,
-  ResponseSchema extends ZodType = ZodType,
-  RequestSchema = ZodType,
->(endpoint: {
-  config: BaseEndpointConfig<
-    Method,
-    Url,
-    QuerySchema,
-    ResponseSchema,
-    RequestSchema
-  >
-}) {
+export function Endpoint<const Config extends EndpointOptions>(
+  endpoint: EndpointHandler<Config, false>,
+) {
   return function (
     target: any,
     propertyKey: string | symbol,
-    descriptor: EndpointMethodDescriptor<
-      Url,
-      QuerySchema,
-      RequestSchema,
-      ResponseSchema
-    >,
+    descriptor: EndpointMethodDescriptor<Config>,
   ): PropertyDescriptor | void {
     if (!descriptor) {
       throw new Error(
@@ -81,12 +60,7 @@ export function Endpoint<
       )
     }
     // Type check the descriptor value matches expected signature
-    const typedDescriptor = descriptor as EndpointMethodDescriptor<
-      Url,
-      QuerySchema,
-      RequestSchema,
-      ResponseSchema
-    >
+    const typedDescriptor = descriptor as EndpointMethodDescriptor<Config>
     const context = createMethodContext(target, propertyKey, typedDescriptor)
     const originalDecorator = OriginalEndpoint(endpoint)
     // @ts-expect-error - we don't need to type the value

package/src/legacy-compat/decorators/multipart.decorator.mts

@@ -1,9 +1,9 @@
 import type {
-  BaseEndpointConfig,
-  EndpointFunctionArgs,
-  HttpMethod,
+  EndpointHandler,
+  EndpointOptions,
+  RequestArgs,
 } from '@navios/builder'
-import type { z, ZodObject, ZodType } from 'zod/v4'
+import type { z } from 'zod/v4'
 
 import { Multipart as OriginalMultipart } from '../../decorators/multipart.decorator.mjs'
 import { createMethodContext } from '../context-compat.mjs'
@@ -13,22 +13,18 @@ import { createMethodContext } from '../context-compat.mjs'
  * Note: In legacy decorators, type constraints are checked when the decorator is applied,
  * but may not be preserved perfectly when decorators are stacked.
  */
-type MultipartMethodDescriptor<
-  Url extends string,
-  QuerySchema,
-  RequestSchema,
-  ResponseSchema extends ZodType,
-> = TypedPropertyDescriptor<
-  (
-    params: QuerySchema extends ZodObject
-      ? RequestSchema extends ZodType
-        ? EndpointFunctionArgs<Url, QuerySchema, RequestSchema, true>
-        : EndpointFunctionArgs<Url, QuerySchema, undefined, true>
-      : RequestSchema extends ZodType
-        ? EndpointFunctionArgs<Url, undefined, RequestSchema, true>
-        : EndpointFunctionArgs<Url, undefined, undefined, true>,
-  ) => Promise<z.input<ResponseSchema>>
->
+type MultipartMethodDescriptor<Config extends EndpointOptions> =
+  TypedPropertyDescriptor<
+    (
+      params: RequestArgs<
+        Config['url'],
+        Config['querySchema'],
+        Config['requestSchema'],
+        Config['urlParamsSchema'],
+        true
+      >,
+    ) => Promise<z.input<Config['responseSchema']>>
+  >
 
 /**
  * Legacy-compatible Multipart decorator.
@@ -51,30 +47,13 @@ type MultipartMethodDescriptor<
  * }
  * ```
  */
-export function Multipart<
-  Method extends HttpMethod = HttpMethod,
-  Url extends string = string,
-  QuerySchema = undefined,
-  ResponseSchema extends ZodType = ZodType,
-  RequestSchema = ZodType,
->(endpoint: {
-  config: BaseEndpointConfig<
-    Method,
-    Url,
-    QuerySchema,
-    ResponseSchema,
-    RequestSchema
-  >
-}) {
+export function Multipart<const Config extends EndpointOptions>(
+  endpoint: EndpointHandler<Config, false>,
+) {
   return function <T extends object>(
     target: T,
     propertyKey: string | symbol,
-    descriptor: MultipartMethodDescriptor<
-      Url,
-      QuerySchema,
-      RequestSchema,
-      ResponseSchema
-    >,
+    descriptor: MultipartMethodDescriptor<Config>,
   ): PropertyDescriptor | void {
     if (!descriptor) {
       throw new Error(

package/src/legacy-compat/decorators/stream.decorator.mts

@@ -1,41 +1,42 @@
 import type {
-  BaseStreamConfig,
-  EndpointFunctionArgs,
-  HttpMethod,
+  BaseEndpointOptions,
+  RequestArgs,
+  StreamHandler,
 } from '@navios/builder'
-import type { ZodObject, ZodType } from 'zod/v4'
 
 import { Stream as OriginalStream } from '../../decorators/stream.decorator.mjs'
 import { createMethodContext } from '../context-compat.mjs'
 
-type StreamParams<
-  Url extends string,
-  QuerySchema,
-  RequestSchema,
-> = QuerySchema extends ZodObject
-  ? RequestSchema extends ZodType
-    ? EndpointFunctionArgs<Url, QuerySchema, RequestSchema, true>
-    : EndpointFunctionArgs<Url, QuerySchema, undefined, true>
-  : RequestSchema extends ZodType
-    ? EndpointFunctionArgs<Url, undefined, RequestSchema, true>
-    : EndpointFunctionArgs<Url, undefined, undefined, true>
-
 /**
  * Type helper to constrain a PropertyDescriptor's value to match a stream endpoint signature.
  * Supports both with and without reply parameter (Bun doesn't use reply parameter).
+ * Note: In legacy decorators, type constraints are checked when the decorator is applied,
+ * but may not be preserved perfectly when decorators are stacked.
  */
-type StreamMethodDescriptor<
-  Url extends string,
-  QuerySchema,
-  RequestSchema,
-> =
+type StreamMethodDescriptor<Config extends BaseEndpointOptions> =
   | TypedPropertyDescriptor<
-      (params: StreamParams<Url, QuerySchema, RequestSchema>, reply: any) => any
+      (
+        params: RequestArgs<
+          Config['url'],
+          Config['querySchema'],
+          Config['requestSchema'],
+          Config['urlParamsSchema'],
+          true
+        >,
+        reply: any,
+      ) => any
     >
   | TypedPropertyDescriptor<
-      (params: StreamParams<Url, QuerySchema, RequestSchema>) => any
+      (
+        params: RequestArgs<
+          Config['url'],
+          Config['querySchema'],
+          Config['requestSchema'],
+          Config['urlParamsSchema'],
+          true
+        >,
+      ) => any
     >
-  | TypedPropertyDescriptor<() => any>
 
 /**
  * Legacy-compatible Stream decorator.
@@ -58,26 +59,31 @@ type StreamMethodDescriptor<
  * }
  * ```
  */
-export function Stream<
-  Method extends HttpMethod = HttpMethod,
-  Url extends string = string,
-  QuerySchema = undefined,
-  RequestSchema = ZodType,
->(endpoint: {
-  config: BaseStreamConfig<Method, Url, QuerySchema, RequestSchema>
-}) {
-  return function <T extends object>(
-    target: T,
+export function Stream<const Config extends BaseEndpointOptions>(
+  endpoint: StreamHandler<Config, false>,
+) {
+  return function (
+    target: any,
     propertyKey: string | symbol,
-    descriptor: StreamMethodDescriptor<Url, QuerySchema, RequestSchema>,
-  ) {
-    const context = createMethodContext(target, propertyKey, descriptor)
+    descriptor: StreamMethodDescriptor<Config>,
+  ): PropertyDescriptor | void {
+    if (!descriptor || !descriptor.value) {
+      throw new Error(
+        '[Navios] @Stream decorator requires a method descriptor. Make sure experimentalDecorators is enabled.',
+      )
+    }
+    // Type check the descriptor value matches expected signature
+    const typedDescriptor = descriptor as StreamMethodDescriptor<Config>
+    const context = createMethodContext(target, propertyKey, typedDescriptor)
     const originalDecorator = OriginalStream(endpoint)
-    // @ts-expect-error - we don't need to type the value
-    const result = originalDecorator(descriptor.value, context)
-    if (result !== descriptor.value) {
-      descriptor.value = result as any
+    // Stage3 decorator returns void in type signature but actually returns the function
+    // We know value is defined because we checked above
+    const result = originalDecorator(typedDescriptor.value!, context) as
+      | typeof typedDescriptor.value
+      | void
+    if (result && result !== typedDescriptor.value) {
+      typedDescriptor.value = result as any
     }
-    return descriptor
+    return typedDescriptor
   }
 }

package/src/metadata/module.metadata.mts

@@ -14,6 +14,7 @@ export interface ModuleMetadata {
   guards: Set<
     ClassTypeWithInstance<CanActivate> | InjectionToken<CanActivate, undefined>
   >
+  overrides: Set<ClassType>
   customAttributes: Map<string | symbol, any>
 }
 
@@ -35,6 +36,7 @@ export function getModuleMetadata(
           | ClassTypeWithInstance<CanActivate>
           | InjectionToken<CanActivate, undefined>
         >(),
+        overrides: new Set<ClassType>(),
         customAttributes: new Map<string | symbol, any>(),
       }
       context.metadata[ModuleMetadataKey] = newMetadata

package/src/responders/enums/framework-error.enum.mts

@@ -0,0 +1,38 @@
+/**
+ * Enumeration of framework-level error types.
+ * Used to explicitly specify which error responder should handle an error.
+ *
+ * @example
+ * ```typescript
+ * // In adapter error handling
+ * if (error instanceof ZodError) {
+ *   return errorProducer.respond(FrameworkError.ValidationError, error)
+ * }
+ * return errorProducer.handleUnknown(error)
+ * ```
+ */
+export enum FrameworkError {
+  /**
+   * Resource not found (HTTP 404).
+   * Use when a requested resource does not exist.
+   */
+  NotFound = 'NotFound',
+
+  /**
+   * Forbidden (HTTP 403).
+   * Use when access to a resource is denied (e.g., guard rejection).
+   */
+  Forbidden = 'Forbidden',
+
+  /**
+   * Internal server error (HTTP 500).
+   * Use for unexpected errors that don't fit other categories.
+   */
+  InternalServerError = 'InternalServerError',
+
+  /**
+   * Validation error (HTTP 400).
+   * Use when request data fails validation (e.g., Zod errors).
+   */
+  ValidationError = 'ValidationError',
+}

package/src/responders/enums/index.mts

@@ -0,0 +1 @@
+export * from './framework-error.enum.mjs'

package/src/responders/index.mts

@@ -0,0 +1,4 @@
+export * from './enums/index.mjs'
+export * from './interfaces/index.mjs'
+export * from './services/index.mjs'
+export * from './tokens/index.mjs'

package/src/responders/interfaces/error-responder.interface.mts

@@ -0,0 +1,42 @@
+import type { ErrorResponse } from './error-response.interface.mjs'
+
+/**
+ * Interface for error responders that convert errors to HTTP responses.
+ * Each responder handles a specific type of framework error and produces
+ * an RFC 7807 compliant response.
+ *
+ * Implementations are registered with low priority (-10) so they can be
+ * easily overridden by consumers.
+ *
+ * @example
+ * ```typescript
+ * @Injectable({
+ *   token: InternalServerErrorResponderToken,
+ *   priority: 0, // Override default implementation
+ * })
+ * export class CustomInternalErrorResponder implements ErrorResponder {
+ *   getResponse(error: unknown, description?: string): ErrorResponse {
+ *     return {
+ *       statusCode: 500,
+ *       payload: {
+ *         type: 'https://api.myapp.com/errors/server-error',
+ *         title: 'Server Error',
+ *         status: 500,
+ *         detail: description ?? 'An unexpected error occurred',
+ *       },
+ *       headers: { 'Content-Type': 'application/problem+json' },
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export interface ErrorResponder {
+  /**
+   * Converts an error to an ErrorResponse with RFC 7807 Problem Details.
+   *
+   * @param error - The original error that was thrown
+   * @param description - Optional custom description to include in the response
+   * @returns ErrorResponse with status code, payload, and headers
+   */
+  getResponse(error: unknown, description?: string): ErrorResponse
+}

package/src/responders/interfaces/error-response.interface.mts

@@ -0,0 +1,22 @@
+import type { ProblemDetails } from './problem-details.interface.mjs'
+
+/**
+ * Represents a complete error response that can be sent to the client.
+ * Includes the status code, payload (RFC 7807 Problem Details), and headers.
+ */
+export interface ErrorResponse {
+  /**
+   * HTTP status code for the response.
+   */
+  statusCode: number
+
+  /**
+   * RFC 7807 Problem Details payload.
+   */
+  payload: ProblemDetails
+
+  /**
+   * HTTP headers to include in the response.
+   */
+  headers: Record<string, string>
+}

package/src/responders/interfaces/index.mts

@@ -0,0 +1,3 @@
+export * from './error-responder.interface.mjs'
+export * from './error-response.interface.mjs'
+export * from './problem-details.interface.mjs'

package/src/responders/interfaces/problem-details.interface.mts

@@ -0,0 +1,34 @@
+/**
+ * RFC 7807 Problem Details for HTTP APIs
+ * @see https://tools.ietf.org/html/rfc7807
+ */
+export interface ProblemDetails {
+  /**
+   * A URI reference that identifies the problem type.
+   * When dereferenced, it should provide human-readable documentation.
+   * @default 'about:blank'
+   */
+  type?: string
+
+  /**
+   * A short, human-readable summary of the problem type.
+   * It should not change from occurrence to occurrence.
+   */
+  title: string
+
+  /**
+   * The HTTP status code for this occurrence of the problem.
+   */
+  status: number
+
+  /**
+   * A human-readable explanation specific to this occurrence of the problem.
+   */
+  detail?: string
+
+  /**
+   * Additional extension members.
+   * Custom properties can be added to provide more context.
+   */
+  [key: string]: unknown
+}

package/src/responders/services/error-response-producer.service.mts

@@ -0,0 +1,143 @@
+import { inject, Injectable } from '@navios/di'
+
+import { FrameworkError } from '../enums/framework-error.enum.mjs'
+import type { ErrorResponse } from '../interfaces/error-response.interface.mjs'
+import {
+  ForbiddenResponderToken,
+  InternalServerErrorResponderToken,
+  NotFoundResponderToken,
+  ValidationErrorResponderToken,
+} from '../tokens/responder.tokens.mjs'
+
+/**
+ * Service for producing standardized error responses.
+ *
+ * This service coordinates error responders to produce RFC 7807 compliant
+ * Problem Details responses. Adapters use this service to convert errors
+ * into standardized HTTP responses.
+ *
+ * The caller explicitly specifies which type of error response to produce
+ * via the FrameworkError enum, giving full control to the adapter.
+ *
+ * @example Usage in an adapter:
+ * ```typescript
+ * @Injectable()
+ * class MyAdapter {
+ *   private errorProducer = inject(ErrorResponseProducerService)
+ *
+ *   handleError(error: unknown): Response {
+ *     if (error instanceof ZodError) {
+ *       const response = this.errorProducer.respond(
+ *         FrameworkError.ValidationError,
+ *         error,
+ *       )
+ *       return new Response(JSON.stringify(response.payload), {
+ *         status: response.statusCode,
+ *         headers: response.headers,
+ *       })
+ *     }
+ *
+ *     // Fallback for unknown errors
+ *     const response = this.errorProducer.handleUnknown(error)
+ *     return new Response(JSON.stringify(response.payload), {
+ *       status: response.statusCode,
+ *       headers: response.headers,
+ *     })
+ *   }
+ * }
+ * ```
+ */
+@Injectable()
+export class ErrorResponseProducerService {
+  private readonly forbiddenResponder = inject(ForbiddenResponderToken)
+  private readonly internalServerErrorResponder = inject(
+    InternalServerErrorResponderToken,
+  )
+  private readonly notFoundResponder = inject(NotFoundResponderToken)
+  private readonly validationErrorResponder = inject(
+    ValidationErrorResponderToken,
+  )
+
+  /**
+   * Produces an error response for a specific framework error type.
+   *
+   * @param type - The type of framework error (from FrameworkError enum)
+   * @param error - The original error that was thrown
+   * @param description - Optional custom description to include in the response
+   * @returns ErrorResponse with status code, RFC 7807 payload, and headers
+   */
+  respond(
+    type: FrameworkError,
+    error: unknown,
+    description?: string,
+  ): ErrorResponse {
+    switch (type) {
+      case FrameworkError.NotFound:
+        return this.notFoundResponder.getResponse(error, description)
+      case FrameworkError.Forbidden:
+        return this.forbiddenResponder.getResponse(error, description)
+      case FrameworkError.InternalServerError:
+        return this.internalServerErrorResponder.getResponse(error, description)
+      case FrameworkError.ValidationError:
+        return this.validationErrorResponder.getResponse(error, description)
+    }
+  }
+
+  /**
+   * Handles unknown errors by producing an Internal Server Error response.
+   *
+   * Use this as a fallback when the error type is not known or doesn't
+   * match any specific framework error type.
+   *
+   * @param error - The original error that was thrown
+   * @param description - Optional custom description to include in the response
+   * @returns ErrorResponse with 500 status code
+   */
+  handleUnknown(error: unknown, description?: string): ErrorResponse {
+    return this.internalServerErrorResponder.getResponse(error, description)
+  }
+
+  /**
+   * Convenience method to produce a Not Found error response.
+   *
+   * @param error - The original error that was thrown
+   * @param description - Optional custom description
+   * @returns ErrorResponse with 404 status code
+   */
+  notFound(error: unknown, description?: string): ErrorResponse {
+    return this.notFoundResponder.getResponse(error, description)
+  }
+
+  /**
+   * Convenience method to produce a Validation Error response.
+   *
+   * @param error - The original error (typically a ZodError)
+   * @param description - Optional custom description
+   * @returns ErrorResponse with 400 status code
+   */
+  validationError(error: unknown, description?: string): ErrorResponse {
+    return this.validationErrorResponder.getResponse(error, description)
+  }
+
+  /**
+   * Convenience method to produce an Internal Server Error response.
+   *
+   * @param error - The original error
+   * @param description - Optional custom description
+   * @returns ErrorResponse with 500 status code
+   */
+  internalServerError(error: unknown, description?: string): ErrorResponse {
+    return this.internalServerErrorResponder.getResponse(error, description)
+  }
+
+  /**
+   * Convenience method to produce a Forbidden error response.
+   *
+   * @param error - The original error
+   * @param description - Optional custom description
+   * @returns ErrorResponse with 403 status code
+   */
+  forbidden(error: unknown, description?: string): ErrorResponse {
+    return this.forbiddenResponder.getResponse(error, description)
+  }
+}