fragment-ts 1.0.33 → 1.0.35

package/README.md

@@ -1,3 +1,5 @@
+---
+
 # Fragment TS - A Modern TypeScript Framework
 
 [![npm version](https://img.shields.io/npm/v/fragment-ts)](https://www.npmjs.com/package/fragment-ts)
@@ -15,6 +17,7 @@ Fragment TS is a lightweight, dependency injection-based framework for building
 - 🔧 **Auto-configuration**: Smart component scanning and registration
 - 🧪 **Testable Design**: Easily mock dependencies for unit testing
 - 📦 **Production Ready**: Works with compiled JavaScript and TypeScript source
+- 🛡️ **Enhancement Pipeline**: Middleware, guards, interceptors, and exception filters for advanced request processing
 
 ## Installation
 
@@ -109,7 +112,7 @@ export class UserRepository {
 
 ### 5. Configure TypeORM:
 
-```typescript
+```json
 // fragment.json
 {
   "type": "mysql",
@@ -123,6 +126,169 @@ export class UserRepository {
 }
 ```
 
+## Enhancement Pipeline
+
+Fragment TS provides a powerful request processing pipeline with four types of enhancements that can be applied at both **class** and **method** levels:
+
+### Middleware (`@FragmentMiddleware`)
+
+Apply Express-compatible middleware to log requests, handle authentication headers, or modify the request/response cycle.
+
+```typescript
+// src/middlewares/logging.middleware.ts
+import { Injectable } from 'fragment-ts';
+import { Request, Response, NextFunction } from 'express';
+
+@Injectable()
+export class LoggingMiddleware {
+  use(req: Request, res: Response, next: NextFunction): void {
+    console.log(`📥 ${req.method} ${req.path}`);
+    next();
+  }
+}
+
+// Usage
+import { Controller, Get } from 'fragment-ts';
+import { LoggingMiddleware } from '../middlewares/logging.middleware';
+
+@FragmentMiddleware(LoggingMiddleware)
+@Controller('/api')
+export class AppController {
+  @Get('/health')
+  health() {
+    return { status: 'OK' };
+  }
+}
+```
+
+### Guards (`@FragmentGuard`)
+
+Control access to routes with authorization logic. Guards run after middleware but before the route handler.
+
+```typescript
+// src/guards/auth.guard.ts
+import { Injectable } from 'fragment-ts';
+import { Request } from 'express';
+
+@Injectable()
+export class AuthGuard {
+  canActivate(req: Request): boolean {
+    const token = req.headers.authorization;
+    return token === 'Bearer valid-token';
+  }
+}
+
+// Usage
+import { Controller, Get } from 'fragment-ts';
+import { AuthGuard } from '../guards/auth.guard';
+
+@FragmentGuard(AuthGuard)
+@Controller('/secure')
+export class SecureController {
+  @Get('/data')
+  getData() {
+    return { secret: 'Protected data' };
+  }
+}
+```
+
+### Interceptors (`@FragmentInterceptor`)
+
+Transform the response data before it's sent to the client. Interceptors run after the route handler executes.
+
+```typescript
+// src/interceptors/transform.interceptor.ts
+import { Injectable } from 'fragment-ts';
+import { Request, Response } from 'express';
+
+@Injectable()
+export class TransformInterceptor {
+  intercept(req: Request, res: Response, result: any): any {
+    return {
+      success: true,
+       result,
+      timestamp: new Date().toISOString()
+    };
+  }
+}
+
+// Usage
+import { Controller, Get } from 'fragment-ts';
+import { TransformInterceptor } from '../interceptors/transform.interceptor';
+
+@FragmentInterceptor(TransformInterceptor)
+@Controller('/api')
+export class DataController {
+  @Get('/info')
+  getInfo() {
+    return { message: 'Hello World' };
+  }
+}
+```
+
+### Exception Filters (`@FragmentExceptionFilter`)
+
+Handle errors gracefully with custom error responses. Filters are checked in method → controller → application order.
+
+```typescript
+// src/filters/http-exception.filter.ts
+import { Injectable } from 'fragment-ts';
+import { Request, Response } from 'express';
+
+@Injectable()
+export class HttpExceptionFilter {
+  catch(exception: Error, req: Request, res: Response): void {
+    if (exception.name === 'ValidationError') {
+      res.status(400).json({ error: 'Validation failed', message: exception.message });
+    } else if (exception.name === 'NotFoundError') {
+      res.status(404).json({ error: 'Not found', message: exception.message });
+    } else {
+      res.status(500).json({ error: 'Internal server error' });
+    }
+  }
+}
+
+// Usage
+import { FragmentApplication } from 'fragment-ts';
+import { HttpExceptionFilter } from './filters/http-exception.filter';
+
+@FragmentApplication({
+  port: 3000,
+  autoScan: true,
+})
+@FragmentExceptionFilter(HttpExceptionFilter)
+export class Application {
+  constructor() {
+    console.log('Application starting...');
+  }
+}
+```
+
+### Combined Usage
+
+All enhancement decorators can be combined and applied at different levels:
+
+```typescript
+@FragmentMiddleware(LoggingMiddleware)
+@FragmentGuard(AuthGuard)
+@FragmentInterceptor(TransformInterceptor)
+@Controller('/api')
+export class ComplexController {
+  @Get('/public')
+  @FragmentGuard(PublicGuard) // Overrides class-level guard
+  publicData() {
+    return { message: 'Public data' };
+  }
+
+  @Post('/admin')
+  @FragmentGuard(AdminGuard) // Additional guard
+  @FragmentInterceptor(CacheInterceptor) // Additional interceptor
+  createAdminData(@Body() data: any) {
+    return { created: true, data };
+  }
+}
+```
+
 ## Running the Application
 
 ```bash
@@ -151,5 +317,4 @@ For issues and feature requests, please [open an issue](https://github.com/youru
 
 ## License
 
-MIT © [Your Name]
-```
+MIT © [Digitwhale Innovations](https://digitwhale.com)

package/USAGE.md

@@ -1,3 +1,5 @@
+---
+
 # Usage Guide
 
 This guide demonstrates practical usage patterns for Fragment TS framework.
@@ -19,8 +21,16 @@ src/
 │   └── user.repository.ts
 ├── entities/
 │   └── user.entity.ts
-└── dtos/
-    └── create-user.dto.ts
+├── dtos/
+│   └── create-user.dto.ts
+├── middlewares/
+│   └── logging.middleware.ts
+├── guards/
+│   └── auth.guard.ts
+├── interceptors/
+│   └── transform.interceptor.ts
+└── filters/
+    └── http-exception.filter.ts
 ```
 
 ## Dependency Injection
@@ -160,6 +170,282 @@ export class ProductController {
 }
 ```
 
+## Enhancement Pipeline
+
+### Middleware Implementation
+
+```typescript
+// src/middlewares/request-id.middleware.ts
+import { Injectable } from 'fragment-ts';
+import { Request, Response, NextFunction } from 'express';
+import { v4 as uuidv4 } from 'uuid';
+
+@Injectable()
+export class RequestIdMiddleware {
+  use(req: Request, res: Response, next: NextFunction): void {
+    const requestId = req.headers['x-request-id'] || uuidv4();
+    req.headers['x-request-id'] = requestId as string;
+    res.setHeader('X-Request-ID', requestId);
+    next();
+  }
+}
+
+// src/middlewares/logging.middleware.ts
+import { Injectable } from 'fragment-ts';
+import { Request, Response, NextFunction } from 'express';
+
+@Injectable()
+export class LoggingMiddleware {
+  use(req: Request, res: Response, next: NextFunction): void {
+    const start = Date.now();
+    console.log(`📥 [${req.method}] ${req.path} - ${req.ip || 'unknown'}`);
+    
+    res.on('finish', () => {
+      const duration = Date.now() - start;
+      console.log(`📤 [${req.method}] ${req.path} → ${res.statusCode} (${duration}ms)`);
+    });
+    
+    next();
+  }
+}
+```
+
+### Guard Implementation
+
+```typescript
+// src/guards/role.guard.ts
+import { Injectable } from 'fragment-ts';
+import { Request } from 'express';
+
+@Injectable()
+export class RoleGuard {
+  canActivate(req: Request): boolean {
+    const userRole = req.headers['x-user-role'];
+    const requiredRoles = ['admin', 'moderator'];
+    return requiredRoles.includes(userRole as string);
+  }
+}
+
+// src/guards/api-key.guard.ts
+import { Injectable } from 'fragment-ts';
+import { Request } from 'express';
+
+@Injectable()
+export class ApiKeyGuard {
+  canActivate(req: Request): boolean {
+    const apiKey = req.headers['x-api-key'];
+    const validKeys = process.env.VALID_API_KEYS?.split(',') || [];
+    return validKeys.includes(apiKey as string);
+  }
+}
+```
+
+### Interceptor Implementation
+
+```typescript
+// src/interceptors/cache.interceptor.ts
+import { Injectable } from 'fragment-ts';
+import { Request, Response } from 'express';
+import { CacheService } from '../services/cache.service';
+
+@Injectable()
+export class CacheInterceptor {
+  constructor(private cacheService: CacheService) {}
+  
+  async intercept(req: Request, res: Response, result: any): Promise<any> {
+    const cacheKey = `${req.method}:${req.path}`;
+    
+    // Store in cache for GET requests
+    if (req.method === 'GET') {
+      await this.cacheService.set(cacheKey, result, 300); // 5 minutes
+    }
+    
+    return result;
+  }
+}
+
+// src/interceptors/validation.interceptor.ts
+import { Injectable } from 'fragment-ts';
+import { Request, Response } from 'express';
+import { validate } from 'class-validator';
+
+@Injectable()
+export class ValidationInterceptor {
+  async intercept(req: Request, res: Response, result: any): Promise<any> {
+    // Validate response data if it's an object with validation decorators
+    if (result && typeof result === 'object' && !Array.isArray(result)) {
+      const errors = await validate(result);
+      if (errors.length > 0) {
+        console.warn('Response validation failed:', errors);
+      }
+    }
+    return result;
+  }
+}
+```
+
+### Exception Filter Implementation
+
+```typescript
+// src/filters/validation-exception.filter.ts
+import { Injectable } from 'fragment-ts';
+import { Request, Response } from 'express';
+import { ValidationError } from 'class-validator';
+
+@Injectable()
+export class ValidationExceptionFilter {
+  catch(exception: Error, req: Request, res: Response): void {
+    if (exception instanceof ValidationError) {
+      const errors = this.formatValidationErrors(exception);
+      res.status(400).json({
+        statusCode: 400,
+        error: 'Bad Request',
+        message: 'Validation failed',
+        details: errors
+      });
+    }
+  }
+  
+  private formatValidationErrors(error: ValidationError): Record<string, string[]> {
+    const errors: Record<string, string[]> = {};
+    for (const constraint of Object.values(error.constraints || {})) {
+      const property = error.property;
+      if (!errors[property]) errors[property] = [];
+      errors[property].push(constraint);
+    }
+    return errors;
+  }
+}
+
+// src/filters/database-exception.filter.ts
+import { Injectable } from 'fragment-ts';
+import { Request, Response } from 'express';
+
+@Injectable()
+export class DatabaseExceptionFilter {
+  catch(exception: Error, req: Request, res: Response): void {
+    if (exception.name === 'QueryFailedError' || exception.message.includes('database')) {
+      res.status(500).json({
+        statusCode: 500,
+        error: 'Database Error',
+        message: 'An error occurred while accessing the database'
+      });
+    }
+  }
+}
+```
+
+### Applying Enhancements
+
+#### Class-Level Enhancements
+
+```typescript
+import { Controller, Get } from 'fragment-ts';
+import { LoggingMiddleware } from '../middlewares/logging.middleware';
+import { AuthGuard } from '../guards/auth.guard';
+import { TransformInterceptor } from '../interceptors/transform.interceptor';
+import { HttpExceptionFilter } from '../filters/http-exception.filter';
+
+@FragmentMiddleware(LoggingMiddleware)
+@FragmentGuard(AuthGuard)
+@FragmentInterceptor(TransformInterceptor)
+@FragmentExceptionFilter(HttpExceptionFilter)
+@Controller('/api/v1')
+export class ApiController {
+  @Get('/users')
+  async getUsers() {
+    return [{ id: 1, name: 'John' }];
+  }
+  
+  @Get('/status')
+  async getStatus() {
+    return { status: 'healthy' };
+  }
+}
+```
+
+#### Method-Level Enhancements
+
+```typescript
+import { Controller, Get, Post, Body } from 'fragment-ts';
+import { ApiKeyGuard } from '../guards/api-key.guard';
+import { CacheInterceptor } from '../interceptors/cache.interceptor';
+import { ValidationExceptionFilter } from '../filters/validation-exception.filter';
+import { CreateUserDto } from '../dtos/create-user.dto';
+
+@Controller('/api')
+export class UserController {
+  @Get('/public-data')
+  @FragmentGuard(ApiKeyGuard) // Only this method requires API key
+  getPublicData() {
+    return { data: 'public information' };
+  }
+  
+  @Get('/users')
+  @FragmentInterceptor(CacheInterceptor) // Cache only this endpoint
+  async getUsers() {
+    // Fetch from database
+    return [{ id: 1, name: 'John' }];
+  }
+  
+  @Post('/users')
+  @FragmentExceptionFilter(ValidationExceptionFilter) // Specific error handling
+  async createUser(@Body() userData: CreateUserDto) {
+    // Create user logic
+    return { id: 1, ...userData };
+  }
+}
+```
+
+#### Mixed Class and Method Enhancements
+
+```typescript
+@FragmentMiddleware(LoggingMiddleware)
+@FragmentGuard(AuthGuard) // Applied to all methods
+@Controller('/admin')
+export class AdminController {
+  @Get('/dashboard')
+  getDashboard() {
+    // Uses both LoggingMiddleware and AuthGuard
+    return { dashboard: 'data' };
+  }
+  
+  @Get('/public-stats')
+  @FragmentGuard(PublicGuard) // Overrides class-level AuthGuard
+  getPublicStats() {
+    // Uses LoggingMiddleware and PublicGuard (not AuthGuard)
+    return { stats: 'public' };
+  }
+  
+  @Post('/settings')
+  @FragmentInterceptor(AuditInterceptor) // Additional interceptor
+  updateSettings(@Body() settings: any) {
+    // Uses LoggingMiddleware, AuthGuard, and AuditInterceptor
+    return { updated: true };
+  }
+}
+```
+
+#### Application-Level Exception Filters
+
+```typescript
+import { FragmentApplication } from 'fragment-ts';
+import { GlobalExceptionFilter } from './filters/global-exception.filter';
+import { DatabaseExceptionFilter } from './filters/database-exception.filter';
+
+@FragmentApplication({
+  port: 3000,
+  autoScan: true
+})
+@FragmentExceptionFilter(DatabaseExceptionFilter)
+@FragmentExceptionFilter(GlobalExceptionFilter)
+export class Application {
+  constructor() {
+    console.log('Application starting...');
+  }
+}
+```
+
 ## Repositories
 
 ### TypeORM Repository Injection
@@ -331,6 +617,101 @@ describe('UserService', () => {
 });
 ```
 
+### Testing Guards
+
+```typescript
+import { AuthGuard } from '../guards/auth.guard';
+
+describe('AuthGuard', () => {
+  let guard: AuthGuard;
+  
+  beforeEach(() => {
+    guard = new AuthGuard();
+  });
+  
+  it('should allow valid tokens', () => {
+    const mockReq = { headers: { authorization: 'Bearer valid-token' } } as any;
+    expect(guard.canActivate(mockReq)).toBe(true);
+  });
+  
+  it('should reject invalid tokens', () => {
+    const mockReq = { headers: { authorization: 'Bearer invalid' } } as any;
+    expect(guard.canActivate(mockReq)).toBe(false);
+  });
+  
+  it('should reject missing tokens', () => {
+    const mockReq = { headers: {} } as any;
+    expect(guard.canActivate(mockReq)).toBe(false);
+  });
+});
+```
+
+### Testing Interceptors
+
+```typescript
+import { TransformInterceptor } from '../interceptors/transform.interceptor';
+
+describe('TransformInterceptor', () => {
+  let interceptor: TransformInterceptor;
+  let mockReq: any;
+  let mockRes: any;
+  
+  beforeEach(() => {
+    interceptor = new TransformInterceptor();
+    mockReq = { path: '/test', method: 'GET' };
+    mockRes = {};
+  });
+  
+  it('should wrap result with metadata', () => {
+    const originalResult = { data: 'test' };
+    const result = interceptor.intercept(mockReq, mockRes, originalResult);
+    
+    expect(result).toHaveProperty('success', true);
+    expect(result).toHaveProperty('data', originalResult);
+    expect(result).toHaveProperty('timestamp');
+  });
+});
+```
+
+### Integration Testing with Enhancements
+
+```typescript
+import request from 'supertest';
+import { FragmentWebApplication } from 'fragment-ts';
+import { Application } from '../app';
+
+describe('API with Enhancements', () => {
+  let app: FragmentWebApplication;
+  
+  beforeAll(async () => {
+    app = new FragmentWebApplication();
+    await app.bootstrap(Application);
+  });
+  
+  it('should log requests with middleware', async () => {
+    const consoleSpy = jest.spyOn(console, 'log').mockImplementation();
+    
+    await request(app.getExpressApp())
+      .get('/api/status')
+      .expect(200);
+    
+    expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('📥 [GET] /api/status'));
+    consoleSpy.mockRestore();
+  });
+  
+  it('should require authentication with guard', async () => {
+    await request(app.getExpressApp())
+      .get('/admin/dashboard')
+      .expect(403); // Assuming guard returns false without proper auth
+  
+    await request(app.getExpressApp())
+      .get('/admin/dashboard')
+      .set('Authorization', 'Bearer valid-token')
+      .expect(200);
+  });
+});
+```
+
 ## Environment Configuration
 
 ### fragment.json Example
@@ -361,6 +742,7 @@ DB_HOST=production-db.example.com
 DB_USER=app_user
 DB_PASSWORD=secure_password
 FEATURE_FLAG_NEW_UI=true
+VALID_API_KEYS=key1,key2,key3
 ```
 
 ## Production Deployment
@@ -417,6 +799,11 @@ CMD ["node", "dist/app.js"]
    - Check route methods have appropriate HTTP decorators (`@Get()`, `@Post()`, etc.)
    - Ensure controller classes are exported and discoverable
 
+4. **Enhancement decorators not working**:
+   - Ensure enhancement classes have `@Injectable()` or similar decorator
+   - Verify enhancement classes implement the correct interface
+   - Check that metadata is being stored as arrays (not single values)
+
 ### Debugging Tips
 
 1. Enable detailed logging by setting environment variable:
@@ -440,3 +827,9 @@ CMD ["node", "dist/app.js"]
    console.log('Discovered classes:', storage.getAllClasses());
    console.log('Discovered methods:', storage.getAllMethods());
    ```
+
+4. Debug enhancement pipeline execution:
+   ```typescript
+   // Add console logs to your middleware/guards/interceptors
+   // to verify they're being called in the expected order
+   ```

package/dist/cli/commands/build.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build.command.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/build.command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAOpC,qBAAa,YAAY;IACvB,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;WAW1B,OAAO,CAAC,OAAO,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IA8CjD,OAAO,CAAC,MAAM,CAAC,OAAO;IA+BtB,OAAO,CAAC,MAAM,CAAC,YAAY;CAqC5B"}
+{"version":3,"file":"build.command.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/build.command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQpC,qBAAa,YAAY;IACvB,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;WAW1B,OAAO,CAAC,OAAO,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IA4DjD,OAAO,CAAC,MAAM,CAAC,OAAO;IA+BtB,OAAO,CAAC,MAAM,CAAC,YAAY;CAqC5B"}

package/dist/cli/commands/build.command.js

@@ -42,6 +42,7 @@ const path = __importStar(require("path"));
 const fs = __importStar(require("fs"));
 const chalk_1 = __importDefault(require("chalk"));
 const ora_1 = __importDefault(require("ora"));
+const tsconfig_utils_1 = require("../../shared/tsconfig.utils");
 class BuildCommand {
     static register(program) {
         program
@@ -64,13 +65,25 @@ class BuildCommand {
                 console.log(chalk_1.default.cyan("  npm install --save-dev typescript"));
                 process.exit(1);
             }
-            // Check if tsconfig.json exists
-            const tsconfigPath = path.join(process.cwd(), "tsconfig.json");
-            if (!fs.existsSync(tsconfigPath)) {
+            // Check if tsconfig.json exists using utility
+            if (!tsconfig_utils_1.TsConfigUtils.exists()) {
                 spinner.fail("tsconfig.json not found");
                 console.log(chalk_1.default.yellow("\nCreate a tsconfig.json file in your project root"));
                 process.exit(1);
             }
+            // Validate required compiler options for Fragment
+            if (!tsconfig_utils_1.TsConfigUtils.hasDecoratorSupport()) {
+                spinner.fail("Required TypeScript compiler options not enabled");
+                console.log(chalk_1.default.yellow("\nYour tsconfig.json must include:"));
+                console.log(chalk_1.default.cyan('  "compilerOptions": {'));
+                console.log(chalk_1.default.cyan('    "experimentalDecorators": true,'));
+                console.log(chalk_1.default.cyan('    "emitDecoratorMetadata": true'));
+                console.log(chalk_1.default.cyan("  }"));
+                process.exit(1);
+            }
+            // Get output directory from tsconfig instead of hardcoding
+            const outDir = tsconfig_utils_1.TsConfigUtils.getOutDir();
+            const relativeOutDir = path.relative(process.cwd(), outDir);
             // Run TypeScript compiler
             spinner.text = "Compiling TypeScript...";
             (0, child_process_1.execSync)(`"${tscPath}"`, {
@@ -80,9 +93,9 @@ class BuildCommand {
             spinner.succeed("Build completed successfully!");
             if (options.analyze) {
                 console.log(chalk_1.default.blue("\n📊 Bundle Analysis:"));
-                this.analyzeBuild();
+                this.analyzeBuild(outDir); // Pass the actual output directory
             }
-            console.log(chalk_1.default.green("\n✨ Build output: dist/"));
+            console.log(chalk_1.default.green(`\n✨ Build output: ${relativeOutDir}/`));
         }
         catch (error) {
             spinner.fail("Build failed");
@@ -111,10 +124,9 @@ class BuildCommand {
         }
         return null;
     }
-    static analyzeBuild() {
-        const distPath = path.join(process.cwd(), "dist");
+    static analyzeBuild(distPath) {
         if (!fs.existsSync(distPath)) {
-            console.log(chalk_1.default.yellow("  No dist/ directory found"));
+            console.log(chalk_1.default.yellow(`  No ${path.basename(distPath)}/ directory found`));
             return;
         }
         let totalSize = 0;