@navios/core 0.8.0 → 0.9.1

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

@@ -13,10 +13,12 @@ import type {
 } from '../index.mjs'
 
 import {
+  AttributeFactory,
   Controller,
   Endpoint,
   Header,
   HttpCode,
+  Injectable,
   Module,
   Multipart,
   Stream,
@@ -138,9 +140,7 @@ describe('Legacy Decorators Type Safety', () => {
           // - request.urlParams.userId: string | number
           // - request.params.page: number
           // - request.params.limit: number
-          expectTypeOf(request.urlParams.userId).toEqualTypeOf<
-            string | number
-          >()
+          expectTypeOf(request.urlParams.userId).toEqualTypeOf<string>()
           expectTypeOf(request.params.page).toEqualTypeOf<number>()
           expectTypeOf(request.params.limit).toEqualTypeOf<number>()
           return {
@@ -261,18 +261,16 @@ describe('Legacy Decorators Type Safety', () => {
     test('should enforce correct parameter type', () => {
       @Controller()
       class FileController {
+        // @ts-expect-error - legacy decorator is not typed
         @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.urlParams.fileId).toEqualTypeOf<string>()
           expectTypeOf(request.params.page).toEqualTypeOf<number>()
           expectTypeOf(request.params.limit).toEqualTypeOf<number>()
         }
@@ -281,17 +279,20 @@ describe('Legacy Decorators Type Safety', () => {
       expectTypeOf(FileController).toBeConstructibleWith()
     })
 
-    test('should require reply parameter', () => {
+    test('should work without reply parameter (Bun compatibility)', () => {
       @Controller()
       class FileController {
-        // @ts-expect-error - missing reply parameter
+        // @ts-expect-error - legacy decorator is not typed
         @Stream(downloadFileEndpoint)
         async downloadFile(
           request: StreamParams<typeof downloadFileEndpoint>,
         ): Promise<void> {
-          // Stream methods must have reply parameter
+          // Stream methods can work without reply parameter (for Bun)
+          expectTypeOf(request.urlParams.fileId).toEqualTypeOf<string>()
         }
       }
+
+      expectTypeOf(FileController).toBeConstructibleWith()
     })
   })
 
@@ -376,6 +377,109 @@ describe('Legacy Decorators Type Safety', () => {
     })
   })
 
+  describe('Injectable decorator', () => {
+    test('should work with services', () => {
+      @Injectable()
+      class UserService {
+        getUser(id: string) {
+          return { id, name: 'John' }
+        }
+      }
+
+      expectTypeOf(UserService).toBeConstructibleWith()
+    })
+
+    test('should work with controller dependencies', () => {
+      @Injectable()
+      class UserService {
+        getUser(id: string) {
+          return { id, name: 'John' }
+        }
+      }
+
+      @Controller()
+      class UserController {
+        constructor(private readonly userService: UserService) {}
+
+        @Endpoint(getUserEndpoint)
+        async getUser(
+          request: EndpointParams<typeof getUserEndpoint>,
+        ): EndpointResult<typeof getUserEndpoint> {
+          return this.userService.getUser(request.urlParams.userId.toString())
+        }
+      }
+
+      expectTypeOf(UserController).toBeConstructibleWith(
+        {} as InstanceType<typeof UserService>,
+      )
+    })
+  })
+
+  describe('AttributeFactory', () => {
+    test('should create simple attribute for controllers', () => {
+      const Public = AttributeFactory.createAttribute(Symbol.for('Public'))
+
+      // Note: In legacy decorators, decorators are applied bottom-to-top
+      // So @Controller() must be at the bottom to run first
+      @Public()
+      @Controller()
+      class PublicController {
+        @Endpoint(getUserEndpoint)
+        async getUser(
+          request: EndpointParams<typeof getUserEndpoint>,
+        ): EndpointResult<typeof getUserEndpoint> {
+          return { id: '1', name: 'John' }
+        }
+      }
+
+      expectTypeOf(PublicController).toBeConstructibleWith()
+      expectTypeOf(Public.token).toEqualTypeOf<symbol>()
+    })
+
+    test('should create attribute with schema for endpoints', () => {
+      const RateLimit = AttributeFactory.createAttribute(
+        Symbol.for('RateLimit'),
+        z.object({ requests: z.number(), window: z.number() }),
+      )
+
+      @Controller()
+      class RateLimitedController {
+        // Note: For method decorators, @Endpoint must be at the bottom
+        // @ts-expect-error - legacy decorator is not typed correctly
+        @RateLimit({ requests: 100, window: 60000 })
+        @Endpoint(getUserEndpoint)
+        async getUser(
+          request: EndpointParams<typeof getUserEndpoint>,
+        ): EndpointResult<typeof getUserEndpoint> {
+          return { id: '1', name: 'John' }
+        }
+      }
+
+      expectTypeOf(RateLimitedController).toBeConstructibleWith()
+      expectTypeOf(RateLimit.token).toEqualTypeOf<symbol>()
+      expectTypeOf(RateLimit.schema).toBeObject()
+    })
+
+    test('should create attribute for modules', () => {
+      const ApiVersion = AttributeFactory.createAttribute(
+        Symbol.for('ApiVersion'),
+        z.string(),
+      )
+
+      @Controller()
+      class VersionedController {}
+
+      // Note: In legacy decorators, @Module must be at the bottom
+      @ApiVersion('v2')
+      @Module({
+        controllers: [VersionedController],
+      })
+      class VersionedModule {}
+
+      expectTypeOf(VersionedModule).toBeConstructibleWith()
+    })
+  })
+
   describe('Integration test - full controller', () => {
     test('should work with all decorators together', () => {
       @Controller({

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

@@ -0,0 +1,365 @@
+import type { ClassType } from '@navios/di'
+import type { z, ZodType } from 'zod/v4'
+
+import type {
+  ControllerMetadata,
+  HandlerMetadata,
+  ModuleMetadata,
+} from '../metadata/index.mjs'
+
+import {
+  getControllerMetadata,
+  getEndpointMetadata,
+  getModuleMetadata,
+  hasControllerMetadata,
+  hasModuleMetadata,
+} from '../metadata/index.mjs'
+import {
+  getManagedMetadata,
+  hasManagedMetadata,
+} from '../metadata/navios-managed.metadata.mjs'
+import { createClassContext, createMethodContext } from './context-compat.mjs'
+
+/**
+ * Type for a legacy class 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
+  }
+
+/**
+ * Type for a legacy class 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
+  }
+
+/**
+ * Legacy-compatible factory for creating custom attribute decorators.
+ *
+ * Works with TypeScript experimental decorators (legacy API).
+ *
+ * Attributes allow you to add custom metadata to modules, controllers, and endpoints.
+ * This is useful for cross-cutting concerns like rate limiting, caching, API versioning, etc.
+ *
+ * @example
+ * ```typescript
+ * // Create a simple boolean attribute
+ * const Public = LegacyAttributeFactory.createAttribute(Symbol.for('Public'))
+ *
+ * // Use it as a decorator
+ * @Controller()
+ * @Public()
+ * export class PublicController { }
+ *
+ * // Check if attribute exists
+ * if (LegacyAttributeFactory.has(Public, controllerMetadata)) {
+ *   // Skip authentication
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Create an attribute with a validated value
+ * const RateLimit = LegacyAttributeFactory.createAttribute(
+ *   Symbol.for('RateLimit'),
+ *   z.object({ requests: z.number(), window: z.number() })
+ * )
+ *
+ * // Use it with a value
+ * @Endpoint(apiEndpoint)
+ * @RateLimit({ requests: 100, window: 60000 })
+ * async handler() { }
+ *
+ * // Get the value
+ * const limit = LegacyAttributeFactory.get(RateLimit, endpointMetadata)
+ * // limit is typed as { requests: number, window: number } | null
+ * ```
+ */
+export class LegacyAttributeFactory {
+  /**
+   * Creates a simple attribute decorator without a value.
+   *
+   * @param token - A unique symbol to identify this attribute
+   * @returns A decorator function that can be applied to classes or methods
+   *
+   * @example
+   * ```typescript
+   * const Public = LegacyAttributeFactory.createAttribute(Symbol.for('Public'))
+   *
+   * @Public()
+   * @Controller()
+   * export class PublicController { }
+   * ```
+   */
+  static createAttribute(token: symbol): LegacyClassAttribute
+  /**
+   * Creates an attribute decorator with a validated value.
+   *
+   * @param token - A unique symbol to identify this attribute
+   * @param schema - A Zod schema to validate the attribute value
+   * @returns A decorator function that accepts a value and can be applied to classes or methods
+   *
+   * @example
+   * ```typescript
+   * const RateLimit = LegacyAttributeFactory.createAttribute(
+   *   Symbol.for('RateLimit'),
+   *   z.object({ requests: z.number(), window: z.number() })
+   * )
+   *
+   * @RateLimit({ requests: 100, window: 60000 })
+   * @Endpoint(apiEndpoint)
+   * async handler() { }
+   * ```
+   */
+  static createAttribute<T extends ZodType>(
+    token: symbol,
+    schema: T,
+  ): LegacyClassSchemaAttribute<T>
+
+  static createAttribute(token: symbol, schema?: ZodType) {
+    const res = (value?: unknown) => {
+      // Return a decorator that can handle both class and method targets
+      function decorator(target: any): any
+      function decorator(
+        target: any,
+        propertyKey: string | symbol,
+        descriptor: PropertyDescriptor,
+      ): PropertyDescriptor
+      function decorator(
+        target: any,
+        propertyKey?: string | symbol,
+        descriptor?: PropertyDescriptor,
+      ): any {
+        const isMethodDecorator =
+          propertyKey !== undefined && descriptor !== undefined
+
+        if (isMethodDecorator) {
+          // Method decorator - apply to endpoint
+          const context = createMethodContext(target, propertyKey, descriptor)
+          const metadata = getEndpointMetadata(descriptor.value, context)
+
+          if (schema) {
+            const validatedValue = schema.safeParse(value)
+            if (!validatedValue.success) {
+              throw new Error(
+                `[Navios] Invalid value for attribute ${token.toString()}: ${validatedValue.error}`,
+              )
+            }
+            metadata.customAttributes.set(token, validatedValue.data)
+          } else {
+            metadata.customAttributes.set(token, true)
+          }
+          return descriptor
+        } else {
+          // Class decorator
+          const isController = hasControllerMetadata(target as ClassType)
+          const isModule = hasModuleMetadata(target as ClassType)
+          const isManaged = hasManagedMetadata(target as ClassType)
+
+          if (!isController && !isModule && !isManaged) {
+            throw new Error(
+              '[Navios] Attribute can only be applied to classes with @Controller, @Module, or other Navios-managed decorators',
+            )
+          }
+
+          const context = createClassContext(target)
+          const metadata = isController
+            ? getControllerMetadata(target, context)
+            : isModule
+              ? getModuleMetadata(target, context)
+              : isManaged
+                ? getManagedMetadata(target)!
+                : null
+
+          if (!metadata) {
+            throw new Error(
+              '[Navios] Could not determine metadata for attribute target',
+            )
+          }
+
+          if (schema) {
+            const validatedValue = schema.safeParse(value)
+            if (!validatedValue.success) {
+              throw new Error(
+                `[Navios] Invalid value for attribute ${token.toString()}: ${validatedValue.error}`,
+              )
+            }
+            metadata.customAttributes.set(token, validatedValue.data)
+          } else {
+            metadata.customAttributes.set(token, true)
+          }
+          return target
+        }
+      }
+      return decorator
+    }
+    res.token = token
+    if (schema) {
+      res.schema = schema
+    }
+    return res
+  }
+
+  /**
+   * Gets the value of an attribute from metadata.
+   *
+   * Returns `null` if the attribute is not present.
+   * For simple attributes (without values), returns `true` if present.
+   *
+   * @param attribute - The attribute decorator
+   * @param target - The metadata object (module, controller, or handler)
+   * @returns The attribute value, `true` for simple attributes, or `null` if not found
+   *
+   * @example
+   * ```typescript
+   * const isPublic = LegacyAttributeFactory.get(Public, controllerMetadata)
+   * // isPublic is true | null
+   *
+   * const rateLimit = LegacyAttributeFactory.get(RateLimit, endpointMetadata)
+   * // rateLimit is { requests: number, window: number } | null
+   * ```
+   */
+  static get(
+    attribute: LegacyClassAttribute,
+    target: ModuleMetadata | ControllerMetadata | HandlerMetadata<any>,
+  ): true | null
+  static get<T extends ZodType>(
+    attribute: LegacyClassSchemaAttribute<T>,
+    target: ModuleMetadata | ControllerMetadata | HandlerMetadata<any>,
+  ): z.output<T> | null
+  static get(
+    attribute: LegacyClassAttribute | LegacyClassSchemaAttribute<any>,
+    target: ModuleMetadata | ControllerMetadata | HandlerMetadata<any>,
+  ) {
+    return target.customAttributes.get(attribute.token) ?? null
+  }
+
+  /**
+   * Gets all values of an attribute from metadata (useful when an attribute can appear multiple times).
+   *
+   * Returns `null` if the attribute is not present.
+   *
+   * @param attribute - The attribute decorator
+   * @param target - The metadata object (module, controller, or handler)
+   * @returns An array of attribute values, or `null` if not found
+   *
+   * @example
+   * ```typescript
+   * const tags = LegacyAttributeFactory.getAll(Tag, endpointMetadata)
+   * // tags is string[] | null
+   * ```
+   */
+  static getAll(
+    attribute: LegacyClassAttribute,
+    target: ModuleMetadata | ControllerMetadata | HandlerMetadata<any>,
+  ): Array<true> | null
+  static getAll<T extends ZodType>(
+    attribute: LegacyClassSchemaAttribute<T>,
+    target: ModuleMetadata | ControllerMetadata | HandlerMetadata<any>,
+  ): Array<z.output<T>> | null
+  static getAll(
+    attribute: LegacyClassAttribute | LegacyClassSchemaAttribute<any>,
+    target: ModuleMetadata | ControllerMetadata | HandlerMetadata<any>,
+  ) {
+    const values = Array.from(target.customAttributes.entries())
+      .filter(([key]) => key === attribute.token)
+      .map(([, value]) => value)
+    return values.length > 0 ? values : null
+  }
+
+  /**
+   * Gets the last value of an attribute from an array of metadata objects.
+   *
+   * Searches from the end of the array backwards, useful for finding the most
+   * specific attribute value (e.g., endpoint-level overrides module-level).
+   *
+   * @param attribute - The attribute decorator
+   * @param target - An array of metadata objects (typically [module, controller, handler])
+   * @returns The last attribute value found, or `null` if not found
+   *
+   * @example
+   * ```typescript
+   * // Check attribute hierarchy: endpoint -> controller -> module
+   * const rateLimit = LegacyAttributeFactory.getLast(RateLimit, [
+   *   moduleMetadata,
+   *   controllerMetadata,
+   *   endpointMetadata
+   * ])
+   * ```
+   */
+  static getLast(
+    attribute: LegacyClassAttribute,
+    target: (ModuleMetadata | ControllerMetadata | HandlerMetadata<any>)[],
+  ): true | null
+  static getLast<T extends ZodType>(
+    attribute: LegacyClassSchemaAttribute<T>,
+    target: (ModuleMetadata | ControllerMetadata | HandlerMetadata<any>)[],
+  ): z.output<T> | null
+  static getLast(
+    attribute: LegacyClassAttribute | LegacyClassSchemaAttribute<any>,
+    target: (ModuleMetadata | ControllerMetadata | HandlerMetadata<any>)[],
+  ) {
+    for (let i = target.length - 1; i >= 0; i--) {
+      const value = target[i].customAttributes.get(attribute.token)
+      if (value) {
+        return value
+      }
+    }
+    return null
+  }
+
+  /**
+   * Checks if an attribute is present on the metadata object.
+   *
+   * @param attribute - The attribute decorator
+   * @param target - The metadata object (module, controller, or handler)
+   * @returns `true` if the attribute is present, `false` otherwise
+   *
+   * @example
+   * ```typescript
+   * if (LegacyAttributeFactory.has(Public, controllerMetadata)) {
+   *   // Skip authentication
+   * }
+   * ```
+   */
+  static has(
+    attribute: LegacyClassAttribute,
+    target: ModuleMetadata | ControllerMetadata | HandlerMetadata<any>,
+  ): boolean
+  static has<T extends ZodType>(
+    attribute: LegacyClassSchemaAttribute<T>,
+    target: ModuleMetadata | ControllerMetadata | HandlerMetadata<any>,
+  ): boolean
+  static has(
+    attribute: LegacyClassAttribute | LegacyClassSchemaAttribute<any>,
+    target: ModuleMetadata | ControllerMetadata | HandlerMetadata<any>,
+  ) {
+    return target.customAttributes.has(attribute.token)
+  }
+}
+
+// Re-export as AttributeFactory for convenience
+export { LegacyAttributeFactory as AttributeFactory }

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

@@ -30,6 +30,7 @@ function getConstructor(prototype: any): ClassType | null {
 
 /**
  * Creates a mock ClassDecoratorContext for legacy class decorators.
+ * @internal
  */
 export function createClassContext(target: ClassType): ClassDecoratorContext {
   // Get or create metadata storage for this class
@@ -53,6 +54,7 @@ export function createClassContext(target: ClassType): ClassDecoratorContext {
  *
  * Note: Method decorators need to share metadata with the class context
  * because endpoint metadata is stored at the class level.
+ * @internal
  */
 export function createMethodContext(
   target: any,

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

@@ -6,4 +6,5 @@ export * from './header.decorator.mjs'
 export * from './http-code.decorator.mjs'
 export * from './multipart.decorator.mjs'
 export * from './stream.decorator.mjs'
+export * from './injectable.decorator.mjs'
 

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

@@ -0,0 +1,41 @@
+import type { ClassType } from '@navios/di'
+
+import {
+  Injectable as OriginalInjectable,
+  type InjectableOptions,
+} from '@navios/di'
+
+import { createClassContext } from '../context-compat.mjs'
+
+export type { InjectableOptions }
+
+/**
+ * Legacy-compatible Injectable decorator.
+ *
+ * Works with TypeScript experimental decorators (legacy API).
+ *
+ * @param options - Injectable configuration options
+ * @returns A class decorator compatible with legacy decorator API
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * export class UserService {
+ *   getUser(id: string) {
+ *     return { id, name: 'John' }
+ *   }
+ * }
+ * ```
+ */
+export function Injectable(options: InjectableOptions = {}) {
+  return function (target: ClassType) {
+    const context = createClassContext(target)
+    // Use the no-args overload when options is empty, otherwise pass options
+    const originalDecorator =
+      Object.keys(options).length === 0
+        ? OriginalInjectable()
+        : // @ts-expect-error - InjectableOptions is a union type, we let runtime handle it
+          OriginalInjectable(options)
+    return originalDecorator(target, context)
+  }
+}

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

@@ -22,11 +22,11 @@ type MultipartMethodDescriptor<
   (
     params: QuerySchema extends ZodObject
       ? RequestSchema extends ZodType
-        ? EndpointFunctionArgs<Url, QuerySchema, RequestSchema>
-        : EndpointFunctionArgs<Url, QuerySchema, undefined>
+        ? EndpointFunctionArgs<Url, QuerySchema, RequestSchema, true>
+        : EndpointFunctionArgs<Url, QuerySchema, undefined, true>
       : RequestSchema extends ZodType
-        ? EndpointFunctionArgs<Url, undefined, RequestSchema>
-        : EndpointFunctionArgs<Url, undefined, undefined>,
+        ? EndpointFunctionArgs<Url, undefined, RequestSchema, true>
+        : EndpointFunctionArgs<Url, undefined, undefined, true>,
   ) => Promise<z.input<ResponseSchema>>
 >
 

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

@@ -8,27 +8,34 @@ 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.
- * Note: In legacy decorators, type constraints are checked when the decorator is applied,
- * but may not be preserved perfectly when decorators are stacked.
+ * Supports both with and without reply parameter (Bun doesn't use reply parameter).
  */
 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>
->
+> =
+  | TypedPropertyDescriptor<
+      (params: StreamParams<Url, QuerySchema, RequestSchema>, reply: any) => any
+    >
+  | TypedPropertyDescriptor<
+      (params: StreamParams<Url, QuerySchema, RequestSchema>) => any
+    >
+  | TypedPropertyDescriptor<() => any>
 
 /**
  * Legacy-compatible Stream decorator.