fragment-ts 1.0.31 → 1.0.32

package/USAGE.md

@@ -1,1439 +1,442 @@
-# Fragment Framework - Comprehensive Use Cases & Examples
+# Usage Guide
 
-## Table of Contents
+This guide demonstrates practical usage patterns for Fragment TS framework.
 
-- [Quick Start](#quick-start)
-- [Basic REST API](#basic-rest-api)
-- [Authentication & Authorization](#authentication--authorization)
-- [Database Operations](#database-operations)
-- [AI-Powered Applications](#ai-powered-applications)
-- [Dependency Injection Patterns](#dependency-injection-patterns)
-- [Advanced Routing](#advanced-routing)
-- [Custom Middleware](#custom-middleware)
-- [Testing](#testing)
-- [Production Deployment](#production-deployment)
-- [CLI Reference](#cli-reference)
-- [Best Practices](#best-practices)
-- [Troubleshooting](#troubleshooting)
+## Project Structure
 
----
-
-## Quick Start
-
-### Installation & Project Initialization
-
-```bash
-# Install Fragment CLI globally
-npm install -g fragment
-
-# Option 1: Initialize in current directory
-mkdir my-app && cd my-app
-fragment init .
-
-# Option 2: Create new directory and initialize
-fragment init my-app
-cd my-app
-
-# Option 3: Use specific template
-fragment init my-api --template=api
-
-# Option 4: Select features interactively
-fragment init my-app --features=auth,ai,database
-
-# Option 5: Skip npm install (install manually later)
-fragment init my-app --skip-install
-```
-
-**Yes, `fragment init .` initializes in the current directory!**
-
-### Start Development
-
-```bash
-# Start with hot reload (auto-restarts on file changes)
-fragment serve
-
-# Start on custom port
-fragment serve --port=4000
-
-# Start without watch mode
-fragment serve --no-watch
-
-# Build for production
-fragment build
-
-# Run production build
-npm start
 ```
-
----
-
-## Basic REST API
-
-### Use Case 1: Simple CRUD API
-
-Create a complete REST API for managing products.
-
-```bash
-# Generate complete resource (controller, service, entity, DTO, repository)
-fragment generate resource product
-
-# Or use shorthand
-fragment g resource product
+src/
+├── app.ts                 # Application entry point
+├── config/
+│   └── fragment.json      # TypeORM configuration
+├── controllers/
+│   ├── user.controller.ts
+│   └── auth.controller.ts
+├── services/
+│   ├── user.service.ts
+│   └── auth.service.ts
+├── repositories/
+│   └── user.repository.ts
+├── entities/
+│   └── user.entity.ts
+└── dtos/
+    └── create-user.dto.ts
 ```
 
-**Generated Files:**
+## Dependency Injection
 
-**src/controllers/product.controller.ts**
+### Basic Property Injection
 
 ```typescript
-import { Controller, Get, Post, Put, Delete, Body, Param } from "fragment-ts";
-import { ProductService } from "../services/product.service";
+import { Service, Autowired } from 'fragment-ts';
+import { UserRepository } from '../repositories/user.repository';
+import { LoggerService } from './logger.service';
 
-@Controller("/products")
-export class ProductController {
-  constructor(private productService: ProductService) {}
-
-  @Get()
+@Service()
+export class UserService {
+  @Autowired()
+  private userRepository!: UserRepository;
+  
+  @Autowired()
+  private logger!: LoggerService;
+  
   async findAll() {
-    return this.productService.findAll();
-  }
-
-  @Get("/:id")
-  async findOne(@Param("id") id: string) {
-    return this.productService.findOne(id);
-  }
-
-  @Post()
-  async create(@Body() body: any) {
-    return this.productService.create(body);
-  }
-
-  @Put("/:id")
-  async update(@Param("id") id: string, @Body() body: any) {
-    return this.productService.update(id, body);
-  }
-
-  @Delete("/:id")
-  async delete(@Param("id") id: string) {
-    return this.productService.delete(id);
+    this.logger.info('Fetching all users');
+    return this.userRepository.findAll();
   }
 }
 ```
 
-**src/services/product.service.ts**
+### Optional Dependencies
 
 ```typescript
-import { Service } from "fragment-ts";
-import { ProductRepository } from "../repositories/product.repository";
+import { Service, Autowired, Optional } from 'fragment-ts';
+import { CacheService } from './cache.service';
 
 @Service()
 export class ProductService {
-  constructor(private productRepository: ProductRepository) {}
-
-  async findAll() {
-    return this.productRepository.findAll();
-  }
-
-  async findOne(id: string) {
-    const product = await this.productRepository.findById(parseInt(id));
-    if (!product) {
-      throw new Error("Product not found");
+  @Autowired()
+  @Optional()
+  private cacheService?: CacheService;
+  
+  async getProduct(id: string) {
+    if (this.cacheService) {
+      const cached = await this.cacheService.get(`product:${id}`);
+      if (cached) return cached;
     }
+    
+    // Fetch from database
+    const product = await this.productRepository.findById(id);
+    
+    if (this.cacheService) {
+      await this.cacheService.set(`product:${id}`, product);
+    }
+    
     return product;
   }
-
-  async create(data: any) {
-    return this.productRepository.create(data);
-  }
-
-  async update(id: string, data: any) {
-    return this.productRepository.update(parseInt(id), data);
-  }
-
-  async delete(id: string) {
-    return this.productRepository.delete(parseInt(id));
-  }
-}
-```
-
-**src/entities/product.entity.ts**
-
-```typescript
-import { Entity, PrimaryGeneratedColumn, Column } from "typeorm";
-
-@Entity()
-export class Product {
-  @PrimaryGeneratedColumn()
-  id: number;
-
-  @Column()
-  name: string;
-
-  @Column("decimal", { precision: 10, scale: 2 })
-  price: number;
-
-  @Column({ nullable: true })
-  description: string;
-
-  @Column({ default: 0 })
-  stock: number;
-
-  @Column({ type: "timestamp", default: () => "CURRENT_TIMESTAMP" })
-  createdAt: Date;
-
-  @Column({ type: "timestamp", default: () => "CURRENT_TIMESTAMP" })
-  updatedAt: Date;
 }
 ```
 
-**Testing the API:**
-
-```bash
-# Start server
-fragment serve
-
-# Verify routes are registered
-fragment routes
-
-# Test endpoints
-curl http://localhost:3000/products
-curl -X POST http://localhost:3000/products \
-  -H "Content-Type: application/json" \
-  -d '{"name":"Laptop","price":999.99,"stock":10}'
-curl http://localhost:3000/products/1
-curl -X PUT http://localhost:3000/products/1 \
-  -H "Content-Type: application/json" \
-  -d '{"price":899.99}'
-curl -X DELETE http://localhost:3000/products/1
-```
-
----
-
-## Authentication & Authorization
-
-### Use Case 2: User Authentication System
-
-Complete authentication with JWT tokens, password hashing, and role-based access.
-
-```bash
-# Initialize with auth feature
-fragment init auth-api --features=auth,database
-cd auth-api
-
-# Generate user resource
-fragment generate resource user
-```
-
-**src/entities/user.entity.ts**
+### Value Injection (Environment Variables)
 
 ```typescript
-import { Entity, PrimaryGeneratedColumn, Column } from "typeorm";
-
-@Entity()
-export class User {
-  @PrimaryGeneratedColumn()
-  id: number;
-
-  @Column({ unique: true })
-  email: string;
-
-  @Column()
-  password: string;
-
-  @Column()
-  name: string;
-
-  @Column("simple-array", { default: "user" })
-  roles: string[];
-
-  @Column({ type: "timestamp", default: () => "CURRENT_TIMESTAMP" })
-  createdAt: Date;
-}
-```
-
-**src/services/auth.service.ts**
-
-```typescript
-import { Service } from "fragment";
-import { AuthModule, NotFoundError, UnauthorizedError } from "fragment-ts";
-import { UserRepository } from "../repositories/user.repository";
+import { Service, Value } from 'fragment-ts';
 
 @Service()
-export class AuthService {
-  constructor(private userRepository: UserRepository) {}
-
-  async register(email: string, password: string, name: string) {
-    // Hash password
-    const hashedPassword = await AuthModule.hashPassword(password);
-
-    // Create user
-    const user = await this.userRepository.create({
-      email,
-      password: hashedPassword,
-      name,
-      roles: ["user"],
-    });
-
-    // Generate token
-    const token = AuthModule.generateToken({
-      userId: user.id.toString(),
-      email: user.email,
-      roles: user.roles,
-    });
-
-    return { user: { id: user.id, email, name }, token };
-  }
-
-  async login(email: string, password: string) {
-    // Find user
-    const user = await this.userRepository.findByEmail(email);
-    if (!user) {
-      throw new UnauthorizedError("Invalid credentials");
-    }
-
-    // Verify password
-    const isValid = await AuthModule.comparePassword(password, user.password);
-    if (!isValid) {
-      throw new UnauthorizedError("Invalid credentials");
-    }
-
-    // Generate token
-    const token = AuthModule.generateToken({
-      userId: user.id.toString(),
-      email: user.email,
-      roles: user.roles,
-    });
-
-    return { user: { id: user.id, email, name: user.name }, token };
-  }
-
-  async getCurrentUser(userId: string) {
-    const user = await this.userRepository.findById(parseInt(userId));
-    if (!user) {
-      throw new NotFoundError("User not found");
-    }
-    return { id: user.id, email: user.email, name: user.name };
+export class ConfigService {
+  @Value('${PORT:3000}')
+  private port!: number;
+  
+  @Value('${DB_HOST:localhost}')
+  private dbHost!: string;
+  
+  @Value('${FEATURE_ENABLED:false}')
+  private featureEnabled!: boolean;
+  
+  getPort(): number {
+    return this.port;
+  }
+  
+  isFeatureEnabled(): boolean {
+    return this.featureEnabled;
   }
 }
 ```
 
-**src/controllers/auth.controller.ts**
+## Controllers & Routes
 
-```typescript
-import { Controller, Post, Get, Body, Req } from "fragment-ts";
-import { AuthModule } from "fragment-ts";
-import { AuthService } from "../services/auth.service";
+### Basic Controller
 
-@Controller("/auth")
-export class AuthController {
-  constructor(private authService: AuthService) {}
+```typescript
+import { Controller, Get, Post, Body, Param, Query } from 'fragment-ts';
+import { UserService } from '../services/user.service';
+import { CreateUserDto } from '../dtos/create-user.dto';
 
-  @Post("/register")
-  async register(@Body() body: any) {
-    return this.authService.register(body.email, body.password, body.name);
+@Controller('/users')
+export class UserController {
+  constructor(private userService: UserService) {}
+  
+  @Get()
+  async findAll(@Query('page') page: number = 1) {
+    return this.userService.findAll(page);
   }
-
-  @Post("/login")
-  async login(@Body() body: any) {
-    return this.authService.login(body.email, body.password);
+  
+  @Get('/:id')
+  async findById(@Param('id') id: string) {
+    return this.userService.findById(id);
   }
-}
-
-@Controller("/api")
-export class ProtectedController {
-  constructor(private authService: AuthService) {}
-
-  // Protected route - requires authentication
-  @Get("/me")
-  async getProfile(@Req() req: any) {
-    // In production, use middleware to attach user to request
-    const authHeader = req.headers.authorization;
-    if (!authHeader) {
-      throw new UnauthorizedError("Missing authorization header");
-    }
-
-    const token = authHeader.replace("Bearer ", "");
-    const payload = AuthModule.verifyToken(token);
-
-    return this.authService.getCurrentUser(payload.userId);
+  
+  @Post()
+  async create(@Body() createUserDto: CreateUserDto) {
+    return this.userService.create(createUserDto);
   }
 }
 ```
 
-**src/main.ts - Add Auth Middleware**
+### Route Parameters and Query Parameters
 
 ```typescript
-import "reflect-metadata";
-import { FragmentApplication } from "fragment-ts";
-import { FragmentWebApplication } from "fragment-ts";
-import { AuthModule } from "fragment-ts";
-
-@FragmentApplication({
-  port: 3000,
-  autoScan: true,
-})
-class Application {}
-
-async function bootstrap() {
-  const app = new FragmentWebApplication();
-
-  // Apply auth middleware to protected routes
-  const expressApp = app.getExpressApp();
-  expressApp.use("/api/*", AuthModule.authMiddleware());
-
-  // Apply role-based guards
-  expressApp.use("/admin/*", AuthModule.roleGuard("admin"));
-
-  await app.bootstrap(Application);
-}
-
-bootstrap();
-```
-
-**Testing Authentication:**
-
-```bash
-# Register
-curl -X POST http://localhost:3000/auth/register \
-  -H "Content-Type: application/json" \
-  -d '{"email":"user@example.com","password":"secret123","name":"John Doe"}'
-
-# Response: {"user":{"id":1,"email":"user@example.com","name":"John Doe"},"token":"eyJ..."}
-
-# Login
-curl -X POST http://localhost:3000/auth/login \
-  -H "Content-Type: application/json" \
-  -d '{"email":"user@example.com","password":"secret123"}'
-
-# Access protected route
-curl http://localhost:3000/api/me \
-  -H "Authorization: Bearer YOUR_TOKEN_HERE"
-```
+import { Controller, Get, Param, Query } from 'fragment-ts';
 
----
-
-## Database Operations
-
-### Use Case 3: Advanced Database Migrations
-
-```bash
-# Create migration
-fragment migrate:create AddProductCategories
-
-# Run all pending migrations
-fragment migrate:run
-
-# Check migration status
-fragment migrate:status
-
-# Revert last migration
-fragment migrate:revert
-
-# Refresh all migrations (drop and re-run - CAREFUL!)
-fragment migrate:refresh
-
-# Sync schema (development only - not for production!)
-fragment schema:sync
-
-# Drop all tables (DANGEROUS!)
-fragment schema:drop
-```
-
-**Example Migration: src/migrations/1234567890-AddProductCategories.ts**
-
-```typescript
-import {
-  MigrationInterface,
-  QueryRunner,
-  Table,
-  TableForeignKey,
-} from "typeorm";
-
-export class AddProductCategories1234567890 implements MigrationInterface {
-  async up(queryRunner: QueryRunner): Promise<void> {
-    // Create categories table
-    await queryRunner.createTable(
-      new Table({
-        name: "category",
-        columns: [
-          {
-            name: "id",
-            type: "int",
-            isPrimary: true,
-            isGenerated: true,
-            generationStrategy: "increment",
-          },
-          { name: "name", type: "varchar", isUnique: true },
-          { name: "description", type: "text", isNullable: true },
-          {
-            name: "createdAt",
-            type: "timestamp",
-            default: "CURRENT_TIMESTAMP",
-          },
-        ],
-      }),
-    );
-
-    // Add category column to products
-    await queryRunner.query(`ALTER TABLE product ADD COLUMN categoryId INT`);
-
-    // Add foreign key
-    await queryRunner.createForeignKey(
-      "product",
-      new TableForeignKey({
-        columnNames: ["categoryId"],
-        referencedTableName: "category",
-        referencedColumnNames: ["id"],
-        onDelete: "SET NULL",
-      }),
-    );
+@Controller('/products')
+export class ProductController {
+  @Get()
+  async search(
+    @Query('q') query: string,
+    @Query('category') category?: string,
+    @Query('minPrice') minPrice?: number,
+    @Query('maxPrice') maxPrice?: number
+  ) {
+    // Implementation
   }
-
-  async down(queryRunner: QueryRunner): Promise<void> {
-    // Drop foreign key first
-    const table = await queryRunner.getTable("product");
-    const foreignKey = table?.foreignKeys.find(
-      (fk) => fk.columnNames.indexOf("categoryId") !== -1,
-    );
-    if (foreignKey) {
-      await queryRunner.dropForeignKey("product", foreignKey);
-    }
-
-    // Drop column and table
-    await queryRunner.dropColumn("product", "categoryId");
-    await queryRunner.dropTable("category");
+  
+  @Get('/:id/reviews')
+  async getProductReviews(
+    @Param('id') productId: string,
+    @Query('rating') minRating?: number
+  ) {
+    // Implementation
   }
 }
 ```
 
-### Database Seeding
-
-```bash
-# Create seed
-fragment seed:create InitialData
-
-# Run all seeds
-fragment seed
-```
+## Repositories
 
-**src/seeds/InitialData.seed.ts**
+### TypeORM Repository Injection
 
 ```typescript
-import { TypeORMModule } from "fragment-ts";
-
-export default class InitialDataSeed {
-  static async run() {
-    const dataSource = TypeORMModule.getDataSource();
-
-    // Seed categories
-    await dataSource.query(`
-      INSERT INTO category (name, description) VALUES
-      ('Electronics', 'Electronic devices and accessories'),
-      ('Clothing', 'Apparel and fashion items'),
-      ('Books', 'Physical and digital books')
-    `);
-
-    // Seed products
-    await dataSource.query(`
-      INSERT INTO product (name, price, stock, categoryId) VALUES
-      ('Laptop', 999.99, 50, 1),
-      ('T-Shirt', 29.99, 200, 2),
-      ('Novel', 14.99, 100, 3)
-    `);
-
-    console.log("✅ Initial data seeded successfully");
+import { Repository, InjectRepository } from 'fragment-ts';
+import { User } from '../entities/user.entity';
+import { Repository as TypeOrmRepository } from 'typeorm';
+
+@Repository()
+export class UserRepository {
+  @InjectRepository(User)
+  private repo!: TypeOrmRepository<User>;
+  
+  async findAll(): Promise<User[]> {
+    return this.repo.find();
+  }
+  
+  async findById(id: string): Promise<User | null> {
+    return this.repo.findOneBy({ id });
+  }
+  
+  async save(user: User): Promise<User> {
+    return this.repo.save(user);
   }
 }
 ```
 
----
-
-## AI-Powered Applications
-
-### Use Case 4: AI Chat Service
-
-```bash
-# Initialize with AI feature
-fragment init ai-app --features=ai
-cd ai-app
-
-# Generate AI components
-fragment generate controller chat
-fragment generate service chat
-```
-
-**src/services/chat.service.ts**
+### Custom Repository Methods
 
 ```typescript
-import { Service } from "fragment-ts";
-import { AIModule } from "fragment-ts";
-
-@Service()
-export class ChatService {
-  private aiModule: AIModule;
-
-  constructor() {
-    this.aiModule = new AIModule({
-      openaiKey: process.env.OPENAI_API_KEY,
-      ollamaUrl: process.env.OLLAMA_URL,
-    });
-  }
-
-  async chat(message: string, history: any[] = []) {
-    const messages = [
-      { role: "system" as const, content: "You are a helpful assistant." },
-      ...history,
-      { role: "user" as const, content: message },
-    ];
-
-    const response = await this.aiModule.complete(messages, {
-      model: "gpt-3.5-turbo",
-      temperature: 0.7,
-      maxTokens: 500,
+import { Repository, InjectRepository } from 'fragment-ts';
+import { User } from '../entities/user.entity';
+import { Repository as TypeOrmRepository } from 'typeorm';
+
+@Repository()
+export class UserRepository {
+  @InjectRepository(User)
+  private repo!: TypeOrmRepository<User>;
+  
+  async findByEmail(email: string): Promise<User | null> {
+    return this.repo.findOneBy({ email });
+  }
+  
+  async findActiveUsers(): Promise<User[]> {
+    return this.repo.find({ where: { isActive: true } });
+  }
+  
+  async findWithRelations(id: string): Promise<User | null> {
+    return this.repo.findOne({
+      where: { id },
+      relations: ['orders', 'profile']
     });
-
-    return {
-      response,
-      history: [
-        ...history,
-        { role: "user", content: message },
-        { role: "assistant", content: response },
-      ],
-    };
-  }
-
-  async streamChat(message: string, onChunk: (chunk: string) => void) {
-    const messages = [
-      { role: "system" as const, content: "You are a helpful assistant." },
-      { role: "user" as const, content: message },
-    ];
-
-    await this.aiModule.streamComplete(
-      messages,
-      { model: "gpt-3.5-turbo" },
-      onChunk,
-    );
-  }
-
-  async generateEmbeddings(texts: string[]) {
-    return this.aiModule.embeddings(texts);
   }
 }
 ```
 
-**src/controllers/chat.controller.ts**
-
-```typescript
-import { Controller, Post, Body, Res } from "fragment-ts";
-import { ChatService } from "../services/chat.service";
-import { Response } from "express";
+## Conditional Components
 
-@Controller("/chat")
-export class ChatController {
-  constructor(private chatService: ChatService) {}
+### Conditional On Class
 
-  @Post("/message")
-  async sendMessage(@Body() body: any) {
-    return this.chatService.chat(body.message, body.history || []);
-  }
-
-  @Post("/stream")
-  async streamMessage(@Body() body: any, @Res() res: Response) {
-    res.setHeader("Content-Type", "text/event-stream");
-    res.setHeader("Cache-Control", "no-cache");
-    res.setHeader("Connection", "keep-alive");
-
-    await this.chatService.streamChat(body.message, (chunk) => {
-      res.write(`data: ${JSON.stringify({ chunk })}\n\n`);
-    });
-
-    res.write("data: [DONE]\n\n");
-    res.end();
-  }
-
-  @Post("/embeddings")
-  async getEmbeddings(@Body() body: any) {
-    const embeddings = await this.chatService.generateEmbeddings(body.texts);
-    return { embeddings };
-  }
+```typescript
+import { AutoConfiguration, ConditionalOnClass } from 'fragment-ts';
+import { RedisCacheService } from './redis-cache.service';
+import { Redis } from 'ioredis';
+
+@AutoConfiguration()
+@ConditionalOnClass(Redis)
+export class RedisAutoConfiguration {
+  // This configuration only loads if Redis class is available
 }
 ```
 
-**.env Configuration:**
-
-```env
-NODE_ENV=development
-PORT=3000
-OPENAI_API_KEY=sk-your-key-here
-OLLAMA_URL=http://localhost:11434
-```
-
-**Testing AI Endpoints:**
-
-```bash
-# Chat
-curl -X POST http://localhost:3000/chat/message \
-  -H "Content-Type: application/json" \
-  -d '{"message":"What is TypeScript?"}'
-
-# Stream (watch responses appear in real-time)
-curl -X POST http://localhost:3000/chat/stream \
-  -H "Content-Type: application/json" \
-  -d '{"message":"Write a short story"}' \
-  --no-buffer
-
-# Embeddings (vector representations of text)
-curl -X POST http://localhost:3000/chat/embeddings \
-  -H "Content-Type: application/json" \
-  -d '{"texts":["Hello world","Fragment Framework"]}'
-```
-
----
-
-## Dependency Injection Patterns
-
-### Use Case 5: Complex DI with Multiple Services
+### Conditional On Property
 
 ```typescript
-// src/services/email.service.ts
-import { Service } from "fragment-ts";
+import { Service, ConditionalOnProperty } from 'fragment-ts';
+import { CloudStorageService } from './cloud-storage.service';
 
 @Service()
-export class EmailService {
-  async sendEmail(to: string, subject: string, body: string) {
-    console.log(`Sending email to ${to}: ${subject}`);
-    // Email sending logic (SendGrid, Mailgun, etc.)
-    return { sent: true };
-  }
-}
-
-// src/services/notification.service.ts
-import { Service, Autowired } from "fragment-ts";
-import { EmailService } from "./email.service";
-
-@Service()
-export class NotificationService {
-  // Property injection using @Autowired
-  @Autowired()
-  private emailService: EmailService;
-
-  async notifyUser(userId: string, message: string) {
-    // Send email notification
-    await this.emailService.sendEmail(
-      `user${userId}@example.com`,
-      "Notification",
-      message,
-    );
-  }
-}
-
-// src/services/order.service.ts
-import { Service } from "fragment-ts";
-import { NotificationService } from "./notification.service";
-import { ProductRepository } from "../repositories/product.repository";
-
-@Service()
-export class OrderService {
-  // Constructor injection
-  constructor(
-    private notificationService: NotificationService,
-    private productRepository: ProductRepository,
-  ) {}
-
-  async createOrder(userId: string, productId: number, quantity: number) {
-    const product = await this.productRepository.findById(productId);
-
-    if (!product || product.stock < quantity) {
-      throw new Error("Insufficient stock");
-    }
-
-    // Update stock
-    await this.productRepository.update(productId, {
-      stock: product.stock - quantity,
-    });
-
-    // Notify user
-    await this.notificationService.notifyUser(
-      userId,
-      `Your order for ${quantity}x ${product.name} has been placed!`,
-    );
-
-    return { orderId: Date.now(), product, quantity };
-  }
+@ConditionalOnProperty('USE_CLOUD_STORAGE', 'true')
+export class CloudStorageService {
+  // Only registered if USE_CLOUD_STORAGE env var is 'true'
 }
 ```
 
----
-
-## Advanced Routing
-
-### Use Case 6: Complex Route Parameters
+### Conditional On Missing Bean
 
 ```typescript
-import {
-  Controller,
-  Get,
-  Post,
-  Param,
-  Query,
-  Header,
-  Body,
-  Req,
-  Res,
-} from "fragment-ts";
-import { Request, Response } from "express";
-
-@Controller("/api/v1/users")
-export class UserController {
-  // Nested route parameters
-  // Route: GET /api/v1/users/:userId/orders/:orderId
-  @Get("/:userId/orders/:orderId")
-  async getUserOrder(
-    @Param("userId") userId: string,
-    @Param("orderId") orderId: string,
-  ) {
-    return { userId, orderId };
-  }
-
-  // Query parameters
-  // Route: GET /api/v1/users?page=1&limit=10&sort=name
-  @Get()
-  async getUsers(
-    @Query("page") page: string,
-    @Query("limit") limit: string,
-    @Query("sort") sort: string,
-  ) {
-    return {
-      page: parseInt(page) || 1,
-      limit: parseInt(limit) || 10,
-      sort: sort || "id",
-      users: [],
-    };
-  }
-
-  // Header extraction
-  @Get("/profile")
-  async getProfile(@Header("Authorization") auth: string) {
-    return { authorized: !!auth };
-  }
+import { Service, ConditionalOnMissingBean } from 'fragment-ts';
+import { DefaultLoggerService } from './default-logger.service';
+import { LoggerService } from './logger.service.interface';
 
-  // Complex body handling
-  @Post("/bulk")
-  async bulkCreate(@Body() body: any) {
-    const users = body.users || [];
-    return { created: users.length };
-  }
-
-  // Full request/response access
-  @Get("/advanced")
-  async advancedRoute(@Req() req: Request, @Res() res: Response) {
-    res.status(200).json({
-      method: req.method,
-      path: req.path,
-      headers: req.headers,
-    });
-  }
+@Service()
+@ConditionalOnMissingBean(LoggerService)
+export class DefaultLoggerService implements LoggerService {
+  // Only registered if no other LoggerService is available
 }
 ```
 
----
-
-## Custom Middleware
+## Lifecycle Hooks
 
-### Use Case 7: Request Logging Middleware
+### PostConstruct & PreDestroy
 
 ```typescript
-// src/middlewares/logger.middleware.ts
-import { Request, Response, NextFunction } from "express";
-
-export class LoggerMiddleware {
-  use(req: Request, res: Response, next: NextFunction) {
-    const start = Date.now();
-
-    res.on("finish", () => {
-      const duration = Date.now() - start;
-      console.log(
-        `${req.method} ${req.path} - ${res.statusCode} - ${duration}ms`,
-      );
-    });
+import { Service, PostConstruct, PreDestroy } from 'fragment-ts';
+import { ConnectionPool } from './connection-pool';
 
-    next();
+@Service()
+export class DatabaseService {
+  private connectionPool!: ConnectionPool;
+  
+  @PostConstruct()
+  init() {
+    console.log('Initializing database connection pool');
+    this.connectionPool = new ConnectionPool();
+  }
+  
+  getConnection() {
+    return this.connectionPool.getConnection();
+  }
+  
+  @PreDestroy()
+  cleanup() {
+    console.log('Cleaning up database connections');
+    this.connectionPool.closeAll();
   }
 }
-
-// src/main.ts
-import "reflect-metadata";
-import { FragmentApplication, FragmentWebApplication } from "fragment-ts";
-import { LoggerMiddleware } from "./middlewares/logger.middleware";
-
-@FragmentApplication({
-  port: 3000,
-  autoScan: true,
-})
-class Application {}
-
-async function bootstrap() {
-  const app = new FragmentWebApplication();
-  const expressApp = app.getExpressApp();
-
-  // Apply middleware
-  const logger = new LoggerMiddleware();
-  expressApp.use(logger.use.bind(logger));
-
-  await app.bootstrap(Application);
-}
-
-bootstrap();
 ```
 
----
-
 ## Testing
 
-### Use Case 8: Comprehensive Testing
-
-```bash
-# Generate test file alongside controller
-fragment generate controller users
-```
-
-**test/users.spec.ts**
+### Unit Testing a Service
 
 ```typescript
-import { describe, it, expect } from "fragment-ts";
-import { DIContainer } from "fragment-ts";
-import { UserService } from "../src/services/user.service";
+import { UserService } from './user.service';
+import { UserRepository } from '../repositories/user.repository';
+import { User } from '../entities/user.entity';
 
-describe("UserService", () => {
+describe('UserService', () => {
   let userService: UserService;
-
+  let mockUserRepository: jest.Mocked<UserRepository>;
+  
   beforeEach(() => {
-    const container = DIContainer.getInstance();
-    userService = container.resolve<UserService>(UserService);
-  });
-
-  it("should create a user", async () => {
-    const user = await userService.create({
-      email: "test@example.com",
-      name: "Test User",
-      password: "password123",
+    mockUserRepository = {
+      findAll: jest.fn(),
+      findById: jest.fn(),
+      save: jest.fn()
+    } as any;
+    
+    userService = new UserService();
+    // Use reflection to set the private property
+    Object.defineProperty(userService, 'userRepository', {
+      value: mockUserRepository
     });
-
-    expect(user).toBeTruthy();
-    expect(user.email).toBe("test@example.com");
-    expect(user.name).toBe("Test User");
-  });
-
-  it("should find user by id", async () => {
-    const user = await userService.findOne("1");
-    expect(user).toBeTruthy();
-    expect(user.id).toBe(1);
   });
-
-  it("should throw error for non-existent user", async () => {
-    expect(() => userService.findOne("99999")).toThrow();
-  });
-
-  it("should update user", async () => {
-    const updated = await userService.update("1", { name: "Updated Name" });
-    expect(updated.name).toBe("Updated Name");
+  
+  describe('findAll', () => {
+    it('should return all users', async () => {
+      const mockUsers = [{ id: '1', name: 'John' }, { id: '2', name: 'Jane' }];
+      mockUserRepository.findAll.mockResolvedValue(mockUsers);
+      
+      const result = await userService.findAll();
+      
+      expect(result).toEqual(mockUsers);
+      expect(mockUserRepository.findAll).toHaveBeenCalled();
+    });
   });
 });
 ```
 
-```bash
-# Run tests
-fragment test
+## Environment Configuration
 
-# Run with coverage
-fragment test --coverage
+### fragment.json Example
 
-# Run specific test file
-fragment test test/users.spec.ts
+```json
+{
+  "type": "mysql",
+  "host": "localhost",
+  "port": 3306,
+  "username": "root",
+  "password": "password",
+  "database": "my_app",
+  "entities": ["dist/entities/**/*.js"],
+  "migrations": ["dist/migrations/**/*.js"],
+  "subscribers": ["dist/subscribers/**/*.js"],
+  "logging": true,
+  "synchronize": false,
+  "migrationsRun": true
+}
 ```
 
----
+### Environment Variables
 
-## Production Deployment
+```
+# .env file
+PORT=3000
+DB_HOST=production-db.example.com
+DB_USER=app_user
+DB_PASSWORD=secure_password
+FEATURE_FLAG_NEW_UI=true
+```
 
-### Use Case 9: Deploy to Production
+## Production Deployment
 
-**Build and Deploy**
+### Building for Production
 
 ```bash
-# Build for production
-fragment build
-
-# Verify build
-ls dist/
+# Install dependencies
+npm install
 
-# Set production environment variables
-export NODE_ENV=production
-export PORT=8080
-export DATABASE_URL=postgresql://user:pass@host:5432/db
-export JWT_SECRET=super-secret-production-key
+# Build TypeScript to JavaScript
+frg build
 
-# Run migrations
-fragment migrate:run
-
-# Start production server
+# Start the application
 npm start
 ```
 
-**Docker Deployment**
-
-**Dockerfile:**
+### Docker Configuration
 
 ```dockerfile
-FROM node:18-alpine
+FROM node:16-alpine
 
 WORKDIR /app
 
-# Copy package files
+# Copy package.json and install dependencies
 COPY package*.json ./
-
-# Install production dependencies
 RUN npm ci --only=production
 
-# Copy source code
-COPY . .
+# Copy built application
+COPY dist ./dist
+COPY fragment.json ./
 
-# Build TypeScript
-RUN npm run build
-
-# Expose port
 EXPOSE 3000
 
-# Health check
-HEALTHCHECK --interval=30s --timeout=3s \
-  CMD node -e "require('http').get('http://localhost:3000/health', (r) => process.exit(r.statusCode === 200 ? 0 : 1))"
-
-# Start application
-CMD ["npm", "start"]
-```
-
-**docker-compose.yml:**
-
-```yaml
-version: "3.8"
-
-services:
-  app:
-    build: .
-    ports:
-      - "3000:3000"
-    environment:
-      - NODE_ENV=production
-      - DATABASE_URL=postgresql://postgres:password@db:5432/myapp
-      - JWT_SECRET=your-secret-key
-    depends_on:
-      - db
-    restart: unless-stopped
-
-  db:
-    image: postgres:15-alpine
-    environment:
-      - POSTGRES_DB=myapp
-      - POSTGRES_USER=postgres
-      - POSTGRES_PASSWORD=password
-    volumes:
-      - db-data:/var/lib/postgresql/data
-    restart: unless-stopped
-
-volumes:
-  db-data:
-```
-
-```bash
-# Build and start services
-docker-compose up -d
-
-# View logs
-docker-compose logs -f app
-
-# Run migrations in container
-docker-compose exec app fragment migrate:run
-
-# Stop services
-docker-compose down
-
-# Stop and remove volumes
-docker-compose down -v
+CMD ["node", "dist/app.js"]
 ```
 
----
-
-## CLI Reference
-
-### Complete CLI Command Reference
-
-**Project Management**
-
-```bash
-fragment init [dir]              # Initialize new project
-fragment init . --features=auth  # Initialize with features in current dir
-fragment serve                   # Start development server
-fragment serve --port=4000       # Start on custom port
-fragment serve --no-watch        # Disable hot reload
-fragment build                   # Build for production
-```
-
-**Code Generation**
-
-```bash
-fragment generate <type> <name>  # Generate component
-fragment g <type> <name>         # Shorthand
-
-# Types:
-fragment generate controller users
-fragment generate service auth
-fragment generate entity product
-fragment generate repository users
-fragment generate dto create-user
-fragment generate resource product  # Generates all of the above
-
-# With options:
-fragment generate service users --with-repository
-```
-
-**Database Operations**
-
-```bash
-fragment migrate                 # Run pending migrations
-fragment migrate:create <name>   # Create new migration
-fragment migrate:run             # Run migrations
-fragment migrate:revert          # Revert last migration
-fragment migrate:refresh         # Drop and re-run all migrations
-fragment migrate:status          # Show migration status
-fragment schema:sync             # Sync schema (dev only)
-fragment schema:drop             # Drop all tables
-fragment seed                    # Run seeds
-fragment seed:create <name>      # Create seed file
-```
-
-**Diagnostics**
-
-```bash
-fragment routes                  # List all routes (auto-detect mode)
-fragment routes --env=dev        # List routes from TypeScript src/
-fragment routes --env=prod       # List routes from compiled dist/
-fragment beans                   # List all beans
-fragment beans --tree            # Show beans as tree
-fragment info                    # Show app information
-fragment config                  # Show configuration
-fragment version                 # Show Fragment version
-```
-
-### Diagnostics & Debugging
-
-**Environment-Specific Diagnostics**
-
-```bash
-# Auto-detect (prefers src/ if available, falls back to dist/)
-fragment routes
-fragment beans
-
-# Force development mode (use TypeScript source)
-fragment routes --env=dev
-fragment beans --env=dev --tree
-
-# Force production mode (use compiled JavaScript)
-fragment routes --env=prod
-fragment beans --env=prod
-
-# Show application info
-fragment info
-# Output:
-# 📊 Application Information:
-#   Name:        my-app
-#   Version:     1.0.0
-#   Node:        v18.17.0
-#   Platform:    darwin
-#   Architecture: arm64
-#   Environment: development
-#   Source:      ✓ src/
-#   Built:       ✓ dist/
-
-# View configuration
-fragment config
-# Shows contents of fragment.json
-
-# Check version
-fragment version
-# ✨ Fragment Framework v1.0.0
-```
-
----
-
-## Best Practices
-
-### Development
-
-1. **Always use decorators** - Leverage `@Controller`, `@Service`, `@Injectable` for clean architecture
-2. **Keep services focused** - One responsibility per service (Single Responsibility Principle)
-3. **Use DTOs** - Define Data Transfer Objects for request/response validation
-4. **Type everything** - Take advantage of TypeScript's type system
-5. **Use environment variables** - Never hardcode secrets or configuration
-
-### Database
-
-1. **Use migrations in production** - Never use `synchronize: true` in production
-2. **Version your migrations** - Keep migration files in version control
-3. **Test migrations** - Always test both `up` and `down` migrations
-4. **Use transactions** - Wrap related operations in database transactions
-5. **Index strategically** - Add indexes for frequently queried columns
-
-### Security
-
-1. **Hash passwords** - Always use `AuthModule.hashPassword()`
-2. **Validate input** - Use DTOs with class-validator
-3. **Rate limiting** - Implement rate limiting on public endpoints
-4. **CORS configuration** - Configure CORS appropriately for your frontend
-5. **Environment-specific secrets** - Use different secrets for dev/prod
-
-### Testing
-
-1. **Test business logic** - Focus on service and repository tests
-2. **Mock external dependencies** - Don't hit real databases or APIs in tests
-3. **Test edge cases** - Test error conditions and boundary cases
-4. **Use descriptive test names** - Make test failures easy to understand
-
-### Deployment
-
-1. **Use Docker** - Containerize your application for consistent deployments
-2. **Health checks** - Implement health check endpoints
-3. **Logging** - Use structured logging for production
-4. **Monitoring** - Set up monitoring and alerting
-5. **Backup strategy** - Regular database backups
-
----
-
 ## Troubleshooting
 
-### Common Issues and Solutions
-
-#### Issue: "Cannot find module"
-
-```bash
-# Solution: Rebuild the project
-npm run build
-fragment serve
-```
-
-#### Issue: "Port already in use"
-
-```bash
-# Solution 1: Use different port
-fragment serve --port=4000
-
-# Solution 2: Kill process using port (macOS/Linux)
-lsof -ti:3000 | xargs kill -9
-
-# Solution 3: Kill process using port (Windows)
-netstat -ano | findstr :3000
-taskkill /PID <PID> /F
-```
-
-#### Issue: "Database connection failed"
-
-```bash
-# Check configuration
-fragment config
-
-# Test connection
-fragment migrate:status
-
-# Verify DATABASE_URL
-echo $DATABASE_URL
-
-# Common fixes:
-# - Ensure database server is running
-# - Check username/password
-# - Verify database name exists
-# - Check network connectivity
-```
-
-#### Issue: "Decorators not working"
-
-```bash
-# Ensure tsconfig.json has these settings:
-{
-  "compilerOptions": {
-    "experimentalDecorators": true,
-    "emitDecoratorMetadata": true
-  }
-}
-
-# Rebuild after changes
-npm run build
-```
-
-#### Issue: "Routes not registering"
-
-```bash
-# Check if components are being scanned
-fragment routes
-
-# If no routes shown:
-# 1. Ensure files follow naming convention (*.controller.ts)
-# 2. Verify decorators are applied correctly
-# 3. Check if autoScan is enabled in @FragmentApplication
-# 4. Try manual import in main.ts
-
-# Force specific environment
-fragment routes --env=dev
-fragment routes --env=prod
-```
-
-#### Issue: "Circular dependency detected"
-
-```bash
-# Error: Circular dependency detected: UserService
-
-# Solution: Use property injection instead of constructor injection
-# Before (circular):
-@Service()
-class UserService {
-  constructor(private authService: AuthService) {}
-}
-@Service()
-class AuthService {
-  constructor(private userService: UserService) {} // Circular!
-}
-
-# After (fixed):
-@Service()
-class UserService {
-  @Autowired()
-  private authService: AuthService; // Property injection breaks cycle
-}
-```
-
-#### Issue: "Hot reload not working"
-
-```bash
-# Check if chokidar is installed
-npm install --save-dev chokidar
-
-# Restart with watch mode explicitly enabled
-fragment serve --watch
-
-# Check file watch patterns in serve command
-```
-
-#### Issue: "Migration fails"
-
-```bash
-# Revert last migration
-fragment migrate:revert
-
-# Check migration status
-fragment migrate:status
-
-# Fix migration file and re-run
-fragment migrate:run
-
-# If all else fails, drop and recreate (DEV ONLY!)
-fragment schema:drop
-fragment migrate:run
-```
-
-#### Issue: "TypeScript compilation errors"
-
-```bash
-# Check TypeScript version compatibility
-npm list typescript
-
-# Clear build artifacts
-rm -rf dist/
-npm run build
-
-# Check for conflicting type definitions
-npm list @types
-```
-
----
-
-## Performance Tips
-
-### Optimize Database Queries
-
-```typescript
-// Use eager loading to avoid N+1 queries
-const users = await userRepository.find({
-  relations: ["posts", "comments"],
-});
-
-// Use indexes for frequently queried columns
-@Entity()
-export class User {
-  @Index()
-  @Column({ unique: true })
-  email: string;
-}
-
-// Use pagination for large datasets
-const [users, total] = await userRepository.findAndCount({
-  skip: (page - 1) * limit,
-  take: limit,
-});
-```
-
-### Caching Strategies
-
-```typescript
-// In-memory cache for frequently accessed data
-@Service()
-export class CacheService {
-  private cache = new Map<string, any>();
-
-  get(key: string) {
-    return this.cache.get(key);
-  }
-
-  set(key: string, value: any, ttl: number = 3600000) {
-    this.cache.set(key, value);
-    setTimeout(() => this.cache.delete(key), ttl);
-  }
-}
-```
-
-### Connection Pooling
-
-```json
-// fragment.json
-{
-  "database": {
-    "poolSize": ${DB_POOL_SIZE},
-    "maxQueryExecutionTime": ${DB_MAX_QUERY_TIME}
-  }
-}
-```
-
----
-
-## Summary
-
-Fragment Framework provides:
-
-- ✅ **Quick project initialization** - `fragment init .` or `fragment init my-app`
-- ✅ **Hot reload development** - Automatic server restart on file changes
-- ✅ **Comprehensive CLI** - Code generation, migrations, diagnostics
-- ✅ **Built-in authentication** - JWT, password hashing, role guards
-- ✅ **Database migrations** - TypeORM integration with full migration support
-- ✅ **AI integrations** - OpenAI, Ollama, and custom providers
-- ✅ **Production-ready** - Docker, health checks, logging
-- ✅ **Type-safe DI** - Automatic dependency injection
-- ✅ **Convention over configuration** - Sensible defaults, minimal setup
-- ✅ **Environment flexibility** - Dev/prod modes with `--env` flag
-
-**Start building your next TypeScript application with Fragment today!**
-
-```bash
-npm install -g fragment
-fragment init my-app
-cd my-app
-fragment serve
-```
-
-Visit [https://fragment.digitwhale.com](https://fragment.digitwhale.com) for more documentation and examples.
+### Common Issues
+
+1. **"Cannot read properties of undefined" errors**: This typically means dependency injection failed. Check:
+   - All services/controllers have appropriate decorators (`@Service()`, `@Controller()`)
+   - TypeScript compiler option `emitDecoratorMetadata` is enabled in `tsconfig.json`
+   - All dependencies are properly registered before use
+
+2. **TypeORM connection issues**: 
+   - Verify `fragment.json` configuration is correct
+   - Ensure database is accessible from your application
+   - Check entity paths match your compiled output directory
+
+3. **Route registration problems**:
+   - Verify controller classes have `@Controller()` decorator
+   - Check route methods have appropriate HTTP decorators (`@Get()`, `@Post()`, etc.)
+   - Ensure controller classes are exported and discoverable
+
+### Debugging Tips
+
+1. Enable detailed logging by setting environment variable:
+   ```bash
+   DEBUG=fragment:* npm run dev
+   ```
+
+2. Use the container API to inspect registered components:
+   ```typescript
+   import { DIContainer } from 'fragment-ts';
+   
+   const container = DIContainer.getInstance();
+   console.log('Registered components:', container.getAllInstances());
+   ```
+
+3. Verify component scanning is working:
+   ```typescript
+   import { MetadataStorage } from 'fragment-ts';
+   
+   const storage = MetadataStorage.getInstance();
+   console.log('Discovered classes:', storage.getAllClasses());
+   console.log('Discovered methods:', storage.getAllMethods());
+   ```