@navios/core 0.6.0 → 0.7.0

package/src/interfaces/abstract-execution-context.inteface.mts

@@ -4,10 +4,45 @@ import type {
   ModuleMetadata,
 } from '../metadata/index.mjs'
 
+/**
+ * Interface providing access to the execution context during request handling.
+ * 
+ * The execution context provides access to metadata and request/reply objects
+ * for the current request. It is available in guards and can be injected into
+ * services if needed.
+ * 
+ * @example
+ * ```typescript
+ * @Injectable()
+ * export class AuthGuard implements CanActivate {
+ *   async canActivate(context: AbstractExecutionContext): Promise<boolean> {
+ *     const request = context.getRequest()
+ *     const handler = context.getHandler()
+ *     // Access request and handler metadata
+ *     return true
+ *   }
+ * }
+ * ```
+ */
 export interface AbstractExecutionContext {
+  /**
+   * Gets the metadata for the module containing the current endpoint.
+   */
   getModule(): ModuleMetadata
+  /**
+   * Gets the metadata for the controller containing the current endpoint.
+   */
   getController(): ControllerMetadata
+  /**
+   * Gets the metadata for the current endpoint handler.
+   */
   getHandler(): HandlerMetadata
+  /**
+   * Gets the HTTP request object (adapter-specific).
+   */
   getRequest(): any
+  /**
+   * Gets the HTTP reply object (adapter-specific).
+   */
   getReply(): any
 }

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

@@ -0,0 +1,15 @@
+import type { ModuleMetadata } from '../metadata/index.mjs';
+import type { AbstractHttpCorsOptions } from './abstract-http-cors-options.interface.mjs';
+import type { AbstractHttpListenOptions } from './abstract-http-listen-options.interface.mjs';
+export interface AbstractHttpAdapterInterface<ServerInstance, CorsOptions = AbstractHttpCorsOptions, Options = {}, MultipartOptions = {}> {
+    setupHttpServer(options: Options): Promise<void>;
+    onModulesInit(modules: Map<string, ModuleMetadata>): Promise<void>;
+    ready(): Promise<void>;
+    getServer(): ServerInstance;
+    setGlobalPrefix(prefix: string): void;
+    enableCors(options: CorsOptions): void;
+    enableMultipart(options: MultipartOptions): void;
+    listen(options: AbstractHttpListenOptions): Promise<string>;
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=abstract-http-adapter.interface.d.mts.map

package/src/interfaces/abstract-http-adapter.interface.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abstract-http-adapter.interface.d.mts","sourceRoot":"","sources":["abstract-http-adapter.interface.mts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAC3D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,4CAA4C,CAAA;AACzF,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,8CAA8C,CAAA;AAE7F,MAAM,WAAW,4BAA4B,CAC3C,cAAc,EACd,WAAW,GAAG,uBAAuB,EACrC,OAAO,GAAG,EAAE,EACZ,gBAAgB,GAAG,EAAE;IAErB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAChD,aAAa,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAClE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACtB,SAAS,IAAI,cAAc,CAAA;IAC3B,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrC,UAAU,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAAA;IACtC,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI,CAAA;IAChD,MAAM,CAAC,OAAO,EAAE,yBAAyB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAC3D,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACzB"}

package/src/interfaces/abstract-http-cors-options.interface.d.mts

@@ -0,0 +1,58 @@
+import type { LogLevel } from '../logger/index.mjs';
+interface ArrayOfValueOrArray<T> extends Array<ValueOrArray<T>> {
+}
+type OriginType = string | boolean | RegExp;
+type ValueOrArray<T> = T | ArrayOfValueOrArray<T>;
+export interface AbstractHttpCorsOptions {
+    /**
+     * Configures the Access-Control-Allow-Origin CORS header.
+     */
+    origin?: ValueOrArray<OriginType>;
+    /**
+     * Configures the Access-Control-Allow-Credentials CORS header.
+     * Set to true to pass the header, otherwise it is omitted.
+     */
+    credentials?: boolean;
+    /**
+     * Configures the Access-Control-Expose-Headers CORS header.
+     * Expects a comma-delimited string (ex: 'Content-Range,X-Content-Range')
+     * or an array (ex: ['Content-Range', 'X-Content-Range']).
+     * If not specified, no custom headers are exposed.
+     */
+    exposedHeaders?: string | string[];
+    /**
+     * Configures the Access-Control-Allow-Headers CORS header.
+     * Expects a comma-delimited string (ex: 'Content-Type,Authorization')
+     * or an array (ex: ['Content-Type', 'Authorization']). If not
+     * specified, defaults to reflecting the headers specified in the
+     * request's Access-Control-Request-Headers header.
+     */
+    allowedHeaders?: string | string[];
+    /**
+     * Configures the Access-Control-Allow-Methods CORS header.
+     * Expects a comma-delimited string (ex: 'GET,PUT,POST') or an array (ex: ['GET', 'PUT', 'POST']).
+     */
+    methods?: string | string[];
+    /**
+     * Configures the Access-Control-Max-Age CORS header.
+     * Set to an integer to pass the header, otherwise it is omitted.
+     */
+    maxAge?: number;
+    /**
+     * Configures the Cache-Control header for CORS preflight responses.
+     * Set to an integer to pass the header as `Cache-Control: max-age=${cacheControl}`,
+     * or set to a string to pass the header as `Cache-Control: ${cacheControl}` (fully define
+     * the header value), otherwise the header is omitted.
+     */
+    cacheControl?: number | string;
+    /**
+     * Sets the Fastify log level specifically for the internal OPTIONS route
+     * used to handle CORS preflight requests. For example, setting this to `'silent'`
+     * will prevent these requests from being logged.
+     * Useful for reducing noise in application logs.
+     * Default: inherits Fastify's global log level.
+     */
+    logLevel?: LogLevel;
+}
+
+//# sourceMappingURL=abstract-http-cors-options.interface.d.mts.map

package/src/interfaces/abstract-http-cors-options.interface.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abstract-http-cors-options.interface.d.mts","sourceRoot":"","sources":["abstract-http-cors-options.interface.mts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAEnD,UAAU,mBAAmB,CAAC,CAAC,CAAE,SAAQ,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;CAAG;AAElE,KAAK,UAAU,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAAA;AAC3C,KAAK,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,mBAAmB,CAAC,CAAC,CAAC,CAAA;AAEjD,MAAM,WAAW,uBAAuB;IACtC;;OAEG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC,UAAU,CAAC,CAAA;IACjC;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IAClC;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IAClC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IAC3B;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IAE9B;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAA;CACpB"}

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

@@ -0,0 +1,7 @@
+import type { ClassType, ScopedContainer } from '@navios/di';
+import type { HandlerMetadata } from '../metadata/index.mjs';
+export interface AbstractHttpHandlerAdapterInterface {
+    prepareArguments?: (handlerMetadata: HandlerMetadata<any>) => ((target: Record<string, any>, request: any) => Promise<void> | void)[];
+    provideHandler: (controller: ClassType, handlerMetadata: HandlerMetadata<any>) => (context: ScopedContainer, request: any, reply: any) => Promise<any>;
+}
+//# sourceMappingURL=abstract-http-handler-adapter.interface.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"abstract-http-handler-adapter.interface.d.mts","sourceRoot":"","sources":["abstract-http-handler-adapter.interface.mts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAE5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAE5D,MAAM,WAAW,mCAAmC;IAClD,gBAAgB,CAAC,EAAE,CACjB,eAAe,EAAE,eAAe,CAAC,GAAG,CAAC,KAClC,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,OAAO,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,EAAE,CAAA;IAC5E,cAAc,EAAE,CACd,UAAU,EAAE,SAAS,EACrB,eAAe,EAAE,eAAe,CAAC,GAAG,CAAC,KAClC,CAAC,OAAO,EAAE,eAAe,EAAE,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,CAAA;CAC1E"}

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

@@ -1,4 +1,4 @@
-import type { ClassType, RequestContextHolder } from '@navios/di'
+import type { ClassType, ScopedContainer } from '@navios/di'
 
 import type { HandlerMetadata } from '../metadata/index.mjs'
 
@@ -9,5 +9,5 @@ export interface AbstractHttpHandlerAdapterInterface {
   provideHandler: (
     controller: ClassType,
     handlerMetadata: HandlerMetadata<any>,
-  ) => (context: RequestContextHolder, request: any, reply: any) => Promise<any>
+  ) => (context: ScopedContainer, request: any, reply: any) => Promise<any>
 }

package/src/interfaces/abstract-http-listen-options.interface.d.mts

@@ -0,0 +1,5 @@
+export interface AbstractHttpListenOptions {
+    port: number;
+    host?: string;
+}
+//# sourceMappingURL=abstract-http-listen-options.interface.d.mts.map

package/src/interfaces/abstract-http-listen-options.interface.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abstract-http-listen-options.interface.d.mts","sourceRoot":"","sources":["abstract-http-listen-options.interface.mts"],"names":[],"mappings":"AAAA,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,CAAA;CACd"}

package/src/interfaces/can-activate.d.mts

@@ -0,0 +1,36 @@
+import type { AbstractExecutionContext } from '../interfaces/index.mjs';
+/**
+ * Interface that guards must implement to control access to endpoints.
+ *
+ * Guards are used for authentication, authorization, and request validation.
+ * They are executed before the endpoint handler and can prevent the request
+ * from proceeding by returning `false` or throwing an exception.
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * export class AuthGuard implements CanActivate {
+ *   async canActivate(context: AbstractExecutionContext): Promise<boolean> {
+ *     const request = context.getRequest()
+ *     const token = request.headers.authorization
+ *
+ *     if (!token) {
+ *       throw new UnauthorizedException('Authentication required')
+ *     }
+ *
+ *     // Validate token
+ *     return true
+ *   }
+ * }
+ * ```
+ */
+export interface CanActivate {
+    /**
+     * Determines if the current request can proceed to the endpoint handler.
+     *
+     * @param executionContext - The execution context containing request, reply, and metadata
+     * @returns `true` if the request can proceed, `false` otherwise. Can also throw an exception.
+     */
+    canActivate(executionContext: AbstractExecutionContext): Promise<boolean> | boolean;
+}
+//# sourceMappingURL=can-activate.d.mts.map

package/src/interfaces/can-activate.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"can-activate.d.mts","sourceRoot":"","sources":["can-activate.mts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAA;AAEvE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;OAKG;IACH,WAAW,CACT,gBAAgB,EAAE,wBAAwB,GACzC,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAA;CAC9B"}

package/src/interfaces/can-activate.mts

@@ -1,6 +1,37 @@
 import type { AbstractExecutionContext } from '../interfaces/index.mjs'
 
+/**
+ * Interface that guards must implement to control access to endpoints.
+ * 
+ * Guards are used for authentication, authorization, and request validation.
+ * They are executed before the endpoint handler and can prevent the request
+ * from proceeding by returning `false` or throwing an exception.
+ * 
+ * @example
+ * ```typescript
+ * @Injectable()
+ * export class AuthGuard implements CanActivate {
+ *   async canActivate(context: AbstractExecutionContext): Promise<boolean> {
+ *     const request = context.getRequest()
+ *     const token = request.headers.authorization
+ *     
+ *     if (!token) {
+ *       throw new UnauthorizedException('Authentication required')
+ *     }
+ *     
+ *     // Validate token
+ *     return true
+ *   }
+ * }
+ * ```
+ */
 export interface CanActivate {
+  /**
+   * Determines if the current request can proceed to the endpoint handler.
+   * 
+   * @param executionContext - The execution context containing request, reply, and metadata
+   * @returns `true` if the request can proceed, `false` otherwise. Can also throw an exception.
+   */
   canActivate(
     executionContext: AbstractExecutionContext,
   ): Promise<boolean> | boolean

package/src/interfaces/http-header.d.mts

@@ -0,0 +1,10 @@
+import type { OutgoingHttpHeaders } from 'http';
+export type OmitIndexSignature<T> = {
+    [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K];
+};
+/**
+ * HTTP header strings
+ * Use this type only for input values, not for output values.
+ */
+export type HttpHeader = keyof OmitIndexSignature<OutgoingHttpHeaders> | (string & Record<never, never>);
+//# sourceMappingURL=http-header.d.mts.map

package/src/interfaces/http-header.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-header.d.mts","sourceRoot":"","sources":["http-header.mts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,MAAM,CAAA;AAE/C,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAAI;KACjC,CAAC,IAAI,MAAM,CAAC,IAAI,MAAM,SAAS,CAAC,GAC7B,KAAK,GACL,MAAM,SAAS,CAAC,GACd,KAAK,GACL,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CACf,CAAA;AAED;;;GAGG;AAEH,MAAM,MAAM,UAAU,GAClB,MAAM,kBAAkB,CAAC,mBAAmB,CAAC,GAC7C,CAAC,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAA"}

package/src/interfaces/index.d.mts

@@ -0,0 +1,9 @@
+export * from './abstract-execution-context.inteface.mjs';
+export * from './abstract-http-adapter.interface.mjs';
+export * from './abstract-http-cors-options.interface.mjs';
+export * from './abstract-http-handler-adapter.interface.mjs';
+export * from './abstract-http-listen-options.interface.mjs';
+export * from './can-activate.mjs';
+export * from './http-header.mjs';
+export * from './navios-module.mjs';
+//# sourceMappingURL=index.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["index.mts"],"names":[],"mappings":"AAAA,cAAc,2CAA2C,CAAA;AACzD,cAAc,uCAAuC,CAAA;AACrD,cAAc,4CAA4C,CAAA;AAC1D,cAAc,+CAA+C,CAAA;AAC7D,cAAc,8CAA8C,CAAA;AAC5D,cAAc,oBAAoB,CAAA;AAClC,cAAc,mBAAmB,CAAA;AACjC,cAAc,qBAAqB,CAAA"}

package/src/interfaces/navios-module.d.mts

@@ -0,0 +1,29 @@
+/**
+ * Interface that all Navios modules must implement.
+ *
+ * Modules decorated with @Module() should implement this interface to receive
+ * lifecycle hooks.
+ *
+ * @example
+ * ```typescript
+ * @Module({
+ *   controllers: [UserController],
+ * })
+ * export class AppModule implements NaviosModule {
+ *   async onModuleInit() {
+ *     console.log('AppModule initialized')
+ *     // Perform initialization logic
+ *   }
+ * }
+ * ```
+ */
+export interface NaviosModule {
+    /**
+     * Optional lifecycle hook called after the module is initialized.
+     *
+     * This is called after all modules are loaded and the HTTP server is set up
+     * (if an adapter is configured), but before the server starts listening.
+     */
+    onModuleInit?: () => Promise<void> | void;
+}
+//# sourceMappingURL=navios-module.d.mts.map

package/src/interfaces/navios-module.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"navios-module.d.mts","sourceRoot":"","sources":["navios-module.mts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;CAC1C"}

package/src/interfaces/navios-module.mts

@@ -1,3 +1,28 @@
+/**
+ * Interface that all Navios modules must implement.
+ * 
+ * Modules decorated with @Module() should implement this interface to receive
+ * lifecycle hooks.
+ * 
+ * @example
+ * ```typescript
+ * @Module({
+ *   controllers: [UserController],
+ * })
+ * export class AppModule implements NaviosModule {
+ *   async onModuleInit() {
+ *     console.log('AppModule initialized')
+ *     // Perform initialization logic
+ *   }
+ * }
+ * ```
+ */
 export interface NaviosModule {
+  /**
+   * Optional lifecycle hook called after the module is initialized.
+   * 
+   * This is called after all modules are loaded and the HTTP server is set up
+   * (if an adapter is configured), but before the server starts listening.
+   */
   onModuleInit?: () => Promise<void> | void
 }