@el-j/magic-helix-core 4.0.0-beta.2 → 4.0.0-beta.4

package/dist/default_templates/patterns/architecture/clean-architecture.md

@@ -1,469 +0,0 @@
-# Clean Architecture Pattern
-
-## Purpose
-Enforce separation of concerns through concentric layers, keeping business logic independent of frameworks, UI, and external dependencies.
-
-## Core Principles
-
-### Layer Dependency Rule
-**Inner layers NEVER depend on outer layers. Dependencies point inward only.**
-
-```
-┌─────────────────────────────────────┐
-│     Frameworks & Drivers (UI, DB)  │  ← Outermost layer
-├─────────────────────────────────────┤
-│     Interface Adapters (Controllers)│
-├─────────────────────────────────────┤
-│     Application Business Rules      │
-│     (Use Cases / Interactors)       │
-├─────────────────────────────────────┤
-│     Enterprise Business Rules       │
-│     (Entities / Domain Models)      │  ← Innermost layer
-└─────────────────────────────────────┘
-```
-
-### Layer Responsibilities
-
-#### 1. Entities (Domain Models) - Innermost
-**Pure business logic. No framework dependencies. Use plain objects + pure functions.**
-
-```typescript
-// ✅ Modern: Domain entity as immutable data + pure functions
-export type User = {
-  readonly id: string;
-  readonly email: string;
-  readonly passwordHash: string;
-  readonly createdAt: Date;
-};
-
-// Factory function to create user
-export function createUser(email: string, password: string): User {
-  if (!isValidEmail(email)) {
-    throw new Error('Invalid email format');
-  }
-  
-  return {
-    id: generateId(),
-    email,
-    passwordHash: hashPassword(password),
-    createdAt: new Date(),
-  };
-}
-
-// Pure functions for business logic
-export function validatePassword(user: User, plainPassword: string): boolean {
-  return hashPassword(plainPassword) === user.passwordHash;
-}
-
-export function changeEmail(user: User, newEmail: string): User {
-  if (!isValidEmail(newEmail)) {
-    throw new Error('Invalid email format');
-  }
-  // Immutable update - return new object
-  return { ...user, email: newEmail };
-}
-
-function isValidEmail(email: string): boolean {
-  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
-}
-
-function hashPassword(plain: string): string {
-  // Business rule for password hashing
-  return /* hashing logic */;
-}
-```
-
-#### 2. Use Cases (Application Business Rules)
-**Orchestrate entities. Define application-specific business rules. Framework-independent.**
-
-```typescript
-// ✅ Modern: Repository as plain interface (no class)
-export type UserRepository = {
-  findById: (id: string) => Promise<User | null>;
-  findByEmail: (email: string) => Promise<User | null>;
-  save: (user: User) => Promise<void>;
-};
-
-export type EmailService = {
-  sendWelcomeEmail: (email: string) => Promise<void>;
-};
-
-// ✅ Use case as pure function with dependencies injected as parameters
-export async function registerUser(
-  email: string,
-  password: string,
-  deps: {
-    userRepository: UserRepository;
-    emailService: EmailService;
-  }
-): Promise<User> {
-  // Application business rule
-  const existingUser = await deps.userRepository.findByEmail(email);
-  if (existingUser) {
-    throw new Error('User already exists');
-  }
-
-  const user = createUser(email, password);
-  await deps.userRepository.save(user);
-  await deps.emailService.sendWelcomeEmail(email);
-  
-  return user;
-}
-
-// Alternative: Factory pattern for partial application
-export function makeRegisterUser(deps: {
-  userRepository: UserRepository;
-  emailService: EmailService;
-}) {
-  return async (email: string, password: string) => {
-    return registerUser(email, password, deps);
-  };
-}
-```
-
-#### 3. Interface Adapters (Controllers, Presenters, Gateways)
-**Convert data between use cases and external layers. Adapt external formats to internal formats.**
-
-```typescript
-// ✅ Modern: Controller as pure function (no class)
-export async function registerUserHandler(
-  req: Request,
-  res: Response,
-  deps: { registerUser: typeof registerUser }
-): Promise<void> {
-  try {
-    const { email, password } = req.body;
-    
-    // Adapt HTTP input to use case input
-    const user = await deps.registerUser(email, password, deps);
-    
-    // Adapt use case output to HTTP response
-    res.status(201).json({
-      id: user.id,
-      email: user.email,
-    });
-  } catch (error) {
-    res.status(400).json({ error: error.message });
-  }
-}
-
-// ✅ Repository adapter implements type interface
-export function createPostgresUserRepository(db: Database): UserRepository {
-  return {
-    async findById(id: string): Promise<User | null> {
-      const row = await db.query('SELECT * FROM users WHERE id = $1', [id]);
-      if (!row) return null;
-      
-      // Adapt database row to domain entity
-      return {
-        id: row.id,
-        email: row.email,
-        passwordHash: row.password_hash,
-        createdAt: new Date(row.created_at),
-      };
-    },
-
-    async findByEmail(email: string): Promise<User | null> {
-      const row = await db.query('SELECT * FROM users WHERE email = $1', [email]);
-      if (!row) return null;
-      
-      return {
-        id: row.id,
-        email: row.email,
-        passwordHash: row.password_hash,
-        createdAt: new Date(row.created_at),
-      };
-    },
-
-    async save(user: User): Promise<void> {
-      // Adapt domain entity to database row
-      await db.query(
-        'INSERT INTO users (id, email, password_hash, created_at) VALUES ($1, $2, $3, $4)',
-        [user.id, user.email, user.passwordHash, user.createdAt]
-      );
-    },
-  };
-}
-```
-
-#### 4. Frameworks & Drivers (UI, Database, External Services)
-**Implementation details. Frameworks, libraries, databases.**
-
-```typescript
-// ✅ Modern: Framework-specific setup with functional composition
-import express from 'express';
-import { createDatabase } from './infrastructure/database';
-import { createPostgresUserRepository } from './adapters/repositories/user-repository';
-import { createSendGridEmailService } from './adapters/services/email-service';
-import { makeRegisterUser } from './usecases/register-user';
-import { registerUserHandler } from './adapters/controllers/user-controller';
-
-const app = express();
-const db = createDatabase();
-
-// Wire up dependencies (Dependency Injection via composition)
-const userRepository = createPostgresUserRepository(db);
-const emailService = createSendGridEmailService(process.env.SENDGRID_KEY!);
-
-// Create use case with dependencies
-const registerUser = makeRegisterUser({ userRepository, emailService });
-
-// Register route with handler
-app.post('/api/users', (req, res) => 
-  registerUserHandler(req, res, { registerUser })
-);
-
-app.listen(3000);
-```
-
-## File Organization
-
-### Recommended Structure
-
-```
-src/
-├── domain/                    # Entities layer (innermost)
-│   ├── entities/
-│   │   ├── User.ts
-│   │   ├── Order.ts
-│   │   └── Product.ts
-│   └── value-objects/
-│       ├── Email.ts
-│       └── Money.ts
-│
-├── usecases/                  # Application business rules
-│   ├── user/
-│   │   ├── RegisterUser.ts
-│   │   ├── LoginUser.ts
-│   │   └── interfaces/        # Interfaces for repositories, services
-│   │       ├── IUserRepository.ts
-│   │       └── IEmailService.ts
-│   └── order/
-│       ├── CreateOrder.ts
-│       └── interfaces/
-│           └── IOrderRepository.ts
-│
-├── adapters/                  # Interface adapters layer
-│   ├── controllers/           # HTTP/API controllers
-│   │   ├── UserController.ts
-│   │   └── OrderController.ts
-│   ├── presenters/            # Format output for UI
-│   │   └── UserPresenter.ts
-│   ├── repositories/          # Database implementations
-│   │   ├── PostgresUserRepository.ts
-│   │   └── PostgresOrderRepository.ts
-│   └── services/              # External service implementations
-│       └── SendGridEmailService.ts
-│
-└── infrastructure/            # Frameworks & drivers (outermost)
-    ├── database/
-    │   └── postgres.ts
-    ├── http/
-    │   └── express-app.ts
-    └── config/
-        └── env.ts
-```
-
-## Testing Strategy
-
-### Test Each Layer Independently
-
-```typescript
-// ✅ Test domain entity (no mocks needed - pure logic)
-describe('User', () => {
-  it('validates password correctly', () => {
-    const user = new User('1', 'test@example.com', 'hashedPass');
-    expect(user.validatePassword('wrongPass')).toBe(false);
-  });
-});
-
-// ✅ Test use case (mock repository and service interfaces)
-describe('RegisterUserUseCase', () => {
-  it('registers new user and sends welcome email', async () => {
-    const mockRepo: IUserRepository = {
-      findById: jest.fn().mockResolvedValue(null),
-      save: jest.fn(),
-    };
-    const mockEmail: IEmailService = {
-      sendWelcomeEmail: jest.fn(),
-    };
-
-    const useCase = new RegisterUserUseCase(mockRepo, mockEmail);
-    await useCase.execute('new@example.com', 'password');
-
-    expect(mockRepo.save).toHaveBeenCalled();
-    expect(mockEmail.sendWelcomeEmail).toHaveBeenCalledWith('new@example.com');
-  });
-});
-
-// ✅ Test controller (mock use case)
-describe('UserController', () => {
-  it('returns 201 on successful registration', async () => {
-    const mockUseCase = {
-      execute: jest.fn().mockResolvedValue(new User('1', 'test@example.com', 'hash')),
-    };
-
-    const controller = new UserController(mockUseCase);
-    const req = { body: { email: 'test@example.com', password: 'pass' } };
-    const res = { status: jest.fn().mockReturnThis(), json: jest.fn() };
-
-    await controller.register(req, res);
-
-    expect(res.status).toHaveBeenCalledWith(201);
-  });
-});
-```
-
-## Migration Strategy
-
-### Step 1: Identify Current Layers
-- What's your business logic? (→ Entities)
-- What are your application operations? (→ Use Cases)
-- What talks to the outside world? (→ Adapters)
-- What are framework implementations? (→ Infrastructure)
-
-### Step 2: Extract Entities First
-```typescript
-// ❌ Before: Mixed concerns
-class UserService {
-  async register(req: Request): Promise<Response> {
-    const user = await db.query('SELECT * FROM users WHERE email = $1', [req.body.email]);
-    if (user) throw new Error('Exists');
-    await db.query('INSERT INTO users...');
-    await sendEmail(req.body.email);
-    return res.json({ success: true });
-  }
-}
-
-// ✅ After: Extracted entity
-class User {
-  constructor(public id: string, public email: string) {}
-  // Business logic here
-}
-```
-
-### Step 3: Create Use Cases
-```typescript
-// ✅ Extract application logic
-class RegisterUserUseCase {
-  async execute(email: string, password: string): Promise<User> {
-    // Application business rules
-  }
-}
-```
-
-### Step 4: Create Adapters
-```typescript
-// ✅ Separate database adapter
-class PostgresUserRepository implements IUserRepository {
-  // Database-specific code
-}
-```
-
-## Test-Driven Development (TDD)
-
-**ALWAYS write tests before implementation. Follow the Red-Green-Refactor cycle.**
-
-### TDD Workflow
-
-```typescript
-// 1. RED: Write failing test first
-describe('createUser', () => {
-  it('should create user with valid email and hashed password', () => {
-    const user = createUser('test@example.com', 'password123');
-    
-    expect(user.email).toBe('test@example.com');
-    expect(user.passwordHash).not.toBe('password123'); // Should be hashed
-    expect(user.id).toBeDefined();
-    expect(user.createdAt).toBeInstanceOf(Date);
-  });
-  
-  it('should throw error for invalid email', () => {
-    expect(() => createUser('invalid-email', 'password123'))
-      .toThrow('Invalid email format');
-  });
-});
-
-// 2. GREEN: Write minimal code to pass
-export function createUser(email: string, password: string): User {
-  if (!isValidEmail(email)) {
-    throw new Error('Invalid email format');
-  }
-  
-  return {
-    id: generateId(),
-    email,
-    passwordHash: hashPassword(password),
-    createdAt: new Date(),
-  };
-}
-
-// 3. REFACTOR: Clean up while keeping tests green
-```
-
-### Why Test-First?
-
-- **Design pressure**: Tests force you to think about interfaces before implementation
-- **Testable code**: Code written to be tested is naturally more modular and decoupled
-- **Living documentation**: Tests show how code is meant to be used
-- **Confidence**: Refactor freely knowing tests will catch breakage
-- **No test debt**: Tests are written, not "TODO"
-
-### TDD Best Practices
-
-```typescript
-// ✅ DO: Test behavior, not implementation
-it('should return active users', () => {
-  const users = filterActiveUsers(allUsers);
-  expect(users.every(u => u.isActive)).toBe(true);
-});
-
-// ❌ DON'T: Test internal implementation details
-it('should call isActive method', () => {
-  expect(mockUser.isActive).toHaveBeenCalled(); // Fragile!
-});
-
-// ✅ DO: Use descriptive test names that explain business rules
-it('should reject orders when inventory is insufficient', () => {
-  // ...
-});
-
-// ❌ DON'T: Use vague test names
-it('should work correctly', () => {
-  // What does "correctly" mean?
-});
-
-// ✅ DO: Arrange-Act-Assert (AAA) pattern
-it('should calculate total with tax', () => {
-  // Arrange
-  const items = [{ price: 100 }, { price: 200 }];
-  const taxRate = 0.1;
-  
-  // Act
-  const total = calculateTotal(items, taxRate);
-  
-  // Assert
-  expect(total).toBe(330); // (100 + 200) * 1.1
-});
-```
-
-### Test Coverage Goals
-
-- **Entities/Domain**: 100% coverage - critical business logic
-- **Use Cases**: 90%+ coverage - application logic paths
-- **Adapters**: 80%+ coverage - focus on error handling
-- **Integration**: Key user journeys and edge cases
-
-## Rules Summary
-
-- **ALWAYS** write tests BEFORE writing implementation code (TDD)
-- **ALWAYS** keep entities framework-free
-- **ALWAYS** define interfaces in use cases, implement in adapters
-- **ALWAYS** point dependencies inward (outer layers depend on inner)
-- **ALWAYS** test each layer independently with appropriate coverage
-- **NEVER** import frameworks in entities or use cases
-- **NEVER** let inner layers know about outer layers
-- **NEVER** skip writing tests (no test debt)
-- **PREFER** dependency injection over direct instantiation
-- **PREFER** small, focused use cases over large service classes
-- **PREFER** testing behavior over implementation details