1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

// A high-level HTTP client abstraction
interface HttpClient {
    get<T>(url: string, options?: RequestOptions): Promise<T>;
    post<T>(url: string, body: unknown, options?: RequestOptions): Promise<T>;
    put<T>(url: string, body: unknown, options?: RequestOptions): Promise<T>;
    delete<T>(url: string, options?: RequestOptions): Promise<T>;
}
 
// What this abstraction OMITS:
// - Connection pooling and lifecycle
// - DNS resolution
// - TLS handshake details
// - TCP packet management
// - HTTP/2 multiplexing
// - Request queuing and retry logic
// - Cookie management
// - Proxy configuration
// - Certificate validation
// - Compression negotiation
// - Timeout implementation
// - Redirect handling
 
// What this abstraction EXPOSES:
// - Request methods (GET, POST, PUT, DELETE)
// - URLs and bodies
// - Response types
// - High-level configuration (headers, auth)
 
// The USER of this abstraction thinks:
// "Send request, get response"
// NOT:
// "Establish TCP connection, negotiate TLS, send HTTP frames..."

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

// REALITY: A database record is...
// - Bytes on disk or SSD
// - Indexed by B-tree structures
// - Cached in multiple memory layers
// - Protected by locks and MVCC
// - Replicated across nodes
// - Logged in a write-ahead log
// - Subject to vacuum and compaction
 
// MODEL: We abstract it as an "entity"
interface User {
    id: string;
    email: string;
    name: string;
    createdAt: Date;
}
 
// The model is "wrong" — a User isn't really an object with fields.
// It's a complex dance of bytes, indexes, and transactions.
 
// But the model is USEFUL — we can reason about users
// without thinking about storage internals:
 
async function updateUserEmail(userId: string, newEmail: string): Promise<User> {
    // This simple code hides enormous complexity:
    // - Connection pooling to the database
    // - Transaction management
    // - Index updates
    // - Replication propagation
    // - Audit logging
    
    const user = await userRepository.findById(userId);
    user.email = newEmail;
    return userRepository.save(user);
}
 
// The programmer thinks in terms of the MODEL (users with emails)
// not the REALITY (bytes, indexes, transactions).
// This is abstraction enabling productive thinking.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

// BEFORE: Specific implementations with duplicated structure
 
async function fetchUsersFromAPI(): Promise<User[]> {
    const response = await fetch('/api/users');
    if (!response.ok) throw new Error('Failed to fetch users');
    return response.json();
}
 
async function fetchOrdersFromAPI(): Promise<Order[]> {
    const response = await fetch('/api/orders');
    if (!response.ok) throw new Error('Failed to fetch orders');
    return response.json();
}
 
async function fetchProductsFromAPI(): Promise<Product[]> {
    const response = await fetch('/api/products');
    if (!response.ok) throw new Error('Failed to fetch products');
    return response.json();
}
 
// AFTER: Generalized abstraction capturing the common pattern
 
interface ApiClient {
    fetch<T>(endpoint: string): Promise<T>;
}
 
class HttpApiClient implements ApiClient {
    constructor(private baseUrl: string) {}
    
    async fetch<T>(endpoint: string): Promise<T> {
        const response = await fetch(`${this.baseUrl}${endpoint}`);
        if (!response.ok) {
            throw new Error(`Failed to fetch from ${endpoint}`);
        }
        return response.json();
    }
}
 
// Usage becomes simple and consistent
const api = new HttpApiClient('/api');
const users = await api.fetch<User[]>('/users');
const orders = await api.fetch<Order[]>('/orders');
const products = await api.fetch<Product[]>('/products');

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

// Simple, focused validator primitives
interface Validator<T> {
    validate(value: T): ValidationResult;
}
 
const required: Validator<string> = {
    validate: (value) => value ? { valid: true } : { valid: false, error: 'Required' }
};
 
const email: Validator<string> = {
    validate: (value) => /^[^@]+@[^@]+$/.test(value) 
        ? { valid: true } 
        : { valid: false, error: 'Invalid email format' }
};
 
const minLength = (min: number): Validator<string> => ({
    validate: (value) => value.length >= min 
        ? { valid: true } 
        : { valid: false, error: `Must be at least ${min} characters` }
});
 
// COMPOSITION: Build complex validation from simple parts
function compose<T>(...validators: Validator<T>[]): Validator<T> {
    return {
        validate: (value) => {
            for (const validator of validators) {
                const result = validator.validate(value);
                if (!result.valid) return result;
            }
            return { valid: true };
        }
    };
}
 
// Complex validation through simple composition
const emailValidator = compose(required, email);
const passwordValidator = compose(required, minLength(8));
const usernameValidator = compose(required, minLength(3));
 
// Each primitive is trivial to understand.
// The composition is trivial to understand.
// The result handles complex validation.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

// FALSE SIMPLE: Looks simple, but hides critical complexity
 
// This "simple" API hides that:
// - The callback might be called 0, 1, or many times
// - The callback might be async
// - Errors might be swallowed or thrown
// - The request might be cached
// - The request might be retried
// - The order of callbacks is undefined
 
function fetchData(url: string, callback: (data: any) => void): void;
 
// Users discover these issues through painful debugging.
// The "simple" interface creates more work, not less.
 
// ACTUALLY SIMPLE: Explicit about its behavior
 
interface FetchResult<T> {
    data: T;
    cached: boolean;
    attemptCount: number;
}
 
async function fetchData<T>(
    url: string, 
    options?: FetchOptions
): Promise<FetchResult<T>>;
 
// More visible complexity, but less hidden complexity.
// Users know what to expect.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

// KITCHEN SINK: Everything exposed, nothing simplified
 
interface UserManager {
    createUser(user: User): Promise<User>;
    updateUser(user: User): Promise<User>;
    deleteUser(id: string): Promise<void>;
    findById(id: string): Promise<User>;
    findByEmail(email: string): Promise<User>;
    findByUsername(username: string): Promise<User>;
    findByPhone(phone: string): Promise<User>;
    findAll(): Promise<User[]>;
    findAllPaginated(page: number, size: number): Promise<Page<User>>;
    findByDepartment(dept: string): Promise<User[]>;
    findByRole(role: string): Promise<User[]>;
    findByStatus(status: string): Promise<User[]>;
    findByCreatedDateRange(start: Date, end: Date): Promise<User[]>;
    countAll(): Promise<number>;
    countByDepartment(dept: string): Promise<number>;
    countByRole(role: string): Promise<number>;
    existsById(id: string): Promise<boolean>;
    existsByEmail(email: string): Promise<boolean>;
    validateEmail(email: string): Promise<boolean>;
    validatePassword(password: string): Promise<boolean>;
    hashPassword(password: string): Promise<string>;
    verifyPassword(password: string, hash: string): Promise<boolean>;
    auditUserAction(userId: string, action: string): Promise<void>;
    // ... 50 more methods
}
 
// This is not abstraction — it's an everything bundle.
// Users must understand the whole surface area.
// Changes to any method might affect users.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

// LEAKY BUCKET: Implementation details constantly leak
 
// The "abstraction"
interface DatabaseConnection {
    query(sql: string, params: any[]): Promise<any[]>;
}
 
// User code is flooded with implementation concerns:
 
// User must know it's MySQL syntax
const users = await db.query(
    'SELECT * FROM users WHERE created_at > ? LIMIT ?',
    [date, limit]
);
 
// User must handle MySQL-specific errors
try {
    await db.query('INSERT INTO users ...', []);
} catch (error) {
    if (error.code === 'ER_DUP_ENTRY') {  // MySQL-specific!
        // handle duplicate
    }
}
 
// User must understand connection pooling
await db.query('SET SESSION wait_timeout = 28800', []);
 
// The "abstraction" doesn't abstract — it's a thin wrapper
// that still requires MySQL expertise to use correctly.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73

// STEP 1: Identify the essential concept
// What do all notifications share? 
// A recipient, a message, and a delivery mechanism.
 
interface Notification {
    recipient: Recipient;
    message: Message;
    priority: 'low' | 'normal' | 'high' | 'critical';
}
 
// STEP 2: Abstract the recipient
// Hide the complexity of different addressing schemes
 
type Recipient = {
    userId: string;           // System determines how to reach them
    preferredChannels?: Channel[];  // Optional hint
};
 
// STEP 3: Abstract the message
// Hide template engines, formatting, localization
 
interface Message {
    templateId: string;       // Reference to a template
    variables: Record<string, unknown>;  // Template data
    fallbackText: string;     // If template fails
}
 
// STEP 4: Create the simplified interface
 
interface NotificationService {
    send(notification: Notification): Promise<NotificationResult>;
    sendBatch(notifications: Notification[]): Promise<BatchResult>;
    cancel(notificationId: string): Promise<boolean>;
    getStatus(notificationId: string): Promise<NotificationStatus>;
}
 
// STEP 5: Hide channel complexity behind the interface
 
class NotificationServiceImpl implements NotificationService {
    constructor(
        private userService: UserService,
        private templateEngine: TemplateEngine,
        private channels: Map<ChannelType, ChannelProvider>
    ) {}
    
    async send(notification: Notification): Promise<NotificationResult> {
        // 1. Resolve user's contact methods (hidden complexity)
        const contacts = await this.userService.getContacts(
            notification.recipient.userId
        );
        
        // 2. Render message for each channel (hidden complexity)
        const rendered = await this.templateEngine.render(
            notification.message,
            notification.recipient
        );
        
        // 3. Select best channel (hidden complexity)
        const channel = this.selectChannel(
            contacts,
            notification.priority,
            notification.recipient.preferredChannels
        );
        
        // 4. Send through channel (hidden complexity)
        return this.channels.get(channel)!.send(
            contacts[channel],
            rendered[channel]
        );
    }
    
    // ... channel selection logic, retry logic, etc.
}