@navios/core 0.6.0 → 0.7.0

package/lib/use-guards.decorator-kZ3lNK8v.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-guards.decorator-kZ3lNK8v.mjs","names":["EndpointMetadataKey","Symbol","getAllEndpointMetadata","context","metadata","Set","Error","getEndpointMetadata","target","endpointMetadata","Array","from","find","item","classMethod","name","newMetadata","url","successStatusCode","adapterToken","headers","httpMethod","config","guards","customAttributes","Map","add","getAllEndpointMetadata","ControllerMetadataKey","Symbol","getControllerMetadata","target","context","metadata","endpointsMetadata","newMetadata","endpoints","guards","Set","customAttributes","Map","Error","extractControllerMetadata","hasControllerMetadata","ModuleMetadataKey","Symbol","getModuleMetadata","target","context","metadata","newMetadata","controllers","Set","imports","guards","customAttributes","Map","Error","extractModuleMetadata","name","hasModuleMetadata","Injectable","InjectableScope","InjectionToken","getControllerMetadata","Controller","guards","target","context","kind","Error","token","create","metadata","controllerMetadata","guard","Array","from","reverse","add","scope","Request","InjectionToken","EndpointAdapterToken","create","InjectionToken","ExecutionContextInjectionToken","ExecutionContext","create","InjectionToken","HttpAdapterToken","create","InjectionToken","MultipartAdapterToken","create","InjectionToken","Reply","create","InjectionToken","Request","create","InjectionToken","StreamAdapterToken","create","InjectionToken","XmlStreamAdapterToken","create","getEndpointMetadata","EndpointAdapterToken","Endpoint","endpoint","target","context","kind","Error","config","metadata","endpointMetadata","url","method","adapterToken","classMethod","name","httpMethod","getEndpointMetadata","Header","name","value","target","context","kind","Error","metadata","headers","getEndpointMetadata","HttpCode","code","target","context","kind","Error","metadata","successStatusCode","Injectable","InjectableScope","InjectionToken","getModuleMetadata","Module","controllers","imports","guards","target","context","kind","Error","token","create","moduleMetadata","controller","add","importedModule","guard","Array","from","reverse","scope","Singleton","getEndpointMetadata","MultipartAdapterToken","Multipart","endpoint","target","context","Error","kind","config","metadata","endpointMetadata","url","method","adapterToken","classMethod","name","httpMethod","getEndpointMetadata","StreamAdapterToken","Stream","endpoint","target","context","Error","kind","config","metadata","endpointMetadata","url","method","adapterToken","classMethod","name","httpMethod","getControllerMetadata","getEndpointMetadata","UseGuards","guards","target","context","kind","controllerMetadata","guard","reverse","add","endpointMetadata","Error"],"sources":["../src/metadata/handler.metadata.mts","../src/metadata/controller.metadata.mts","../src/metadata/module.metadata.mts","../src/decorators/controller.decorator.mts","../src/tokens/endpoint-adapter.token.mts","../src/tokens/execution-context.token.mts","../src/tokens/http-adapter.token.mts","../src/tokens/multipart-adapter.token.mts","../src/tokens/reply.token.mts","../src/tokens/request.token.mts","../src/tokens/stream-adapter.token.mts","../src/tokens/xml-stream-adapter.token.mts","../src/decorators/endpoint.decorator.mts","../src/decorators/header.decorator.mts","../src/decorators/http-code.decorator.mts","../src/decorators/module.decorator.mts","../src/decorators/multipart.decorator.mts","../src/decorators/stream.decorator.mts","../src/decorators/use-guards.decorator.mts"],"sourcesContent":["import type { HttpMethod } from '@navios/builder'\nimport type { ClassTypeWithInstance, InjectionToken } from '@navios/di'\n\nimport type {\n  AbstractHttpHandlerAdapterInterface,\n  CanActivate,\n  HttpHeader,\n} from '../interfaces/index.mjs'\n\nexport const EndpointMetadataKey = Symbol('EndpointMetadataKey')\n\nexport interface HandlerMetadata<Config = null> {\n  classMethod: string\n  url: string\n  successStatusCode: number\n  adapterToken:\n    | InjectionToken<AbstractHttpHandlerAdapterInterface, undefined>\n    | ClassTypeWithInstance<AbstractHttpHandlerAdapterInterface>\n    | null\n  headers: Partial<Record<HttpHeader, number | string | string[] | undefined>>\n  httpMethod: HttpMethod\n  config: Config\n  guards: Set<\n    ClassTypeWithInstance<CanActivate> | InjectionToken<CanActivate, undefined>\n  >\n  customAttributes: Map<string | symbol, any>\n}\n\nexport function getAllEndpointMetadata(\n  context: ClassMethodDecoratorContext | ClassDecoratorContext,\n): Set<HandlerMetadata<any>> {\n  if (context.metadata) {\n    const metadata = context.metadata[EndpointMetadataKey] as\n      | Set<HandlerMetadata>\n      | undefined\n    if (metadata) {\n      return metadata\n    } else {\n      context.metadata[EndpointMetadataKey] = new Set<HandlerMetadata<any>>()\n      return context.metadata[EndpointMetadataKey] as Set<HandlerMetadata<any>>\n    }\n  }\n  throw new Error('[Navios] Wrong environment.')\n}\n\nexport function getEndpointMetadata<Config = any>(\n  target: Function,\n  context: ClassMethodDecoratorContext,\n): HandlerMetadata<Config> {\n  if (context.metadata) {\n    const metadata = getAllEndpointMetadata(context)\n    if (metadata) {\n      const endpointMetadata = Array.from(metadata).find(\n        (item) => item.classMethod === target.name,\n      )\n      if (endpointMetadata) {\n        return endpointMetadata\n      } else {\n        const newMetadata: HandlerMetadata<Config> = {\n          classMethod: target.name,\n          url: '',\n          successStatusCode: 200,\n          adapterToken: null,\n          headers: {},\n          httpMethod: 'GET',\n          // @ts-expect-error We are using a generic type here\n          config: null,\n          guards: new Set<\n            | ClassTypeWithInstance<CanActivate>\n            | InjectionToken<CanActivate, undefined>\n          >(),\n          customAttributes: new Map<string | symbol, any>(),\n        }\n        metadata.add(newMetadata)\n        return newMetadata\n      }\n    }\n  }\n  throw new Error('[Navios] Wrong environment.')\n}\n","import type {\n  ClassType,\n  ClassTypeWithInstance,\n  InjectionToken,\n} from '@navios/di'\n\nimport type { CanActivate } from '../interfaces/index.mjs'\nimport type { HandlerMetadata } from './handler.metadata.mjs'\n\nimport { getAllEndpointMetadata } from './handler.metadata.mjs'\n\nexport const ControllerMetadataKey = Symbol('ControllerMetadataKey')\n\nexport interface ControllerMetadata {\n  endpoints: Set<HandlerMetadata>\n  guards: Set<\n    ClassTypeWithInstance<CanActivate> | InjectionToken<CanActivate, undefined>\n  >\n  customAttributes: Map<string | symbol, any>\n}\n\nexport function getControllerMetadata(\n  target: ClassType,\n  context: ClassDecoratorContext,\n): ControllerMetadata {\n  if (context.metadata) {\n    const metadata = context.metadata[ControllerMetadataKey] as\n      | ControllerMetadata\n      | undefined\n    if (metadata) {\n      return metadata\n    } else {\n      const endpointsMetadata = getAllEndpointMetadata(context)\n      const newMetadata: ControllerMetadata = {\n        endpoints: endpointsMetadata,\n        guards: new Set<\n          | ClassTypeWithInstance<CanActivate>\n          | InjectionToken<CanActivate, undefined>\n        >(),\n        customAttributes: new Map<string | symbol, any>(),\n      }\n      context.metadata[ControllerMetadataKey] = newMetadata\n      // @ts-expect-error We add a custom metadata key to the target\n      target[ControllerMetadataKey] = newMetadata\n      return newMetadata\n    }\n  }\n  throw new Error('[Navios] Wrong environment.')\n}\n\nexport function extractControllerMetadata(\n  target: ClassType,\n): ControllerMetadata {\n  // @ts-expect-error We add a custom metadata key to the target\n  const metadata = target[ControllerMetadataKey] as\n    | ControllerMetadata\n    | undefined\n  if (!metadata) {\n    throw new Error(\n      '[Navios] Controller metadata not found. Make sure to use @Controller decorator.',\n    )\n  }\n  return metadata\n}\n\nexport function hasControllerMetadata(target: ClassType): boolean {\n  // @ts-expect-error We add a custom metadata key to the target\n  const metadata = target[ControllerMetadataKey] as\n    | ControllerMetadata\n    | undefined\n  return !!metadata\n}\n","import type {\n  ClassType,\n  ClassTypeWithInstance,\n  InjectionToken,\n} from '@navios/di'\n\nimport type { CanActivate } from '../index.mjs'\n\nexport const ModuleMetadataKey = Symbol('ControllerMetadataKey')\n\nexport interface ModuleMetadata {\n  controllers: Set<ClassType>\n  imports: Set<ClassType>\n  guards: Set<\n    ClassTypeWithInstance<CanActivate> | InjectionToken<CanActivate, undefined>\n  >\n  customAttributes: Map<string | symbol, any>\n}\n\nexport function getModuleMetadata(\n  target: ClassType,\n  context: ClassDecoratorContext,\n): ModuleMetadata {\n  if (context.metadata) {\n    const metadata = context.metadata[ModuleMetadataKey] as\n      | ModuleMetadata\n      | undefined\n    if (metadata) {\n      return metadata\n    } else {\n      const newMetadata: ModuleMetadata = {\n        controllers: new Set<ClassType>(),\n        imports: new Set<ClassType>(),\n        guards: new Set<\n          | ClassTypeWithInstance<CanActivate>\n          | InjectionToken<CanActivate, undefined>\n        >(),\n        customAttributes: new Map<string | symbol, any>(),\n      }\n      context.metadata[ModuleMetadataKey] = newMetadata\n      // @ts-expect-error We add a custom metadata key to the target\n      target[ModuleMetadataKey] = newMetadata\n      return newMetadata\n    }\n  }\n  throw new Error('[Navios] Wrong environment.')\n}\n\nexport function extractModuleMetadata(target: ClassType): ModuleMetadata {\n  // @ts-expect-error We add a custom metadata key to the target\n  const metadata = target[ModuleMetadataKey] as ModuleMetadata | undefined\n  if (!metadata) {\n    throw new Error(\n      `[Navios] Module metadata not found for ${target.name}. Make sure to use @Module decorator.`,\n    )\n  }\n  return metadata\n}\n\nexport function hasModuleMetadata(target: ClassType): boolean {\n  // @ts-expect-error We add a custom metadata key to the target\n  return !!target[ModuleMetadataKey]\n}\n","import type { ClassType } from '@navios/di'\n\nimport { Injectable, InjectableScope, InjectionToken } from '@navios/di'\n\nimport { getControllerMetadata } from '../metadata/index.mjs'\n\n/**\n * Options for configuring a Navios controller.\n */\nexport interface ControllerOptions {\n  /**\n   * Guards to apply to all endpoints in this controller.\n   * Guards are executed in reverse order (last guard first).\n   */\n  guards?: ClassType[] | Set<ClassType>\n}\n\n/**\n * Decorator that marks a class as a Navios controller.\n * \n * Controllers handle HTTP requests and define endpoints.\n * They are request-scoped by default, meaning a new instance is created for each request.\n * \n * @param options - Controller configuration options\n * @returns A class decorator\n * \n * @example\n * ```typescript\n * @Controller({ guards: [AuthGuard] })\n * export class UserController {\n *   @Endpoint(getUserEndpoint)\n *   async getUser(request: EndpointParams<typeof getUserEndpoint>) {\n *     // Handle request\n *   }\n * }\n * ```\n */\nexport function Controller({ guards }: ControllerOptions = {}) {\n  return function (target: ClassType, context: ClassDecoratorContext) {\n    if (context.kind !== 'class') {\n      throw new Error(\n        '[Navios] @Controller decorator can only be used on classes.',\n      )\n    }\n    const token = InjectionToken.create(target)\n    if (context.metadata) {\n      const controllerMetadata = getControllerMetadata(target, context)\n      if (guards) {\n        for (const guard of Array.from(guards).reverse()) {\n          controllerMetadata.guards.add(guard)\n        }\n      }\n    }\n    return Injectable({\n      token,\n      scope: InjectableScope.Request,\n    })(target, context)\n  }\n}\n","import { InjectionToken } from '@navios/di'\n\nimport type { AbstractHttpHandlerAdapterInterface } from '../interfaces/index.mjs'\n\nexport const EndpointAdapterToken =\n  InjectionToken.create<AbstractHttpHandlerAdapterInterface>(\n    'EndpointAdapterToken',\n  )\n","import { InjectionToken } from '@navios/di'\n\nimport type { AbstractExecutionContext } from '../interfaces/index.mjs'\n\nexport const ExecutionContextInjectionToken = 'ExecutionContextInjectionToken'\n\nexport const ExecutionContext = InjectionToken.create<AbstractExecutionContext>(\n  ExecutionContextInjectionToken,\n)\n","import { InjectionToken } from '@navios/di'\n\nimport type { AbstractHttpAdapterInterface } from '../interfaces/index.mjs'\n\nexport const HttpAdapterToken =\n  InjectionToken.create<AbstractHttpAdapterInterface<any, any, any, any>>(\n    'HttpAdapterToken',\n  )\n","import { InjectionToken } from '@navios/di'\n\nimport type { AbstractHttpHandlerAdapterInterface } from '../interfaces/index.mjs'\n\nexport const MultipartAdapterToken =\n  InjectionToken.create<AbstractHttpHandlerAdapterInterface>(\n    'MultipartAdapterToken',\n  )\n","import { InjectionToken } from '@navios/di'\n\nexport const Reply = InjectionToken.create<any>('ReplyToken')\n","import { InjectionToken } from '@navios/di'\n\nexport const Request = InjectionToken.create<any>('RequestToken')\n","import { InjectionToken } from '@navios/di'\n\nimport type { AbstractHttpHandlerAdapterInterface } from '../interfaces/index.mjs'\n\nexport const StreamAdapterToken =\n  InjectionToken.create<AbstractHttpHandlerAdapterInterface>(\n    'StreamAdapterToken',\n  )\n","import { InjectionToken } from '@navios/di'\n\nimport type { AbstractHttpHandlerAdapterInterface } from '../interfaces/index.mjs'\n\nexport const XmlStreamAdapterToken =\n  InjectionToken.create<AbstractHttpHandlerAdapterInterface>(\n    'XmlStreamAdapterToken',\n  )\n","import type {\n  BaseEndpointConfig,\n  EndpointFunctionArgs,\n  HttpMethod,\n  Util_FlatObject,\n} from '@navios/builder'\nimport type { z, ZodType } from 'zod/v4'\n\nimport { ZodDiscriminatedUnion } from 'zod/v4'\n\nimport { getEndpointMetadata } from '../metadata/index.mjs'\nimport { EndpointAdapterToken } from '../tokens/index.mjs'\n\n/**\n * Extracts the typed parameters for an endpoint handler function.\n *\n * This utility type extracts URL parameters, query parameters, and request body\n * from an endpoint declaration and flattens them into a single object.\n *\n * @typeParam EndpointDeclaration - The endpoint declaration from @navios/builder\n *\n * @example\n * ```typescript\n * const getUserEndpoint = api.declareEndpoint({\n *   method: 'get',\n *   url: '/users/$userId',\n *   querySchema: z.object({ include: z.string().optional() }),\n *   responseSchema: z.object({ id: z.string(), name: z.string() }),\n * })\n *\n * @Endpoint(getUserEndpoint)\n * async getUser(request: EndpointParams<typeof getUserEndpoint>) {\n *   // request.urlParams.userId is typed as string\n *   // request.query.include is typed as string | undefined\n * }\n * ```\n */\nexport type EndpointParams<\n  EndpointDeclaration extends {\n    config: BaseEndpointConfig<any, any, any, any, any>\n  },\n  Url extends string = EndpointDeclaration['config']['url'],\n  QuerySchema = EndpointDeclaration['config']['querySchema'],\n> = QuerySchema extends ZodType\n  ? EndpointDeclaration['config']['requestSchema'] extends ZodType\n    ? Util_FlatObject<\n        EndpointFunctionArgs<\n          Url,\n          QuerySchema,\n          EndpointDeclaration['config']['requestSchema'],\n          true\n        >\n      >\n    : Util_FlatObject<EndpointFunctionArgs<Url, QuerySchema, undefined, true>>\n  : EndpointDeclaration['config']['requestSchema'] extends ZodType\n    ? Util_FlatObject<\n        EndpointFunctionArgs<\n          Url,\n          undefined,\n          EndpointDeclaration['config']['requestSchema'],\n          true\n        >\n      >\n    : Util_FlatObject<EndpointFunctionArgs<Url, undefined, undefined, true>>\n\n/**\n * Extracts the typed return value for an endpoint handler function.\n *\n * This utility type extracts the response schema from an endpoint declaration\n * and returns the appropriate Promise type.\n *\n * @typeParam EndpointDeclaration - The endpoint declaration from @navios/builder\n *\n * @example\n * ```typescript\n * const getUserEndpoint = api.declareEndpoint({\n *   method: 'get',\n *   url: '/users/$userId',\n *   responseSchema: z.object({ id: z.string(), name: z.string() }),\n * })\n *\n * @Endpoint(getUserEndpoint)\n * async getUser(request: EndpointParams<typeof getUserEndpoint>): EndpointResult<typeof getUserEndpoint> {\n *   return { id: '1', name: 'John' } // Type-checked against responseSchema\n * }\n * ```\n */\nexport type EndpointResult<\n  EndpointDeclaration extends {\n    config: BaseEndpointConfig<any, any, any, any, any>\n  },\n> =\n  EndpointDeclaration['config']['responseSchema'] extends ZodDiscriminatedUnion<\n    infer Options\n  >\n    ? Promise<z.input<Options[number]>>\n    : Promise<z.input<EndpointDeclaration['config']['responseSchema']>>\n\n/**\n * Decorator that marks a method as an HTTP endpoint.\n *\n * The endpoint must be defined using @navios/builder's `declareEndpoint` method.\n * This ensures type safety and consistency between client and server.\n *\n * @param endpoint - The endpoint declaration from @navios/builder\n * @returns A method decorator\n *\n * @example\n * ```typescript\n * import { builder } from '@navios/builder'\n *\n * const api = builder()\n * const getUserEndpoint = api.declareEndpoint({\n *   method: 'get',\n *   url: '/users/$userId',\n *   responseSchema: z.object({ id: z.string(), name: z.string() }),\n * })\n *\n * @Controller()\n * export class UserController {\n *   @Endpoint(getUserEndpoint)\n *   async getUser(request: EndpointParams<typeof getUserEndpoint>) {\n *     const { userId } = request.urlParams\n *     return { id: userId, name: 'John' }\n *   }\n * }\n * ```\n */\nexport function Endpoint<\n  Method extends HttpMethod = HttpMethod,\n  Url extends string = string,\n  QuerySchema = undefined,\n  ResponseSchema extends ZodType = ZodType,\n  RequestSchema = ZodType,\n>(endpoint: {\n  config: BaseEndpointConfig<\n    Method,\n    Url,\n    QuerySchema,\n    ResponseSchema,\n    RequestSchema\n  >\n}) {\n  return (\n    target: (\n      params: QuerySchema extends ZodType\n        ? RequestSchema extends ZodType\n          ? EndpointFunctionArgs<Url, QuerySchema, RequestSchema, true>\n          : EndpointFunctionArgs<Url, QuerySchema, undefined, true>\n        : RequestSchema extends ZodType\n          ? EndpointFunctionArgs<Url, undefined, RequestSchema, true>\n          : EndpointFunctionArgs<Url, undefined, undefined, true>,\n    ) => Promise<z.input<ResponseSchema>>,\n    context: ClassMethodDecoratorContext,\n  ) => {\n    if (context.kind !== 'method') {\n      throw new Error(\n        '[Navios] Endpoint decorator can only be used on methods.',\n      )\n    }\n    const config = endpoint.config\n    if (context.metadata) {\n      let endpointMetadata = getEndpointMetadata<BaseEndpointConfig>(\n        target,\n        context,\n      )\n      if (endpointMetadata.config && endpointMetadata.config.url) {\n        throw new Error(\n          `[Navios] Endpoint ${config.method} ${config.url} already exists. Please use a different method or url.`,\n        )\n      }\n      // @ts-expect-error We don't need to set correctly in the metadata\n      endpointMetadata.config = config\n      endpointMetadata.adapterToken = EndpointAdapterToken\n      endpointMetadata.classMethod = target.name\n      endpointMetadata.httpMethod = config.method\n      endpointMetadata.url = config.url\n    }\n    return target\n  }\n}\n","import type { HttpHeader } from '../interfaces/index.mjs'\n\nimport { getEndpointMetadata } from '../metadata/index.mjs'\n\n/**\n * Decorator that sets a custom HTTP response header for an endpoint.\n * \n * @param name - The header name (e.g., 'Content-Type', 'Cache-Control')\n * @param value - The header value (string, number, or array of strings)\n * @returns A method decorator\n * \n * @example\n * ```typescript\n * @Controller()\n * export class UserController {\n *   @Endpoint(getUserEndpoint)\n *   @Header('Cache-Control', 'max-age=3600')\n *   async getUser() {\n *     return { id: '1', name: 'John' }\n *   }\n * }\n * ```\n */\nexport function Header(name: HttpHeader, value: string | number | string[]) {\n  return <T extends Function>(\n    target: T,\n    context: ClassMethodDecoratorContext,\n  ) => {\n    if (context.kind !== 'method') {\n      throw new Error('[Navios] Header decorator can only be used on methods.')\n    }\n    const metadata = getEndpointMetadata(target, context)\n\n    metadata.headers[name] = value\n\n    return target\n  }\n}\n","import { getEndpointMetadata } from '../metadata/index.mjs'\n\n/**\n * Decorator that sets a custom HTTP status code for successful responses.\n * \n * By default, endpoints return 200 OK. Use this decorator to return a different status code.\n * \n * @param code - The HTTP status code to return (e.g., 201, 204, 202)\n * @returns A method decorator\n * \n * @example\n * ```typescript\n * @Controller()\n * export class UserController {\n *   @Endpoint(createUserEndpoint)\n *   @HttpCode(201)\n *   async createUser() {\n *     return { id: '1', name: 'John' }\n *   }\n * }\n * ```\n */\nexport function HttpCode(code: number) {\n  return <T extends Function>(\n    target: T,\n    context: ClassMethodDecoratorContext,\n  ) => {\n    if (context.kind !== 'method') {\n      throw new Error(\n        '[Navios] HttpCode decorator can only be used on methods.',\n      )\n    }\n    const metadata = getEndpointMetadata(target, context)\n    metadata.successStatusCode = code\n\n    return target\n  }\n}\n","import type { ClassType } from '@navios/di'\n\nimport { Injectable, InjectableScope, InjectionToken } from '@navios/di'\n\nimport { getModuleMetadata } from '../metadata/index.mjs'\n\n/**\n * Options for configuring a Navios module.\n */\nexport interface ModuleOptions {\n  /**\n   * Controllers to register in this module.\n   * Controllers handle HTTP requests and define endpoints.\n   */\n  controllers?: ClassType[] | Set<ClassType>\n  /**\n   * Other modules to import into this module.\n   * Imported modules' controllers and services become available.\n   */\n  imports?: ClassType[] | Set<ClassType>\n  /**\n   * Guards to apply to all controllers in this module.\n   * Guards are executed in reverse order (last guard first).\n   */\n  guards?: ClassType[] | Set<ClassType>\n}\n\n/**\n * Decorator that marks a class as a Navios module.\n * \n * Modules are the basic building blocks of a Navios application.\n * They organize controllers, services, and other modules into logical units.\n * \n * @param options - Module configuration options\n * @returns A class decorator\n * \n * @example\n * ```typescript\n * @Module({\n *   controllers: [UserController, AuthController],\n *   imports: [DatabaseModule],\n *   guards: [AuthGuard],\n * })\n * export class AppModule {}\n * ```\n */\nexport function Module(\n  { controllers = [], imports = [], guards = [] }: ModuleOptions = {\n    controllers: [],\n    imports: [],\n    guards: [],\n  },\n) {\n  return (target: ClassType, context: ClassDecoratorContext) => {\n    if (context.kind !== 'class') {\n      throw new Error('[Navios] @Module decorator can only be used on classes.')\n    }\n    // Register the module in the service locator\n    const token = InjectionToken.create(target)\n    const moduleMetadata = getModuleMetadata(target, context)\n    for (const controller of controllers) {\n      moduleMetadata.controllers.add(controller)\n    }\n    for (const importedModule of imports) {\n      moduleMetadata.imports.add(importedModule)\n    }\n    for (const guard of Array.from(guards).reverse()) {\n      moduleMetadata.guards.add(guard)\n    }\n\n    return Injectable({\n      token,\n      scope: InjectableScope.Singleton,\n    })(target, context)\n  }\n}\n","import type {\n  BaseEndpointConfig,\n  EndpointFunctionArgs,\n  HttpMethod,\n  Util_FlatObject,\n} from '@navios/builder'\nimport type { z, ZodObject, ZodType } from 'zod/v4'\n\nimport { ZodDiscriminatedUnion } from 'zod/v4'\n\nimport { getEndpointMetadata } from '../metadata/index.mjs'\nimport { MultipartAdapterToken } from '../tokens/index.mjs'\n\n/**\n * Extracts the typed parameters for a multipart endpoint handler function.\n * \n * Similar to `EndpointParams`, but specifically for multipart/form-data endpoints.\n * \n * @typeParam EndpointDeclaration - The endpoint declaration from @navios/builder\n */\nexport type MultipartParams<\n  EndpointDeclaration extends {\n    config: BaseEndpointConfig<any, any, any, any, any>\n  },\n  Url extends string = EndpointDeclaration['config']['url'],\n  QuerySchema = EndpointDeclaration['config']['querySchema'],\n> = QuerySchema extends ZodObject\n  ? EndpointDeclaration['config']['requestSchema'] extends ZodType\n    ? Util_FlatObject<\n        EndpointFunctionArgs<\n          Url,\n          QuerySchema,\n          EndpointDeclaration['config']['requestSchema'],\n          true\n        >\n      >\n    : Util_FlatObject<EndpointFunctionArgs<Url, QuerySchema, undefined, true>>\n  : EndpointDeclaration['config']['requestSchema'] extends ZodType\n    ? Util_FlatObject<\n        EndpointFunctionArgs<\n          Url,\n          undefined,\n          EndpointDeclaration['config']['requestSchema'],\n          true\n        >\n      >\n    : Util_FlatObject<EndpointFunctionArgs<Url, undefined, undefined, true>>\n\n/**\n * Extracts the typed return value for a multipart endpoint handler function.\n * \n * @typeParam EndpointDeclaration - The endpoint declaration from @navios/builder\n */\nexport type MultipartResult<\n  EndpointDeclaration extends {\n    config: BaseEndpointConfig<any, any, any, any, any>\n  },\n> =\n  EndpointDeclaration['config']['responseSchema'] extends ZodDiscriminatedUnion<\n    infer Options\n  >\n    ? Promise<z.input<Options[number]>>\n    : Promise<z.input<EndpointDeclaration['config']['responseSchema']>>\n\n/**\n * Decorator that marks a method as a multipart/form-data endpoint.\n * \n * Use this decorator for endpoints that handle file uploads or form data.\n * The endpoint must be defined using @navios/builder's `declareMultipart` method.\n * \n * @param endpoint - The multipart endpoint declaration from @navios/builder\n * @returns A method decorator\n * \n * @example\n * ```typescript\n * const uploadFileEndpoint = api.declareMultipart({\n *   method: 'post',\n *   url: '/upload',\n *   requestSchema: z.object({ file: z.instanceof(File) }),\n *   responseSchema: z.object({ url: z.string() }),\n * })\n * \n * @Controller()\n * export class FileController {\n *   @Multipart(uploadFileEndpoint)\n *   async uploadFile(request: MultipartParams<typeof uploadFileEndpoint>) {\n *     const { file } = request.data\n *     // Handle file upload\n *     return { url: 'https://example.com/file.jpg' }\n *   }\n * }\n * ```\n */\nexport function Multipart<\n  Method extends HttpMethod = HttpMethod,\n  Url extends string = string,\n  QuerySchema = undefined,\n  ResponseSchema extends ZodType = ZodType,\n  RequestSchema = ZodType,\n>(endpoint: {\n  config: BaseEndpointConfig<\n    Method,\n    Url,\n    QuerySchema,\n    ResponseSchema,\n    RequestSchema\n  >\n}) {\n  return (\n    target: (\n      params: QuerySchema extends ZodObject\n        ? RequestSchema extends ZodType\n          ? EndpointFunctionArgs<Url, QuerySchema, RequestSchema>\n          : EndpointFunctionArgs<Url, QuerySchema, undefined>\n        : RequestSchema extends ZodType\n          ? EndpointFunctionArgs<Url, undefined, RequestSchema>\n          : EndpointFunctionArgs<Url, undefined, undefined>,\n    ) => Promise<z.input<ResponseSchema>>,\n    context: ClassMethodDecoratorContext,\n  ) => {\n    if (typeof target !== 'function') {\n      throw new Error(\n        '[Navios] Endpoint decorator can only be used on functions.',\n      )\n    }\n    if (context.kind !== 'method') {\n      throw new Error(\n        '[Navios] Endpoint decorator can only be used on methods.',\n      )\n    }\n    const config = endpoint.config\n    if (context.metadata) {\n      let endpointMetadata = getEndpointMetadata<BaseEndpointConfig>(\n        target,\n        context,\n      )\n      if (endpointMetadata.config && endpointMetadata.config.url) {\n        throw new Error(\n          `[Navios] Endpoint ${config.method} ${config.url} already exists. Please use a different method or url.`,\n        )\n      }\n      // @ts-expect-error We don't need to set correctly in the metadata\n      endpointMetadata.config = config\n      endpointMetadata.adapterToken = MultipartAdapterToken\n      endpointMetadata.classMethod = target.name\n      endpointMetadata.httpMethod = config.method\n      endpointMetadata.url = config.url\n    }\n    return target\n  }\n}\n","import type {\n  BaseStreamConfig,\n  EndpointFunctionArgs,\n  HttpMethod,\n  Util_FlatObject,\n} from '@navios/builder'\nimport type { ZodObject, ZodType } from 'zod/v4'\n\nimport { getEndpointMetadata } from '../metadata/index.mjs'\nimport { StreamAdapterToken } from '../tokens/index.mjs'\n\n/**\n * Extracts the typed parameters for a stream endpoint handler function.\n * \n * Similar to `EndpointParams`, but specifically for streaming endpoints.\n * \n * @typeParam EndpointDeclaration - The stream endpoint declaration from @navios/builder\n */\nexport type StreamParams<\n  EndpointDeclaration extends {\n    config: BaseStreamConfig<any, any, any, any>\n  },\n  Url extends string = EndpointDeclaration['config']['url'],\n  QuerySchema = EndpointDeclaration['config']['querySchema'],\n> = QuerySchema extends ZodObject\n  ? EndpointDeclaration['config']['requestSchema'] extends ZodType\n    ? Util_FlatObject<\n        EndpointFunctionArgs<\n          Url,\n          QuerySchema,\n          EndpointDeclaration['config']['requestSchema'],\n          true\n        >\n      >\n    : Util_FlatObject<EndpointFunctionArgs<Url, QuerySchema, undefined, true>>\n  : EndpointDeclaration['config']['requestSchema'] extends ZodType\n    ? Util_FlatObject<\n        EndpointFunctionArgs<\n          Url,\n          undefined,\n          EndpointDeclaration['config']['requestSchema'],\n          true\n        >\n      >\n    : Util_FlatObject<EndpointFunctionArgs<Url, undefined, undefined, true>>\n\n/**\n * Decorator that marks a method as a streaming endpoint.\n * \n * Use this decorator for endpoints that stream data (e.g., file downloads, SSE).\n * The endpoint must be defined using @navios/builder's `declareStream` method.\n * \n * @param endpoint - The stream endpoint declaration from @navios/builder\n * @returns A method decorator\n * \n * @example\n * ```typescript\n * const downloadFileEndpoint = api.declareStream({\n *   method: 'get',\n *   url: '/files/$fileId',\n * })\n * \n * @Controller()\n * export class FileController {\n *   @Stream(downloadFileEndpoint)\n *   async downloadFile(request: StreamParams<typeof downloadFileEndpoint>, reply: any) {\n *     const { fileId } = request.urlParams\n *     // Stream file data to reply\n *   }\n * }\n * ```\n */\nexport function Stream<\n  Method extends HttpMethod = HttpMethod,\n  Url extends string = string,\n  QuerySchema = undefined,\n  RequestSchema = ZodType,\n>(endpoint: {\n  config: BaseStreamConfig<Method, Url, QuerySchema, RequestSchema>\n}) {\n  return (\n    target: (\n      params: QuerySchema extends ZodObject\n        ? RequestSchema extends ZodType\n          ? EndpointFunctionArgs<Url, QuerySchema, RequestSchema>\n          : EndpointFunctionArgs<Url, QuerySchema, undefined>\n        : RequestSchema extends ZodType\n          ? EndpointFunctionArgs<Url, undefined, RequestSchema>\n          : EndpointFunctionArgs<Url, undefined, undefined>,\n      reply: any,\n    ) => Promise<void>,\n    context: ClassMethodDecoratorContext,\n  ) => {\n    if (typeof target !== 'function') {\n      throw new Error(\n        '[Navios] Endpoint decorator can only be used on functions.',\n      )\n    }\n    if (context.kind !== 'method') {\n      throw new Error(\n        '[Navios] Endpoint decorator can only be used on methods.',\n      )\n    }\n    const config = endpoint.config\n    if (context.metadata) {\n      let endpointMetadata = getEndpointMetadata<BaseStreamConfig>(\n        target,\n        context,\n      )\n      if (endpointMetadata.config && endpointMetadata.config.url) {\n        throw new Error(\n          `[Navios] Endpoint ${config.method} ${config.url} already exists. Please use a different method or url.`,\n        )\n      }\n      // @ts-expect-error We don't need to set correctly in the metadata\n      endpointMetadata.config = config\n      endpointMetadata.adapterToken = StreamAdapterToken\n      endpointMetadata.classMethod = target.name\n      endpointMetadata.httpMethod = config.method\n      endpointMetadata.url = config.url\n    }\n    return target\n  }\n}\n","import type {\n  ClassType,\n  ClassTypeWithInstance,\n  InjectionToken,\n} from '@navios/di'\n\nimport type { CanActivate } from '../interfaces/index.mjs'\n\nimport {\n  getControllerMetadata,\n  getEndpointMetadata,\n} from '../metadata/index.mjs'\n\n/**\n * Decorator that applies guards to a controller or endpoint.\n * \n * Guards are used for authentication, authorization, and request validation.\n * They implement the `CanActivate` interface and are executed before the endpoint handler.\n * Guards can be applied at the module, controller, or endpoint level.\n * \n * @param guards - Guard classes or injection tokens to apply\n * @returns A class or method decorator\n * \n * @example\n * ```typescript\n * // Apply to a controller\n * @Controller()\n * @UseGuards(AuthGuard, RoleGuard)\n * export class UserController {\n *   @Endpoint(getUserEndpoint)\n *   async getUser() { }\n * }\n * \n * // Apply to a specific endpoint\n * @Controller()\n * export class UserController {\n *   @Endpoint(getUserEndpoint)\n *   @UseGuards(AuthGuard)\n *   async getUser() { }\n * }\n * ```\n */\nexport function UseGuards(\n  ...guards: (\n    | ClassTypeWithInstance<CanActivate>\n    | InjectionToken<CanActivate, undefined>\n  )[]\n) {\n  return function <T extends Function>(\n    target: T,\n    context: ClassMethodDecoratorContext | ClassDecoratorContext,\n  ): T {\n    if (context.kind === 'class') {\n      const controllerMetadata = getControllerMetadata(\n        target as unknown as ClassType,\n        context,\n      )\n      for (const guard of guards.reverse()) {\n        controllerMetadata.guards.add(guard)\n      }\n    } else if (context.kind === 'method') {\n      const endpointMetadata = getEndpointMetadata(target, context)\n      for (const guard of guards.reverse()) {\n        endpointMetadata.guards.add(guard)\n      }\n    } else {\n      throw new Error(\n        '[Navios] @UseGuards decorator can only be used on classes or methods.',\n      )\n    }\n    return target\n  }\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@navios/core",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "author": {
     "name": "Oleksandr Hanzha",
     "email": "alex@granted.name"
@@ -12,7 +12,7 @@
   },
   "license": "MIT",
   "peerDependencies": {
-    "@navios/builder": "^0.4.0",
+    "@navios/builder": "^0.5.0",
     "zod": "^3.25.0 || ^4.0.0"
   },
   "typings": "./lib/index.d.mts",
@@ -28,10 +28,30 @@
         "types": "./lib/index.d.ts",
         "default": "./lib/index.js"
       }
+    },
+    "./testing": {
+      "import": {
+        "types": "./lib/testing/index.d.mts",
+        "default": "./lib/testing/index.mjs"
+      },
+      "require": {
+        "types": "./lib/testing/index.d.ts",
+        "default": "./lib/testing/index.js"
+      }
+    },
+    "./legacy-compat": {
+      "import": {
+        "types": "./lib/legacy-compat/index.d.mts",
+        "default": "./lib/legacy-compat/index.mjs"
+      },
+      "require": {
+        "types": "./lib/legacy-compat/index.d.ts",
+        "default": "./lib/legacy-compat/index.js"
+      }
     }
   },
   "devDependencies": {
-    "@navios/builder": "^0.4.0",
+    "@navios/builder": "^0.5.0",
     "@types/supertest": "^6.0.3",
     "supertest": "^7.1.4",
     "tsx": "^4.21.0",
@@ -39,6 +59,6 @@
     "zod": "^4.1.13"
   },
   "dependencies": {
-    "@navios/di": "^0.5.0"
+    "@navios/di": "^0.6.0"
   }
 }

package/project.json

@@ -38,11 +38,11 @@
     },
     "build": {
       "executor": "nx:run-commands",
-      "inputs": ["projectSources", "{projectRoot}/tsup.config.mts"],
+      "inputs": ["projectSources", "{projectRoot}/tsdown.config.mts"],
       "outputs": ["{projectRoot}/lib"],
       "dependsOn": ["check", "test:ci", "lint"],
       "options": {
-        "command": "tsup",
+        "command": "tsdown",
         "cwd": "packages/core"
       }
     },

package/src/attribute.factory.d.mts

@@ -0,0 +1,175 @@
+import type { z, ZodType } from 'zod/v4';
+import type { ControllerMetadata, HandlerMetadata, ModuleMetadata } from './metadata/index.mjs';
+/**
+ * Type for a class attribute decorator without a value.
+ *
+ * Attributes are custom metadata decorators that can be applied to modules,
+ * controllers, and endpoints.
+ */
+export type ClassAttribute = (() => <T>(target: T, context: ClassDecoratorContext | ClassMethodDecoratorContext) => T) & {
+    token: symbol;
+};
+/**
+ * Type for a class attribute decorator with a validated value.
+ *
+ * @typeParam T - The Zod schema type for validation
+ */
+export type ClassSchemaAttribute<T extends ZodType> = ((value: z.input<T>) => <T>(target: T, context: ClassDecoratorContext | ClassMethodDecoratorContext) => T) & {
+    token: symbol;
+    schema: ZodType;
+};
+/**
+ * Factory for creating custom attribute decorators.
+ *
+ * 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 = AttributeFactory.createAttribute(Symbol.for('Public'))
+ *
+ * // Use it as a decorator
+ * @Controller()
+ * @Public()
+ * export class PublicController { }
+ *
+ * // Check if attribute exists
+ * if (AttributeFactory.has(Public, controllerMetadata)) {
+ *   // Skip authentication
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Create an attribute with a validated value
+ * const RateLimit = AttributeFactory.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 = AttributeFactory.get(RateLimit, endpointMetadata)
+ * // limit is typed as { requests: number, window: number } | null
+ * ```
+ */
+export declare class AttributeFactory {
+    /**
+     * 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 = AttributeFactory.createAttribute(Symbol.for('Public'))
+     *
+     * @Public()
+     * @Controller()
+     * export class PublicController { }
+     * ```
+     */
+    static createAttribute(token: symbol): ClassAttribute;
+    /**
+     * 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 = AttributeFactory.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): ClassSchemaAttribute<T>;
+    /**
+     * 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 = AttributeFactory.get(Public, controllerMetadata)
+     * // isPublic is true | null
+     *
+     * const rateLimit = AttributeFactory.get(RateLimit, endpointMetadata)
+     * // rateLimit is { requests: number, window: number } | null
+     * ```
+     */
+    static get(attribute: ClassAttribute, target: ModuleMetadata | ControllerMetadata | HandlerMetadata<any>): true | null;
+    static get<T extends ZodType>(attribute: ClassSchemaAttribute<T>, target: ModuleMetadata | ControllerMetadata | HandlerMetadata<any>): z.output<T> | 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 = AttributeFactory.getAll(Tag, endpointMetadata)
+     * // tags is string[] | null
+     * ```
+     */
+    static getAll(attribute: ClassAttribute, target: ModuleMetadata | ControllerMetadata | HandlerMetadata<any>): Array<true> | null;
+    static getAll<T extends ZodType>(attribute: ClassSchemaAttribute<T>, target: ModuleMetadata | ControllerMetadata | HandlerMetadata<any>): Array<z.output<T>> | 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 = AttributeFactory.getLast(RateLimit, [
+     *   moduleMetadata,
+     *   controllerMetadata,
+     *   endpointMetadata
+     * ])
+     * ```
+     */
+    static getLast(attribute: ClassAttribute, target: (ModuleMetadata | ControllerMetadata | HandlerMetadata<any>)[]): true | null;
+    static getLast<T extends ZodType>(attribute: ClassSchemaAttribute<T>, target: (ModuleMetadata | ControllerMetadata | HandlerMetadata<any>)[]): z.output<T> | 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 (AttributeFactory.has(Public, controllerMetadata)) {
+     *   // Skip authentication
+     * }
+     * ```
+     */
+    static has(attribute: ClassAttribute, target: ModuleMetadata | ControllerMetadata | HandlerMetadata<any>): boolean;
+    static has<T extends ZodType>(attribute: ClassSchemaAttribute<T>, target: ModuleMetadata | ControllerMetadata | HandlerMetadata<any>): boolean;
+}
+//# sourceMappingURL=attribute.factory.d.mts.map

package/src/attribute.factory.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attribute.factory.d.mts","sourceRoot":"","sources":["attribute.factory.mts"],"names":[],"mappings":"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"}

package/src/attribute.factory.mts

@@ -15,12 +15,24 @@ import {
   hasModuleMetadata,
 } from './metadata/index.mjs'
 
+/**
+ * Type for a class attribute decorator without a value.
+ * 
+ * Attributes are custom metadata decorators that can be applied to modules,
+ * controllers, and endpoints.
+ */
 export type ClassAttribute = (() => <T>(
   target: T,
   context: ClassDecoratorContext | ClassMethodDecoratorContext,
 ) => T) & {
   token: symbol
 }
+
+/**
+ * Type for a class attribute decorator with a validated value.
+ * 
+ * @typeParam T - The Zod schema type for validation
+ */
 export type ClassSchemaAttribute<T extends ZodType> = ((
   value: z.input<T>,
 ) => <T>(
@@ -31,8 +43,82 @@ export type ClassSchemaAttribute<T extends ZodType> = ((
   schema: ZodType
 }
 
+/**
+ * Factory for creating custom attribute decorators.
+ * 
+ * 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 = AttributeFactory.createAttribute(Symbol.for('Public'))
+ * 
+ * // Use it as a decorator
+ * @Controller()
+ * @Public()
+ * export class PublicController { }
+ * 
+ * // Check if attribute exists
+ * if (AttributeFactory.has(Public, controllerMetadata)) {
+ *   // Skip authentication
+ * }
+ * ```
+ * 
+ * @example
+ * ```typescript
+ * // Create an attribute with a validated value
+ * const RateLimit = AttributeFactory.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 = AttributeFactory.get(RateLimit, endpointMetadata)
+ * // limit is typed as { requests: number, window: number } | null
+ * ```
+ */
 export class AttributeFactory {
+  /**
+   * 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 = AttributeFactory.createAttribute(Symbol.for('Public'))
+   * 
+   * @Public()
+   * @Controller()
+   * export class PublicController { }
+   * ```
+   */
   static createAttribute(token: symbol): ClassAttribute
+  /**
+   * 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 = AttributeFactory.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,
@@ -84,6 +170,25 @@ export class AttributeFactory {
     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 = AttributeFactory.get(Public, controllerMetadata)
+   * // isPublic is true | null
+   * 
+   * const rateLimit = AttributeFactory.get(RateLimit, endpointMetadata)
+   * // rateLimit is { requests: number, window: number } | null
+   * ```
+   */
   static get(
     attribute: ClassAttribute,
     target: ModuleMetadata | ControllerMetadata | HandlerMetadata<any>,
@@ -99,6 +204,21 @@ export class AttributeFactory {
     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 = AttributeFactory.getAll(Tag, endpointMetadata)
+   * // tags is string[] | null
+   * ```
+   */
   static getAll(
     attribute: ClassAttribute,
     target: ModuleMetadata | ControllerMetadata | HandlerMetadata<any>,
@@ -117,6 +237,26 @@ export class AttributeFactory {
     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 = AttributeFactory.getLast(RateLimit, [
+   *   moduleMetadata,
+   *   controllerMetadata,
+   *   endpointMetadata
+   * ])
+   * ```
+   */
   static getLast(
     attribute: ClassAttribute,
     target: (ModuleMetadata | ControllerMetadata | HandlerMetadata<any>)[],
@@ -138,6 +278,20 @@ export class AttributeFactory {
     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 (AttributeFactory.has(Public, controllerMetadata)) {
+   *   // Skip authentication
+   * }
+   * ```
+   */
   static has(
     attribute: ClassAttribute,
     target: ModuleMetadata | ControllerMetadata | HandlerMetadata<any>,

package/src/config/config-service.interface.d.mts

@@ -0,0 +1,39 @@
+import type { Path, PathValue } from './types.mjs';
+/**
+ * Interface for configuration service implementations.
+ *
+ * Provides type-safe access to configuration values with support for nested paths.
+ *
+ * @typeParam Config - The configuration object type
+ */
+export interface ConfigServiceInterface<Config = Record<string, unknown>> {
+    /**
+     * Gets the entire configuration object.
+     */
+    getConfig: () => Config;
+    /**
+     * Gets a configuration value by key path. Returns `null` if not found.
+     *
+     * @param key - Dot-separated path to the configuration value (e.g., 'database.host')
+     * @returns The configuration value or `null` if not found
+     */
+    get: <Key extends Path<Config>>(key: Key) => PathValue<Config, Key> | null;
+    /**
+     * Gets a configuration value by key path, or returns a default value if not found.
+     *
+     * @param key - Dot-separated path to the configuration value
+     * @param defaultValue - Default value to return if the key is not found
+     * @returns The configuration value or the default value
+     */
+    getOrDefault: <Key extends Path<Config>>(key: Key, defaultValue: PathValue<Config, Key>) => PathValue<Config, Key>;
+    /**
+     * Gets a configuration value by key path, or throws an error if not found.
+     *
+     * @param key - Dot-separated path to the configuration value
+     * @param errorMessage - Optional custom error message
+     * @returns The configuration value
+     * @throws Error if the key is not found
+     */
+    getOrThrow: <Key extends Path<Config>>(key: Key, errorMessage?: string) => PathValue<Config, Key>;
+}
+//# sourceMappingURL=config-service.interface.d.mts.map

package/src/config/config-service.interface.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-service.interface.d.mts","sourceRoot":"","sources":["config-service.interface.mts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAElD;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACtE;;OAEG;IACH,SAAS,EAAE,MAAM,MAAM,CAAA;IACvB;;;;;OAKG;IACH,GAAG,EAAE,CAAC,GAAG,SAAS,IAAI,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,GAAG,KAAK,SAAS,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAA;IAE1E;;;;;;OAMG;IACH,YAAY,EAAE,CAAC,GAAG,SAAS,IAAI,CAAC,MAAM,CAAC,EACrC,GAAG,EAAE,GAAG,EACR,YAAY,EAAE,SAAS,CAAC,MAAM,EAAE,GAAG,CAAC,KACjC,SAAS,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAE3B;;;;;;;OAOG;IACH,UAAU,EAAE,CAAC,GAAG,SAAS,IAAI,CAAC,MAAM,CAAC,EACnC,GAAG,EAAE,GAAG,EACR,YAAY,CAAC,EAAE,MAAM,KAClB,SAAS,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAC5B"}

package/src/config/config-service.interface.mts

@@ -1,14 +1,45 @@
 import type { Path, PathValue } from './types.mjs'
 
+/**
+ * Interface for configuration service implementations.
+ * 
+ * Provides type-safe access to configuration values with support for nested paths.
+ * 
+ * @typeParam Config - The configuration object type
+ */
 export interface ConfigServiceInterface<Config = Record<string, unknown>> {
+  /**
+   * Gets the entire configuration object.
+   */
   getConfig: () => Config
+  /**
+   * Gets a configuration value by key path. Returns `null` if not found.
+   * 
+   * @param key - Dot-separated path to the configuration value (e.g., 'database.host')
+   * @returns The configuration value or `null` if not found
+   */
   get: <Key extends Path<Config>>(key: Key) => PathValue<Config, Key> | null
 
+  /**
+   * Gets a configuration value by key path, or returns a default value if not found.
+   * 
+   * @param key - Dot-separated path to the configuration value
+   * @param defaultValue - Default value to return if the key is not found
+   * @returns The configuration value or the default value
+   */
   getOrDefault: <Key extends Path<Config>>(
     key: Key,
     defaultValue: PathValue<Config, Key>,
   ) => PathValue<Config, Key>
 
+  /**
+   * Gets a configuration value by key path, or throws an error if not found.
+   * 
+   * @param key - Dot-separated path to the configuration value
+   * @param errorMessage - Optional custom error message
+   * @returns The configuration value
+   * @throws Error if the key is not found
+   */
   getOrThrow: <Key extends Path<Config>>(
     key: Key,
     errorMessage?: string,