wynkjs 1.0.3 → 1.0.6

package/README.md

@@ -2,14 +2,14 @@
 
 <div align="center">
 
-**A high-performance TypeScript framework built on Elysia for Bun with NestJS-style decorators**
+**A high-performance TypeScript first framework built for Bun with Elegant Decorator-Based Architecture**
 
 [![npm version](https://img.shields.io/npm/v/wynkjs.svg)](https://www.npmjs.com/package/wynkjs)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
 [![Bun](https://img.shields.io/badge/Bun-1.0+-black.svg)](https://bun.sh/)
 
-_20x faster than Express, easier than NestJS, built for Bun_ ⚡
+_10x faster than Express/NestJs, built for modern TypeScript development for Bun_ ⚡
 
 [Quick Start](#-quick-start) • [CLI Tools](#️-cli-tools) • [Features](#-features--examples) • [Documentation](#-documentation)
 
@@ -19,32 +19,18 @@ _20x faster than Express, easier than NestJS, built for Bun_ ⚡
 
 ## About
 
-WynkJS is a modern, TypeScript-first web framework that brings NestJS-style decorators to the blazing-fast Elysia runtime built for **Bun**. It's a lightweight NestJS alternative with familiar concepts—controllers, dependency injection, guards, pipes, interceptors, and exception filters—designed for building high‑performance REST APIs and backends on **Bun**. WynkJS embraces ESM, ships first-class types, and keeps things simple so you can move fast without the bloat.
+WynkJS is a modern, TypeScript-first web framework alternative to NestJs that brings Elegant Decorator-Based Architecture to the blazing-fast Elysia runtime built for **Bun**. It features familiar concepts—**Controllers, Dependency Injection, Guards, Pipes, Interceptors, and Exception Filters**—designed for building high‑performance REST APIs and backends on **Bun**. WynkJS embraces ESM, ships first-class types, and keeps things simple so you can move fast without the bloat.
 
-**🚀 Get Started in 30 Seconds:**
-
-```bash
-bunx create-wynkjs        # Create new project
-cd my-wynkjs-app          # Navigate to project
-bun run dev               # Start server with hot reload
-```
-
-Then generate your first API module:
-
-```bash
-wynkjs g m product        # Generate complete CRUD module
-```
-
-Keywords: NestJS alternative, Elysia framework, Bun framework, TypeScript decorators, dependency injection (DI), guards, pipes, interceptors, exception filters, fast web framework, REST API, backend.
+Keywords: Bun framework, Fast web server, TypeScript decorators, dependency injection (DI), guards, pipes, interceptors, exception filters, fast web framework, REST API, backend, modern TypeScript.
 
 ---
 
 ## ✨ Why WynkJS?
 
-WynkJS combines the **speed of Elysia** with the **elegant decorator syntax of NestJS**, giving you the best of both worlds:
+WynkJS combines the **speed of Elysia** with an **Elegant Decorator-Based Architecture**, giving you the best of both worlds:
 
-- 🚀 **20x Faster** - Built on Elysia, one of the fastest web frameworks for Bun
-- 🎨 **Decorator-Based** - Familiar NestJS-style decorators
+- 🚀 **10x Faster** - One of the fastest web frameworks for Bun
+- 🎨 **Decorator-Based** - Clean, intuitive decorator syntax for TypeScript
 - 💉 **Dependency Injection** - Built-in DI (no need to import reflect-metadata!)
 - 🔒 **TypeScript First** - TypeScript is mandatory, not optional. Full type safety and IntelliSense support
 - 🎯 **Simple & Clean** - Easy to learn, powerful to use
@@ -54,60 +40,98 @@ WynkJS combines the **speed of Elysia** with the **elegant decorator syntax of N
 
 ---
 
-## 📦 Installation
-
-**Requirements:** Bun 1.0 or higher
+## 🚀 Get Started in 30 Seconds:
 
-### Quick Start (Recommended)
+### 📦 create-wynkjs - Project Scaffolding
 
-Create a new WynkJS project with all best practices:
+Quickly scaffold a new WynkJS project with best practices:
 
 ```bash
+# Create a new project
 bunx create-wynkjs
 # or
 npx create-wynkjs
 ```
 
-This will scaffold a complete **TypeScript** project with:
-
-- ✅ TypeScript (strict mode, decorators enabled)
-- ✅ ESLint + Prettier (optional)
-- ✅ Hot reload with `bun --watch`
-- ✅ Example code (controllers, services, DTOs)
-- ✅ Git hooks (optional)
+**What you get:**
 
-### Manual Installation
+- ✅ **TypeScript** - Strict mode with decorators enabled (mandatory)
+- ✅ **ESLint** - Code linting with TypeScript rules (optional)
+- ✅ **Prettier** - Code formatting (optional)
+- ✅ **Husky** - Git hooks for pre-commit checks (optional)
+- ✅ **Hot Reload** - `bun --watch` for instant feedback
+- ✅ **Working Example** - Complete CRUD controller, service, and DTOs
 
-Add to an existing project:
+**Generated Project Structure:**
 
-```bash
-bun add wynkjs elysia
+```
+my-wynkjs-app/
+├── src/
+│   ├── modules/
+│   │   └── user/
+│   │       ├── user.controller.ts
+│   │       ├── user.service.ts
+│   │       └── user.dto.ts
+│   └── index.ts
+├── .eslintrc.json
+├── .prettierrc
+├── tsconfig.json
+└── package.json
 ```
 
-**Note**: WynkJS is built specifically for **Bun**. It leverages Elysia's performance optimizations that are designed for Bun runtime. ✨
+**Available Scripts:**
 
----
+- `bun run dev` - Development with hot reload
+- `bun run start` - Production server
+- `bun run build` - Build TypeScript
+- `bun run lint` - Run ESLint
+- `bun run format` - Format with Prettier
+
+[Learn more about create-wynkjs](./packages/create-wynkjs/README.md)
 
-## 🚀 Quick Start
+**Example:**
+
+```bash
+bunx create-wynkjs
+# Choose project name: my-api
+# Add ESLint? Yes
+# Add Prettier? Yes
+# Add Husky? No
+
+cd my-api
+bun run dev
+# 🚀 Server running on http://localhost:3000
+```
 
-### 1. Create Your DTOs (Data Transfer Objects)
+### 1. Find Your DTOs (Data Transfer Objects)
 
 ```typescript
 // user.dto.ts
 import { DTO, CommonDTO } from "wynkjs";
 
 export const CreateUserDTO = DTO.Strict({
-  name: DTO.Optional(DTO.String({ minLength: 2, maxLength: 50 })),
+  name: DTO.Optional(
+    DTO.String({
+      maxLength: 50,
+      error: "Name must be between 2 and 50 characters",
+    })
+  ),
   email: CommonDTO.Email({
     description: "User email address",
+    error: "Please provide a valid email address",
   }),
   mobile: DTO.Optional(
     DTO.String({
       pattern: "^[6-9]{1}[0-9]{9}$",
-      errorMessage: "Invalid mobile number",
+      error: "Invalid mobile number format",
+    })
+  ),
+  age: DTO.Optional(
+    DTO.Number({
+      minimum: 18,
+      error: "Age must be at least 18 years",
     })
   ),
-  age: DTO.Optional(DTO.Number({ minimum: 18 })),
 });
 
 export interface CreateUserType {
@@ -126,7 +150,7 @@ export interface ParamIdType {
 }
 ```
 
-### 2. Create a Service with Dependency Injection
+### 2. Find Your Service with Dependency Injection
 
 ```typescript
 // email.service.ts
@@ -141,7 +165,7 @@ export class EmailService {
 }
 ```
 
-### 3. Create Your Controller
+### 3. Find Your Controller
 
 ```typescript
 // user.controller.ts
@@ -221,9 +245,9 @@ console.log("🚀 Server running on http://localhost:3000");
 ### 5. Run Your Server
 
 ```bash
-bun run index.ts
+bun run start
 # or with --watch for hot reload
-bun --watch index.ts
+bun run dev
 ```
 
 ### 6. Test Your API
@@ -254,25 +278,56 @@ That's it! 🎉
 
 ### HTTP Methods
 
+All HTTP method decorators support both **string** and **object** formats:
+
 ```typescript
-@Get(path?: string)        // GET request
-@Post(path?: string)       // POST request
-@Put(path?: string)        // PUT request
-@Patch(path?: string)      // PATCH request
-@Delete(path?: string)     // DELETE request
-@Options(path?: string)    // OPTIONS request
-@Head(path?: string)       // HEAD request
+// Simple string format
+@Get(path?: string)
+@Post(path?: string)
+@Put(path?: string)
+@Patch(path?: string)
+@Delete(path?: string)
+@Options(path?: string)
+@Head(path?: string)
+
+// Object format with validation
+@Get({ path?: string, params?: Schema, query?: Schema })
+@Post({ path?: string, body?: Schema, params?: Schema, query?: Schema })
+@Put({ path?: string, body?: Schema, params?: Schema, query?: Schema })
+@Patch({ path?: string, body?: Schema, params?: Schema, query?: Schema })
+@Delete({ path?: string, params?: Schema, query?: Schema })
+```
+
+**Examples:**
+
+```typescript
+// Simple string path
+@Get("/users")
+async findAll() { }
+
+// Object with body validation
+@Post({ path: "/users", body: CreateUserDTO })
+async create(@Body() body: CreateUserType) { }
+
+// Object with multiple validations
+@Post({
+  path: "/:id1/:id2",
+  body: CreateUserDTO,
+  params: MultiParamDto,
+  query: UserQueryDto
+})
+async create(@Body() body, @Param("id1") id1, @Query() query) { }
 ```
 
 ### Parameter Decorators
 
 ```typescript
-@Param(key?: string)       // Route parameters
-@Body()                    // Request body
-@Query(key?: string)       // Query parameters
-@Headers(key?: string)     // Request headers
-@Req()                     // Full request object
-@Res()                     // Full response object
+@Param(key?: string)       // Route parameters (single or all)
+@Body()                    // Request body (validated by decorator schema)
+@Query(key?: string)       // Query parameters (single or all)
+@Headers(key?: string)     // Request headers (single or all)
+@Req()                     // Full Elysia request object
+@Res()                     // Full Elysia response object
 ```
 
 ### Route Options
@@ -299,40 +354,6 @@ That's it! 🎉
 
 WynkJS provides powerful CLI tools to speed up your development workflow:
 
-### 📦 create-wynkjs - Project Scaffolding
-
-Quickly scaffold a new WynkJS project with best practices:
-
-```bash
-# Create a new project
-bunx create-wynkjs
-# or
-npx create-wynkjs
-```
-
-**What you get:**
-
-- ✅ **TypeScript** - Strict mode with decorators enabled (mandatory)
-- ✅ **ESLint** - Code linting with TypeScript rules (optional)
-- ✅ **Prettier** - Code formatting (optional)
-- ✅ **Husky** - Git hooks for pre-commit checks (optional)
-- ✅ **Hot Reload** - `bun --watch` for instant feedback
-- ✅ **Working Example** - Complete CRUD controller, service, and DTOs
-
-**Example:**
-
-```bash
-bunx create-wynkjs
-# Choose project name: my-api
-# Add ESLint? Yes
-# Add Prettier? Yes
-# Add Husky? No
-
-cd my-api
-bun run dev
-# 🚀 Server running on http://localhost:3000
-```
-
 ### ⚡ wynkjs-cli - Code Generator
 
 Generate modules, controllers, services, and DTOs instantly:
@@ -349,26 +370,26 @@ bun add -D wynkjs-cli
 
 ```bash
 # Generate complete CRUD module (controller + service + DTO)
-wynkjs generate module product
-# or short: wynkjs g m product
+wynkjs-cli generate module product
+# or short: wynkjs-cli g m product
 
 # Generate controller only (all HTTP methods)
-wynkjs generate controller user
-# or short: wynkjs g c user
+wynkjs-cli generate controller user
+# or short: wynkjs-cli g c user
 
 # Generate service only (all CRUD methods)
-wynkjs generate service order
-# or short: wynkjs g s order
+wynkjs-cli generate service order
+# or short: wynkjs-cli g s order
 
 # Generate DTO only (Create, Update, ID DTOs)
-wynkjs generate dto payment
-# or short: wynkjs g d payment
+wynkjs-cli generate dto payment
+# or short: wynkjs-cli g d payment
 ```
 
 **What it generates:**
 
 ```bash
-wynkjs g m product
+wynkjs-cli g m product
 # Creates:
 # src/modules/product/
 #   ├── product.controller.ts   # Full CRUD controller
@@ -450,6 +471,45 @@ Create `wynkjs.config.json` in your project root:
 
 ## 🎯 Features & Examples
 
+### 🌐 Built-in CORS Support
+
+WynkJS includes built-in CORS support - no additional packages needed!
+
+```typescript
+import { WynkFactory, CorsOptions } from "wynkjs";
+
+// Simple: Allow all origins (development)
+const app = WynkFactory.create({
+  controllers: [UserController],
+  cors: true,
+});
+
+// Advanced: Custom CORS with specific origins (production)
+const corsOptions: CorsOptions = {
+  origin: ["https://yourdomain.com", "https://app.yourdomain.com"],
+  credentials: true,
+  methods: ["GET", "POST", "PUT", "DELETE"],
+  allowedHeaders: ["Content-Type", "Authorization"],
+  maxAge: 86400, // 24 hours
+};
+
+const app = WynkFactory.create({
+  controllers: [UserController],
+  cors: corsOptions,
+});
+
+// Dynamic origin validation (NestJS-style)
+const corsOptions: CorsOptions = {
+  origin: (origin: string) => {
+    const allowedOrigins = ["https://yourdomain.com"];
+    return allowedOrigins.includes(origin);
+  },
+  credentials: true,
+};
+```
+
+See [CORS.md](./CORS.md) for complete documentation.
+
 ### 🔒 Authentication with Guards
 
 ```typescript
@@ -561,7 +621,65 @@ export class UserController {
 
 - Capital: `Injectable`, `Inject`, `Singleton`, `AutoInjectable`, `Container`
 
-### 🗃️ Database Integration (Drizzle ORM)
+### � Provider System
+
+WynkJS providers are singleton services that initialize when your app starts. Perfect for database connections, configuration, and external services:
+
+```typescript
+import { Injectable, singleton } from "wynkjs";
+import { drizzle } from "drizzle-orm/bun-sqlite";
+import { Database } from "bun:sqlite";
+
+@Injectable()
+@singleton()
+export class DatabaseService {
+  public db: any;
+  private sqlite: Database;
+
+  // Called automatically when app starts
+  async onModuleInit() {
+    console.log("🔌 Connecting to database...");
+    this.sqlite = new Database("mydb.sqlite", { create: true });
+    this.db = drizzle(this.sqlite);
+    console.log("✅ Database connected");
+  }
+
+  getDb() {
+    return this.db;
+  }
+}
+
+// Register provider in factory
+const app = WynkFactory.create({
+  providers: [DatabaseService], // ✅ Initialized on startup
+  controllers: [UserController],
+});
+
+// Use in controllers/services
+@Injectable()
+@Controller("/users")
+export class UserController {
+  constructor(private dbService: DatabaseService) {}
+
+  @Get("/")
+  async findAll() {
+    const db = this.dbService.getDb();
+    return await db.select().from(userTable);
+  }
+}
+```
+
+**Benefits:**
+
+- ✅ **Automatic Initialization**: Providers init before routes are registered
+- ✅ **Error Handling**: App won't start if provider fails to initialize
+- ✅ **Tight Coupling**: Only registered providers are available
+- ✅ **Lifecycle Hooks**: `onModuleInit()` for setup, `onModuleDestroy()` for cleanup
+- ✅ **Type Safety**: Full TypeScript support with DI
+
+**See [docs-wynkjs/PROVIDERS.md](./docs-wynkjs/PROVIDERS.md) for complete guide**
+
+### �🗃️ Database Integration (Drizzle ORM)
 
 ```typescript
 import { drizzle } from "drizzle-orm/bun-sqlite";
@@ -592,25 +710,38 @@ export class UserService {
 
 ### 📝 Request Validation
 
-WynkJS provides automatic request validation with **full IntelliSense support** and customizable error formats:
+WynkJS provides automatic request validation with **full IntelliSense support**, **custom error messages**, and customizable error formats:
 
 ```typescript
 // user.dto.ts
 import { DTO, CommonDTO } from "wynkjs";
 
 // ✨ Full IntelliSense when typing DTO.String(), DTO.Number(), etc!
+// ✨ Add custom error messages with the `error` property
 export const CreateUserDTO = DTO.Strict({
-  name: DTO.Optional(DTO.String({ minLength: 2, maxLength: 50 })),
+  name: DTO.Optional(
+    DTO.String({
+      minLength: 2,
+      maxLength: 50,
+      error: "Name must be between 2 and 50 characters",
+    })
+  ),
   email: CommonDTO.Email({
     description: "User email address",
+    error: "Please provide a valid email address",
   }),
   mobile: DTO.Optional(
     DTO.String({
       pattern: "^[6-9]{1}[0-9]{9}$",
-      errorMessage: "Invalid mobile number",
+      error: "Invalid mobile number format",
+    })
+  ),
+  age: DTO.Optional(
+    DTO.Number({
+      minimum: 18,
+      error: "Age must be at least 18 years",
     })
   ),
-  age: DTO.Optional(DTO.Number({ minimum: 18 })),
 });
 
 export interface CreateUserType {
@@ -621,8 +752,19 @@ export interface CreateUserType {
 }
 
 export const UserUpdateDTO = DTO.Strict({
-  email: DTO.Optional(DTO.String({ format: "email", minLength: 5 })),
-  age: DTO.Optional(DTO.Number({ minimum: 18 })),
+  email: DTO.Optional(
+    DTO.String({
+      format: "email",
+      minLength: 5,
+      error: "Email must be valid and at least 5 characters",
+    })
+  ),
+  age: DTO.Optional(
+    DTO.Number({
+      minimum: 18,
+      error: "Age must be at least 18 years",
+    })
+  ),
 });
 
 export interface UserUpdateType {
@@ -659,45 +801,147 @@ export class UserController {
 
 **Customize validation error format:**
 
+WynkJS provides three built-in **formatters** for validation errors:
+
 ```typescript
-import { WynkFactory, FormatErrorFormatter } from "wynkjs";
+import {
+  WynkFactory,
+  FormatErrorFormatter, // Object-based { field: ["messages"] }
+  SimpleErrorFormatter, // Simple array ["message1", "message2"]
+  DetailedErrorFormatter, // Detailed with field info
+} from "wynkjs";
 
 const app = WynkFactory.create({
   controllers: [UserController],
   // Choose your validation error format
-  validationErrorFormatter: new FormatErrorFormatter(), // NestJS-style (recommended)
-  // validationErrorFormatter: new SimpleErrorFormatter(), // Simple array
-  // validationErrorFormatter: new DetailedErrorFormatter(), // Detailed with paths
+  validationErrorFormatter: new DetailedErrorFormatter(), // ✅ Recommended
 });
+```
 
-@Controller("/users")
-export class UserController {
-  @Post({
-    path: "/",
-    body: CreateUserDTO,
-  })
-  async create(@Body() body: any) {
-    // Body is automatically validated!
-    return { message: "User created", data: body };
-  }
-}
+**Available formatters:**
 
-// Choose your validation error format
-const app = WynkFactory.create({
-  controllers: [UserController],
-  // Option 1: Default format (recommended)
-  // validationErrorFormatter: new FormatErrorFormatter(), // NestJS-style
-  // Option 2: Simple array format
-  // validationErrorFormatter: new SimpleErrorFormatter(),
-  // Option 3: Detailed format with field info
-  // validationErrorFormatter: new DetailedErrorFormatter(),
+1. **FormatErrorFormatter** (Object-based):
+
+   ```json
+   {
+     "statusCode": 400,
+     "message": "Validation failed",
+     "errors": {
+       "email": ["Invalid email address"],
+       "age": ["Must be at least 18"]
+     }
+   }
+   ```
+
+2. **SimpleErrorFormatter** (Simple array):
+
+   ```json
+   {
+     "statusCode": 400,
+     "message": "Validation failed",
+     "errors": ["Invalid email address", "Must be at least 18"]
+   }
+   ```
+
+3. **DetailedErrorFormatter** (Detailed):
+   ```json
+   {
+     "statusCode": 400,
+     "message": "Validation failed",
+     "errors": [
+       {
+         "field": "email",
+         "message": "Invalid email address",
+         "value": "invalid-email"
+       }
+     ]
+   }
+   ```
+
+**Note:** Formatters are for **validation errors only** (from DTO validation). For runtime exception handling, use **exception filters** - see [Exception Handling](#-exception-handling) section.
+
+**See [docs-wynkjs/VALIDATION_FORMATTERS.md](./docs-wynkjs/VALIDATION_FORMATTERS.md) for all available error formats**
+
+### ✨ Custom Validation Error Messages
+
+WynkJS supports custom error messages at the DTO level using the `error` or `errorMessage` property. This allows you to provide user-friendly error messages instead of the default TypeBox validation messages:
+
+```typescript
+// user.dto.ts
+import { DTO, CommonDTO } from "wynkjs";
+
+export const CreateUserDTO = DTO.Strict({
+  name: DTO.String({
+    minLength: 2,
+    maxLength: 50,
+    error: "Name must be between 2 and 50 characters", // ✨ Custom message
+  }),
+  email: CommonDTO.Email({
+    error: "Invalid email address", // ✨ Custom message
+  }),
+  mobile: DTO.String({
+    pattern: "^[6-9]{1}[0-9]{9}$",
+    error: "Invalid mobile number", // ✨ Custom message
+  }),
+  age: DTO.Number({
+    minimum: 18,
+    error: "You must be at least 18 years old", // ✨ Custom message
+  }),
 });
 ```
 
-**See [VALIDATION_FORMATTERS.md](./docs-wynkjs/VALIDATION_FORMATTERS.md) for all available error formats**
+**Example response with invalid data:**
+
+```bash
+curl -X POST http://localhost:3000/users \
+  -H "Content-Type: application/json" \
+  -d '{"name":"A","email":"invalid","mobile":"1234567890","age":15}'
+```
+
+**Response:**
+
+```json
+{
+  "statusCode": 400,
+  "message": "Validation failed",
+  "errors": [
+    { "field": "name", "message": "Name must be between 2 and 50 characters" },
+    { "field": "email", "message": "Invalid email address" },
+    { "field": "mobile", "message": "Invalid mobile number" },
+    { "field": "age", "message": "You must be at least 18 years old" }
+  ]
+}
+```
+
+**Without custom messages, you would get generic TypeBox messages:**
+
+```json
+{
+  "errors": [
+    {
+      "field": "name",
+      "message": "Expected string length greater or equal to 2"
+    },
+    { "field": "email", "message": "Expected string to match email format" },
+    {
+      "field": "mobile",
+      "message": "Expected string to match '^[6-9]{1}[0-9]{9}$'"
+    },
+    { "field": "age", "message": "Expected number greater or equal to 18" }
+  ]
+}
+```
+
+**Note:** You can use either `error` or `errorMessage` property - both work the same way.
 
 ### 🚫 Exception Handling
 
+WynkJS provides a powerful exception handling system with **formatters** for validation errors and **filters** for runtime exceptions.
+
+#### Exception Classes
+
+Throw HTTP exceptions anywhere in your code:
+
 ```typescript
 import { Controller, Get, Param, NotFoundException } from "wynkjs";
 
@@ -721,7 +965,101 @@ export class UserController {
 - `UnauthorizedException` - 401
 - `ForbiddenException` - 403
 - `NotFoundException` - 404
+- `ConflictException` - 409
 - `InternalServerErrorException` - 500
+- And many more...
+
+#### Validation Error Formatting
+
+Format validation errors using **formatters** (passed to factory options):
+
+```typescript
+import { WynkFactory, DetailedErrorFormatter } from "wynkjs";
+
+const app = WynkFactory.create({
+  controllers: [UserController],
+  validationErrorFormatter: new DetailedErrorFormatter(), // ✅ For validation
+});
+```
+
+**Available formatters:**
+
+- `FormatErrorFormatter` - Object format `{ field: ["messages"] }`
+- `SimpleErrorFormatter` - Simple array `["message1", "message2"]`
+- `DetailedErrorFormatter` - Detailed with field info
+
+#### Global Exception Filters
+
+Handle runtime exceptions using **global filters**:
+
+```typescript
+import {
+  WynkFactory,
+  DatabaseExceptionFilter,
+  NotFoundExceptionFilter,
+  GlobalExceptionFilter,
+} from "wynkjs";
+
+const app = WynkFactory.create({
+  controllers: [UserController],
+  validationErrorFormatter: new DetailedErrorFormatter(),
+});
+
+// Register global exception filters
+app.useGlobalFilters(
+  new DatabaseExceptionFilter(), // Handles database errors
+  new NotFoundExceptionFilter(), // Smart 404 handling with response data checking
+  new GlobalExceptionFilter() // Catch-all for other exceptions
+);
+```
+
+**Available global filters:**
+
+- `DatabaseExceptionFilter` - Catches database errors (unique constraints, foreign keys, etc.)
+- `NotFoundExceptionFilter` - Smart filter that only formats truly empty 404 responses
+- `FileUploadExceptionFilter` - Handles file upload errors
+- `GlobalExceptionFilter` - Catch-all for unhandled exceptions
+
+**What's the difference?**
+
+| Feature          | Formatters                                         | Filters                    |
+| ---------------- | -------------------------------------------------- | -------------------------- |
+| **Purpose**      | Format validation errors                           | Handle runtime exceptions  |
+| **When?**        | During request validation (TypeBox)                | When exceptions are thrown |
+| **Registration** | `WynkFactory.create({ validationErrorFormatter })` | `app.useGlobalFilters()`   |
+| **Example**      | `FormatErrorFormatter`                             | `DatabaseExceptionFilter`  |
+
+#### Custom Exception Filters
+
+Create your own filters for specific routes:
+
+```typescript
+import { WynkExceptionFilter, ExecutionContext, Catch } from "wynkjs";
+
+@Catch() // Catches all exceptions
+export class CustomExceptionFilter implements WynkExceptionFilter {
+  catch(exception: any, context: ExecutionContext) {
+    const request = context.getRequest();
+
+    return {
+      statusCode: exception.statusCode || 500,
+      message: exception.message,
+      timestamp: new Date().toISOString(),
+      path: request.url,
+    };
+  }
+}
+
+// Use globally
+app.useGlobalFilters(new CustomExceptionFilter());
+
+// Or on specific controllers/routes
+@UseFilters(CustomExceptionFilter)
+@Controller("/api")
+export class ApiController {}
+```
+
+**See [ARCHITECTURE.md](./ARCHITECTURE.md) for complete architecture details**
 
 ### 🔄 Multiple Params and Query Validation
 
@@ -821,157 +1159,71 @@ my-wynk-app/
 
 ---
 
-## 🎨 Complete Working Example
-
-Here's a complete, production-ready example with all features:
-
-```typescript
-// dto/user.dto.ts
-import { DTO, CommonDTO } from "wynkjs";
-
-export const CreateUserDTO = DTO.Strict({
-  name: DTO.Optional(DTO.String({ minLength: 2, maxLength: 50 })),
-  email: CommonDTO.Email({ description: "User email address" }),
-  mobile: DTO.Optional(
-    DTO.String({
-      pattern: "^[6-9]{1}[0-9]{9}$",
-      errorMessage: "Invalid mobile number",
-    })
-  ),
-  age: DTO.Optional(DTO.Number({ minimum: 18 })),
-});
-
-export const UserIdDto = DTO.Object({
-  id: DTO.String({ minLength: 2, maxLength: 50 }),
-});
-
-export interface CreateUserType {
-  name?: string;
-  email: string;
-  mobile?: string;
-  age?: number;
-}
+## 📖 API Reference
 
-// services/email.service.ts
-import { Injectable } from "wynkjs";
+### Core Decorators
 
-@Injectable()
-export class EmailService {
-  async sendWelcomeEmail(email: string, userName: string): Promise<void> {
-    console.log(`📧 Sending welcome email to ${email}`);
-    // Your email sending logic (SendGrid, AWS SES, etc.)
-  }
-}
+#### `@Controller(basePath?: string)`
 
-// controllers/user.controller.ts
-import {
-  Controller,
-  Get,
-  Post,
-  Patch,
-  Body,
-  Param,
-  Injectable,
-  NotFoundException,
-} from "wynkjs";
-import { CreateUserDTO, UserIdDto } from "../dto/user.dto";
-import type { CreateUserType } from "../dto/user.dto";
-import { EmailService } from "../services/email.service";
+Define a controller class with optional base path.
 
-@Injectable()
+```typescript
 @Controller("/users")
 export class UserController {
-  constructor(private emailService: EmailService) {}
-
-  @Get("/")
-  async list() {
-    return { users: ["Alice", "Bob", "Charlie"] };
-  }
-
-  @Post({ path: "/", body: CreateUserDTO })
-  async create(@Body() body: CreateUserType) {
-    // Send welcome email using injected service
-    if (body.email && body.name) {
-      await this.emailService.sendWelcomeEmail(body.email, body.name);
-    }
-    return { message: "User created", data: body };
-  }
-
-  @Get({ path: "/:id", params: UserIdDto })
-  async findOne(@Param("id") id: string) {
-    if (id === "nonexistent") {
-      throw new NotFoundException("User not found");
-    }
-    return { user: { id, name: "Alice" } };
-  }
-
-  @Patch({ path: "/:id", params: UserIdDto })
-  async update(@Param("id") id: string, @Body() body: any) {
-    return { message: "User updated", id, data: body };
-  }
+  // All routes will be prefixed with /users
 }
-
-// index.ts
-import { WynkFactory } from "wynkjs";
-import { UserController } from "./controllers/user.controller";
-
-const app = WynkFactory.create({
-  controllers: [UserController],
-});
-
-await app.listen(3000);
-console.log("🚀 Server running on http://localhost:3000");
 ```
 
-**Test the API:**
+#### HTTP Method Decorators
 
-```bash
-# List all users
-curl http://localhost:3000/users
-
-# Create a new user (with validation and email)
-curl -X POST http://localhost:3000/users \
-  -H "Content-Type: application/json" \
-  -d '{"name":"Alice","email":"alice@example.com","age":25}'
-
-# Get user by ID
-curl http://localhost:3000/users/123
+All HTTP methods support both **string** and **object** formats:
 
-# Update user
-curl -X PATCH http://localhost:3000/users/123 \
-  -H "Content-Type: application/json" \
-  -d '{"email":"newemail@example.com"}'
+**String format:**
 
-# Test 404 exception
-curl http://localhost:3000/users/nonexistent
+```typescript
+@Get("/")                              // GET /users
+@Post("/")                             // POST /users
+@Patch("/:id")                         // PATCH /users/:id
 ```
 
----
+**Object format with validation:**
 
-## 📖 API Reference
+```typescript
+@Get({ path: "/" })                    // GET with options
 
-### Core Decorators
+@Post({
+  path: "/",
+  body: CreateUserDTO                  // POST with body validation
+})
 
-#### `@Controller(basePath?: string)`
+@Patch({
+  path: "/:id",
+  params: UserIdDto,                   // PATCH with param validation
+  body: UpdateUserDTO                  // PATCH with body validation
+})
 
-Define a controller class with optional base path.
+@Get({
+  path: "/",
+  query: UserQueryDto                  // GET with query validation
+})
 
-```typescript
-@Controller("/users")
-export class UserController {
-  // All routes will be prefixed with /users
-}
+@Post({
+  path: "/:id1/:id2",
+  body: CreateUserDTO,                 // Multiple validations
+  params: MultiParamDto,
+  query: UserQueryDto
+})
 ```
 
-#### `@Get(path?: string)` / `@Post()` / `@Patch()` / `@Delete()`
+**Available HTTP methods:**
 
-HTTP method decorators with optional path and options.
-
-```typescript
-@Get("/")                    // GET /users
-@Post({ path: "/", body: CreateUserDTO })  // POST with validation
-@Patch({ path: "/:id", params: UserIdDto }) // PATCH with param validation
-```
+- `@Get()` - GET requests (params, query)
+- `@Post()` - POST requests (body, params, query)
+- `@Put()` - PUT requests (body, params, query)
+- `@Patch()` - PATCH requests (body, params, query)
+- `@Delete()` - DELETE requests (params, query)
+- `@Options()` - OPTIONS requests
+- `@Head()` - HEAD requests
 
 #### `@Body()` / `@Param(key?)` / `@Query(key?)`
 
@@ -1033,60 +1285,13 @@ throw new InternalServerErrorException("Error"); // 500
 
 ---
 
-## �️ CLI Tool
-
-### create-wynkjs
-
-Quickly scaffold a new WynkJS project with best practices:
-
-```bash
-bunx create-wynkjs
-# or
-npx create-wynkjs
-```
-
-**Features:**
-
-- 🎯 Interactive project setup
-- ✅ TypeScript configuration (strict mode)
-- 🔍 ESLint with TypeScript rules
-- 💅 Prettier for code formatting
-- 🪝 Husky for Git hooks (optional)
-- 🔥 Hot reload with `bun --watch` (faster than nodemon)
-- 📝 Complete working example (CRUD API)
-
-**Generated Project Structure:**
-
-```
-my-wynkjs-app/
-├── src/
-│   ├── modules/
-│   │   └── user/
-│   │       ├── user.controller.ts
-│   │       ├── user.service.ts
-│   │       └── user.dto.ts
-│   └── index.ts
-├── .eslintrc.json
-├── .prettierrc
-├── tsconfig.json
-└── package.json
-```
-
-**Available Scripts:**
-
-- `bun run dev` - Development with hot reload
-- `bun run start` - Production server
-- `bun run build` - Build TypeScript
-- `bun run lint` - Run ESLint
-- `bun run format` - Format with Prettier
-
-[Learn more about create-wynkjs](./packages/create-wynkjs/README.md)
-
----
-
-## �🔗 Resources
+## 🔗 Resources
 
 - 📚 [Full Documentation](https://github.com/wynkjs/wynkjs-core)
+- 💡 [Example Code](./docs-wynkjs/EXAMPLE_GUIDE.md)
+- 🏗️ [Architecture Guide](./ARCHITECTURE.md) - Complete guide to formatters vs filters
+- 🔧 [Provider System](./docs-wynkjs/PROVIDERS.md) - **NEW!** Database, config, and service providers
+- 🔄 [Migration Guide](./MIGRATION.md) - Upgrading from older versions
 - 🚀 [CLI Tool (create-wynkjs)](./packages/create-wynkjs/README.md)
 - 🎨 [Validation Formatters](./docs-wynkjs/VALIDATION_FORMATTERS.md)
 - 📝 [Changelog](./CHANGELOG.md)
@@ -1127,33 +1332,21 @@ If you find a bug or have a feature request:
    bun install
    ```
 
-3. **Build the packages**
+3. **Create a branch**
 
-   ```bash
-   # Build main framework
-   bun run build
-
-   # Build CLI tools
-   cd packages/create-wynkjs && bun run build
-   cd ../wynkjs-cli && bun run build
-   ```
-
-4. **Create a branch**
    ```bash
    git checkout -b feature/your-feature-name
    # or
    git checkout -b fix/bug-description
    ```
 
-#### Development Workflow
-
-1. **Make your changes** in the appropriate package:
+4. **Make your changes** in the appropriate package:
 
    - `core/` - Core framework decorators and utilities
    - `packages/create-wynkjs/` - Project scaffolding CLI
    - `packages/wynkjs-cli/` - Code generator CLI
 
-2. **Test your changes**
+5. **Test your changes**
 
    ```bash
    # Test in the example project
@@ -1164,7 +1357,7 @@ If you find a bug or have a feature request:
    cd /tmp && bunx /path/to/wynkjs-core/packages/create-wynkjs
    ```
 
-3. **Build all packages**
+6. **Build all packages**
 
    ```bash
    # From project root
@@ -1173,7 +1366,7 @@ If you find a bug or have a feature request:
    cd ../wynkjs-cli && bun run build
    ```
 
-4. **Commit your changes**
+7. **Commit your changes**
 
    ```bash
    git add .
@@ -1191,7 +1384,7 @@ If you find a bug or have a feature request:
    - `test:` - Adding tests
    - `chore:` - Maintenance tasks
 
-5. **Push and create a Pull Request**
+8. **Push and create a Pull Request**
 
    ```bash
    git push origin feature/your-feature-name
@@ -1229,19 +1422,6 @@ Documentation improvements are always welcome!
 - **Guides**: Create helpful guides in `docs-wynkjs/`
 - **Examples**: Add real-world usage examples
 
-### 🚀 Release Process (Maintainers)
-
-1. Update `CHANGELOG.md` with changes
-2. Bump version in `package.json` files
-3. Build all packages
-4. Commit and tag the release
-5. Publish to npm:
-   ```bash
-   npm publish --access public
-   cd packages/create-wynkjs && npm publish --access public
-   cd ../wynkjs-cli && npm publish --access public
-   ```
-
 ### 💬 Community
 
 - **GitHub Discussions**: Ask questions and share ideas