Beginner

// Anemic model - just data, no behavior
class BankAccount {
  constructor(
    // => Constructor: initializes object with provided parameters
    public accountNumber: string, // => Public fields break encapsulation
    public balance: number, // => Can be modified without validation
    public isActive: boolean,
  ) {}
}
 
// Business logic in separate service
class BankingService {
  withdraw(account: BankAccount, amount: number): void {
    if (!account.isActive) {
      // => Business rule in service (not domain object)
      throw new Error("Account inactive");
      // => Raise domain exception
    }
    // => Validates business rule
 
    if (account.balance < amount) {
      throw new Error("Insufficient funds");
      // => Raise domain exception
    }
    // => Enforces invariant
 
    account.balance -= amount; // => Direct mutation, no protection or events
  }
}
 
// Usage
const account = new BankAccount("123", 1000, true);
// => account: {accountNumber: "123", balance: 1000, isActive: true}
const service = new BankingService();
// => Creates BankingService instance for use in the example
service.withdraw(account, 500); // => account.balance becomes 500
console.log(account.balance); // => Output: 500

// Rich domain model - data + behavior + business rules
class BankAccount {
  constructor(accountNumber: string, initialBalance: number) {
    // => Initialize object with parameters
    this.accountNumber = accountNumber;
    // => Update accountNumber state
    this.balance = initialBalance;
    // => Update balance state
    this.isActive = true;
    // => New accounts active by default
    // => Business rule: accounts start active
  }
 
  withdraw(amount: number): void {
    this.ensureIsActive();
    // => Business rule #1: must be active to withdraw
    this.ensureSufficientFunds(amount);
    // => Business rule #2: sufficient funds required
    this.balance -= amount;
    // => balance reduced by amount (balance decremented)
  }
  // => Validates business rule
 
  private ensureIsActive(): void {
    // => Helper: ensureIsActive()
    if (!this.isActive) {
      throw new Error("Cannot withdraw from inactive account");
      // => Raise domain exception
    }
    // => Enforces invariant
  }
 
  private ensureSufficientFunds(amount: number): void {
    // => Helper: ensureSufficientFunds()
    if (this.balance < amount) {
      throw new Error(`Insufficient funds. Balance: ${this.balance}, Requested: ${amount}`);
      // => Raise domain exception
    }
  }
 
  getBalance(): number {
    // => Read-only access to balance
    // => No setBalance() method exists
    return this.balance;
    // => Return result to caller
  }
}
 
// Usage
const account = new BankAccount("123", 1000);
// => balance=1000, isActive=true
account.withdraw(500);
// => ensureSufficientFunds(500) validates balance >= 500
// => balance becomes 500
console.log(account.getBalance());
// => Output: 500

// Domain: Healthcare appointment scheduling
// Ubiquitous Language terms: Patient, Practitioner, Appointment, TimeSlot
 
// ❌ WRONG: Using technical terms instead of domain language
class Person1 {
  // => Person1: domain class definition
  // => Encapsulates data and domain behavior together
 
  constructor(public id: string) {}
  // => Initialize object with parameters
  // => All fields initialized: object in valid initial state
}
// => End of Person1 class
 
class Person2 {
  // => Person2: domain class definition
  // => Encapsulates data and domain behavior together
 
  constructor(public id: string) {}
  // => Initialize object with parameters
  // => All fields initialized: object in valid initial state
}
// => End of Person2 class
 
class Event {
  // => Event: domain class definition
  // => Encapsulates data and domain behavior together
 
  constructor(
    // => Constructor: initializes object state
    // => All fields initialized: object in valid initial state
 
    public person1Id: string, // => Who is person1?
    public person2Id: string, // => Who is person2?
    public startTime: Date,
    // => startTime: public Date field
 
    public endTime: Date,
    // => endTime: public Date field
  ) {}
  // => Constructor body empty: no additional initialization needed
}
// => End of Event class
 
// ✅ CORRECT: Using domain language directly
class Patient {
  // => Patient: domain class definition
  // => Encapsulates data and domain behavior together
 
  constructor(
    // => Constructor: initializes object state
    // => All fields initialized: object in valid initial state
 
    private readonly patientId: string, // => Domain-specific identifier
    private readonly name: string,
    // => Encapsulated state, not directly accessible
    // => Human-readable identifier for ubiquitous language
 
    private readonly dateOfBirth: Date,
    // => Encapsulated state, not directly accessible
    // => Temporal: records when event occurred
  ) {}
  // => Constructor body empty: no additional initialization needed
 
  getPatientId(): string {
    // => getPatientId: returns string
    // => Domain operation: enforces business rules
 
    return this.patientId; // => Returns patient ID
  }
  // => End of getPatientId()
}
// => End of Patient class
 
class Practitioner {
  // => Practitioner: domain class definition
  // => Encapsulates data and domain behavior together
 
  constructor(
    // => Constructor: initializes object state
    // => All fields initialized: object in valid initial state
 
    private readonly practitionerId: string, // => Domain-specific identifier
    private readonly name: string,
    // => name: private readonly string field
 
    private readonly specialty: string, // => Domain term: specialty, not "skill"
  ) {}
  // => Constructor body empty: no additional initialization needed
 
  getPractitionerId(): string {
    // => getPractitionerId: returns string
    // => Domain operation: enforces business rules
 
    return this.practitionerId; // => Returns practitioner ID
  }
  // => End of getPractitionerId()
}
// => End of Practitioner class
 
class TimeSlot {
  // => TimeSlot: domain class definition
  // => Encapsulates data and domain behavior together
 
  constructor(
    // => Constructor: initializes object state
    // => All fields initialized: object in valid initial state
 
    private readonly startTime: Date, // => Slot start time
    private readonly endTime: Date, // => Slot end time
  ) {}
  // => Constructor body empty: no additional initialization needed
 
  getDurationMinutes(): number {
    // => getDurationMinutes: returns number
    // => Domain operation: enforces business rules
 
    const diff = this.endTime.getTime() - this.startTime.getTime(); // => Calculate difference
    return diff / (1000 * 60); // => Convert milliseconds to minutes
  }
  // => End of getDurationMinutes()
}
// => End of TimeSlot class
 
class Appointment {
  // => Appointment: domain class definition
  // => Encapsulates data and domain behavior together
 
  constructor(
    // => Constructor: initializes object state
    // => All fields initialized: object in valid initial state
 
    private readonly appointmentId: string, // => Unique appointment identifier
    private readonly patient: Patient, // => Who is being seen
    private readonly practitioner: Practitioner, // => Who is providing care
    private readonly timeSlot: TimeSlot, // => When the appointment occurs
    private status: AppointmentStatus, // => Current state: scheduled, completed, cancelled
  ) {}
  // => Constructor body empty: no additional initialization needed
 
  cancel(): void {
    // => cancel: returns void
    // => Domain operation: enforces business rules
 
    if (this.status === AppointmentStatus.Completed) {
      // => Checks: this.status === AppointmentStatus.Completed
      // => State validation: ensures preconditions met
 
      throw new Error("Cannot cancel completed appointment");
      // => Raise domain exception
    }
    this.status = AppointmentStatus.Cancelled; // => Update to cancelled
    // => Appointment cancelled
  }
  // => End of cancel()
}
// => End of Appointment class
 
enum AppointmentStatus {
  // => Domain vocabulary for appointment states
  Scheduled = "SCHEDULED", // => Appointment is booked
  Completed = "COMPLETED", // => Visit finished
  Cancelled = "CANCELLED", // => Appointment cancelled
}
 
// Usage with domain language
const patient = new Patient("P123", "John Doe", new Date("1980-05-15")); // => Create patient
const doctor = new Practitioner("D456", "Dr. Smith", "Cardiology"); // => Create practitioner
const slot = new TimeSlot(new Date("2026-02-01T10:00"), new Date("2026-02-01T10:30")); // => 30-minute slot
const appointment = new Appointment("A789", patient, doctor, slot, AppointmentStatus.Scheduled); // => Schedule appointment
appointment.cancel(); // => status becomes Cancelled

// Domain: E-commerce orders
class Order {
  // => Entity: defined by identity
  // => Rich domain model: combines data + business behavior
  // => OOP: bundles data with behavior
 
  private readonly orderId: string; // => Unique identifier (never changes)
  private customerId: string; // => Can change (customer reassignment)
  private items: OrderItem[]; // => Can change (add/remove items)
  private status: OrderStatus; // => Can change (order lifecycle)
 
  constructor(orderId: string, customerId: string) {
    // => Constructor: initializes object state
    // => All fields initialized: object in valid initial state
    // => DDD pattern: aggregate root creation
 
    this.orderId = orderId; // => Set immutable ID
    this.customerId = customerId; // => Set initial customer
    this.items = []; // => Start with empty items
    this.status = OrderStatus.Draft; // => New orders start as draft
    // => Order created: id=orderId, customer=customerId, items=[], status=Draft
  }
  // => End of constructor body
  // => Domain logic applied here
 
  addItem(productId: string, quantity: number, price: number): void {
    // => addItem: returns void
    // => Domain operation: enforces business rules
 
    const item = new OrderItem(productId, quantity, price); // => Create new item
    this.items.push(item); // => Add to items array
    // => Item added: items.length increased by 1
  }
  // => End of addItem()
  // => Domain logic applied here
 
  submit(): void {
    // => submit: returns void
    // => Domain operation: enforces business rules
 
    if (this.items.length === 0) {
      // => Validate has items
      // => Domain rule: precondition before operation
      // => Instance-level state change
 
      throw new Error("Cannot submit empty order");
      // => Throws domain error: "Cannot submit empty order"
      // => Domain invariant violated: operation rejected
      // => Caller must handle this exception case
    }
    this.status = OrderStatus.Submitted; // => Change status to submitted
    // => Order submitted
  }
  // => End of submit()
 
  equals(other: Order): boolean {
    // => equals: returns boolean
    // => Domain operation: enforces business rules
 
    return this.orderId === other.orderId; // => Identity comparison (not attribute comparison)
  }
  // => End of equals()
 
  getOrderId(): string {
    // => getOrderId: returns string
    // => Domain operation: enforces business rules
 
    return this.orderId; // => Read-only access to ID
  }
  // => End of getOrderId()
}
// => End of Order class
 
class OrderItem {
  // => OrderItem: domain class definition
  // => Encapsulates data and domain behavior together
 
  constructor(
    // => Constructor: initializes object state
    // => All fields initialized: object in valid initial state
 
    public readonly productId: string, // => Product being ordered
    public readonly quantity: number, // => How many
    public readonly price: number, // => Price per unit
  ) {}
  // => Constructor body empty: no additional initialization needed
}
// => End of OrderItem class
 
enum OrderStatus {
  // => OrderStatus: enumeration of domain values
 
  Draft = "DRAFT", // => Order being built
  Submitted = "SUBMITTED", // => Order placed
  Shipped = "SHIPPED", // => Order sent to customer
  Delivered = "DELIVERED", // => Order received by customer
}
// => End of Order class definition
 
// Usage demonstrating identity
const order1 = new Order("ORD-001", "CUST-123"); // => order1: id=ORD-001
order1.addItem("PROD-A", 2, 50.0); // => order1: items=[{PROD-A, qty=2, price=50}]
 
const order2 = new Order("ORD-001", "CUST-456"); // => order2: id=ORD-001 (same ID)
// => order1.equals(order2) returns TRUE even though customers differ
// => Identity (orderId) defines equality, not attributes
 
const order3 = new Order("ORD-002", "CUST-123"); // => order3: id=ORD-002 (different ID)
// => order1.equals(order3) returns FALSE even though customer same
// => Different identity = different entity

// Domain: Order processing with state transitions
class Order {
  // => Order: domain class definition
  // => Encapsulates data and domain behavior together
  // => OOP: bundles data with behavior
 
  private readonly orderId: string; // => Immutable identity
  private status: OrderStatus; // => Current lifecycle state
 
  constructor(orderId: string) {
    // => Constructor: initializes object state
    // => All fields initialized: object in valid initial state
    // => DDD pattern: aggregate root creation
 
    this.orderId = orderId; // => Set ID
    this.status = OrderStatus.Draft; // => Initial state: Draft
    // => Order created in Draft state
  }
  // => End of constructor body
  // => Domain logic applied here
 
  submit(): void {
    // => submit: returns void
    // => Domain operation: enforces business rules
 
    this.ensureCanTransitionTo(OrderStatus.Submitted); // => Validate transition allowed
    this.status = OrderStatus.Submitted; // => Transition to Submitted
    // => Status: Draft → Submitted
  }
  // => End of submit()
  // => Domain logic applied here
 
  ship(): void {
    // => ship: returns void
    // => Domain operation: enforces business rules
 
    this.ensureCanTransitionTo(OrderStatus.Shipped); // => Validate transition allowed
    this.status = OrderStatus.Shipped; // => Transition to Shipped
    // => Status: Submitted → Shipped
  }
  // => End of ship()
  // => Domain logic applied here
 
  deliver(): void {
    // => deliver: returns void
    // => Domain operation: enforces business rules
 
    this.ensureCanTransitionTo(OrderStatus.Delivered); // => Validate transition allowed
    this.status = OrderStatus.Delivered; // => Transition to Delivered
    // => Status: Shipped → Delivered
  }
  // => End of deliver()
  // => Domain logic applied here
 
  cancel(): void {
    // => cancel: returns void
    // => Domain operation: enforces business rules
 
    this.ensureCanTransitionTo(OrderStatus.Cancelled); // => Validate transition allowed
    this.status = OrderStatus.Cancelled; // => Transition to Cancelled
    // => Status: [any state] → Cancelled
  }
  // => End of cancel()
  // => Domain logic applied here
 
  private ensureCanTransitionTo(newStatus: OrderStatus): void {
    // => Internal logic (not part of public API)
    // => Encapsulated: accessed only through domain methods
    // => Not directly accessible to clients
 
    const allowedTransitions = this.getAllowedTransitions(); // => Get valid next states
 
    if (!allowedTransitions.includes(newStatus)) {
      // => Check if transition valid
      // => Domain rule: precondition before operation
 
      throw new Error(
        // => Throws domain exception
        // => Domain invariant violated: operation rejected
        // => Caller must handle this exception case
 
        `Invalid transition from ${this.status} to ${newStatus}. ` + `Allowed: ${allowedTransitions.join(", ")}`,
        // => Delegates to internal method
        // => Modifies this aggregate instance
      );
    }
    // => Transition validated
    // => Domain logic applied here
  }
  // => End of constructor body
  // => Domain logic applied here
 
  private getAllowedTransitions(): OrderStatus[] {
    // => Internal logic (not part of public API)
    // => Collection: add/remove through domain methods only
 
    const transitions: Record<OrderStatus, OrderStatus[]> = {
      // => transitions = {
 
      [OrderStatus.Draft]: [OrderStatus.Submitted, OrderStatus.Cancelled], // => Draft can go to Submitted or Cancelled
      [OrderStatus.Submitted]: [OrderStatus.Shipped, OrderStatus.Cancelled], // => Submitted can go to Shipped or Cancelled
      [OrderStatus.Shipped]: [OrderStatus.Delivered, OrderStatus.Cancelled], // => Shipped can go to Delivered or Cancelled
      [OrderStatus.Delivered]: [], // => Delivered is terminal (no transitions)
      [OrderStatus.Cancelled]: [], // => Cancelled is terminal (no transitions)
    };
 
    return transitions[this.status]; // => Return allowed transitions for current state
  }
 
  getStatus(): OrderStatus {
    // => getStatus: returns OrderStatus
    // => Domain operation: enforces business rules
 
    return this.status; // => Read current status
  }
  // => End of getStatus()
}
// => End of Order class
 
enum OrderStatus {
  // => OrderStatus: enumeration of domain values
 
  Draft = "DRAFT",
  // => Draft = "DRAFT",
 
  Submitted = "SUBMITTED",
  // => Submitted = "SUBMITTED",
 
  Shipped = "SHIPPED",
  // => Shipped = "SHIPPED",
 
  Delivered = "DELIVERED",
  // => Delivered = "DELIVERED",
 
  Cancelled = "CANCELLED",
  // => Cancelled = "CANCELLED",
}
 
// Usage showing valid and invalid transitions
const order = new Order("ORD-001"); // => order: status=Draft
console.log(order.getStatus()); // => Output: DRAFT
 
order.submit(); // => status: Draft → Submitted (valid)
console.log(order.getStatus()); // => Output: SUBMITTED
 
order.ship(); // => status: Submitted → Shipped (valid)
console.log(order.getStatus()); // => Output: SHIPPED
 
// order.submit();                           // => Would throw error: cannot Submitted from Shipped
order.deliver(); // => status: Shipped → Delivered (valid)
console.log(order.getStatus()); // => Output: DELIVERED
 
// order.ship();                             // => Would throw error: Delivered is terminal state

// Domain: Banking - Account with overdraft protection
public class BankAccount {
// => class: public unknown field
// => Rich domain model: combines data + business behavior
// => OOP: bundles data with behavior
 
 
 
    private final String accountId;          // => Immutable identity
    private Money balance;                   // => Current balance (changes over time)
    private final Money overdraftLimit;      // => Maximum allowed negative balance
    private boolean isFrozen;                // => Account status flag
 
    public BankAccount(String accountId, Money initialBalance, Money overdraftLimit) {
    // => BankAccount: public unknown field
    // => Aggregate state managed
 
 
        if (overdraftLimit.isNegative()) {   // => Validate: overdraft limit cannot be negative
            throw new IllegalArgumentException("Overdraft limit must be non-negative");
              // => Raise domain exception
              // => Invariant enforcement: invalid state rejected
              // => Caller must handle this exception case
 
 
        }
 
        this.accountId = accountId;          // => Set immutable ID
        this.balance = initialBalance;       // => Set initial balance
        this.overdraftLimit = overdraftLimit;  // => Set overdraft protection
        this.isFrozen = false;               // => Account starts active (not frozen)
 
        this.ensureInvariants();             // => Validate invariants on creation
        // => Account created with valid state
    }
 
    public void deposit(Money amount) {
    // => void: public unknown field
    // => Domain logic applied here
 
 
        if (amount.isNegativeOrZero()) {     // => Validate: deposit must be positive
            throw new IllegalArgumentException("Deposit amount must be positive");
              // => Raise domain exception
              // => Invariant enforcement: invalid state rejected
              // => Caller must handle this exception case
 
 
        }
 
        this.ensureNotFrozen();              // => Validate: account not frozen
        this.balance = this.balance.add(amount);  // => Add to balance
        this.ensureInvariants();             // => Validate invariants after change
        // => balance increased by amount
    }
 
    public void withdraw(Money amount) {
    // => void: public unknown field
    // => Business rule enforced
 
 
        if (amount.isNegativeOrZero()) {     // => Validate: withdrawal must be positive
            throw new IllegalArgumentException("Withdrawal amount must be positive");
              // => Raise domain exception
              // => Invariant enforcement: invalid state rejected
              // => Caller must handle this exception case
 
 
        }
 
        this.ensureNotFrozen();              // => Validate: account not frozen
        this.ensureSufficientFundsWithOverdraft(amount);  // => Validate: within overdraft limit
 
        this.balance = this.balance.subtract(amount);     // => Deduct from balance
        this.ensureInvariants();             // => Validate invariants after change
        // => balance decreased by amount
    }
 
    public void freeze() {
    // => void: public unknown field
    // => Part of domain model implementation
 
 
        this.isFrozen = true;                // => Set frozen flag
        // => Account frozen (no deposits/withdrawals allowed)
    }
 
    private void ensureNotFrozen() {
    // => void: private unknown field
    // => Identity: encapsulated, exposed only via getter
    // => Not directly accessible to clients
 
 
 
        if (this.isFrozen) {                 // => Check frozen status
            throw new IllegalStateException("Cannot perform operations on frozen account");
              // => Raise domain exception
              // => Invariant enforcement: invalid state rejected
              // => Caller must handle this exception case
 
 
        }
        // => Validation passed: account is active
        // => Domain logic applied here
 
    }
 
    private void ensureSufficientFundsWithOverdraft(Money amount) {
    // => void: private unknown field
    // => Identity: encapsulated, exposed only via getter
    // => Not directly accessible to clients
 
 
 
        Money minimumAllowed = this.overdraftLimit.negate();  // => Calculate minimum balance (negative overdraft)
        Money balanceAfterWithdrawal = this.balance.subtract(amount);  // => Calculate new balance
 
        if (balanceAfterWithdrawal.isLessThan(minimumAllowed)) {  // => Check if below overdraft limit
            throw new IllegalStateException(
              // => Raise domain exception
              // => Invariant enforcement: invalid state rejected
              // => Caller must handle this exception case
 
 
                String.format("Insufficient funds. Balance: %s, Withdrawal: %s, Overdraft limit: %s",
                // => Calls String.format()
                // => Business rule enforced
 
 
                    this.balance, amount, this.overdraftLimit)
            );
        }
        // => Validation passed: withdrawal within limits
        // => Domain logic applied here
 
    }
 
    private void ensureInvariants() {
      // => Encapsulated state, not directly accessible
      // => Identity: encapsulated, exposed only via getter
      // => Not directly accessible to clients
 
 
        // Invariant 1: Balance + overdraft limit >= 0
        Money minimumAllowed = this.overdraftLimit.negate();  // => Calculate minimum allowed balance
        if (this.balance.isLessThan(minimumAllowed)) {        // => Check invariant
            throw new IllegalStateException("Invariant violation: balance below overdraft limit");
              // => Raise domain exception
              // => Invariant enforcement: invalid state rejected
              // => Caller must handle this exception case
 
 
        }
 
        // Invariant 2: Overdraft limit is non-negative
        if (this.overdraftLimit.isNegative()) {               // => Check invariant
            throw new IllegalStateException("Invariant violation: overdraft limit cannot be negative");
              // => Raise domain exception
              // => Invariant enforcement: invalid state rejected
              // => Caller must handle this exception case
 
 
        }
 
        // => All invariants satisfied
    }
 
    public Money getBalance() {
    // => Money: public unknown field
    // => Part of domain model implementation
 
 
        return this.balance;                 // => Return current balance
    }
}
 
// Money: value object handling currency amounts and validation
public class Money {
// => class: public unknown field
// => Rich domain model: combines data + business behavior
// => OOP: bundles data with behavior
 
 
 
    private final BigDecimal amount;
      // => Encapsulated state, not directly accessible
      // => Encapsulated: accessed only through domain methods
      // => Not directly accessible to clients
 
 
    private final String currency;
      // => Encapsulated state, not directly accessible
      // => Encapsulated: accessed only through domain methods
      // => Not directly accessible to clients
 
 
 
    public Money(BigDecimal amount, String currency) {
    // => Money: public unknown field
 
        this.amount = amount;
          // => Update amount state
          // => Mutates aggregate state
 
        this.currency = currency;
          // => Update currency state
          // => Mutates aggregate state
 
    }
 
    public Money add(Money other) {
    // => Money: public unknown field
 
        this.ensureSameCurrency(other);
        // => Delegates to internal method
        return new Money(this.amount.add(other.amount), this.currency);
          // => Return result to caller
          // => Returns computed domain value
 
    }
 
    public Money subtract(Money other) {
    // => Money: public unknown field
 
        this.ensureSameCurrency(other);
        // => Delegates to internal method
        return new Money(this.amount.subtract(other.amount), this.currency);
          // => Return result to caller
          // => Returns computed domain value
 
    }
 
    public Money negate() {
    // => Money: public unknown field
 
        return new Money(this.amount.negate(), this.currency);
          // => Return result to caller
          // => Returns computed domain value
 
    }
 
    public boolean isNegative() {
    // => boolean: public unknown field
 
        return this.amount.compareTo(BigDecimal.ZERO) < 0;
          // => Return result to caller
          // => Returns computed domain value
 
    }
 
    public boolean isNegativeOrZero() {
    // => boolean: public unknown field
 
        return this.amount.compareTo(BigDecimal.ZERO) <= 0;
          // => Return result to caller
          // => Returns computed domain value
 
    }
 
    public boolean isLessThan(Money other) {
    // => boolean: public unknown field
 
        this.ensureSameCurrency(other);
        // => Delegates to internal method
        return this.amount.compareTo(other.amount) < 0;
          // => Return result to caller
          // => Returns computed domain value
 
    }
 
    private void ensureSameCurrency(Money other) {
      // => Encapsulated state, not directly accessible
      // => Identity: encapsulated, exposed only via getter
 
        if (!this.currency.equals(other.currency)) {
          // => Conditional check
          // => Domain rule: precondition before operation
 
            throw new IllegalArgumentException("Cannot operate on different currencies");
              // => Raise domain exception
              // => Invariant enforcement: invalid state rejected
              // => Caller must handle this exception case
 
 
        }
    }
}
 
// Usage
Money initialBalance = new Money(new BigDecimal("1000.00"), "USD");     // => Create initial balance
Money overdraftLimit = new Money(new BigDecimal("500.00"), "USD");      // => Allow $500 overdraft
BankAccount account = new BankAccount("ACC-001", initialBalance, overdraftLimit);  // => Create account
 
account.deposit(new Money(new BigDecimal("500.00"), "USD"));            // => balance: $1000 → $1500
account.withdraw(new Money(new BigDecimal("2000.00"), "USD"));          // => balance: $1500 → -$500 (within overdraft)
// account.withdraw(new Money(new BigDecimal("100.00"), "USD"));        // => Would throw: exceeds overdraft limit (-$600 < -$500)
 
account.freeze();                                                       // => Account frozen
// account.deposit(new Money(new BigDecimal("100.00"), "USD"));         // => Would throw: frozen account

// Domain: Customer management
class Customer {
  // => Entity with identity
  // => Rich domain model: combines data + business behavior
  // => OOP: bundles data with behavior
 
  private readonly customerId: string; // => Unique identifier
  private email: string; // => Customer email
  private name: string; // => Customer name
  private createdAt: Date; // => Registration timestamp
 
  constructor(customerId: string, email: string, name: string) {
    // => Constructor: initializes object state
    // => All fields initialized: object in valid initial state
    // => DDD pattern: aggregate root creation
 
    this.customerId = customerId; // => Set ID
    this.email = email; // => Set email
    this.name = name; // => Set name
    this.createdAt = new Date(); // => Record creation time
    // => Customer created
  }
  // => End of constructor body
  // => Domain logic applied here
 
  changeEmail(newEmail: string): void {
    // => changeEmail: returns void
    // => Domain operation: enforces business rules
 
    if (!this.isValidEmail(newEmail)) {
      // => Validate email format
      // => Domain rule: precondition before operation
      // => Instance-level state change
 
      throw new Error("Invalid email format");
      // => Raise domain exception
      // => Invariant enforcement: invalid state rejected
      // => Caller must handle this exception case
    }
    this.email = newEmail; // => Update email
    // => Email changed
  }
  // => End of changeEmail()
  // => Domain logic applied here
 
  private isValidEmail(email: string): boolean {
    // => Internal logic (not part of public API)
    // => Identity: encapsulated, exposed only via getter
    // => Not directly accessible to clients
 
    return email.includes("@"); // => Simple validation (real impl would use regex)
  }
  // => End of constructor body
  // => Domain logic applied here
 
  getCustomerId(): string {
    // => getCustomerId: returns string
    // => Domain operation: enforces business rules
 
    return this.customerId;
    // => Return result to caller
    // => Returns computed domain value
    // => Instance-level state change
  }
  // => End of getCustomerId()
  // => Domain logic applied here
 
  getEmail(): string {
    // => getEmail: returns string
    // => Domain operation: enforces business rules
 
    return this.email;
    // => Return result to caller
    // => Returns computed domain value
    // => Instance-level state change
  }
  // => End of getEmail()
  // => Domain logic applied here
}
// => End of Customer class
// => Domain logic applied here
 
// Repository interface (domain layer - no database details)
interface CustomerRepository {
  // => CustomerRepository: contract/interface definition
  // => Dependency inversion: domain does not depend on infrastructure
 
  save(customer: Customer): Promise<void>; // => Persist customer
  findById(customerId: string): Promise<Customer | null>; // => Retrieve by ID
  findByEmail(email: string): Promise<Customer | null>; // => Retrieve by email
  delete(customerId: string): Promise<void>; // => Remove customer
}
// => End of CustomerRepository interface
 
// Repository implementation (infrastructure layer - database details)
class PostgresCustomerRepository implements CustomerRepository {
  // => PostgresCustomerRepository: implements CustomerRepository interface
  // => Rich domain model: combines data + business behavior
 
  constructor(private db: DatabaseConnection) {} // => Injects any DatabaseConnection (pg, mysql2, etc.)
  // => DatabaseConnection: any database driver implementing execute() and queryOne()
  // => All fields initialized: object in valid initial state
 
  async save(customer: Customer): Promise<void> {
    // => save(): async returns Promise<void>
 
    const query = `
      // => Store value in query
      INSERT INTO customers (customer_id, email, name, created_at)
      VALUES ($1, $2, $3, $4)
      ON CONFLICT (customer_id) DO UPDATE
      SET email = $2, name = $3
    `;
    // => Upsert query (insert or update if exists)
 
    await this.db.execute(query, [
      // => Awaits async operation
 
      customer.getCustomerId(),
      // => Execute method
      customer.getEmail(),
      // => Execute method
      customer.getName(),
      // => Execute method
      customer.getCreatedAt(),
      // => Execute method
    ]);
    // => Customer saved to database
  }
  // => End of save()
 
  async findById(customerId: string): Promise<Customer | null> {
    // => findById(): async returns Promise<Customer | null>
 
    const query = `SELECT * FROM customers WHERE customer_id = $1`; // => SQL query
    const row = await this.db.queryOne(query, [customerId]); // => Execute query
 
    if (!row) {
      // => Checks: !row
      // => Domain rule: precondition before operation
 
      return null; // => Customer not found
    }
 
    return this.mapRowToCustomer(row); // => Convert database row to domain entity
  }
  // => End of findById()
 
  async findByEmail(email: string): Promise<Customer | null> {
    // => findByEmail(): async returns Promise<Customer | null>
 
    const query = `SELECT * FROM customers WHERE email = $1`; // => SQL query
    const row = await this.db.queryOne(query, [email]); // => Execute query
 
    if (!row) {
      // => Checks: !row
      // => Domain rule: precondition before operation
 
      return null; // => Customer not found
    }
 
    return this.mapRowToCustomer(row); // => Convert to domain entity
  }
  // => End of findByEmail()
 
  async delete(customerId: string): Promise<void> {
    // => delete(): async returns Promise<void>
 
    const query = `DELETE FROM customers WHERE customer_id = $1`; // => SQL delete
    await this.db.execute(query, [customerId]); // => Execute deletion
    // => Customer deleted from database
  }
  // => End of delete()
 
  private mapRowToCustomer(row: any): Customer {
    // => Internal logic (not part of public API)
    // => Encapsulated: accessed only through domain methods
 
    return new Customer(
      // => Returns new Customer(
      // => Creates and returns new instance
 
      row.customer_id, // => Reconstruct entity from database row
      row.email,
      row.name,
    );
  }
}
// => End of PostgresCustomerRepository class
 
// Usage (domain service using repository)
class CustomerService {
  // => CustomerService: domain class definition
  // => Encapsulates data and domain behavior together
 
  constructor(private customerRepo: CustomerRepository) {} // => Inject repository
 
  async changeCustomerEmail(customerId: string, newEmail: string): Promise<void> {
    // => changeCustomerEmail(): async returns Promise<void>
 
    const customer = await this.customerRepo.findById(customerId); // => Load entity
 
    if (!customer) {
      // => Checks: !customer
      // => Domain rule: precondition before operation
 
      throw new Error("Customer not found");
      // => Raise domain exception
      // => Invariant enforcement: invalid state rejected
      // => Caller must handle this exception case
    }
 
    customer.changeEmail(newEmail); // => Domain logic (validates email)
    await this.customerRepo.save(customer); // => Persist changes
    // => Email changed and saved
  }
  // => End of changeCustomerEmail()
}
// => End of CustomerService class
 
// Usage example
const db = new DatabaseConnection(); // => Database connection
const customerRepo = new PostgresCustomerRepository(db); // => Create repository
const customerService = new CustomerService(customerRepo); // => Create service
 
// Change email for customer
await customerService.changeCustomerEmail("CUST-123", "newemail@example.com");
// => Loads customer, validates email, saves changes

// Domain: E-commerce product creation
public class Product {
// => class: public unknown field
// => Rich domain model: combines data + business behavior
// => OOP: bundles data with behavior
 
 
 
    private final String productId;          // => Unique identifier
    private final String name;               // => Product name
    private final Money price;               // => Product price
    private final ProductCategory category;  // => Product category
    private final List<String> tags;         // => Search tags
    private ProductStatus status;            // => Current status
 
    // Private constructor - only factory can create
    private Product(
      // => Encapsulated state, not directly accessible
      // => Encapsulated: accessed only through domain methods
      // => Not directly accessible to clients
 
 
        String productId,
        String name,
        Money price,
        ProductCategory category,
        List<String> tags
    ) {
        this.productId = productId;          // => Set ID
        this.name = name;                    // => Set name
        this.price = price;                  // => Set price
        this.category = category;            // => Set category
        this.tags = new ArrayList<>(tags);   // => Copy tags (defensive copy)
        this.status = ProductStatus.DRAFT;   // => New products start as draft
        // => Product created in valid initial state
    }
 
    public void publish() {
    // => void: public unknown field
    // => Part of domain model implementation
    // => Domain model component
 
 
 
        if (this.status != ProductStatus.DRAFT) {
        // => Checks: this.status != ProductStatus.DRAFT
        // => State validation: ensures preconditions met
        // => Instance-level state change
 
 
 
            throw new IllegalStateException("Can only publish draft products");
              // => Raise domain exception
              // => Invariant enforcement: invalid state rejected
              // => Caller must handle this exception case
 
 
        }
        this.status = ProductStatus.PUBLISHED;  // => Change status to published
        // => Product published
    }
 
    // Factory for creating products
    public static class Factory {
    // => static: public unknown field
    // => Rich domain model: combines data + business behavior
    // => OOP: bundles data with behavior
 
 
 
        private final IdGenerator idGenerator;        // => ID generation service
        private final PricingService pricingService;  // => Pricing validation
 
        public Factory(IdGenerator idGenerator, PricingService pricingService) {
        // => Factory: public unknown field
        // => Domain logic applied here
        // => Business logic applied
 
 
 
            this.idGenerator = idGenerator;      // => Inject ID generator
            this.pricingService = pricingService;  // => Inject pricing service
            // => Factory initialized
        }
 
        public Product createProduct(
        // => Product: public unknown field
        // => Domain logic applied here
        // => DDD tactical pattern
 
 
 
            String name,
            BigDecimal basePrice,
            String currency,
            ProductCategory category,
            List<String> tags
        ) {
            // Step 1: Validate inputs
            this.validateName(name);             // => Ensure name is valid
            this.validateCategory(category);     // => Ensure category is valid
            this.validateTags(tags);             // => Ensure tags are valid
            // => All validations passed
 
            // Step 2: Generate ID
            String productId = this.idGenerator.generateProductId();  // => Create unique ID
            // => ID generated: productId
 
            // Step 3: Calculate price (may involve complex logic)
            Money price = this.pricingService.calculatePrice(
                basePrice,
                currency,
                category
            );
            // => Price calculated with category-specific rules
            // => Domain logic applied here
            // => Aggregate consistency enforced
 
 
 
            // Step 4: Normalize tags
            List<String> normalizedTags = tags.stream()
                .map(String::toLowerCase)        // => Convert to lowercase
                .map(String::trim)               // => Remove whitespace
                .distinct()                      // => Remove duplicates
                .collect(Collectors.toList());
            // => Tags normalized
            // => Business rule enforced
            // => Domain operation processed
 
 
 
            // Step 5: Create product
            Product product = new Product(
              // => Create Product instance
              // => Business rule enforced
              // => Entity lifecycle managed
 
 
                productId,
                name,
                price,
                category,
                normalizedTags
            );
            // => Product created with valid state
            // => Domain logic applied here
            // => Domain service delegation
 
 
 
            return product;                      // => Return fully initialized product
        }
 
        public Product createProductFromExisting(Product template, String newName) {
        // => Product: public unknown field
        // => Business rule enforced
        // => Repository interaction point
 
 
 
            // Clone existing product with new name
            String newProductId = this.idGenerator.generateProductId();  // => New ID
 
            return new Product(
            // => Returns new Product(
            // => Creates and returns new instance
            // => Value object creation
 
 
 
                newProductId,                    // => New ID (not same as template)
                newName,                         // => New name
                template.price,                  // => Copy price from template
                template.category,               // => Copy category from template
                new ArrayList<>(template.tags)   // => Copy tags from template
            );
            // => New product created based on template
            // => Domain logic applied here
            // => Domain event triggered
 
 
        }
 
        private void validateName(String name) {
          // => Encapsulated state, not directly accessible
          // => Identity: encapsulated, exposed only via getter
          // => Not directly accessible to clients
 
 
            if (name == null || name.trim().isEmpty()) {
              // => Conditional check
              // => True branch: early return when missing
              // => Domain model component
 
 
                throw new IllegalArgumentException("Product name cannot be empty");
                  // => Raise domain exception
                  // => Invariant enforcement: invalid state rejected
                  // => Caller must handle this exception case
 
 
            }
            if (name.length() > 200) {
              // => Conditional check
              // => Domain rule: precondition before operation
              // => Business logic applied
 
 
                throw new IllegalArgumentException("Product name too long (max 200 chars)");
                  // => Raise domain exception
                  // => Invariant enforcement: invalid state rejected
                  // => Caller must handle this exception case
 
 
            }
            // => Name validation passed
            // => Domain logic applied here
            // => DDD tactical pattern
 
 
        }
 
        private void validateCategory(ProductCategory category) {
          // => Encapsulated state, not directly accessible
          // => Identity: encapsulated, exposed only via getter
          // => Not directly accessible to clients
 
 
            if (category == null) {
            // => Checks: category == null
            // => True branch: early return when missing
            // => Aggregate consistency enforced
 
 
 
                throw new IllegalArgumentException("Product category is required");
                  // => Raise domain exception
                  // => Invariant enforcement: invalid state rejected
                  // => Caller must handle this exception case
 
 
            }
            // => Category validation passed
            // => Domain logic applied here
 
        }
 
        private void validateTags(List<String> tags) {
          // => Encapsulated state, not directly accessible
          // => Identity: encapsulated, exposed only via getter
          // => Not directly accessible to clients
 
 
            if (tags == null || tags.isEmpty()) {
              // => Conditional check
              // => True branch: early return when missing
 
                throw new IllegalArgumentException("At least one tag is required");
                  // => Raise domain exception
                  // => Invariant enforcement: invalid state rejected
                  // => Caller must handle this exception case
 
 
            }
            if (tags.size() > 10) {
              // => Conditional check
              // => Domain rule: precondition before operation
 
                throw new IllegalArgumentException("Too many tags (max 10)");
                  // => Raise domain exception
                  // => Invariant enforcement: invalid state rejected
                  // => Caller must handle this exception case
 
 
            }
            // => Tags validation passed
            // => Domain logic applied here
 
        }
    }
}
 
enum ProductCategory {
// => ProductCategory: enumeration of domain values
// => Closed set of domain states
 
 
    ELECTRONICS, CLOTHING, BOOKS, FOOD
}
 
enum ProductStatus {
// => ProductStatus: enumeration of domain values
// => Closed set of domain states
 
 
    DRAFT, PUBLISHED, DISCONTINUED
}
 
// Usage
IdGenerator idGen = new UUIDGenerator();     // => ID generation service
PricingService pricing = new TieredPricingService();  // => Pricing calculation service
Product.Factory productFactory = new Product.Factory(idGen, pricing);  // => Create factory
 
// Create new product
Product laptop = productFactory.createProduct(
    "Gaming Laptop X1",                      // => Product name
    new BigDecimal("1500.00"),               // => Base price
    "USD",                                   // => Currency
    ProductCategory.ELECTRONICS,             // => Category
    Arrays.asList("gaming", "laptop", "electronics", "computers")  // => Tags
);
// => Product created: id=generated, name="Gaming Laptop X1", status=DRAFT
// => Price calculated with electronics category markup
// => Tags normalized: ["gaming", "laptop", "electronics", "computers"]
 
laptop.publish();                            // => status: DRAFT → PUBLISHED
 
// Create product from template
Product similarLaptop = productFactory.createProductFromExisting(laptop, "Gaming Laptop X2");
// => New product with same price/category/tags but different ID and name
// => Part of domain model implementation
 

// Domain: Geographic location
class Address {
  // => Value Object: defined by attributes
  // => Rich domain model: combines data + business behavior
  // => OOP: bundles data with behavior
 
  private readonly street: string; // => Immutable field
  private readonly city: string; // => Immutable field
  private readonly postalCode: string; // => Immutable field
  private readonly country: string; // => Immutable field
 
  constructor(street: string, city: string, postalCode: string, country: string) {
    // => Constructor: initializes object state
    // => All fields initialized: object in valid initial state
 
    if (!street || !city || !postalCode || !country) {
      // => Validate all fields required
      // => Domain rule: precondition before operation
 
      throw new Error("All address fields are required");
      // => Throws domain error: "All address fields are required"
      // => Domain invariant violated: operation rejected
      // => Caller must handle this exception case
    }
 
    this.street = street; // => Set immutable street
    this.city = city; // => Set immutable city
    this.postalCode = postalCode; // => Set immutable postal code
    this.country = country; // => Set immutable country
    // => Address created (immutable)
  }
  // => End of constructor body
 
  equals(other: Address): boolean {
    // => equals: returns boolean
    // => Domain operation: enforces business rules
 
    return (
      // => Returns (
      // => Read-only access to internal state
 
      this.street === other.street && // => Compare all attributes
      this.city === other.city &&
      // => this.city = == other.city &&
      // => Mutates aggregate state
 
      this.postalCode === other.postalCode &&
      // => this.postalCode = == other.postalCode &&
      // => Mutates aggregate state
 
      this.country === other.country
      // => this.country = == other.country
      // => Mutates aggregate state
    );
  }
  // => End of equals()
 
  toString(): string {
    // => toString: returns string
    // => Domain operation: enforces business rules
 
    return `${this.street}, ${this.city} ${this.postalCode}, ${this.country}`;
    // => Returns `${this.street}, ${this.city} ${this.postalCode}, ${this.country}`
    // => Exposes encapsulated state (read-only access)
  }
  // => End of toString()
}
// => End of Address class
 
// Usage demonstrating value object characteristics
const addr1 = new Address("123 Main St", "New York", "10001", "USA"); // => Create address
const addr2 = new Address("123 Main St", "New York", "10001", "USA"); // => Create identical address
const addr3 = new Address("456 Elm St", "Boston", "02101", "USA"); // => Create different address
 
console.log(addr1.equals(addr2)); // => Output: true (same attributes = equal)
console.log(addr1 === addr2); // => Output: false (different object references)
console.log(addr1.equals(addr3)); // => Output: false (different attributes)
 
// addr1.city = "Boston";                    // => Compile error: readonly field cannot be changed
// => To "change" address, create new value object
const updatedAddr = new Address(
  // => updatedAddr = new Address(
 
  "123 Main St",
  // => String value: "123 Main St"
 
  "Boston", // => Changed city
  "10001",
  // => Postal code: "10001"
 
  "USA",
  // => Country/region code: "USA"
);
// => New address created (original addr1 unchanged)

// Domain: Financial transactions
public class Money {
// => class: public unknown field
// => Rich domain model: combines data + business behavior
// => OOP: bundles data with behavior
 
 
 
    private final BigDecimal amount;         // => Immutable amount (using BigDecimal for precision)
    private final Currency currency;         // => Immutable currency
 
    public Money(BigDecimal amount, Currency currency) {
    // => Money: public unknown field
    // => Part of domain model implementation
    // => Domain operation processed
 
 
 
        if (amount == null) {
        // => Checks: amount == null
        // => True branch: early return when missing
        // => Entity lifecycle managed
 
 
 
            throw new IllegalArgumentException("Amount cannot be null");
              // => Raise domain exception
              // => Invariant enforcement: invalid state rejected
              // => Caller must handle this exception case
 
 
        }
        if (currency == null) {
        // => Checks: currency == null
        // => True branch: early return when missing
        // => Domain service delegation
 
 
 
            throw new IllegalArgumentException("Currency cannot be null");
              // => Raise domain exception
              // => Invariant enforcement: invalid state rejected
              // => Caller must handle this exception case
 
 
        }
 
        this.amount = amount.setScale(currency.getDefaultFractionDigits(), RoundingMode.HALF_UP);  // => Round to currency precision
        this.currency = currency;            // => Set currency
        // => Money created: amount rounded to currency decimal places
    }
 
    public Money add(Money other) {
    // => Money: public unknown field
    // => Part of domain model implementation
    // => Repository interaction point
 
 
 
        this.ensureSameCurrency(other);      // => Validate: cannot add different currencies
        BigDecimal newAmount = this.amount.add(other.amount);  // => Add amounts
        return new Money(newAmount, this.currency);  // => Return new Money (immutable)
    }
 
    public Money subtract(Money other) {
    // => Money: public unknown field
    // => Business rule enforced
    // => Value object creation
 
 
 
        this.ensureSameCurrency(other);      // => Validate: cannot subtract different currencies
        BigDecimal newAmount = this.amount.subtract(other.amount);  // => Subtract amounts
        return new Money(newAmount, this.currency);  // => Return new Money (immutable)
    }
 
    public Money multiply(BigDecimal multiplier) {
    // => Money: public unknown field
    // => Business rule enforced
    // => Domain event triggered
 
 
 
        BigDecimal newAmount = this.amount.multiply(multiplier);  // => Multiply amount
        return new Money(newAmount, this.currency);  // => Return new Money (same currency)
    }
 
    public boolean isGreaterThan(Money other) {
    // => boolean: public unknown field
    // => Aggregate state managed
    // => Domain model component
 
 
 
        this.ensureSameCurrency(other);      // => Validate: cannot compare different currencies
        return this.amount.compareTo(other.amount) > 0;  // => Compare amounts
    }
 
    public boolean equals(Object obj) {
    // => boolean: public unknown field
    // => Domain logic applied here
    // => Business logic applied
 
 
 
        if (this == obj) return true;        // => Same reference = equal
        if (!(obj instanceof Money)) return false;  // => Different type = not equal
 
        Money other = (Money) obj;
        return this.amount.equals(other.amount) &&     // => Compare amount
               this.currency.equals(other.currency);   // => Compare currency
    }
 
    @Override
    public int hashCode() {
    // => int: public unknown field
    // => Domain logic applied here
    // => DDD tactical pattern
 
 
 
        return Objects.hash(amount, currency);  // => Hash based on amount and currency
        // => Enables using Money as HashMap key
    }
 
    private void ensureSameCurrency(Money other) {
    // => void: private unknown field
    // => Identity: encapsulated, exposed only via getter
    // => Not directly accessible to clients
 
 
 
        if (!this.currency.equals(other.currency)) {  // => Check currency match
            throw new IllegalArgumentException(
              // => Raise domain exception
              // => Invariant enforcement: invalid state rejected
              // => Caller must handle this exception case
 
 
                String.format("Cannot operate on different currencies: %s vs %s",
                // => Calls String.format()
                // => Business rule enforced
                // => Aggregate consistency enforced
 
 
 
                    this.currency.getCurrencyCode(),
                    // => Delegates to internal method
                    // => Modifies this aggregate instance
                    // => Domain operation processed
 
 
                    other.currency.getCurrencyCode())
                      // => Execute method
                      // => Aggregate state managed
 
            );
        }
        // => Validation passed: same currency
        // => Domain logic applied here
 
    }
 
    @Override
    public String toString() {
    // => String: public unknown field
    // => Part of domain model implementation
 
 
        return String.format("%s %s", this.currency.getCurrencyCode(), this.amount);
        // => Returns String.format("%s %s", this.currency.getCurrencyCode(), this.amount)
        // => Exposes encapsulated state (read-only access)
        // => Instance-level state change
 
 
 
    }
}
 
// Usage
Money price = new Money(new BigDecimal("99.99"), Currency.getInstance("USD"));     // => price: USD 99.99
Money tax = new Money(new BigDecimal("8.00"), Currency.getInstance("USD"));        // => tax: USD 8.00
Money total = price.add(tax);                                                      // => total: USD 107.99
System.out.println(total);                                                         // => Output: USD 107.99
 
Money discount = total.multiply(new BigDecimal("0.10"));                           // => 10% discount: USD 10.80 (rounded)
Money finalPrice = total.subtract(discount);                                       // => finalPrice: USD 97.19
System.out.println(finalPrice);                                                    // => Output: USD 97.19
 
// Money errorPrice = new Money(new BigDecimal("50.00"), Currency.getInstance("EUR"));  // => EUR 50.00
// total.add(errorPrice);                                                          // => Throws: cannot add USD and EUR

// Domain: Hotel booking system
class DateRange {
  // => Value Object representing time period
  // => Rich domain model: combines data + business behavior
 
  private readonly start: Date; // => Range start (inclusive)
  private readonly end: Date; // => Range end (inclusive)
 
  constructor(start: Date, end: Date) {
    // => Constructor: initializes object state
    // => All fields initialized: object in valid initial state
 
    if (start >= end) {
      // => Validate: start must be before end
      // => Domain rule: precondition before operation
 
      throw new Error("Start date must be before end date");
      // => Throws domain error: "Start date must be before end date"
      // => Domain invariant violated: operation rejected
      // => Caller must handle this exception case
    }
 
    this.start = new Date(start.getTime()); // => Defensive copy (prevent external mutation)
    this.end = new Date(end.getTime()); // => Defensive copy
    // => DateRange created: [start, end]
  }
  // => End of constructor body
 
  getDurationDays(): number {
    // => getDurationDays: returns number
    // => Domain operation: enforces business rules
 
    const diffMs = this.end.getTime() - this.start.getTime(); // => Calculate time difference in ms
    const diffDays = diffMs / (1000 * 60 * 60 * 24); // => Convert to days
    return Math.ceil(diffDays); // => Round up to full days
  }
  // => End of getDurationDays()
 
  overlaps(other: DateRange): boolean {
    // => overlaps: returns boolean
    // => Domain operation: enforces business rules
 
    return this.start <= other.end && this.end >= other.start; // => Check overlap condition
  }
  // => End of overlaps()
 
  contains(date: Date): boolean {
    // => contains: returns boolean
    // => Domain operation: enforces business rules
 
    return date >= this.start && date <= this.end; // => Check if date within range
  }
  // => End of contains()
 
  equals(other: DateRange): boolean {
    // => equals: returns boolean
    // => Domain operation: enforces business rules
 
    return (
      // => Returns (
      // => Read-only access to internal state
 
      this.start.getTime() === other.start.getTime() && // => Compare start dates
      this.end.getTime() === other.end.getTime()
    ); // => Compare end dates
  }
  // => End of equals()
 
  toString(): string {
    // => toString: returns string
    // => Domain operation: enforces business rules
 
    return `${this.start.toISOString()} to ${this.end.toISOString()}`;
    // => Returns `${this.start.toISOString()} to ${this.end.toISOString()}`
    // => Exposes encapsulated state (read-only access)
  }
  // => End of toString()
}
// => End of DateRange class
 
// Usage in booking domain
const booking1 = new DateRange(
  // => booking1 = new DateRange(
 
  new Date("2026-03-01"), // => Check-in: March 1
  new Date("2026-03-05"), // => Check-out: March 5
);
// => booking1: March 1-5 (4 nights)
 
const booking2 = new DateRange(
  // => booking2 = new DateRange(
 
  new Date("2026-03-04"), // => Check-in: March 4
  new Date("2026-03-07"), // => Check-out: March 7
);
// => booking2: March 4-7 (3 nights)
 
console.log(booking1.getDurationDays()); // => Output: 4
console.log(booking1.overlaps(booking2)); // => Output: true (March 4-5 overlap)
 
const checkInDate = new Date("2026-03-03");
// => checkInDate = new Date("2026-03-03")
// => Arithmetic calculation on domain values
 
console.log(booking1.contains(checkInDate)); // => Output: true (March 3 in March 1-5 range)
 
// Business logic using DateRange
class Hotel {
  // => Hotel: domain class definition
  // => Encapsulates data and domain behavior together
 
  private bookings: DateRange[] = [];
  // => Encapsulated field (not publicly accessible)
  // => Collection: add/remove through domain methods only
 
  canBook(requestedRange: DateRange): boolean {
    // => canBook: returns boolean
    // => Domain operation: enforces business rules
 
    for (const existing of this.bookings) {
      // => Loop: processes each element
 
      if (existing.overlaps(requestedRange)) {
        // => Check for conflicts
        // => Domain rule: precondition before operation
 
        return false; // => Cannot book: overlap with existing
      }
    }
    return true; // => Can book: no overlaps
  }
  // => End of canBook()
 
  addBooking(range: DateRange): void {
    // => addBooking: returns void
    // => Domain operation: enforces business rules
 
    if (!this.canBook(range)) {
      // => Checks: !this.canBook(range)
      // => Domain rule: precondition before operation
 
      throw new Error("Cannot book: dates overlap with existing booking");
      // => Throws domain error: "Cannot book: dates overlap with existing booking"
      // => Guard: entity must exist to proceed
      // => Caller must handle this exception case
    }
    this.bookings.push(range); // => Add booking
    // => Booking added
  }
  // => End of addBooking()
}
// => End of Hotel class
 
const hotel = new Hotel();
// => hotel = new Hotel()
 
hotel.addBooking(booking1); // => Add first booking (March 1-5)
// hotel.addBooking(booking2);                   // => Would throw: overlaps with booking1

// Domain: User management
public class Email {
// => class: public unknown field
// => Rich domain model: combines data + business behavior
// => OOP: bundles data with behavior
 
 
 
    private final String value;              // => Immutable email address
 
    private Email(String value) {
    // => Email: private unknown field
    // => Encapsulated: accessed only through domain methods
    // => Not directly accessible to clients
 
 
 
        this.value = value;                  // => Store validated email
        // => Email created (validation already performed)
    }
 
    public static Email of(String value) {
    // => static: public unknown field
    // => Part of domain model implementation
    // => Entity lifecycle managed
 
 
 
        if (value == null || value.trim().isEmpty()) {  // => Validate: not empty
            throw new IllegalArgumentException("Email cannot be empty");
            // => Throws domain error: "Email cannot be empty"
            // => Domain invariant violated: operation rejected
            // => Caller must handle this exception case
 
 
 
        }
 
        String normalized = value.trim().toLowerCase();  // => Normalize: trim + lowercase
 
        if (!isValid(normalized)) {          // => Validate format
            throw new IllegalArgumentException("Invalid email format: " + value);
            // => Throws domain error: "Invalid email format: "
            // => Validation: input must meet format rules
            // => Caller must handle this exception case
 
 
 
        }
 
        return new Email(normalized);        // => Return validated Email
        // => Email created with normalized value
    }
 
    private static boolean isValid(String email) {
    // => static: private unknown field
    // => Encapsulated: accessed only through domain methods
    // => Not directly accessible to clients
 
 
 
        // Simplified validation (real impl would use regex or library)
        return email.contains("@") &&        // => Must have @ symbol
               email.indexOf("@") > 0 &&     // => @ not at start
               email.indexOf("@") < email.length() - 1 &&  // => @ not at end
               email.indexOf("@") == email.lastIndexOf("@");  // => Exactly one @
    }
 
    public String getDomain() {
    // => String: public unknown field
    // => Aggregate state managed
    // => Domain service delegation
 
 
 
        return this.value.substring(this.value.indexOf("@") + 1);  // => Extract domain part
    }
 
    public String getLocalPart() {
    // => String: public unknown field
    // => Business rule enforced
    // => Repository interaction point
 
 
 
        return this.value.substring(0, this.value.indexOf("@"));  // => Extract local part
    }
 
    @Override
    public boolean equals(Object obj) {
    // => boolean: public unknown field
    // => Domain logic applied here
    // => Value object creation
 
 
 
        if (this == obj) return true;        // => Same reference
        if (!(obj instanceof Email)) return false;  // => Different type
 
        Email other = (Email) obj;
        return this.value.equals(other.value);  // => Compare normalized values
    }
 
    @Override
    public int hashCode() {
    // => int: public unknown field
    // => Domain logic applied here
    // => Domain event triggered
 
 
 
        return this.value.hashCode();        // => Hash based on value
    }
 
    @Override
    public String toString() {
    // => String: public unknown field
    // => Part of domain model implementation
    // => Domain model component
 
 
 
        return this.value;                   // => Return email string
    }
}
 
// Usage
Email email1 = Email.of("  USER@EXAMPLE.COM  ");  // => Create email (normalized)
// => email1.value = "user@example.com" (trimmed, lowercased)
 
Email email2 = Email.of("user@example.com");      // => Create identical email
System.out.println(email1.equals(email2));        // => Output: true (same normalized value)
 
System.out.println(email1.getDomain());           // => Output: example.com
System.out.println(email1.getLocalPart());        // => Output: user
 
// Email invalid1 = Email.of("notanemail");       // => Throws: invalid format (no @)
// Email invalid2 = Email.of("@example.com");     // => Throws: invalid format (@ at start)
// Email invalid3 = Email.of("user@@example.com");  // => Throws: invalid format (multiple @)
 
// Business logic using Email
class User {
// => User: domain class definition
// => Encapsulates data and domain behavior together
// => OOP: bundles data with behavior
 
 
 
    private final String userId;
    // => final: private unknown field
    // => Encapsulated: accessed only through domain methods
    // => Not directly accessible to clients
 
 
 
    private Email email;                     // => Email as value object (not String)
 
    public User(String userId, Email email) {
    // => User: public unknown field
    // => Part of domain model implementation
 
 
        this.userId = userId;
        // => this.userId = userId
        // => ID immutable after initial assignment
        // => Instance-level state change
 
 
 
        this.email = email;                  // => Guaranteed valid email
        // => User created with validated email
    }
 
    public void changeEmail(Email newEmail) {
    // => void: public unknown field
    // => Aggregate state managed
 
 
        this.email = newEmail;               // => Update email (guaranteed valid)
        // => Email changed
    }
 
    public Email getEmail() {
    // => Email: public unknown field
    // => Domain logic applied here
 
 
        return this.email;                   // => Return email value object
    }
}
// => End of User class
// => Domain logic applied here
 
 
 
// Usage
Email validEmail = Email.of("john@example.com");  // => Create validated email
User user = new User("U123", validEmail);         // => Create user with valid email
// => Cannot create User with invalid email (Email.of throws on invalid input)

// Domain: Shipping logistics
enum WeightUnit {
  // => WeightUnit: enumeration of domain values
  // => Closed set of domain states
  // => Business logic applied
 
  KILOGRAM = "kg",
  // => KILOGRAM = "kg",
  // => Business rule enforced
  // => DDD tactical pattern
 
  POUND = "lb",
  // => POUND = "lb",
  // => Domain logic applied here
  // => Aggregate consistency enforced
 
  GRAM = "g",
  // => GRAM = "g",
  // => Domain logic applied here
  // => Domain operation processed
}
 
class Weight {
  // => Value Object for weight measurements
  // => Rich domain model: combines data + business behavior
  // => OOP: bundles data with behavior
 
  private readonly value: number; // => Numeric value (immutable)
  private readonly unit: WeightUnit; // => Unit of measurement (immutable)
 
  private constructor(value: number, unit: WeightUnit) {
    // => constructor: private unknown field
    // => All required fields set in constructor: ensures valid state
    // => Not directly accessible to clients
 
    if (value < 0) {
      // => Validate: weight cannot be negative
      // => Domain rule: precondition before operation
      // => Entity lifecycle managed
 
      throw new Error("Weight cannot be negative");
      // => Throws domain error: "Weight cannot be negative"
      // => Domain invariant violated: operation rejected
      // => Caller must handle this exception case
    }
 
    this.value = value; // => Set value
    this.unit = unit; // => Set unit
    // => Weight created: value + unit
  }
 
  static kilograms(value: number): Weight {
    return new Weight(value, WeightUnit.KILOGRAM); // => Create weight in kg
  }
 
  static pounds(value: number): Weight {
    return new Weight(value, WeightUnit.POUND); // => Create weight in lb
  }
 
  static grams(value: number): Weight {
    return new Weight(value, WeightUnit.GRAM); // => Create weight in g
  }
 
  toKilograms(): Weight {
    // => toKilograms: returns Weight
    // => Domain operation: enforces business rules
    // => Domain service delegation
 
    if (this.unit === WeightUnit.KILOGRAM) {
      // => Checks: this.unit === WeightUnit.KILOGRAM
      // => State validation: ensures preconditions met
      // => Instance-level state change
 
      return this; // => Already in kg, return self
    }
 
    const conversionRates: Record<WeightUnit, number> = {
      // => conversionRates = {
      // => Immutable reference in this scope
      // => Repository interaction point
 
      [WeightUnit.KILOGRAM]: 1,
      [WeightUnit.POUND]: 0.453592, // => 1 lb = 0.453592 kg
      [WeightUnit.GRAM]: 0.001, // => 1 g = 0.001 kg
    };
 
    const kgValue = this.value * conversionRates[this.unit]; // => Convert to kg
    return new Weight(kgValue, WeightUnit.KILOGRAM); // => Return new Weight in kg
  }
  // => End of toKilograms()
  // => Domain logic applied here
  // => Value object creation
 
  add(other: Weight): Weight {
    // => add: returns Weight
    // => Domain operation: enforces business rules
    // => Domain event triggered
 
    const thisInKg = this.toKilograms(); // => Convert this to kg
    const otherInKg = other.toKilograms(); // => Convert other to kg
 
    const sumKg = thisInKg.value + otherInKg.value; // => Add kg values
    return new Weight(sumKg, WeightUnit.KILOGRAM); // => Return sum in kg
  }
  // => End of add()
  // => Domain logic applied here
  // => Domain model component
 
  isGreaterThan(other: Weight): boolean {
    // => isGreaterThan: returns boolean
    // => Domain operation: enforces business rules
    // => Business logic applied
 
    const thisInKg = this.toKilograms(); // => Convert to common unit (kg)
    const otherInKg = other.toKilograms(); // => Convert to common unit (kg)
    return thisInKg.value > otherInKg.value; // => Compare in same units
  }
  // => End of isGreaterThan()
  // => Domain logic applied here
  // => DDD tactical pattern
 
  equals(other: Weight): boolean {
    // => equals: returns boolean
    // => Domain operation: enforces business rules
    // => Aggregate consistency enforced
 
    const thisInKg = this.toKilograms(); // => Convert to common unit
    const otherInKg = other.toKilograms(); // => Convert to common unit
    return Math.abs(thisInKg.value - otherInKg.value) < 0.0001; // => Compare with tolerance
  }
  // => End of equals()
  // => Domain logic applied here
  // => Domain operation processed
 
  toString(): string {
    // => toString: returns string
    // => Domain operation: enforces business rules
 
    return `${this.value} ${this.unit}`; // => Format as "value unit"
  }
  // => End of toString()
  // => Domain logic applied here
}
// => End of Weight class
// => Domain logic applied here
 
// Usage in shipping domain
const package1 = Weight.kilograms(5); // => 5 kg
const package2 = Weight.pounds(10); // => 10 lb
const package3 = Weight.grams(500); // => 500 g
 
console.log(package1.toString()); // => Output: 5 kg
console.log(package2.toKilograms().toString()); // => Output: 4.53592 kg (10 lb converted)
 
const totalWeight = package1.add(package2).add(package3); // => Add all packages
// => Converts to common unit (kg), adds values
// => Aggregated value computed from collection
 
console.log(totalWeight.toString()); // => Output: 10.03592 kg
 
console.log(package1.isGreaterThan(package3)); // => Output: true (5 kg > 500 g)
 
// Business logic using Weight
class ShippingRate {
  // => ShippingRate: domain class definition
  // => Encapsulates data and domain behavior together
  // => OOP: bundles data with behavior
 
  static calculateCost(weight: Weight): number {
    const kgWeight = weight.toKilograms(); // => Normalize to kg for calculation
 
    if (kgWeight.value <= 1) {
      // => Checks: kgWeight.value <= 1
      // => Domain rule: precondition before operation
 
      return 5.0; // => $5 for ≤ 1 kg
    } else if (kgWeight.value <= 5) {
      return 10.0; // => $10 for 1-5 kg
    } else {
      // => Else branch: handles the alternative case
      // => Part of domain model implementation
 
      return 10.0 + (kgWeight.value - 5) * 2; // => $10 + $2 per kg over 5
    }
  }
}
// => End of ShippingRate class
// => Domain logic applied here
 
const cost = ShippingRate.calculateCost(package1); // => 5 kg → $10.00
console.log(`Shipping cost: $${cost}`); // => Output: Shipping cost: $10.00
 
// Weight prevents unit confusion bugs
// const badCalculation = package1.value + package2.value;  // => Would be 15 (5+10) but wrong units!
// Weight value object forces unit-aware operations

// Domain: E-commerce order processing
class OrderLine {
  // => Entity within aggregate (not root)
  // => Rich domain model: combines data + business behavior
 
  private readonly orderLineId: string; // => Unique identifier
  private readonly productId: string; // => Product being ordered
  private quantity: number; // => Quantity ordered (can change)
  private readonly unitPrice: Money; // => Price per unit (immutable for this order)
 
  constructor(orderLineId: string, productId: string, quantity: number, unitPrice: Money) {
    // => Constructor: initializes object state
    // => All fields initialized: object in valid initial state
 
    if (quantity <= 0) {
      // => Checks: quantity <= 0
      // => Domain rule: precondition before operation
 
      throw new Error("Quantity must be positive");
      // => Throws domain error: "Quantity must be positive"
      // => Domain invariant violated: operation rejected
      // => Caller must handle this exception case
    }
 
    this.orderLineId = orderLineId; // => Set ID
    this.productId = productId; // => Set product
    this.quantity = quantity; // => Set quantity
    this.unitPrice = unitPrice; // => Set price
    // => OrderLine created
  }
  // => End of constructor body
 
  changeQuantity(newQuantity: number): void {
    // => changeQuantity: returns void
    // => Domain operation: enforces business rules
 
    if (newQuantity <= 0) {
      // => Checks: newQuantity <= 0
      // => Domain rule: precondition before operation
 
      throw new Error("Quantity must be positive");
      // => Throws domain error: "Quantity must be positive"
      // => Domain invariant violated: operation rejected
    }
    this.quantity = newQuantity; // => Update quantity
    // => Quantity changed
  }
  // => End of changeQuantity()
 
  getTotal(): Money {
    // => getTotal: returns Money
    // => Domain operation: enforces business rules
 
    return this.unitPrice.multiply(this.quantity); // => Calculate line total
  }
  // => End of getTotal()
 
  getOrderLineId(): string {
    // => getOrderLineId: returns string
    // => Domain operation: enforces business rules
 
    return this.orderLineId;
    // => Returns this.orderLineId
    // => Exposes encapsulated state (read-only access)
  }
  // => End of getOrderLineId()
}
// => End of OrderLine class
 
class Order {
  // => Aggregate Root
  // => Rich domain model: combines data + business behavior
 
  private readonly orderId: string; // => Aggregate identity
  private customerId: string; // => Customer reference
  private orderLines: OrderLine[]; // => Entities within aggregate
  private status: OrderStatus; // => Aggregate state
 
  constructor(orderId: string, customerId: string) {
    // => Constructor: initializes object state
    // => All fields initialized: object in valid initial state
 
    this.orderId = orderId; // => Set aggregate ID
    this.customerId = customerId; // => Set customer
    this.orderLines = []; // => Initialize empty lines
    this.status = OrderStatus.Draft; // => Initial state
    // => Order aggregate created
  }
  // => End of constructor body
 
  // Aggregate Root controls access to OrderLine entities
  addLine(productId: string, quantity: number, unitPrice: Money): void {
    // => addLine: returns void
    // => Domain operation: enforces business rules
 
    this.ensureCanModify(); // => Check aggregate state allows modification
 
    const lineId = `${this.orderId}-LINE-${this.orderLines.length + 1}`; // => Generate line ID
    const line = new OrderLine(lineId, productId, quantity, unitPrice); // => Create line
 
    this.orderLines.push(line); // => Add to aggregate
    // => OrderLine added to aggregate
  }
  // => End of addLine()
 
  changeLineQuantity(orderLineId: string, newQuantity: number): void {
    // => changeLineQuantity: returns void
    // => Domain operation: enforces business rules
 
    this.ensureCanModify(); // => Check can modify
 
    const line = this.orderLines.find((l) => l.getOrderLineId() === orderLineId); // => Find line
    if (!line) {
      // => Checks: !line
      // => Domain rule: precondition before operation
 
      throw new Error(`OrderLine ${orderLineId} not found`);
      // => Throws domain exception
      // => Domain invariant violated: operation rejected
    }
 
    line.changeQuantity(newQuantity); // => Modify line through aggregate
    // => Line quantity updated
  }
  // => End of changeLineQuantity()
 
  removeLine(orderLineId: string): void {
    // => removeLine: returns void
    // => Domain operation: enforces business rules
 
    this.ensureCanModify(); // => Check can modify
 
    const index = this.orderLines.findIndex((l) => l.getOrderLineId() === orderLineId);
    // => index = this.orderLines.findIndex((l) => l.getOrderLineId() === orderLineId)
 
    if (index === -1) {
      // => Checks: index === -1
      // => State validation: ensures preconditions met
 
      throw new Error(`OrderLine ${orderLineId} not found`);
      // => Throws domain exception
      // => Domain invariant violated: operation rejected
    }
 
    this.orderLines.splice(index, 1); // => Remove line
    // => Line removed from aggregate
  }
  // => End of removeLine()
 
  submit(): void {
    // => submit: returns void
    // => Domain operation: enforces business rules
 
    if (this.orderLines.length === 0) {
      // => Checks: this.orderLines.length === 0
      // => State validation: ensures preconditions met
 
      throw new Error("Cannot submit order with no lines");
      // => Throws domain error: "Cannot submit order with no lines"
      // => Domain invariant violated: operation rejected
    }
 
    this.status = OrderStatus.Submitted; // => Change aggregate state
    // => Order submitted
  }
  // => End of submit()
 
  getTotal(): Money {
    // => getTotal: returns Money
    // => Domain operation: enforces business rules
 
    if (this.orderLines.length === 0) {
      // => Checks: this.orderLines.length === 0
      // => State validation: ensures preconditions met
 
      return Money.zero("USD"); // => Empty order = $0
    }
 
    return (
      this.orderLines
        // => Returns this.orderLines
        // => Exposes encapsulated state (read-only access)
 
        .map((line) => line.getTotal()) // => Get each line total
        .reduce((sum, lineTotal) => sum.add(lineTotal))
    ); // => Sum all lines
  }
  // => End of getTotal()
 
  private ensureCanModify(): void {
    // => Internal logic (not part of public API)
    // => Encapsulated: accessed only through domain methods
 
    if (this.status !== OrderStatus.Draft) {
      // => Checks: this.status !== OrderStatus.Draft
      // => State validation: ensures preconditions met
 
      throw new Error(`Cannot modify order in ${this.status} status`);
      // => Throws domain exception
      // => Domain invariant violated: operation rejected
    }
    // => Validation passed
  }
  // => End of constructor body
 
  // NO direct access to orderLines from outside
  // External code must go through aggregate root methods
}
// => End of Order class
 
enum OrderStatus {
  // => OrderStatus: enumeration of domain values
 
  Draft = "DRAFT",
  // => Draft = "DRAFT",
 
  Submitted = "SUBMITTED",
  // => Submitted = "SUBMITTED",
 
  Paid = "PAID",
  // => Paid = "PAID",
 
  Shipped = "SHIPPED",
  // => Shipped = "SHIPPED",
}
// => End of OrderLine class definition
 
// Usage
const order = new Order("ORD-001", "CUST-123"); // => Create aggregate root
order.addLine("PROD-A", 2, Money.dollars(50)); // => Add first line
order.addLine("PROD-B", 1, Money.dollars(30)); // => Add second line
// => order.orderLines.length = 2
 
const total = order.getTotal(); // => Calculate total
console.log(total.toString()); // => Output: USD 130.00 (2×50 + 1×30)
 
order.changeLineQuantity("ORD-001-LINE-1", 3); // => Change first line: 2 → 3
// => Total now: USD 180.00 (3×50 + 1×30)
 
order.submit(); // => Submit order
// order.addLine("PROD-C", 1, Money.dollars(20));  // => Would throw: cannot modify submitted order