wynkjs 1.0.3 → 1.0.4

package/dist/decorators/exception.advanced.d.ts

@@ -5,46 +5,216 @@ import { NotFoundException, UnauthorizedException, ForbiddenException } from "./
 /**
  * Advanced Exception Filters for WynkJS Framework
  * Specialized filters for different error scenarios
+ *
+ * IMPORTANT: Exception Filter Execution Order
+ * ==========================================
+ *
+ * Filters execute in this order:
+ * 1. Method-level filters (@UseFilters() on route method)
+ * 2. Controller-level filters (@UseFilters() on controller class)
+ * 3. Global filters (app.useGlobalFilters())
+ *
+ * Within each level, filters execute in the order they are registered.
+ *
+ * ============================================================================
+ * CRITICAL: Understanding Filter Scope
+ * ============================================================================
+ *
+ * Exception filters in WynkJS have NO BUILT-IN FILTERING - they catch ALL
+ * exceptions of their type! You must control their scope through placement:
+ *
+ * ❌ PROBLEM: Type-Specific Filters as Global (Old Behavior)
+ * -----------------------------------------------------------
+ * Most type-specific filters (AuthenticationExceptionFilter, etc.) catch ALL
+ * instances of their exception type across your ENTIRE application!
+ *
+ * @example
+ * // ❌ BAD: These catch ALL exceptions of their type everywhere!
+ * app.useGlobalFilters(
+ *   new AuthenticationExceptionFilter() // Catches ALL 401s
+ * );
+ *
+ * ✅ EXCEPTION: NotFoundExceptionFilter (Smart Filter)
+ * ----------------------------------------------------
+ * NotFoundExceptionFilter is SMART - it checks if response data exists:
+ * - If empty/null/[]/{}  → Formats as "Not Found" error
+ * - If has data → Passes to next filter
+ *
+ * This makes it SAFE to use globally!
+ *
+ * @example
+ * // ✅ GOOD: NotFoundExceptionFilter can be used globally
+ * app.useGlobalFilters(
+ *   new NotFoundExceptionFilter(),      // Safe! Only formats truly empty 404s
+ *   new DatabaseExceptionFilter(),      // Only catches DB errors
+ *   new GlobalExceptionFilter()         // Catches everything else
+ * );
+ *
+ * ✅ SOLUTION 1: Use on Specific Routes/Controllers (For non-smart filters)
+ * --------------------------------------------------------------------------
+ * Apply filters where you need custom formatting:
+ *
+ * @example
+ * // ✅ GOOD: Only affects this controller
+ * @UseFilters(AuthenticationExceptionFilter)
+ * @Controller('/auth')
+ * export class AuthController {}
+ *
+ * ✅ SOLUTION 2: Use Generic Filters Globally
+ * --------------------------------------------
+ * These filters check exception types and re-throw what they don't handle:
+ *
+ * @example
+ * // ✅ GOOD: Generic filters that filter themselves
+ * app.useGlobalFilters(
+ *   new DatabaseExceptionFilter(),      // Only catches DB errors, re-throws HttpExceptions
+ *   new NotFoundExceptionFilter(),      // Smart filter - checks response data
+ *   new GlobalExceptionFilter()         // Catches everything else
+ * );
+ *
+ * Best Practice for Multiple Filters:
+ * ------------------------------------
+ * When using multiple specialized filters, register them from MOST SPECIFIC to MOST GENERAL:
+ *
+ * @example
+ * // ✅ RECOMMENDED GLOBAL SETUP
+ * const app = WynkFactory.create({
+ *   controllers: [UserController],
+ *   validationErrorFormatter: new FormatErrorFormatter(), // Handles validation
+ * });
+ *
+ * app.useGlobalFilters(
+ *   new DatabaseExceptionFilter(),  // Handles DB errors only
+ *   new GlobalExceptionFilter()     // Catches everything else
+ * );
+ *
+ * // Then use specific filters on specific routes:
+ * @UseFilters(NotFoundExceptionFilter)
+ * @Get('/:id')
+ * async findOne(@Param('id') id: string) {}
+ *
+ * How Filters Work:
+ * -----------------
+ * 1. Each filter checks if it should handle the exception
+ * 2. If YES: Returns the formatted error response
+ * 3. If NO: Re-throws the exception (using `throw exception`)
+ * 4. Next filter in chain catches the re-thrown exception
+ *
+ * IMPORTANT: Specialized filters now check for HttpException
+ * If you throw HttpException or its subclasses (ConflictException, NotFoundException, etc.),
+ * these specialized filters will re-throw them to let the default handler process them correctly.
  */
 /**
  * Error Formatter Interface
- * Used by ValidationExceptionFilter to format validation errors
+ * Used by WynkFactory to format validation errors
+ *
+ * IMPORTANT: These formatters are passed to WynkFactory.create(), NOT to useGlobalFilters()!
+ *
+ * @example
+ * // CORRECT usage:
+ * const app = WynkFactory.create({
+ *   controllers: [UserController],
+ *   validationErrorFormatter: new FormatErrorFormatter(), // ✅ Pass here
+ * });
+ *
+ * // WRONG usage:
+ * app.useGlobalFilters(
+ *   new ValidationExceptionFilter(new FormatErrorFormatter()) // ❌ This does nothing!
+ * );
  */
 export interface ErrorFormatter {
     format(validationError: any): any;
 }
 /**
  * FormatErrorFormatter - Formats as { field: [messages] } like NestJS
+ *
+ * Output example:
+ * {
+ *   "statusCode": 400,
+ *   "message": "Validation failed",
+ *   "errors": {
+ *     "email": ["Invalid email address"],
+ *     "age": ["Must be at least 18"]
+ *   }
+ * }
+ *
+ * @example
+ * const app = WynkFactory.create({
+ *   controllers: [UserController],
+ *   validationErrorFormatter: new FormatErrorFormatter(),
+ * });
  */
 export declare class FormatErrorFormatter implements ErrorFormatter {
     format(error: any): any;
 }
 /**
  * SimpleErrorFormatter - Formats as simple array of messages
+ *
+ * Output example:
+ * {
+ *   "statusCode": 400,
+ *   "message": "Validation failed",
+ *   "errors": [
+ *     "Invalid email address",
+ *     "Must be at least 18"
+ *   ]
+ * }
+ *
+ * @example
+ * const app = WynkFactory.create({
+ *   controllers: [UserController],
+ *   validationErrorFormatter: new SimpleErrorFormatter(),
+ * });
  */
 export declare class SimpleErrorFormatter implements ErrorFormatter {
     format(error: any): any;
 }
 /**
  * DetailedErrorFormatter - Formats with detailed field info
+ *
+ * Output example:
+ * {
+ *   "statusCode": 400,
+ *   "message": "Validation failed",
+ *   "errors": [
+ *     {
+ *       "field": "email",
+ *       "message": "Invalid email address",
+ *       "value": "invalid-email",
+ *       "expected": {...schema...}
+ *     }
+ *   ]
+ * }
+ *
+ * @example
+ * const app = WynkFactory.create({
+ *   controllers: [UserController],
+ *   validationErrorFormatter: new DetailedErrorFormatter(),
+ * });
  */
 export declare class DetailedErrorFormatter implements ErrorFormatter {
     format(error: any): any;
 }
 /**
- * Validation Exception Filter - Handles validation errors with customizable formatting
- * @example
- * // With FormatErrorFormatter (NestJS-style)
- * app.useGlobalFilters(new ValidationExceptionFilter(new FormatErrorFormatter()));
+ * Validation Exception Filter - DEPRECATED / NOT RECOMMENDED
  *
- * // With SimpleErrorFormatter
- * app.useGlobalFilters(new ValidationExceptionFilter(new SimpleErrorFormatter()));
+ * ⚠️ WARNING: This filter is NOT used by WynkJS for validation errors!
  *
- * // With DetailedErrorFormatter
- * app.useGlobalFilters(new ValidationExceptionFilter(new DetailedErrorFormatter()));
+ * Validation errors are handled directly in the factory's onError hook.
+ * To format validation errors, use the validationErrorFormatter option:
  *
- * // Without formatter (default detailed format)
- * app.useGlobalFilters(new ValidationExceptionFilter());
+ * @example
+ * // ✅ CORRECT: Use validationErrorFormatter in factory options
+ * const app = WynkFactory.create({
+ *   controllers: [UserController],
+ *   validationErrorFormatter: new FormatErrorFormatter(), // This works!
+ * });
+ *
+ * // ❌ WRONG: This does nothing for validation errors
+ * app.useGlobalFilters(new ValidationExceptionFilter(new FormatErrorFormatter()));
+ *
+ * This class is kept for backward compatibility and custom use cases,
+ * but it's not part of the standard validation error flow.
  */
 export declare class ValidationExceptionFilter implements WynkExceptionFilter {
     private formatter;
@@ -53,11 +223,38 @@ export declare class ValidationExceptionFilter implements WynkExceptionFilter {
     private isValidationError;
 }
 /**
- * Database Exception Filter - Handles database errors
+ * Database Exception Filter - Handles database errors ONLY (not HttpExceptions)
+ *
+ * This filter catches actual database errors (like unique constraint violations,
+ * foreign key errors, etc.) and converts them to user-friendly messages.
+ *
+ * It will NOT catch HttpException or its subclasses (ConflictException, etc.)
+ * that you throw manually - those will pass through to be handled correctly.
+ *
  * @example
+ * // Use as global filter
+ * app.useGlobalFilters(new DatabaseExceptionFilter());
+ *
+ * // Use on specific controller
  * @UseFilters(DatabaseExceptionFilter)
  * @Controller('/users')
- * export class UserController {}
+ * export class UserController {
+ *   @Post()
+ *   async create(@Body() data: any) {
+ *     // If you throw manually, it passes through:
+ *     if (await this.userExists(data.email)) {
+ *       throw new ConflictException('User with this email already exists'); // ✅ Works correctly
+ *     }
+ *
+ *     // If database throws error, filter catches it:
+ *     return await this.db.insert(users).values(data); // ❌ DB unique constraint error → caught by filter
+ *   }
+ * }
+ *
+ * Handles these database error codes:
+ * - 23505: Unique constraint violation → 409 Conflict
+ * - 23503: Foreign key constraint violation → 400 Bad Request
+ * - 23502: Not null constraint violation → 400 Bad Request
  */
 export declare class DatabaseExceptionFilter implements WynkExceptionFilter {
     catch(exception: any, context: ExecutionContext): {
@@ -70,10 +267,20 @@ export declare class DatabaseExceptionFilter implements WynkExceptionFilter {
 }
 /**
  * Authentication Exception Filter - Handles auth errors
+ *
+ * ⚠️ IMPORTANT: This catches ALL UnauthorizedException instances!
+ * Use on specific routes/controllers, not globally.
+ *
  * @example
+ * // ✅ GOOD: Use on auth-protected controller
  * @UseFilters(AuthenticationExceptionFilter)
  * @Controller('/auth')
- * export class AuthController {}
+ * export class AuthController {
+ *   @Post('/login')
+ *   async login() {
+ *     throw new UnauthorizedException('Invalid credentials');
+ *   }
+ * }
  */
 export declare class AuthenticationExceptionFilter implements WynkExceptionFilter<UnauthorizedException> {
     catch(exception: UnauthorizedException, context: ExecutionContext): {
@@ -87,10 +294,20 @@ export declare class AuthenticationExceptionFilter implements WynkExceptionFilte
 }
 /**
  * Authorization Exception Filter - Handles permission errors
+ *
+ * ⚠️ IMPORTANT: This catches ALL ForbiddenException instances!
+ * Use on specific routes/controllers, not globally.
+ *
  * @example
+ * // ✅ GOOD: Use on admin-only controller
  * @UseFilters(AuthorizationExceptionFilter)
  * @Controller('/admin')
- * export class AdminController {}
+ * export class AdminController {
+ *   @Get('/users')
+ *   async getAllUsers() {
+ *     throw new ForbiddenException('Admin access required');
+ *   }
+ * }
  */
 export declare class AuthorizationExceptionFilter implements WynkExceptionFilter<ForbiddenException> {
     catch(exception: ForbiddenException, context: ExecutionContext): {
@@ -103,11 +320,48 @@ export declare class AuthorizationExceptionFilter implements WynkExceptionFilter
     };
 }
 /**
- * Not Found Exception Filter - Handles 404 errors
+ * Not Found Exception Filter - Handles 404 errors with smart detection
+ *
+ * This filter is SMART - it only handles NotFoundExceptionFilter if:
+ * 1. The exception is NotFoundException, AND
+ * 2. No response data has been set (empty, null, empty array, or empty object)
+ *
+ * This allows it to be used globally without breaking routes that return
+ * legitimate empty responses or have their own error handling.
+ *
  * @example
- * @UseFilters(NotFoundExceptionFilter)
+ * // ✅ Can be used globally - smart filtering
+ * app.useGlobalFilters(
+ *   new NotFoundExceptionFilter(),  // Safe to use globally now!
+ *   new GlobalExceptionFilter()
+ * );
+ *
+ * @example
+ * // Works correctly in all scenarios:
+ *
+ * // Scenario 1: Empty response with NotFoundException
  * @Get('/:id')
- * async findOne(@Param('id') id: string) {}
+ * async findOne(@Param('id') id: string) {
+ *   const item = await this.service.findOne(id);
+ *   if (!item) {
+ *     throw new NotFoundException('Item not found'); // ✅ Caught and formatted by NotFoundExceptionFilter
+ *   }
+ *   return item;
+ * }
+ *
+ * // Scenario 2: Valid empty array response
+ * @Get('/search')
+ * async search(@Query('q') query: string) {
+ *   const results = await this.service.search(query);
+ *   return results; // ✅ Returns [] without triggering NotFoundExceptionFilter (no NotFoundException thrown)
+ * }
+ *
+ * // Scenario 3: NotFoundException with existing response data
+ * @Get('/custom')
+ * async custom() {
+ *   const data = { message: 'Custom data' };
+ *   throw new NotFoundException('Not found'); // ✅ Passes through (has response data)
+ * }
  */
 export declare class NotFoundExceptionFilter implements WynkExceptionFilter<NotFoundException> {
     catch(exception: NotFoundException, context: ExecutionContext): {
@@ -118,6 +372,12 @@ export declare class NotFoundExceptionFilter implements WynkExceptionFilter<NotF
         path: any;
         suggestion: string;
     };
+    /**
+     * Check if response has meaningful data
+     * Returns false for: null, undefined, {}, [], ""
+     * Returns true for: anything else
+     */
+    private hasResponseData;
 }
 /**
  * Rate Limit Exception Filter - Handles rate limit errors
@@ -186,4 +446,12 @@ export declare class GlobalExceptionFilter implements WynkExceptionFilter {
         path: any;
     };
 }
+/**
+ * ============================================================================
+ * COMPLETE EXAMPLE: Using Multiple Exception Filters
+ * ============================================================================
+ *
+ * Here's a complete example showing how to properly use multiple exception
+ * filters in a WynkJS application with the correct order and behavior.
+ */
 //# sourceMappingURL=exception.advanced.d.ts.map

package/dist/decorators/exception.advanced.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"exception.advanced.d.ts","sourceRoot":"","sources":["../../core/decorators/exception.advanced.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAC1B,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAEL,iBAAiB,EAEjB,qBAAqB,EACrB,kBAAkB,EAEnB,MAAM,wBAAwB,CAAC;AAEhC;;;GAGG;AAEH;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,eAAe,EAAE,GAAG,GAAG,GAAG,CAAC;CACnC;AAED;;GAEG;AACH,qBAAa,oBAAqB,YAAW,cAAc;IACzD,MAAM,CAAC,KAAK,EAAE,GAAG,GAAG,GAAG;CAsBxB;AAED;;GAEG;AACH,qBAAa,oBAAqB,YAAW,cAAc;IACzD,MAAM,CAAC,KAAK,EAAE,GAAG,GAAG,GAAG;CAiBxB;AAED;;GAEG;AACH,qBAAa,sBAAuB,YAAW,cAAc;IAC3D,MAAM,CAAC,KAAK,EAAE,GAAG,GAAG,GAAG;CAgCxB;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,yBAA0B,YAAW,mBAAmB;IACnE,OAAO,CAAC,SAAS,CAA+B;gBAEpC,SAAS,CAAC,EAAE,cAAc;IAItC,KAAK,CAAC,SAAS,EAAE,GAAG,EAAE,OAAO,EAAE,gBAAgB;IAgC/C,OAAO,CAAC,iBAAiB;CAiB1B;AAED;;;;;;GAMG;AACH,qBAAa,uBAAwB,YAAW,mBAAmB;IACjE,KAAK,CAAC,SAAS,EAAE,GAAG,EAAE,OAAO,EAAE,gBAAgB;;;;;;;CAiChD;AAED;;;;;;GAMG;AACH,qBAAa,6BACX,YAAW,mBAAmB,CAAC,qBAAqB,CAAC;IAErD,KAAK,CAAC,SAAS,EAAE,qBAAqB,EAAE,OAAO,EAAE,gBAAgB;;;;;;;;CAalE;AAED;;;;;;GAMG;AACH,qBAAa,4BACX,YAAW,mBAAmB,CAAC,kBAAkB,CAAC;IAElD,KAAK,CAAC,SAAS,EAAE,kBAAkB,EAAE,OAAO,EAAE,gBAAgB;;;;;;;;CAe/D;AAED;;;;;;GAMG;AACH,qBAAa,uBACX,YAAW,mBAAmB,CAAC,iBAAiB,CAAC;IAEjD,KAAK,CAAC,SAAS,EAAE,iBAAiB,EAAE,OAAO,EAAE,gBAAgB;;;;;;;;CAa9D;AAED;;;;;;GAMG;AACH,qBAAa,wBAAyB,YAAW,mBAAmB;IAClE,KAAK,CAAC,SAAS,EAAE,GAAG,EAAE,OAAO,EAAE,gBAAgB;;;;;;;;;CAchD;AAED;;;;;;GAMG;AACH,qBAAa,4BAA6B,YAAW,mBAAmB;IACtE,KAAK,CAAC,SAAS,EAAE,GAAG,EAAE,OAAO,EAAE,gBAAgB;;;;;;;;;CAchD;AAED;;;;;;GAMG;AACH,qBAAa,yBAA0B,YAAW,mBAAmB;IACnE,KAAK,CAAC,SAAS,EAAE,GAAG,EAAE,OAAO,EAAE,gBAAgB;;;;;;;CAsBhD;AAED;;;;GAIG;AACH,qBAAa,qBAAsB,YAAW,mBAAmB;IAC/D,KAAK,CAAC,SAAS,EAAE,GAAG,EAAE,OAAO,EAAE,gBAAgB;;;;;;;;CA2BhD"}
+{"version":3,"file":"exception.advanced.d.ts","sourceRoot":"","sources":["../../core/decorators/exception.advanced.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAC1B,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAEL,iBAAiB,EAEjB,qBAAqB,EACrB,kBAAkB,EAEnB,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqGG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,eAAe,EAAE,GAAG,GAAG,GAAG,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,oBAAqB,YAAW,cAAc;IACzD,MAAM,CAAC,KAAK,EAAE,GAAG,GAAG,GAAG;CAsBxB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,oBAAqB,YAAW,cAAc;IACzD,MAAM,CAAC,KAAK,EAAE,GAAG,GAAG,GAAG;CAiBxB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,sBAAuB,YAAW,cAAc;IAC3D,MAAM,CAAC,KAAK,EAAE,GAAG,GAAG,GAAG;CAgCxB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,yBAA0B,YAAW,mBAAmB;IACnE,OAAO,CAAC,SAAS,CAA+B;gBAEpC,SAAS,CAAC,EAAE,cAAc;IAItC,KAAK,CAAC,SAAS,EAAE,GAAG,EAAE,OAAO,EAAE,gBAAgB;IAgC/C,OAAO,CAAC,iBAAiB;CAiB1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,qBAAa,uBAAwB,YAAW,mBAAmB;IACjE,KAAK,CAAC,SAAS,EAAE,GAAG,EAAE,OAAO,EAAE,gBAAgB;;;;;;;CAuChD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,6BACX,YAAW,mBAAmB,CAAC,qBAAqB,CAAC;IAErD,KAAK,CAAC,SAAS,EAAE,qBAAqB,EAAE,OAAO,EAAE,gBAAgB;;;;;;;;CAalE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,4BACX,YAAW,mBAAmB,CAAC,kBAAkB,CAAC;IAElD,KAAK,CAAC,SAAS,EAAE,kBAAkB,EAAE,OAAO,EAAE,gBAAgB;;;;;;;;CAe/D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,qBAAa,uBACX,YAAW,mBAAmB,CAAC,iBAAiB,CAAC;IAEjD,KAAK,CAAC,SAAS,EAAE,iBAAiB,EAAE,OAAO,EAAE,gBAAgB;;;;;;;;IA2B7D;;;;OAIG;IACH,OAAO,CAAC,eAAe;CAuBxB;AAED;;;;;;GAMG;AACH,qBAAa,wBAAyB,YAAW,mBAAmB;IAClE,KAAK,CAAC,SAAS,EAAE,GAAG,EAAE,OAAO,EAAE,gBAAgB;;;;;;;;;CAmBhD;AAED;;;;;;GAMG;AACH,qBAAa,4BAA6B,YAAW,mBAAmB;IACtE,KAAK,CAAC,SAAS,EAAE,GAAG,EAAE,OAAO,EAAE,gBAAgB;;;;;;;;;CAmBhD;AAED;;;;;;GAMG;AACH,qBAAa,yBAA0B,YAAW,mBAAmB;IACnE,KAAK,CAAC,SAAS,EAAE,GAAG,EAAE,OAAO,EAAE,gBAAgB;;;;;;;CA2BhD;AAED;;;;GAIG;AACH,qBAAa,qBAAsB,YAAW,mBAAmB;IAC/D,KAAK,CAAC,SAAS,EAAE,GAAG,EAAE,OAAO,EAAE,gBAAgB;;;;;;;;CA2BhD;AAED;;;;;;;GAOG"}