fragment-ts 1.0.34 → 1.0.35

package/DOCS.md

@@ -1,3 +1,4 @@
+---
 
 # In-Depth Documentation
 
@@ -9,6 +10,7 @@ Fragment TS follows a component-based architecture with dependency injection at
 2. **Separation of Concerns**: Clear separation between controllers, services, and repositories
 3. **Convention over Configuration**: Automatic component scanning and registration
 4. **Type Safety**: Leveraging TypeScript's type system for compile-time validation
+5. **Enhancement Pipeline**: Modular request/response processing through middleware, guards, interceptors, and exception filters
 
 ![Architecture Diagram](https://example.com/fragment-architecture.png)
 
@@ -19,6 +21,7 @@ Fragment TS follows a component-based architecture with dependency injection at
 3. **Component Scanner**: Discovers and registers components automatically
 4. **Web Application**: Configures and starts the Express server
 5. **TypeORM Module**: Integrates TypeORM for database operations
+6. **Enhancement Pipeline**: Processes requests through middleware → guards → interceptors → handlers → exception filters
 
 ## Dependency Injection System
 
@@ -30,11 +33,13 @@ The dependency injection system in Fragment TS works through a combination of de
    - Class decorators (`@Service()`, `@Controller()`, etc.) register components with the metadata storage
    - Property decorators (`@Autowired()`, `@InjectRepository()`, etc.) store metadata about dependencies
    - Method and parameter decorators store route and handler information
+   - **Enhancement decorators** (`@FragmentMiddleware`, `@FragmentGuard`, etc.) store pipeline metadata
 
 2. **Component Registration**:
    - During application bootstrap, the component scanner loads all relevant files
    - The metadata storage is populated with component definitions
    - Components are registered with the DI container
+   - Enhancement components are resolved through the same DI container
 
 3. **Dependency Resolution**:
    - When a component is requested, the container creates an instance
@@ -51,13 +56,13 @@ Fragment TS supports three scopes for components:
 3. **Transient**: New instance every time it's requested
 
 ```typescript
-@Injectable('singleton')
+@Injectable("singleton")
 class DatabaseConnection {}
 
-@Injectable('request')
+@Injectable("request")
 class RequestContext {}
 
-@Injectable('transient')
+@Injectable("transient")
 class RandomGenerator {}
 ```
 
@@ -94,17 +99,17 @@ Fragment TS components follow a well-defined lifecycle:
 @Service()
 class LifecycleService {
   constructor() {
-    console.log('Constructor called');
+    console.log("Constructor called");
   }
-  
+
   @PostConstruct()
   init() {
-    console.log('Post-construct called - dependencies are available');
+    console.log("Post-construct called - dependencies are available");
   }
-  
+
   @PreDestroy()
   cleanup() {
-    console.log('Pre-destroy called - cleanup resources');
+    console.log("Pre-destroy called - cleanup resources");
   }
 }
 ```
@@ -113,20 +118,171 @@ class LifecycleService {
 
 ### Request Processing Pipeline
 
+Fragment TS implements a sophisticated request processing pipeline that executes enhancements in a specific order:
+
 1. **Route Registration**:
    - Controllers and routes are registered during application bootstrap
    - Route metadata is stored in the metadata storage
+   - Enhancement metadata (middleware, guards, interceptors, filters) is collected
+
+2. **Request Handling Pipeline**:
+   - **Express Middleware**: Standard Express middleware runs first
+   - **Fragment Middleware**: `@FragmentMiddleware` components execute (class-level then method-level)
+   - **Guards**: `@FragmentGuard` components validate access (class-level then method-level)
+   - **Parameter Resolution**: Route parameters are resolved and injected
+   - **Handler Execution**: Controller method is invoked
+   - **Interceptors**: `@FragmentInterceptor` components transform the result (class-level then method-level)
+   - **Response**: Final result is sent as JSON
+
+3. **Error Handling Pipeline**:
+   - If any step throws an error, **Exception Filters** are executed
+   - `@FragmentExceptionFilter` components handle errors (method-level then class-level)
+   - If no filter handles the error, it falls back to Express error handling
+
+### Enhancement Decorators
+
+#### Middleware (`@FragmentMiddleware`)
+
+Middleware components implement the `Middleware` interface and can modify the request/response cycle or terminate it early.
+
+```typescript
+// Middleware interface
+interface Middleware {
+  use(req: Request, res: Response, next: NextFunction): void | Promise<void>;
+}
+
+// Implementation
+@Injectable()
+class LoggingMiddleware implements Middleware {
+  use(req: Request, res: Response, next: NextFunction): void {
+    console.log(`📥 ${req.method} ${req.path}`);
+    next();
+  }
+}
+
+// Usage
+@FragmentMiddleware(LoggingMiddleware)
+@Controller("/api")
+class ApiController {}
+```
+
+#### Guards (`@FragmentGuard`)
+
+Guard components implement the `Guard` interface and control whether a route handler should be executed.
 
-2. **Request Handling**:
-   - Express middleware processes the incoming request
-   - Route handler is matched based on path and HTTP method
-   - Controller instance is retrieved from the container
-   - Route parameters are resolved and injected
-   - Handler method is invoked
+```typescript
+// Guard interface
+interface Guard {
+  canActivate(req: Request): boolean | Promise<boolean>;
+}
 
-3. **Response Processing**:
-   - Return value is automatically converted to JSON
-   - Error handling middleware processes any exceptions
+// Implementation
+@Injectable()
+class AuthGuard implements Guard {
+  canActivate(req: Request): boolean {
+    const token = req.headers.authorization;
+    return token === "Bearer valid-token";
+  }
+}
+
+// Usage
+@FragmentGuard(AuthGuard)
+@Controller("/secure")
+class SecureController {}
+```
+
+#### Interceptors (`@FragmentInterceptor`)
+
+Interceptor components implement the `Interceptor` interface and can transform the handler's result before it's sent to the client.
+
+```typescript
+// Interceptor interface
+interface Interceptor {
+  intercept(req: Request, res: Response, result: any): any | Promise<any>;
+}
+
+// Implementation
+@Injectable()
+class TransformInterceptor implements Interceptor {
+  intercept(req: Request, res: Response, result: any): any {
+    return {
+      success: true,
+      data: result,
+      timestamp: new Date().toISOString(),
+    };
+  }
+}
+
+// Usage
+@FragmentInterceptor(TransformInterceptor)
+@Controller("/api")
+class DataController {}
+```
+
+#### Exception Filters (`@FragmentExceptionFilter`)
+
+Exception filter components implement the `ExceptionFilter` interface and handle errors thrown during request processing.
+
+```typescript
+// ExceptionFilter interface
+interface ExceptionFilter {
+  catch(exception: Error, req: Request, res: Response): void;
+}
+
+// Implementation
+@Injectable()
+class HttpExceptionFilter implements ExceptionFilter {
+  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
+@FragmentExceptionFilter(HttpExceptionFilter)
+@FragmentApplication()
+class Application {}
+```
+
+### Enhancement Composition
+
+All enhancement decorators can be combined and applied at both class and method levels:
+
+```typescript
+@FragmentMiddleware(LoggingMiddleware)
+@FragmentGuard(AuthGuard)
+@FragmentInterceptor(TransformInterceptor)
+@FragmentExceptionFilter(HttpExceptionFilter)
+@Controller("/api")
+class ComplexController {
+  @Get("/public")
+  @FragmentGuard(PublicGuard) // Overrides class-level guard for this method
+  publicData() {
+    return { message: "Public data" };
+  }
+
+  @Post("/admin")
+  @FragmentGuard(AdminGuard) // Additional guard
+  @FragmentInterceptor(CacheInterceptor) // Additional interceptor
+  createAdminData(@Body() data: any) {
+    return { created: true, data };
+  }
+}
+```
+
+The execution order is:
+
+1. **Middleware**: Class → Method
+2. **Guards**: Class → Method (all must pass)
+3. **Interceptors**: Class → Method (applied in reverse order on result)
+4. **Exception Filters**: Method → Class (first one to handle stops propagation)
 
 ### Middleware Integration
 
@@ -136,8 +292,8 @@ Fragment TS integrates with Express middleware through the underlying Express ap
 const app = new FragmentWebApplication();
 const expressApp = app.getExpressApp();
 
-// Add custom middleware
-expressApp.use('/api', apiMiddleware);
+// Add custom Express middleware
+expressApp.use("/api", apiMiddleware);
 expressApp.use(errorHandler);
 ```
 
@@ -171,10 +327,10 @@ Fragment TS encourages the repository pattern for data access:
 export class User {
   @PrimaryGeneratedColumn()
   id: number;
-  
+
   @Column()
   name: string;
-  
+
   @Column()
   email: string;
 }
@@ -191,15 +347,15 @@ export interface UserRepository {
 export class TypeOrmUserRepository implements UserRepository {
   @InjectRepository(User)
   private repo!: Repository<User>;
-  
+
   async findAll(): Promise<User[]> {
     return this.repo.find();
   }
-  
+
   async findById(id: number): Promise<User | null> {
     return this.repo.findOneBy({ id });
   }
-  
+
   async save(user: User): Promise<User> {
     return this.repo.save(user);
   }
@@ -225,7 +381,7 @@ class DefaultLoggerService implements LoggerService {}
 
 // Only register if environment variable is set
 @Service()
-@ConditionalOnProperty('ENABLE_CACHE', 'true')
+@ConditionalOnProperty("ENABLE_CACHE", "true")
 class CacheService {}
 ```
 
@@ -236,13 +392,13 @@ Application configuration can be injected from environment variables or config f
 ```typescript
 @Service()
 class AppConfig {
-  @Value('${PORT:3000}')
+  @Value("${PORT:3000}")
   port!: number;
-  
-  @Value('${DATABASE_URL}')
+
+  @Value("${DATABASE_URL}")
   databaseUrl!: string;
-  
-  @Value('${FEATURE_FLAG_NEW_UI:false}')
+
+  @Value("${FEATURE_FLAG_NEW_UI:false}")
   featureFlagNewUi!: boolean;
 }
 ```
@@ -253,32 +409,51 @@ Fragment TS is designed for testability with minimal dependencies on framework i
 
 ```typescript
 // Unit test example
-describe('UserService', () => {
+describe("UserService", () => {
   let userService: UserService;
   let mockUserRepository: jest.Mocked<UserRepository>;
-  
+
   beforeEach(() => {
     mockUserRepository = {
       findAll: jest.fn(),
-      findById: jest.fn()
+      findById: jest.fn(),
     } as any;
-    
+
     userService = new UserService();
-    Object.defineProperty(userService, 'userRepository', {
-      value: mockUserRepository
+    Object.defineProperty(userService, "userRepository", {
+      value: mockUserRepository,
     });
   });
-  
-  it('should return all users', async () => {
-    const mockUsers = [{ id: 1, name: 'John' }];
+
+  it("should return all users", async () => {
+    const mockUsers = [{ id: 1, name: "John" }];
     mockUserRepository.findAll.mockResolvedValue(mockUsers);
-    
+
     const result = await userService.findAll();
-    
+
     expect(result).toEqual(mockUsers);
     expect(mockUserRepository.findAll).toHaveBeenCalled();
   });
 });
+
+// Testing guards
+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);
+  });
+});
 ```
 
 ## Performance Considerations
@@ -297,9 +472,17 @@ Component scanning and dependency resolution happen during application startup.
 - Request-scoped components are created per request and should be lightweight
 - Transient components are created on-demand and not cached
 
+### Enhancement Performance
+
+- **Middleware**: Should be fast and non-blocking; avoid heavy async operations
+- **Guards**: Should be lightweight validation; avoid database calls when possible
+- **Interceptors**: Can be more expensive since they run after handler execution
+- **Exception Filters**: Should handle errors quickly without additional async operations
+
 ### Optimization Techniques
 
 1. **Lazy Loading**:
+
 ```typescript
 @Service()
 class HeavyService {
@@ -310,9 +493,10 @@ class HeavyService {
 ```
 
 2. **Selective Component Scanning**:
+
 ```typescript
 @FragmentApplication({
-  autoScan: false // Disable automatic scanning
+  autoScan: false, // Disable automatic scanning
 })
 class Application {}
 
@@ -323,6 +507,7 @@ container.register(UserController);
 ```
 
 3. **Production Build**:
+
 - Always use compiled JavaScript in production
 - Enable tree-shaking and minification
 - Use environment variables for configuration instead of config files when possible
@@ -341,13 +526,16 @@ class CustomErrorHandler {
   @PostConstruct()
   register() {
     const expressApp = app.getExpressApp();
-    expressApp.use((err: Error, req: Request, res: Response, next: NextFunction) => {
-      console.error('Global error:', err);
-      res.status(500).json({
-        error: 'Internal Server Error',
-        message: process.env.NODE_ENV === 'development' ? err.message : undefined
-      });
-    });
+    expressApp.use(
+      (err: Error, req: Request, res: Response, next: NextFunction) => {
+        console.error("Global error:", err);
+        res.status(500).json({
+          error: "Internal Server Error",
+          message:
+            process.env.NODE_ENV === "development" ? err.message : undefined,
+        });
+      },
+    );
   }
 }
 ```
@@ -360,18 +548,29 @@ Define custom error types for better error handling:
 export class NotFoundError extends Error {
   constructor(message: string) {
     super(message);
-    this.name = 'NotFoundError';
+    this.name = "NotFoundError";
   }
 }
 
 export class ValidationError extends Error {
   constructor(public errors: any[]) {
-    super('Validation failed');
-    this.name = 'ValidationError';
+    super("Validation failed");
+    this.name = "ValidationError";
   }
 }
 ```
 
+### Exception Filter Hierarchy
+
+Exception filters follow a specific hierarchy for error handling:
+
+1. **Method-level filters** are checked first
+2. **Controller-level filters** are checked next
+3. **Application-level filters** (on `@FragmentApplication` class) are checked last
+4. **Global Express error handler** is the final fallback
+
+This allows for fine-grained error handling at different levels of your application.
+
 ## Extensibility
 
 ### Custom Decorators
@@ -380,7 +579,11 @@ Create custom decorators by leveraging the metadata storage:
 
 ```typescript
 function CustomDecorator(metadata: any): MethodDecorator {
-  return (target: any, propertyKey: string | symbol, descriptor: PropertyDescriptor) => {
+  return (
+    target: any,
+    propertyKey: string | symbol,
+    descriptor: PropertyDescriptor,
+  ) => {
     const storage = MetadataStorage.getInstance();
     storage.addCustomMetadata(target.constructor, propertyKey, metadata);
   };
@@ -388,11 +591,19 @@ function CustomDecorator(metadata: any): MethodDecorator {
 
 // Usage
 class MyController {
-  @CustomDecorator({ role: 'admin' })
+  @CustomDecorator({ role: "admin" })
   adminMethod() {}
 }
 ```
 
+### Custom Enhancement Types
+
+You can extend the enhancement pipeline with custom types by:
+
+1. Adding new metadata keys to `METADATA_KEYS`
+2. Creating new decorators that store metadata
+3. Updating the route registration logic to process your custom enhancements
+
 ### Custom Modules
 
 Extend the framework with custom modules:
@@ -401,9 +612,9 @@ Extend the framework with custom modules:
 class CustomModule {
   static async initialize() {
     // Custom initialization logic
-    console.log('Custom module initialized');
+    console.log("Custom module initialized");
   }
-  
+
   static getDependency() {
     // Return dependency for injection
     return new CustomDependency();
@@ -426,10 +637,19 @@ class Application {
 1. **Single Responsibility**: Each component should have one clear responsibility
 2. **Loose Coupling**: Depend on abstractions (interfaces) rather than concrete implementations
 3. **High Cohesion**: Related functionality should be grouped together
+4. **Enhancement Separation**: Keep middleware, guards, interceptors, and filters focused on their specific concerns
+
+### Enhancement Patterns
+
+1. **Middleware**: Use for cross-cutting concerns like logging, authentication headers, request ID generation
+2. **Guards**: Use for authorization, rate limiting, feature flags
+3. **Interceptors**: Use for response transformation, caching, metrics collection
+4. **Exception Filters**: Use for standardized error responses, logging, alerting
 
 ### Code Organization
 
 1. **Feature-based Structure**:
+
 ```
 src/
 ├── features/
@@ -442,16 +662,26 @@ src/
 │   └── product/
 │       ├── product.controller.ts
 │       └── ...
+├── enhancements/
+│   ├── middleware/
+│   ├── guards/
+│   ├── interceptors/
+│   └── filters/
 ```
 
 2. **Layer-based Structure**:
+
 ```
 src/
 ├── controllers/
 ├── services/
 ├── repositories/
 ├── entities/
-└── dtos/
+├── dtos/
+├── middleware/
+├── guards/
+├── interceptors/
+└── filters/
 ```
 
 ### Testing Strategy
@@ -459,26 +689,29 @@ src/
 1. **Unit Tests**: Test individual components in isolation
 2. **Integration Tests**: Test component interactions
 3. **End-to-End Tests**: Test full request/response cycle
+4. **Enhancement Tests**: Specifically test middleware, guards, interceptors, and filters in isolation
 
 ## Migration Guide
 
 ### From Express
 
 1. Create a Fragment application class:
+
 ```typescript
 @FragmentApplication()
 class Application {}
 ```
 
 2. Convert Express routes to controllers:
+
 ```typescript
 // Before (Express)
-app.get('/users', (req, res) => {
+app.get("/users", (req, res) => {
   // handler
 });
 
 // After (Fragment)
-@Controller('/users')
+@Controller("/users")
 class UserController {
   @Get()
   findAll() {
@@ -488,9 +721,10 @@ class UserController {
 ```
 
 3. Extract business logic to services:
+
 ```typescript
 // Before
-app.post('/users', async (req, res) => {
+app.post("/users", async (req, res) => {
   const user = await db.users.create(req.body);
   res.json(user);
 });
@@ -500,17 +734,17 @@ app.post('/users', async (req, res) => {
 class UserService {
   @Autowired()
   private userRepository!: UserRepository;
-  
+
   async create(userData: any) {
     return this.userRepository.save(userData);
   }
 }
 
-@Controller('/users')
+@Controller("/users")
 class UserController {
   @Autowired()
   private userService!: UserService;
-  
+
   @Post()
   async create(@Body() userData: any) {
     return this.userService.create(userData);
@@ -518,6 +752,31 @@ class UserController {
 }
 ```
 
+4. Convert Express middleware to Fragment middleware:
+
+```typescript
+// Before
+app.use("/api", (req, res, next) => {
+  console.log("API request");
+  next();
+});
+
+// After
+@Injectable()
+class ApiLoggingMiddleware implements Middleware {
+  use(req: Request, res: Response, next: NextFunction) {
+    if (req.path.startsWith("/api")) {
+      console.log("API request");
+    }
+    next();
+  }
+}
+
+@FragmentMiddleware(ApiLoggingMiddleware)
+@Controller("/api")
+class ApiController {}
+```
+
 ### From NestJS
 
 Fragment TS shares many concepts with NestJS:
@@ -525,11 +784,14 @@ Fragment TS shares many concepts with NestJS:
 1. **Dependency Injection**: Similar `@Injectable()`, `@Autowired()` patterns
 2. **Controllers and Services**: Nearly identical structure
 3. **TypeORM Integration**: Similar repository patterns
+4. **Enhancement Pipeline**: Similar to NestJS interceptors, guards, and filters
 
 Key differences:
+
 - Fragment TS uses property injection by default instead of constructor injection
 - Simpler configuration with less boilerplate
 - More lightweight with fewer dependencies
+- Enhancement decorators work at both class and method levels with intuitive composition
 
 ## Roadmap
 
@@ -540,6 +802,8 @@ Key differences:
 3. **Swagger Integration**: Automatic API documentation
 4. **WebSockets Support**: Real-time communication capabilities
 5. **CLI Tooling**: Project generation and management commands
+6. **Async Local Storage**: Better request context propagation
+7. **Performance Monitoring**: Built-in metrics and tracing
 
 ### Community Contributions
 

package/NewCLIGENERATECOMMANDS.txt

@@ -0,0 +1,5 @@
+# Generate enhancement components
+fragment generate middleware logging
+fragment generate guard auth
+fragment generate interceptor transform
+fragment generate filter http-exception