@navios/core 0.7.1 → 0.8.0

package/src/__tests__/controller-resolver.spec.mts

@@ -0,0 +1,223 @@
+import {
+  Container,
+  getInjectableToken,
+  inject,
+  Injectable,
+  InjectableScope,
+} from '@navios/di'
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+
+import { InstanceResolverService } from '../services/instance-resolver.service.mjs'
+
+function createTestSetup() {
+  const container = new Container()
+
+  return { container }
+}
+
+describe('InstanceResolverService', () => {
+  let container: Container
+
+  beforeEach(() => {
+    const setup = createTestSetup()
+    container = setup.container
+  })
+
+  afterEach(async () => {
+    await container.dispose()
+  })
+
+  describe('resolve', () => {
+    it('should cache singleton controller without request-scoped dependencies', async () => {
+      @Injectable()
+      class SimpleService {
+        value = 'simple'
+      }
+
+      @Injectable()
+      class SingletonController {
+        private service = inject(SimpleService)
+
+        getValue() {
+          return this.service.value
+        }
+      }
+
+      const resolver = await container.get(InstanceResolverService)
+      const resolution = await resolver.resolve(SingletonController)
+
+      expect(resolution.cached).toBe(true)
+      expect(resolution.instance).toBeInstanceOf(SingletonController)
+      expect((resolution.instance as SingletonController).getValue()).toBe(
+        'simple',
+      )
+    })
+
+    it('should not cache controller with request-scoped dependencies', async () => {
+      @Injectable({ scope: InjectableScope.Request })
+      class RequestScopedService {
+        id = Math.random().toString(36).substring(7)
+      }
+
+      @Injectable()
+      class ControllerWithRequestDep {
+        private service = inject(RequestScopedService)
+
+        getServiceId() {
+          return this.service.id
+        }
+      }
+
+      const resolver = await container.get(InstanceResolverService)
+      const resolution = await resolver.resolve(ControllerWithRequestDep)
+
+      expect(resolution.cached).toBe(false)
+      expect(resolution.instance).toBeNull()
+      expect(typeof resolution.resolve).toBe('function')
+    })
+
+    it('should update controller scope to Request when it has request-scoped dependencies', async () => {
+      @Injectable({ scope: InjectableScope.Request })
+      class RequestScopedService {
+        id = Math.random().toString(36).substring(7)
+      }
+
+      @Injectable()
+      class ControllerWithRequestDep {
+        private service = inject(RequestScopedService)
+
+        getServiceId() {
+          return this.service.id
+        }
+      }
+
+      const resolver = await container.get(InstanceResolverService)
+      await resolver.resolve(ControllerWithRequestDep)
+
+      // Check that the controller's scope was updated
+      const token = container
+        .getRegistry()
+        .get(getInjectableToken(ControllerWithRequestDep))
+      expect(token.scope).toBe(InjectableScope.Request)
+    })
+
+    it('should resolve different instances per request when controller has request-scoped deps', async () => {
+      let serviceInstanceCount = 0
+
+      @Injectable({ scope: InjectableScope.Request })
+      class RequestScopedService {
+        id = ++serviceInstanceCount
+      }
+
+      @Injectable()
+      class ControllerWithRequestDep {
+        private service = inject(RequestScopedService)
+
+        getServiceId() {
+          return this.service.id
+        }
+      }
+
+      const resolver = await container.get(InstanceResolverService)
+      const resolution = await resolver.resolve(ControllerWithRequestDep)
+
+      expect(resolution.cached).toBe(false)
+
+      // Request 1
+      const scoped1 = container.beginRequest('request-1')
+      const controller1 = await resolution.resolve(scoped1)
+      const id1 = (controller1 as ControllerWithRequestDep).getServiceId()
+
+      // Request 2
+      const scoped2 = container.beginRequest('request-2')
+      const controller2 = await resolution.resolve(scoped2)
+      const id2 = (controller2 as ControllerWithRequestDep).getServiceId()
+
+      expect(id1).toBe(1)
+      expect(id2).toBe(2)
+      expect(controller1).not.toBe(controller2)
+
+      await scoped1.endRequest()
+      await scoped2.endRequest()
+    })
+
+    it('should handle parallel requests with isolated instances', async () => {
+      let serviceInstanceCount = 0
+
+      @Injectable({ scope: InjectableScope.Request })
+      class RequestTrackerService {
+        id = ++serviceInstanceCount
+        data: Record<string, any> = {}
+
+        addData(key: string, value: any) {
+          this.data[key] = value
+        }
+
+        getData(key: string) {
+          return this.data[key]
+        }
+      }
+
+      @Injectable()
+      class ControllerWithTracker {
+        private tracker = inject(RequestTrackerService)
+
+        async handleRequest(data: string) {
+          this.tracker.addData('input', data)
+          // Simulate async work
+          await new Promise((resolve) => setTimeout(resolve, 5))
+          return {
+            id: this.tracker.id,
+            data: this.tracker.getData('input'),
+          }
+        }
+      }
+
+      const resolver = await container.get(InstanceResolverService)
+      const resolution = await resolver.resolve(ControllerWithTracker)
+
+      expect(resolution.cached).toBe(false)
+
+      // Create 5 parallel requests
+      const requests = ['req1', 'req2', 'req3', 'req4', 'req5'].map(
+        async (data, i) => {
+          const scoped = container.beginRequest(`request-${i}`)
+          const controller = (await resolution.resolve(
+            scoped,
+          )) as ControllerWithTracker
+          const result = await controller.handleRequest(data)
+          await scoped.endRequest()
+          return result
+        },
+      )
+
+      const results = await Promise.all(requests)
+
+      // Verify each request got its own unique ID
+      const ids = results.map((r) => r.id)
+      const uniqueIds = new Set(ids)
+      expect(uniqueIds.size).toBe(5)
+
+      // Verify each request returned its own data
+      const expectedData = ['req1', 'req2', 'req3', 'req4', 'req5']
+      const actualData = results.map((r) => r.data)
+      expect(actualData).toEqual(expect.arrayContaining(expectedData))
+    })
+
+    it('should return same cached instance for singleton controllers', async () => {
+      @Injectable()
+      class SingletonController {
+        id = Math.random()
+      }
+
+      const resolver = await container.get(InstanceResolverService)
+      const resolution1 = await resolver.resolve(SingletonController)
+      const resolution2 = await resolver.resolve(SingletonController)
+
+      expect(resolution1.cached).toBe(true)
+      expect(resolution2.cached).toBe(true)
+      expect(resolution1.instance).toBe(resolution2.instance)
+    })
+  })
+})

package/src/__tests__/controller.spec.mts

@@ -36,7 +36,7 @@ describe('Controller decorator', () => {
     @Controller()
     class Test {
       @Endpoint(endpoint)
-      async getBar(params: EndpointParams<typeof endpoint>) {
+      async getBar() {
         return {
           foo: 'bar',
         }

package/src/decorators/controller.decorator.mts

@@ -1,6 +1,6 @@
 import type { ClassType } from '@navios/di'
 
-import { Injectable, InjectableScope, InjectionToken } from '@navios/di'
+import { Injectable, InjectionToken, Registry } from '@navios/di'
 
 import { getControllerMetadata } from '../metadata/index.mjs'
 
@@ -13,17 +13,22 @@ export interface ControllerOptions {
    * Guards are executed in reverse order (last guard first).
    */
   guards?: ClassType[] | Set<ClassType>
+  /**
+   * Registry to use for the controller.
+   * Registry is used to store the controller and its endpoints.
+   */
+  registry?: Registry
 }
 
 /**
  * Decorator that marks a class as a Navios controller.
- * 
+ *
  * Controllers handle HTTP requests and define endpoints.
  * They are request-scoped by default, meaning a new instance is created for each request.
- * 
+ *
  * @param options - Controller configuration options
  * @returns A class decorator
- * 
+ *
  * @example
  * ```typescript
  * @Controller({ guards: [AuthGuard] })
@@ -35,7 +40,7 @@ export interface ControllerOptions {
  * }
  * ```
  */
-export function Controller({ guards }: ControllerOptions = {}) {
+export function Controller({ guards, registry }: ControllerOptions = {}) {
   return function (target: ClassType, context: ClassDecoratorContext) {
     if (context.kind !== 'class') {
       throw new Error(
@@ -53,7 +58,7 @@ export function Controller({ guards }: ControllerOptions = {}) {
     }
     return Injectable({
       token,
-      scope: InjectableScope.Request,
+      registry,
     })(target, context)
   }
 }

package/src/decorators/endpoint.decorator.mts

@@ -126,6 +126,51 @@ export type EndpointResult<
  * }
  * ```
  */
+export function Endpoint<
+  Method extends HttpMethod = HttpMethod,
+  Url extends string = string,
+  QuerySchema = undefined,
+  ResponseSchema extends ZodType = ZodType,
+  RequestSchema = ZodType,
+  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>,
+>(endpoint: {
+  config: BaseEndpointConfig<
+    Method,
+    Url,
+    QuerySchema,
+    ResponseSchema,
+    RequestSchema
+  >
+}): (
+  target: (
+    params: Params,
+  ) => Promise<z.input<ResponseSchema>> | z.input<ResponseSchema>,
+  context: ClassMethodDecoratorContext,
+) => void
+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
+  >
+}): (
+  target: () => Promise<z.input<ResponseSchema>> | z.input<ResponseSchema>,
+  context: ClassMethodDecoratorContext,
+) => void
 export function Endpoint<
   Method extends HttpMethod = HttpMethod,
   Url extends string = string,
@@ -141,18 +186,21 @@ export function Endpoint<
     RequestSchema
   >
 }) {
-  return (
-    target: (
-      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>>,
-    context: ClassMethodDecoratorContext,
-  ) => {
+  type 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>
+
+  type Handler =
+    | ((
+        params: Params,
+      ) => Promise<z.input<ResponseSchema>> | z.input<ResponseSchema>)
+    | (() => Promise<z.input<ResponseSchema>> | z.input<ResponseSchema>)
+
+  return (target: Handler, context: ClassMethodDecoratorContext) => {
     if (context.kind !== 'method') {
       throw new Error(
         '[Navios] Endpoint decorator can only be used on methods.',

package/src/decorators/multipart.decorator.mts

@@ -13,9 +13,9 @@ import { MultipartAdapterToken } from '../tokens/index.mjs'
 
 /**
  * Extracts the typed parameters for a multipart endpoint handler function.
- * 
+ *
  * Similar to `EndpointParams`, but specifically for multipart/form-data endpoints.
- * 
+ *
  * @typeParam EndpointDeclaration - The endpoint declaration from @navios/builder
  */
 export type MultipartParams<
@@ -48,7 +48,7 @@ export type MultipartParams<
 
 /**
  * Extracts the typed return value for a multipart endpoint handler function.
- * 
+ *
  * @typeParam EndpointDeclaration - The endpoint declaration from @navios/builder
  */
 export type MultipartResult<
@@ -64,13 +64,13 @@ export type MultipartResult<
 
 /**
  * Decorator that marks a method as a multipart/form-data endpoint.
- * 
+ *
  * Use this decorator for endpoints that handle file uploads or form data.
  * The endpoint must be defined using @navios/builder's `declareMultipart` method.
- * 
+ *
  * @param endpoint - The multipart endpoint declaration from @navios/builder
  * @returns A method decorator
- * 
+ *
  * @example
  * ```typescript
  * const uploadFileEndpoint = api.declareMultipart({
@@ -79,7 +79,7 @@ export type MultipartResult<
  *   requestSchema: z.object({ file: z.instanceof(File) }),
  *   responseSchema: z.object({ url: z.string() }),
  * })
- * 
+ *
  * @Controller()
  * export class FileController {
  *   @Multipart(uploadFileEndpoint)
@@ -91,6 +91,51 @@ export type MultipartResult<
  * }
  * ```
  */
+export function Multipart<
+  Method extends HttpMethod = HttpMethod,
+  Url extends string = string,
+  QuerySchema = undefined,
+  ResponseSchema extends ZodType = ZodType,
+  RequestSchema = ZodType,
+  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>,
+>(endpoint: {
+  config: BaseEndpointConfig<
+    Method,
+    Url,
+    QuerySchema,
+    ResponseSchema,
+    RequestSchema
+  >
+}): (
+  target: (
+    params: Params,
+  ) => Promise<z.input<ResponseSchema>> | z.input<ResponseSchema>,
+  context: ClassMethodDecoratorContext,
+) => void
+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
+  >
+}): (
+  target: () => Promise<z.input<ResponseSchema>> | z.input<ResponseSchema>,
+  context: ClassMethodDecoratorContext,
+) => void
 export function Multipart<
   Method extends HttpMethod = HttpMethod,
   Url extends string = string,
@@ -106,23 +151,21 @@ export function Multipart<
     RequestSchema
   >
 }) {
-  return (
-    target: (
-      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>>,
-    context: ClassMethodDecoratorContext,
-  ) => {
-    if (typeof target !== 'function') {
-      throw new Error(
-        '[Navios] Endpoint decorator can only be used on functions.',
-      )
-    }
+  type 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>
+
+  type Handler =
+    | ((
+        params: Params,
+      ) => Promise<z.input<ResponseSchema>> | z.input<ResponseSchema>)
+    | (() => Promise<z.input<ResponseSchema>> | z.input<ResponseSchema>)
+
+  return (target: Handler, context: ClassMethodDecoratorContext) => {
     if (context.kind !== 'method') {
       throw new Error(
         '[Navios] Endpoint decorator can only be used on methods.',

package/src/decorators/stream.decorator.mts

@@ -11,9 +11,9 @@ import { StreamAdapterToken } from '../tokens/index.mjs'
 
 /**
  * Extracts the typed parameters for a stream endpoint handler function.
- * 
+ *
  * Similar to `EndpointParams`, but specifically for streaming endpoints.
- * 
+ *
  * @typeParam EndpointDeclaration - The stream endpoint declaration from @navios/builder
  */
 export type StreamParams<
@@ -46,20 +46,20 @@ export type StreamParams<
 
 /**
  * Decorator that marks a method as a streaming endpoint.
- * 
+ *
  * Use this decorator for endpoints that stream data (e.g., file downloads, SSE).
  * The endpoint must be defined using @navios/builder's `declareStream` method.
- * 
+ *
  * @param endpoint - The stream endpoint declaration from @navios/builder
  * @returns A method decorator
- * 
+ *
  * @example
  * ```typescript
  * const downloadFileEndpoint = api.declareStream({
  *   method: 'get',
  *   url: '/files/$fileId',
  * })
- * 
+ *
  * @Controller()
  * export class FileController {
  *   @Stream(downloadFileEndpoint)
@@ -70,6 +70,51 @@ export type StreamParams<
  * }
  * ```
  */
+export function Stream<
+  Method extends HttpMethod = HttpMethod,
+  Url extends string = string,
+  QuerySchema = undefined,
+  RequestSchema = ZodType,
+  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>,
+>(endpoint: {
+  config: BaseStreamConfig<Method, Url, QuerySchema, RequestSchema>
+}): (
+  target: (params: Params, reply: any) => any,
+  context: ClassMethodDecoratorContext,
+) => void
+// Bun doesn't support reply parameter
+export function Stream<
+  Method extends HttpMethod = HttpMethod,
+  Url extends string = string,
+  QuerySchema = undefined,
+  RequestSchema = ZodType,
+  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>,
+>(endpoint: {
+  config: BaseStreamConfig<Method, Url, QuerySchema, RequestSchema>
+}): (
+  target: (params: Params) => any,
+  context: ClassMethodDecoratorContext,
+) => void
+export function Stream<
+  Method extends HttpMethod = HttpMethod,
+  Url extends string = string,
+  QuerySchema = undefined,
+  RequestSchema = ZodType,
+>(endpoint: {
+  config: BaseStreamConfig<Method, Url, QuerySchema, RequestSchema>
+}): (target: () => any, context: ClassMethodDecoratorContext) => void
 export function Stream<
   Method extends HttpMethod = HttpMethod,
   Url extends string = string,
@@ -78,24 +123,20 @@ export function Stream<
 >(endpoint: {
   config: BaseStreamConfig<Method, Url, QuerySchema, RequestSchema>
 }) {
-  return (
-    target: (
-      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>,
-    context: ClassMethodDecoratorContext,
-  ) => {
-    if (typeof target !== 'function') {
-      throw new Error(
-        '[Navios] Endpoint decorator can only be used on functions.',
-      )
-    }
+  type 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>
+
+  type Handler =
+    | ((params: Params, reply: any) => any)
+    | ((params: Params) => any)
+    | (() => any)
+
+  return (target: Handler, context: ClassMethodDecoratorContext) => {
     if (context.kind !== 'method') {
       throw new Error(
         '[Navios] Endpoint decorator can only be used on methods.',

package/src/interfaces/abstract-http-handler-adapter.interface.mts

@@ -2,6 +2,36 @@ import type { ClassType, ScopedContainer } from '@navios/di'
 
 import type { HandlerMetadata } from '../metadata/index.mjs'
 
+/**
+ * Static handler result - handler can be called without a scoped container.
+ * Used when the controller and all its dependencies are singletons.
+ */
+export type StaticHandler<TRequest = any, TReply = any> = {
+  isStatic: true
+  handler: (request: TRequest, reply: TReply) => Promise<any>
+}
+
+/**
+ * Dynamic handler result - handler requires a scoped container for resolution.
+ * Used when the controller or its dependencies need per-request resolution.
+ */
+export type DynamicHandler<TRequest = any, TReply = any> = {
+  isStatic: false
+  handler: (
+    scoped: ScopedContainer,
+    request: TRequest,
+    reply: TReply,
+  ) => Promise<any>
+}
+
+/**
+ * Handler result returned by provideHandler.
+ * Can be either static (pre-resolved) or dynamic (needs scoped container).
+ */
+export type HandlerResult<TRequest = any, TReply = any> =
+  | StaticHandler<TRequest, TReply>
+  | DynamicHandler<TRequest, TReply>
+
 export interface AbstractHttpHandlerAdapterInterface {
   prepareArguments?: (
     handlerMetadata: HandlerMetadata<any>,
@@ -9,5 +39,5 @@ export interface AbstractHttpHandlerAdapterInterface {
   provideHandler: (
     controller: ClassType,
     handlerMetadata: HandlerMetadata<any>,
-  ) => (context: ScopedContainer, request: any, reply: any) => Promise<any>
+  ) => Promise<HandlerResult>
 }

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

@@ -92,7 +92,7 @@ export function 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
+      typedDescriptor.value = result as any
     }
     return typedDescriptor
   }