fragment-ts 1.0.30 → 1.0.32

package/DOCS.md

@@ -0,0 +1,555 @@
+
+# In-Depth Documentation
+
+## Architecture Overview
+
+Fragment TS follows a component-based architecture with dependency injection at its core. The framework is designed around several key principles:
+
+1. **Inversion of Control (IoC)**: Components declare their dependencies rather than creating them directly
+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
+
+![Architecture Diagram](https://example.com/fragment-architecture.png)
+
+### Core Components
+
+1. **DI Container**: Manages the lifecycle and dependencies of all components
+2. **Metadata Storage**: Stores decorator metadata for runtime processing
+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
+
+## Dependency Injection System
+
+### How It Works
+
+The dependency injection system in Fragment TS works through a combination of decorators, TypeScript metadata, and reflection:
+
+1. **Decorator Metadata Collection**:
+   - 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
+
+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
+
+3. **Dependency Resolution**:
+   - When a component is requested, the container creates an instance
+   - Constructor parameters are resolved recursively
+   - Property dependencies are injected based on metadata
+   - Post-construction hooks are called
+
+### Scopes
+
+Fragment TS supports three scopes for components:
+
+1. **Singleton (default)**: One instance per application
+2. **Request**: One instance per HTTP request
+3. **Transient**: New instance every time it's requested
+
+```typescript
+@Injectable('singleton')
+class DatabaseConnection {}
+
+@Injectable('request')
+class RequestContext {}
+
+@Injectable('transient')
+class RandomGenerator {}
+```
+
+### Circular Dependencies
+
+The framework detects circular dependencies during component resolution and throws meaningful errors:
+
+```typescript
+@Service()
+class ServiceA {
+  @Autowired()
+  private serviceB!: ServiceB;
+}
+
+@Service()
+class ServiceB {
+  @Autowired()
+  private serviceA!: ServiceA; // This will cause a circular dependency error
+}
+```
+
+## Component Lifecycle
+
+Fragment TS components follow a well-defined lifecycle:
+
+1. **Registration**: Component is registered with the container
+2. **Instantiation**: Container creates a new instance
+3. **Dependency Injection**: Dependencies are injected via constructor and properties
+4. **Post-Construction**: `@PostConstruct` methods are called
+5. **Usage**: Component is ready for use
+6. **Destruction**: `@PreDestroy` methods are called before garbage collection
+
+```typescript
+@Service()
+class LifecycleService {
+  constructor() {
+    console.log('Constructor called');
+  }
+  
+  @PostConstruct()
+  init() {
+    console.log('Post-construct called - dependencies are available');
+  }
+  
+  @PreDestroy()
+  cleanup() {
+    console.log('Pre-destroy called - cleanup resources');
+  }
+}
+```
+
+## Web Layer
+
+### Request Processing Pipeline
+
+1. **Route Registration**:
+   - Controllers and routes are registered during application bootstrap
+   - Route metadata is stored in the metadata storage
+
+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
+
+3. **Response Processing**:
+   - Return value is automatically converted to JSON
+   - Error handling middleware processes any exceptions
+
+### Middleware Integration
+
+Fragment TS integrates with Express middleware through the underlying Express application:
+
+```typescript
+const app = new FragmentWebApplication();
+const expressApp = app.getExpressApp();
+
+// Add custom middleware
+expressApp.use('/api', apiMiddleware);
+expressApp.use(errorHandler);
+```
+
+## Database Integration
+
+### TypeORM Configuration
+
+TypeORM is configured via a JSON file (default: `fragment.json`):
+
+```json
+{
+  "type": "mysql",
+  "host": "localhost",
+  "port": 3306,
+  "username": "root",
+  "password": "password",
+  "database": "my_db",
+  "entities": ["dist/entities/**/*.js"],
+  "synchronize": true,
+  "logging": false
+}
+```
+
+### Repository Pattern
+
+Fragment TS encourages the repository pattern for data access:
+
+```typescript
+// Entity
+@Entity()
+export class User {
+  @PrimaryGeneratedColumn()
+  id: number;
+  
+  @Column()
+  name: string;
+  
+  @Column()
+  email: string;
+}
+
+// Repository interface
+export interface UserRepository {
+  findAll(): Promise<User[]>;
+  findById(id: number): Promise<User | null>;
+  save(user: User): Promise<User>;
+}
+
+// Fragment repository implementation
+@Repository()
+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);
+  }
+}
+```
+
+## Advanced Features
+
+### Conditional Components
+
+Components can be conditionally registered based on environment, class availability, or existing beans:
+
+```typescript
+// Only register if Redis class is available
+@AutoConfiguration()
+@ConditionalOnClass(Redis)
+class RedisConfiguration {}
+
+// Only register if no other logger is available
+@Service()
+@ConditionalOnMissingBean(LoggerService)
+class DefaultLoggerService implements LoggerService {}
+
+// Only register if environment variable is set
+@Service()
+@ConditionalOnProperty('ENABLE_CACHE', 'true')
+class CacheService {}
+```
+
+### Configuration Properties
+
+Application configuration can be injected from environment variables or config files:
+
+```typescript
+@Service()
+class AppConfig {
+  @Value('${PORT:3000}')
+  port!: number;
+  
+  @Value('${DATABASE_URL}')
+  databaseUrl!: string;
+  
+  @Value('${FEATURE_FLAG_NEW_UI:false}')
+  featureFlagNewUi!: boolean;
+}
+```
+
+### Testing Support
+
+Fragment TS is designed for testability with minimal dependencies on framework internals:
+
+```typescript
+// Unit test example
+describe('UserService', () => {
+  let userService: UserService;
+  let mockUserRepository: jest.Mocked<UserRepository>;
+  
+  beforeEach(() => {
+    mockUserRepository = {
+      findAll: jest.fn(),
+      findById: jest.fn()
+    } as any;
+    
+    userService = new UserService();
+    Object.defineProperty(userService, 'userRepository', {
+      value: mockUserRepository
+    });
+  });
+  
+  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();
+  });
+});
+```
+
+## Performance Considerations
+
+### Startup Time
+
+Component scanning and dependency resolution happen during application startup. For large applications:
+
+- Use conditional components to limit unnecessary registrations
+- Consider lazy loading for heavy dependencies
+- Split application into modules if necessary
+
+### Memory Usage
+
+- Singleton-scoped components are held in memory for the application lifetime
+- Request-scoped components are created per request and should be lightweight
+- Transient components are created on-demand and not cached
+
+### Optimization Techniques
+
+1. **Lazy Loading**:
+```typescript
+@Service()
+class HeavyService {
+  @Lazy()
+  @Autowired()
+  private resourceIntensiveService!: ResourceIntensiveService;
+}
+```
+
+2. **Selective Component Scanning**:
+```typescript
+@FragmentApplication({
+  autoScan: false // Disable automatic scanning
+})
+class Application {}
+
+// Manually register components
+const container = DIContainer.getInstance();
+container.register(UserService);
+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
+
+## Error Handling
+
+### Global Error Handling
+
+Fragment TS provides a global error handler that catches unhandled exceptions:
+
+```typescript
+const app = new FragmentWebApplication();
+
+// Custom error handler
+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
+      });
+    });
+  }
+}
+```
+
+### Custom Error Types
+
+Define custom error types for better error handling:
+
+```typescript
+export class NotFoundError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'NotFoundError';
+  }
+}
+
+export class ValidationError extends Error {
+  constructor(public errors: any[]) {
+    super('Validation failed');
+    this.name = 'ValidationError';
+  }
+}
+```
+
+## Extensibility
+
+### Custom Decorators
+
+Create custom decorators by leveraging the metadata storage:
+
+```typescript
+function CustomDecorator(metadata: any): MethodDecorator {
+  return (target: any, propertyKey: string | symbol, descriptor: PropertyDescriptor) => {
+    const storage = MetadataStorage.getInstance();
+    storage.addCustomMetadata(target.constructor, propertyKey, metadata);
+  };
+}
+
+// Usage
+class MyController {
+  @CustomDecorator({ role: 'admin' })
+  adminMethod() {}
+}
+```
+
+### Custom Modules
+
+Extend the framework with custom modules:
+
+```typescript
+class CustomModule {
+  static async initialize() {
+    // Custom initialization logic
+    console.log('Custom module initialized');
+  }
+  
+  static getDependency() {
+    // Return dependency for injection
+    return new CustomDependency();
+  }
+}
+
+// Register with application
+@FragmentApplication()
+class Application {
+  constructor() {
+    CustomModule.initialize();
+  }
+}
+```
+
+## Best Practices
+
+### Component Design
+
+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
+
+### Code Organization
+
+1. **Feature-based Structure**:
+```
+src/
+├── features/
+│   ├── user/
+│   │   ├── user.controller.ts
+│   │   ├── user.service.ts
+│   │   ├── user.repository.ts
+│   │   ├── user.entity.ts
+│   │   └── index.ts
+│   └── product/
+│       ├── product.controller.ts
+│       └── ...
+```
+
+2. **Layer-based Structure**:
+```
+src/
+├── controllers/
+├── services/
+├── repositories/
+├── entities/
+└── dtos/
+```
+
+### Testing Strategy
+
+1. **Unit Tests**: Test individual components in isolation
+2. **Integration Tests**: Test component interactions
+3. **End-to-End Tests**: Test full request/response cycle
+
+## 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) => {
+  // handler
+});
+
+// After (Fragment)
+@Controller('/users')
+class UserController {
+  @Get()
+  findAll() {
+    // handler
+  }
+}
+```
+
+3. Extract business logic to services:
+```typescript
+// Before
+app.post('/users', async (req, res) => {
+  const user = await db.users.create(req.body);
+  res.json(user);
+});
+
+// After
+@Service()
+class UserService {
+  @Autowired()
+  private userRepository!: UserRepository;
+  
+  async create(userData: any) {
+    return this.userRepository.save(userData);
+  }
+}
+
+@Controller('/users')
+class UserController {
+  @Autowired()
+  private userService!: UserService;
+  
+  @Post()
+  async create(@Body() userData: any) {
+    return this.userService.create(userData);
+  }
+}
+```
+
+### From NestJS
+
+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
+
+Key differences:
+- Fragment TS uses property injection by default instead of constructor injection
+- Simpler configuration with less boilerplate
+- More lightweight with fewer dependencies
+
+## Roadmap
+
+### Planned Features
+
+1. **Request-scoped Components**: Full support for request-scoped dependencies
+2. **Validation Pipelines**: Built-in validation decorators
+3. **Swagger Integration**: Automatic API documentation
+4. **WebSockets Support**: Real-time communication capabilities
+5. **CLI Tooling**: Project generation and management commands
+
+### Community Contributions
+
+Fragment TS welcomes community contributions:
+
+1. **Bug Reports**: Report issues with reproduction steps
+2. **Feature Requests**: Suggest new features and improvements
+3. **Pull Requests**: Contribute code following the contribution guidelines
+4. **Documentation**: Improve documentation and examples
+
+## License
+
+Fragment TS is released under the MIT License. See [LICENSE](LICENSE) for details.