@navios/core 0.5.1 → 0.7.0

package/src/config/config.provider.d.mts

@@ -0,0 +1,46 @@
+import { FactoryInjectionToken } from '@navios/di';
+import { z } from 'zod/v4';
+import type { ConfigServiceOptions } from './config.service.mjs';
+import { ConfigService, ConfigServiceOptionsSchema } from './config.service.mjs';
+/**
+ * Schema for configuration provider options.
+ */
+export declare const ConfigProviderOptions: z.ZodObject<{
+    load: z.ZodFunction<z.core.$ZodFunctionArgs, z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+/**
+ * Creates a factory injection token for ConfigService that loads configuration asynchronously.
+ *
+ * Use this when you need to load configuration from a file, database, or other async source.
+ *
+ * @param options - Configuration provider options
+ * @param options.load - Async function that loads and returns the configuration object
+ * @returns A factory injection token for ConfigService
+ *
+ * @example
+ * ```typescript
+ * const MyConfigService = provideConfig({
+ *   load: async () => {
+ *     const config = await loadConfigFromFile('config.json')
+ *     return config
+ *   },
+ * })
+ *
+ * // Use in module setup
+ * container.bind(ConfigServiceToken).toFactory(configProvider)
+ * ```
+ */
+export declare function provideConfig<ConfigMap extends ConfigServiceOptions>(options: z.input<typeof ConfigProviderOptions>): FactoryInjectionToken<ConfigService<ConfigMap>, typeof ConfigServiceOptionsSchema>;
+/**
+ * Pre-configured ConfigService provider that uses environment variables.
+ *
+ * Provides a ConfigService instance bound to `process.env`.
+ *
+ * @example
+ * ```typescript
+ * // Use environment variables as configuration
+ * container.bind(ConfigServiceToken).toValue(EnvConfigProvider)
+ * ```
+ */
+export declare const EnvConfigProvider: import("@navios/di").BoundInjectionToken<ConfigService<Record<string, string>>, z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+//# sourceMappingURL=config.provider.d.mts.map

package/src/config/config.provider.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.provider.d.mts","sourceRoot":"","sources":["config.provider.mts"],"names":[],"mappings":"AAEA,OAAO,EAAE,qBAAqB,EAAkB,MAAM,YAAY,CAAA;AAElE,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAA;AAE1B,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAA;AAEhE,OAAO,EACL,aAAa,EACb,0BAA0B,EAE3B,MAAM,sBAAsB,CAAA;AAE7B;;GAEG;AACH,eAAO,MAAM,qBAAqB;;iBAEhC,CAAA;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,CAAC,SAAS,SAAS,oBAAoB,EAClE,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,GAC7C,qBAAqB,CACtB,aAAa,CAAC,SAAS,CAAC,EACxB,OAAO,0BAA0B,CAClC,CAEA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,yHAK5B,CAAA"}

package/src/config/config.provider.mts

@@ -12,10 +12,35 @@ import {
   ConfigServiceToken,
 } from './config.service.mjs'
 
+/**
+ * Schema for configuration provider options.
+ */
 export const ConfigProviderOptions = z.object({
   load: z.function({ output: ConfigServiceOptionsSchema }),
 })
 
+/**
+ * Creates a factory injection token for ConfigService that loads configuration asynchronously.
+ *
+ * Use this when you need to load configuration from a file, database, or other async source.
+ *
+ * @param options - Configuration provider options
+ * @param options.load - Async function that loads and returns the configuration object
+ * @returns A factory injection token for ConfigService
+ *
+ * @example
+ * ```typescript
+ * const MyConfigService = provideConfig({
+ *   load: async () => {
+ *     const config = await loadConfigFromFile('config.json')
+ *     return config
+ *   },
+ * })
+ *
+ * // Use in module setup
+ * container.bind(ConfigServiceToken).toFactory(configProvider)
+ * ```
+ */
 export function provideConfig<ConfigMap extends ConfigServiceOptions>(
   options: z.input<typeof ConfigProviderOptions>,
 ): FactoryInjectionToken<
@@ -25,6 +50,17 @@ export function provideConfig<ConfigMap extends ConfigServiceOptions>(
   return InjectionToken.factory(ConfigServiceToken, async () => options.load())
 }
 
+/**
+ * Pre-configured ConfigService provider that uses environment variables.
+ *
+ * Provides a ConfigService instance bound to `process.env`.
+ *
+ * @example
+ * ```typescript
+ * // Use environment variables as configuration
+ * container.bind(ConfigServiceToken).toValue(EnvConfigProvider)
+ * ```
+ */
 export const EnvConfigProvider = InjectionToken.bound<
   ConfigService<Record<string, string>>,
   typeof ConfigServiceOptionsSchema

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

@@ -0,0 +1,108 @@
+import { InjectionToken } from '@navios/di';
+import { z } from 'zod/v4';
+import type { ConfigServiceInterface as IConfigService } from './config-service.interface.mjs';
+import type { Path, PathValue } from './types.mjs';
+/**
+ * Schema for validating configuration service options.
+ */
+export declare const ConfigServiceOptionsSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+/**
+ * Type for configuration service options.
+ */
+export type ConfigServiceOptions = z.infer<typeof ConfigServiceOptionsSchema>;
+/**
+ * Injection token for ConfigService.
+ */
+export declare const ConfigServiceToken: InjectionToken<IConfigService<Record<string, unknown>>, z.ZodRecord<z.ZodString, z.ZodUnknown>, true>;
+/**
+ * Service for managing application configuration with type-safe access.
+ *
+ * Provides methods to access configuration values using dot-notation paths
+ * with full TypeScript type inference.
+ *
+ * @typeParam Config - The configuration object type
+ *
+ * @example
+ * ```typescript
+ * interface AppConfig {
+ *   database: {
+ *     host: string
+ *     port: number
+ *   }
+ *   api: {
+ *     timeout: number
+ *   }
+ * }
+ *
+ * @Injectable()
+ * export class DatabaseService {
+ *   private config = inject(MyConfigService)
+ *
+ *   connect() {
+ *     const host = this.config.getOrThrow('database.host')
+ *     const port = this.config.getOrDefault('database.port', 5432)
+ *     // host is typed as string, port is typed as number
+ *   }
+ * }
+ * ```
+ */
+export declare class ConfigService<Config extends ConfigServiceOptions = Record<string, unknown>> implements IConfigService<Config> {
+    private config;
+    private readonly logger;
+    /**
+     * Creates a new ConfigService instance.
+     *
+     * @param config - The configuration object
+     */
+    constructor(config?: Config);
+    /**
+     * Gets the entire configuration object.
+     *
+     * @returns The complete configuration object
+     */
+    getConfig(): Config;
+    /**
+     * Gets a configuration value by key path.
+     *
+     * Returns `null` if the key is not found or if any part of the path is invalid.
+     *
+     * @param key - Dot-separated path to the configuration value (e.g., 'database.host')
+     * @returns The configuration value or `null` if not found
+     *
+     * @example
+     * ```typescript
+     * const host = config.get('database.host') // string | null
+     * const port = config.get('database.port') // number | null
+     * ```
+     */
+    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
+     *
+     * @example
+     * ```typescript
+     * const port = config.getOrDefault('database.port', 5432) // number
+     * ```
+     */
+    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
+     *
+     * @example
+     * ```typescript
+     * const host = config.getOrThrow('database.host') // string (throws if not found)
+     * const apiKey = config.getOrThrow('api.key', 'API key is required') // string
+     * ```
+     */
+    getOrThrow<Key extends Path<Config>>(key: Key, errorMessage?: string): PathValue<Config, Key>;
+}
+//# sourceMappingURL=config.service.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"config.service.d.mts","sourceRoot":"","sources":["config.service.mts"],"names":[],"mappings":"AACA,OAAO,EAAsB,cAAc,EAAE,MAAM,YAAY,CAAA;AAE/D,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAA;AAE1B,OAAO,KAAK,EAAE,sBAAsB,IAAI,cAAc,EAAE,MAAM,gCAAgC,CAAA;AAC9F,OAAO,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAIlD;;GAEG;AACH,eAAO,MAAM,0BAA0B,wCAAoC,CAAA;AAC3E;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAA;AAE7E;;GAEG;AACH,eAAO,MAAM,kBAAkB,uGAG2B,CAAA;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qBAGa,aAAa,CACxB,MAAM,SAAS,oBAAoB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAC7D,YAAW,cAAc,CAAC,MAAM,CAAC;IAUrB,OAAO,CAAC,MAAM;IAT1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAErB;IAEF;;;;OAIG;gBACiB,MAAM,GAAE,MAAqB;IAEjD;;;;OAIG;IACH,SAAS,IAAI,MAAM;IAInB;;;;;;;;;;;;;OAaG;IACH,GAAG,CAAC,GAAG,SAAS,IAAI,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,GAAG,GAAG,SAAS,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI;IA0BtE;;;;;;;;;;;OAWG;IACH,YAAY,CAAC,GAAG,SAAS,IAAI,CAAC,MAAM,CAAC,EACnC,GAAG,EAAE,GAAG,EACR,YAAY,EAAE,SAAS,CAAC,MAAM,EAAE,GAAG,CAAC,GACnC,SAAS,CAAC,MAAM,EAAE,GAAG,CAAC;IAKzB;;;;;;;;;;;;;OAaG;IACH,UAAU,CAAC,GAAG,SAAS,IAAI,CAAC,MAAM,CAAC,EACjC,GAAG,EAAE,GAAG,EACR,YAAY,CAAC,EAAE,MAAM,GACpB,SAAS,CAAC,MAAM,EAAE,GAAG,CAAC;CAa1B"}

package/src/config/config.service.mts

@@ -1,4 +1,4 @@
-import { NaviosException } from '@navios/builder'
+import { NaviosError } from '@navios/builder'
 import { inject, Injectable, InjectionToken } from '@navios/di'
 
 import { z } from 'zod/v4'
@@ -8,31 +8,95 @@ import type { Path, PathValue } from './types.mjs'
 
 import { Logger } from '../logger/index.mjs'
 
+/**
+ * Schema for validating configuration service options.
+ */
 export const ConfigServiceOptionsSchema = z.record(z.string(), z.unknown())
+/**
+ * Type for configuration service options.
+ */
 export type ConfigServiceOptions = z.infer<typeof ConfigServiceOptionsSchema>
 
+/**
+ * Injection token for ConfigService.
+ */
 export const ConfigServiceToken = InjectionToken.create<
   IConfigService,
   typeof ConfigServiceOptionsSchema
 >(Symbol.for('ConfigService'), ConfigServiceOptionsSchema)
 
+/**
+ * Service for managing application configuration with type-safe access.
+ *
+ * Provides methods to access configuration values using dot-notation paths
+ * with full TypeScript type inference.
+ *
+ * @typeParam Config - The configuration object type
+ *
+ * @example
+ * ```typescript
+ * interface AppConfig {
+ *   database: {
+ *     host: string
+ *     port: number
+ *   }
+ *   api: {
+ *     timeout: number
+ *   }
+ * }
+ *
+ * @Injectable()
+ * export class DatabaseService {
+ *   private config = inject(MyConfigService)
+ *
+ *   connect() {
+ *     const host = this.config.getOrThrow('database.host')
+ *     const port = this.config.getOrDefault('database.port', 5432)
+ *     // host is typed as string, port is typed as number
+ *   }
+ * }
+ * ```
+ */
 @Injectable({
   token: ConfigServiceToken,
 })
 export class ConfigService<
   Config extends ConfigServiceOptions = Record<string, unknown>,
-> implements IConfigService<Config>
-{
+> implements IConfigService<Config> {
   private readonly logger = inject(Logger, {
     context: ConfigService.name,
   })
 
+  /**
+   * Creates a new ConfigService instance.
+   *
+   * @param config - The configuration object
+   */
   constructor(private config: Config = {} as Config) {}
 
+  /**
+   * Gets the entire configuration object.
+   *
+   * @returns The complete configuration object
+   */
   getConfig(): Config {
     return this.config
   }
 
+  /**
+   * Gets a configuration value by key path.
+   *
+   * Returns `null` if the key is not found or if any part of the path is invalid.
+   *
+   * @param key - Dot-separated path to the configuration value (e.g., 'database.host')
+   * @returns The configuration value or `null` if not found
+   *
+   * @example
+   * ```typescript
+   * const host = config.get('database.host') // string | null
+   * const port = config.get('database.port') // number | null
+   * ```
+   */
   get<Key extends Path<Config>>(key: Key): PathValue<Config, Key> | null {
     try {
       const parts = String(key).split('.')
@@ -59,6 +123,18 @@ export class ConfigService<
     }
   }
 
+  /**
+   * 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
+   *
+   * @example
+   * ```typescript
+   * const port = config.getOrDefault('database.port', 5432) // number
+   * ```
+   */
   getOrDefault<Key extends Path<Config>>(
     key: Key,
     defaultValue: PathValue<Config, Key>,
@@ -67,6 +143,20 @@ export class ConfigService<
     return value !== null ? value : defaultValue
   }
 
+  /**
+   * 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
+   *
+   * @example
+   * ```typescript
+   * const host = config.getOrThrow('database.host') // string (throws if not found)
+   * const apiKey = config.getOrThrow('api.key', 'API key is required') // string
+   * ```
+   */
   getOrThrow<Key extends Path<Config>>(
     key: Key,
     errorMessage?: string,
@@ -78,7 +168,7 @@ export class ConfigService<
         errorMessage ||
         `Configuration value for key "${String(key)}" is not defined`
       this.logger.error(message)
-      throw new NaviosException(message)
+      throw new NaviosError(message)
     }
 
     return value

package/src/config/index.d.mts

@@ -0,0 +1,6 @@
+export * from './utils/index.mjs';
+export * from './config.provider.mjs';
+export * from './config.service.mjs';
+export * from './config-service.interface.mjs';
+export * from './types.mjs';
+//# sourceMappingURL=index.d.mts.map

package/src/config/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["index.mts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAA;AACjC,cAAc,uBAAuB,CAAA;AACrC,cAAc,sBAAsB,CAAA;AACpC,cAAc,gCAAgC,CAAA;AAC9C,cAAc,aAAa,CAAA"}

package/src/config/types.d.mts

@@ -0,0 +1,13 @@
+/**
+ * Evaluates to `true` if `T` is `any`. `false` otherwise.
+ * (c) https://stackoverflow.com/a/68633327/5290447
+ */
+type IsAny<T> = unknown extends T ? [keyof T] extends [never] ? false : true : false;
+type ExcludedParts = 'services' | 'mailer' | 'aws' | 'computedTimeRates' | 'aiModelsRates';
+type ExcludedKeys = 'computedTimeRates' | 'aiModelsRates' | 'aiModel';
+export type PathImpl<T, Key extends keyof T> = Key extends string ? Key extends ExcludedKeys ? never : IsAny<T[Key]> extends true ? never : T[Key] extends string ? never : T[Key] extends any[] ? never : T[Key] extends Record<string, any> ? Key extends ExcludedParts ? `${Key}.${Exclude<keyof T[Key], keyof any[]> & string}` : `${Key}.${PathImpl<T[Key], Exclude<keyof T[Key], keyof any[]>> & string}` | `${Key}.${Exclude<keyof T[Key], keyof any[]> & string}` : never : never;
+export type PathImpl2<T> = PathImpl<T, keyof T> | keyof T;
+export type Path<T> = keyof T extends string ? PathImpl2<T> extends infer P ? P extends string | keyof T ? P : keyof T : keyof T : never;
+export type PathValue<T, P extends Path<T>> = P extends `${infer Key}.${infer Rest}` ? Key extends keyof T ? Rest extends Path<T[Key]> ? PathValue<T[Key], Rest> : never : never : P extends keyof T ? T[P] : never;
+
+//# sourceMappingURL=types.d.mts.map

package/src/config/types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.mts","sourceRoot":"","sources":["types.mts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,KAAK,KAAK,CAAC,CAAC,IAAI,OAAO,SAAS,CAAC,GAC7B,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GACvB,KAAK,GACL,IAAI,GACN,KAAK,CAAA;AAET,KAAK,aAAa,GACd,UAAU,GACV,QAAQ,GACR,KAAK,GACL,mBAAmB,GACnB,eAAe,CAAA;AACnB,KAAK,YAAY,GAAG,mBAAmB,GAAG,eAAe,GAAG,SAAS,CAAA;AAErE,MAAM,MAAM,QAAQ,CAAC,CAAC,EAAE,GAAG,SAAS,MAAM,CAAC,IAAI,GAAG,SAAS,MAAM,GAC7D,GAAG,SAAS,YAAY,GACtB,KAAK,GACL,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,SAAS,IAAI,GACxB,KAAK,GACL,CAAC,CAAC,GAAG,CAAC,SAAS,MAAM,GACnB,KAAK,GACL,CAAC,CAAC,GAAG,CAAC,SAAS,GAAG,EAAE,GAClB,KAAK,GACL,CAAC,CAAC,GAAG,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAChC,GAAG,SAAS,aAAa,GACvB,GAAG,GAAG,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,EAAE,CAAC,GAAG,MAAM,EAAE,GAEnD,GAAG,GAAG,IAAI,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,EAAE,CAAC,CAAC,GAAG,MAAM,EAAE,GACzE,GAAG,GAAG,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,EAAE,CAAC,GAAG,MAAM,EAAE,GAC7D,KAAK,GACf,KAAK,CAAA;AAET,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,GAAG,MAAM,CAAC,CAAA;AAEzD,MAAM,MAAM,IAAI,CAAC,CAAC,IAAI,MAAM,CAAC,SAAS,MAAM,GACxC,SAAS,CAAC,CAAC,CAAC,SAAS,MAAM,CAAC,GAC1B,CAAC,SAAS,MAAM,GAAG,MAAM,CAAC,GACxB,CAAC,GACD,MAAM,CAAC,GACT,MAAM,CAAC,GACT,KAAK,CAAA;AAET,MAAM,MAAM,SAAS,CACnB,CAAC,EACD,CAAC,SAAS,IAAI,CAAC,CAAC,CAAC,IACf,CAAC,SAAS,GAAG,MAAM,GAAG,IAAI,MAAM,IAAI,EAAE,GACtC,GAAG,SAAS,MAAM,CAAC,GACjB,IAAI,SAAS,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GACvB,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,GACvB,KAAK,GACP,KAAK,GACP,CAAC,SAAS,MAAM,CAAC,GACf,CAAC,CAAC,CAAC,CAAC,GACJ,KAAK,CAAA"}

package/src/config/utils/helpers.d.mts

@@ -0,0 +1,3 @@
+export declare function envInt(key: keyof NodeJS.ProcessEnv, defaultValue: number): number;
+export declare function envString<DefaultValue extends string | undefined, Ensured = DefaultValue extends string ? true : false>(key: keyof NodeJS.ProcessEnv, defaultValue?: DefaultValue): Ensured extends true ? string : string | undefined;
+//# sourceMappingURL=helpers.d.mts.map

package/src/config/utils/helpers.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.mts","sourceRoot":"","sources":["helpers.mts"],"names":[],"mappings":"AAEA,wBAAgB,MAAM,CACpB,GAAG,EAAE,MAAM,MAAM,CAAC,UAAU,EAC5B,YAAY,EAAE,MAAM,GACnB,MAAM,CAIR;AAED,wBAAgB,SAAS,CACvB,YAAY,SAAS,MAAM,GAAG,SAAS,EACvC,OAAO,GAAG,YAAY,SAAS,MAAM,GAAG,IAAI,GAAG,KAAK,EAEpD,GAAG,EAAE,MAAM,MAAM,CAAC,UAAU,EAC5B,YAAY,CAAC,EAAE,YAAY,GAC1B,OAAO,SAAS,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAKpD"}

package/src/config/utils/index.d.mts

@@ -0,0 +1,2 @@
+export * from './helpers.mjs';
+//# sourceMappingURL=index.d.mts.map

package/src/config/utils/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["index.mts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAA"}

package/src/decorators/controller.decorator.d.mts

@@ -0,0 +1,33 @@
+import type { ClassType } from '@navios/di';
+/**
+ * Options for configuring a Navios controller.
+ */
+export interface ControllerOptions {
+    /**
+     * Guards to apply to all endpoints in this controller.
+     * Guards are executed in reverse order (last guard first).
+     */
+    guards?: ClassType[] | Set<ClassType>;
+}
+/**
+ * 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] })
+ * export class UserController {
+ *   @Endpoint(getUserEndpoint)
+ *   async getUser(request: EndpointParams<typeof getUserEndpoint>) {
+ *     // Handle request
+ *   }
+ * }
+ * ```
+ */
+export declare function Controller({ guards }?: ControllerOptions): (target: ClassType, context: ClassDecoratorContext) => ClassType;
+//# sourceMappingURL=controller.decorator.d.mts.map

package/src/decorators/controller.decorator.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller.decorator.d.mts","sourceRoot":"","sources":["controller.decorator.mts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAM3C;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,EAAE,GAAG,GAAG,CAAC,SAAS,CAAC,CAAA;CACtC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,UAAU,CAAC,EAAE,MAAM,EAAE,GAAE,iBAAsB,IAC1C,QAAQ,SAAS,EAAE,SAAS,qBAAqB,eAoBnE"}

package/src/decorators/controller.decorator.mts

@@ -4,9 +4,37 @@ import { Injectable, InjectableScope, InjectionToken } from '@navios/di'
 
 import { getControllerMetadata } from '../metadata/index.mjs'
 
+/**
+ * Options for configuring a Navios controller.
+ */
 export interface ControllerOptions {
+  /**
+   * Guards to apply to all endpoints in this controller.
+   * Guards are executed in reverse order (last guard first).
+   */
   guards?: ClassType[] | Set<ClassType>
 }
+
+/**
+ * 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] })
+ * export class UserController {
+ *   @Endpoint(getUserEndpoint)
+ *   async getUser(request: EndpointParams<typeof getUserEndpoint>) {
+ *     // Handle request
+ *   }
+ * }
+ * ```
+ */
 export function Controller({ guards }: ControllerOptions = {}) {
   return function (target: ClassType, context: ClassDecoratorContext) {
     if (context.kind !== 'class') {

package/src/decorators/endpoint.decorator.d.mts

@@ -0,0 +1,89 @@
+import type { BaseEndpointConfig, EndpointFunctionArgs, HttpMethod, Util_FlatObject } from '@navios/builder';
+import type { z, ZodType } from 'zod/v4';
+import { ZodDiscriminatedUnion } from 'zod/v4';
+/**
+ * Extracts the typed parameters for an endpoint handler function.
+ *
+ * This utility type extracts URL parameters, query parameters, and request body
+ * from an endpoint declaration and flattens them into a single object.
+ *
+ * @typeParam EndpointDeclaration - The endpoint declaration from @navios/builder
+ *
+ * @example
+ * ```typescript
+ * const getUserEndpoint = api.declareEndpoint({
+ *   method: 'get',
+ *   url: '/users/$userId',
+ *   querySchema: z.object({ include: z.string().optional() }),
+ *   responseSchema: z.object({ id: z.string(), name: z.string() }),
+ * })
+ *
+ * @Endpoint(getUserEndpoint)
+ * async getUser(request: EndpointParams<typeof getUserEndpoint>) {
+ *   // request.urlParams.userId is typed as string
+ *   // request.query.include is typed as string | undefined
+ * }
+ * ```
+ */
+export type EndpointParams<EndpointDeclaration extends {
+    config: BaseEndpointConfig<any, any, any, any, any>;
+}, Url extends string = EndpointDeclaration['config']['url'], QuerySchema = EndpointDeclaration['config']['querySchema']> = QuerySchema extends ZodType ? EndpointDeclaration['config']['requestSchema'] extends ZodType ? Util_FlatObject<EndpointFunctionArgs<Url, QuerySchema, EndpointDeclaration['config']['requestSchema'], true>> : Util_FlatObject<EndpointFunctionArgs<Url, QuerySchema, undefined, true>> : EndpointDeclaration['config']['requestSchema'] extends ZodType ? Util_FlatObject<EndpointFunctionArgs<Url, undefined, EndpointDeclaration['config']['requestSchema'], true>> : Util_FlatObject<EndpointFunctionArgs<Url, undefined, undefined, true>>;
+/**
+ * Extracts the typed return value for an endpoint handler function.
+ *
+ * This utility type extracts the response schema from an endpoint declaration
+ * and returns the appropriate Promise type.
+ *
+ * @typeParam EndpointDeclaration - The endpoint declaration from @navios/builder
+ *
+ * @example
+ * ```typescript
+ * const getUserEndpoint = api.declareEndpoint({
+ *   method: 'get',
+ *   url: '/users/$userId',
+ *   responseSchema: z.object({ id: z.string(), name: z.string() }),
+ * })
+ *
+ * @Endpoint(getUserEndpoint)
+ * async getUser(request: EndpointParams<typeof getUserEndpoint>): EndpointResult<typeof getUserEndpoint> {
+ *   return { id: '1', name: 'John' } // Type-checked against responseSchema
+ * }
+ * ```
+ */
+export type EndpointResult<EndpointDeclaration extends {
+    config: BaseEndpointConfig<any, any, any, any, any>;
+}> = EndpointDeclaration['config']['responseSchema'] extends ZodDiscriminatedUnion<infer Options> ? Promise<z.input<Options[number]>> : Promise<z.input<EndpointDeclaration['config']['responseSchema']>>;
+/**
+ * Decorator that marks a method as an HTTP endpoint.
+ *
+ * The endpoint must be defined using @navios/builder's `declareEndpoint` method.
+ * This ensures type safety and consistency between client and server.
+ *
+ * @param endpoint - The endpoint declaration from @navios/builder
+ * @returns A method decorator
+ *
+ * @example
+ * ```typescript
+ * import { builder } from '@navios/builder'
+ *
+ * const api = builder()
+ * const getUserEndpoint = api.declareEndpoint({
+ *   method: 'get',
+ *   url: '/users/$userId',
+ *   responseSchema: z.object({ id: z.string(), name: z.string() }),
+ * })
+ *
+ * @Controller()
+ * export class UserController {
+ *   @Endpoint(getUserEndpoint)
+ *   async getUser(request: EndpointParams<typeof getUserEndpoint>) {
+ *     const { userId } = request.urlParams
+ *     return { id: userId, name: 'John' }
+ *   }
+ * }
+ * ```
+ */
+export declare function Endpoint<Method extends HttpMethod = HttpMethod, Url extends string = string, QuerySchema = undefined, ResponseSchema extends ZodType = ZodType, RequestSchema = ZodType>(endpoint: {
+    config: BaseEndpointConfig<Method, Url, QuerySchema, ResponseSchema, RequestSchema>;
+}): (target: (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) => (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>>;
+//# sourceMappingURL=endpoint.decorator.d.mts.map

package/src/decorators/endpoint.decorator.d.mts.map

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