@buenojs/bueno 0.8.10 → 0.8.11

package/dist/modules/filters.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Exception Filters System
+ *
+ * Filters catch exceptions thrown during request processing and transform
+ * them into appropriate responses. They act as error boundaries in the
+ * request pipeline.
+ *
+ * Execution Order:
+ * Incoming Request → Guards → Pipes → Handler → Filters (if error) → Error Response
+ */
+import type { Context } from "../context";
+import type { Token } from "../types";
+import { BuenoError, NotFoundError, ValidationError } from "../types";
+/**
+ * Exception filter interface
+ * Filters implement this interface to handle specific exception types
+ */
+export interface ExceptionFilter<T = Error> {
+    catch(exception: T, context: Context): Response | Promise<Response>;
+}
+/**
+ * Filter function type for functional filters
+ */
+export type FilterFn<T = Error> = (exception: T, context: Context) => Response | Promise<Response>;
+/**
+ * Filter type - can be a token, instance, or function
+ */
+export type Filter<T = Error> = Token<ExceptionFilter<T>> | ExceptionFilter<T> | FilterFn<T>;
+type Constructor = new (...args: unknown[]) => unknown;
+/**
+ * Decorator to apply filters to a controller class or method
+ * Filters are executed in order: global → class → method
+ *
+ * @param filters - Filters to apply
+ * @returns ClassDecorator & MethodDecorator
+ *
+ * @example
+ * ```typescript
+ * @Controller('users')
+ * @UseFilters(CustomExceptionFilter)  // Applied to all methods
+ * class UsersController {
+ *   @Get(':id')
+ *   @UseFilters(NotFoundExceptionFilter)  // Additional filter for this method
+ *   getUser() {}
+ * }
+ * ```
+ */
+export declare function UseFilters(...filters: Filter[]): MethodDecorator & ClassDecorator;
+/**
+ * Decorator to mark a filter as catching a specific exception type
+ *
+ * @param exceptionType - The exception class to catch
+ * @returns ClassDecorator
+ *
+ * @example
+ * ```typescript
+ * @Catch(ValidationError)
+ * @Injectable()
+ * class CustomValidationFilter implements ExceptionFilter<ValidationError> {
+ *   catch(exception: ValidationError, context: Context): Response {
+ *     return context.status(422).json({
+ *       error: 'Validation Failed',
+ *       issues: exception.issues
+ *     });
+ *   }
+ * }
+ * ```
+ */
+export declare function Catch<T extends Error>(exceptionType: new (...args: never[]) => T): ClassDecorator;
+/**
+ * Get class-level filters from a controller
+ */
+export declare function getClassFilters(target: Constructor): Filter[] | undefined;
+/**
+ * Get method-level filters from a controller method
+ */
+export declare function getMethodFilters(target: object, propertyKey: string | symbol): Filter[] | undefined;
+/**
+ * Get the exception type that a filter catches
+ */
+export declare function getCatchType(filter: Filter): (new (...args: unknown[]) => Error) | undefined;
+/**
+ * Check if a filter can handle a specific exception
+ */
+export declare function canHandleException(filter: Filter, exception: Error): boolean;
+/**
+ * Type guard to check if a value is an ExceptionFilter instance
+ */
+export declare function isExceptionFilter(value: unknown): value is ExceptionFilter;
+/**
+ * Type guard to check if a value is a FilterFn
+ */
+export declare function isFilterFn(value: unknown): value is FilterFn;
+/**
+ * Execute a filter and return the response
+ */
+export declare function executeFilter(filter: Filter, exception: Error, context: Context, resolveFilter?: (filter: Filter) => ExceptionFilter | null): Promise<Response>;
+/**
+ * Options for executing filters
+ */
+export interface ExecuteFiltersOptions {
+    globalFilters: Filter[];
+    classFilters: Filter[];
+    methodFilters: Filter[];
+    resolveFilter?: (filter: Filter) => ExceptionFilter | null;
+}
+/**
+ * Find and execute the appropriate filter for an exception
+ * Filters are checked in order: method → class → global
+ * The first filter that can handle the exception is used
+ */
+export declare function findAndExecuteFilter(exception: Error, context: Context, options: ExecuteFiltersOptions): Promise<Response>;
+/**
+ * HttpExceptionFilter - Handles BuenoError exceptions
+ * Returns appropriate HTTP status codes and error details
+ */
+export declare class HttpExceptionFilter implements ExceptionFilter<BuenoError> {
+    catch(exception: BuenoError, context: Context): Response;
+}
+/**
+ * ValidationFilter - Handles ValidationError exceptions
+ * Returns validation error details with issues list
+ */
+export declare class ValidationFilter implements ExceptionFilter<ValidationError> {
+    catch(exception: ValidationError, context: Context): Response;
+}
+/**
+ * NotFoundFilter - Handles NotFoundError exceptions
+ * Returns 404 response with resource not found message
+ */
+export declare class NotFoundFilter implements ExceptionFilter<NotFoundError> {
+    catch(exception: NotFoundError, context: Context): Response;
+}
+/**
+ * AllExceptionsFilter - Catch-all filter for any Error
+ * This filter handles all unhandled exceptions
+ */
+export declare class AllExceptionsFilter implements ExceptionFilter<Error> {
+    catch(exception: Error, context: Context): Response;
+}
+/**
+ * Create a default error response when no filter matches
+ */
+export declare function createDefaultErrorResponse(exception: Error, context: Context): Response;
+/**
+ * Create an internal error response
+ */
+export declare function createInternalErrorResponse(exception: Error): Response;
+export {};
+//# sourceMappingURL=filters.d.ts.map

package/dist/modules/filters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filters.d.ts","sourceRoot":"","sources":["../../src/modules/filters.ts"],"names":[],"mappings":"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"}

package/dist/modules/filters.js

@@ -0,0 +1,338 @@
+/**
+ * Exception Filters System
+ *
+ * Filters catch exceptions thrown during request processing and transform
+ * them into appropriate responses. They act as error boundaries in the
+ * request pipeline.
+ *
+ * Execution Order:
+ * Incoming Request → Guards → Pipes → Handler → Filters (if error) → Error Response
+ */
+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;
+};
+import { BuenoError, NotFoundError, ValidationError } from "../types";
+// Metadata storage for filters
+const filterMetadataStore = new WeakMap();
+const catchMetadataStore = new WeakMap();
+// Prototype metadata for method decorators
+const filterPrototypeStore = new WeakMap();
+function setFilterMetadata(target, key, value) {
+    if (!filterMetadataStore.has(target)) {
+        filterMetadataStore.set(target, new Map());
+    }
+    filterMetadataStore.get(target)?.set(key, value);
+}
+function getFilterMetadata(target, key) {
+    return filterMetadataStore.get(target)?.get(key);
+}
+function setFilterPrototypeMetadata(target, key, value) {
+    if (!filterPrototypeStore.has(target)) {
+        filterPrototypeStore.set(target, new Map());
+    }
+    filterPrototypeStore.get(target)?.set(key, value);
+}
+function getFilterPrototypeMetadata(target, key) {
+    return filterPrototypeStore.get(target)?.get(key);
+}
+// ============= Decorators =============
+/**
+ * Decorator to apply filters to a controller class or method
+ * Filters are executed in order: global → class → method
+ *
+ * @param filters - Filters to apply
+ * @returns ClassDecorator & MethodDecorator
+ *
+ * @example
+ * ```typescript
+ * @Controller('users')
+ * @UseFilters(CustomExceptionFilter)  // Applied to all methods
+ * class UsersController {
+ *   @Get(':id')
+ *   @UseFilters(NotFoundExceptionFilter)  // Additional filter for this method
+ *   getUser() {}
+ * }
+ * ```
+ */
+export function UseFilters(...filters) {
+    const decorator = (target, propertyKey, descriptor) => {
+        if (descriptor && propertyKey !== undefined) {
+            // Method decorator
+            const targetObj = target;
+            const existingFilters = getFilterPrototypeMetadata(targetObj, "filters:method") ?? [];
+            setFilterPrototypeMetadata(targetObj, "filters:method", [
+                ...existingFilters,
+                ...filters,
+            ]);
+            return descriptor;
+        }
+        else {
+            // Class decorator
+            const targetClass = target;
+            const existingFilters = getFilterMetadata(targetClass, "filters:class") ?? [];
+            setFilterMetadata(targetClass, "filters:class", [
+                ...existingFilters,
+                ...filters,
+            ]);
+        }
+    };
+    return decorator;
+}
+/**
+ * Decorator to mark a filter as catching a specific exception type
+ *
+ * @param exceptionType - The exception class to catch
+ * @returns ClassDecorator
+ *
+ * @example
+ * ```typescript
+ * @Catch(ValidationError)
+ * @Injectable()
+ * class CustomValidationFilter implements ExceptionFilter<ValidationError> {
+ *   catch(exception: ValidationError, context: Context): Response {
+ *     return context.status(422).json({
+ *       error: 'Validation Failed',
+ *       issues: exception.issues
+ *     });
+ *   }
+ * }
+ * ```
+ */
+export function Catch(exceptionType) {
+    const decorator = (target) => {
+        catchMetadataStore.set(target, {
+            exceptionType: exceptionType,
+        });
+    };
+    return decorator;
+}
+// ============= Helper Functions =============
+/**
+ * Get class-level filters from a controller
+ */
+export function getClassFilters(target) {
+    return getFilterMetadata(target, "filters:class");
+}
+/**
+ * Get method-level filters from a controller method
+ */
+export function getMethodFilters(target, propertyKey) {
+    // First check method-specific filters
+    const methodFilters = getFilterPrototypeMetadata(target, `filters:method:${String(propertyKey)}`);
+    if (methodFilters) {
+        return methodFilters;
+    }
+    // Fall back to general method filters
+    return getFilterPrototypeMetadata(target, "filters:method");
+}
+/**
+ * Get the exception type that a filter catches
+ */
+export function getCatchType(filter) {
+    // If it's a class constructor, check the catch metadata
+    if (typeof filter === "function" && filter.prototype !== undefined) {
+        const metadata = catchMetadataStore.get(filter);
+        return metadata?.exceptionType;
+    }
+    // If it's an instance, check its constructor
+    if (typeof filter === "object" && filter !== null && "catch" in filter) {
+        const constructor = filter.constructor;
+        const metadata = catchMetadataStore.get(constructor);
+        return metadata?.exceptionType;
+    }
+    return undefined;
+}
+/**
+ * Check if a filter can handle a specific exception
+ */
+export function canHandleException(filter, exception) {
+    const catchType = getCatchType(filter);
+    if (!catchType) {
+        // No specific catch type means it handles all exceptions
+        return true;
+    }
+    return exception instanceof catchType;
+}
+/**
+ * Type guard to check if a value is an ExceptionFilter instance
+ */
+export function isExceptionFilter(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "catch" in value &&
+        typeof value.catch === "function");
+}
+/**
+ * Type guard to check if a value is a FilterFn
+ */
+export function isFilterFn(value) {
+    return typeof value === "function" && value.length === 2;
+}
+/**
+ * Execute a filter and return the response
+ */
+export async function executeFilter(filter, exception, context, resolveFilter) {
+    let filterInstance = null;
+    if (isExceptionFilter(filter)) {
+        filterInstance = filter;
+    }
+    else if (isFilterFn(filter)) {
+        // Convert filter function to response
+        return filter(exception, context);
+    }
+    else if (typeof filter === "function") {
+        // It's a class constructor - try to resolve from container or instantiate
+        if (resolveFilter) {
+            filterInstance = resolveFilter(filter);
+        }
+        if (!filterInstance) {
+            // Try to instantiate directly (for simple filters without dependencies)
+            try {
+                const Constructor = filter;
+                filterInstance = new Constructor();
+            }
+            catch {
+                // Cannot instantiate - will fall through to default handling
+            }
+        }
+    }
+    else if (typeof filter === "object" &&
+        filter !== null &&
+        !isExceptionFilter(filter)) {
+        // It's a token - try to resolve
+        if (resolveFilter) {
+            filterInstance = resolveFilter(filter);
+        }
+    }
+    if (filterInstance && isExceptionFilter(filterInstance)) {
+        return filterInstance.catch(exception, context);
+    }
+    // Fallback - should not reach here if a catch-all filter is configured
+    return createInternalErrorResponse(exception);
+}
+/**
+ * Find and execute the appropriate filter for an exception
+ * Filters are checked in order: method → class → global
+ * The first filter that can handle the exception is used
+ */
+export async function findAndExecuteFilter(exception, context, options) {
+    const { globalFilters, classFilters, methodFilters, resolveFilter } = options;
+    // Combine all filters in execution order (method first, then class, then global)
+    const allFilters = [...methodFilters, ...classFilters, ...globalFilters];
+    // Find the first filter that can handle this exception type
+    for (const filter of allFilters) {
+        if (canHandleException(filter, exception)) {
+            return executeFilter(filter, exception, context, resolveFilter);
+        }
+    }
+    // No specific filter found - use default error response
+    return createDefaultErrorResponse(exception, context);
+}
+// ============= Built-in Filters =============
+/**
+ * HttpExceptionFilter - Handles BuenoError exceptions
+ * Returns appropriate HTTP status codes and error details
+ */
+let HttpExceptionFilter = class HttpExceptionFilter {
+    catch(exception, context) {
+        return context.status(exception.statusCode).json({
+            error: exception.name,
+            message: exception.message,
+            code: exception.code,
+            statusCode: exception.statusCode,
+        });
+    }
+};
+HttpExceptionFilter = __decorate([
+    Catch(BuenoError)
+], HttpExceptionFilter);
+export { HttpExceptionFilter };
+/**
+ * ValidationFilter - Handles ValidationError exceptions
+ * Returns validation error details with issues list
+ */
+let ValidationFilter = class ValidationFilter {
+    catch(exception, context) {
+        return context.status(422).json({
+            error: "Validation Failed",
+            message: exception.message,
+            code: "VALIDATION_ERROR",
+            issues: exception.issues,
+        });
+    }
+};
+ValidationFilter = __decorate([
+    Catch(ValidationError)
+], ValidationFilter);
+export { ValidationFilter };
+/**
+ * NotFoundFilter - Handles NotFoundError exceptions
+ * Returns 404 response with resource not found message
+ */
+let NotFoundFilter = class NotFoundFilter {
+    catch(exception, context) {
+        return context.status(404).json({
+            error: "Not Found",
+            message: exception.message,
+            code: "NOT_FOUND",
+        });
+    }
+};
+NotFoundFilter = __decorate([
+    Catch(NotFoundError)
+], NotFoundFilter);
+export { NotFoundFilter };
+/**
+ * AllExceptionsFilter - Catch-all filter for any Error
+ * This filter handles all unhandled exceptions
+ */
+export class AllExceptionsFilter {
+    catch(exception, context) {
+        // Log the error for debugging
+        console.error("Unhandled exception:", exception);
+        // Check if it's a known error type
+        if (exception instanceof BuenoError) {
+            return context.status(exception.statusCode).json({
+                error: exception.name,
+                message: exception.message,
+                code: exception.code,
+            });
+        }
+        // Generic error response
+        return context.status(500).json({
+            error: "Internal Server Error",
+            message: exception.message || "An unexpected error occurred",
+        });
+    }
+}
+// ============= Helper Response Functions =============
+/**
+ * Create a default error response when no filter matches
+ */
+export function createDefaultErrorResponse(exception, context) {
+    // Log the unhandled exception
+    console.error("Unhandled exception (no filter matched):", exception);
+    return context.status(500).json({
+        error: "Internal Server Error",
+        message: exception.message || "An unexpected error occurred",
+    });
+}
+/**
+ * Create an internal error response
+ */
+export function createInternalErrorResponse(exception) {
+    console.error("Internal server error:", exception);
+    return new Response(JSON.stringify({
+        error: "Internal Server Error",
+        message: "An unexpected error occurred",
+    }), {
+        status: 500,
+        headers: {
+            "Content-Type": "application/json",
+        },
+    });
+}
+//# sourceMappingURL=filters.js.map

package/dist/modules/filters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filters.js","sourceRoot":"","sources":["../../src/modules/filters.ts"],"names":[],"mappings":"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"}

package/dist/modules/guards.d.ts

@@ -0,0 +1,188 @@
+/**
+ * Guards System
+ *
+ * Guards determine whether a request should be allowed to proceed to the handler.
+ * They run before interceptors and pipes in the request pipeline.
+ *
+ * Execution Order:
+ * Incoming Request → Guards → Interceptors → Pipes → Handler
+ *
+ * If any guard returns false, the request is rejected with 403 Forbidden.
+ */
+import type { Token } from "../container";
+import type { Context } from "../context";
+/**
+ * Guard interface for authorization checks
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * class AuthGuard implements CanActivate {
+ *   canActivate(context: Context): boolean {
+ *     return !!context.request.headers.get('Authorization');
+ *   }
+ * }
+ * ```
+ */
+export interface CanActivate {
+    canActivate(context: Context): boolean | Promise<boolean>;
+}
+/**
+ * Guard function type (for functional guards)
+ *
+ * @example
+ * ```typescript
+ * const authGuard: GuardFn = (context) => {
+ *   return !!context.request.headers.get('Authorization');
+ * };
+ * ```
+ */
+export type GuardFn = (context: Context) => boolean | Promise<boolean>;
+/**
+ * Guard type - can be:
+ * - A token for a guard class registered in the container
+ * - A guard class instance
+ * - A guard function
+ */
+export type Guard = Token<CanActivate> | CanActivate | GuardFn;
+type Constructor = new (...args: unknown[]) => unknown;
+/**
+ * Get guards from a class constructor
+ */
+export declare function getClassGuards(target: Constructor): Guard[] | undefined;
+/**
+ * Get guards from a method
+ */
+export declare function getMethodGuards(target: object, propertyKey: string | symbol): Guard[] | undefined;
+/**
+ * Decorator to apply guards to a controller class or method.
+ * Guards are executed in the order they are provided.
+ *
+ * @param guards - Guards to apply
+ * @returns ClassDecorator & MethodDecorator
+ *
+ * @example
+ * ```typescript
+ * // Apply to all methods in controller
+ * @Controller('users')
+ * @UseGuards(AuthGuard)
+ * class UsersController {
+ *   @Get()
+ *   getUsers() {} // Protected by AuthGuard
+ *
+ *   @Get(':id')
+ *   @UseGuards(RolesGuard) // Additional guard
+ *   getUser() {} // Protected by AuthGuard AND RolesGuard
+ * }
+ * ```
+ */
+export declare function UseGuards(...guards: Guard[]): MethodDecorator & ClassDecorator;
+/**
+ * AuthGuard - Checks for Authorization header
+ *
+ * This guard verifies that the request has an Authorization header.
+ * It does not validate the token - that should be done by a custom guard.
+ *
+ * @example
+ * ```typescript
+ * @Controller('api')
+ * @UseGuards(AuthGuard)
+ * class ApiController {
+ *   @Get('protected')
+ *   protectedRoute() {} // Requires Authorization header
+ * }
+ * ```
+ */
+export declare class AuthGuard implements CanActivate {
+    canActivate(context: Context): boolean;
+}
+/**
+ * Get required roles from a method
+ */
+export declare function getMethodRoles(target: object, propertyKey: string | symbol): string[] | undefined;
+/**
+ * Decorator to specify required roles for a route
+ * Must be used in conjunction with RolesGuard
+ *
+ * @param roles - Required roles
+ * @returns MethodDecorator
+ *
+ * @example
+ * ```typescript
+ * @Controller('admin')
+ * @UseGuards(AuthGuard, RolesGuard)
+ * class AdminController {
+ *   @Get('users')
+ *   @Roles('admin', 'moderator')
+ *   getUsers() {} // Requires 'admin' or 'moderator' role
+ * }
+ * ```
+ */
+export declare function Roles(...roles: string[]): MethodDecorator;
+/**
+ * User interface for type safety
+ * Applications should extend this interface with their user type
+ */
+export interface User {
+    id: string | number;
+    roles?: string[];
+}
+/**
+ * Context extension for user data
+ * This extends the Context type to include user information
+ */
+declare module "../context" {
+    interface Context {
+        user?: User;
+    }
+}
+/**
+ * RolesGuard - Checks user roles
+ *
+ * This guard checks if the authenticated user has the required roles.
+ * It should be used after AuthGuard in the guard chain.
+ *
+ * The user object must be set on the context before this guard runs.
+ * This is typically done by an authentication middleware or a previous guard.
+ *
+ * @example
+ * ```typescript
+ * @Controller('admin')
+ * @UseGuards(AuthGuard, RolesGuard)
+ * class AdminController {
+ *   @Get('dashboard')
+ *   @Roles('admin')
+ *   getDashboard() {} // Requires 'admin' role
+ * }
+ * ```
+ */
+export declare class RolesGuard implements CanActivate {
+    canActivate(context: Context): boolean;
+}
+/**
+ * Guard executor options
+ */
+export interface GuardExecutorOptions {
+    /** Global guards applied to all routes */
+    globalGuards?: Guard[];
+    /** Guards from controller class */
+    classGuards?: Guard[];
+    /** Guards from method */
+    methodGuards?: Guard[];
+    /** Container for resolving guard instances */
+    resolveGuard?: (guard: Guard) => CanActivate | GuardFn | null;
+}
+/**
+ * Execute guards in order and return whether the request should proceed
+ *
+ * @param context - Request context
+ * @param options - Guard executor options
+ * @returns true if all guards pass, false otherwise
+ */
+export declare function executeGuards(context: Context, options: GuardExecutorOptions): Promise<boolean>;
+/**
+ * Create a 403 Forbidden response
+ */
+export declare function createForbiddenResponse(): Response;
+export {};
+//# sourceMappingURL=guards.d.ts.map