@expressots/core 3.0.0 → 4.0.0-preview.3

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

@@ -1,11 +1,102 @@
 /**
- * The AppError class extends the built-in Error class in JavaScript,
- * providing additional properties to manage custom application errors.
- * It captures detailed information about the error, including a status code
- * and an optional service identifier, which can be useful for error handling
- * and logging within the application.
+ * 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);
  *
- * @extends {Error}
+ * // 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 {
     /**
@@ -19,11 +110,68 @@ declare class AppError extends Error {
      * 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
      */
-    constructor(message: string, statusCode?: number, service?: string);
+    toProblemDetails(): ProblemDetails;
 }
 export { AppError };

package/lib/cjs/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/cjs/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/cjs/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/cjs/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/cjs/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/cjs/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/cjs/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;
+}

package/lib/cjs/types/error/filters/global-exception.filter.d.ts

@@ -0,0 +1,9 @@
+import { BaseExceptionFilter } from "../base-exception-filter.js";
+import type { ExceptionContext } from "../exception-filter.interface.js";
+/**
+ * Global exception filter that catches all unhandled exceptions.
+ * Not auto-registered. Bind it explicitly or use `setErrorHandler({ filters: [GlobalExceptionFilter] })`.
+ */
+export declare class GlobalExceptionFilter extends BaseExceptionFilter {
+    catch(exception: Error, context: ExceptionContext): void;
+}

package/lib/cjs/types/error/filters/not-found.filter.d.ts

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

package/lib/cjs/types/error/filters/validation-error.filter.d.ts

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

package/lib/cjs/types/error/index.d.ts

@@ -1,3 +1,14 @@
-export { StatusCode } from "./status-code";
-export { Report } from "./report";
-export { AppError } from "./app-error";
+export { StatusCode } from "./status-code.js";
+export { Report } from "./report.js";
+export { AppError, type AppErrorOptions, type ProblemDetails, type ValidationError, } from "./app-error.js";
+export { NotFoundError } from "./not-found.error.js";
+export { ValidationError as ValidationErrorClass } from "./validation.error.js";
+export type { IExceptionFilter, ExceptionContext, IHttpContext, ErrorConstructor, } from "./exception-filter.interface.js";
+export { BaseExceptionFilter } from "./base-exception-filter.js";
+export { ExceptionFilterRegistry } from "./exception-filter-registry.js";
+export { Catch, UseFilters } from "./exception-filter-decorators.js";
+export { EXCEPTION_FILTER_METADATA_KEY } from "./exception-filter-constants.js";
+export { AppErrorFilter } from "./filters/app-error.filter.js";
+export { GlobalExceptionFilter } from "./filters/global-exception.filter.js";
+export { NotFoundFilter } from "./filters/not-found.filter.js";
+export { ValidationErrorFilter } from "./filters/validation-error.filter.js";

package/lib/cjs/types/error/not-found.error.d.ts

@@ -0,0 +1,7 @@
+import { AppError } from "./app-error.js";
+/**
+ * NotFoundError - Specific error type for resource not found scenarios
+ */
+export declare class NotFoundError extends AppError {
+    constructor(resource: string, id?: string);
+}