SuperAPI AI Directory

ddd-kotlin-idioms

Coding & development

View repository

Updated 10-16 16:27

About this skill

One-line summary

Translate DDD pattern decisions into idiomatic Kotlin using stdlib only — no framework opinions.

When to use this skill

  • A DDD pattern has been chosen (typically via ddd-implement) and the target language is Kotlin.
  • The user wants idiomatic code, not pseudocode.
  • A code review on Kotlin DDD code asks "what is the right Kotlin construct for this pattern?".

When NOT to use this skill

  • The target language is not Kotlin.
  • The user is still deciding the pattern — route to a ddd-core pattern skill first.
  • The user wants framework-specific scaffolding (Spring annotations, Arrow Either) — those are out of scope here and will live in future adapter plugins (ddd-kotlin-spring, ddd-kotlin-arrow).

Core content

The mapping. For each DDD pattern, the idiomatic Kotlin construct and the trade-off that motivates the choice.

Value object — wrap of a single primitive.

@JvmInline
value class CustomerId(val raw: UUID)

Use Kotlin's @JvmInline value class for zero-allocation typed IDs and other single-field wraps. Caveat: prior to Kotlin 1.9, value classes could not have an init {} block; for validated single-field wraps, use a data class or a private constructor with a validating companion factory.

Value object — composite, multi-field.

data class Money(val amount: BigDecimal, val currency: Currency) {
    init {
        require(amount.scale() <= currency.defaultFractionDigits) {
            "amount scale exceeds ${currency.defaultFractionDigits} for ${currency.currencyCode}"
        }
    }
    fun add(other: Money): Money {
        require(currency == other.currency) { "cannot add $currency and ${other.currency}" }
        return Money(amount + other.amount, currency)
    }
}

data class is the right choice — equal-by-attribute, immutable by default (use val), copy-on-modify via copy(). Put invariants in the init block.

Entity.

class Customer(val id: CustomerId, name: String) {
    var name: String = name
        private set

    fun rename(to: String) {
        require(to.isNotBlank())
        this.name = to
    }

    override fun equals(other: Any?) = other is Customer && other.id == id
    override fun hashCode() = id.hashCode()
}

A regular class, not data class. Override equals/hashCode to compare by identity (the id) only. data class would compare all fields, which makes two Customer instances with the same name (but different IDs) equal — wrong.

Aggregate root. An entity that exposes only commands. Internals stay private; queries return immutable views.

class Order(val id: OrderId, val customerId: CustomerId) {
    private val _items = mutableListOf<LineItem>()
    val items: List<LineItem> get() = _items.toList()

    fun addItem(productId: ProductId, quantity: Int) {
        check(items.none { it.productId == productId }) { "product already in order" }
        _items.add(LineItem(productId, quantity))
    }
}

Note customerId: CustomerId — a reference by ID to the Customer aggregate, not a Customer object reference.

Domain event.

sealed interface OrderEvent {
    data class Placed(val orderId: OrderId, val at: Instant) : OrderEvent
    data class Cancelled(val orderId: OrderId, val reason: String, val at: Instant) : OrderEvent
}

Past-tense names. sealed interface is preferred over sealed class for marker hierarchies; the variants are data classes because they are value objects.

Status / state machine.

sealed class OrderStatus {
    data object Draft : OrderStatus()
    data class Placed(val at: Instant) : OrderStatus()
    data object Cancelled : OrderStatus()
}

sealed enables exhaustive when. Use data object (Kotlin 1.9+) for stateless variants so toString and equals are sensible.

Result / fallible operation.

fun place(order: Order): Result<Order> = runCatching { /* domain logic */ }

Use kotlin.Result for now. (A future ddd-kotlin-arrow plugin would substitute Arrow's Either<DomainError, Order> with named error types.)

Invariants.

  • require(...) for constructor preconditions — throws IllegalArgumentException.
  • check(...) for state-invariant checks during operations — throws IllegalStateException.

For domain-specific exceptions, define your own: class OrderAlreadyPlacedException(...) : IllegalStateException(...).

Repository interface.

interface OrderRepository {
    fun save(order: Order)
    fun findById(id: OrderId): Order?
}

The interface lives in the domain module. Implementations live in an infrastructure module and are wired by the application bootstrap.

Factory — preferred form.

class Order private constructor(/* ... */) {
    companion object {
        fun place(customerId: CustomerId, items: List<LineItem>): Order { /* invariant checks, then return Order */ }
    }
}

Private constructor + a named companion factory expresses the domain verb (place) and prevents arbitrary callers from constructing invalid Order instances.

Decision heuristics

  • Use data class only when all properties participate in identity (value objects). Use a regular class with an overridden equals for entities so identity is by ID alone.
  • Prefer sealed interface over sealed class unless the hierarchy needs to share state.
  • For typed IDs and single-primitive wraps with no validation, prefer @JvmInline value class. Otherwise prefer data class.
  • Prefer immutability everywhere except inside an entity that owns mutable state — and even then, only mutate via methods that maintain invariants.

Anti-patterns

  • Using data class for entities — equality includes mutable fields, breaks identity semantics.
  • Putting JPA annotations (@Entity, @Column) on a domain entity that lives in a pure-domain module — couples the domain to the persistence framework.
  • Throwing bare IllegalArgumentException everywhere instead of defining domain-meaningful exceptions.
  • Abusing lateinit var to fake immutability — lateinit is a workaround for DI lifecycle, not a domain modeling tool.
  • Using JpaRepository<Order, UUID> as the domain repository — exposes every CRUD method and ties the domain to JPA.

See also

  • ddd-entity, ddd-value-object, ddd-aggregate, ddd-domain-event, ddd-repository, ddd-factory — the patterns this skill realizes.
  • ddd-implement — the entry-point that routes here for Kotlin code generation.

References

  • Kotlin language docs on data class, value class (@JvmInline), sealed class / sealed interface, and Result.
  • Evans, Domain-Driven Design (2003), Chs 5–6, for the underlying patterns.