wynkjs 1.0.1 → 1.0.3

package/README.md

@@ -2,15 +2,16 @@
 
 <div align="center">
 
-**A high-performance TypeScript framework built on Elysia with NestJS-style decorators**
+**A high-performance TypeScript framework built on Elysia for Bun with NestJS-style decorators**
 
 [![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_ ⚡
+_20x faster than Express, easier than NestJS, built for Bun_ ⚡
 
-[Documentation](#documentation) • [Quick Start](#quick-start) • [Examples](#examples) • [Features](#features)
+[Quick Start](#-quick-start) • [CLI Tools](#️-cli-tools) • [Features](#-features--examples) • [Documentation](#-documentation)
 
 </div>
 
@@ -18,9 +19,23 @@ _20x faster than Express, easier than NestJS_ ⚡
 
 ## About
 
-WynkJS is a modern, TypeScript-first web framework that brings NestJS-style decorators to the blazing-fast Elysia runtime. 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 Node.js or 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 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.
 
-Keywords: NestJS alternative, Elysia framework, TypeScript decorators, dependency injection (DI), guards, pipes, interceptors, exception filters, fast web framework, REST API, backend, Bun, Node.js.
+**🚀 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.
 
 ---
 
@@ -28,63 +43,171 @@ Keywords: NestJS alternative, Elysia framework, TypeScript decorators, dependenc
 
 WynkJS combines the **speed of Elysia** with the **elegant decorator syntax of NestJS**, giving you the best of both worlds:
 
-- 🚀 **20x Faster** - Built on Elysia, one of the fastest web frameworks
+- 🚀 **20x Faster** - Built on Elysia, one of the fastest web frameworks for Bun
 - 🎨 **Decorator-Based** - Familiar NestJS-style decorators
 - 💉 **Dependency Injection** - Built-in DI (no need to import reflect-metadata!)
-- 🔒 **Type-Safe** - Full TypeScript support
+- 🔒 **TypeScript First** - TypeScript is mandatory, not optional. Full type safety and IntelliSense support
 - 🎯 **Simple & Clean** - Easy to learn, powerful to use
 - 🔌 **Middleware Support** - Guards, interceptors, pipes, filters
-- ⚡ **Hot Reload** - Fast development with Bun
+- ⚡ **Bun Only** - Built exclusively for Bun runtime (not Node.js)
 - 📦 **Single Import** - Everything from `wynkjs` (Injectable, Controller, Get, etc.)
 
 ---
 
 ## 📦 Installation
 
+**Requirements:** Bun 1.0 or higher
+
+### Quick Start (Recommended)
+
+Create a new WynkJS project with all best practices:
+
 ```bash
-npm install wynkjs elysia
+bunx create-wynkjs
+# or
+npx create-wynkjs
 ```
 
-Or with Bun:
+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)
+
+### Manual Installation
+
+Add to an existing project:
 
 ```bash
 bun add wynkjs elysia
 ```
 
+**Note**: WynkJS is built specifically for **Bun**. It leverages Elysia's performance optimizations that are designed for Bun runtime. ✨
+
 ---
 
 ## 🚀 Quick Start
 
-### 1. Create Your First Controller
+### 1. Create Your DTOs (Data Transfer Objects)
 
 ```typescript
-import { Controller, Get, Post, Body, Param, Injectable } from "wynkjs";
+// 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 interface CreateUserType {
+  name?: string;
+  email?: string;
+  mobile?: string;
+  age?: number;
+}
+
+export const UserIdDto = DTO.Object({
+  id: DTO.String({ minLength: 2, maxLength: 50 }),
+});
+
+export interface ParamIdType {
+  id: string;
+}
+```
+
+### 2. Create a Service with Dependency Injection
+
+```typescript
+// email.service.ts
+import { Injectable } from "wynkjs";
+
+@Injectable()
+export class EmailService {
+  async sendWelcomeEmail(email: string, userName: string): Promise<void> {
+    console.log(`📧 Sending welcome email to ${email}`);
+    // Your email logic here
+  }
+}
+```
+
+### 3. Create Your Controller
+
+```typescript
+// user.controller.ts
+import {
+  Controller,
+  Get,
+  Post,
+  Body,
+  Param,
+  Patch,
+  Query,
+  Injectable,
+  NotFoundException,
+} from "wynkjs";
+import { CreateUserDTO, UserIdDto } from "./user.dto";
+import type { CreateUserType, ParamIdType } from "./user.dto";
+import { EmailService } from "./email.service";
 
 @Injectable()
 @Controller("/users")
 export class UserController {
+  constructor(private emailService: EmailService) {}
+
   @Get("/")
   async list() {
     return { users: ["Alice", "Bob", "Charlie"] };
   }
 
-  @Post("/")
-  async create(@Body() body: any) {
+  @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("/:id")
+  @Get({ path: "/:id", params: UserIdDto })
   async findOne(@Param("id") id: string) {
     return { user: { id, name: "Alice" } };
   }
+
+  @Patch({
+    path: "/:id",
+    params: UserIdDto,
+  })
+  async update(@Param("id") id: string, @Body() body: any) {
+    if (id === "nonexistent") {
+      throw new NotFoundException("User not found");
+    }
+
+    return { message: "User updated", id, data: body };
+  }
 }
 ```
 
-### 2. Create Your Application
+### 4. Bootstrap Your Application
 
 ```typescript
+// index.ts
 import { WynkFactory } from "wynkjs";
-import { UserController } from "./controllers/user.controller";
+import { UserController } from "./user.controller";
 
 const app = WynkFactory.create({
   controllers: [UserController],
@@ -95,12 +218,32 @@ await app.listen(3000);
 console.log("🚀 Server running on http://localhost:3000");
 ```
 
-**Note**: No need to import `reflect-metadata` - WynkJS handles it automatically! ✨
-
-### 3. Run Your Server
+### 5. Run Your Server
 
 ```bash
 bun run index.ts
+# or with --watch for hot reload
+bun --watch index.ts
+```
+
+### 6. Test Your API
+
+```bash
+# List users
+curl http://localhost:3000/users
+
+# Create user (with validation)
+curl -X POST http://localhost:3000/users \
+  -H "Content-Type: application/json" \
+  -d '{"name":"John","email":"john@example.com","age":25}'
+
+# Get user by ID
+curl http://localhost:3000/users/123
+
+# Update user
+curl -X PATCH http://localhost:3000/users/123 \
+  -H "Content-Type: application/json" \
+  -d '{"email":"newemail@example.com"}'
 ```
 
 That's it! 🎉
@@ -152,6 +295,159 @@ That's it! 🎉
 
 ---
 
+## 🛠️ CLI Tools
+
+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:
+
+```bash
+# Install globally (recommended)
+bun add -g wynkjs-cli
+
+# Or install in project
+bun add -D wynkjs-cli
+```
+
+**Commands:**
+
+```bash
+# Generate complete CRUD module (controller + service + DTO)
+wynkjs generate module product
+# or short: wynkjs g m product
+
+# Generate controller only (all HTTP methods)
+wynkjs generate controller user
+# or short: wynkjs g c user
+
+# Generate service only (all CRUD methods)
+wynkjs generate service order
+# or short: wynkjs g s order
+
+# Generate DTO only (Create, Update, ID DTOs)
+wynkjs generate dto payment
+# or short: wynkjs g d payment
+```
+
+**What it generates:**
+
+```bash
+wynkjs g m product
+# Creates:
+# src/modules/product/
+#   ├── product.controller.ts   # Full CRUD controller
+#   ├── product.service.ts      # All CRUD methods
+#   └── product.dto.ts           # Validation schemas
+```
+
+**Auto-imports:** Controllers are automatically imported and added to `src/index.ts`!
+
+**Generated Code Example:**
+
+```typescript
+// product.controller.ts - Ready to use!
+@Injectable()
+@Controller("/product")
+export class ProductController {
+  constructor(private productService: ProductService) {}
+
+  @Get("/")
+  async findAll() {
+    /* ... */
+  }
+
+  @Post({ path: "/", body: CreateProductDTO })
+  async create(@Body() body: CreateProductType) {
+    /* ... */
+  }
+
+  @Get({ path: "/:id", params: ProductIdDto })
+  async findOne(@Param("id") id: string) {
+    /* ... */
+  }
+
+  @Put({ path: "/:id", params: ProductIdDto, body: UpdateProductDTO })
+  async update(@Param("id") id: string, @Body() body: UpdateProductType) {
+    /* ... */
+  }
+
+  @Delete({ path: "/:id", params: ProductIdDto })
+  async remove(@Param("id") id: string) {
+    /* ... */
+  }
+}
+```
+
+**Full Workflow:**
+
+```bash
+# 1. Create new project
+bunx create-wynkjs
+cd my-api
+
+# 2. Generate your first module
+wynkjs g m product
+
+# 3. Start developing
+bun run dev
+
+# 4. Your API is ready!
+curl http://localhost:3000/product
+# {"data":[]}
+```
+
+**Custom Configuration** (optional):
+
+Create `wynkjs.config.json` in your project root:
+
+```json
+{
+  "srcDir": "src",
+  "controllersDir": "src/controllers",
+  "servicesDir": "src/services",
+  "dtoDir": "src/dto",
+  "modulesDir": "src/modules"
+}
+```
+
+---
+
 ## 🎯 Features & Examples
 
 ### 🔒 Authentication with Guards
@@ -211,38 +507,52 @@ export class AdminController {
 
 ### 💉 Dependency Injection
 
+WynkJS includes powerful dependency injection with **zero setup required**:
+
 ```typescript
-// Option 1: Capital-cased (recommended for consistency)
-import { Injectable, Inject, Controller, Get } from "wynkjs";
+// email.service.ts
+import { Injectable } from "wynkjs";
 
 @Injectable()
-export class UserService {
-  async findAll() {
-    return [{ id: 1, name: "Alice" }];
+export class EmailService {
+  async sendWelcomeEmail(email: string, userName: string): Promise<void> {
+    console.log(`📧 Sending welcome email to ${email}`);
+    // Your email sending logic
+  }
+
+  async sendPasswordResetEmail(
+    email: string,
+    resetToken: string
+  ): Promise<void> {
+    console.log(`🔐 Sending password reset to ${email}`);
+    // Your reset email logic
   }
 }
 
+// user.controller.ts
+import { Controller, Post, Body, Injectable } from "wynkjs";
+import { EmailService } from "./email.service";
+
 @Injectable()
 @Controller("/users")
 export class UserController {
-  constructor(private userService: UserService) {}
+  // ✨ EmailService is automatically injected!
+  constructor(private emailService: EmailService) {}
 
-  @Get("/")
-  async list() {
-    const users = await this.userService.findAll();
-    return { users };
+  @Post("/")
+  async create(@Body() body: { name: string; email: string }) {
+    // Use the injected service
+    await this.emailService.sendWelcomeEmail(body.email, body.name);
+    return { message: "User created and email sent!" };
   }
-}
-```
 
-```typescript
-// Option 2: Lowercase (tsyringe convention)
-import { Injectable, Inject, Controller, Get } from "wynkjs";
-
-@Injectable()
-export class UserService {
-  async findAll() {
-    return [{ id: 1, name: "Alice" }];
+  @Post("/send-reset-email")
+  async sendPasswordReset(@Body() body: { email: string }) {
+    await this.emailService.sendPasswordResetEmail(
+      body.email,
+      "reset-token-123"
+    );
+    return { message: "Password reset email sent" };
   }
 }
 ```
@@ -254,15 +564,15 @@ export class UserService {
 ### 🗃️ Database Integration (Drizzle ORM)
 
 ```typescript
-import { drizzle } from "drizzle-orm/node-postgres";
-import { pgTable, varchar } from "drizzle-orm/pg-core";
+import { drizzle } from "drizzle-orm/bun-sqlite";
+import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
 import { InjectTable, registerTables } from "wynkjs";
 
 // Define your table
-const userTable = pgTable("users", {
-  id: varchar("id").primaryKey(),
-  name: varchar("name").notNull(),
-  email: varchar("email").notNull().unique(),
+const userTable = sqliteTable("users", {
+  id: integer("id").primaryKey(),
+  name: text("name").notNull(),
+  email: text("email").notNull().unique(),
 });
 
 // Register tables
@@ -282,16 +592,82 @@ export class UserService {
 
 ### 📝 Request Validation
 
-WynkJS provides automatic request validation with customizable error formats:
+WynkJS provides automatic request validation with **full IntelliSense support** and customizable error formats:
 
 ```typescript
-import { Post, Body, DTO, WynkFactory, FormatErrorFormatter } from "wynkjs";
+// user.dto.ts
+import { DTO, CommonDTO } from "wynkjs";
+
+// ✨ Full IntelliSense when typing DTO.String(), DTO.Number(), etc!
+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 interface CreateUserType {
+  name?: string;
+  email?: string;
+  mobile?: string;
+  age?: number;
+}
 
-// Define your DTO with validation rules
-const CreateUserDTO = DTO.Strict({
-  name: DTO.String({ minLength: 2 }),
-  email: DTO.String({ format: "email", minLength: 5 }),
-  age: DTO.Number({ minimum: 18 }),
+export const UserUpdateDTO = DTO.Strict({
+  email: DTO.Optional(DTO.String({ format: "email", minLength: 5 })),
+  age: DTO.Optional(DTO.Number({ minimum: 18 })),
+});
+
+export interface UserUpdateType {
+  email?: string;
+  age?: number;
+}
+
+// user.controller.ts
+import { Controller, Post, Patch, Body, Param } from "wynkjs";
+import { CreateUserDTO, UserUpdateDTO } from "./user.dto";
+import type { CreateUserType, UserUpdateType } from "./user.dto";
+
+@Controller("/users")
+export class UserController {
+  @Post({
+    path: "/",
+    body: CreateUserDTO, // ✅ Automatic validation
+  })
+  async create(@Body() body: CreateUserType) {
+    // Body is validated automatically!
+    // Invalid requests get clear error messages
+    return { message: "User created", data: body };
+  }
+
+  @Patch({
+    path: "/:id",
+    body: UserUpdateDTO, // ✅ Different schema for updates
+  })
+  async update(@Param("id") id: string, @Body() body: UserUpdateType) {
+    return { message: "User updated", id, data: body };
+  }
+}
+```
+
+**Customize validation error format:**
+
+```typescript
+import { WynkFactory, FormatErrorFormatter } 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
 });
 
 @Controller("/users")
@@ -318,7 +694,70 @@ const app = WynkFactory.create({
 });
 ```
 
-**See [VALIDATION_FORMATTERS.md](./docs/VALIDATION_FORMATTERS.md) for all available error formats**
+**See [VALIDATION_FORMATTERS.md](./docs-wynkjs/VALIDATION_FORMATTERS.md) for all available error formats**
+
+### 🚫 Exception Handling
+
+```typescript
+import { Controller, Get, Param, NotFoundException } from "wynkjs";
+
+@Controller("/users")
+export class UserController {
+  @Get("/:id")
+  async findOne(@Param("id") id: string) {
+    // Built-in exceptions
+    if (id === "nonexistent") {
+      throw new NotFoundException("User not found");
+    }
+
+    return { user: { id, name: "Alice" } };
+  }
+}
+```
+
+**Built-in exceptions:**
+
+- `BadRequestException` - 400
+- `UnauthorizedException` - 401
+- `ForbiddenException` - 403
+- `NotFoundException` - 404
+- `InternalServerErrorException` - 500
+
+### 🔄 Multiple Params and Query Validation
+
+```typescript
+// user.dto.ts
+export const MultiParamDto = DTO.Object({
+  id1: DTO.String({ minLength: 2, maxLength: 50 }),
+  id2: DTO.String({ minLength: 2, maxLength: 50 }),
+});
+
+export const UserQueryDto = DTO.Strict({
+  includePosts: DTO.Optional(DTO.Boolean({ default: false })),
+  includeComments: DTO.Optional(DTO.Boolean({ default: false })),
+});
+
+// user.controller.ts
+@Post({
+  path: "/:id1/:id2",
+  body: CreateUserDTO,
+  params: MultiParamDto,  // ✅ Validates route params
+  query: UserQueryDto,     // ✅ Validates query params
+})
+async create(
+  @Body() body: CreateUserType,
+  @Param("id1") id1: string,
+  @Param("id2") id2: string,
+  @Query() query: UserQueryType
+) {
+  return {
+    message: "User created",
+    data: body,
+    params: { id1, id2 },
+    query
+  };
+}
+```
 
 ### 🔄 Multiple Middleware
 
@@ -348,217 +787,475 @@ export class ApiController {
 
 ## 🏗️ Project Structure
 
+Recommended project structure for WynkJS applications:
+
 ```
 my-wynk-app/
 ├── src/
-│   ├── controllers/
-│   │   ├── user.controller.ts
-│   │   └── auth.controller.ts
-│   ├── services/
-│   │   ├── user.service.ts
-│   │   └── auth.service.ts
-│   ├── middleware/
-│   │   ├── jwt.guard.ts
-│   │   └── roles.guard.ts
-│   ├── dto/
-│   │   └── user.dto.ts
+│   ├── modules/
+│   │   ├── user/
+│   │   │   ├── user.controller.ts
+│   │   │   ├── user.service.ts
+│   │   │   └── user.dto.ts
+│   │   └── product/
+│   │       ├── product.controller.ts
+│   │       ├── product.service.ts
+│   │       └── product.dto.ts
+│   ├── exceptions/
+│   │   └── custom.exceptions.ts
+│   ├── guards/
+│   │   └── auth.guard.ts
+│   ├── filters/
+│   │   └── http-exception.filter.ts
 │   └── index.ts
 ├── package.json
 └── tsconfig.json
 ```
 
+**Module-based Organization:**
+
+- Each feature/domain lives in its own module folder
+- Controllers, services, and DTOs are co-located
+- Easy to navigate and maintain
+- Generated automatically by `wynkjs-cli`
+
 ---
 
-## 🎨 Complete Example
+## 🎨 Complete Working Example
+
+Here's a complete, production-ready example with all features:
 
 ```typescript
-// index.ts
-import "reflect-metadata";
-import { WynkFramework } from "wynkjs";
-import { UserController } from "./controllers/user.controller";
-import { AuthController } from "./controllers/auth.controller";
+// 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 })),
+});
 
-const app = await WynkFramework.create({
-  controllers: [UserController, AuthController],
-  globalGuards: [],
-  globalInterceptors: [],
+export const UserIdDto = DTO.Object({
+  id: DTO.String({ minLength: 2, maxLength: 50 }),
 });
 
-await app.listen(3000);
-console.log("🚀 Server running on http://localhost:3000");
-```
+export interface CreateUserType {
+  name?: string;
+  email: string;
+  mobile?: string;
+  age?: number;
+}
+
+// services/email.service.ts
+import { Injectable } from "wynkjs";
+
+@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.)
+  }
+}
 
-```typescript
 // controllers/user.controller.ts
 import {
-  Injectable,
-  Inject,
   Controller,
   Get,
   Post,
-  Put,
-  Delete,
+  Patch,
   Body,
   Param,
-  Use,
+  Injectable,
+  NotFoundException,
 } from "wynkjs";
-import { UserService } from "../services/user.service";
-import { jwtGuard } from "../middleware/jwt.guard";
+import { CreateUserDTO, UserIdDto } from "../dto/user.dto";
+import type { CreateUserType } from "../dto/user.dto";
+import { EmailService } from "../services/email.service";
 
 @Injectable()
 @Controller("/users")
-@Use(jwtGuard)
 export class UserController {
-  constructor(@Inject(UserService) private userService: UserService) {}
+  constructor(private emailService: EmailService) {}
 
   @Get("/")
   async list() {
-    const users = await this.userService.findAll();
-    return { users };
+    return { users: ["Alice", "Bob", "Charlie"] };
   }
 
-  @Get("/:id")
-  async findOne(@Param("id") id: string) {
-    const user = await this.userService.findById(id);
-    return { user };
+  @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 };
   }
 
-  @Post("/")
-  async create(@Body() body: any) {
-    const user = await this.userService.create(body);
-    return { message: "User created", user };
+  @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" } };
   }
 
-  @Put("/:id")
+  @Patch({ path: "/:id", params: UserIdDto })
   async update(@Param("id") id: string, @Body() body: any) {
-    const user = await this.userService.update(id, body);
-    return { message: "User updated", user };
+    return { message: "User updated", id, data: body };
   }
+}
 
-  @Delete("/:id")
-  @HttpCode(204)
-  async delete(@Param("id") id: string) {
-    await this.userService.delete(id);
-  }
+// 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:**
+
+```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
+
+# Update user
+curl -X PATCH http://localhost:3000/users/123 \
+  -H "Content-Type: application/json" \
+  -d '{"email":"newemail@example.com"}'
+
+# Test 404 exception
+curl http://localhost:3000/users/nonexistent
+```
+
+---
+
+## 📖 API Reference
+
+### Core Decorators
+
+#### `@Controller(basePath?: string)`
+
+Define a controller class with optional base path.
+
+```typescript
+@Controller("/users")
+export class UserController {
+  // All routes will be prefixed with /users
 }
 ```
 
+#### `@Get(path?: string)` / `@Post()` / `@Patch()` / `@Delete()`
+
+HTTP method decorators with optional path and options.
+
 ```typescript
-// services/user.service.ts
+@Get("/")                    // GET /users
+@Post({ path: "/", body: CreateUserDTO })  // POST with validation
+@Patch({ path: "/:id", params: UserIdDto }) // PATCH with param validation
+```
 
-@Injectable()
-export class UserService {
-  private users = [
-    { id: "1", name: "Alice", email: "alice@example.com" },
-    { id: "2", name: "Bob", email: "bob@example.com" },
-  ];
+#### `@Body()` / `@Param(key?)` / `@Query(key?)`
 
-  async findAll() {
-    return this.users;
-  }
+Parameter extraction decorators.
 
-  async findById(id: string) {
-    return this.users.find((u) => u.id === id);
-  }
+```typescript
+async create(
+  @Body() body: CreateUserType,      // Full body
+  @Param("id") id: string,            // Single param
+  @Query() query: UserQueryType       // Full query object
+) {}
+```
 
-  async create(data: any) {
-    const user = { id: Date.now().toString(), ...data };
-    this.users.push(user);
-    return user;
-  }
+#### `@Injectable()`
 
-  async update(id: string, data: any) {
-    const index = this.users.findIndex((u) => u.id === id);
-    if (index !== -1) {
-      this.users[index] = { ...this.users[index], ...data };
-      return this.users[index];
-    }
-    return null;
-  }
+Mark a class as injectable for dependency injection.
 
-  async delete(id: string) {
-    const index = this.users.findIndex((u) => u.id === id);
-    if (index !== -1) {
-      this.users.splice(index, 1);
-    }
-  }
+```typescript
+@Injectable()
+export class EmailService {
+  // This service can be injected into controllers
 }
 ```
 
----
+### DTO Helpers
 
-## 🔧 API Reference
+#### `DTO.Strict(properties, options?)`
 
-### WynkFramework.create(options)
+Create object schema that strips additional properties.
 
-Create a new WynkJS application.
+```typescript
+const UserDTO = DTO.Strict({
+  name: DTO.String(),
+  email: DTO.String({ format: "email" }),
+});
+```
 
-**Options:**
+#### `CommonDTO` Patterns
 
-- `controllers: Array<Class>` - Array of controller classes
-- `globalGuards?: Array<Guard>` - Global guards (optional)
-- `globalInterceptors?: Array<Interceptor>` - Global interceptors (optional)
-- `globalPipes?: Array<Pipe>` - Global pipes (optional)
-- `globalFilters?: Array<Filter>` - Global exception filters (optional)
+Pre-built validation patterns for common use cases.
 
-**Returns:** Promise<WynkFramework>
+```typescript
+CommonDTO.Email(); // Email validation
+CommonDTO.Name(); // Name (2-50 chars)
+CommonDTO.Password(); // Password (min 6 chars)
+CommonDTO.UUID(); // UUID format
+CommonDTO.PhoneIN(); // Indian phone number
+```
 
-### app.listen(port, callback?)
+### Exception Classes
 
-Start the server on the specified port.
+```typescript
+throw new NotFoundException("User not found"); // 404
+throw new BadRequestException("Invalid input"); // 400
+throw new UnauthorizedException("Not authenticated"); // 401
+throw new ForbiddenException("Access denied"); // 403
+throw new InternalServerErrorException("Error"); // 500
+```
 
 ---
 
-## 🎯 Performance
+## �️ CLI Tool
 
-WynkJS is built on Elysia, which is **20x faster than Express**:
+### create-wynkjs
 
-| Framework  | Requests/sec | Latency (avg) |
-| ---------- | ------------ | ------------- |
-| **WynkJS** | **~250,000** | **~0.4ms**    |
-| Elysia     | ~250,000     | ~0.4ms        |
-| Fastify    | ~45,000      | ~2.2ms        |
-| Express    | ~12,000      | ~8.3ms        |
+Quickly scaffold a new WynkJS project with best practices:
 
-_Benchmarks may vary based on hardware and configuration_
+```bash
+bunx create-wynkjs
+# or
+npx create-wynkjs
+```
 
----
+**Features:**
 
-## 🤝 Contributing
+- 🎯 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)
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+**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
+```
 
-## 📄 License
+**Available Scripts:**
 
-MIT © Alam Jamal
+- `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)
 
 ---
 
-## 🔗 Links
+## �🔗 Resources
 
-- [GitHub Repository](https://github.com/alamjamal/wynkjs)
-- [Issue Tracker](https://github.com/alamjamal/wynkjs/issues)
-- [Elysia Documentation](https://elysiajs.com/)
-- [TypeScript Decorators](https://www.typescriptlang.org/docs/handbook/decorators.html)
+- 📚 [Full Documentation](https://github.com/wynkjs/wynkjs-core)
+- 🚀 [CLI Tool (create-wynkjs)](./packages/create-wynkjs/README.md)
+- 🎨 [Validation Formatters](./docs-wynkjs/VALIDATION_FORMATTERS.md)
+- 📝 [Changelog](./CHANGELOG.md)
+- 🐛 [Report Issues](https://github.com/wynkjs/wynkjs-core/issues)
 
 ---
 
-## 💖 Acknowledgments
+## 🤝 Contributing
+
+We welcome contributions from the community! Whether you're fixing bugs, improving documentation, or proposing new features, your help is appreciated.
 
-Built with:
+### 🐛 Reporting Issues
 
-- [Elysia](https://elysiajs.com/) - The fast web framework
-- [tsyringe](https://github.com/microsoft/tsyringe) - Dependency injection
-- [TypeScript](https://www.typescriptlang.org/) - Type safety
+If you find a bug or have a feature request:
 
----
+1. **Check existing issues** to avoid duplicates
+2. **Create a new issue** with a clear title and description
+3. **Provide details**: Steps to reproduce, expected behavior, actual behavior
+4. **Include environment info**: Bun version, OS, WynkJS version
 
-<div align="center">
+[Report an issue →](https://github.com/wynkjs/wynkjs-core/issues)
 
-**[⬆ back to top](#-wynkjs)**
+### 💡 Contributing Code
 
-Made with ❤️ by [Alam Jamal](https://github.com/alamjamal)
+#### Getting Started
 
-</div>
+1. **Fork the repository**
+
+   ```bash
+   # Fork on GitHub, then clone your fork
+   git clone https://github.com/YOUR_USERNAME/wynkjs-core.git
+   cd wynkjs-core
+   ```
+
+2. **Install dependencies**
+
+   ```bash
+   bun install
+   ```
+
+3. **Build the packages**
+
+   ```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:
+
+   - `core/` - Core framework decorators and utilities
+   - `packages/create-wynkjs/` - Project scaffolding CLI
+   - `packages/wynkjs-cli/` - Code generator CLI
+
+2. **Test your changes**
+
+   ```bash
+   # Test in the example project
+   cd example
+   bun run dev
+
+   # Test CLI generation
+   cd /tmp && bunx /path/to/wynkjs-core/packages/create-wynkjs
+   ```
+
+3. **Build all packages**
+
+   ```bash
+   # From project root
+   bun run build
+   cd packages/create-wynkjs && bun run build
+   cd ../wynkjs-cli && bun run build
+   ```
+
+4. **Commit your changes**
+
+   ```bash
+   git add .
+   git commit -m "feat: add new feature"
+   # or
+   git commit -m "fix: resolve issue with decorators"
+   ```
+
+   **Commit Convention:**
+
+   - `feat:` - New feature
+   - `fix:` - Bug fix
+   - `docs:` - Documentation changes
+   - `refactor:` - Code refactoring
+   - `test:` - Adding tests
+   - `chore:` - Maintenance tasks
+
+5. **Push and create a Pull Request**
+
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+   Then open a Pull Request on GitHub with:
+
+   - Clear description of changes
+   - Link to related issues
+   - Screenshots/examples if applicable
+
+#### Code Style
+
+- **TypeScript**: Strict mode enabled
+- **Formatting**: Use Prettier (run `bun run format` if available)
+- **Linting**: Follow ESLint rules
+- **Naming**:
+  - PascalCase for classes and interfaces
+  - camelCase for functions and variables
+  - kebab-case for file names
+
+#### Testing Guidelines
+
+- Test your changes in the `example/` directory
+- Ensure existing examples still work
+- Add new examples for new features
+- Test CLI tools in a fresh directory
+
+### 📝 Documentation
+
+Documentation improvements are always welcome!
+
+- **README updates**: Keep examples current and clear
+- **Code comments**: Add JSDoc comments for public APIs
+- **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
+- **Discord**: (Coming soon) Join our community chat
+- **Twitter**: Follow [@wynkjs](https://twitter.com/wynkjs) for updates
+
+### 📜 License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.
+
+---
+
+**Thank you for contributing to WynkJS! 🎉**
+
+```
+
+```