@navios/core 1.0.0-alpha.2 → 1.0.0-alpha.3

package/src/__tests__/guard-runner.service.spec.mts

@@ -0,0 +1,399 @@
+import type { ScopedContainer } from '@navios/di'
+
+import { Container, Injectable, InjectionToken } from '@navios/di'
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import type {
+  AbstractExecutionContext,
+  CanActivate,
+} from '../interfaces/index.mjs'
+import type {
+  ControllerMetadata,
+  HandlerMetadata,
+  ModuleMetadata,
+} from '../metadata/index.mjs'
+
+import { HttpException } from '../exceptions/index.mjs'
+import { LoggerOutput } from '../logger/logger.tokens.mjs'
+import {
+  ForbiddenResponderToken,
+  InternalServerErrorResponderToken,
+  NotFoundResponderToken,
+  ValidationErrorResponderToken,
+} from '../responders/tokens/responder.tokens.mjs'
+import { GuardRunnerService } from '../services/guard-runner.service.mjs'
+
+// Mock responders
+const createMockResponder = (statusCode: number, message: string) => ({
+  getResponse: vi.fn().mockReturnValue({
+    statusCode,
+    payload: { message },
+    headers: { 'content-type': 'application/problem+json' },
+  }),
+})
+
+// Mock logger output
+const mockLoggerOutput = {
+  log: vi.fn(),
+  error: vi.fn(),
+  warn: vi.fn(),
+  debug: vi.fn(),
+  verbose: vi.fn(),
+  fatal: vi.fn(),
+}
+
+// Mock execution context
+const createMockExecutionContext = (): AbstractExecutionContext => {
+  const mockReply = {
+    status: vi.fn().mockReturnThis(),
+    send: vi.fn().mockReturnThis(),
+  }
+  return {
+    getRequest: vi.fn().mockReturnValue({}),
+    getReply: vi.fn().mockReturnValue(mockReply),
+    getHandler: vi.fn(),
+    getModule: vi.fn(),
+    getController: vi.fn(),
+  }
+}
+
+// Mock guard
+const createMockGuard = (
+  canActivateResult: boolean | Promise<boolean>,
+): CanActivate => ({
+  canActivate: vi.fn().mockImplementation(() => canActivateResult),
+})
+
+describe('GuardRunnerService', () => {
+  let container: Container
+  let mockForbiddenResponder: ReturnType<typeof createMockResponder>
+  let mockInternalErrorResponder: ReturnType<typeof createMockResponder>
+  let mockNotFoundResponder: ReturnType<typeof createMockResponder>
+  let mockValidationErrorResponder: ReturnType<typeof createMockResponder>
+
+  beforeEach(() => {
+    container = new Container()
+    vi.clearAllMocks()
+
+    // Create mock responders
+    mockForbiddenResponder = createMockResponder(403, 'Forbidden')
+    mockInternalErrorResponder = createMockResponder(
+      500,
+      'Internal Server Error',
+    )
+    mockNotFoundResponder = createMockResponder(404, 'Not Found')
+    mockValidationErrorResponder = createMockResponder(400, 'Validation Error')
+
+    // Register all required dependencies
+    container.addInstance(ForbiddenResponderToken, mockForbiddenResponder)
+    container.addInstance(
+      InternalServerErrorResponderToken,
+      mockInternalErrorResponder,
+    )
+    container.addInstance(NotFoundResponderToken, mockNotFoundResponder)
+    container.addInstance(
+      ValidationErrorResponderToken,
+      mockValidationErrorResponder,
+    )
+    container.addInstance(LoggerOutput, mockLoggerOutput)
+  })
+
+  afterEach(async () => {
+    await container.dispose()
+  })
+
+  describe('runGuardsStatic', () => {
+    it('should return true when all guards pass', async () => {
+      const service = await container.get(GuardRunnerService)
+      const guards = [createMockGuard(true), createMockGuard(true)]
+      const context = createMockExecutionContext()
+
+      const result = await service.runGuardsStatic(guards, context)
+
+      expect(result).toBe(true)
+      expect(guards[0].canActivate).toHaveBeenCalledWith(context)
+      expect(guards[1].canActivate).toHaveBeenCalledWith(context)
+    })
+
+    it('should return false when a guard returns false', async () => {
+      const service = await container.get(GuardRunnerService)
+      const guards = [createMockGuard(true), createMockGuard(false)]
+      const context = createMockExecutionContext()
+
+      const result = await service.runGuardsStatic(guards, context)
+
+      expect(result).toBe(false)
+      expect(context.getReply().status).toHaveBeenCalledWith(403)
+    })
+
+    it('should stop execution when a guard fails', async () => {
+      const service = await container.get(GuardRunnerService)
+      const firstGuard = createMockGuard(false)
+      const secondGuard = createMockGuard(true)
+      const guards = [firstGuard, secondGuard]
+      const context = createMockExecutionContext()
+
+      await service.runGuardsStatic(guards, context)
+
+      expect(firstGuard.canActivate).toHaveBeenCalled()
+      expect(secondGuard.canActivate).not.toHaveBeenCalled()
+    })
+
+    it('should handle HttpException from guard', async () => {
+      const service = await container.get(GuardRunnerService)
+      const httpException = new HttpException(401, 'Unauthorized')
+      const guard = {
+        canActivate: vi.fn().mockRejectedValue(httpException),
+      }
+      const context = createMockExecutionContext()
+
+      const result = await service.runGuardsStatic([guard], context)
+
+      expect(result).toBe(false)
+      expect(context.getReply().status).toHaveBeenCalledWith(401)
+      expect(context.getReply().send).toHaveBeenCalledWith('Unauthorized')
+    })
+
+    it('should handle unknown errors from guard', async () => {
+      const service = await container.get(GuardRunnerService)
+      const guard = {
+        canActivate: vi.fn().mockRejectedValue(new Error('Unknown error')),
+      }
+      const context = createMockExecutionContext()
+
+      const result = await service.runGuardsStatic([guard], context)
+
+      expect(result).toBe(false)
+      expect(mockLoggerOutput.error).toHaveBeenCalled()
+      expect(context.getReply().status).toHaveBeenCalledWith(500)
+    })
+
+    it('should handle async guards', async () => {
+      const service = await container.get(GuardRunnerService)
+      const asyncGuard = createMockGuard(Promise.resolve(true))
+      const context = createMockExecutionContext()
+
+      const result = await service.runGuardsStatic([asyncGuard], context)
+
+      expect(result).toBe(true)
+    })
+
+    it('should work with empty guard array', async () => {
+      const service = await container.get(GuardRunnerService)
+      const context = createMockExecutionContext()
+
+      const result = await service.runGuardsStatic([], context)
+
+      expect(result).toBe(true)
+    })
+  })
+
+  describe('runGuards', () => {
+    it('should resolve guards from scoped container', async () => {
+      @Injectable()
+      class TestGuard implements CanActivate {
+        canActivate = vi.fn().mockReturnValue(true)
+      }
+
+      const service = await container.get(GuardRunnerService)
+      const testGuardInstance = new TestGuard()
+
+      const mockScopedContainer = {
+        get: vi.fn().mockResolvedValue(testGuardInstance),
+      } as unknown as ScopedContainer
+
+      const guards = new Set([TestGuard])
+      const context = createMockExecutionContext()
+
+      const result = await service.runGuards(
+        guards,
+        context,
+        mockScopedContainer,
+      )
+
+      expect(result).toBe(true)
+      expect(mockScopedContainer.get).toHaveBeenCalled()
+      expect(testGuardInstance.canActivate).toHaveBeenCalledWith(context)
+    })
+
+    it('should throw error for guard without canActivate', async () => {
+      @Injectable()
+      class InvalidGuard {
+        // Missing canActivate
+      }
+
+      const service = await container.get(GuardRunnerService)
+      const mockScopedContainer = {
+        get: vi.fn().mockResolvedValue(new InvalidGuard()),
+      } as unknown as ScopedContainer
+
+      const guards = new Set([InvalidGuard as any])
+      const context = createMockExecutionContext()
+
+      await expect(
+        service.runGuards(guards, context, mockScopedContainer),
+      ).rejects.toThrow('does not implement canActivate')
+    })
+
+    it('should reverse guard order (module -> controller -> endpoint)', async () => {
+      const callOrder: string[] = []
+
+      @Injectable()
+      class Guard1 implements CanActivate {
+        canActivate() {
+          callOrder.push('guard1')
+          return true
+        }
+      }
+
+      @Injectable()
+      class Guard2 implements CanActivate {
+        canActivate() {
+          callOrder.push('guard2')
+          return true
+        }
+      }
+
+      @Injectable()
+      class Guard3 implements CanActivate {
+        canActivate() {
+          callOrder.push('guard3')
+          return true
+        }
+      }
+
+      const service = await container.get(GuardRunnerService)
+
+      const mockScopedContainer = {
+        get: vi.fn().mockImplementation((token) => {
+          if (token === Guard1) return new Guard1()
+          if (token === Guard2) return new Guard2()
+          if (token === Guard3) return new Guard3()
+        }),
+      } as unknown as ScopedContainer
+
+      // Order in Set: Guard1, Guard2, Guard3
+      // Should execute in reverse: Guard3, Guard2, Guard1
+      const guards = new Set([Guard1, Guard2, Guard3])
+      const context = createMockExecutionContext()
+
+      await service.runGuards(guards, context, mockScopedContainer)
+
+      expect(callOrder).toEqual(['guard3', 'guard2', 'guard1'])
+    })
+  })
+
+  describe('makeContext', () => {
+    it('should merge guards from module, controller, and endpoint', async () => {
+      const service = await container.get(GuardRunnerService)
+
+      class ModuleGuard {}
+      class ControllerGuard {}
+      class EndpointGuard {}
+
+      const moduleMetadata = {
+        guards: new Set([ModuleGuard]),
+      } as unknown as ModuleMetadata
+
+      const controllerMetadata = {
+        guards: new Set([ControllerGuard]),
+      } as unknown as ControllerMetadata
+
+      const endpointMetadata = {
+        guards: new Set([EndpointGuard]),
+      } as unknown as HandlerMetadata<any>
+
+      const result = service.makeContext(
+        moduleMetadata,
+        controllerMetadata,
+        endpointMetadata,
+      )
+
+      expect(result.size).toBe(3)
+      expect(result.has(ModuleGuard as any)).toBe(true)
+      expect(result.has(ControllerGuard as any)).toBe(true)
+      expect(result.has(EndpointGuard as any)).toBe(true)
+    })
+
+    it('should handle empty guards at each level', async () => {
+      const service = await container.get(GuardRunnerService)
+
+      const moduleMetadata = {
+        guards: new Set(),
+      } as unknown as ModuleMetadata
+
+      const controllerMetadata = {
+        guards: new Set(),
+      } as unknown as ControllerMetadata
+
+      const endpointMetadata = {
+        guards: new Set(),
+      } as unknown as HandlerMetadata<any>
+
+      const result = service.makeContext(
+        moduleMetadata,
+        controllerMetadata,
+        endpointMetadata,
+      )
+
+      expect(result.size).toBe(0)
+    })
+
+    it('should deduplicate guards', async () => {
+      const service = await container.get(GuardRunnerService)
+
+      class SharedGuard {}
+
+      const moduleMetadata = {
+        guards: new Set([SharedGuard]),
+      } as unknown as ModuleMetadata
+
+      const controllerMetadata = {
+        guards: new Set([SharedGuard]), // Same guard
+      } as unknown as ControllerMetadata
+
+      const endpointMetadata = {
+        guards: new Set([SharedGuard]), // Same guard
+      } as unknown as HandlerMetadata<any>
+
+      const result = service.makeContext(
+        moduleMetadata,
+        controllerMetadata,
+        endpointMetadata,
+      )
+
+      // Set deduplicates automatically
+      expect(result.size).toBe(1)
+    })
+
+    it('should handle injection tokens as guards', async () => {
+      const service = await container.get(GuardRunnerService)
+
+      const GuardToken = InjectionToken.create<CanActivate>(
+        Symbol.for('GuardToken'),
+      )
+
+      const moduleMetadata = {
+        guards: new Set([GuardToken]),
+      } as unknown as ModuleMetadata
+
+      const controllerMetadata = {
+        guards: new Set(),
+      } as unknown as ControllerMetadata
+
+      const endpointMetadata = {
+        guards: new Set(),
+      } as unknown as HandlerMetadata<any>
+
+      const result = service.makeContext(
+        moduleMetadata,
+        controllerMetadata,
+        endpointMetadata,
+      )
+
+      expect(result.size).toBe(1)
+      expect(result.has(GuardToken)).toBe(true)
+    })
+  })
+})

package/src/__tests__/logger.service.spec.mts

@@ -0,0 +1,147 @@
+import { Container } from '@navios/di'
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import type { LoggerService } from '../index.mjs'
+
+import { LoggerInstance } from '../logger/logger.service.mjs'
+import { LoggerOutput } from '../logger/logger.tokens.mjs'
+
+describe('LoggerInstance', () => {
+  let container: Container
+  let mockLoggerOutput: {
+    log: ReturnType<typeof vi.fn>
+    error: ReturnType<typeof vi.fn>
+    warn: ReturnType<typeof vi.fn>
+    debug: ReturnType<typeof vi.fn>
+    verbose: ReturnType<typeof vi.fn>
+    fatal: ReturnType<typeof vi.fn>
+  }
+
+  beforeEach(() => {
+    container = new Container()
+    mockLoggerOutput = {
+      log: vi.fn(),
+      error: vi.fn(),
+      warn: vi.fn(),
+      debug: vi.fn(),
+      verbose: vi.fn(),
+      fatal: vi.fn(),
+    }
+  })
+
+  afterEach(async () => {
+    await container.dispose()
+  })
+
+  describe('log', () => {
+    it('should call localInstance.log with message', async () => {
+      container.addInstance(LoggerOutput, mockLoggerOutput as LoggerService)
+      const logger = await container.get(LoggerInstance)
+
+      logger.log('Test message')
+
+      expect(mockLoggerOutput.log).toHaveBeenCalledWith('Test message')
+    })
+  })
+
+  describe('error', () => {
+    it('should call localInstance.error with message', async () => {
+      container.addInstance(LoggerOutput, mockLoggerOutput as LoggerService)
+      const logger = await container.get(LoggerInstance)
+
+      logger.error('Error message')
+
+      expect(mockLoggerOutput.error).toHaveBeenCalledWith('Error message')
+    })
+  })
+
+  describe('warn', () => {
+    it('should call localInstance.warn with message', async () => {
+      container.addInstance(LoggerOutput, mockLoggerOutput as LoggerService)
+      const logger = await container.get(LoggerInstance)
+
+      logger.warn('Warning message')
+
+      expect(mockLoggerOutput.warn).toHaveBeenCalledWith('Warning message')
+    })
+  })
+
+  describe('debug', () => {
+    it('should call localInstance.debug with message', async () => {
+      container.addInstance(LoggerOutput, mockLoggerOutput as LoggerService)
+      const logger = await container.get(LoggerInstance)
+
+      logger.debug('Debug message')
+
+      expect(mockLoggerOutput.debug).toHaveBeenCalledWith('Debug message')
+    })
+
+    it('should handle missing debug method gracefully', async () => {
+      const loggerWithoutDebug = {
+        log: vi.fn(),
+        error: vi.fn(),
+        warn: vi.fn(),
+        // No debug method
+      }
+
+      container.addInstance(LoggerOutput, loggerWithoutDebug as LoggerService)
+      const logger = await container.get(LoggerInstance)
+
+      // Should not throw
+      expect(() => logger.debug('Debug message')).not.toThrow()
+    })
+  })
+
+  describe('verbose', () => {
+    it('should call localInstance.verbose with message', async () => {
+      container.addInstance(LoggerOutput, mockLoggerOutput as LoggerService)
+      const logger = await container.get(LoggerInstance)
+
+      logger.verbose('Verbose message')
+
+      expect(mockLoggerOutput.verbose).toHaveBeenCalledWith('Verbose message')
+    })
+
+    it('should handle missing verbose method gracefully', async () => {
+      const loggerWithoutVerbose = {
+        log: vi.fn(),
+        error: vi.fn(),
+        warn: vi.fn(),
+        // No verbose method
+      }
+
+      container.addInstance(LoggerOutput, loggerWithoutVerbose as LoggerService)
+      const logger = await container.get(LoggerInstance)
+
+      // Should not throw
+      expect(() => logger.verbose('Verbose message')).not.toThrow()
+    })
+  })
+
+  describe('fatal', () => {
+    it('should call localInstance.fatal with message', async () => {
+      container.addInstance(LoggerOutput, mockLoggerOutput as LoggerService)
+      const logger = await container.get(LoggerInstance)
+
+      logger.fatal('Fatal message')
+
+      expect(mockLoggerOutput.fatal).toHaveBeenCalledWith('Fatal message')
+    })
+
+    it('should handle missing fatal method gracefully', async () => {
+      const loggerWithoutFatal = {
+        log: vi.fn(),
+        error: vi.fn(),
+        warn: vi.fn(),
+        // No fatal method
+      }
+
+      container.addInstance(LoggerOutput, loggerWithoutFatal as LoggerService)
+      const logger = await container.get(LoggerInstance)
+
+      // Should not throw
+      expect(() => logger.fatal('Fatal message')).not.toThrow()
+    })
+  })
+})

package/src/__tests__/responders.spec.mts

@@ -9,10 +9,11 @@ import type { ErrorResponse } from '../responders/interfaces/error-response.inte
 import { NotFoundException } from '../exceptions/not-found.exception.mjs'
 import { FrameworkError } from '../responders/enums/framework-error.enum.mjs'
 import { ErrorResponseProducerService } from '../responders/services/error-response-producer.service.mjs'
-import { ForbiddenResponderService } from '../responders/services/forbidden-responder.service.mjs'
-import { InternalServerErrorResponderService } from '../responders/services/internal-server-error-responder.service.mjs'
-import { NotFoundResponderService } from '../responders/services/not-found-responder.service.mjs'
-import { ValidationErrorResponderService } from '../responders/services/validation-error-responder.service.mjs'
+// Import services for side-effects (registers @Injectable decorators)
+import '../responders/services/forbidden-responder.service.mjs'
+import '../responders/services/internal-server-error-responder.service.mjs'
+import '../responders/services/not-found-responder.service.mjs'
+import '../responders/services/validation-error-responder.service.mjs'
 import {
   ForbiddenResponderToken,
   InternalServerErrorResponderToken,
@@ -309,7 +310,7 @@ describe('Responders', () => {
         token: NotFoundResponderToken,
         priority: 0, // Higher than default -10
       })
-      class CustomNotFoundResponder implements ErrorResponder {
+      class _CustomNotFoundResponder implements ErrorResponder {
         getResponse(_error: unknown, description?: string): ErrorResponse {
           return {
             statusCode: 404,

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

@@ -32,10 +32,94 @@ export type HandlerResult<TRequest = any, TReply = any> =
   | StaticHandler<TRequest, TReply>
   | DynamicHandler<TRequest, TReply>
 
-export interface AbstractHttpHandlerAdapterInterface {
+/**
+ * Function type for argument getters that extract data from requests.
+ * Each getter populates a target object with data from the request.
+ */
+export type ArgumentGetterFn<TRequest = any> = (
+  target: Record<string, any>,
+  request: TRequest,
+) => void | Promise<void>
+
+/**
+ * Function type for formatting arguments from a request.
+ * Built from argument getters, optimized for sync/async handling.
+ */
+export type FormatArgumentsFn<TRequest = any> = (
+  request: TRequest,
+) => Record<string, any> | Promise<Record<string, any>>
+
+/**
+ * Interface for HTTP handler adapter services.
+ *
+ * Adapters handle different types of HTTP requests (REST, streaming, multipart)
+ * and are responsible for:
+ * - Parsing and validating request data
+ * - Creating handler functions
+ * - Formatting responses
+ * - Providing schema information (for frameworks like Fastify)
+ */
+export interface AbstractHttpHandlerAdapterInterface<TRequest = any> {
+  /**
+   * Prepares argument getters for parsing request data.
+   *
+   * Creates functions that extract and validate data from the request,
+   * populating a target object with validated arguments.
+   *
+   * @param handlerMetadata - The handler metadata with schemas and configuration.
+   * @returns An array of getter functions that populate request arguments.
+   */
   prepareArguments?: (
     handlerMetadata: HandlerMetadata<any>,
-  ) => ((target: Record<string, any>, request: any) => Promise<void> | void)[]
+  ) => ArgumentGetterFn<TRequest>[]
+
+  /**
+   * Builds a formatArguments function from argument getters.
+   *
+   * Automatically detects sync vs async getters and optimizes accordingly:
+   * - If all getters are sync: returns sync function (no Promise overhead)
+   * - If any getter is async: returns async function with Promise.all
+   * - If no getters: returns frozen empty object (zero allocation)
+   *
+   * This method is useful for composition-based adapters that need to
+   * build formatArguments without duplicating the optimization logic.
+   *
+   * @param getters - Array of argument getter functions
+   * @returns Function to format arguments from request
+   */
+  buildFormatArguments?: (
+    getters: ArgumentGetterFn<TRequest>[],
+  ) => FormatArgumentsFn<TRequest>
+
+  /**
+   * Checks if the handler has any validation schemas defined.
+   *
+   * @param handlerMetadata - The handler metadata containing configuration.
+   * @returns `true` if the handler has any schemas (request, query, response).
+   */
+  hasSchema?: (handlerMetadata: HandlerMetadata<any>) => boolean
+
+  /**
+   * Provides schema information for the framework's validation system.
+   *
+   * For frameworks like Fastify, this returns route schema objects.
+   * For frameworks like Bun, this typically returns an empty object.
+   *
+   * @param handlerMetadata - The handler metadata containing configuration.
+   * @returns Schema information for framework registration.
+   */
+  provideSchema?: (handlerMetadata: HandlerMetadata<any>) => Record<string, any>
+
+  /**
+   * Creates a request handler function for the endpoint.
+   *
+   * This is the core method that generates the actual handler function
+   * that will be called when a request matches the endpoint.
+   *
+   * @param controller - The controller class containing the handler method.
+   * @param handlerMetadata - The handler metadata with configuration and schemas.
+   * @returns A handler result that is either static or dynamic.
+   */
   provideHandler: (
     controller: ClassType,
     handlerMetadata: HandlerMetadata<any>,

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

@@ -1,5 +1,6 @@
-import type { z, ZodType } from 'zod/v4'
 import type { ClassType } from '@navios/di'
+import { createClassContext, createMethodContext } from '@navios/di/legacy-compat'
+import type { z, ZodType } from 'zod/v4'
 
 import type {
   ControllerMetadata,
@@ -18,7 +19,6 @@ import {
   getManagedMetadata,
   hasManagedMetadata,
 } from '../metadata/navios-managed.metadata.mjs'
-import { createClassContext, createMethodContext } from './context-compat.mjs'
 
 /**
  * Type for a legacy class/method attribute decorator without a value.

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

@@ -1,9 +1,9 @@
 import type { ClassType } from '@navios/di'
+import { createClassContext } from '@navios/di/legacy-compat'
 
 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.