@navios/core 0.9.2 → 1.0.0-alpha.1

package/src/legacy-compat/attribute.factory.mts

@@ -1,5 +1,5 @@
-import type { ClassType } from '@navios/di'
 import type { z, ZodType } from 'zod/v4'
+import type { ClassType } from '@navios/di'
 
 import type {
   ControllerMetadata,
@@ -21,40 +21,26 @@ import {
 import { createClassContext, createMethodContext } from './context-compat.mjs'
 
 /**
- * Type for a legacy class attribute decorator without a value.
+ * Type for a legacy class/method attribute decorator without a value.
  *
  * Attributes are custom metadata decorators that can be applied to modules,
  * controllers, and endpoints.
  */
-export type LegacyClassAttribute = (() => <T extends ClassType>(
-  target: T,
-) => T) &
-  (() => <T extends object>(
-    target: T,
-    propertyKey: string | symbol,
-    descriptor: PropertyDescriptor,
-  ) => PropertyDescriptor) & {
-    token: symbol
-  }
+export type LegacyClassAttribute = {
+  (): ClassDecorator & MethodDecorator
+  token: symbol
+}
 
 /**
- * Type for a legacy class attribute decorator with a validated value.
+ * Type for a legacy class/method attribute decorator with a validated value.
  *
  * @typeParam S - The Zod schema type for validation
  */
-export type LegacyClassSchemaAttribute<S extends ZodType> = ((
-  value: z.input<S>,
-) => <T extends ClassType>(target: T) => T) &
-  ((
-    value: z.input<S>,
-  ) => <T extends object>(
-    target: T,
-    propertyKey: string | symbol,
-    descriptor: PropertyDescriptor,
-  ) => PropertyDescriptor) & {
-    token: symbol
-    schema: ZodType
-  }
+export type LegacyClassSchemaAttribute<S extends ZodType> = {
+  (value: z.input<S>): ClassDecorator & MethodDecorator
+  token: symbol
+  schema: ZodType
+}
 
 /**
  * Legacy-compatible factory for creating custom attribute decorators.

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)
+  }
+}

package/src/responders/services/forbidden-responder.service.mts

@@ -0,0 +1,77 @@
+import { Injectable } from '@navios/di'
+
+import type { ErrorResponder } from '../interfaces/error-responder.interface.mjs'
+import type { ErrorResponse } from '../interfaces/error-response.interface.mjs'
+import { ForbiddenResponderToken } from '../tokens/responder.tokens.mjs'
+
+/**
+ * Default responder for forbidden errors (HTTP 403).
+ *
+ * Converts errors to RFC 7807 Problem Details format.
+ * Used when access to a resource is denied (e.g., guard rejection).
+ * Registered with low priority (-10) so it can be easily overridden.
+ *
+ * @example Override with custom implementation:
+ * ```typescript
+ * @Injectable({
+ *   token: ForbiddenResponderToken,
+ *   priority: 0,
+ * })
+ * export class CustomForbiddenResponder implements ErrorResponder {
+ *   getResponse(error: unknown, description?: string): ErrorResponse {
+ *     return {
+ *       statusCode: 403,
+ *       payload: {
+ *         type: 'https://api.myapp.com/errors/forbidden',
+ *         title: 'Access Denied',
+ *         status: 403,
+ *         detail: description ?? 'You do not have permission to access this resource',
+ *       },
+ *       headers: { 'Content-Type': 'application/problem+json' },
+ *     }
+ *   }
+ * }
+ * ```
+ */
+@Injectable({
+  token: ForbiddenResponderToken,
+  priority: -10,
+})
+export class ForbiddenResponderService implements ErrorResponder {
+  getResponse(error: unknown, description?: string): ErrorResponse {
+    // Explicit description takes priority
+    if (description) {
+      return this.createResponse(description)
+    }
+
+    // Try to extract detail from error with a response property (like ForbiddenException)
+    if (
+      error &&
+      typeof error === 'object' &&
+      'response' in error &&
+      error.response
+    ) {
+      if (typeof error.response === 'string') {
+        return this.createResponse(error.response)
+      }
+    }
+
+    // Default message
+    return this.createResponse('Access to this resource is forbidden')
+  }
+
+  private createResponse(detail: string): ErrorResponse {
+    return {
+      statusCode: 403,
+      payload: {
+        type: 'about:blank',
+        title: 'Forbidden',
+        status: 403,
+        detail,
+      },
+      headers: {
+        'Content-Type': 'application/problem+json',
+      },
+    }
+  }
+}

package/src/responders/services/index.mts

@@ -0,0 +1,5 @@
+export * from './error-response-producer.service.mjs'
+export * from './forbidden-responder.service.mjs'
+export * from './internal-server-error-responder.service.mjs'
+export * from './not-found-responder.service.mjs'
+export * from './validation-error-responder.service.mjs'

package/src/responders/services/internal-server-error-responder.service.mts

@@ -0,0 +1,57 @@
+import { Injectable } from '@navios/di'
+
+import type { ErrorResponder } from '../interfaces/error-responder.interface.mjs'
+import type { ErrorResponse } from '../interfaces/error-response.interface.mjs'
+import { InternalServerErrorResponderToken } from '../tokens/responder.tokens.mjs'
+
+/**
+ * Default responder for internal server errors (HTTP 500).
+ *
+ * Converts generic errors to RFC 7807 Problem Details format.
+ * Registered with low priority (-10) so it can be easily overridden.
+ *
+ * @example Override with custom implementation:
+ * ```typescript
+ * @Injectable({
+ *   token: InternalServerErrorResponderToken,
+ *   priority: 0,
+ * })
+ * 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' },
+ *     }
+ *   }
+ * }
+ * ```
+ */
+@Injectable({
+  token: InternalServerErrorResponderToken,
+  priority: -10,
+})
+export class InternalServerErrorResponderService implements ErrorResponder {
+  getResponse(error: unknown, description?: string): ErrorResponse {
+    const message =
+      error instanceof Error ? error.message : 'Internal Server Error'
+
+    return {
+      statusCode: 500,
+      payload: {
+        type: 'about:blank',
+        title: 'Internal Server Error',
+        status: 500,
+        detail: description ?? message,
+      },
+      headers: {
+        'Content-Type': 'application/problem+json',
+      },
+    }
+  }
+}

package/src/responders/services/not-found-responder.service.mts

@@ -0,0 +1,76 @@
+import { Injectable } from '@navios/di'
+
+import type { ErrorResponder } from '../interfaces/error-responder.interface.mjs'
+import type { ErrorResponse } from '../interfaces/error-response.interface.mjs'
+import { NotFoundResponderToken } from '../tokens/responder.tokens.mjs'
+
+/**
+ * Default responder for not found errors (HTTP 404).
+ *
+ * Converts errors to RFC 7807 Problem Details format.
+ * Registered with low priority (-10) so it can be easily overridden.
+ *
+ * @example Override with custom implementation:
+ * ```typescript
+ * @Injectable({
+ *   token: NotFoundResponderToken,
+ *   priority: 0,
+ * })
+ * export class CustomNotFoundResponder implements ErrorResponder {
+ *   getResponse(error: unknown, description?: string): ErrorResponse {
+ *     return {
+ *       statusCode: 404,
+ *       payload: {
+ *         type: 'https://api.myapp.com/errors/not-found',
+ *         title: 'Resource Not Found',
+ *         status: 404,
+ *         detail: description ?? 'The requested resource was not found',
+ *       },
+ *       headers: { 'Content-Type': 'application/problem+json' },
+ *     }
+ *   }
+ * }
+ * ```
+ */
+@Injectable({
+  token: NotFoundResponderToken,
+  priority: -10,
+})
+export class NotFoundResponderService implements ErrorResponder {
+  getResponse(error: unknown, description?: string): ErrorResponse {
+    // Explicit description takes priority
+    if (description) {
+      return this.createResponse(description)
+    }
+
+    // Try to extract detail from error with a response property (like NotFoundException)
+    if (
+      error &&
+      typeof error === 'object' &&
+      'response' in error &&
+      error.response
+    ) {
+      if (typeof error.response === 'string') {
+        return this.createResponse(error.response)
+      }
+    }
+
+    // Default message
+    return this.createResponse('The requested resource was not found')
+  }
+
+  private createResponse(detail: string): ErrorResponse {
+    return {
+      statusCode: 404,
+      payload: {
+        type: 'about:blank',
+        title: 'Not Found',
+        status: 404,
+        detail,
+      },
+      headers: {
+        'Content-Type': 'application/problem+json',
+      },
+    }
+  }
+}

package/src/responders/services/validation-error-responder.service.mts

@@ -0,0 +1,78 @@
+import { Injectable } from '@navios/di'
+import { treeifyError, ZodError } from 'zod/v4'
+
+import type { ErrorResponder } from '../interfaces/error-responder.interface.mjs'
+import type { ErrorResponse } from '../interfaces/error-response.interface.mjs'
+import { ValidationErrorResponderToken } from '../tokens/responder.tokens.mjs'
+
+/**
+ * Default responder for validation errors (HTTP 400).
+ *
+ * Converts Zod validation errors to RFC 7807 Problem Details format.
+ * Includes the structured validation errors from treeifyError.
+ * Registered with low priority (-10) so it can be easily overridden.
+ *
+ * @example Override with custom implementation:
+ * ```typescript
+ * @Injectable({
+ *   token: ValidationErrorResponderToken,
+ *   priority: 0,
+ * })
+ * export class CustomValidationResponder implements ErrorResponder {
+ *   getResponse(error: unknown, description?: string): ErrorResponse {
+ *     const zodError = error as ZodError
+ *     return {
+ *       statusCode: 422, // Use 422 instead of 400
+ *       payload: {
+ *         type: 'https://api.myapp.com/errors/validation',
+ *         title: 'Unprocessable Entity',
+ *         status: 422,
+ *         detail: description ?? 'Validation failed',
+ *         issues: zodError.issues,
+ *       },
+ *       headers: { 'Content-Type': 'application/problem+json' },
+ *     }
+ *   }
+ * }
+ * ```
+ */
+@Injectable({
+  token: ValidationErrorResponderToken,
+  priority: -10,
+})
+export class ValidationErrorResponderService implements ErrorResponder {
+  getResponse(error: unknown, description?: string): ErrorResponse {
+    // Handle ZodError specifically
+    if (error instanceof ZodError) {
+      return {
+        statusCode: 400,
+        payload: {
+          type: 'about:blank',
+          title: 'Validation Error',
+          status: 400,
+          detail: description ?? 'Request validation failed',
+          errors: treeifyError(error),
+        },
+        headers: {
+          'Content-Type': 'application/problem+json',
+        },
+      }
+    }
+
+    // Fallback for non-Zod validation errors
+    return {
+      statusCode: 400,
+      payload: {
+        type: 'about:blank',
+        title: 'Validation Error',
+        status: 400,
+        detail:
+          description ??
+          (error instanceof Error ? error.message : 'Validation failed'),
+      },
+      headers: {
+        'Content-Type': 'application/problem+json',
+      },
+    }
+  }
+}

package/src/responders/tokens/index.mts

@@ -0,0 +1 @@
+export * from './responder.tokens.mjs'