wynkjs 1.0.2 → 1.0.4

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 framework built on Elysia 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 on Bun_ ⚡
 
 [Quick Start](#-quick-start) • [CLI Tools](#️-cli-tools) • [Features](#-features--examples) • [Documentation](#-documentation)
 
@@ -19,7 +19,7 @@ _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 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:**
 
@@ -35,16 +35,16 @@ Then generate your first API module:
 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, Elysia framework, 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
+- 🎨 **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
@@ -349,34 +349,31 @@ 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/
-#   ├── controllers/
-#   │   └── product.controller.ts   # Full CRUD controller
-#   ├── services/
-#   │   └── product.service.ts      # All CRUD methods
-#   └── dto/
-#       └── product.dto.ts           # Validation schemas
+#   ├── 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`!
@@ -597,8 +594,6 @@ export class UserService {
 
 WynkJS provides automatic request validation with **full IntelliSense support** and customizable error formats:
 
-> 💡 **New in v1.0.2**: Type `DTO.` and get full autocomplete! See [INTELLISENSE_GUIDE.md](./docs/INTELLISENSE_GUIDE.md)
-
 ```typescript
 // user.dto.ts
 import { DTO, CommonDTO } from "wynkjs";
@@ -664,45 +659,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:**
+
+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:
 
-// 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(),
+```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](./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";
 
@@ -726,7 +823,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/Elysia)         | 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
 
@@ -792,22 +983,38 @@ export class ApiController {
 
 ## 🏗️ Project Structure
 
+Recommended project structure for WynkJS applications:
+
 ```
 my-wynk-app/
 ├── src/
-│   ├── controllers/
-│   │   └── user.controller.ts
-│   ├── services/
-│   │   └── email.service.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/
-│   │   └── email.exceptions.ts
+│   │   └── 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 Working Example
@@ -901,13 +1108,25 @@ export class UserController {
 }
 
 // index.ts
-import { WynkFactory } from "wynkjs";
+import {
+  WynkFactory,
+  DetailedErrorFormatter,
+  GlobalExceptionFilter,
+  DatabaseExceptionFilter,
+} from "wynkjs";
 import { UserController } from "./controllers/user.controller";
 
 const app = WynkFactory.create({
   controllers: [UserController],
+  validationErrorFormatter: new DetailedErrorFormatter(), // ✅ Format validation errors
 });
 
+// Register global exception filters
+app.useGlobalFilters(
+  new DatabaseExceptionFilter(), // Handles database errors
+  new GlobalExceptionFilter() // Catch-all for other exceptions
+);
+
 await app.listen(3000);
 console.log("🚀 Server running on http://localhost:3000");
 ```
@@ -1049,12 +1268,11 @@ npx create-wynkjs
 ```
 my-wynkjs-app/
 ├── src/
-│   ├── controllers/
-│   │   └── user.controller.ts
-│   ├── services/
-│   │   └── user.service.ts
-│   ├── dto/
-│   │   └── user.dto.ts
+│   ├── modules/
+│   │   └── user/
+│   │       ├── user.controller.ts
+│   │       ├── user.service.ts
+│   │       └── user.dto.ts
 │   └── index.ts
 ├── .eslintrc.json
 ├── .prettierrc
@@ -1074,12 +1292,13 @@ my-wynkjs-app/
 
 ---
 
-## �🔗 Resources
+## 🔗 Resources
 
 - 📚 [Full Documentation](https://github.com/wynkjs/wynkjs-core)
+- 🏗️ [Architecture Guide](./ARCHITECTURE.md) - **NEW!** Complete guide to formatters vs filters
+- 🔄 [Migration Guide](./MIGRATION.md) - Upgrading from older versions
 - 🚀 [CLI Tool (create-wynkjs)](./packages/create-wynkjs/README.md)
-- 💡 [IntelliSense Guide](./docs/INTELLISENSE_GUIDE.md)
-- 🎨 [Validation Formatters](./VALIDATION_FORMATTERS.md)
+- 🎨 [Validation Formatters](./docs-wynkjs/VALIDATION_FORMATTERS.md)
 - 📝 [Changelog](./CHANGELOG.md)
 - 🐛 [Report Issues](https://github.com/wynkjs/wynkjs-core/issues)
 
@@ -1087,83 +1306,153 @@ my-wynkjs-app/
 
 ## 🤝 Contributing
 
-```
+We welcome contributions from the community! Whether you're fixing bugs, improving documentation, or proposing new features, your help is appreciated.
 
----
+### 🐛 Reporting Issues
 
-## 🔧 API Reference
+If you find a bug or have a feature request:
 
-### WynkFramework.create(options)
+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
 
-Create a new WynkJS application.
+[Report an issue →](https://github.com/wynkjs/wynkjs-core/issues)
 
-**Options:**
+### 💡 Contributing Code
 
-- `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)
+#### Getting Started
 
-**Returns:** Promise<WynkFramework>
+1. **Fork the repository**
 
-### app.listen(port, callback?)
+   ```bash
+   # Fork on GitHub, then clone your fork
+   git clone https://github.com/YOUR_USERNAME/wynkjs-core.git
+   cd wynkjs-core
+   ```
 
-Start the server on the specified port.
+2. **Install dependencies**
 
----
+   ```bash
+   bun install
+   ```
 
-## 🎯 Performance
+3. **Build the packages**
 
-WynkJS is built on Elysia, which is **20x faster than Express**:
+   ```bash
+   # Build main framework
+   bun run build
 
-| 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        |
+   # Build CLI tools
+   cd packages/create-wynkjs && bun run build
+   cd ../wynkjs-cli && bun run build
+   ```
 
-_Benchmarks may vary based on hardware and configuration_
+4. **Create a branch**
+   ```bash
+   git checkout -b feature/your-feature-name
+   # or
+   git checkout -b fix/bug-description
+   ```
 
----
+#### Development Workflow
 
-## 🤝 Contributing
+1. **Make your changes** in the appropriate package:
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+   - `core/` - Core framework decorators and utilities
+   - `packages/create-wynkjs/` - Project scaffolding CLI
+   - `packages/wynkjs-cli/` - Code generator CLI
 
----
+2. **Test your changes**
 
-## 📄 License
+   ```bash
+   # Test in the example project
+   cd example
+   bun run dev
 
-MIT © Alam Jamal
+   # Test CLI generation
+   cd /tmp && bunx /path/to/wynkjs-core/packages/create-wynkjs
+   ```
 
----
+3. **Build all packages**
 
-## 🔗 Links
+   ```bash
+   # From project root
+   bun run build
+   cd packages/create-wynkjs && bun run build
+   cd ../wynkjs-cli && bun run build
+   ```
 
-- [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)
+4. **Commit your changes**
 
----
+   ```bash
+   git add .
+   git commit -m "feat: add new feature"
+   # or
+   git commit -m "fix: resolve issue with decorators"
+   ```
 
-## 💖 Acknowledgments
+   **Commit Convention:**
 
-Built with:
+   - `feat:` - New feature
+   - `fix:` - Bug fix
+   - `docs:` - Documentation changes
+   - `refactor:` - Code refactoring
+   - `test:` - Adding tests
+   - `chore:` - Maintenance tasks
 
-- [Elysia](https://elysiajs.com/) - The fast web framework
-- [tsyringe](https://github.com/microsoft/tsyringe) - Dependency injection
-- [TypeScript](https://www.typescriptlang.org/) - Type safety
+5. **Push and create a Pull Request**
 
----
+   ```bash
+   git push origin feature/your-feature-name
+   ```
 
-<div align="center">
+   Then open a Pull Request on GitHub with:
 
-**[⬆ back to top](#-wynkjs)**
+   - Clear description of changes
+   - Link to related issues
+   - Screenshots/examples if applicable
 
-Made with ❤️ by [Alam Jamal](https://github.com/alamjamal)
+#### 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
+
+### 💬 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! 🎉**
+
+```
 
-</div>
 ```