@navios/core 0.6.0 → 0.7.1

package/src/legacy-compat/context-compat.mts

@@ -0,0 +1,93 @@
+/**
+ * Compatibility layer for converting legacy decorator signatures to Stage 3 format.
+ *
+ * This module provides utilities to create mock Stage 3 decorator contexts
+ * from legacy decorator arguments, and manages metadata storage using WeakMap.
+ */
+
+import type { ClassType } from '@navios/di'
+
+// WeakMap to store metadata for legacy decorators
+// Keyed by class constructor for class decorators
+// For method decorators, we use the class constructor (extracted from the prototype)
+const classMetadataMap = new WeakMap<ClassType, Record<string | symbol, any>>()
+
+/**
+ * Gets the constructor from a prototype (for method decorators).
+ */
+function getConstructor(prototype: any): ClassType | null {
+  if (!prototype || typeof prototype !== 'object') {
+    return null
+  }
+  // In legacy decorators, target is the prototype
+  // The constructor is typically available via prototype.constructor
+  const constructor = prototype.constructor
+  if (constructor && typeof constructor === 'function') {
+    return constructor as ClassType
+  }
+  return null
+}
+
+/**
+ * Creates a mock ClassDecoratorContext for legacy class decorators.
+ */
+export function createClassContext(target: ClassType): ClassDecoratorContext {
+  // Get or create metadata storage for this class
+  if (!classMetadataMap.has(target)) {
+    classMetadataMap.set(target, {})
+  }
+  const metadata = classMetadataMap.get(target)!
+
+  return {
+    kind: 'class',
+    name: target.name,
+    metadata,
+    addInitializer() {
+      // Legacy decorators don't support initializers
+    },
+  } as ClassDecoratorContext
+}
+
+/**
+ * Creates a mock ClassMethodDecoratorContext for legacy method decorators.
+ *
+ * Note: Method decorators need to share metadata with the class context
+ * because endpoint metadata is stored at the class level.
+ */
+export function createMethodContext(
+  target: any,
+  propertyKey: string | symbol,
+  descriptor: PropertyDescriptor,
+): ClassMethodDecoratorContext {
+  // For method decorators, target is the prototype
+  // We need to get the class constructor to access class-level metadata
+  const constructor = getConstructor(target)
+  if (!constructor) {
+    throw new Error(
+      '[Navios] Could not determine class constructor from method decorator target.',
+    )
+  }
+
+  // Get or create metadata storage for the class
+  // Method decorators share metadata with the class
+  if (!classMetadataMap.has(constructor)) {
+    classMetadataMap.set(constructor, {})
+  }
+  const metadata = classMetadataMap.get(constructor)!
+
+  return {
+    kind: 'method',
+    name: propertyKey,
+    metadata,
+    static: false, // We can't determine this from legacy decorators
+    private: false, // We can't determine this from legacy decorators
+    access: {
+      has: () => true,
+      get: () => descriptor.value,
+      set: () => {},
+    },
+    addInitializer() {
+      // Legacy decorators don't support initializers
+    },
+  } as ClassMethodDecoratorContext
+}

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

@@ -0,0 +1,31 @@
+import type { ClassType } from '@navios/di'
+
+import type { ControllerOptions } from '../../decorators/controller.decorator.mjs'
+
+import { Controller as OriginalController } from '../../decorators/controller.decorator.mjs'
+import { createClassContext } from '../context-compat.mjs'
+
+/**
+ * Legacy-compatible Controller decorator.
+ *
+ * Works with TypeScript experimental decorators (legacy API).
+ *
+ * @param options - Controller configuration options
+ * @returns A class decorator compatible with legacy decorator API
+ *
+ * @example
+ * ```typescript
+ * @Controller({ guards: [AuthGuard] })
+ * export class UserController {
+ *   @Endpoint(getUserEndpoint)
+ *   async getUser() { }
+ * }
+ * ```
+ */
+export function Controller(options: ControllerOptions = {}) {
+  return function (target: ClassType) {
+    const context = createClassContext(target)
+    const originalDecorator = OriginalController(options)
+    return originalDecorator(target, context)
+  }
+}

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

@@ -0,0 +1,99 @@
+import type {
+  BaseEndpointConfig,
+  EndpointFunctionArgs,
+  HttpMethod,
+} from '@navios/builder'
+import type { z, ZodType } from 'zod/v4'
+
+import { Endpoint as OriginalEndpoint } from '../../decorators/endpoint.decorator.mjs'
+import { createMethodContext } from '../context-compat.mjs'
+
+/**
+ * Type helper to constrain a PropertyDescriptor's value to match an endpoint signature.
+ * 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>>
+>
+
+/**
+ * Legacy-compatible Endpoint decorator.
+ *
+ * Works with TypeScript experimental decorators (legacy API).
+ * Provides type safety by ensuring method signatures match the endpoint configuration.
+ *
+ * @param endpoint - The endpoint declaration from @navios/builder
+ * @returns A method decorator compatible with legacy decorator API
+ *
+ * @example
+ * ```typescript
+ * @Controller()
+ * export class UserController {
+ *   @Endpoint(getUserEndpoint)
+ *   async getUser(request: EndpointParams<typeof getUserEndpoint>): EndpointResult<typeof getUserEndpoint> {
+ *     return { id: '1', name: 'John' }
+ *   }
+ * }
+ * ```
+ */
+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
+  >
+}) {
+  return function (
+    target: any,
+    propertyKey: string | symbol,
+    descriptor: EndpointMethodDescriptor<
+      Url,
+      QuerySchema,
+      RequestSchema,
+      ResponseSchema
+    >,
+  ): PropertyDescriptor | void {
+    if (!descriptor) {
+      throw new Error(
+        '[Navios] @Endpoint decorator requires a method descriptor. Make sure experimentalDecorators is enabled.',
+      )
+    }
+    // Type check the descriptor value matches expected signature
+    const typedDescriptor = descriptor as EndpointMethodDescriptor<
+      Url,
+      QuerySchema,
+      RequestSchema,
+      ResponseSchema
+    >
+    const context = createMethodContext(target, propertyKey, typedDescriptor)
+    const originalDecorator = OriginalEndpoint(endpoint)
+    // @ts-expect-error - we don't need to type the value
+    const result = originalDecorator(typedDescriptor.value, context)
+    if (result !== typedDescriptor.value) {
+      typedDescriptor.value = result
+    }
+    return typedDescriptor
+  }
+}

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

@@ -0,0 +1,42 @@
+import type { HttpHeader } from '../../interfaces/index.mjs'
+
+import { Header as OriginalHeader } from '../../decorators/header.decorator.mjs'
+import { createMethodContext } from '../context-compat.mjs'
+
+/**
+ * Legacy-compatible Header decorator.
+ * 
+ * Works with TypeScript experimental decorators (legacy API).
+ * 
+ * @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 compatible with legacy decorator API
+ * 
+ * @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 function <T extends object>(
+    target: T,
+    propertyKey: string | symbol,
+    descriptor: PropertyDescriptor,
+  ) {
+    const context = createMethodContext(target, propertyKey, descriptor)
+    const originalDecorator = OriginalHeader(name, value)
+    const result = originalDecorator(descriptor.value, context)
+    if (result !== descriptor.value) {
+      descriptor.value = result
+    }
+    return descriptor
+  }
+}
+

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

@@ -0,0 +1,38 @@
+import { HttpCode as OriginalHttpCode } from '../../decorators/http-code.decorator.mjs'
+import { createMethodContext } from '../context-compat.mjs'
+
+/**
+ * Legacy-compatible HttpCode decorator.
+ *
+ * Works with TypeScript experimental decorators (legacy API).
+ *
+ * @param code - The HTTP status code to return (e.g., 201, 204, 202)
+ * @returns A method decorator compatible with legacy decorator API
+ *
+ * @example
+ * ```typescript
+ * @Controller()
+ * export class UserController {
+ *   @Endpoint(createUserEndpoint)
+ *   @HttpCode(201)
+ *   async createUser() {
+ *     return { id: '1', name: 'John' }
+ *   }
+ * }
+ * ```
+ */
+export function HttpCode(code: number) {
+  return function <T extends object>(
+    target: T,
+    propertyKey: string | symbol,
+    descriptor: PropertyDescriptor,
+  ) {
+    const context = createMethodContext(target, propertyKey, descriptor)
+    const originalDecorator = OriginalHttpCode(code)
+    const result = originalDecorator(descriptor.value, context)
+    if (result !== descriptor.value) {
+      descriptor.value = result
+    }
+    return descriptor
+  }
+}

package/src/legacy-compat/decorators/index.mts

@@ -0,0 +1,9 @@
+export * from './module.decorator.mjs'
+export * from './controller.decorator.mjs'
+export * from './endpoint.decorator.mjs'
+export * from './use-guards.decorator.mjs'
+export * from './header.decorator.mjs'
+export * from './http-code.decorator.mjs'
+export * from './multipart.decorator.mjs'
+export * from './stream.decorator.mjs'
+

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

@@ -0,0 +1,37 @@
+import type { ClassType } from '@navios/di'
+
+import { Module as OriginalModule, type ModuleOptions } from '../../decorators/module.decorator.mjs'
+import { createClassContext } from '../context-compat.mjs'
+
+/**
+ * Legacy-compatible Module decorator.
+ * 
+ * Works with TypeScript experimental decorators (legacy API).
+ * 
+ * @param options - Module configuration options
+ * @returns A class decorator compatible with legacy decorator API
+ * 
+ * @example
+ * ```typescript
+ * @Module({
+ *   controllers: [UserController, AuthController],
+ *   imports: [DatabaseModule],
+ *   guards: [AuthGuard],
+ * })
+ * export class AppModule {}
+ * ```
+ */
+export function Module(
+  options: ModuleOptions = {
+    controllers: [],
+    imports: [],
+    guards: [],
+  },
+) {
+  return function (target: ClassType) {
+    const context = createClassContext(target)
+    const originalDecorator = OriginalModule(options)
+    return originalDecorator(target, context)
+  }
+}
+

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

@@ -0,0 +1,93 @@
+import type {
+  BaseEndpointConfig,
+  EndpointFunctionArgs,
+  HttpMethod,
+} from '@navios/builder'
+import type { z, ZodObject, ZodType } from 'zod/v4'
+
+import { Multipart as OriginalMultipart } from '../../decorators/multipart.decorator.mjs'
+import { createMethodContext } from '../context-compat.mjs'
+
+/**
+ * Type helper to constrain a PropertyDescriptor's value to match a multipart endpoint signature.
+ * 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>
+        : EndpointFunctionArgs<Url, QuerySchema, undefined>
+      : RequestSchema extends ZodType
+        ? EndpointFunctionArgs<Url, undefined, RequestSchema>
+        : EndpointFunctionArgs<Url, undefined, undefined>,
+  ) => Promise<z.input<ResponseSchema>>
+>
+
+/**
+ * Legacy-compatible Multipart decorator.
+ *
+ * Works with TypeScript experimental decorators (legacy API).
+ * Provides type safety by ensuring method signatures match the endpoint configuration.
+ *
+ * @param endpoint - The multipart endpoint declaration from @navios/builder
+ * @returns A method decorator compatible with legacy decorator API
+ *
+ * @example
+ * ```typescript
+ * @Controller()
+ * export class FileController {
+ *   @Multipart(uploadFileEndpoint)
+ *   async uploadFile(request: MultipartParams<typeof uploadFileEndpoint>): MultipartResult<typeof uploadFileEndpoint> {
+ *     const { file } = request.data
+ *     return { url: 'https://example.com/file.jpg' }
+ *   }
+ * }
+ * ```
+ */
+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
+  >
+}) {
+  return function <T extends object>(
+    target: T,
+    propertyKey: string | symbol,
+    descriptor: MultipartMethodDescriptor<
+      Url,
+      QuerySchema,
+      RequestSchema,
+      ResponseSchema
+    >,
+  ): PropertyDescriptor | void {
+    if (!descriptor) {
+      throw new Error(
+        '[Navios] @Multipart decorator requires a method descriptor. Make sure experimentalDecorators is enabled.',
+      )
+    }
+    const context = createMethodContext(target, propertyKey, descriptor)
+    const originalDecorator = OriginalMultipart(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
+    }
+    return descriptor
+  }
+}

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

@@ -0,0 +1,76 @@
+import type {
+  BaseStreamConfig,
+  EndpointFunctionArgs,
+  HttpMethod,
+} 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 helper to constrain a PropertyDescriptor's value to match a stream endpoint signature.
+ * 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,
+> = TypedPropertyDescriptor<
+  (
+    params: QuerySchema extends ZodObject
+      ? RequestSchema extends ZodType
+        ? EndpointFunctionArgs<Url, QuerySchema, RequestSchema>
+        : EndpointFunctionArgs<Url, QuerySchema, undefined>
+      : RequestSchema extends ZodType
+        ? EndpointFunctionArgs<Url, undefined, RequestSchema>
+        : EndpointFunctionArgs<Url, undefined, undefined>,
+    reply: any,
+  ) => Promise<void>
+>
+
+/**
+ * Legacy-compatible Stream decorator.
+ *
+ * Works with TypeScript experimental decorators (legacy API).
+ * Provides type safety by ensuring method signatures match the endpoint configuration.
+ *
+ * @param endpoint - The stream endpoint declaration from @navios/builder
+ * @returns A method decorator compatible with legacy decorator API
+ *
+ * @example
+ * ```typescript
+ * @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,
+  QuerySchema = undefined,
+  RequestSchema = ZodType,
+>(endpoint: {
+  config: BaseStreamConfig<Method, Url, QuerySchema, RequestSchema>
+}) {
+  return function <T extends object>(
+    target: T,
+    propertyKey: string | symbol,
+    descriptor: StreamMethodDescriptor<Url, QuerySchema, RequestSchema>,
+  ) {
+    const context = createMethodContext(target, propertyKey, descriptor)
+    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
+    }
+    return descriptor
+  }
+}

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

@@ -0,0 +1,80 @@
+import type {
+  ClassType,
+  ClassTypeWithInstance,
+  InjectionToken,
+} from '@navios/di'
+
+import type { CanActivate } from '../../interfaces/index.mjs'
+
+import { UseGuards as OriginalUseGuards } from '../../decorators/use-guards.decorator.mjs'
+import { createClassContext, createMethodContext } from '../context-compat.mjs'
+
+/**
+ * Legacy-compatible UseGuards decorator.
+ *
+ * Works with TypeScript experimental decorators (legacy API).
+ * Can be applied to classes or methods.
+ *
+ * @param guards - Guard classes or injection tokens to apply
+ * @returns A class or method decorator compatible with legacy decorator API
+ *
+ * @example
+ * ```typescript
+ * // Apply to a controller
+ * @Controller()
+ * @UseGuards(AuthGuard, RoleGuard)
+ * export class UserController { }
+ *
+ * // Apply to a specific endpoint
+ * @Controller()
+ * export class UserController {
+ *   @Endpoint(getUserEndpoint)
+ *   @UseGuards(AuthGuard)
+ *   async getUser() { }
+ * }
+ * ```
+ */
+export function UseGuards(
+  ...guards: (
+    | ClassTypeWithInstance<CanActivate>
+    | InjectionToken<CanActivate, undefined>
+  )[]
+) {
+  // Create the decorator function
+  // Note: TypeScript's legacy decorator system has strict type checking for decorators
+  // We use a flexible implementation that works for both class and method decorators
+  function decoratorImpl(
+    target: ClassType | Function,
+    propertyKey?: string | symbol,
+    descriptor?: PropertyDescriptor,
+  ): any {
+    // Determine if this is a class or method decorator
+    if (propertyKey !== undefined && descriptor !== undefined) {
+      // Method decorator
+      const context = createMethodContext(
+        target as Function,
+        propertyKey,
+        descriptor,
+      )
+      const originalDecorator = OriginalUseGuards(...guards)
+      const result = originalDecorator(descriptor.value, context)
+      if (result !== descriptor.value) {
+        descriptor.value = result
+      }
+      return descriptor
+    } else {
+      // Class decorator
+      const context = createClassContext(target as ClassType)
+      const originalDecorator = OriginalUseGuards(...guards)
+      return originalDecorator(target as ClassType, context)
+    }
+  }
+
+  // Return with 'any' type to work around TypeScript's strict decorator checking
+  // TypeScript's legacy decorator system cannot properly type-check decorators
+  // that work as both class and method decorators. The runtime behavior is correct.
+  // When used as a class decorator, it returns the class (preserving type at runtime)
+  // When used as a method decorator, it returns the PropertyDescriptor
+  // @ts-ignore - TypeScript limitation with dual-purpose legacy decorators
+  return decoratorImpl as any
+}

package/src/legacy-compat/index.mts

@@ -0,0 +1,40 @@
+/**
+ * Legacy-compatible decorators for projects that cannot use Stage 3 decorators.
+ * 
+ * These decorators use the TypeScript experimental decorator API and convert
+ * the arguments to Stage 3 format internally.
+ * 
+ * @example
+ * ```typescript
+ * import { Module, Controller, Endpoint } from '@navios/core/legacy-compat'
+ * 
+ * @Module({
+ *   controllers: [UserController],
+ * })
+ * export class AppModule {}
+ * ```
+ */
+
+// Re-export types
+export type {
+  ModuleOptions,
+  ControllerOptions,
+  EndpointParams,
+  EndpointResult,
+  MultipartParams,
+  MultipartResult,
+  StreamParams,
+} from '../decorators/index.mjs'
+
+// Export legacy-compatible decorators
+export {
+  Module,
+  Controller,
+  Endpoint,
+  UseGuards,
+  Header,
+  HttpCode,
+  Multipart,
+  Stream,
+} from './decorators/index.mjs'
+

package/src/logger/console-logger.service.mts

@@ -7,6 +7,7 @@ import { Injectable } from '@navios/di'
 import type { LogLevel } from './log-levels.mjs'
 import type { LoggerService } from './logger-service.interface.mjs'
 
+import { getRequestId } from '../stores/request-id.store.mjs'
 import { LoggerOutput } from './logger.tokens.mjs'
 import {
   clc,
@@ -312,6 +313,17 @@ export class ConsoleLogger implements LoggerService {
     return isLogLevelEnabled(level, logLevels)
   }
 
+  /**
+   * Gets the current request ID from the AsyncLocalStorage store.
+   * Only returns a value if the requestId option is enabled.
+   */
+  protected getCurrentRequestId(): string | undefined {
+    if (!this.options.requestId) {
+      return undefined
+    }
+    return getRequestId()
+  }
+
   protected getTimestamp(): string {
     return dateTimeFormatter.format(Date.now())
   }
@@ -324,6 +336,7 @@ export class ConsoleLogger implements LoggerService {
     writeStreamType?: 'stdout' | 'stderr',
     errorStack?: unknown,
   ) {
+    const resolvedRequestId = requestId ?? this.getCurrentRequestId()
     messages.forEach((message) => {
       if (this.options.json) {
         this.printAsJson(message, {
@@ -331,7 +344,7 @@ export class ConsoleLogger implements LoggerService {
           logLevel,
           writeStreamType,
           errorStack,
-          requestId,
+          requestId: resolvedRequestId,
         })
         return
       }
@@ -346,7 +359,7 @@ export class ConsoleLogger implements LoggerService {
         formattedLogLevel,
         contextMessage,
         timestampDiff,
-        requestId,
+        resolvedRequestId,
       )
 
       process[writeStreamType ?? 'stdout'].write(formattedMessage)