name: encapsulation
description: Use when exposing internal state. Use when making fields public for convenience. Use when external code modifies object internals.

Encapsulation

Overview

Hide internal state. Expose behavior, not data. Control access through methods.

Public fields let anyone modify your object's internals, bypassing validation and breaking invariants. Encapsulation protects data integrity.

When to Use

• Designing classes with state
• Tempted to make fields public
• External code directly modifies object state
• Invariants can be violated by direct access

The Iron Rule

NEVER expose internal state directly. Always use methods to control access.

No exceptions:
- Not for "it's simpler"
- Not for "we trust callers"
- Not for "it's just data"
- Not for "getters/setters are verbose"

Detection: Exposed State Smell

If internal state is directly accessible, STOP:

// ❌ VIOLATION: Public state
class BankAccount {
  public balance: number = 0;  // Anyone can modify!
  public transactions: Transaction[] = [];
}

// Callers can break invariants
const account = new BankAccount();
account.balance = -1000000;  // Negative balance!
account.transactions = [];   // Audit trail destroyed!

Problems:
- No validation on changes
- Invariants easily violated
- No audit trail
- Can't change internal representation

The Correct Pattern: Private State, Public Methods

// ✅ CORRECT: Encapsulated state
class BankAccount {
  private _balance: number = 0;
  private _transactions: Transaction[] = [];

  get balance(): number {
    return this._balance;
  }

  deposit(amount: number): void {
    if (amount <= 0) {
      throw new Error('Deposit must be positive');
    }

    this._balance += amount;
    this._transactions.push({
      type: 'deposit',
      amount,
      timestamp: new Date()
    });
  }

  withdraw(amount: number): void {
    if (amount <= 0) {
      throw new Error('Withdrawal must be positive');
    }
    if (amount > this._balance) {
      throw new Error('Insufficient funds');
    }

    this._balance -= amount;
    this._transactions.push({
      type: 'withdrawal',
      amount,
      timestamp: new Date()
    });
  }

  getTransactionHistory(): ReadonlyArray<Transaction> {
    return [...this._transactions];  // Return copy
  }
}

// Now invariants are protected
const account = new BankAccount();
account.deposit(100);     // ✅ Validated, logged
account.withdraw(50);     // ✅ Validated, logged
account.balance = -1000;  // ❌ Error: Cannot set

Encapsulation Techniques

1. Private Fields

class User {
  private _password: string;

  setPassword(newPassword: string): void {
    if (newPassword.length < 8) throw new Error('Too short');
    this._password = hash(newPassword);
  }

  checkPassword(attempt: string): boolean {
    return verify(attempt, this._password);
  }
}

2. Readonly for Read-Only Access

class Config {
  readonly apiUrl: string;
  readonly timeout: number;

  constructor(apiUrl: string, timeout: number) {
    this.apiUrl = apiUrl;
    this.timeout = timeout;
  }
}

3. Return Copies, Not References

class Order {
  private _items: OrderItem[] = [];

  // ❌ BAD: Returns reference
  getItems(): OrderItem[] {
    return this._items;  // Caller can modify!
  }

  // ✅ GOOD: Returns copy
  getItems(): OrderItem[] {
    return [...this._items];
  }

  // ✅ ALSO GOOD: Return readonly
  getItems(): ReadonlyArray<OrderItem> {
    return this._items;
  }
}

4. Validate in Setters

class Product {
  private _price: number = 0;

  get price(): number {
    return this._price;
  }

  set price(value: number) {
    if (value < 0) throw new Error('Price cannot be negative');
    if (value > 1000000) throw new Error('Price too high');
    this._price = value;
  }
}

Pressure Resistance Protocol

1. "It's Simpler"

Pressure: "Public fields are less code"

Response: Less code now, more bugs later. Encapsulation prevents invalid states.

Action: Private fields + methods. The extra code is validation.

2. "We Trust Callers"

Pressure: "Our team won't misuse public fields"

Response: Teams grow. Code evolves. Mistakes happen. Protect invariants in code.

Action: Don't rely on caller discipline. Enforce in class.

3. "It's Just Data"

Pressure: "This class is just a data container"

Response: Even data has rules. Emails have formats. Ages have ranges.

Action: Use DTOs/interfaces for pure data. Classes = behavior + encapsulation.

4. "Getters/Setters Are Verbose"

Pressure: "Java-style getters/setters are boilerplate"

Response: TypeScript has concise get/set syntax. Use it.

Action: get balance() is not verbose.

Red Flags - STOP and Reconsider

• public keyword on mutable fields
• Direct property assignment from outside
• Arrays/objects returned by reference
• No validation on state changes
• Invariants only documented, not enforced

All of these mean: Encapsulate the state.

Quick Reference

Common Rationalizations (All Invalid)

The Bottom Line

Private state. Public methods. Validate on every change.

Never expose internal state directly. Return copies of collections. Validate in setters. Encapsulation protects invariants and enables safe evolution.