@expressots/core 3.0.0 → 4.0.0-preview.3

package/lib/esm/types/di/syntax/binding_when_on_syntax.d.ts

@@ -0,0 +1,25 @@
+import { interfaces } from "../interfaces/interfaces.js";
+declare class BindingWhenOnSyntax<T> implements interfaces.BindingWhenSyntax<T>, interfaces.BindingOnSyntax<T> {
+    private _bindingWhenSyntax;
+    private _bindingOnSyntax;
+    private _binding;
+    constructor(binding: interfaces.Binding<T>);
+    when(constraint: (request: interfaces.Request) => boolean): interfaces.BindingOnSyntax<T>;
+    whenTargetNamed(name: string): interfaces.BindingOnSyntax<T>;
+    whenTargetIsDefault(): interfaces.BindingOnSyntax<T>;
+    whenTargetTagged(tag: string, value: unknown): interfaces.BindingOnSyntax<T>;
+    whenInjectedInto(parent: NewableFunction | string): interfaces.BindingOnSyntax<T>;
+    whenParentNamed(name: string): interfaces.BindingOnSyntax<T>;
+    whenParentTagged(tag: string, value: unknown): interfaces.BindingOnSyntax<T>;
+    whenAnyAncestorIs(ancestor: NewableFunction | string): interfaces.BindingOnSyntax<T>;
+    whenNoAncestorIs(ancestor: NewableFunction | string): interfaces.BindingOnSyntax<T>;
+    whenAnyAncestorNamed(name: string): interfaces.BindingOnSyntax<T>;
+    whenAnyAncestorTagged(tag: string, value: unknown): interfaces.BindingOnSyntax<T>;
+    whenNoAncestorNamed(name: string): interfaces.BindingOnSyntax<T>;
+    whenNoAncestorTagged(tag: string, value: unknown): interfaces.BindingOnSyntax<T>;
+    whenAnyAncestorMatches(constraint: (request: interfaces.Request) => boolean): interfaces.BindingOnSyntax<T>;
+    whenNoAncestorMatches(constraint: (request: interfaces.Request) => boolean): interfaces.BindingOnSyntax<T>;
+    onActivation(handler: (context: interfaces.Context, injectable: T) => T): interfaces.BindingWhenSyntax<T>;
+    onDeactivation(handler: (injectable: T) => Promise<void> | void): interfaces.BindingWhenSyntax<T>;
+}
+export { BindingWhenOnSyntax };

package/lib/esm/types/di/syntax/binding_when_syntax.d.ts

@@ -0,0 +1,21 @@
+import { interfaces } from "../interfaces/interfaces.js";
+declare class BindingWhenSyntax<T> implements interfaces.BindingWhenSyntax<T> {
+    private _binding;
+    constructor(binding: interfaces.Binding<T>);
+    when(constraint: (request: interfaces.Request) => boolean): interfaces.BindingOnSyntax<T>;
+    whenTargetNamed(name: string | number | symbol): interfaces.BindingOnSyntax<T>;
+    whenTargetIsDefault(): interfaces.BindingOnSyntax<T>;
+    whenTargetTagged(tag: string | number | symbol, value: unknown): interfaces.BindingOnSyntax<T>;
+    whenInjectedInto(parent: NewableFunction | string): interfaces.BindingOnSyntax<T>;
+    whenParentNamed(name: string | number | symbol): interfaces.BindingOnSyntax<T>;
+    whenParentTagged(tag: string | number | symbol, value: unknown): interfaces.BindingOnSyntax<T>;
+    whenAnyAncestorIs(ancestor: NewableFunction | string): interfaces.BindingOnSyntax<T>;
+    whenNoAncestorIs(ancestor: NewableFunction | string): interfaces.BindingOnSyntax<T>;
+    whenAnyAncestorNamed(name: string | number | symbol): interfaces.BindingOnSyntax<T>;
+    whenNoAncestorNamed(name: string | number | symbol): interfaces.BindingOnSyntax<T>;
+    whenAnyAncestorTagged(tag: string | number | symbol, value: unknown): interfaces.BindingOnSyntax<T>;
+    whenNoAncestorTagged(tag: string | number | symbol, value: unknown): interfaces.BindingOnSyntax<T>;
+    whenAnyAncestorMatches(constraint: (request: interfaces.Request) => boolean): interfaces.BindingOnSyntax<T>;
+    whenNoAncestorMatches(constraint: (request: interfaces.Request) => boolean): interfaces.BindingOnSyntax<T>;
+}
+export { BindingWhenSyntax };

package/lib/esm/types/di/syntax/constraint_helpers.d.ts

@@ -0,0 +1,6 @@
+import { interfaces } from "../interfaces/interfaces.js";
+declare const traverseAncerstors: (request: interfaces.Request, constraint: interfaces.ConstraintFunction) => boolean;
+declare const taggedConstraint: (key: string | number | symbol) => (value: unknown) => interfaces.ConstraintFunction;
+declare const namedConstraint: (value: unknown) => interfaces.ConstraintFunction;
+declare const typeConstraint: (type: NewableFunction | string) => (request: interfaces.Request | null) => boolean;
+export { traverseAncerstors, taggedConstraint, namedConstraint, typeConstraint, };

package/lib/esm/types/di/utils/async.d.ts

@@ -0,0 +1,3 @@
+declare function isPromise<T>(object: unknown): object is Promise<T>;
+declare function isPromiseOrContainsPromise<T>(object: unknown): object is Promise<T> | Array<T | Promise<T>>;
+export { isPromise, isPromiseOrContainsPromise };

package/lib/esm/types/di/utils/binding_utils.d.ts

@@ -0,0 +1,4 @@
+import type { interfaces } from "../interfaces/interfaces.js";
+export declare const multiBindToService: (container: interfaces.Container) => (service: interfaces.ServiceIdentifier) => (...types: Array<interfaces.ServiceIdentifier>) => void;
+export declare const ensureFullyBound: <T = unknown>(binding: interfaces.Binding<T>) => void;
+export declare const getFactoryDetails: <T = unknown>(binding: interfaces.Binding<T>) => interfaces.FactoryDetails;

package/lib/esm/types/di/utils/clonable.d.ts

@@ -0,0 +1,3 @@
+import { interfaces } from "../interfaces/interfaces.js";
+declare function isClonable<T>(obj: unknown): obj is interfaces.Clonable<T>;
+export { isClonable };

package/lib/esm/types/di/utils/exceptions.d.ts

@@ -0,0 +1,2 @@
+export declare function isStackOverflowExeption(error: unknown): error is RangeError;
+export declare const tryAndThrowErrorIfStackOverflow: <T>(fn: () => T, errorCallback: () => Error) => T;

package/lib/esm/types/di/utils/factory_type.d.ts

@@ -0,0 +1,5 @@
+export declare enum FactoryType {
+    DynamicValue = "toDynamicValue",
+    Factory = "toFactory",
+    Provider = "toProvider"
+}

package/lib/esm/types/di/utils/id.d.ts

@@ -0,0 +1,2 @@
+declare function id(): number;
+export { id };

package/lib/esm/types/di/utils/js.d.ts

@@ -0,0 +1 @@
+export declare function getFirstArrayDuplicate<T>(array: Array<T>): T | undefined;

package/lib/esm/types/di/utils/serialization.d.ts

@@ -0,0 +1,10 @@
+import { interfaces } from "../interfaces/interfaces.js";
+declare function getServiceIdentifierAsString(serviceIdentifier: interfaces.ServiceIdentifier): string;
+declare function listRegisteredBindingsForServiceIdentifier(container: interfaces.Container, serviceIdentifier: string, getBindings: <T>(container: interfaces.Container, serviceIdentifier: interfaces.ServiceIdentifier<T>) => Array<interfaces.Binding<T>>): string;
+declare function circularDependencyToException(request: interfaces.Request): void;
+declare function listMetadataForTarget(serviceIdentifierString: string, target: interfaces.Target): string;
+declare function getFunctionName(func: {
+    name: string | null;
+}): string;
+declare function getSymbolDescription(symbol: symbol): string;
+export { getFunctionName, getServiceIdentifierAsString, listRegisteredBindingsForServiceIdentifier, listMetadataForTarget, circularDependencyToException, getSymbolDescription, };

package/lib/esm/types/error/app-error.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Validation error structure for detailed validation failures
+ */
+export interface ValidationError {
+    property: string;
+    messages: Array<string>;
+    value?: unknown;
+}
+/**
+ * RFC 7807 Problem Details structure
+ */
+export interface ProblemDetails {
+    type?: string;
+    title: string;
+    status: number;
+    detail?: string | Record<string, unknown>;
+    instance?: string;
+    timestamp?: string;
+    errorCode?: string;
+    service?: string;
+    validationErrors?: Array<ValidationError>;
+    [key: string]: unknown;
+}
+/**
+ * Options for creating an AppError with enhanced metadata
+ */
+export interface AppErrorOptions {
+    errorCode?: string;
+    details?: Record<string, unknown>;
+    instance?: string;
+    type?: string;
+    validationErrors?: Array<ValidationError>;
+    requestId?: string;
+}
+/**
+ * Application error class with RFC 7807 Problem Details support.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept error-handling
+ * @difficulty beginner
+ *
+ * @summary Quick Start
+ * Create application errors with HTTP status codes and rich metadata.
+ *
+ * @example
+ * ```typescript
+ * // Simple error
+ * throw new AppError("User not found", 404);
+ *
+ * // With helper methods
+ * throw AppError.notFound("User", "123");
+ * throw AppError.badRequest("Invalid input", { field: "email" });
+ * ```
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
+ * **Internal Architecture**
+ *
+ * AppError extends Error with:
+ * - HTTP status code mapping
+ * - RFC 7807 Problem Details format
+ * - Rich metadata (errorCode, details, validationErrors)
+ * - Request correlation (requestId)
+ * - Timestamp tracking
+ *
+ * **Design Decisions**
+ * - Extends native Error for stack traces
+ * - RFC 7807 compliance for API consistency
+ * - Helper methods for common HTTP errors
+ * - Validation error support
+ *
+ * @see {@link StatusCode} for HTTP status codes
+ * @see {@link Report} for error reporting utility
+ *
+ * @layer advanced
+ * @audience power-users
+ *
+ * **Advanced Usage**
+ *
+ * With validation errors:
+ * ```typescript
+ * throw AppError.validationFailed([
+ *   { property: "email", messages: ["Invalid email format"] },
+ *   { property: "age", messages: ["Must be 18 or older"] }
+ * ]);
+ * ```
+ *
+ * With custom metadata:
+ * ```typescript
+ * throw new AppError("Custom error", 400, "MyService", {
+ *   errorCode: "CUSTOM_ERROR",
+ *   details: { userId: 123 },
+ *   requestId: "req-123"
+ * });
+ * ```
+ *
+ * @public API
+ */
+declare class AppError extends Error {
+    /**
+     * The HTTP status code associated with the error.
+     * Commonly used to define the HTTP response status code.
+     */
+    statusCode: number;
+    /**
+     * The service identifier associated with the error.
+     * This property can be used to trace the origin of the error in the application.
+     * It is optional and can be left undefined.
+     */
+    service?: string;
+    /**
+     * Application-specific error code for programmatic error handling
+     */
+    errorCode?: string;
+    /**
+     * Additional error context and details
+     */
+    details?: Record<string, unknown>;
+    /**
+     * URI reference that identifies the specific occurrence of the problem (RFC 7807)
+     */
+    instance?: string;
+    /**
+     * A URI reference that identifies the problem type (RFC 7807)
+     */
+    type?: string;
+    /**
+     * Timestamp when the error occurred
+     */
+    timestamp: Date;
+    /**
+     * Request correlation ID for tracing
+     */
+    requestId?: string;
+    /**
+     * Validation errors for validation failures
+     */
+    validationErrors?: Array<ValidationError>;
+    /**
+     * @param {string} message - The error message to be displayed.
+     * @param {number} [statusCode=500] - The HTTP status code associated with the error (default: 500).
+     * @param {string} [service] - The service identifier associated with the error.
+     * @param {AppErrorOptions} [options] - Additional error metadata options.
+     */
+    constructor(message: string, statusCode?: number, service?: string, options?: AppErrorOptions);
+    /**
+     * Creates a BadRequest (400) error
+     */
+    static badRequest(message: string, details?: Record<string, unknown>): AppError;
+    /**
+     * Creates a NotFound (404) error
+     */
+    static notFound(resource: string, id?: string): AppError;
+    /**
+     * Creates an Unauthorized (401) error
+     */
+    static unauthorized(message?: string): AppError;
+    /**
+     * Creates a Forbidden (403) error
+     */
+    static forbidden(message?: string): AppError;
+    /**
+     * Creates an UnprocessableEntity (422) validation error
+     */
+    static validationFailed(errors: Array<ValidationError>): AppError;
+    /**
+     * Creates a Conflict (409) error
+     */
+    static conflict(message: string, details?: Record<string, unknown>): AppError;
+    /**
+     * Converts the error to RFC 7807 Problem Details format
+     */
+    toProblemDetails(): ProblemDetails;
+}
+export { AppError };

package/lib/esm/types/error/base-exception-filter.d.ts

@@ -0,0 +1,73 @@
+import { Logger } from "../provider/logger/logger.provider.js";
+import { Report } from "./report.js";
+import type { IExceptionFilter, ExceptionContext } from "./exception-filter.interface.js";
+/**
+ * Base exception filter with common functionality.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept exception-filter-base
+ * @difficulty intermediate
+ *
+ * @summary Quick Start
+ * Extend this class to create custom exception filters.
+ *
+ * @example
+ * ```typescript
+ * @Catch(MyCustomError)
+ * export class MyCustomErrorFilter extends BaseExceptionFilter {
+ *   catch(exception: MyCustomError, context: ExceptionContext): void {
+ *     this.logError(exception, context);
+ *     this.sendErrorResponse(context, 400, { message: exception.message });
+ *   }
+ * }
+ * ```
+ *
+ * **Provided Helpers:**
+ * - `logError()` - Logs error with context
+ * - `sendErrorResponse()` - Sends HTTP error response
+ * - Injected `logger` and `report` services
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
+ * **Internal Architecture**
+ *
+ * BaseExceptionFilter provides:
+ * - Logger injection for error logging
+ * - Report injection for error reporting
+ * - Helper methods for common operations
+ * - Error suggestions integration
+ *
+ * **Design Decisions**
+ * - Abstract class (must implement `catch()`)
+ * - Dependency injection for logger/report
+ * - Helper methods reduce boilerplate
+ * - Integrates with logger suggestions system
+ *
+ * @see {@link Catch} for registering filters
+ * @see {@link IExceptionFilter} for interface definition
+ *
+ * @public API
+ */
+export declare abstract class BaseExceptionFilter implements IExceptionFilter {
+    protected logger?: Logger;
+    protected report?: Report;
+    /**
+     * Handles the exception - must be implemented by derived classes
+     */
+    abstract catch(exception: Error, context: ExceptionContext): void | Promise<void>;
+    /**
+     * Sends an error response
+     * @param context - The exception context
+     * @param statusCode - HTTP status code
+     * @param body - Response body
+     */
+    protected sendErrorResponse(context: ExceptionContext, statusCode: number, body: unknown): void;
+    /**
+     * Logs the error
+     * @param exception - The exception
+     * @param context - The exception context
+     */
+    protected logError(exception: Error, context: ExceptionContext): void;
+}

package/lib/esm/types/error/error-handler-middleware.d.ts

@@ -0,0 +1,11 @@
+import { NextFunction, Response } from "express";
+/**
+ * errorHandler is a custom Express error-handling middleware function.
+ * It logs the error, sets the status code, and sends a JSON response containing the status code and error message.
+ * @param error - An instance of IAppError containing error details.
+ * @param res - The Express response object.
+ * @param next - The Express next function for passing control to the next middleware function.
+ * @param showStackTrace - A boolean value indicating whether to show the stack trace in the response.
+ */
+declare function defaultErrorHandler(error: Error, res: Response, next: NextFunction, showStackTrace?: boolean): void;
+export default defaultErrorHandler;

package/lib/esm/types/error/exception-filter-constants.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Metadata keys for exception filter system
+ * These are used by the exception filter decorators and registry
+ */
+export declare const EXCEPTION_FILTER_METADATA_KEY: {
+    exceptionFilter: string;
+    controllerExceptionFilters: string;
+    methodExceptionFilters: string;
+};

package/lib/esm/types/error/exception-filter-decorators.d.ts

@@ -0,0 +1,126 @@
+import "reflect-metadata";
+import type { IExceptionFilter, ErrorConstructor } from "./exception-filter.interface.js";
+/**
+ * Decorator to mark a class as an exception filter for specific exception types.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept exception-filter
+ * @difficulty intermediate
+ *
+ * @summary Quick Start
+ * Create exception filters to handle specific error types.
+ *
+ * @example
+ * ```typescript
+ * @Catch(AppError)
+ * export class AppErrorFilter extends BaseExceptionFilter {
+ *   catch(exception: AppError, context: ExceptionContext): void {
+ *     // Handle AppError
+ *   }
+ * }
+ * ```
+ *
+ * @param exceptionTypes - Exception types this filter handles. If empty, handles all exceptions.
+ * @returns ClassDecorator
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
+ * **Internal Behavior**
+ * - Stores filter metadata in Reflect
+ * - Registers in global registry for auto-discovery
+ * - ExceptionFilterRegistry discovers filters during initialization
+ * - Supports inheritance matching (parent filters handle child exceptions)
+ *
+ * **Exception Matching**
+ * - Exact type match (highest priority)
+ * - Parent type match (inheritance)
+ * - Global catch-all (Error base class)
+ *
+ * @see {@link ExceptionFilterRegistry} for auto-discovery mechanism
+ * @see {@link UseFilters} for applying filters to routes
+ *
+ * @layer advanced
+ * @audience power-users
+ *
+ * **Advanced Usage**
+ *
+ * Catch multiple exception types:
+ * ```typescript
+ * @Catch(ValidationError, TypeError)
+ * export class ValidationErrorFilter extends BaseExceptionFilter {
+ *   catch(exception: Error, context: ExceptionContext): void {
+ *     // Handle both ValidationError and TypeError
+ *   }
+ * }
+ * ```
+ *
+ * Global catch-all filter:
+ * ```typescript
+ * @Catch()  // No types = catch all
+ * export class GlobalExceptionFilter extends BaseExceptionFilter {
+ *   catch(exception: Error, context: ExceptionContext): void {
+ *     // Handle all unhandled exceptions
+ *   }
+ * }
+ * ```
+ *
+ * @public API
+ */
+export declare function Catch(...exceptionTypes: Array<ErrorConstructor>): ClassDecorator;
+/**
+ * Decorator to apply exception filters at controller or method level.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept exception-filter-application
+ * @difficulty beginner
+ *
+ * @summary Quick Start
+ * Apply exception filters to protect routes with custom error handling.
+ *
+ * @example
+ * ```typescript
+ * // Controller-level filter
+ * @UseFilters(AppErrorFilter, ValidationErrorFilter)
+ * @controller("/users")
+ * export class UserController {
+ *   @Get("/")
+ *   getUsers() {
+ *     // Both filters apply to all methods
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Method-level filter (overrides controller-level)
+ * @controller("/users")
+ * export class UserController {
+ *   @Get("/")
+ *   @UseFilters(NotFoundFilter) // Only this filter applies
+ *   getUser(@param("id") id: string) {
+ *     // Only NotFoundFilter applies
+ *   }
+ * }
+ * ```
+ *
+ * @param filters - Exception filter classes to apply
+ * @returns ClassDecorator & MethodDecorator
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
+ * **Internal Behavior**
+ * - Stores filter metadata on controller/method
+ * - Method-level filters override controller-level filters
+ * - Filters are resolved and executed by ExceptionHandlerMiddleware
+ * - Execution order: method filters → controller filters → global filters
+ *
+ * @see {@link Catch} for creating exception filters
+ * @see {@link ExceptionHandlerMiddleware} for execution logic
+ *
+ * @public API
+ */
+export declare function UseFilters(...filters: Array<new (...args: Array<unknown>) => IExceptionFilter>): ClassDecorator & MethodDecorator;

package/lib/esm/types/error/exception-filter-registry.d.ts

@@ -0,0 +1,38 @@
+import "reflect-metadata";
+import { interfaces } from "../di/inversify.js";
+import { Logger } from "../provider/logger/logger.provider.js";
+import type { IExceptionFilter, ErrorConstructor } from "./exception-filter.interface.js";
+/**
+ * Registry for managing exception filters with automatic discovery
+ * Supports exception type inheritance matching
+ */
+export declare class ExceptionFilterRegistry {
+    private container;
+    private logger;
+    private filters;
+    private initialized;
+    constructor(container: interfaces.Container, logger: Logger);
+    /**
+     * Initialize the registry by auto-discovering all filters decorated with @Catch
+     * This should be called after the container is fully configured
+     */
+    initialize(): void;
+    /**
+     * Get filters for a specific exception type
+     * Supports inheritance - filters for parent types will handle child exceptions
+     * @param exception - The exception instance
+     * @returns Array of matching exception filters
+     */
+    getFilters(exception: Error): Array<IExceptionFilter>;
+    /**
+     * Manually register a filter for specific exception types
+     * Useful for programmatic registration
+     * @param exceptionTypes - Exception types to register for
+     * @param filter - Filter instance
+     */
+    registerFilter(exceptionTypes: Array<ErrorConstructor>, filter: IExceptionFilter): void;
+    /**
+     * Clear all registered filters
+     */
+    clear(): void;
+}

package/lib/esm/types/error/exception-filter.interface.d.ts

@@ -0,0 +1,82 @@
+import { Request, Response, NextFunction } from "express";
+/**
+ * Generic HTTP context interface (adapter-agnostic)
+ * Adapters can extend this with their specific context types
+ */
+export interface IHttpContext {
+    container?: unknown;
+    request: Request;
+    response: Response;
+    user?: unknown;
+}
+/**
+ * Exception context providing comprehensive information about the error occurrence
+ */
+export interface ExceptionContext {
+    /**
+     * Express request object
+     */
+    request: Request;
+    /**
+     * Express response object
+     */
+    response: Response;
+    /**
+     * Express next function
+     */
+    next: NextFunction;
+    /**
+     * Controller class where the error occurred (if available)
+     */
+    controller?: NewableFunction;
+    /**
+     * Handler method name where the error occurred (if available)
+     */
+    handler?: string;
+    /**
+     * Route path where the error occurred (if available)
+     */
+    route?: string;
+    /**
+     * HTTP method where the error occurred (if available)
+     */
+    method?: string;
+    /**
+     * HTTP context with container, request, response, and user (if available)
+     * This is adapter-specific and optional to avoid circular dependencies
+     */
+    httpContext?: IHttpContext;
+    /**
+     * Whether to show stack traces in logs and responses
+     */
+    showStackTrace?: boolean;
+}
+/**
+ * Exception filter interface for handling specific exception types
+ */
+export interface IExceptionFilter {
+    /**
+     * Handles the exception
+     * @param exception - The exception that was thrown
+     * @param context - The exception context with request/response information
+     */
+    catch(exception: Error, context: ExceptionContext): void | Promise<void>;
+}
+/**
+ * Type for any Error constructor (allows any parameter signature)
+ * Using any[] is necessary here to accept error constructors with varying parameter types
+ */
+export type ErrorConstructor = new (...args: Array<any>) => Error;
+/**
+ * Metadata for exception filter registration
+ */
+export interface ExceptionFilterMetadata {
+    /**
+     * Exception types this filter handles
+     */
+    exceptionTypes: Array<ErrorConstructor>;
+    /**
+     * The filter class
+     */
+    filter: NewableFunction;
+}

package/lib/esm/types/error/exception-handler-middleware.d.ts

@@ -0,0 +1,35 @@
+import { Request, Response, NextFunction } from "express";
+import { interfaces } from "../di/inversify.js";
+import { ExceptionFilterRegistry } from "./exception-filter-registry.js";
+/**
+ * Enhanced error handler middleware that integrates with exception filters
+ * Supports route-specific filters, exception type filters, and fallback handling
+ */
+export declare class ExceptionHandlerMiddleware {
+    private registry?;
+    private container?;
+    private logger?;
+    private showStackTrace;
+    constructor(container?: interfaces.Container, registry?: ExceptionFilterRegistry, showStackTrace?: boolean);
+    /**
+     * Express error handler middleware function
+     */
+    handle: (error: Error, req: Request, res: Response, next: NextFunction) => Promise<void>;
+    /**
+     * Get route-specific exception filters
+     * Extracts method-level filters (highest priority) and controller-level filters
+     */
+    private getRouteFilters;
+    /**
+     * Instantiate an exception filter, trying container first, then direct instantiation
+     */
+    private instantiateFilter;
+    /**
+     * Execute exception filters in order
+     */
+    private executeFilters;
+    /**
+     * Default error handler (fallback)
+     */
+    private defaultHandler;
+}

package/lib/esm/types/error/filters/app-error.filter.d.ts

@@ -0,0 +1,10 @@
+import { AppError } from "../app-error.js";
+import { BaseExceptionFilter } from "../base-exception-filter.js";
+import type { ExceptionContext } from "../exception-filter.interface.js";
+/**
+ * Built-in exception filter for AppError instances.
+ * Not auto-registered. Bind it explicitly or use `setErrorHandler({ filters: [AppErrorFilter] })`.
+ */
+export declare class AppErrorFilter extends BaseExceptionFilter {
+    catch(exception: AppError, context: ExceptionContext): void;
+}