Domain Driven Design

// Plain data classes (no behavior)
interface Order {
  // => Just data, no methods
  id: string;
  customerId: string;
  items: OrderItem[];
  total: number;
  status: string;
  // => status as string (no validation)
  createdAt: Date;
}

interface OrderItem {
  productId: string;
  quantity: number;
  price: number;
}

// Business logic in service (transaction script)
class OrderService {
  // => All logic in service layer
  // => Domain objects just data carriers

  placeOrder(order: Order): void {
    // => Business rules in service (scattered)
    if (order.items.length === 0) {
      // => Validation outside domain object
      throw new Error("Order must have items");
    }

    order.total = order.items.reduce((sum, item) => sum + item.price * item.quantity, 0);
    // => Calculation outside domain object
    // => Order doesn't know how to calculate itself

    order.status = "placed";
    // => Status change outside domain object
    // => No validation of state transitions

    this.orderRepository.save(order);
    // => Persistence logic in service
  }

  cancelOrder(order: Order): void {
    // => More business logic in service
    if (order.status === "shipped") {
      // => Duplication: Status validation repeated
      throw new Error("Cannot cancel shipped order");
    }

    order.status = "cancelled";
    // => Status mutation outside domain object
    this.orderRepository.save(order);
  }
}

// Value Object: Money (immutable)
class Money {
  // => Value object for currency
  // => Immutable: No setters
  private constructor(
    public readonly amount: number,
    // => readonly: Cannot be changed after construction
    public readonly currency: string,
  ) {
    // => Private constructor: Use factory method
    if (amount < 0) {
      throw new Error("Money amount cannot be negative");
      // => Invariant: Money must be non-negative
    }
  }

  static create(amount: number, currency: string): Money {
    // => Factory method for creation
    // => Validates before construction
    return new Money(amount, currency);
  }

  add(other: Money): Money {
    // => Behavior: Addition
    // => Returns new Money (immutability)
    if (this.currency !== other.currency) {
      throw new Error("Cannot add different currencies");
      // => Invariant: Same currency required
    }
    return new Money(this.amount + other.amount, this.currency);
    // => New instance (immutability preserved)
  }

  multiply(factor: number): Money {
    // => Behavior: Multiplication
    return new Money(this.amount * factor, this.currency);
  }

  equals(other: Money): boolean {
    // => Value equality (not reference)
    return this.amount === other.amount && this.currency === other.currency;
  }
}

// Entity: Order (has identity, mutable state)
class Order {
  // => Entity with identity (id)
  // => Mutable state (status changes)
  private items: OrderItem[] = [];
  // => Private field: Encapsulation
  // => Cannot be modified directly from outside

  private status: OrderStatus = "draft";
  // => Private status: Enforces state transitions

  constructor(
    public readonly id: string,
    // => Identity field (immutable)
    public readonly customerId: string,
  ) {}

  addItem(productId: string, quantity: number, price: Money): void {
    // => Behavior: Add item with validation
    if (this.status !== "draft") {
      // => Business rule: Can only modify draft orders
      throw new Error("Cannot modify non-draft order");
    }

    if (quantity <= 0) {
      // => Invariant: Positive quantity
      throw new Error("Quantity must be positive");
    }

    this.items.push({ productId, quantity, price });
    // => Mutation encapsulated in method
  }

  place(): void {
    // => Behavior: Place order (state transition)
    if (this.status !== "draft") {
      throw new Error("Can only place draft orders");
      // => State transition validation
    }

    if (this.items.length === 0) {
      throw new Error("Cannot place empty order");
      // => Business rule: Orders need items
    }

    this.status = "placed";
    // => State transition encapsulated
  }

  cancel(): void {
    // => Behavior: Cancel order
    if (this.status === "shipped" || this.status === "delivered") {
      throw new Error("Cannot cancel shipped/delivered order");
      // => Business rule: Cannot cancel after shipping
    }

    this.status = "cancelled";
    // => Valid state transition
  }

  calculateTotal(): Money {
    // => Behavior: Calculate total
    // => Order knows how to calculate itself
    return this.items.reduce(
      (sum, item) => sum.add(item.price.multiply(item.quantity)),
      Money.create(0, "USD"),
      // => Reduces to Money value object
    );
  }

  getStatus(): OrderStatus {
    // => Getter for private field (read-only access)
    return this.status;
  }

  getItems(): readonly OrderItem[] {
    // => Returns readonly array (immutability)
    return this.items;
    // => Prevents external mutation
  }
}

type OrderStatus = "draft" | "placed" | "shipped" | "delivered" | "cancelled";
// => Type alias for valid statuses
// => Prevents invalid string values

interface OrderItem {
  productId: string;
  quantity: number;
  price: Money;
}

// Value Object: Address
class Address {
  // => Value object (immutable)
  private constructor(
    public readonly street: string,
    public readonly city: string,
    public readonly zipCode: string,
    public readonly country: string,
  ) {
    if (!street || !city || !zipCode || !country) {
      throw new Error("All address fields required");
      // => Validation in constructor
    }
  }

  static create(street: string, city: string, zipCode: string, country: string): Address {
    return new Address(street, city, zipCode, country);
  }

  equals(other: Address): boolean {
    // => Value equality
    return (
      this.street === other.street &&
      this.city === other.city &&
      this.zipCode === other.zipCode &&
      this.country === other.country
    );
  }
}

// Entity: OrderLine (part of Order aggregate)
class OrderLine {
  // => Entity inside aggregate
  // => No independent existence outside Order

  constructor(
    public readonly id: string,
    // => Identity within aggregate
    public readonly productId: string,
    public readonly quantity: number,
    public readonly unitPrice: Money,
  ) {
    if (quantity <= 0) {
      throw new Error("Quantity must be positive");
    }
  }

  getTotal(): Money {
    // => Calculate line total
    return this.unitPrice.multiply(this.quantity);
  }
}

// Aggregate Root: Order
class Order {
  // => Aggregate root: Entry point for modifications
  // => Enforces invariants across entire aggregate
  private orderLines: OrderLine[] = [];
  // => Private collection: Cannot be modified externally
  private status: OrderStatus = "draft";
  private shippingAddress?: Address;
  // => Optional until order placed

  constructor(
    public readonly id: string,
    // => Aggregate root identity
    public readonly customerId: string,
  ) {}

  // Commands (modify aggregate)
  addOrderLine(productId: string, quantity: number, unitPrice: Money): void {
    // => Command: Add order line
    // => Validates state before modification
    if (this.status !== "draft") {
      throw new Error("Cannot modify non-draft order");
      // => Invariant: Only draft orders modifiable
    }

    const lineId = `${this.id}-${this.orderLines.length + 1}`;
    const orderLine = new OrderLine(lineId, productId, quantity, unitPrice);
    // => Create entity
    this.orderLines.push(orderLine);
    // => Add to aggregate
  }

  removeOrderLine(lineId: string): void {
    // => Command: Remove order line
    if (this.status !== "draft") {
      throw new Error("Cannot modify non-draft order");
    }

    const index = this.orderLines.findIndex((line) => line.id === lineId);
    if (index === -1) {
      throw new Error("Order line not found");
    }

    this.orderLines.splice(index, 1);
    // => Remove from aggregate
  }

  setShippingAddress(address: Address): void {
    // => Command: Set shipping address
    if (this.status !== "draft") {
      throw new Error("Cannot modify non-draft order");
    }

    this.shippingAddress = address;
    // => Store value object
  }

  place(): void {
    // => Command: Place order
    if (this.status !== "draft") {
      throw new Error("Order already placed");
    }

    if (this.orderLines.length === 0) {
      throw new Error("Cannot place empty order");
      // => Invariant: Orders need lines
    }

    if (!this.shippingAddress) {
      throw new Error("Shipping address required");
      // => Invariant: Address required before placing
    }

    this.status = "placed";
    // => State transition
  }

  ship(): void {
    // => Command: Ship order
    if (this.status !== "placed") {
      throw new Error("Can only ship placed orders");
      // => State transition validation
    }

    this.status = "shipped";
  }

  // Queries (read aggregate state)
  getTotal(): Money {
    // => Query: Calculate total
    // => Aggregate knows how to calculate itself
    return this.orderLines.reduce((sum, line) => sum.add(line.getTotal()), Money.create(0, "USD"));
  }

  getStatus(): OrderStatus {
    return this.status;
  }

  getOrderLines(): readonly OrderLine[] {
    // => Returns readonly (prevents external mutation)
    return this.orderLines;
  }
}

type OrderStatus = "draft" | "placed" | "shipped" | "delivered" | "cancelled";

// Repository interface (abstraction)
interface IOrderRepository {
  // => Repository for Order aggregate
  // => Collection-like interface
  save(order: Order): Promise<void>;
  // => Persist aggregate (insert or update)

  findById(id: string): Promise<Order | null>;
  // => Retrieve by identity

  findByCustomerId(customerId: string): Promise<Order[]>;
  // => Query by customer (returns collection)

  delete(id: string): Promise<void>;
  // => Remove from collection
}

// In-memory implementation (for testing)
class InMemoryOrderRepository implements IOrderRepository {
  // => Test double: No database required
  private orders: Map<string, Order> = new Map();
  // => In-memory storage

  async save(order: Order): Promise<void> {
    // => Store in map
    this.orders.set(order.id, order);
    // => Simulates database save
  }

  async findById(id: string): Promise<Order | null> {
    // => Retrieve from map
    return this.orders.get(id) || null;
    // => Returns null if not found
  }

  async findByCustomerId(customerId: string): Promise<Order[]> {
    // => Filter by customer
    return Array.from(this.orders.values()).filter((order) => order.customerId === customerId);
    // => Returns matching orders
  }

  async delete(id: string): Promise<void> {
    this.orders.delete(id);
  }
}

// PostgreSQL implementation (for production)
class PostgresOrderRepository implements IOrderRepository {
  // => Production implementation
  constructor(private pool: pg.Pool) {
    // => Inject database pool
  }

  async save(order: Order): Promise<void> {
    // => Persist to PostgreSQL
    const client = await this.pool.connect();
    try {
      await client.query("BEGIN");
      // => Start transaction

      await client.query(
        `INSERT INTO orders (id, customer_id, status, created_at)
         VALUES ($1, $2, $3, NOW())
         ON CONFLICT (id) DO UPDATE
         SET status = $2`,
        // => Upsert order
        [order.id, order.customerId, order.getStatus()],
      );

      // Delete existing order lines
      await client.query("DELETE FROM order_lines WHERE order_id = $1", [order.id]);

      // Insert order lines
      for (const line of order.getOrderLines()) {
        await client.query(
          `INSERT INTO order_lines (id, order_id, product_id, quantity, unit_price)
           VALUES ($1, $2, $3, $4, $5)`,
          [line.id, order.id, line.productId, line.quantity, line.unitPrice.amount],
        );
      }

      await client.query("COMMIT");
      // => Commit transaction (atomic)
    } catch (error) {
      await client.query("ROLLBACK");
      // => Rollback on error
      throw error;
    } finally {
      client.release();
    }
  }

  async findById(id: string): Promise<Order | null> {
    // => Reconstruct aggregate from database
    const result = await this.pool.query("SELECT * FROM orders WHERE id = $1", [id]);

    if (result.rows.length === 0) {
      return null;
    }

    const orderRow = result.rows[0];
    const order = new Order(orderRow.id, orderRow.customer_id);
    // => Reconstruct aggregate root

    // Load order lines
    const linesResult = await this.pool.query("SELECT * FROM order_lines WHERE order_id = $1", [id]);

    for (const lineRow of linesResult.rows) {
      // => Reconstruct entities
      order.addOrderLine(lineRow.product_id, lineRow.quantity, Money.create(lineRow.unit_price, "USD"));
    }

    // Restore status (hack for demo, normally use factory)
    // => Production: Use factory method or reflection
    (order as any).status = orderRow.status;

    return order;
  }

  async findByCustomerId(customerId: string): Promise<Order[]> {
    // => Query by customer
    const result = await this.pool.query("SELECT id FROM orders WHERE customer_id = $1", [customerId]);

    const orders: Order[] = [];
    for (const row of result.rows) {
      const order = await this.findById(row.id);
      if (order) {
        orders.push(order);
      }
    }

    return orders;
  }

  async delete(id: string): Promise<void> {
    const client = await this.pool.connect();
    try {
      await client.query("BEGIN");
      await client.query("DELETE FROM order_lines WHERE order_id = $1", [id]);
      await client.query("DELETE FROM orders WHERE id = $1", [id]);
      await client.query("COMMIT");
    } catch (error) {
      await client.query("ROLLBACK");
      throw error;
    } finally {
      client.release();
    }
  }
}

// Base domain event
interface DomainEvent {
  // => All domain events implement this
  eventId: string;
  occurredAt: Date;
  aggregateId: string;
}

// Specific domain events
interface OrderPlacedEvent extends DomainEvent {
  // => Event: Order was placed
  eventType: "OrderPlaced";
  customerId: string;
  total: Money;
}

interface OrderShippedEvent extends DomainEvent {
  // => Event: Order was shipped
  eventType: "OrderShipped";
  shippingAddress: Address;
}

// Aggregate with domain events
class Order {
  private events: DomainEvent[] = [];
  // => Uncommitted events
  // => Collected during aggregate modifications

  // ... existing code ...

  place(): void {
    if (this.status !== "draft") {
      throw new Error("Order already placed");
    }

    if (this.orderLines.length === 0) {
      throw new Error("Cannot place empty order");
    }

    this.status = "placed";
    // => State change

    this.addDomainEvent({
      // => Record what happened
      eventId: crypto.randomUUID(),
      eventType: "OrderPlaced",
      occurredAt: new Date(),
      aggregateId: this.id,
      customerId: this.customerId,
      total: this.getTotal(),
    });
    // => Event captured (not yet published)
  }

  ship(): void {
    if (this.status !== "placed") {
      throw new Error("Can only ship placed orders");
    }

    this.status = "shipped";

    this.addDomainEvent({
      eventId: crypto.randomUUID(),
      eventType: "OrderShipped",
      occurredAt: new Date(),
      aggregateId: this.id,
      shippingAddress: this.shippingAddress!,
    });
  }

  private addDomainEvent(event: DomainEvent): void {
    // => Add to uncommitted events
    this.events.push(event);
  }

  getDomainEvents(): readonly DomainEvent[] {
    // => Get uncommitted events
    return this.events;
  }

  clearDomainEvents(): void {
    // => Clear after publishing
    this.events = [];
  }
}

// Event handler
class EmailNotificationHandler {
  // => Subscribes to domain events
  async handle(event: DomainEvent): Promise<void> {
    // => Process event
    if (event.eventType === "OrderPlaced") {
      // => Handle OrderPlaced event
      const orderPlaced = event as OrderPlacedEvent;
      console.log(`Sending order confirmation to customer ${orderPlaced.customerId}`);
      // => Side effect: Send email
    }

    if (event.eventType === "OrderShipped") {
      // => Handle OrderShipped event
      const orderShipped = event as OrderShippedEvent;
      console.log(`Sending shipping notification to ${orderShipped.shippingAddress.street}`);
    }
  }
}

// Event dispatcher
class DomainEventDispatcher {
  // => Publishes events to handlers
  private handlers: Array<(event: DomainEvent) => Promise<void>> = [];

  subscribe(handler: (event: DomainEvent) => Promise<void>): void {
    // => Register event handler
    this.handlers.push(handler);
  }

  async dispatch(events: readonly DomainEvent[]): Promise<void> {
    // => Publish events to all handlers
    for (const event of events) {
      for (const handler of this.handlers) {
        await handler(event);
        // => Invoke handler with event
      }
    }
  }
}

// Usage with repository
class OrderApplicationService {
  constructor(
    private orderRepository: IOrderRepository,
    private eventDispatcher: DomainEventDispatcher,
  ) {}

  async placeOrder(orderId: string): Promise<void> {
    // => Application service coordinates
    const order = await this.orderRepository.findById(orderId);
    if (!order) {
      throw new Error("Order not found");
    }

    order.place();
    // => Domain logic (generates events)

    await this.orderRepository.save(order);
    // => Persist aggregate

    await this.eventDispatcher.dispatch(order.getDomainEvents());
    // => Publish events (after successful save)

    order.clearDomainEvents();
    // => Clear events after publishing
  }
}

// ❌ BAD: Validation in setter
class Email {
  constructor(public value: string) {}

  validate(): boolean {
    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(this.value);
  }
}

const email = new Email("invalid");
// => Invalid email created!

// ✅ GOOD: Validation in constructor
class Email {
  private constructor(public readonly value: string) {}

  static create(value: string): Email {
    if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)) {
      throw new Error("Invalid email format");
    }
    return new Email(value);
  }
}

// Email.create("invalid");
// => Throws immediately

// ❌ BAD: Mutable value object
class Money {
  constructor(public amount: number) {}

  add(value: number): void {
    this.amount += value;
    // => Mutation (unexpected behavior)
  }
}

// ✅ GOOD: Immutable value object
class Money {
  constructor(public readonly amount: number) {}

  add(other: Money): Money {
    return new Money(this.amount + other.amount);
    // => Returns new instance
  }
}

// ❌ BAD: Complex constructor
class Order {
  constructor(id: string, customerId: string, lines: OrderLine[], status: OrderStatus, shippingAddress: Address) {
    // => Too many parameters
  }
}

// ✅ GOOD: Factory method
class Order {
  private constructor(
    public readonly id: string,
    public readonly customerId: string,
  ) {}

  static createDraft(customerId: string): Order {
    // => Factory for draft orders
    const id = crypto.randomUUID();
    return new Order(id, customerId);
  }

  static reconstitute(id: string, customerId: string, lines: OrderLine[], status: OrderStatus): Order {
    // => Factory for database loading
    const order = new Order(id, customerId);
    (order as any).orderLines = lines;
    (order as any).status = status;
    return order;
  }
}

// ❌ BAD: Logic in service
class OrderService {
  placeOrder(order: Order): void {
    if (order.items.length === 0) {
      throw new Error("No items");
    }
    order.status = "placed";
  }
}

// ✅ GOOD: Logic in domain
class Order {
  place(): void {
    if (this.orderLines.length === 0) {
      throw new Error("No items");
    }
    this.status = "placed";
  }
}

// ❌ BAD: Public field
class Order {
  public items: OrderItem[] = [];
}

order.items.push(invalidItem);
// => Bypasses validation!

// ✅ GOOD: Private field
class Order {
  private items: OrderItem[] = [];

  addItem(item: OrderItem): void {
    // => Validation here
    this.items.push(item);
  }
}

// ❌ BAD: Multiple aggregates in transaction
async function transferStock(fromWarehouse: Warehouse, toWarehouse: Warehouse): Promise<void> {
  fromWarehouse.removeStock(productId, quantity);
  toWarehouse.addStock(productId, quantity);
  // => Two aggregates modified (risky)
  await repository.save(fromWarehouse);
  await repository.save(toWarehouse);
}

// ✅ GOOD: Event-driven
async function transferStock(fromWarehouse: Warehouse): Promise<void> {
  fromWarehouse.removeStock(productId, quantity);
  // => Generates StockRemovedEvent
  await repository.save(fromWarehouse);
  await eventDispatcher.dispatch(fromWarehouse.getDomainEvents());
  // => Event handler updates toWarehouse
}