@decaf-ts/for-nest 0.6.0 → 0.7.0

package/lib/types/factory/NestBootstraper.d.mts

@@ -0,0 +1,224 @@
+import { INestApplication, Logger, NestInterceptor, PipeTransform } from "@nestjs/common";
+/**
+ * @description
+ * Defines all customizable parameters for Swagger setup.
+ *
+ * @summary
+ * This interface allows developers to customize how Swagger UI is configured
+ * within the NestJS application. It includes parameters for titles, paths,
+ * color schemes, and asset paths to tailor the API documentation experience.
+ *
+ * @param {string} title - Title displayed in Swagger UI.
+ * @param {string} description - Description shown below the title.
+ * @param {string} version - API version displayed in the documentation.
+ * @param {string} [path] - Optional path where Swagger will be available.
+ * @param {boolean} [persistAuthorization] - Whether authorization tokens persist across reloads.
+ * @param {string} [assetsPath] - Path to custom assets for Swagger UI.
+ * @param {string} [topbarBgColor] - Custom background color for the Swagger top bar.
+ * @param {string} [topbarIconPath] - Path to a custom icon displayed in the top bar.
+ * @param {string} [faviconPath] - Path to a custom favicon.
+ */
+export interface SwaggerSetupOptions {
+    title: string;
+    description: string;
+    version: string;
+    path?: string;
+    persistAuthorization?: boolean;
+    assetsPath?: string;
+    topbarBgColor?: string;
+    topbarIconPath?: string;
+    faviconPath?: string;
+    /**
+     * Path to expose the OpenAPI specification in JSON format.
+     * Example: /api/openapi.json
+     */
+    openApiJsonPath?: string;
+    /**
+     * Path to expose the OpenAPI specification in YAML format.
+     * Requires 'yaml' package as peer dependency.
+     * Example: /api/openapi.yaml
+     */
+    openApiYamlPath?: string;
+}
+/**
+ * @description
+ * A fluent, static bootstrap class for initializing and configuring a NestJS application.
+ *
+ * @summary
+ * The `NestBootstraper` class provides a chainable API for configuring
+ * a NestJS application instance. It includes built-in methods for enabling
+ * CORS, Helmet security, Swagger documentation, global pipes, filters,
+ * interceptors, and starting the server.
+ *
+ * This class promotes consistency and reduces repetitive setup code
+ * across multiple NestJS projects.
+ *
+ * @example
+ * ```ts
+ * import { NestFactory } from "@nestjs/core";
+ * import { AppModule } from "./app.module.js";
+ * import { MyLogger } from "./MyLogger.js";
+ * import { NestBootstraper } from "@decaf-ts/for-nest";
+ *
+ * async function bootstrap() {
+ *   const app = await NestFactory.create(AppModule);
+ *
+ *   await NestBootstraper
+ *     .initialize(app)
+ *     .enableLogger(new MyLogger())
+ *     .enableCors(["http://localhost:4200"])
+ *     .useHelmet()
+ *     .setupSwagger({
+ *       title: "OpenAPI by TradeMark™",
+ *       description: "TradeMark™ API documentation",
+ *       version: "1.0.0",
+ *       path: "api",
+ *       persistAuthorization: true,
+ *       topbarBgColor: "#2C3E50",
+ *       topbarIconPath: "/assets/logo.svg",
+ *       faviconPath: "/assets/favicon.ico"
+ *     })
+ *     .useGlobalFilters()
+ *     .useGlobalPipes(...)
+ *     .useGlobalInterceptors(...)
+ *     .start(3000);
+ * }
+ *
+ * bootstrap();
+ * ```
+ * @class
+ */
+export declare class NestBootstraper {
+    private static app;
+    private static _logger;
+    /**
+     * @description
+     * Returns the current logger instance, creating a default one if not set.
+     *
+     * @summary
+     * Ensures that a valid `Logger` instance is always available
+     * for logging bootstrap-related messages.
+     *
+     * @return {Logger} The active logger instance.
+     */
+    private static get logger();
+    /**
+     * @description
+     * Initializes the bootstrapper with a given NestJS application.
+     *
+     * @summary
+     * Binds the provided NestJS app instance to the bootstrapper, enabling
+     * chained configuration methods.
+     *
+     * @param {INestApplication} app - The NestJS application instance to initialize.
+     * @return {NestBootstraper} Returns the class for chaining configuration methods.
+     */
+    static initialize(app: INestApplication): typeof NestBootstraper;
+    /**
+     * @description
+     * Enables or replaces the global logger for the NestJS application.
+     *
+     * @summary
+     * If a custom logger is provided, it replaces the default logger. Otherwise,
+     * a new logger named `"NestBootstrap"` is used. This logger is also registered
+     * with the NestJS application.
+     *
+     * @param {Logger} [customLogger] - Optional custom logger instance.
+     * @return {NestBootstraper} Returns the class for chaining.
+     */
+    static enableLogger(customLogger?: Logger): typeof NestBootstraper;
+    /**
+     * @description
+     * Enables Cross-Origin Resource Sharing (CORS) for the application.
+     *
+     * @summary
+     * Allows defining either a wildcard origin (`"*"`) or a list of allowed origins.
+     * Automatically accepts local development requests and those without origin headers.
+     * Throws a `CorsError` for unauthorized origins.
+     *
+     * @param {'*' | string[]} [origins=[]] - List of allowed origins or `"*"` to allow all.
+     * @param {string[]} [allowMethods=['GET', 'POST', 'PUT', 'DELETE']] - Allowed HTTP methods.
+     * @return {NestBootstraper} Returns the class for chaining configuration.
+     *
+     */
+    static enableCors(origins?: "*" | string[], allowMethods?: string[]): typeof NestBootstraper;
+    /**
+     * @description
+     * Applies the Helmet middleware for enhanced security.
+     *
+     * @summary
+     * Dynamically loads the `helmet` package if available and registers it
+     * as middleware to improve HTTP header security. If not installed, logs a warning
+     * and continues execution without throwing errors.
+     *
+     * @param {Record<string, any>} [options] - Optional configuration passed to Helmet.
+     * @return {NestBootstraper} Returns the class for chaining configuration.
+     */
+    static useHelmet(options?: Record<string, any>): typeof NestBootstraper;
+    /**
+     * @description
+     * Configures and initializes Swagger UI for API documentation.
+     *
+     * @summary
+     * Uses the `SwaggerBuilder` utility to configure API documentation
+     * with detailed customization for title, version, paths, and colors.
+     * Swagger is automatically exposed at the configured path.
+     *
+     * @param {SwaggerSetupOptions} options - Swagger configuration options.
+     * @return {NestBootstraper} Returns the class for chaining configuration.
+     */
+    static setupSwagger(options: SwaggerSetupOptions): typeof NestBootstraper;
+    /**
+     * @description
+     * Registers one or more global validation pipes.
+     *
+     * @summary
+     * Enables request payload validation and transformation globally across
+     * the entire NestJS application. Multiple pipes can be chained together
+     * for modular input validation.
+     *
+     * @param {...PipeTransform[]} pipes - Pipe instances to register globally.
+     * @return {NestBootstraper} Returns the class for chaining.
+     */
+    static useGlobalPipes(...pipes: PipeTransform[]): typeof NestBootstraper;
+    /**
+     * @description
+     * Registers one or more global exception filters.
+     *
+     * @summary
+     * If no filters are provided, it automatically registers a default
+     * set of standard exception filters for common error types like
+     * `HttpException`, `ValidationException`, `ConflictException`, and others.
+     *
+     * @param {...ExceptionFilter[]} filters - Optional filters to apply globally.
+     */
+    static useGlobalFilters(...filters: any[]): typeof NestBootstraper;
+    /**
+     * @description
+     * Registers global interceptors for request and response transformation.
+     *
+     * @summary
+     * Interceptors allow advanced request/response manipulation such as
+     * serialization, logging, or transformation. Multiple interceptors
+     * can be added for modular configuration.
+     *
+     * @param {...NestInterceptor[]} interceptors - Interceptor instances to register.
+     * @return {NestBootstraper} Returns the class for chaining configuration.
+     */
+    static useGlobalInterceptors(...interceptors: NestInterceptor[]): typeof NestBootstraper;
+    /**
+     * @description
+     * Starts the NestJS application and binds it to the given port and host.
+     *
+     * @summary
+     * Listens on the specified port and optionally a host. Once started,
+     * logs the application URL for easy access. The startup process resolves
+     * once the application is successfully running.
+     *
+     * @param {number} [port=3000] - Port number to listen on.
+     * @param {string} [host] - Optional host or IP address to bind to.
+     * @param {boolean} [log=true] - Whether to log the application URL upon startup.
+     * @return {Promise<void>} Resolves once the application starts successfully.
+     */
+    static start(port?: number, host?: string | undefined, log?: boolean): Promise<void>;
+}

package/lib/types/factory/errors/cors.d.cts

@@ -0,0 +1,4 @@
+import { ForbiddenError } from "@decaf-ts/core";
+export declare class CorsError extends ForbiddenError {
+    constructor(msg: string | Error);
+}

package/lib/types/factory/errors/cors.d.mts

@@ -0,0 +1,4 @@
+import { ForbiddenError } from "@decaf-ts/core";
+export declare class CorsError extends ForbiddenError {
+    constructor(msg: string | Error);
+}

package/lib/types/factory/errors/index.d.cts

@@ -0,0 +1 @@
+export * from "./cors.cjs";

package/lib/types/factory/errors/index.d.mts

@@ -0,0 +1 @@
+export * from "./cors.js";

package/lib/types/factory/errors/throttling.d.cts

@@ -0,0 +1,4 @@
+import { BaseError } from "@decaf-ts/db-decorators";
+export declare class ToManyRequestsError extends BaseError {
+    constructor(msg: string | Error);
+}

package/lib/types/factory/errors/throttling.d.mts

@@ -0,0 +1,4 @@
+import { BaseError } from "@decaf-ts/db-decorators";
+export declare class ToManyRequestsError extends BaseError {
+    constructor(msg: string | Error);
+}

package/lib/types/factory/exceptions/DecafErrorFilter.d.cts

@@ -0,0 +1,4 @@
+import { ArgumentsHost, ExceptionFilter } from "@nestjs/common";
+export declare class DecafExceptionFilter implements ExceptionFilter {
+    catch(exception: Error, host: ArgumentsHost): void;
+}

package/lib/types/factory/exceptions/DecafErrorFilter.d.mts

@@ -0,0 +1,4 @@
+import { ArgumentsHost, ExceptionFilter } from "@nestjs/common";
+export declare class DecafExceptionFilter implements ExceptionFilter {
+    catch(exception: Error, host: ArgumentsHost): void;
+}

package/lib/types/factory/exceptions/decorators.d.cts

@@ -0,0 +1,2 @@
+export declare function UseDecafFilter(): MethodDecorator & ClassDecorator;
+export declare function UseDecafHeaders(): MethodDecorator & ClassDecorator;

package/lib/types/factory/exceptions/decorators.d.mts

@@ -0,0 +1,2 @@
+export declare function UseDecafFilter(): MethodDecorator & ClassDecorator;
+export declare function UseDecafHeaders(): MethodDecorator & ClassDecorator;

package/lib/types/factory/exceptions/index.d.cts

@@ -0,0 +1,2 @@
+export * from "./DecafErrorFilter.cjs";
+export * from "./decorators.cjs";

package/lib/types/factory/exceptions/index.d.mts

@@ -0,0 +1,2 @@
+export * from "./DecafErrorFilter.js";
+export * from "./decorators.js";

package/lib/types/factory/index.d.cts

@@ -0,0 +1,4 @@
+export * from "./errors/index.cjs";
+export * from "./exceptions/index.cjs";
+export * from "./openapi/index.cjs";
+export * from "./NestBootstraper.cjs";

package/lib/types/factory/index.d.mts

@@ -0,0 +1,4 @@
+export * from "./errors/index.js";
+export * from "./exceptions/index.js";
+export * from "./openapi/index.js";
+export * from "./NestBootstraper.js";

package/lib/types/factory/openapi/DtoBuilder.d.cts

@@ -0,0 +1,25 @@
+import { OperationKeys } from "@decaf-ts/db-decorators";
+import { Constructor } from "@decaf-ts/decoration";
+import { Model } from "@decaf-ts/decorator-validation";
+/**
+ * Builds a Nest/Swagger DTO class for the given model and CRUD operation.
+ *
+ * Rules:
+ *  - Only CREATE and UPDATE (and their bulk variants) produce a DTO;
+ *    all other operations return the original model class unchanged.
+ *  - @generated() properties (createdAt, updatedAt, createdBy, updatedBy,
+ *    uuid, version, @composed pks, …) are **never** exposed in any DTO.
+ *  - The @pk() property:
+ *      • UPDATE – always included.
+ *      • CREATE  – included only when the pk is NOT auto-generated
+ *                  (checked via Model.pkProps().generated AND Model.generated()).
+ *  - Relation properties (@oneToOne, @oneToMany, …):
+ *      • CREATE  – nested as DtoFor(CREATE, RelatedModel).
+ *      • UPDATE  – union of DtoFor(UPDATE, RelatedModel) **or** the
+ *                  related model's primary-key type (string / integer),
+ *                  expressed as a Swagger oneOf.
+ *
+ * Metadata.properties() now returns ALL properties across the prototype chain,
+ * so DTO inheritance is no longer needed; every DTO is a flat class.
+ */
+export declare function DtoFor<M extends Model>(op: OperationKeys, model: Constructor<M>): Constructor<any>;

package/lib/types/factory/openapi/DtoBuilder.d.mts

@@ -0,0 +1,25 @@
+import { OperationKeys } from "@decaf-ts/db-decorators";
+import { Constructor } from "@decaf-ts/decoration";
+import { Model } from "@decaf-ts/decorator-validation";
+/**
+ * Builds a Nest/Swagger DTO class for the given model and CRUD operation.
+ *
+ * Rules:
+ *  - Only CREATE and UPDATE (and their bulk variants) produce a DTO;
+ *    all other operations return the original model class unchanged.
+ *  - @generated() properties (createdAt, updatedAt, createdBy, updatedBy,
+ *    uuid, version, @composed pks, …) are **never** exposed in any DTO.
+ *  - The @pk() property:
+ *      • UPDATE – always included.
+ *      • CREATE  – included only when the pk is NOT auto-generated
+ *                  (checked via Model.pkProps().generated AND Model.generated()).
+ *  - Relation properties (@oneToOne, @oneToMany, …):
+ *      • CREATE  – nested as DtoFor(CREATE, RelatedModel).
+ *      • UPDATE  – union of DtoFor(UPDATE, RelatedModel) **or** the
+ *                  related model's primary-key type (string / integer),
+ *                  expressed as a Swagger oneOf.
+ *
+ * Metadata.properties() now returns ALL properties across the prototype chain,
+ * so DTO inheritance is no longer needed; every DTO is a flat class.
+ */
+export declare function DtoFor<M extends Model>(op: OperationKeys, model: Constructor<M>): Constructor<any>;

package/lib/types/factory/openapi/SwaggerBuilder.d.cts

@@ -0,0 +1,10 @@
+import { INestApplication } from "@nestjs/common";
+import { SwaggerOptions } from "./constants.cjs";
+export declare class SwaggerBuilder {
+    private readonly app;
+    private readonly options;
+    constructor(app: INestApplication, options: SwaggerOptions);
+    private createDocument;
+    private registerOpenApiRoute;
+    setupSwagger(): void;
+}

package/lib/types/factory/openapi/SwaggerBuilder.d.mts

@@ -0,0 +1,10 @@
+import { INestApplication } from "@nestjs/common";
+import { SwaggerOptions } from "./constants.js";
+export declare class SwaggerBuilder {
+    private readonly app;
+    private readonly options;
+    constructor(app: INestApplication, options: SwaggerOptions);
+    private createDocument;
+    private registerOpenApiRoute;
+    setupSwagger(): void;
+}

package/lib/types/factory/openapi/SwaggerCustomUI.d.cts

@@ -0,0 +1,22 @@
+export interface SwaggerUIOptions {
+    title?: string;
+    path?: string;
+    persistAuthorization: boolean;
+    assetsPath?: string;
+    faviconPath?: string;
+    topbarIconPath?: string;
+    topbarBgColor?: string;
+}
+export declare class SwaggerCustomUI {
+    readonly options: SwaggerUIOptions;
+    constructor(options: SwaggerUIOptions);
+    private customCSS;
+    getCustomOptions(): {
+        customCss: string;
+        swaggerOptions: {
+            persistAuthorization: boolean;
+        };
+        customSiteTitle: string | undefined;
+    };
+    b64(file: string, img?: boolean): string;
+}

package/lib/types/factory/openapi/SwaggerCustomUI.d.mts

@@ -0,0 +1,22 @@
+export interface SwaggerUIOptions {
+    title?: string;
+    path?: string;
+    persistAuthorization: boolean;
+    assetsPath?: string;
+    faviconPath?: string;
+    topbarIconPath?: string;
+    topbarBgColor?: string;
+}
+export declare class SwaggerCustomUI {
+    readonly options: SwaggerUIOptions;
+    constructor(options: SwaggerUIOptions);
+    private customCSS;
+    getCustomOptions(): {
+        customCss: string;
+        swaggerOptions: {
+            persistAuthorization: boolean;
+        };
+        customSiteTitle: string | undefined;
+    };
+    b64(file: string, img?: boolean): string;
+}

package/lib/types/factory/openapi/constants.d.cts

@@ -0,0 +1,27 @@
+import { SecuritySchemeObject } from "@nestjs/swagger/dist/interfaces/open-api-spec.interface";
+import { Constructor } from "@decaf-ts/decoration";
+export interface SwaggerOptions {
+    title: string;
+    description: string;
+    version?: string;
+    assetsPath?: string;
+    faviconFilePath?: string;
+    topbarIconFilePath?: string;
+    persistAuthorization?: boolean;
+    path: string;
+    auth?: SecuritySchemeObject;
+    topbarBgColor?: string;
+    extraModels?: Constructor[];
+    /**
+     * Path to expose the OpenAPI specification in JSON format.
+     * Example: /api/openapi.json
+     */
+    openApiJsonPath?: string;
+    /**
+     * Path to expose the OpenAPI specification in YAML format.
+     * Requires 'yaml' package as peer dependency.
+     * Example: /api/openapi.yaml
+     */
+    openApiYamlPath?: string;
+}
+export declare const SWAGGER_UI_CONSTANTS: SwaggerOptions;

package/lib/types/factory/openapi/constants.d.mts

@@ -0,0 +1,27 @@
+import { SecuritySchemeObject } from "@nestjs/swagger/dist/interfaces/open-api-spec.interface";
+import { Constructor } from "@decaf-ts/decoration";
+export interface SwaggerOptions {
+    title: string;
+    description: string;
+    version?: string;
+    assetsPath?: string;
+    faviconFilePath?: string;
+    topbarIconFilePath?: string;
+    persistAuthorization?: boolean;
+    path: string;
+    auth?: SecuritySchemeObject;
+    topbarBgColor?: string;
+    extraModels?: Constructor[];
+    /**
+     * Path to expose the OpenAPI specification in JSON format.
+     * Example: /api/openapi.json
+     */
+    openApiJsonPath?: string;
+    /**
+     * Path to expose the OpenAPI specification in YAML format.
+     * Requires 'yaml' package as peer dependency.
+     * Example: /api/openapi.yaml
+     */
+    openApiYamlPath?: string;
+}
+export declare const SWAGGER_UI_CONSTANTS: SwaggerOptions;

package/lib/types/factory/openapi/index.d.cts

@@ -0,0 +1,2 @@
+export * from "./SwaggerBuilder.cjs";
+export * from "./DtoBuilder.cjs";

package/lib/types/factory/openapi/index.d.mts

@@ -0,0 +1,2 @@
+export * from "./SwaggerBuilder.js";
+export * from "./DtoBuilder.js";

package/lib/types/index.d.cts

@@ -0,0 +1,43 @@
+/**
+ * @module for-nest
+ * @description This module serves as the main entry point for the ts-workspace library. It aggregates and exports
+ * functionality from various submodules and utilities within the project.
+ *
+ * The module includes:
+ * 1. Utility functions and types from the "./utils" directory:
+ *    - These likely contain helper functions, common types, and shared functionality used throughout the project.
+ *    - May include operations for data manipulation, type checking, or other general-purpose utilities.
+ *
+ * 2. A namespace and related types from the "./namespace" directory:
+ *    - This could contain domain-specific code or a collection of related functionality.
+ *    - Might include interfaces, types, or classes that represent core concepts in the library.
+ *
+ * 3. A VERSION constant:
+ *    - Represents the current version of the module.
+ *    - Useful for version checking and compatibility purposes.
+ *
+ * This structure provides a clean and organized export of the module's functionality, allowing consumers
+ * to easily import and use specific parts of the library as needed.
+ */
+import "./decoration";
+export * from "./decoration.cjs";
+export * from "./decaf-model/index.cjs";
+export * from "./factory/index.cjs";
+export * from "./interceptors/index.cjs";
+export * from "./overrides/index.cjs";
+export * from "./request/index.cjs";
+export * from "./constants.cjs";
+export * from "./controllers.cjs";
+export * from "./module.cjs";
+export * from "./core-module.cjs";
+export * from "./types.cjs";
+export * from "./utils.cjs";
+export * from "./events-module/index.cjs";
+/**
+ * Represents the current version of the ts-workspace module.
+ * The actual version number is replaced during the build process.
+ * @constant
+ * @type {string}
+ */
+export declare const VERSION = "0.6.0";
+export declare const PACKAGE_NAME = "@decaf-ts/for-nest";

package/lib/types/index.d.mts

@@ -0,0 +1,43 @@
+/**
+ * @module for-nest
+ * @description This module serves as the main entry point for the ts-workspace library. It aggregates and exports
+ * functionality from various submodules and utilities within the project.
+ *
+ * The module includes:
+ * 1. Utility functions and types from the "./utils" directory:
+ *    - These likely contain helper functions, common types, and shared functionality used throughout the project.
+ *    - May include operations for data manipulation, type checking, or other general-purpose utilities.
+ *
+ * 2. A namespace and related types from the "./namespace" directory:
+ *    - This could contain domain-specific code or a collection of related functionality.
+ *    - Might include interfaces, types, or classes that represent core concepts in the library.
+ *
+ * 3. A VERSION constant:
+ *    - Represents the current version of the module.
+ *    - Useful for version checking and compatibility purposes.
+ *
+ * This structure provides a clean and organized export of the module's functionality, allowing consumers
+ * to easily import and use specific parts of the library as needed.
+ */
+import "./decoration";
+export * from "./decoration.js";
+export * from "./decaf-model/index.js";
+export * from "./factory/index.js";
+export * from "./interceptors/index.js";
+export * from "./overrides/index.js";
+export * from "./request/index.js";
+export * from "./constants.js";
+export * from "./controllers.js";
+export * from "./module.js";
+export * from "./core-module.js";
+export * from "./types.js";
+export * from "./utils.js";
+export * from "./events-module/index.js";
+/**
+ * Represents the current version of the ts-workspace module.
+ * The actual version number is replaced during the build process.
+ * @constant
+ * @type {string}
+ */
+export declare const VERSION = "0.6.0";
+export declare const PACKAGE_NAME = "@decaf-ts/for-nest";

package/lib/types/index.d.ts

@@ -39,5 +39,5 @@ export * from "./events-module";
  * @constant
  * @type {string}
  */
-export declare const VERSION = "0.5.0";
+export declare const VERSION = "0.6.0";
 export declare const PACKAGE_NAME = "@decaf-ts/for-nest";

package/lib/types/interceptors/AuthInterceptor.d.cts

@@ -0,0 +1,10 @@
+import { NestInterceptor, ExecutionContext, CallHandler } from "@nestjs/common";
+import { Reflector } from "@nestjs/core";
+import { Observable } from "rxjs";
+import type { AuthHandler } from "../types.cjs";
+export declare class AuthInterceptor implements NestInterceptor {
+    private readonly reflector;
+    private readonly authHandler?;
+    constructor(reflector: Reflector, authHandler?: AuthHandler | undefined);
+    intercept(ctx: ExecutionContext, next: CallHandler): Promise<Observable<any>>;
+}

package/lib/types/interceptors/AuthInterceptor.d.mts

@@ -0,0 +1,10 @@
+import { NestInterceptor, ExecutionContext, CallHandler } from "@nestjs/common";
+import { Reflector } from "@nestjs/core";
+import { Observable } from "rxjs";
+import type { AuthHandler } from "../types.js";
+export declare class AuthInterceptor implements NestInterceptor {
+    private readonly reflector;
+    private readonly authHandler?;
+    constructor(reflector: Reflector, authHandler?: AuthHandler | undefined);
+    intercept(ctx: ExecutionContext, next: CallHandler): Promise<Observable<any>>;
+}

package/lib/types/interceptors/DecafRequestHandlerInterceptor.d.cts

@@ -0,0 +1,57 @@
+import { CallHandler, ExecutionContext, NestInterceptor } from "@nestjs/common";
+import { DecafHandlerExecutor, DecafRequestContext } from "../request/index.cjs";
+import { DecafServerCtx } from "../constants.cjs";
+import "../overrides";
+/**
+ * @description
+ * Interceptor responsible for executing all registered Decaf request handlers
+ * before the controller method is invoked.
+ *
+ * @summary
+ * The {@link DecafRequestHandlerInterceptor} integrates the Decaf request-handling pipeline
+ * into NestJS' interceptor mechanism. Before passing execution to the next handler in the
+ * NestJS chain, it delegates request processing to the {@link DecafHandlerExecutor}, which
+ * sequentially runs all registered {@link DecafRequestHandler} instances. This allows
+ * behaviors such as authentication, logging, tenant resolution, or metadata enrichment
+ * to occur prior to controller execution.
+ *
+ * @class DecafRequestHandlerInterceptor
+ *
+ * @example
+ * ```ts
+ * // Apply globally:
+ * app.useGlobalInterceptors(new DecafRequestHandlerInterceptor(executor));
+ *
+ * // Or in a module:
+ * @Module({
+ *   providers: [
+ *     DecafHandlerExecutor,
+ *     {
+ *       provide: APP_INTERCEPTOR,
+ *       useClass: DecafRequestHandlerInterceptor,
+ *     },
+ *   ],
+ * })
+ * export class AppModule {}
+ * ```
+ *
+ * @mermaid
+ * sequenceDiagram
+ *     participant Client
+ *     participant Interceptor
+ *     participant Executor
+ *     participant Controller
+ *
+ *     Client->>Interceptor: HTTP Request
+ *     Interceptor->>Executor: exec(request)
+ *     Executor-->>Interceptor: handlers completed
+ *     Interceptor->>Controller: next.handle()
+ *     Controller-->>Client: Response
+ */
+export declare class DecafRequestHandlerInterceptor implements NestInterceptor {
+    protected readonly requestContext: DecafRequestContext;
+    protected readonly executor: DecafHandlerExecutor;
+    constructor(requestContext: DecafRequestContext, executor: DecafHandlerExecutor);
+    protected contextualize(req: any): Promise<DecafServerCtx>;
+    intercept(context: ExecutionContext, next: CallHandler): Promise<import("rxjs").Observable<any>>;
+}