@navios/core 0.5.1 → 0.7.0

package/src/legacy-compat/__type-tests__/legacy-decorators.spec-d.mts

@@ -0,0 +1,420 @@
+// oxlint-disable no-unused-vars
+import { builder } from '@navios/builder'
+
+import { describe, expectTypeOf, test } from 'vitest'
+import { z } from 'zod/v4'
+
+import type {
+  EndpointParams,
+  EndpointResult,
+  MultipartParams,
+  MultipartResult,
+  StreamParams,
+} from '../index.mjs'
+
+import {
+  Controller,
+  Endpoint,
+  Header,
+  HttpCode,
+  Module,
+  Multipart,
+  Stream,
+  UseGuards,
+} from '../index.mjs'
+
+// Create a test API builder
+const api = builder()
+
+// Test schemas
+const responseSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+})
+
+const querySchema = z.object({
+  page: z.number(),
+  limit: z.number(),
+})
+
+const requestSchema = z.object({
+  name: z.string(),
+  email: z.string(),
+})
+
+const multipartRequestSchema = z.object({
+  file: z.instanceof(File),
+  description: z.string(),
+})
+
+// Test endpoint declarations
+const getUserEndpoint = api.declareEndpoint({
+  method: 'GET',
+  url: '/users/$userId',
+  querySchema,
+  responseSchema,
+})
+
+const createUserEndpoint = api.declareEndpoint({
+  method: 'POST',
+  url: '/users',
+  requestSchema,
+  responseSchema,
+})
+
+const uploadFileEndpoint = api.declareMultipart({
+  method: 'POST',
+  url: '/upload',
+  requestSchema: multipartRequestSchema,
+  responseSchema,
+})
+
+const downloadFileEndpoint = api.declareStream({
+  method: 'GET',
+  url: '/files/$fileId',
+  querySchema,
+})
+
+// Mock guard for testing
+class AuthGuard {
+  canActivate() {
+    return true
+  }
+}
+
+describe('Legacy Decorators Type Safety', () => {
+  describe('Module decorator', () => {
+    test('should accept valid module options', () => {
+      @Module({
+        controllers: [],
+        imports: [],
+        guards: [],
+      })
+      class TestModule {}
+
+      expectTypeOf(TestModule).toBeConstructibleWith()
+    })
+
+    test('should accept controllers in module', () => {
+      @Controller()
+      class TestController {}
+
+      @Module({
+        controllers: [TestController],
+      })
+      class TestModule {}
+
+      expectTypeOf(TestModule).toBeConstructibleWith()
+    })
+  })
+
+  describe('Controller decorator', () => {
+    test('should accept valid controller options', () => {
+      @Controller()
+      class TestController {}
+
+      expectTypeOf(TestController).toBeConstructibleWith()
+    })
+
+    test('should accept guards in controller', () => {
+      @Controller({
+        guards: [AuthGuard],
+      })
+      class TestController {}
+
+      expectTypeOf(TestController).toBeConstructibleWith()
+    })
+  })
+
+  describe('Endpoint decorator', () => {
+    test('should enforce correct parameter type', () => {
+      @Controller()
+      class UserController {
+        @Endpoint(getUserEndpoint)
+        async getUser(
+          request: EndpointParams<typeof getUserEndpoint>,
+        ): EndpointResult<typeof getUserEndpoint> {
+          // TypeScript should infer:
+          // - request.urlParams.userId: string | number
+          // - request.params.page: number
+          // - request.params.limit: number
+          expectTypeOf(request.urlParams.userId).toEqualTypeOf<
+            string | number
+          >()
+          expectTypeOf(request.params.page).toEqualTypeOf<number>()
+          expectTypeOf(request.params.limit).toEqualTypeOf<number>()
+          return {
+            id: request.urlParams.userId.toString(),
+            name: 'Test',
+          }
+        }
+      }
+
+      expectTypeOf(UserController).toBeConstructibleWith()
+    })
+
+    test('should enforce correct return type', () => {
+      @Controller()
+      class UserController {
+        @Endpoint(getUserEndpoint)
+        async getUser(
+          request: EndpointParams<typeof getUserEndpoint>,
+        ): EndpointResult<typeof getUserEndpoint> {
+          // Return type should match responseSchema
+          return {
+            id: '1',
+            name: 'John',
+          }
+        }
+      }
+
+      expectTypeOf(UserController).toBeConstructibleWith()
+    })
+
+    test('should reject incorrect parameter type', () => {
+      @Controller()
+      class UserController {
+        // @ts-expect-error - wrong parameter type
+        @Endpoint(getUserEndpoint)
+        async getUser(request: {
+          wrong: string
+        }): EndpointResult<typeof getUserEndpoint> {
+          return { id: '1', name: 'John' }
+        }
+      }
+    })
+
+    test('should reject incorrect return type', () => {
+      @Controller()
+      class UserController {
+        @Endpoint(getUserEndpoint)
+        async getUser(
+          request: EndpointParams<typeof getUserEndpoint>,
+        ): EndpointResult<typeof getUserEndpoint> {
+          // @ts-expect-error - wrong return type
+          return { wrong: 'value' }
+        }
+      }
+    })
+
+    test('should work with POST endpoint with request body', () => {
+      @Controller()
+      class UserController {
+        @Endpoint(createUserEndpoint)
+        async createUser(
+          request: EndpointParams<typeof createUserEndpoint>,
+        ): EndpointResult<typeof createUserEndpoint> {
+          // TypeScript should infer:
+          // - request.data.name: string
+          // - request.data.email: string
+          expectTypeOf(request.data.name).toEqualTypeOf<string>()
+          expectTypeOf(request.data.email).toEqualTypeOf<string>()
+          return {
+            id: '1',
+            name: request.data.name,
+          }
+        }
+      }
+
+      expectTypeOf(UserController).toBeConstructibleWith()
+    })
+  })
+
+  describe('Multipart decorator', () => {
+    test('should enforce correct parameter type', () => {
+      @Controller()
+      class FileController {
+        @Multipart(uploadFileEndpoint)
+        async uploadFile(
+          request: MultipartParams<typeof uploadFileEndpoint>,
+        ): MultipartResult<typeof uploadFileEndpoint> {
+          // TypeScript should infer:
+          // - request.data.file: File
+          // - request.data.description: string
+          expectTypeOf(request.data.file).toEqualTypeOf<File>()
+          expectTypeOf(request.data.description).toEqualTypeOf<string>()
+          return {
+            id: '1',
+            name: 'uploaded.jpg',
+          }
+        }
+      }
+
+      expectTypeOf(FileController).toBeConstructibleWith()
+    })
+
+    test('should reject incorrect parameter type', () => {
+      @Controller()
+      class FileController {
+        // @ts-expect-error - wrong parameter type
+        @Multipart(uploadFileEndpoint)
+        async uploadFile(request: {
+          wrong: string
+        }): MultipartResult<typeof uploadFileEndpoint> {
+          return { id: '1', name: 'test.jpg' }
+        }
+      }
+    })
+  })
+
+  describe('Stream decorator', () => {
+    test('should enforce correct parameter type', () => {
+      @Controller()
+      class FileController {
+        @Stream(downloadFileEndpoint)
+        async downloadFile(
+          request: StreamParams<typeof downloadFileEndpoint>,
+          reply: any,
+        ): Promise<void> {
+          // TypeScript should infer:
+          // - request.urlParams.fileId: string | number
+          // - request.params.page: number
+          // - request.params.limit: number
+          expectTypeOf(request.urlParams.fileId).toEqualTypeOf<
+            string | number
+          >()
+          expectTypeOf(request.params.page).toEqualTypeOf<number>()
+          expectTypeOf(request.params.limit).toEqualTypeOf<number>()
+        }
+      }
+
+      expectTypeOf(FileController).toBeConstructibleWith()
+    })
+
+    test('should require reply parameter', () => {
+      @Controller()
+      class FileController {
+        // @ts-expect-error - missing reply parameter
+        @Stream(downloadFileEndpoint)
+        async downloadFile(
+          request: StreamParams<typeof downloadFileEndpoint>,
+        ): Promise<void> {
+          // Stream methods must have reply parameter
+        }
+      }
+    })
+  })
+
+  describe('UseGuards decorator', () => {
+    test('should work on class level', () => {
+      @Controller()
+      @UseGuards(AuthGuard)
+      class ProtectedController {
+        @Endpoint(getUserEndpoint)
+        async getUser(
+          request: EndpointParams<typeof getUserEndpoint>,
+        ): EndpointResult<typeof getUserEndpoint> {
+          return { id: '1', name: 'John' }
+        }
+      }
+
+      expectTypeOf(ProtectedController).toBeConstructibleWith()
+    })
+
+    test('should work on method level', () => {
+      @Controller()
+      class UserController {
+        @Endpoint(getUserEndpoint)
+        @UseGuards(AuthGuard)
+        async getUser(
+          request: EndpointParams<typeof getUserEndpoint>,
+        ): EndpointResult<typeof getUserEndpoint> {
+          return { id: '1', name: 'John' }
+        }
+      }
+
+      expectTypeOf(UserController).toBeConstructibleWith()
+    })
+  })
+
+  describe('Header decorator', () => {
+    test('should work with string value', () => {
+      @Controller()
+      class UserController {
+        @Endpoint(getUserEndpoint)
+        @Header('Cache-Control', 'max-age=3600')
+        async getUser(
+          request: EndpointParams<typeof getUserEndpoint>,
+        ): EndpointResult<typeof getUserEndpoint> {
+          return { id: '1', name: 'John' }
+        }
+      }
+
+      expectTypeOf(UserController).toBeConstructibleWith()
+    })
+
+    test('should work with number value', () => {
+      @Controller()
+      class UserController {
+        @Endpoint(getUserEndpoint)
+        @Header('Content-Length', 100)
+        async getUser(
+          request: EndpointParams<typeof getUserEndpoint>,
+        ): EndpointResult<typeof getUserEndpoint> {
+          return { id: '1', name: 'John' }
+        }
+      }
+
+      expectTypeOf(UserController).toBeConstructibleWith()
+    })
+  })
+
+  describe('HttpCode decorator', () => {
+    test('should accept valid status codes', () => {
+      @Controller()
+      class UserController {
+        @Endpoint(createUserEndpoint)
+        @HttpCode(201)
+        async createUser(
+          request: EndpointParams<typeof createUserEndpoint>,
+        ): EndpointResult<typeof createUserEndpoint> {
+          return { id: '1', name: request.data.name }
+        }
+      }
+
+      expectTypeOf(UserController).toBeConstructibleWith()
+    })
+  })
+
+  describe('Integration test - full controller', () => {
+    test('should work with all decorators together', () => {
+      @Controller({
+        guards: [AuthGuard],
+      })
+      @UseGuards(AuthGuard)
+      class UserController {
+        @Endpoint(getUserEndpoint)
+        @UseGuards(AuthGuard)
+        @Header('Cache-Control', 'max-age=3600')
+        @HttpCode(200)
+        async getUser(
+          request: EndpointParams<typeof getUserEndpoint>,
+        ): EndpointResult<typeof getUserEndpoint> {
+          return {
+            id: request.urlParams.userId.toString(),
+            name: 'John',
+          }
+        }
+
+        @Endpoint(createUserEndpoint)
+        @HttpCode(201)
+        async createUser(
+          request: EndpointParams<typeof createUserEndpoint>,
+        ): EndpointResult<typeof createUserEndpoint> {
+          return {
+            id: '1',
+            name: request.data.name,
+          }
+        }
+      }
+
+      @Module({
+        controllers: [UserController],
+      })
+      class AppModule {}
+
+      expectTypeOf(UserController).toBeConstructibleWith()
+      expectTypeOf(AppModule).toBeConstructibleWith()
+    })
+  })
+})

package/src/legacy-compat/__type-tests__/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "extends": "../../../../../tsconfig.base.json",
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": false,
+    "outDir": "../../../dist/legacy-compat/__type-tests__"
+  },
+  "include": ["**/*.spec-d.mts"],
+  "exclude": [],
+  "references": [
+    {
+      "path": "../../../tsconfig.lib.json"
+    }
+  ]
+}

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

@@ -0,0 +1,19 @@
+/**
+ * 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';
+/**
+ * Creates a mock ClassDecoratorContext for legacy class decorators.
+ */
+export declare function createClassContext(target: ClassType): 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 declare function createMethodContext(target: any, propertyKey: string | symbol, descriptor: PropertyDescriptor): ClassMethodDecoratorContext;
+//# sourceMappingURL=context-compat.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"context-compat.d.mts","sourceRoot":"","sources":["context-compat.mts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAuB3C;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,GAAG,qBAAqB,CAe3E;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,GAAG,EACX,WAAW,EAAE,MAAM,GAAG,MAAM,EAC5B,UAAU,EAAE,kBAAkB,GAC7B,2BAA2B,CAgC7B"}

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.d.mts

@@ -0,0 +1,21 @@
+import type { ClassType } from '@navios/di';
+import type { ControllerOptions } from '../../decorators/controller.decorator.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 declare function Controller(options?: ControllerOptions): (target: ClassType) => ClassType;
+//# sourceMappingURL=controller.decorator.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"controller.decorator.d.mts","sourceRoot":"","sources":["controller.decorator.mts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAE3C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2CAA2C,CAAA;AAKlF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,UAAU,CAAC,OAAO,GAAE,iBAAsB,IACvC,QAAQ,SAAS,eAKnC"}

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.d.mts

@@ -0,0 +1,33 @@
+import type { BaseEndpointConfig, EndpointFunctionArgs, HttpMethod } from '@navios/builder';
+import type { z, ZodType } from 'zod/v4';
+/**
+ * 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 declare 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>;
+}): (target: any, propertyKey: string | symbol, descriptor: EndpointMethodDescriptor<Url, QuerySchema, RequestSchema, ResponseSchema>) => PropertyDescriptor | void;
+
+//# sourceMappingURL=endpoint.decorator.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint.decorator.d.mts","sourceRoot":"","sources":["endpoint.decorator.mts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,oBAAoB,EACpB,UAAU,EACX,MAAM,iBAAiB,CAAA;AACxB,OAAO,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAA;AAKxC;;;;GAIG;AACH,KAAK,wBAAwB,CAC3B,GAAG,SAAS,MAAM,EAClB,WAAW,EACX,aAAa,EACb,cAAc,SAAS,OAAO,IAC5B,uBAAuB,CACzB,CACE,MAAM,EAAE,WAAW,SAAS,OAAO,GAC/B,aAAa,SAAS,OAAO,GAC3B,oBAAoB,CAAC,GAAG,EAAE,WAAW,EAAE,aAAa,EAAE,IAAI,CAAC,GAC3D,oBAAoB,CAAC,GAAG,EAAE,WAAW,EAAE,SAAS,EAAE,IAAI,CAAC,GACzD,aAAa,SAAS,OAAO,GAC3B,oBAAoB,CAAC,GAAG,EAAE,SAAS,EAAE,aAAa,EAAE,IAAI,CAAC,GACzD,oBAAoB,CAAC,GAAG,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,CAAC,KACxD,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,CACtC,CAAA;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,QAAQ,CACtB,MAAM,SAAS,UAAU,GAAG,UAAU,EACtC,GAAG,SAAS,MAAM,GAAG,MAAM,EAC3B,WAAW,GAAG,SAAS,EACvB,cAAc,SAAS,OAAO,GAAG,OAAO,EACxC,aAAa,GAAG,OAAO,EACvB,QAAQ,EAAE;IACV,MAAM,EAAE,kBAAkB,CACxB,MAAM,EACN,GAAG,EACH,WAAW,EACX,cAAc,EACd,aAAa,CACd,CAAA;CACF,IAEG,QAAQ,GAAG,EACX,aAAa,MAAM,GAAG,MAAM,EAC5B,YAAY,wBAAwB,CAClC,GAAG,EACH,WAAW,EACX,aAAa,EACb,cAAc,CACf,KACA,kBAAkB,GAAG,IAAI,CAsB7B"}