Implementasi Domain-Driven Design (DDD) dan Hexagonal Architecture pada TypeScript

Mencegah degradasi struktural aplikasi enterprise: pemisahan domain core dari framework, implementasi Aggregate Root dan Value Object immutable, serta isolasi database via Ports and Adapters.

PuluhLabs Engineering Team, Principal Software Architect · 13 November 2026 · 7 min baca

Implementasi Domain-Driven Design (DDD) dan Hexagonal Architecture pada TypeScript
Pengembangan Web
DECOUPLED

Isi artikel ini

  • Prinsip Dependency Inversion: Inti Domain yang Terisolasi
  • Mengimplementasikan Elemen Taktis DDD
  • Mendefinisikan Ports (Kontrak Antarmuka)
  • Membangun Adapters: Menghubungkan Infrastruktur Riil
  • Keuntungan dalam Pengujian Otomatis

Dalam pengembangan aplikasi skala enterprise, arsitektur tiga lapis tradisional (Controller - Service - Repository) sering kali mengalami degradasi struktural seiring bertambahnya kompleksitas fitur. Service class berubah menjadi "god class" berisi ribuan baris kode campuran antara validasi HTTP, query SQL, dan logika bisnis. Entitas database hanya berupa kantong data pasif tanpa aturan validasi (Anemic Domain Model), sementara perubahan library atau database memaksa penulisan ulang seluruh logika sistem.

Untuk menjaga agar logika bisnis inti tetap murni, tahan lama, dan mudah diuji, arsitektur perangkat lunak modern menggabungkan prinsip Domain-Driven Design (DDD) dengan pola Hexagonal Architecture (dikenal juga sebagai Ports and Adapters).

text
Struktur Hexagonal Architecture (Ports and Adapters):
┌────────────────────────────────────────────────────────┐
│ Inbound / Driving Adapters (REST API, GraphQL, CLI)    │
│                 │                                      │
│                 ▼ Memanggil melalui                    │
│ ┌────────────────────────────────────────────────────┐ │
│ │ Inbound Ports (Use Case Interfaces)                │ │
│ │   │                                                │ │
│ │   ▼                                                │ │
│ │ ┌────────────────────────────────────────────────┐ │ │
│ │ │ Domain Core (Murni TypeScript Tanpa Framework) │ │ │
│ │ │ - Entities & Value Objects                     │ │ │
│ │ │ - Aggregate Roots                              │ │ │
│ │ │ - Domain Events & Invariants                   │ │ │
│ │ └────────────────────────────────────────────────┘ │ │
│ │   │                                                │ │
│ │   ▼ Menggunakan definisi                           │ │
│ │ Outbound Ports (Repository / Gateway Interfaces)   │ │
│ └────────────────────────────────────────────────────┘ │
│                 │                                      │
│                 ▼ Diimplementasikan oleh               │
│ Outbound / Driven Adapters (PostgreSQL, Redis, Kafka)  │
└────────────────────────────────────────────────────────┘

Prinsip Dependency Inversion: Inti Domain yang Terisolasi #

Aturan emas dalam Hexagonal Architecture adalah: Arah dependensi selalu mengarah ke dalam.

  • Modul Domain Core tidak boleh mengimpor library luar apa pun, tidak ada decorator database (seperti TypeORM @Entity atau Prisma), dan tidak ada kode HTTP framework (seperti Express atau NestJS).
  • Database dan antarmuka web dianggap sebagai detail teknis di lapisan luar. Jika database diganti dari PostgreSQL ke MongoDB, kode logika bisnis di dalam Domain Core tidak boleh berubah satu baris pun.

Mengimplementasikan Elemen Taktis DDD #

1. Value Object: Menjamin Immutability dan Validasi Bawaan #

Value Object adalah objek yang diidentifikasi oleh nilainya, bukan oleh ID unik. Value Object bersifat abadi (immutable) dan selalu valid sejak pertama kali dibuat.

typescript
// domain/value-objects/Money.ts
export class Money {
  private readonly amount: number;
  private readonly currency: string;

  private constructor(amount: number, currency: string) {
    if (amount < 0) {
      throw new Error('Nominal uang tidak boleh bernilai negatif.');
    }
    this.amount = Math.round(amount * 100) / 100;
    this.currency = currency.toUpperCase();
  }

  public static create(amount: number, currency = 'IDR'): Money {
    return new Money(amount, currency);
  }

  public add(other: Money): Money {
    if (this.currency !== other.currency) {
      throw new Error(`Tidak dapat menjumlahkan mata uang berbeda: ${this.currency} dan ${other.currency}`);
    }
    return new Money(this.amount + other.amount, this.currency);
  }

  public getAmount(): number {
    return this.amount;
  }

  public getCurrency(): string {
    return this.currency;
  }

  public equals(other: Money): boolean {
    return this.amount === other.amount && this.currency === other.currency;
  }
}

2. Aggregate Root: Penjaga Batas Invarian Bisnis #

Aggregate Root adalah entitas utama yang mengontrol akses ke entitas-entitas di dalamnya, memastikan seluruh aturan konsistensi bisnis (invariants) selalu terpenuhi sebelum status disimpan.

typescript
// domain/aggregates/Order.ts
import { Money } from '../value-objects/Money';

export type OrderStatus = 'DRAFT' | 'CONFIRMED' | 'PAID' | 'CANCELLED';

export interface OrderItem {
  productId: string;
  unitPrice: Money;
  quantity: number;
}

export class Order {
  private readonly id: string;
  private readonly customerId: string;
  private items: OrderItem[] = [];
  private status: OrderStatus = 'DRAFT';
  private domainEvents: any[] = [];

  constructor(id: string, customerId: string) {
    this.id = id;
    this.customerId = customerId;
  }

  public addItem(productId: string, unitPrice: Money, quantity: number): void {
    if (this.status !== 'DRAFT') {
      throw new Error('Tidak dapat mengubah item pada pesanan yang sudah difinalisasi.');
    }
    if (quantity <= 0) {
      throw new Error('Kuantitas produk wajib lebih besar dari nol.');
    }

    this.items.push({ productId, unitPrice, quantity });
  }

  public calculateTotal(): Money {
    return this.items.reduce(
      (total, item) => total.add(Money.create(item.unitPrice.getAmount() * item.quantity)),
      Money.create(0)
    );
  }

  public confirm(): void {
    if (this.items.length === 0) {
      throw new Error('Pesanan kosong tidak dapat dikonfirmasi.');
    }
    this.status = 'CONFIRMED';
    
    // Merekam Domain Event
    this.domainEvents.push({
      eventType: 'ORDER_CONFIRMED',
      orderId: this.id,
      totalAmount: this.calculateTotal().getAmount(),
      occurredOn: new Date(),
    });
  }

  public pullDomainEvents(): any[] {
    const events = [...this.domainEvents];
    this.domainEvents = [];
    return events;
  }

  public getId(): string { return this.id; }
  public getStatus(): OrderStatus { return this.status; }
}

Mendefinisikan Ports (Kontrak Antarmuka) #

Port adalah abstraksi murni berupa TypeScript interface yang menyatakan kebutuhan Domain Core terhadap lingkungan luar:

typescript
// domain/ports/OrderRepositoryPort.ts
import { Order } from '../aggregates/Order';

export interface OrderRepositoryPort {
  save(order: Order): Promise<void>;
  findById(id: string): Promise<Order | null>;
}

// domain/ports/NotificationGatewayPort.ts
export interface NotificationGatewayPort {
  sendOrderConfirmationEmail(toEmail: string, orderId: string): Promise<void>;
}

Membangun Adapters: Menghubungkan Infrastruktur Riil #

Adapter adalah implementasi konkret dari Port yang berkomunikasi dengan teknologi spesifik di luar:

typescript
// infrastructure/adapters/PostgresOrderRepositoryAdapter.ts
import { OrderRepositoryPort } from '../../domain/ports/OrderRepositoryPort';
import { Order } from '../../domain/aggregates/Order';
import { Pool } from 'pg';

export class PostgresOrderRepositoryAdapter implements OrderRepositoryPort {
  constructor(private readonly dbPool: Pool) {}

  async save(order: Order): Promise<void> {
    const client = await this.dbPool.connect();
    try {
      await client.query(
        `INSERT INTO orders (id, status, total_amount)
         VALUES ($1, $2, $3)
         ON CONFLICT (id) DO UPDATE
         SET status = EXCLUDED.status, updated_at = NOW()`,
        [order.getId(), order.getStatus(), order.calculateTotal().getAmount()]
      );
    } finally {
      client.release();
    }
  }

  async findById(id: string): Promise<Order | null> {
    // Mapping dari relasional database kembali ke objek Domain Order
    return null;
  }
}

Keuntungan dalam Pengujian Otomatis #

Manfaat terbesar dari arsitektur heksagonal adalah kemudahan pengujian unit (unit testing). Karena domain terisolasi murni dari database dan jaringan:

typescript
// tests/domain/Order.spec.ts
import { Order } from '../../domain/aggregates/Order';
import { Money } from '../../domain/value-objects/Money';

describe('Order Aggregate Root', () => {
  it('harus menolak konfirmasi jika pesanan tidak memiliki item', () => {
    const order = new Order('ord-1', 'cust-99');
    expect(() => order.confirm()).toThrow('Pesanan kosong tidak dapat dikonfirmasi.');
  });

  it('harus menghitung total harga dengan benar dan menerbitkan event', () => {
    const order = new Order('ord-1', 'cust-99');
    order.addItem('prod-A', Money.create(50000), 2);
    order.addItem('prod-B', Money.create(25000), 1);

    expect(order.calculateTotal().getAmount()).toBe(125000);
    order.confirm();

    const events = order.pullDomainEvents();
    expect(events).toHaveLength(1);
    expect(events[0].eventType).toBe('ORDER_CONFIRMED');
  });
});

Uji coba di atas berjalan dalam hitungan milidetik tanpa perlu menyalakan Docker database, mock server HTTP, atau ketergantungan eksternal apa pun. Arsitektur ini menjamin kode sistem enterprise tetap kokoh, mudah dirawat, dan terbebas dari jebakan keterikatan vendor (vendor lock-in).

Bagikan Artikel Ini:
Topik Terkait:Semua artikel: Arsitektur sistem dan APIDomain Driven DesignHexagonal ArchitectureTypeScriptClean ArchitectureSoftware Design
Istilah Teknis Terkait (Knowledge Graph Glossary)
Jejaring Entitas & Solusi Teknis Terkait
3 Solusi Terintegrasi
Architecture Matrix

Perbandingan Headless CMS vs Monolitik

Kajian komparatif performa, keamanan OWASP, dan total biaya kepemilikan (TCO).

Buka Solusi
Planning Tool

Kalkulator Investasi & Jadwal Website

Estimasi biaya pembuatan website company profile, portal B2B, atau web app kustom.

Buka Solusi
Partnership Hub

Kemitraan White-Label untuk Agensi

Dukungan rekayasa teknis rahasia di balik layar agensi Anda dengan NDA resmi.

Buka Solusi

PuluhLabs Engineering Team

Principal Software Architect

Terakhir diperbarui: 13 November 2026

Ingin Menerapkan Standar Performa Ini pada Proyek Agensi Anda?

Tim PuluhLabs siap menjadi mitra rekayasa digital rahasia (white-label) untuk agensi Anda. Garansi performa skor Lighthouse 90+, Core Web Vitals hijau, dan 100% hak milik kode.

Konsultasi Proyek Bersama Tim PuluhLabs

Artikel Rekomendasi Selanjutnya

Lihat Semua
  1. Pengembangan Web

    Membangun Arsitektur Event-Driven Berkinerja Tinggi Menggunakan NestJS, BullMQ, dan Redis

  2. Pengembangan Web

    Arsitektur Search Engine Internal: Implementasi Hybrid Search (Vektor + BM25) Meilisearch & Qdrant

  3. Pengembangan Web

    Arsitektur Resiliency Microservices: Menerapkan Circuit Breaker, Bulkhead, dan Retry Jitter