# Clean Architecture in TypeScript This guide shows how to implement clean architecture principles in TypeScript, focusing on interface-based dependency injection, the `*.system.ts` naming convention, and constructor-based DI patterns. **See also**: [Clean Architecture for AI Agents](./agents.clean.arch.md) - Language-agnostic principles ## Target Audience AI agents refactoring TypeScript/Node.js/Bun projects to improve testability, test coverage, and separation of concerns using clean architecture patterns. ## Problem Statement TypeScript codebases often mix business logic with system interactions (file I/O, shell execution, network calls, database queries). This creates several issues: **Testing challenges:** - Cannot unit test without triggering real system operations - Tests become slow, flaky, and environment-dependent - Complex mocking required for every test **Coverage challenges:** - Business logic coverage diluted by untestable system calls - Coverage metrics don't reflect actual code complexity - Must exclude entire files from coverage, losing visibility into business logic **Maintenance challenges:** - System interaction code scattered across many files - Hard to change system interaction strategy (e.g., switch from child_process to worker_threads) - Difficult to mock system behavior for testing edge cases ## Solution Pattern Use **interface-based dependency injection** with a **naming convention** to separate concerns: 1. **Interface** - Define contracts for system operations 2. **System implementation** - Thin wrapper around actual system calls (excluded from coverage) 3. **Mock implementation** - In-memory test doubles 4. **Business logic** - Uses interface, fully testable ### File Naming Convention **Standard naming pattern:** - **Interface**: `{domain}-interface.ts` (pure TypeScript types, no .system suffix) - **System wrapper**: `{domain}.system.ts` (actual system calls, excluded from coverage) - **Mock**: `tests/mocks/{domain}-mock.ts` (test doubles) - **Business logic**: Original filename or separate module **Benefits of `*.system.ts` convention:** - **Self-documenting** - File name clearly indicates system interaction - **Simple exclusion** - Single glob pattern (`**/*.system.ts`) in coverage config - **Scalable** - Works for all future refactorings without config changes - **Discoverable** - Easy to find all system boundary files ### Folder Organization **Module-based structure (Recommended):** Organize related files into feature/module folders: ```typescript // ✅ GOOD - Module folder with clear separation src/utils/onepassword/ ├── index.ts // Public API: re-export public functions ├── cli-interface.ts // IOnePasswordCLI interface definition ├── cli.system.ts // System implementation (excluded from coverage) ├── session.ts // Business logic: session management ├── resolver.ts // Business logic: secret resolution └── secrets.ts // Business logic: secret parsing tests/mocks/onepassword/ └── cli-mock.ts // Mock implementation for testing // Import from module import { authenticate, readSecret } from '@/utils/onepassword'; ``` **Flat structure (Current, but less scalable):** ```typescript // ⚠️ ACCEPTABLE - Flat structure with prefixes src/utils/ ├── onepassword-cli-interface.ts ├── onepassword-cli.system.ts ├── onepassword-session.ts ├── onepassword-resolver.ts ├── onepassword-secrets.ts └── onepassword.ts // Re-exports tests/mocks/ └── onepassword-cli-mock.ts // Import with full names import { authenticate } from '@/utils/onepassword-session'; import { readSecret } from '@/utils/onepassword-resolver'; ``` **Benefits of module folders:** 1. **Co-location** - All related code in one directory 2. **Clear boundaries** - Module folder defines public API via `index.ts` 3. **Easier to find** - All onepassword code in `onepassword/` folder 4. **Scales better** - Add new modules without cluttering parent directory 5. **Testability** - Module-level mocks in `tests/mocks/{module}/` 6. **Refactoring** - Move entire module without updating many imports **When to use each:** - **Module folders**: 5+ related files, clear domain boundary - **Flat structure**: 2-3 related files, simple utility functions **Real-world example transformation:** ```diff # Before (flat structure) src/utils/ + onepassword-cli-interface.ts (42 lines) + onepassword-cli.system.ts (179 lines) + onepassword-session.ts (254 lines) + onepassword-resolver.ts (331 lines) + onepassword-secrets.ts (187 lines) + onepassword.ts (15 lines) = 1,008 lines across 6 files with "onepassword-" prefix # After (module structure) src/utils/op/ + index.ts (275 lines - namespaced public API) + cli-interface.ts (42 lines) + cli.system.ts (179 lines) + session.ts (254 lines) + resolver.ts (331 lines) + secrets.ts (187 lines) = Same 1,008 lines, better organized # Import comparison - import { parseSecretReference, buildSecretReference } from '@/utils/onepassword-secrets'; + import { Secrets } from '@/utils/op'; + Secrets.parse('op://...'); + Secrets.build({ vault: 'Private', item: 'API', field: 'token' }); ``` ### Clean Namespace API Pattern **Problem**: Exporting many individual functions creates messy imports and unclear API boundaries. ```typescript // ❌ BAD - Function-based exports are verbose and unclear import { parseSecretReference, buildSecretReference, validateSecretReference, findSecretReferences, extractSecretReferences, hasSecretReferences, redactSecretReferences, isSecretReference, getOnePasswordStatus, getOnePasswordCLIPath, getOnePasswordCLIVersion, isOnePasswordCLIAvailable, authenticateWithSession, readSecretWithSession, signOut, } from '@/utils/op'; // Use functions const result = parseSecretReference('op://Private/API/token'); const status = await getOnePasswordStatus(); ``` **Solution**: Use namespaced classes with static methods for cleaner API. ```typescript // ✅ GOOD - Namespaced classes provide clear boundaries import { Secrets, Status, Session } from '@/utils/op'; // Use namespaced methods const result = Secrets.parse('op://Private/API/token'); const status = await Status.get(); await Session.authenticate(); ``` **Implementation pattern:**
Step 1: Module files export functions AND classes Each module file exports both functions and a namespaced class: ```typescript // src/utils/op/secrets.ts // Individual functions (implementation) export function parseSecretReference(uri: string): ParseResult { // Implementation } export function buildSecretReference(ref: SecretReference): string { // Implementation } export function validateSecretReference(ref: SecretReference): ParseResult { // Implementation } // Namespaced class (public API) export class Secrets { static build = buildSecretReference; static extract = extractSecretReferences; static find = findSecretReferences; static has = hasSecretReferences; static is = isSecretReference; static parse = parseSecretReference; static redact = redactSecretReferences; static validate = validateSecretReference; } ``` **Why both exports?** - **Functions**: Backward compatibility, tree-shaking optimization - **Class**: Clean namespace API, better discoverability
Step 2: Index.ts re-exports classes The `index.ts` file simply re-exports classes from modules: ```typescript // src/utils/op/index.ts // ============================================================================ // Namespaced Class Exports // ============================================================================ export { Errors } from './errors.js'; export { Resolver } from './resolver.js'; export { Secrets } from './secrets.js'; export { Session } from './session.js'; export { Setup } from './setup.js'; export { Status } from './status.js'; // ============================================================================ // Individual Function Exports (for backward compatibility) // NOTE: Only applicable if the library is used externally in production, or we are not // moving to a new major version. // Always ASK THE USER if they need this unless this is only used inside the // project itself. // ============================================================================ export { parseSecretReference, buildSecretReference, validateSecretReference, // ... other functions } from './secrets.js'; // Export types directly export type { ParseResult, SecretReference } from './secrets.js'; export type { OnePasswordStatus } from './status.js'; export type { AuthResult } from './session.js'; ``` **Benefits of this approach:** - Classes are defined where implementation lives - `index.ts` is a simple re-export gateway - Maintainers see class and functions together in same file - No mental mapping between file structure and API surface
Step 3: Consumers use namespaced API Application code imports and uses namespaced classes: ```typescript // src/services/config-loader.ts import { Secrets, Session } from '@/utils/op'; export async function loadSecretConfig(configText: string): Promise { // Check if config contains secrets if (!Secrets.has(configText)) { return parseConfig(configText); } // Authenticate if needed if (!Session.isValid()) { await Session.authenticate(); } // Resolve all secrets in config const resolved = await Resolver.resolveInText(configText); return parseConfig(resolved.text); } ```
**Benefits of namespaced classes:** 1. **Clear organization** - Related functions grouped under logical namespaces 2. **Discoverable API** - IDE autocomplete shows `Secrets.` and lists all secret operations 3. **Self-documenting** - Class name indicates domain (`Secrets`, `Session`, `Status`) 4. **Easier imports** - Import 3 classes instead of 20 functions 5. **Better tree-shaking** - Unused namespaces can be eliminated by bundlers 6. **Consistent naming** - `Secrets.parse()` instead of `parseSecretReference()` 7. **Type safety** - Same TypeScript checking as functions 8. **No runtime overhead** - Static methods compile to function calls **API comparison:** | Pattern | Import Statement | Usage | Clarity | | -------------------- | ------------------------------------ | ---------------------------------- | ---------- | | Individual functions | `import { parseSecret... } from '.'` | `parseSecretReference('op://...')` | ❌ Verbose | | Namespaced classes | `import { Secrets } from '.'` | `Secrets.parse('op://...')` | ✅ Clear | | Default export | `import secrets from '.'` | `secrets.parse('op://...')` | ⚠️ Opaque | | Instance methods | `const s = new Secrets(); s.parse()` | Creates unnecessary instances | ❌ Wrong | **When to use this pattern:** - **5+ related functions** - Namespace reduces import clutter - **Clear domain boundaries** - Functions naturally group by purpose - **Stable API** - Public API unlikely to change frequently - **Module folders** - Works best with organized folder structure **When NOT to use:** - **1-3 utility functions** - Direct exports are simpler - **Mixed concerns** - Functions don't group naturally - **Tree-shakeable critical** - Function-level exports optimize better in some bundlers **Coverage note**: `index.ts` files with only re-exports should be excluded from coverage: ```toml # bunfig.toml [test] coveragePathIgnorePatterns = [ "**/*.system.ts", "**/index.ts", # Re-export files have no business logic ] ``` ## Step-by-Step Refactoring Process ### Step 1: Identify System Boundaries Find files that mix business logic with system interactions: ```typescript // ❌ Mixed concerns - hard to test export async function processUserData(userId: string): Promise { // Business logic if (!userId || userId.length < 5) { throw new Error('Invalid user ID'); } // System interaction (blocks testing) const { stdout } = await execAsync(`curl https://api.example.com/users/${userId}`); const rawData = JSON.parse(stdout); // Business logic return { id: rawData.id, name: rawData.full_name.toUpperCase(), email: rawData.email_address, verified: rawData.status === 'active', }; } ``` **Identify the boundary:** - **Business logic**: Validation, transformation, business rules - **System interaction**: HTTP calls, file I/O, process execution, database queries ### Step 2: Define Interface Create an interface that describes all system operations: ```typescript // src/services/user-api-interface.ts /** * User API system operations interface * Abstracts HTTP calls for testability */ export interface IUserAPI { /** * Fetch user data from remote API * * @param userId - User identifier * @returns Raw user data from API * @throws {Error} If API call fails or user not found */ fetchUser(userId: string): Promise; /** * Update user data via API * * @param userId - User identifier * @param updates - Fields to update * @returns Updated user data */ updateUser(userId: string, updates: Partial): Promise; } /** * Raw API response shape */ export interface RawUserData { id: string; full_name: string; email_address: string; status: 'active' | 'inactive' | 'suspended'; created_at: string; } ``` **Interface design guidelines:** - **One interface per system boundary** (HTTP client, database, file system, etc.) - **Synchronous when possible** - Use sync methods for file system if business logic needs sync behavior - **Throw errors** - Don't return error codes; use exceptions for system failures - **Platform-agnostic** - Abstract away OS-specific details - **Minimal surface area** - Only expose operations actually needed by business logic ### Step 3: Create System Implementation Implement the interface with actual system calls in a `*.system.ts` file: ```typescript // src/services/user-api.system.ts import { exec } from 'node:child_process'; import { promisify } from 'node:util'; import type { IUserAPI, RawUserData } from './user-api-interface.js'; const execAsync = promisify(exec); /** * Real User API implementation using curl * * **Coverage note**: This file uses the .system.ts suffix and is automatically * excluded from coverage via glob pattern: **\/*.system.ts * * This is a thin wrapper with no business logic - all system interaction. * * @file user-api.system.ts */ export class UserAPISystem implements IUserAPI { constructor(private baseURL: string = 'https://api.example.com') {} async fetchUser(userId: string): Promise { try { const { stdout } = await execAsync(`curl -s ${this.baseURL}/users/${userId}`); return JSON.parse(stdout); } catch (error) { throw new Error( `Failed to fetch user ${userId}: ${error instanceof Error ? error.message : String(error)}` ); } } async updateUser(userId: string, updates: Partial): Promise { try { const payload = JSON.stringify(updates); const { stdout } = await execAsync( `curl -s -X PATCH -H "Content-Type: application/json" -d '${payload}' ${this.baseURL}/users/${userId}` ); return JSON.parse(stdout); } catch (error) { throw new Error( `Failed to update user ${userId}: ${error instanceof Error ? error.message : String(error)}` ); } } } /** * Singleton instance for convenience * Use this in production code */ export const defaultUserAPI = new UserAPISystem(); ``` **System implementation guidelines:** - **Keep it thin** - No business logic, only system call wrappers - **Document exclusion** - Add comment about `*.system.ts` coverage exclusion - **Provide default instance** - Export singleton for convenience - **Error translation** - Convert system errors to domain exceptions - **Configuration via constructor** - Allow dependency injection of config (URLs, paths, etc.) ### Step 4: Create Mock Implementation Create a test double that implements the interface with in-memory operations: ```typescript // tests/mocks/user-api-mock.ts import type { IUserAPI, RawUserData } from '../../src/services/user-api-interface.js'; /** * Mock User API for testing * No network calls, all operations are in-memory */ export class UserAPIMock implements IUserAPI { private users = new Map(); private fetchShouldFail = false; private updateShouldFail = false; /** * Pre-populate mock with user data */ setUser(userId: string, data: RawUserData): void { this.users.set(userId, data); } /** * Simulate API failures for error testing */ setFetchShouldFail(fail: boolean): void { this.fetchShouldFail = fail; } setUpdateShouldFail(fail: boolean): void { this.updateShouldFail = fail; } /** * Clear all mock data */ clear(): void { this.users.clear(); this.fetchShouldFail = false; this.updateShouldFail = false; } // IUserAPI implementation async fetchUser(userId: string): Promise { if (this.fetchShouldFail) { throw new Error('Network error: Connection timeout'); } const user = this.users.get(userId); if (!user) { throw new Error(`User not found: ${userId}`); } return user; } async updateUser(userId: string, updates: Partial): Promise { if (this.updateShouldFail) { throw new Error('Network error: Server returned 500'); } const existing = this.users.get(userId); if (!existing) { throw new Error(`User not found: ${userId}`); } const updated = { ...existing, ...updates }; this.users.set(userId, updated); return updated; } } ``` **Mock implementation guidelines:** - **Implement full interface** - All methods from system interface - **In-memory state** - No actual system calls - **Configuration methods** - Allow tests to control behavior (simulate failures, set data) - **Realistic behavior** - Throw same errors as real implementation - **Stateful** - Maintain state across calls within a test ### Step 5: Refactor Business Logic Update business logic to accept interface parameter with default value: ```typescript // src/services/user-service.ts import type { IUserAPI, RawUserData } from './user-api-interface.js'; import { defaultUserAPI } from './user-api.system.js'; /** * Normalized user model for application use */ export interface User { id: string; name: string; email: string; verified: boolean; } /** * Process and normalize user data * * @param userId - User identifier * @param api - User API implementation (defaults to real API) * @returns Normalized user object * @throws {Error} If user ID invalid or API call fails */ export async function processUserData( userId: string, api: IUserAPI = defaultUserAPI ): Promise { // Business logic: Validation if (!userId || userId.length < 5) { throw new Error('Invalid user ID: must be at least 5 characters'); } // System interaction (delegated to interface) const rawData = await api.fetchUser(userId); // Business logic: Transformation return { id: rawData.id, name: rawData.full_name.toUpperCase(), email: rawData.email_address, verified: rawData.status === 'active', }; } /** * Update user status * * @param userId - User identifier * @param active - Whether user should be active * @param api - User API implementation (defaults to real API) */ export async function updateUserStatus( userId: string, active: boolean, api: IUserAPI = defaultUserAPI ): Promise { // Business logic: Determine status value const status: RawUserData['status'] = active ? 'active' : 'inactive'; // System interaction (delegated to interface) await api.updateUser(userId, { status }); } ``` **Refactoring guidelines:** - **Add interface parameter last** - With default value for backward compatibility - **Use interface type** - Not concrete implementation type - **Keep business logic pure** - All system interaction through interface - **Maintain public API** - Existing callers work without changes - **Document parameter** - Explain why interface is injectable ### Step 6: Write Tests Use mock implementation for fast, deterministic tests: ```typescript // tests/unit/services/user-service.test.ts import { describe, expect, it, beforeEach } from 'bun:test'; import { UserAPIMock } from '../../mocks/user-api-mock.js'; import { processUserData, updateUserStatus } from '../../../src/services/user-service.js'; describe('User Service', () => { let mockAPI: UserAPIMock; beforeEach(() => { mockAPI = new UserAPIMock(); }); describe('processUserData', () => { it('should normalize user data from API', async () => { // Arrange mockAPI.setUser('user-12345', { id: 'user-12345', full_name: 'john doe', email_address: 'john@example.com', status: 'active', created_at: '2024-01-01T00:00:00Z', }); // Act const user = await processUserData('user-12345', mockAPI); // Assert expect(user).toEqual({ id: 'user-12345', name: 'JOHN DOE', // Uppercased email: 'john@example.com', verified: true, // active -> verified }); }); it('should reject invalid user IDs', async () => { // Act & Assert await expect(processUserData('123', mockAPI)).rejects.toThrow( 'Invalid user ID: must be at least 5 characters' ); }); it('should handle API failures', async () => { // Arrange mockAPI.setFetchShouldFail(true); // Act & Assert await expect(processUserData('user-12345', mockAPI)).rejects.toThrow('Network error'); }); it('should mark inactive users as unverified', async () => { // Arrange mockAPI.setUser('user-12345', { id: 'user-12345', full_name: 'jane doe', email_address: 'jane@example.com', status: 'inactive', created_at: '2024-01-01T00:00:00Z', }); // Act const user = await processUserData('user-12345', mockAPI); // Assert expect(user.verified).toBe(false); }); }); describe('updateUserStatus', () => { beforeEach(() => { mockAPI.setUser('user-12345', { id: 'user-12345', full_name: 'john doe', email_address: 'john@example.com', status: 'active', created_at: '2024-01-01T00:00:00Z', }); }); it('should activate user', async () => { // Act await updateUserStatus('user-12345', true, mockAPI); // Assert const updated = await mockAPI.fetchUser('user-12345'); expect(updated.status).toBe('active'); }); it('should deactivate user', async () => { // Act await updateUserStatus('user-12345', false, mockAPI); // Assert const updated = await mockAPI.fetchUser('user-12345'); expect(updated.status).toBe('inactive'); }); it('should handle update failures', async () => { // Arrange mockAPI.setUpdateShouldFail(true); // Act & Assert await expect(updateUserStatus('user-12345', true, mockAPI)).rejects.toThrow('Network error'); }); }); }); ``` **Test guidelines:** - **No system calls** - Tests run in-memory only - **Fast execution** - Entire suite should run in seconds - **Deterministic** - Same inputs always produce same outputs - **Test business logic** - Focus on validation, transformation, error handling - **Test error paths** - Use mock configuration to simulate failures ### Step 7: Configure Coverage Exclusion Add `*.system.ts` pattern to coverage configuration:
Bun (bunfig.toml) ```toml [test] coveragePathIgnorePatterns = [ "**/*.system.ts", # All system interaction files "tests/**", # Test files "**/*.test.ts", # More test files "**/types/**", # Type definition files ] ```
Jest (jest.config.js) ```javascript export default { coveragePathIgnorePatterns: [ '.*\\.system\\.ts$', // All system interaction files '/node_modules/', '/tests/', '\\.test\\.ts$', ], }; ```
Vitest (vitest.config.ts) ```typescript export default defineConfig({ test: { coverage: { exclude: [ '**/*.system.ts', // All system interaction files 'tests/**', '**/*.test.ts', '**/types/**', ], }, }, }); ```
SonarQube (sonar-project.properties) ```properties # Coverage exclusions sonar.coverage.exclusions=\ **/*.system.ts,\ tests/**,\ **/*.test.ts,\ **/types/** ```
## Common Patterns ### Pattern 1: File System Operations
File system abstraction example **Interface:** ```typescript // src/utils/filesystem-interface.ts export interface IFileSystem { readFile(path: string, encoding: BufferEncoding): Promise; writeFile(path: string, content: string, encoding: BufferEncoding): Promise; exists(path: string): Promise; mkdir(path: string, options?: { recursive?: boolean }): Promise; readdir(path: string): Promise; } ``` **System implementation:** ```typescript // src/utils/filesystem.system.ts import { readFile, writeFile, access, mkdir, readdir } from 'node:fs/promises'; import type { IFileSystem } from './filesystem-interface.js'; export class FileSystemReal implements IFileSystem { async readFile(path: string, encoding: BufferEncoding): Promise { return readFile(path, encoding); } async writeFile(path: string, content: string, encoding: BufferEncoding): Promise { await writeFile(path, content, encoding); } async exists(path: string): Promise { try { await access(path); return true; } catch { return false; } } async mkdir(path: string, options?: { recursive?: boolean }): Promise { await mkdir(path, options); } async readdir(path: string): Promise { return readdir(path); } } export const defaultFS = new FileSystemReal(); ``` **Mock:** ```typescript // tests/mocks/filesystem-mock.ts export class FileSystemMock implements IFileSystem { private files = new Map(); private dirs = new Set(); setFile(path: string, content: string): void { this.files.set(path, content); } setDir(path: string): void { this.dirs.add(path); } clear(): void { this.files.clear(); this.dirs.clear(); } async readFile(path: string, encoding: BufferEncoding): Promise { const content = this.files.get(path); if (!content) throw new Error(`ENOENT: no such file or directory, open '${path}'`); return content; } async writeFile(path: string, content: string, encoding: BufferEncoding): Promise { this.files.set(path, content); } async exists(path: string): Promise { return this.files.has(path) || this.dirs.has(path); } async mkdir(path: string, options?: { recursive?: boolean }): Promise { this.dirs.add(path); } async readdir(path: string): Promise { if (!this.dirs.has(path)) throw new Error(`ENOENT: no such file or directory, scandir '${path}'`); return Array.from(this.files.keys()).filter((f) => f.startsWith(path + '/')); } } ```
### Pattern 2: Shell Command Execution
Shell execution abstraction example **Interface:** ```typescript // src/utils/shell-interface.ts export interface IShellExecutor { exec(command: string): Promise<{ stdout: string; stderr: string; exitCode: number }>; execSync(command: string): { stdout: string; stderr: string; exitCode: number }; commandExists(command: string): Promise; } ``` **System implementation:** ```typescript // src/utils/shell.system.ts import { exec, execSync as nodeExecSync } from 'node:child_process'; import { promisify } from 'node:util'; import type { IShellExecutor } from './shell-interface.js'; const execAsync = promisify(exec); export class ShellExecutorReal implements IShellExecutor { async exec(command: string): Promise<{ stdout: string; stderr: string; exitCode: number }> { try { const { stdout, stderr } = await execAsync(command); return { stdout, stderr, exitCode: 0 }; } catch (error: any) { return { stdout: error.stdout || '', stderr: error.stderr || '', exitCode: error.code || 1, }; } } execSync(command: string): { stdout: string; stderr: string; exitCode: number } { try { const stdout = nodeExecSync(command, { encoding: 'utf-8' }); return { stdout, stderr: '', exitCode: 0 }; } catch (error: any) { return { stdout: error.stdout || '', stderr: error.stderr || '', exitCode: error.status || 1, }; } } async commandExists(command: string): Promise { const result = await this.exec(`command -v ${command}`); return result.exitCode === 0; } } export const defaultShell = new ShellExecutorReal(); ``` **Mock:** ```typescript // tests/mocks/shell-mock.ts export class ShellExecutorMock implements IShellExecutor { private commands = new Map(); private availableCommands = new Set(['ls', 'cat', 'grep']); setCommandOutput(command: string, stdout: string, stderr = '', exitCode = 0): void { this.commands.set(command, { stdout, stderr, exitCode }); } setCommandExists(command: string, exists: boolean): void { if (exists) { this.availableCommands.add(command); } else { this.availableCommands.delete(command); } } clear(): void { this.commands.clear(); } async exec(command: string): Promise<{ stdout: string; stderr: string; exitCode: number }> { const result = this.commands.get(command); if (result) return result; // Default behavior for unknown commands return { stdout: '', stderr: `sh: command not found: ${command}`, exitCode: 127 }; } execSync(command: string): { stdout: string; stderr: string; exitCode: number } { return this.exec(command) as any; // Sync version returns same data } async commandExists(command: string): Promise { return this.availableCommands.has(command); } } ```
### Pattern 3: HTTP Client
HTTP client abstraction example **Interface:** ```typescript // src/utils/http-interface.ts export interface IHTTPClient { get(url: string, headers?: Record): Promise; post(url: string, body: any, headers?: Record): Promise; put(url: string, body: any, headers?: Record): Promise; delete(url: string, headers?: Record): Promise; } ``` **System implementation:** ```typescript // src/utils/http.system.ts export class HTTPClientReal implements IHTTPClient { async get(url: string, headers?: Record): Promise { const response = await fetch(url, { method: 'GET', headers }); if (!response.ok) throw new Error(`HTTP ${response.status}: ${response.statusText}`); return response.json(); } async post(url: string, body: any, headers?: Record): Promise { const response = await fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/json', ...headers }, body: JSON.stringify(body), }); if (!response.ok) throw new Error(`HTTP ${response.status}: ${response.statusText}`); return response.json(); } async put(url: string, body: any, headers?: Record): Promise { const response = await fetch(url, { method: 'PUT', headers: { 'Content-Type': 'application/json', ...headers }, body: JSON.stringify(body), }); if (!response.ok) throw new Error(`HTTP ${response.status}: ${response.statusText}`); return response.json(); } async delete(url: string, headers?: Record): Promise { const response = await fetch(url, { method: 'DELETE', headers }); if (!response.ok) throw new Error(`HTTP ${response.status}: ${response.statusText}`); return response.json(); } } export const defaultHTTP = new HTTPClientReal(); ``` **Mock:** ```typescript // tests/mocks/http-mock.ts export class HTTPClientMock implements IHTTPClient { private routes = new Map(); private shouldFail = false; setRoute(method: string, url: string, response: any): void { this.routes.set(`${method}:${url}`, response); } setShouldFail(fail: boolean): void { this.shouldFail = fail; } clear(): void { this.routes.clear(); this.shouldFail = false; } async get(url: string, headers?: Record): Promise { if (this.shouldFail) throw new Error('HTTP 500: Internal Server Error'); const response = this.routes.get(`GET:${url}`); if (!response) throw new Error(`HTTP 404: Not Found`); return response; } async post(url: string, body: any, headers?: Record): Promise { if (this.shouldFail) throw new Error('HTTP 500: Internal Server Error'); const response = this.routes.get(`POST:${url}`); if (!response) throw new Error(`HTTP 404: Not Found`); return response; } async put(url: string, body: any, headers?: Record): Promise { if (this.shouldFail) throw new Error('HTTP 500: Internal Server Error'); const response = this.routes.get(`PUT:${url}`); if (!response) throw new Error(`HTTP 404: Not Found`); return response; } async delete(url: string, headers?: Record): Promise { if (this.shouldFail) throw new Error('HTTP 500: Internal Server Error'); const response = this.routes.get(`DELETE:${url}`); if (!response) throw new Error(`HTTP 404: Not Found`); return response; } } ```
## Benefits Summary ### Testing Benefits - **Fast tests** - No system calls, all in-memory - **Deterministic** - Same inputs always produce same outputs - **Isolated** - No external dependencies - **Comprehensive** - Easy to test edge cases and error paths - **No mocking complexity** - Simple mock classes instead of complex spy setups ### Coverage Benefits - **Accurate metrics** - Coverage reflects business logic complexity - **Focused exclusions** - Only thin system wrappers excluded - **Better visibility** - Business logic coverage clearly visible - **Scalable pattern** - One glob pattern covers all system files ### Maintainability Benefits - **Clear boundaries** - Business logic vs. system interaction - **Single responsibility** - System files only do system calls - **Easy to change** - Swap system implementation without touching business logic - **Type safety** - Interface contract enforced at compile time - **Self-documenting** - File naming convention makes architecture clear ## Migration Checklist When refactoring existing code: - [ ] Identify file with mixed business logic and system calls - [ ] Define interface for system operations (`{domain}-interface.ts`) - [ ] Create system implementation (`{domain}.system.ts`) - [ ] Create mock implementation (`tests/mocks/{domain}-mock.ts`) - [ ] Refactor business logic to accept interface parameter - [ ] Add default parameter for backward compatibility - [ ] Update tests to use mock implementation - [ ] Add `**/*.system.ts` to coverage exclusion config - [ ] Verify all tests pass with mocks - [ ] Verify production code works with real implementation - [ ] Remove old file from coverage exclusion list (if it was excluded) - [ ] Update documentation to explain new architecture ## Anti-Patterns to Avoid **Don't put business logic in `*.system.ts` files:** ```typescript // ❌ BAD - Business logic in system file export class UserAPISystem implements IUserAPI { async fetchUser(userId: string): Promise { // Business logic belongs in service layer, not here if (!userId || userId.length < 5) { throw new Error('Invalid user ID'); } const { stdout } = await execAsync(`curl ${this.baseURL}/users/${userId}`); return JSON.parse(stdout); } } ``` ```typescript // ✅ GOOD - Pure system interaction export class UserAPISystem implements IUserAPI { async fetchUser(userId: string): Promise { const { stdout } = await execAsync(`curl ${this.baseURL}/users/${userId}`); return JSON.parse(stdout); } } ``` **Don't create overly broad interfaces:** ```typescript // ❌ BAD - Too many responsibilities export interface ISystem { execCommand(cmd: string): Promise; readFile(path: string): Promise; httpGet(url: string): Promise; queryDatabase(sql: string): Promise; } ``` ```typescript // ✅ GOOD - Focused interfaces export interface IShellExecutor { exec(command: string): Promise<{ stdout: string; stderr: string }>; } export interface IFileSystem { readFile(path: string, encoding: BufferEncoding): Promise; } export interface IHTTPClient { get(url: string): Promise; } export interface IDatabase { query(sql: string, params?: any[]): Promise; } ``` **Don't skip the interface:** ```typescript // ❌ BAD - Direct dependency on concrete class export async function processUser(userId: string, api: UserAPISystem): Promise { // Now can't substitute mock } ``` ```typescript // ✅ GOOD - Depend on interface export async function processUser(userId: string, api: IUserAPI): Promise { // Can use real or mock implementation } ``` ## Related Documentation - [Clean Architecture for AI Agents](./agents.clean.arch.md) - Language-agnostic clean architecture principles - [Task Master AI Integration](./agents.task-master.md) - Project task management - [GoTask Usage Guide](./agents.gotask.md) - Build automation patterns - [Markdown Standards](./agents.markdown.md) - Documentation formatting --- **For AI Agents**: This guide implements clean architecture principles for TypeScript. Use `*.system.ts` naming convention for system interaction files, define interfaces for all external dependencies, and use constructor-based dependency injection for testable code.