@expressots/core 3.0.0 → 4.0.0-preview.3

package/lib/esm/error/base-exception-filter.js

@@ -0,0 +1,134 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { inject, injectable } from "../di/inversify.js";
+import { Logger } from "../provider/logger/logger.provider.js";
+import { Report } from "./report.js";
+import { getErrorHints, formatSuggestions, getDefaultSuggestionsConfig, } from "../provider/logger/logger.suggestions.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
+ */
+let BaseExceptionFilter = class BaseExceptionFilter {
+    logger;
+    report;
+    /**
+     * Sends an error response
+     * @param context - The exception context
+     * @param statusCode - HTTP status code
+     * @param body - Response body
+     */
+    sendErrorResponse(context, statusCode, body) {
+        if (!context.response.headersSent) {
+            context.response.status(statusCode).json(body);
+        }
+    }
+    /**
+     * Logs the error
+     * @param exception - The exception
+     * @param context - The exception context
+     */
+    logError(exception, context) {
+        const controllerName = context.controller?.name || "unknown";
+        const handlerName = context.handler || "unknown";
+        const service = context.controller?.name || "exception-filter";
+        this.logger?.error(`Exception in ${controllerName}.${handlerName}: ${exception.message}`, service);
+        // Only log stack trace if showStackTrace is explicitly enabled
+        if (context.showStackTrace === true && exception.stack) {
+            this.logger?.error(exception.stack, service);
+        }
+        // Show error suggestions if enabled
+        // Get config from logger if available, otherwise use default
+        let suggestionsConfig = getDefaultSuggestionsConfig();
+        if (this.logger) {
+            try {
+                const loggerConfig = this.logger.getConfig?.();
+                if (loggerConfig?.suggestions) {
+                    suggestionsConfig = {
+                        ...suggestionsConfig,
+                        ...loggerConfig.suggestions,
+                    };
+                }
+            }
+            catch {
+                // If getConfig fails, use default config
+            }
+        }
+        if (suggestionsConfig.enabled) {
+            const hints = getErrorHints(exception, {
+                path: context.request.path,
+                method: context.method,
+                statusCode: exception instanceof Error && "statusCode" in exception
+                    ? exception.statusCode
+                    : undefined,
+            }, suggestionsConfig);
+            if (hints.length > 0) {
+                const suggestionsText = formatSuggestions(hints);
+                this.logger?.info(suggestionsText, service);
+            }
+        }
+    }
+};
+__decorate([
+    inject(Logger),
+    __metadata("design:type", Logger)
+], BaseExceptionFilter.prototype, "logger", void 0);
+__decorate([
+    inject(Report),
+    __metadata("design:type", Report)
+], BaseExceptionFilter.prototype, "report", void 0);
+BaseExceptionFilter = __decorate([
+    injectable()
+], BaseExceptionFilter);
+export { BaseExceptionFilter };

package/lib/esm/error/error-handler-middleware.js

@@ -0,0 +1,34 @@
+import { AppError } from "./app-error.js";
+import { StatusCode } from "./status-code.js";
+import { beautifyStackTrace } from "./utils.js";
+/**
+ * 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.
+ */
+function defaultErrorHandler(error, res, next, showStackTrace = false) {
+    try {
+        if (error instanceof AppError) {
+            res.status(error.statusCode).json({
+                code: error.statusCode,
+                error: error.message,
+            });
+        }
+        else {
+            res.status(StatusCode.InternalServerError).json({
+                code: StatusCode.InternalServerError,
+                error: "An unexpected error occurred.",
+            });
+        }
+        if (showStackTrace && error.stack) {
+            beautifyStackTrace(error.stack);
+        }
+    }
+    catch (error) {
+        next(error);
+    }
+}
+export default defaultErrorHandler;

package/lib/esm/error/exception-filter-constants.js

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

package/lib/esm/error/exception-filter-decorators.js

@@ -0,0 +1,157 @@
+import "reflect-metadata";
+import { EXCEPTION_FILTER_METADATA_KEY } from "./exception-filter-constants.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 function Catch(...exceptionTypes) {
+    return (target) => {
+        // If no exception types provided, catch all (Error base class)
+        const typesToCatch = exceptionTypes.length > 0 ? exceptionTypes : [Error];
+        const metadata = {
+            exceptionTypes: typesToCatch,
+            filter: target,
+        };
+        Reflect.defineMetadata(EXCEPTION_FILTER_METADATA_KEY.exceptionFilter, metadata, target);
+        // Register filter in global registry for auto-discovery
+        const existingFilters = Reflect.getMetadata(EXCEPTION_FILTER_METADATA_KEY.exceptionFilter, Reflect) || [];
+        const newFilters = [...existingFilters, metadata];
+        Reflect.defineMetadata(EXCEPTION_FILTER_METADATA_KEY.exceptionFilter, newFilters, Reflect);
+    };
+}
+/**
+ * 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 function UseFilters(...filters) {
+    return (
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    target, propertyKey) => {
+        if (propertyKey) {
+            // Method-level filter
+            const existingFilters = Reflect.getMetadata(EXCEPTION_FILTER_METADATA_KEY.methodExceptionFilters, target.constructor, propertyKey) || [];
+            const newFilters = [...existingFilters, ...filters];
+            Reflect.defineMetadata(EXCEPTION_FILTER_METADATA_KEY.methodExceptionFilters, newFilters, target.constructor, propertyKey);
+        }
+        else {
+            // Controller-level filter
+            const existingFilters = Reflect.getMetadata(EXCEPTION_FILTER_METADATA_KEY.controllerExceptionFilters, target) || [];
+            const newFilters = [...existingFilters, ...filters];
+            Reflect.defineMetadata(EXCEPTION_FILTER_METADATA_KEY.controllerExceptionFilters, newFilters, target);
+        }
+    };
+}

package/lib/esm/error/exception-filter-registry.js

@@ -0,0 +1,162 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import "reflect-metadata";
+import { inject, injectable, Container } from "../di/inversify.js";
+import { Logger } from "../provider/logger/logger.provider.js";
+import { EXCEPTION_FILTER_METADATA_KEY } from "./exception-filter-constants.js";
+/**
+ * Helper to check if a value is a constructor function
+ */
+function isConstructor(value) {
+    return (typeof value === "function" &&
+        value.prototype &&
+        value.prototype.constructor === value);
+}
+/**
+ * Registry for managing exception filters with automatic discovery
+ * Supports exception type inheritance matching
+ */
+let ExceptionFilterRegistry = class ExceptionFilterRegistry {
+    container;
+    logger;
+    filters = new Map();
+    initialized = false;
+    constructor(container, logger) {
+        this.container = container;
+        this.logger = logger;
+    }
+    /**
+     * Initialize the registry by auto-discovering all filters decorated with @Catch
+     * This should be called after the container is fully configured
+     */
+    initialize() {
+        if (this.initialized) {
+            return;
+        }
+        try {
+            // Get all filters registered via @Catch decorator
+            const filterMetadata = Reflect.getMetadata(EXCEPTION_FILTER_METADATA_KEY.exceptionFilter, Reflect) || [];
+            filterMetadata.forEach(({ exceptionTypes, filter }) => {
+                try {
+                    // Try to get filter from container (if @provide() decorated)
+                    let filterInstance;
+                    if (this.container.isBound(filter)) {
+                        filterInstance = this.container.get(filter);
+                    }
+                    else {
+                        // Create instance manually if not in container
+                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                        filterInstance = new filter();
+                        // Try to inject dependencies if possible
+                        if (this.container.isBound(Logger)) {
+                            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                            filterInstance.logger = this.container.get(Logger);
+                        }
+                        if (this.container.isBound("Report")) {
+                            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                            filterInstance.report = this.container.get("Report");
+                        }
+                    }
+                    // Register filter for each exception type
+                    exceptionTypes.forEach((exceptionType) => {
+                        if (!this.filters.has(exceptionType)) {
+                            this.filters.set(exceptionType, []);
+                        }
+                        this.filters.get(exceptionType).push(filterInstance);
+                    });
+                }
+                catch (error) {
+                    this.logger.warn(`Failed to register exception filter ${filter.name}: ${error}`, "exception-filter-registry");
+                }
+            });
+            this.initialized = true;
+        }
+        catch (error) {
+            this.logger.error(`Failed to initialize exception filter registry: ${error}`, "exception-filter-registry");
+        }
+    }
+    /**
+     * 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) {
+        const filters = [];
+        const visitedTypes = new Set();
+        // Walk up the prototype chain to find matching filters
+        let currentType = null;
+        // Start with the exception's constructor
+        if (isConstructor(exception.constructor)) {
+            currentType = exception.constructor;
+        }
+        while (currentType &&
+            isConstructor(currentType) &&
+            !visitedTypes.has(currentType)) {
+            visitedTypes.add(currentType);
+            if (this.filters.has(currentType)) {
+                filters.push(...this.filters.get(currentType));
+            }
+            // Move to parent class
+            const parent = Object.getPrototypeOf(currentType);
+            if (isConstructor(parent)) {
+                currentType = parent;
+            }
+            else {
+                currentType = null;
+            }
+        }
+        // Add global catch-all filters (Error base class)
+        if (isConstructor(Error)) {
+            const ErrorConstructor = Error;
+            if (this.filters.has(ErrorConstructor)) {
+                const globalFilters = this.filters.get(ErrorConstructor);
+                // Only add if not already included
+                globalFilters.forEach((filter) => {
+                    if (!filters.includes(filter)) {
+                        filters.push(filter);
+                    }
+                });
+            }
+        }
+        return filters;
+    }
+    /**
+     * 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, filter) {
+        exceptionTypes.forEach((exceptionType) => {
+            if (!this.filters.has(exceptionType)) {
+                this.filters.set(exceptionType, []);
+            }
+            this.filters.get(exceptionType).push(filter);
+        });
+    }
+    /**
+     * Clear all registered filters
+     */
+    clear() {
+        this.filters.clear();
+        this.initialized = false;
+    }
+};
+ExceptionFilterRegistry = __decorate([
+    injectable(),
+    __param(0, inject(Container)),
+    __param(1, inject(Logger)),
+    __metadata("design:paramtypes", [Object, Logger])
+], ExceptionFilterRegistry);
+export { ExceptionFilterRegistry };

package/lib/esm/error/exception-filter.interface.js

@@ -0,0 +1 @@
+export {};