DEV Community: Vadym Yaroshchuk

UI shouldn't think about validation

Vadym Yaroshchuk — Fri, 27 Feb 2026 14:14:40 +0000

I recently worked on abstracting the presentation layer from the UI layer. Ideally, the UI layer should be as dumb as possible when it comes to any non-UI logic. However, the presentation layer often suffers from a fundamental architectural flaw: it tries to decide what the UI should do.

This happens either directly (passing a specific error String to display) or indirectly (passing a string resource Int identifier). The latter creates a false sense of decoupling — the presentation layer is still dictating the exact screen output.

This approach breaks the Separation of Concerns (SoC). The solution is to provide enough contextual information for the UI to decide for itself how to display the error, without leaking presentation or domain logic.

My specific problem area was form input validation. I needed to show UI formatting errors (e.g., length limits) while keeping input validation strictly separated from domain invariants — a distinction many developers miss.

The initial solution in my head was simple: why not just provide enums?

data class TaskCreateState(  
    val name: Input<NameIssue>,  
    val description: Input<DescriptionIssue>,  
    val dueDate: Input<DueDateIssue>,  
    val tags: Input<TagsIssue>,  
    val capturedTags: List<String> = emptyList(),  
) : TaskComponent.State {  
    enum class NameIssue { BLANK, TOO_SHORT, TOO_LONG }  
    enum class DescriptionIssue { BLANK, TOO_SHORT, TOO_LONG }  
    enum class DueDateIssue { FORMAT, INEXISTING_DATETIME, IN_PAST }  
    enum class TagsIssue { TOO_MANY }  

    val hasAnyIssues: Boolean get() = listOf(name, description, dueDate, tags).hasAnyIssues  
}

Where input is:

@ConsistentCopyVisibility  
public data class Input<I> internal constructor(  
    val rawString: String,  
    val issues: List<I> = emptyList(),  
    val isValidated: Boolean = false,  
    private val validator: InputValidator<I>,  
) {  
    public fun validated(): Input<I> {  
        return copy(  
            issues = validator.validate(rawString),  
            isValidated = true,  
        )  
    }  
}  

public fun <I> input(  
    rawString: String = "",  
    validate: (String) -> List<I>  
): Input<I> = Input(  
    rawString = rawString,  
    issues = emptyList(),  
    isValidated = false,  
    validator = validate,  
)  

public fun <I> input(  
    rawString: String,  
    vararg issues: I,  
    validate: (String) -> List<I>  
): Input<I> = Input(  
    rawString = rawString,  
    issues = issues.asList(),  
    isValidated = true,  
    validator = validate  
)  

public val <I> Input<I>.hasAnyIssue: Boolean  
    get() = (if (isValidated) this else validated()).issues.isNotEmpty()  

public val List<Input<*>>.hasAnyIssues: Boolean  
    get() = any { it.hasAnyIssue }

public fun interface InputValidator<I> {  
    public fun validate(rawString: String): List<I>  
}

It looks clean, but iterating on this revealed a problem: if an enum simply says TOO_LONG, the UI still has to calculate the input size or fetch the max length from the domain to show a meaningful error message. It's not as dumb as I want it to be.

Enums weren't the solution. Instead, I migrated to sealed structures to represent validation errors. These data-rich issues give the UI enough context to render the error without forcing it to think or calculate:

class TaskNameValidator : InputValidator<TaskNameIssue> {  
    override fun validate(rawString: String): List<TaskNameIssue> {  
        if (rawString.isBlank()) return listOf(TaskNameIssue.Blank)  

        return when (TaskName.create(rawString)) {  
            TaskName.CreationResult.TooShort -> listOf(  
                TaskNameIssue.TooShort(  
                    minLength = TaskName.MIN_LENGTH,  
                    currentLength = rawString.length,  
                )  
            )  

            TaskName.CreationResult.TooLong -> listOf(  
                TaskNameIssue.TooLong(  
                    maxLength = TaskName.MAX_LENGTH,  
                    currentLength = rawString.length,  
                )  
            )  

            is TaskName.CreationResult.Success -> emptyList()  
        }  
    }  
}  

sealed interface TaskNameIssue {  
    data object Blank : TaskNameIssue  
    data class TooShort(val minLength: Int, val currentLength: Int) : TaskNameIssue  
    data class TooLong(val maxLength: Int, val currentLength: Int) : TaskNameIssue  
}

Now, the UI receives every detail it needs. I eliminated the "decision context hunt" in the UI layer, as it no longer needs to know the presentation layer's implementation details or domain constraints.

Another benefit of this approach is validator composition. I can use common validators across different screens, or compose them with screen-specific custom validators when business logic varies. Some might argue this involves code duplication, but strict SoC (both at the layer level and locally) is always worth the trade-off. Also, I don't think it's a big bottleneck in the era of AI (but, honestly, even without it, it doesn't take that much time).

Failures we don't model correctly

Vadym Yaroshchuk — Mon, 29 Dec 2025 11:15:16 +0000

Guards, validation, error handling — we all do it. We throw exceptions, return null, wrap values into Result, or trust the caller to "do the right thing". Most of the time, we don't even think about it — we follow familiar patterns and move on.

At the same time, there's a constant tension:

"Exceptions are bad"
"This should be exception-free"
"We must handle all errors explicitly"

But what does that actually mean?

Not every failure is an error. Not every exception is exceptional. And not every unsafe operation deserves to be wrapped just to feel safer. What we're really dealing with is something more fundamental: violations of contracts between parts of our program.

A function assumes something about its input. A caller assumes something about the outcome. IO assumes the world behaves. Sooner or later, those assumptions break.

Kotlin gives us many ways to express that "something": throwing, returning null, exposing unsafe operations, wrapping results, or forcing callers to acknowledge failure through types. None of these are universally right or wrong — but each of them communicates responsibility in a different way.

This article isn't about banning exceptions or worshipping types. It's about understanding what contract you're defining, who owns its violation, and how explicit your API should be.

What is a Contract?

Let's start with defining what do we mean by contract:

A contract is an agreement between a function and its caller that defines what inputs are allowed, what result is guaranteed if those inputs are valid, and what happens when those expectations are violated. It describes the assumptions a function makes, the promises it gives in return, and how failure is expressed when those assumptions do not hold.

We can divide contract into three main points:

Preconditions: What conditions caller must uphold before an invocation. For example, List<E>.first() from standard library expects you to check or be sure that List<E> contains at least one element.
Postconditions: What callee guarantees in return. Coming back to the previous example, List<E>.first() guarantees that on non-empty list it will return the first element in an array.
Failure semantics: What happens if contract is violated (function throws an exception, function returns null / type-safe result or just terminates the whole program).

Important thing to understand is that contract is not about validation like putting require(...) or check(...) in your code, rather the definition what is allowed, what is promised, and who is to blame when it goes wrong. You may sometimes not even have any validation (what is better to avoid; fail-fast is still a thing), but it doesn't make 'contract' as a thing magically disappear.

Types of contract violation

As this article most and foremost about handling contract violation, let's talk about different types of contract violations.

User Input

User input is the most obvious and most talked-about source of contract violations — and for a good reason. Users are not part of your program. They don't know your invariants, don't respect your constraints, and will happily provide input that violates every assumption your code could possibly make.

In this case, contract violations are expected, frequent, and non-exceptional. An empty field, an invalid email, a negative number where only positive values make sense — none of this is surprising. It's part of the normal control flow.
That's why user input is usually the place where we:

validate eagerly,
report errors explicitly,
and avoid throwing whenever possible.

Here, throwing an exception often means you lost control. The contract was violated, but the violation was predictable, and your API should reflect that reality. Returning a typed error, a validation result, or a failure value is usually the honest thing to do.

The important part is ownership: the caller owns the violation. The user broke the contract, not the system.

Programmer Error

Programmer errors live in a different reality. These are internal mistakes (logic bugs) that usually lead to exceptions. Unlike user input, which is expected to be invalid at times, programmer errors indicate something went wrong inside your program, and you typically don't handle them silently.

Suppose you have a function that sets the width of a view, and it throws if the width is negative:

fun setWidthPx(view: View, widthPx: Int) {
    require(widthPx >= 0) { "Width must be non-negative" }
    view.layoutParams = view.layoutParams.apply { this.width = widthPx }
}

Now, imagine a caller that calculates a width but forgets to handle an edge case:

val parentWidth = parent.measuredWidth
val padding = 20
val desiredWidth = parentWidth - padding * 2  // oops, parentWidth is smaller than padding * 2
setWidthPx(myView, desiredWidth) // 💥 throws: Width must be non-negative

The function is correct, the caller is "normal", but the contract is violated. This is a real programmer error, and it's not something your program should try to silently recover from — except by not making such mistakes in the first place.

Environmental failure

Environmental failures are a completely different beast. These come from things you don't control, like the file system, network, or hardware. Unlike programmer errors, no amount of perfect internal logic guarantees success. Even with flawless code, these operations can still fail — and that's why they need explicit handling.

And even so, that doesn't mean we should overcomplicate our code or pretend these failures don't exist. The goal isn't to wrap everything in layers of types or defensive checks — it's to handle the inevitable explicitly, clearly, and in the right place with right pace.

How to handle contract violations?

Now as we discussed types of contract violation, it's time to discuss the ways how we can at best mitigate risks that may break our code.

How is it handled in code we use?

Let's start with examples we see on day-to-day basis.

Standard library

kotlin-stdlib is something many developers take inspiration from when building their own APIs. And no wonder — it introduced a set of patterns that quietly shaped how we write Kotlin today.

Let's start with functions that throw exceptions on contract violation:

Firstly, let's start from those that throws exceptions in case of contract violation:

kotlin.Result<T>.getOrThrow() throws encapsulated Exception in case if the result was unsuccessful. You're expected to be absolutely sure about result by checking isSuccess() before calling.
String.toInt() throws NumberFormatException in case if string wasn't a valid number. You're expected to check the string beforehand, be sure about the input or use another variant of function that we're going to discuss below.
Iterable<Int>.max/min/first/last() that throws NoSuchElementException in case if given iterable didn't have any elements.

All of these APIs rely on your knowledge of the state you pass in. If that knowledge turns out to be wrong, they throw. Loudly and immediately.

But throwing isn't the only option. For most of these functions, the standard library also provides OrNull variants, explicitly signaling that failure is a possible and expected outcome:

Here, the contract is different: you don't know for sure, so the API forces you to deal with the absence of a value.

A slightly less talked-about pattern is OrElse, which pushes that responsibility even further to the call site:

val items = listOf("a", "b", "c")

val value = items.elementAtOrElse(5) { index ->
    "<missing at $index>"
}

Instead of throwing or returning null, the function asks you to define the fallback explicitly.

These three patterns — OrThrow, OrNull, and OrElse — form the backbone of the standard library's approach to contract violations. Kotlin doesn't force you into a single "correct" strategy. Instead, it gives you multiple ways to express how confident you are, who owns the failure, and how explicit you want your API to be.

kotlinx.coroutines

kotlinx.coroutines are not much different and it's also no wonder – they're made by Kotlin team as well.

We can see the same patterns, as well as some other:

Deferred<T>.getCompletionExceptionOrNull(): T? returns null if completion was not exceptional.
Deffered.getCompleted() throws IllegalStateException if Deffered<T> wasn't completed at the moment of call.
SendChannel.trySend(value: T): ChannelResult<T>
MutableSharedFlow.trySend(value: T): Boolean

As we can see, there's another pattern that prepends try to its regular counterpart — for example, trySend. In kotlinx.coroutines, this pattern exists to turn an exception-based contract into an explicit, value-based one.

The original function signals failure by throwing. The try* variant preserves the same operation, but returns a meaningful result instead, allowing the caller to handle failure without relying on exceptions or try/catch.

These are the main patterns you'll find across Kotlin's official libraries. The interesting part starts when you have to choose one.

That choice is rarely about personal taste or "exceptions vs types". It's about what kind of failure you're modeling, who owns it, and what the caller is expected to know or guarantee.

Is a failure part of normal control flow, or does it indicate a broken assumption?
Is the caller expected to recover, or is this a point where the program should stop pretending everything is fine?
Does this operation cross a system boundary, or does it stay entirely inside trusted code?

Answering these questions usually makes the pattern obvious: throwing, OrNull, OrElse, or try* stops being a stylistic choice and becomes part of the contract you're defining.

Reality

The real question isn't which patterns exist, but where you draw the line.

In practice, most codebases don't fail everywhere equally. They fail at boundaries.

User Input

User input is one such boundary. We expect invalid data, so throwing is usually the wrong signal. An "exception" there doesn't communicate a bug — it just means the user typed something weird. That's why APIs at this edge naturally gravitate toward type-safe results: they make failure explicit, expected, and local.

At this boundary, we should shift our focus from exception-first to safe-first:

@JvmInline
value class UserName private constructor(val rawString: String) {
    companion object {
        fun create(value: String): FactoryResult {
            return if (value.length !in 2..50) FactoryResult.InvalidLength else FactoryResult.Success(UserName(value))
        }
    }

    sealed interface FactoryResult {
        data object InvalidLength : FactoryResult
        data class Success(val value: UserName) : FactoryResult
    }
}

Which.. directly contradicts our previously established pattern. But is it bad?

Patterns like throwing exception by default and then having OrNull or try* are good — when they apply. The Kotlin standard library is a general-purpose library and designed without our context in mind. By breaking the pattern here we risk nothing: type-system guards us.

But does this mean that all input should be treated as equally unreliable everywhere and we should discourage patterns that were previously discussed? No.

A simple counterexample is the database. When data comes from the database, invalid values usually signal a bug rather than a typical user mistake. Since it was supposed to be validated beforehand.

That's why we often introduce an unsafe variant that intentionally bypasses unsafely our type-safe result:

@JvmInline
value class UserName private constructor(val rawString: String) {
    companion object {
        // ...
        fun createOrThrow(value: String): UserName {
            return if (value.length !in 2..50) throw IllegalArgumentException(...)
            else UserName(...)
        }
    }
    // ...
}

It still carries a familiar Kotlin Standard Library flavor, closely aligning with functions like Result<T>.getOrThrow(), which we call only when we are confident the result must be successful — and anything else would indicate a bug.

We don't make create throw, nor try* return a type-safe variant by default — we aren't a generic library like Kotlin Standard Library or kotlinx.coroutines that doesn't know its target usage. We know what we expect, and in our case — every extra variant is an extra choice — and by definition, every extra choice is an opportunity to misuse it. create is the primary function: it's what appears first in code completion, it's the first one developers reach for, and it sets the expectation of safe handling.

Internal Input

Even though most of the impact on our system comes from users, it doesn't mean we need to apply safe-first patterns everywhere or blindly wrap every system call with OrThrow. That would be overkill.

For data whose lifecycle is entirely owned by the system, it's perfectly fine to throw immediately on invalid values. If a contract is violated here, it's a bug — and we want to know about it as soon as possible. We don't need extra layers of safety for something we fully control. For example:

@JvmInline
value class ConfirmationAttempts(val rawInt: Int) {
    init {
        require(rawInt > 0) { "Confirmation attempts cannot be negative." }
    }
}

ConfirmationAttempts it's quite logical to know that confirmation attempts cannot be negative — its contract is well-established just by naming. You could technically wrap it in createOrThrow if you want, but I usually don't — because if every system-owned value is wrapped this way, the "attention signal" that OrThrow conveys gets lost — especially if everything that throws has such signal. It becomes background noise: effectively, it's the same as just putting a require in the init block, and no one notices it anymore.

This doesn't make the previously discussed patterns from standard library and kotlinx.coroutines obsolete. We use it for the same reason as these libraries do — when we're not sure at what boundary is it going to be used — is it a user input? Or is it a trusted boundary where mistakes are not supposed to happen?

The principle is simple: OrThrow is a way to consume result unsafely, not a default for marking throwable code.

Uncontrolled Input

Not all data comes neatly packaged as "user input" or "system-owned". Sometimes, we deal with sources that are neither fully trusted nor entirely under our control — external APIs or third-party services. These represent a gray area, where contracts exist but you can't guarantee on your side that everything will go according to the plan.

We basically treat it as a user input, but as we're rarely care what exactly went wrong (except logging, but propagated exception is more than enough), I usually introduce Result<T> in such cases:

class UserProfileRepository(
    private val cache: ConcurrentHashMap<Long, UserProfile>, // should be better caching, just an example
    private val database: UserProfileDao,
    private val networkClient: UserProfileApi,
    private val logger: Logger,
) {
    suspend fun getUserProfile(userId: Long): Result<UserProfile> {
        // 1. In-memory cache is trusted system state
        val cached = cache[userId]
        if (cached != null) return Result.success(cached)

        // 2. Database I/O is an Environmental Failure boundary
        val dbEntity = suspendRunCatching { 
            database.getById(userId) 
        }.getOrElse { return Result.failure(it) }

        if (dbEntity != null) {
            // Mapping is OUTSIDE the wrapper. If this fails, it's a Programmer Error.
            // And we don't want it to be swallowed.
            val profile = dbEntity.mapToDomain() 
            cache[userId] = profile
            return Result.success(profile)
        }

        // 3. Network I/O is the most common Environmental Failure boundary
        val response = suspendRunCatching { 
            networkClient.fetchUser(userId) 
        }.getOrElse { return Result.failure(it) }

        // Again, mapping is outside to ensure we don't hide bugs
        val profile = response.mapToDomain()

        // 4. Database Write (Best-effort Side-effect)
        // Persistence is a secondary concern. We wrap and log it so 
        // that a disk/DB failure doesn't deprive the user of a 
        // successfully fetched result.
        suspendRunCatching { 
            database.insert(profile) 
        }.onFailure { throwable ->
            logger.error("Failed to persist user profile to DB", throwable)
        }
        cache[userId] = profile

        return Result.success(profile)
    }
}

It is crucial to notice that we don't wrap the entire function in a single suspendRunCatching (a custom-made alternative function to runCatching that doesn't swallow CancellationException, preventing breakage of structured concurrency). Instead, we surgically wrap only the specific I/O boundaries where failure is an environmental reality.

The mapping logic (mapToDomain) is intentionally left outside. We don't expect our internal mapping to fail; if it does, it is a Programmer Error, not a runtime failure. By keeping it outside the wrapper, we ensure the app crashes immediately, allowing us to catch the bug rather than silencing it inside a Result.failure.

In addition, you might have seen how we handled the database insertion failure. We express that this error is not that critical; we can consider it an exception that does not signal an exceptional state, rather it is a degraded state of a non-critical side-effect. Since the primary contract (delivering the user profile) has already been fulfilled by the network fetch and mapping — a failure in the persistence layer is secondary. It is a best-effort operation where the transient state of the local disk should not be allowed to break the successful delivery of the primary result to the caller.

At the end of the day, you may also introduce the same pattern we apply for user input with sealed result — it depends on how much is it important to you to handle specifics of the failure. But logic of programmer errors remains.

False Safety

Catch.. less

Coming back to the example from the previous section — more specifically, the database — can we really say that every error thrown by an insertion or any other database operation is an environmental failure and not a programmer error?

As we established earlier with mapToDomain, we explicitly didn’t want to wrap everything into suspendRunCatching. The reason is simple: we don’t want to ignore errors that are not part of uncontrolled output.

A database can throw in very different scenarios:

For example, database may throw in different scenarios:

Environmental failures — temporary network issues, connection pool exhaustion, database restarts, timeouts. These are rare, but they do happen, and they're largely outside of your control.
Programmer errors caused by invalid schema or assumptions — missing indexes, violated constraints, incompatible column types, mismatched migrations, incorrect SQL. These indicate a broken contract inside your system, not an unstable environment.

Treating both categories the same way is where false safety starts creeping in.

Yes, we want our users not to see crashes caused by things they don't control — and often things we don't control either. But that doesn't mean we should silence failures blindly. Tools like detekt or ktlint warn you for a reason: being explicit about what you intentionally ignore is part of writing honest code.

The question is not "should this throw?", but rather "what exactly am I willing to silence here?"

Consider this simple function I recently implemented:

public suspend inline fun <reified T : Enum<T>> R2dbcTransaction.createEnumTypeIgnoring() {
    val enumName = T::class.simpleName?.lowercase() ?: error("Enum must have a name")
    val enumValues = enumValues<T>().joinToString(",") { "'${it.name}'" }

    try {
        exec("CREATE TYPE $enumName AS ENUM ($enumValues)")
    }  catch (_: Exception) {
        // postgresql does not support CREATE TYPE IF NOT EXISTS, so we want to ignore such errors;
    }
}

At first glance, this looks reasonable. But what's the flaw here?

We're catching far too broadly. By swallowing Exception, we're not just ignoring the "type already exists" case — we're also ignoring:

SQL syntax errors
permission issues
broken connections
misconfigured transactions
or even bugs introduced by future refactoring

A first improvement might look like this:

try {
    exec("CREATE TYPE $enumName AS ENUM ($enumValues)")
}  catch (e: R2dbcException) {
    // postgresql does not support CREATE TYPE IF NOT EXISTS, so we want to ignore such errors;
}

This is better, but still insufficient. We're now ignoring all database-level failures — including ones that absolutely should surface.

We can narrow it down further:

try {
    exec("CREATE TYPE $enumName AS ENUM ($enumValues)")
}  catch (e: R2dbcException) {
    // In PostgreSQL, SQLSTATE 42710 corresponds to duplicate_object.
    if (e.sqlState != "42710") {
            throw e
    }
}

Now the intent is explicit. We are not saying "database errors don't matter". We're saying "this very specific failure is expected and acceptable; everything else is not".

And it doesn't apply only to such "helper" functions — it applies everywhere.

Failure has destination

And while you usually don't want to leak exceptions like previously "broken connection" (especially it) outside your database layer (which is obviously might be neither ours or user's fault), this doesn't mean that every error should be caught everywhere they might occur.

Some failures are expected to occur, but that does not mean they should be handled everywhere they arise.

A broken connection, a transaction failure, or a driver error are part of the environment your code runs in. They are neither programmer errors nor conditions to be silently absorbed.

These failures must be allowed to propagate until they reach the boundary that owns the decision of what to do next. Catching them earlier doesn't make the system safer — it only hides the fact that something went wrong and shifts responsibility to the wrong place.

And that's why, in the createEnumTypeIgnoring example, we didn't wrap the entire function in a broad try/catch — on its own it means and does nothing. There, uncontrolled failures are allowed — and expected — to propagate. The function only silences the specific, understood case that is part of its contract (duplicate type), and lets everything else escape.

This is intentional. Error handling is not about preventing exceptions from being thrown; it's about choosing the boundary where they should be handled.

Catching an exception too early flattens context. Catching it too late leaks infrastructure details. The right place is usually a boundary that understands both sides: it knows what operation was attempted and what the caller can reasonably do next.

That's also why we don't also "propagate a logger" everywhere. Logging, like error handling, belongs to a boundary that has enough context to decide whether a failure is expected noise, a degraded state, or a real bug.

In short:

Some errors should throw.
Some errors should travel.
Very few errors should be caught "just in case".

The discipline is not in avoiding exceptions, but in letting them move until they reach the boundary that can give them meaning.

Bonus

By the way, do you still remember Deferred<T>.getCompletionExceptionOrNull(): T?? If you assumed it returns the completion exception or null otherwise — you were wrong. I was too. Until it threw an exception in real code.

Only after hitting a bug do you usually end up in the docs, where it says:

Returns completion exception result if this deferred was cancelled and has completed, null if it had completed normally, or throws IllegalStateException if this deferred value has not completed yet.

This function is designed to be used from invokeOnCompletion handlers, when there is an absolute certainty that the value is already complete. See also getCompleted.

Note: This is an experimental api. This function may be removed or renamed in the future.

This isn’t a misuse — it’s a poorly shaped API. The name, return type, and common conventions strongly suggest a safe query, yet the function hides a control-flow trap behind it.

The lesson isn’t "read the docs more carefully". The lesson is: don’t design APIs that violate established expectations — especially around errors.

The lesson for the kotlinx.coroutines maintainers is a hard one: which is more critical — labeling a function OrNull just because the return type is nullable (like we wouldn't know it from compiler..?), or warning the developer of a hidden IllegalStateException? By focusing on the null, the API obscures the danger. In an honest system, it has a few options:

it should not throw,
OrNull marker should be replaced with OrThrow. It would make sense if it would have any counterpart
at the very least, it shouldn't lie about its safety by having OrNull.

Final thoughts

OrThrow, OrElse, and try* are not about how failures are produced, but about how failure states are consumed.

Each variant represents a different way for the caller to deal with a violated contract. Which one is appropriate depends on the boundary you are operating at.

For trusted boundaries — such as system-owned code or data coming from a database that was already validated — exception-first is often more than acceptable choice. At these points, failure usually indicates a bug, not a recoverable situation, and throwing communicates that clearly.

For untrusted or ambiguous boundaries — like user input or external systems we don't control — safe-first APIs are more honest. Focusing on returning a type-safe-first result makes failure explicit and forces the caller to acknowledge it where input is unexpected. Unsafe variants like OrThrow may still exist, but they should be secondary and intentionally opt-in.

Most importantly, OrThrow should not be used as a marker that "this function can throw". Its purpose is to offer an alternative way to consume a failure state, not only to annotate danger. When overused, it loses its signaling value and becomes noise.

These patterns are tools, not rules. They work best when chosen deliberately, based on the contract you are defining, the boundary you are crossing, and who owns the failure. Use them thoughtfully — not out of habit, but out of intent.

Finally, remember the cost of false safety: blindly silencing errors or over-protecting every operation may hide real issues. Handle failures deliberately, at the boundaries you understand, and propagate exceptions where they belong — not everywhere, not nowhere.

Semantic Typing We Ignore

Vadym Yaroshchuk — Wed, 24 Dec 2025 12:41:06 +0000

In Kotlin, we constantly narrow our types. We prefer String over Any for text, Int over Any or even Number for integers. This feels obvious — almost trivial. Done, right?

So what is this article actually about?

While we subconsciously avoid Any in most situations — for good reasons, or sometimes simply because "why would I put Any here instead of Int?" — we often don't apply the same thinking when modeling our own software: its types, its behavior, and the relationships between them.

This article explores the practice of semantic typing — what it means, why you might want it, when it improves your code, and when it becomes a hindrance. We'll look at how semantic typing shows up in real Kotlin projects, both in application code and library design, and what tends to work well — or not.

Even if you're not following Domain-Driven Design, these ideas still apply. You already narrow types every day; this article is about doing it deliberately and thoughtfully.

We'll distill these lessons into practical rules to help you decide when to narrow types semantically — guided by reason, not intuition or habit.

What is semantic typing?

Let's start by defining what we're actually talking about, why it matters, and why it's not something you can just ignore.

Semantic typing is the practice of creating semantically meaningful subsets of general-purpose types to express intent and prevent accidental misuse. It's about shifting from structural types ("this is a string") to behavioral or semantic types ("this is a email").

The idea of semantic typing isn't unique to Kotlin — it has long been a common practice in languages like Java, where developers define lightweight wrapper classes (e.g. UserId, Email) around primitives to encode domain meaning and prevent accidental misuse.

For example:

@JvmInline
value class EmailAddress(val raw: String) {...}

It's worth mentioning that semantic typing isn't limited to wrapping primitives; it applies equally to wrapping any type — whether a simple Int or a complex Map<K, V>. The core idea is to give semantic meaning and stronger type safety by distinguishing values beyond their raw structure.

Why should you care? This is usually where skepticism appears. Whenever this approach comes up, the reactions often sounds like this:

What do I gain in return for this extra code? Isn't this just more boilerplate?

Those are completely valid questions — it makes you invest more time into thinking how to model your code and overall takes more time to write it. I'm all for following ideas of KISS and avoiding wrong abstractions problem.. and now onto a big BUT! 🌚

What you get in return is actually not an abstraction for its own sake — it's clarity. Let's look at what this means in practice.

Why?

Compile-time safety

Let's create an example:

/**
 * @param value The width in density-independent pixels. 
 */
fun setWidth(value: Int) { ... }

At first glance, this looks fine. But it's easy to accidentally swap the measurement unit when calling it:

val containerSize = 1000 // random int or just raw pixels value
card.setWidth(containerSize) // dp was expected

Code successfully compiles and even may seem valid, but there's lying a big bug that you can't validate inside a function.

By narrowing types, we make invalid calls impossible at compile time. For example, we can introduce semantic type Dp

@JvmInline
value class Dp(public val raw: Int) {...}

/**
 * @param value The width in density-independent pixels. 
 */
fun setWidth(value: Dp) { ... }

Now when the value argument is passed, we make sure that the call-site is well-aware of measurement unit we expect.

Documentation

I'm not the only one who's occasionally too lazy to check or write documentation, right? But don't blame me — like a wise man once said (Robert C. Martin, in Clean Code):

The proper use of comments is to compensate for our failure to express ourself in code. Note that I used the word failure. I meant it. Comments are always failures. We must have them because we cannot always figure out how to express ourselves without them, but their use is not a cause for celebration. So when you find yourself in a position where you need to write a comment, think it through and see whether there isn’t some way to turn the tables and express yourself in code.

Semantic typing doesn't just let you wrap a value in a class — it lets you document the type itself. You convey exactly what kind of data it expects, without repeating that information in every function that uses it. Self-documenting code, done right.

Coming back to our example:

/**
 * @param value The width in density-independent pixels. 
 */
fun setWidth(value: Dp) { ... }

You might find the documentation a little funny — as if you could just pass something else instead of Dp. But besides making that comment almost obsolete, we also eliminate another problem: documentation duplication.

Think about it: if we have setWidth, we probably also have setHeight, setSpacing, and similar functions. Without semantic typing, the same documentation gets copied everywhere — or worse, it's incomplete, missing or outdated entirely somewhere, because somebody was lazy or simply forgot. Then anyone reading the code has to guess the expected input based on other parts of the code they might not even be calling. With a narrowed type, that guesswork disappears — you just reuse the type where it's semantically appropriate.

But there's more. Beyond "wrapping" data, you need to consider identity and semantics. You're not just slapping a random name on it, like the one GitHub suggested for your repo, you're giving it real meaning. A type should stand alone, without requiring extra context, so you don't end up with something like this:

fun setWidth(dp: Int) { ... }
// vs
fun setWidth(dp: Size) { ... }

Where you're trying to express the unit of measurement through parameter naming. And documenting function instead don't do better job either. Who forces you or me to check the parameter name? What if after a long day of work I falsely assumed that it accepts raw pixels?

Even in the second example, you could still mess up the units, effectively making it another Int, but just wrapped and with a little less flaws (we guarded it from being just a random Int to a random Size). And the old Int version? Totally generic — it tells us something and nothing at the same time. semantic typing should and forces the code to say what it means, loud and clear. That what makes it powerful and self-documentable.

Validation

Another benefit of introducing semantic typing — is validation. We're circling back to self-documentation, but this time the focus is on reuse.

In our previous examples, every function had to validate density-independent pixels individually to fail fast (hopefully we were doing it, right?) and avoid hidden bugs:

fun setWidth(dp: Int) {
    require(dp < 0) { "dp cannot be negative" }
    // ...
}

fun setHeight(dp: Int) {
    require(dp < 0) { "dp cannot be negative" }
    // ...
}
// ...

Now we can move that logic into the type itself, making it a true subset type, just as we defined earlier:

@JvmInline
value class Dp(public val raw: Int) {
    init {
        require(dp < 0) { "dp cannot be negative" }
    }
}

Notice how this eliminates repeated validation, guarantees correctness everywhere, and clearly documents the intended constraints.

Note
You can, of course, introduce more robust validation to be more type-safe depending on where and how it's used; Since this article is most and foremost about Semantic Typing rather than Validation, you can read about validation separately here. 😄

We could have actually merged Documentation and Validation into one section — but I kept them separate deliberately. Why? Because some validation challenges are more subtle, and using a semantic type highlights them perfectly.

Take a real-world example we hinted at in the introduction:

@JvmInline
value class EmailAddress(val raw: String) {...}

Email validation has always been a headache. Different parts of a system may enforce different rules, often without anyone noticing. One function might just check that the string contains @. Another might use a simplified StackOverflow regex. A third might try to implement the full RFC standard.

The result? Three functions that semantically expect the same input may behave differently: one accepts a string, others reject it. Bugs like this are subtle, hard to catch, and annoying to debug.

By narrowing it to a semantic type, you centralize the constraint:

Any EmailAddress instance is guaranteed to be valid according to your rules. And they remain the same.
Consumers of the type don't need to repeat validation.
The compiler enforces that only valid data flows through your system.

Validation + self-documentation + compile-time safety: this is the power of semantic typing in practice.

When to use it?

With the examples in mind we may proceed to create a rule when we should actually use semantic typing and when most likely not.

Depending on your project or application-level code requirements, it may differ, but not too much. We definitely don't want to over-engineer!

Application code

Let's start with what Kotlin focuses on first — application-level code. Usually, in our projects we apply architecture patterns such as Clean Architecture, Domain-Driven Design, and sometimes even Hexagonal Architecture. All of them share a common layer — the domain — which derives in some form from DDD (check my article if you're not familiar with it: Digging Deep to Find the Right Balance Between DDD, Clean and Hexagonal Architectures).

In the context of domain layers, we typically enforce business rules, constraints, and overall core business logic, isolated from infrastructure or application concerns. Since domains are intended to reflect the language of domain experts, it's usually beneficial to introduce semantic typing, and more specifically, Value Objects.

Let's take an example — a User aggregate:

data class User(
    val id: Int,
    val email: String,
    val name: String,
    val bio: String,
)

To enforce business rules and constraints, you could go down a couple of paths. Let's start with the opposite of semantic typing, just to see what can go wrong:

data class User(
    val id: Int,
    val email: String,
    val name: String,
    val bio: String?,
) {
    init {
        require(id >= 0)
        require(email.matches(emailRegex))
        require(name.length in 2..50)
        require(bio == null || bio.length in 0..500)
    }
}

This is not an invalid approach, but let's reason about what can go wrong or feel suboptimal here.

Duplication is one obvious problem. It's common to see multiple representations of the same entity (in this case, User) with the same properties, which forces you to duplicate validation:

data class PublicUser(
    val id: Int,
    val name: String,
    val bio: String
) {
    init {
        require(id >= 0)
        require(name.length in 2..50)
        require(bio == null || bio.length in 0..500)
    }
}

Here, User contains full information for the owner, while PublicUser is returned to everyone else without the email. Aside from feeling unease of duplication, the rules and constraints tend to change over time, making this decentralized approach fragile and prone to being forgotten.

The solution? Introduce Value Objects with semantic typing. Each property becomes a type that encodes its constraints, centralizing validation and making your domain model self-documenting:

@JvmInline
value class UserId(val rawInt: Int) {
    init { require(raw >= 0) }
} 

@JvmInline
value class Email(val rawString: String) {
    init { require(raw.matches(emailRegex)) }
}

@JvmInline
value class UserName(val rawString: String) {
    init { require(raw.length in 2..50) }
}

@JvmInline
value class Bio(val rawString: String) {
    init { require(raw.length in 0..500) }
}

data class User(
    val id: UserId,
    val email: Email,
    val name: UserName,
    val bio: Bio?,
)

With this approach, validation is centralized, duplication disappears, and your domain objects become self-explanatory and safer by design. Each property now carries semantic meaning, and any changes to rules need to be made only in the Value Object itself, not scattered across multiple classes.

Let's also consider a more complex structure instead of just wrapping primitives. Imagine we have two bounded contexts (features):

One is responsible for the shopping cart,
The other is responsible for payments.

Both features share the same underlying data — selected products — but the business rules differ. For the shopping cart, it's valid to have an empty cart while the user is still selecting products. For the payment feature, however, it's crucial that the cart is not empty — the user must arrive with at least one selected product:

data class PaymentCart(
    val userId: Int,
    val products: List<Product>
) {
    init {
        require(userId >= 0)
        require(products.isNotEmpty()) // must not be empty for payment
    }
}

Meanwhile, you might have something like this instead:

@JvmInline
value class ProductSelection(val raw: List<Product>) {
    // can be something more robust with factory pattern and type-safe result for outer layer, as it's part of user input
    init { require(raw.isNotEmpty()) } // enforces non-empty list
}

data class PaymentCart(
    val userId: Int,
    val products: ProductSelection
)

Now, the type itself guarantees the constraint: you cannot construct a ProductSelection with an empty list, eliminating the risk of forgetting validation if we have, for example, more than one aggregate, like PaymentCart and Bill.

We can also give ProductSelection additional behavior. For instance, if certain campaigns restrict delivery costs depending on the products purchased:

@JvmInline
value class ProductSelection(val raw: List<Product>) {
    init { require(raw.isNotEmpty()) }

    val specialProducts: List<Product>
        get() = raw.filter { /* some filtering logic */ }
}

data class PaymentCart(
    val userId: Int,
    val products: ProductSelection
) {
    val deliveryCosts: Money
        get() = if (products.specialProducts.size >= 3) Money.ZERO else /* normal cost */
}

While you could technically implement this logic inside the aggregate itself, localizing responsibilities in the Value Object (semantic type) simplifies the code, makes the API more explicit, and keeps the aggregate focused on core domain logic. And why should it apply only to code in the domain layer?

Library code

Even though library code is often an additional component of any application — meaning it doesn't always follow the strict rules, conventions, or approaches typical of application code (aside from generic best practices) — I would still strongly recommend using the same approach to narrow your types almost everywhere.

Application code is usually written with the goal of minimizing upfront cost. This means that while it can be worthwhile to apply strict modeling in specific parts (like the domain layer) to reduce future testing and maintenance overhead, maintaining the same strict model everywhere often seems unnecessary or excessive. However, in my opinion, libraries don't fall under this "cost-saving" rationale.

Consider the following example:

@Serializable
sealed interface JsonRpcResponse<T> {
    val jsonrpc: JsonRpcVersion
    val id: JsonRpcRequestId

    data class Success<T>(
        val jsonrpc: JsonRpcVersion,
        val id: JsonRpcRequestId,
        val result: T,
    ) : JsonRpcResponse<T>

    data class Error(
        val jsonrpc: JsonRpcVersion,
        val id: JsonRpcRequestId,
        val error: JsonRpcResponseError,
    )
}

@Serializable
@JvmInline
value class JsonRpcVersion(val string: String) {
    companion object {
        val V2_0 = JsonRpcVersion("2.0")
    }
}

@Serializable
@JvmInline
value class JsonRpcRequestId(val jsonElement: JsonElement) {
    init {
        require(jsonElement is JsonNull || jsonElement is JsonPrimitive) {
            "JSON-RPC ID must be a primitive or null"
        }
        
        if (jsonElement is JsonPrimitive) {
            require(jsonElement.isString || jsonElement.intOrNull != null || jsonElement.longOrNull != null || jsonElement.doubleOrNull != null) {
                "JSON-RPC ID must be a string or number"
            }
        }
    }
    
    val isString: Boolean get() = jsonElement is JsonPrimitive && jsonElement.isString
    // ... other
    val asString: String? get() = if (isString) (jsonElement as JsonPrimitive).content else null
    // ... other
}

// ... other classes in the same way

As we can see, we put semantic types almost everywhere! Let's reason about it:

JsonRpcRequestId is associated with the one that should be presented in the initial request, meaning that it beneficiary for both library code (less error-prone due to human factor). In addition it represents a real concept derived from the specification.
JsonRpcVersion is also reused, but it's not that common to be used and overall the reasoning is different — it first of all represents the concept and makes type self-explanatory by referencing to the JsonRpc Spec. The code that validate it now knows that they accept JsonRpcVersion and not something else.

At the end, I would say that for most cases it's most likely that you need to define semantic types to draw clear boundaries for yours and others sake, but with exceptions about which we are going to talk about later on.

Real-world examples

Now let's hop onto real-world examples to see where we apply this technique, to reason about them and extend our context.

Standard library

Take Thread.sleep():

Thread.sleep(5) // five what? milliseconds? seconds? who knows

The measurement unit is not explicit. You're forced to guess and to know it, and manually convert if you:

Thread.sleep(5 * 60_000) // now it's five minutes, maybe

Some developers might wrap it in a java.time.Duration and convert to milliseconds in place, while others just write raw numbers and multiply it. Nothing forces consistency. Every developer writes what they feel is right, and the code becomes unconventional, almost random. One mistake in conversion, and the behavior silently breaks. And code complexity? It goes rough.

Semantic typing solves this problem elegantly. For example, with Kotlin's Duration type and well-designed API:

suspend fun delay(duration: Duration) {...}

suspend fun foo() {
    delay(5.minutes)
}

Much easier to read, isn't it?

Android Views vs Jetpack Compose

In classic Android Views, setting sizes often looks like this:

val view = ImageView(context)

view.layoutParams = ViewGroup.LayoutParams(200, 300) // what are these numbers? px or dp?

view.layoutParams = ViewGroup.LayoutParams(
    ViewGroup.LayoutParams.MATCH_PARENT,
    ViewGroup.LayoutParams.WRAP_CONTENT
)

The first problem is that, at first glance and without reading documentation, you cannot reason about the input parameters of layoutParams — is that 200 in pixels? dp? Who knows? Sure, in the Android Framework most people are aware of it, thanks to rich documentation and common ecosystem knowledge. But if you're building your own library or application, you don't get the same safety net. Your code probably isn't well-documented, and people rarely memorize internal details. This leads to false assumptions, subtle bugs, and frustrating debugging sessions. Also, remember what once a wise man said?

The second problem is that, just by looking at the ImageView class, you have no idea that these constants exist or that they belong specifically to ViewGroup.LayoutParams. Even though ImageView don't even extend that class, you're expected to know the "magic" behind MATCH_PARENT and WRAP_CONTENT. For any newcomer, this is a nightmare — code that's technically correct but completely opaque.

Now look at Jetpack Compose:

Box(
    modifier = Modifier
        .width(200.dp)
        .height(300.dp)
        .fillMaxWidth()
) {...}

Compose solves the same problem through semantic typing:

Dp wraps raw numbers, preventing accidental misuse.
Intrinsic sizes like fillMaxWidth() are typed functions, not magic numbers.
The compiler enforces correctness — no more guessing about units or constants.

The difference is striking: Compose pushes correctness into the type system, making code self-documenting, safer, and easier to reason about, while classic Views rely on conventions and mental checks.

This is a perfect real-world illustration of why semantic typing matters: it reduces mental overhead, prevents misuse, and communicates intent directly through the types.

When not to use it?

Think of semantic typing in context of value objects from DDD – as first and foremost real-world concepts. In most cases — whether you're building an application or a library — the types you define should represent things that exist or make sense in the world your software models. Most values we work with do correspond to such real-life concepts. However, it's easy to get carried away and start modeling rules instead of ideas — which leads to types that clutter your codebase rather than clarify it.

Modeling inputs

Let's start with something simple.

Take PositiveNumber. At first glance, it might seem useful: it enforces a constraint and could be reused in many places. But is it a concept? Not really.

You may say:

But why bother? Didn't you say that it's an advantage of semantic typing — that I can centralize validation? Isn't that exactly what variable names are for? If I name it price: PositiveNumber or distance: PositiveNumber, doesn't that clarify everything?

It might — for a moment. But naming alone isn't enough in practice:

Naming doesn't travel. Once the value leaves the scope where it was created, the meaning is often lost. You can't rely on every developer — across every file, layer, or feature — to maintain that clarity.
People reuse types for convenience. If PositiveNumber works, someone will use it for price, distance, item count, or whatever else they find that fits. And once a type is reused generically, its original intent disappears. You don't want to create such a "generic" trend, otherwise what's the point of introducing a semantic type?
Reviews and onboarding suffer. When the same type is used for many things, it gets harder to reason about code, harder to trace bugs, and harder for newcomers to understand what a value actually represents.
Bugs creep in silently. You might never notice that someone accidentally passed a "length in kilometers" where "price in euros" was expected — because the type PositiveNumber accepts both.

So the problem isn't that names are bad — it's that they're too easy to misunderstand, too easy to misuse, and too easy to forget. If something means price, make it a Price. That meaning should survive refactors, boundaries, and time. Thus, the simplest reason to avoid it, is because it's too genetic. In reality, Validation is just a handy outcome and not the reason to introduce semantic typing.

You may take a natural language as a reference and think whether you would express your thoughts to a stranger in the way how you phrase your semantic type. But, honestly, because it's too subjective, for me it was not a fit for a rule.

Therefore we can come up with more intuitive and more explicit rule:

Type constraints should not drive your semantic type in any sense – in naming or in existence.

But what if PositiveNumber was in mathematical context?

It may seem that PositiveNumber can still help with preventing mistakes in our code, for example in context of mathematic operation that uses division:

fun sqrt(x: PositiveNumber): Double

At first glance, this looks neat — you're encoding the domain rule "no negatives allowed" right into the type in the context that "allow" such concept.

But is it a valid concept within such domain? I would maybe say "yes", but would most definitely avoid it subconsciously. Why?

The meaning in such case depends on the operation, not the input. Take this:

fun sqrt(x: PositiveNumber): Foo

The operation (sqrt) is what defines the constraint — that the input must be non-negative. The input itself, as a number, does not inherently carry that meaning. Without the operation context, the PositiveNumber type is just a number with a constraint — but what does it really mean on its own?

On top of that, many people casually associate "positive number" with "non-negative", forgetting that zero is not positive nor negative, nor both at the same time. This subtle confusion can lead to seemingly logical code that is actually incorrect. Conceptually, look at these two operations:

@JvmInline
value class PositiveNumber(val value: Double) {
    init {
        require(value > 0) { "Value must be strictly positive" }
    }
}

fun sqrt(x: PositiveNumber): Foo
fun ln(x: PositiveNumber): Foo

Now imagine trying to call these functions:

val zero = PositiveNumber(0.0) // ❌ throws IllegalArgumentException
sqrt(zero) // ❌ fails, but mathematically sqrt(0) is valid
ln(PositiveNumber(1.0)) // ✅ works

Both functions appear to operate on "positive numbers", but the precise constraints differ: sqrt accepts zero (non-negative), whereas ln requires strictly positive values. If you try to reuse a single PositiveNumber type for both, one of the operations will either reject valid input or allow invalid input. Semantic typing must respect the operation context, not just the nominal value.

While the example is really specific, it should give you a great example of possible problems of misusing too general types, making it a reason not to introduce them.

And original problem? You've pushed the constraint to the input, but in practice, it's the operation that defines the constraint. You could instead say:

fun sqrt(a: Double): Double {
    // it would also be more than okay to have here just a guard
    require(a >= 0)
    // ...
}
fun sqrtOrNull(a: Double): Double? {
    if (a > 0) {...}
    return null
}

fun ln(a: Double): Double {
    require(a > 0)
    // ...
}
fun lnOrNull(a: Double): Double? {
    if (a > 0) {...}
    return null
}

Prefer duplication over a wrong abstraction for cases where you can't come up with a real-world concept.

Thus I would make even more explicit rule:

Operation constraints should not drive your semantic type in any sense – in naming or in existence. If you can't come up with reasonable name without mentioning constraint that would fit this rule – you most definitely don't need a "semantic type".

Another thing to mention is that we may, for example, have a Dp class that represents density-independent pixels and still have restrictions defined by operation (usage context):

fun setDividerHeight(value: Dp) {
    require(value != Dp.ZERO)
    // ...
}

Introducing some kind of DividerHeightDp with such condition is overkill and basically falls under PositiveNumber problem.

But you may say:

But what if we allow PositiveNumber just because it enforces a helpful constraint and I don't have any ambiguity in my code for it?

And that's maybe great! But in reality where do we draw the line?

Why stop there?

Why not also have NegativeNumber?
NonZeroNumber?
NonEmptyList, OneElementList, AtLeastThreeItemsList?
ShortString, UppercaseString?

I am absolutely sure that at least some of given options you would not like to see in your code, but without a clear rule it's easy to fall to some extent for that.

And once you go down this path, any rule becomes a candidate for a semantic type — and that's the problem. You're no longer modeling concepts — you're modeling conditions. And conditions are not identities.

At that point, you're not designing a rich domain model. You're building a constraint-validation library shaped like your domain. And that's a completely different goal — one that introduces more complexity than clarity.

Thus, let's come up with the reasonable rule without relying on any of ours "internal feelings":

If the semantic type cannot stand alone as a meaningful concept without its underlying type, it is likely a bad semantic type.

That's also why introducing DividerHeight(value: Dp) instead of DividerHeightDp(value: Int) – is a bad idea. It will just be unwrapped every time, creating a lot of unnecessary boilerplate in our code.

Modeling outputs

We've spent enough time talking about semantic typing for inputs — types that wrap data going into our domain. But what about the opposite direction? Can semantic types also be useful for modeling outputs?

Let's consider the following example:

val textContents: FileTextContents

Why it's bad? First of all it tells the source! But wait.. why is this a problem?

Let's add similar variants to understand this problem more:

FileTextContents
HttpTextContents
UserInputTextContents
..where do we stop?

It's perfectly fine to have the following:

@JvmInline
value class FileSize(private val bytesAmount: Long) {
    val bytes: Long get() = bytesAmount
    val kilobytes: Long get() = ...
    // ...
}

class File (...) {
    // ...

    val size: FileSize get() = ...

    // ...
}

This example isn't really about telling the source of data, but rather about a functional concept in its own right — file size. The idea of FileSize represents an actual concept: an amount of bytes named according to our domain. Whether it came from a file, a memory buffer, or a network stream — its meaning remains the same. FileSize reflects a concept that stands on its own.

Thus, naming it like DownloadedFileSize makes no sense. Ask yourself:

Does the source of this string truly matter to the business logic?

Introducing something like this might feel "descriptive", but in reality, you're hardwiring context that doesn't belong to the core concept. You're taking a neutral, reusable concept — like "text" or "size" — and narrowing its scope unnecessarily. This creates fragmentation, confusion, and needless ceremony in the API of converting one into another for no reason. And I have a feeling that we don't like mapping one into another 🌚

Name your concept narrowly enough to be understood at a glance, but without exaggeration.

Conclusion

Semantic typing, and value objects in particular, are powerful tools for pushing intent, validation and domain meaning into types. Use them when a concept is part of your domain language, when invariants must be centralized, or when an API boundary needs clearer intent. Avoid them when the constraint is defined by an operation rather than the concept itself, or when a type would be overly generic and thus lose meaning. Establish simple team rules so the benefits scale without creating unnecessary ceremony.

Package naming nobody cares about (but should)

Vadym Yaroshchuk — Mon, 15 Sep 2025 09:56:54 +0000

Package naming and organization are fundamental aspects of writing maintainable code. How we choose to group files and modules impacts not only readability but also the ease of navigation and future development.

In this article, we'll briefly explore how packages are used, trying to create some rules and give some reasoning about when it's a bad idea to create a separate package and when it's not.

What is a Package, Really?

A package is one of the first concepts you encounter right after writing your basic "Hello World" program in Java or Kotlin. The simplest and yet misleading way to describe it is just as a folder structure used to organize code and prevent naming conflicts.

And while it's partially true, it might give you the wrong perspective on when to actually use it. But let's stick to some kind of definition:

Package name in Kotlin and Java is a namespace used to organize a set of related types (classes, interfaces, enums, etc.) into a cohesive unit. It serves a dual purpose: providing logical structure to a codebase and preventing naming conflicts in large-scale applications or when integrating third-party libraries.

Taking into account our previous "simple" explanation, it's true that packages help us avoid naming conflicts, since it's rare for class names to be 100% unique.

Packages as Folders

Despite the benefits that packages provide, there's a significant downside: due to how packages are implemented in Java and Kotlin — and how IDEs handle them — they don't fully serve as true namespaces, even though they ideally should. For this reason, we tend to name our classes in a way that is expressive enough on its own, without needing to rely on the package name. For example:

UserAnalyticsReport
OrderRepository
UserFileStorageService

Even though these classes may be placed in distinct logical packages, like:

com.example.user.UserAnalyticsReport
com.example.order.OrderRepository
com.example.user.UserFileStorageService

which theoretically could provide differentiation if we could write something like:

import com.example.user

val report = user::AnalyticsReport(...)

Unfortunately (and fortunately), we're not in C++ (which isn't necessarily a good or a bad thing). Since most people rely on IDEs' auto-importing and auto-completion features, they rarely deal directly with packages and therefore often don't put much thought into package structure.

This approach can lead to a flawed mindset when designing your own package structure — you start thinking in terms of grouping files rather than defining meaningful namespaces and boundaries, leading to unclear responsibilities. The result is often a directory full of classes, organized by location rather than purpose.

Even though it makes you feel good about things being "organized", it usually leads to a lot of problems. This is the wrong mental model.

Packages as Namespaces

A better mental model is to think of packages as semantic boundaries — they tell you what part of the system you're looking at and, ideally, what that code is responsible for.

But let's be honest: most people treat packages as mere folders, often because they're intimidated by the number of files within a package. This "drawer" mentality keeps us from thinking deeper about why we group code the way we do. I struggled with this mindset myself for a long time.

When you start treating packages as true namespaces, several beneficial things happen:

The package itself becomes part of the documentation — just by looking at where a class lives, you get a sense of what it does and what it's responsible for.
Related functionality naturally stays together, while unrelated code stays apart. It also makes you think more about "what is it responsible for?"/"Who is the owner of this particular class/function"?

Beyond that, many common software design headaches simply vanish. One of the biggest culprits in large codebases is the overuse or misapplication of generic "category" packages, such as model, dto, or entity.

For example, consider a large project where multiple teams work on user-related features. You might see packages like:

com.example.user.model.profile  
com.example.user.profile.model  
com.example.user.utils.profile  
com.example.user.profile.utils  
com.example.user.dto.profile  
com.example.user.profile.dto

(It's even more feasible in multi-modular projects, especially when multiple teams involved)!

Here, the "profile" concept is scattered across multiple packages and subpackages, often with duplicated or reversed naming orders. Sometimes "profile" isn't even a standalone domain concept but just a part of the user aggregate — yet it's treated as its own package to reduce the number of files in user.model. Teams unintentionally recreate the same logical groupings multiple times because they don't realize an equivalent package already exists somewhere else. This often results in inconsistent package naming based on personal preference rather than clear conventions, which makes onboarding new team members more difficult and slows down the process. Never to be asked again, “Why is it not here, but here?”.

While this example is simplified, you will inevitably encounter this issue in real projects — especially if you maintain a library where backward compatibility across versions is critical. In such cases, inconsistent or unclear package structures can introduce long-term maintenance headaches and increase the risk of breaking changes.

This situation quickly devolves into a maze where:

You spend more time guessing where something might live rather than understanding what it does.
Terminology becomes inconsistent across teams — some call certain classes "models", others call the same or similar concepts "entities" or "DTOs".
You get tangled in redundant or conflicting packages like user.utils.profile vs user.profile.utils, with no clear ownership or responsibility.

In such cases, generic package names like utils, model, or dto become meaningless labels. Instead of helping you find code based on its responsibility, they force you to rely purely on terminology — and since different people or teams often use these terms differently, this vocabulary can change or conflict over time. This makes understanding the codebase more dependent on mastering a shifting and ambiguous glossary rather than on intuitive architectural boundaries.

By contrast, when packages represent responsibility rather than just file categories or vague groupings, the codebase becomes more navigable, easier to understand, and more resilient to team or terminology changes.

What deserves a namespace?

While it's relatively easy to reason about not creating a .model, .util, .impl, and so on, there is a big elephant in the room that remains unanswered — how to determine what deserves and what does not deserve a namespace?

Let's create an example:

com.example.user  
 ├─ User.kt  
 ├─ UserId.kt  
 ├─ UserFactory.kt  
 ├─ settings  
 │   ├─ UserSettings.kt  
 │   ├─ NotificationPreferences.kt  
 │   └─ PrivacyOptions.kt  
 ├─ profile  
 │   ├─ UserProfile.kt  
 │   ├─ ProfilePicture.kt  
 │   └─ Bio.kt  
 ├─ security  
 │   ├─ Password.kt  
 │   ├─ SecurityQuestions.kt  
 │   └─ TwoFactorAuth.kt  
 └─ utils  
     ├─ UserValidators.kt  
     └─ UserMappers.kt

For the sake of simplicity, we will avoid mentioning any layering in our structure.

While collapsing all folders might make the structure look clean and minimal, it often turns into a long, meandering chain of subpackages with no clear purpose. Take profile for example — it may appear as a cohesive, independent unit, but we should pause and ask ourselves:

Does .profile make any sense without a user concept?
Does the actual usage of entities within .profile make sense outside the user package (for example, is it only wrapped inside another class and managed by)? (mappers don't count 😁)
Does this package provide a meaningful black box with its own API, used by more than just user? Or is it something that only makes sense inside User — for example, a UserProfile that never exists independently, is always unwrapped from User, and cannot be accessed without it?
If I have to change something in this group of classes, will I usually change the others too?

If any of the answers are yes → they most likely belong together in the same package.

If all are no → maybe it deserves its own package.

`.common` / `.core` packages

Another edge case that I think is worth mentioning is the .common / .core packages, which I personally see frequently in codebases. While they seem handy at first, for the most part, their underlying meaning is literally "this is stuff that doesn't fit anywhere else". Thus does not really represent a cohesive concept or a clear boundary.

The question is simple — why introduce com.example.common if it should either be localized to the meaningful place or just be put inside com.example? It's another example of "drawer" mentality, resulting in the situation where, over time, every team member will toss unrelated code there without any thought. And soon the package becomes a grab-bag of everything and nothing at the same time.

As more and more unrelated code gets dumped there, it turns into the most depended-on part of the system, creating hidden coupling everywhere. That in turn makes refactoring dangerous, since moving anything out feels risky when you’re unsure who relies on it. Over time, the result is architectural erosion: instead of well-defined boundaries, the system gravitates around a bloated God-package at its center.

Bonus way of thinking

As an additional way of thinking about it, you can consider an "Aggregate" from DDD as a mental model for identifying a coherent concept that deserves its own namespace. The idea is that a package should represent something that has meaning and utility on its own to the outside world.

Value objects, domain entities, and events often don't qualify for separate packages because they exist solely to support the aggregate — they have no independent meaning outside of it. Splitting them into their own packages would violate the principle of exposing a clear API to the outside and would create artificial boundaries where nothing makes sense in isolation.

Everything inside the aggregate is highly coupled, and that coupling is exactly why it belongs together in the same package: it communicates that these elements only have significance in the context of the aggregate.

This approach ensures packages remain meaningful units of organization, rather than arbitrary folders that obscure the system's true structure.

Namespacing on macro level

Until now, we’ve focused on packages at the micro level, like inside a domain. But what about layers themselves — domain, infrastructure, presentation?

On this level, packages signal architectural boundaries and obviously brings a lot of benefits. domain holds core business logic, presentation deals with APIs or UI, and infrastructure wraps technical details like databases or messaging. Importantly, even, for example, infrastructure often contains self-sufficient logic and types to access its logic (ideally), making it a cohesive unit in its own right. The key is that each layer still groups meaningful units rather than acting as a dumping ground. Done right, macro-level namespaces give developers a quick mental map of the system and make dependencies on layers explicit.

Thus, we can see it as a positive thing rather than a meaningless technical label — these boundaries are, for the most part, self-sufficient.

Naming a namespace (package)

Now that we’ve covered when to create a package, let's talk about how to name it. A package should be named after the concept it represents, not the number of things inside it.

For example, if your code is built around managing a single Order — its validation, lifecycle, and operations — naming the package orders is misleading. Plural implies a collection, which doesn't reflect the fact that the package is about the Order concept itself. The correct choice is order, which communicates that this namespace is about the domain concept, not a list of orders.

Similarly, don’t name packages errors, events, or notifications just because they contain multiple items of that type. The question to ask is: what concept or responsibility does this package capture? Name it after that concept, not the quantity of instances it holds. This keeps your package names precise, meaningful, and aligned with the mental model of your system.

Can a package name ever be plural? Sure. But in practice, it’s far less common than people assume. Most of the time, the package represents a single concept, not a collection, so as a default, we go with singular.

Make the correct focus

It’s not enough to just create meaningful namespaces — the focus of those namespaces matters just as much.

Consider two structures:

com.example.domain   
 └─ user  
     └─ User.kt

vs:

com.example.user   
 └─ domain  
     └─ User.kt

Both look valid, but they communicate very different priorities. The first (com.example.domain.user) puts the technical layer first and center. The second (com.example.user.domain) keeps the spotlight on the concept — user — with the layer being secondary.

This difference becomes important as the system grows. Not every concept or feature will even have a .domain, or a .presentation (for example, authorization most likely does not have a business logic, therefore, does not deserve a .domain), or whatever layer you expect. That means navigation quickly becomes awkward: you can’t tell what a feature does or contains, only that it might sit somewhere under a technical label. The result is uneven hierarchies and folders that feel bloated with layers, while the actual business concepts get buried.

Modules show the same pattern. At a small scale, having :domain:user and :domain:task might look fine. But once you add :application:auth, :application:user, :application:task (while :domain:auth doesn’t exist) navigation becomes strange. You can’t immediately tell the actual capability of a feature or bounded context: does auth even have domain logic, or is it just application code? The structure pushes technical boundaries first, while leaving the conceptual boundaries unclear.

A concept-first approach — com.example.user.domain, com.example.order.infrastructure — avoids this problem. You always start with the thing the business cares about, and only then refine by the layer.

Does it have a domain or infrastructure layer? That doesn’t matter — what matters is the concept itself, and only then how it’s implemented internally. This is especially important because the structure is likely to change over time. And what do you do then?

Conclusion

Let's summarise the main points, starting with the micro level:

First of all, my recommendation would be not to go by 'when not to create a package' path, but by 'when to create', meaning that we don't create a separate package by default. Unless we have a strong reason.
It's justified to have a separate package if we want isolation, for example, when we talk about layered architecture. It's also justified when the package is actually an independent cohesive unit that has an independent meaning.
We definitely don't create packages like utils/ext(ensions)/helpers/ impl and alike.
We don't create packages that do not represent themselves in the general context.

At the macro level, it’s perfectly fine to have packages like domain or infrastructure that reflect the architectural layer you’re working in. In addition, set your priorities correctly — concept is first, then a layer you're operating on.

Finally, use singular names by default, unless the concept itself is inherently plural, like news.

Here is example of the structure just for your reference:

com.example
 ├─ user
 │   ├─ domain
 │   │   ├─ User.kt
 │   │   ├─ UserId.kt
 │   │   └─ UserName.kt
 │   ├─ application
 │   │   ├─ UserService.kt / SomeUseCase.kt
 │   │   └─ UserRepository.kt
 │   └─ infrastructure
 │       ├─ database
 │       │   └─ UserDataSource.kt
 │       └─ adapter
 │           └─ UserRepositoryImpl.kt
 │       └─ messaging
 │           └─ UserEventsPublisher.kt
 ├─ order
 │   ├─ domain
 │   └─ ...

Overall, you may apply these rules to other languages outside JVM-ecosystem, such as TypeScript with its modules systems or anything else that has namespacing as a concept.

More than 5 files within a directory ain't that scary, fellas!

Finding the Right Balance Between DDD, Clean and Hexagonal Architectures

Vadym Yaroshchuk — Sat, 21 Sep 2024 18:16:04 +0000

Choosing the right software architecture is challenging, especially when balancing theory and recommendations from the internet with practical implementation. In this article, I will share my journey and the architectural choices that have worked for me.

Although the title might suggest I’m here to tell you exactly how to structure your application, that’s not my goal. Instead, I’ll focus on my personal experiences, choices, and the reasoning behind the approaches I’ve taken when building my apps. This doesn't mean you should structure things the same way, but since many of my friends have asked me about it, I thought I’d try to explain the architecture we use in TimeMates (P.S: personal project that I make with my mates; upd: it's almost 2026 and it's still not finished :D).

Smart terminology

You're probably already aware of certain terms like Clean Architecture, DDD (domain-driven design), or maybe even Hexagonal Architecture. Perhaps you've read a lot of articles about it all. But as for me, I saw a few problems in most of them – too much theoretical information and little practical information. They might give you small and non-real examples where everything works perfectly, but it never worked for me and never gave me good answers, only increased boilerplate.

Some of them are almost the same or include each other for the most part and do not conflict with each other in most cases, but many people stop at the specific approach not thinking that it's not the end of the world.

We'll try to learn the most valuable information from different approaches I take inspiration from, apart from how I particularly build my apps at first. Then we'll come to, particularly my thoughts and implementation. Let's start from the same place most people do while developing Android apps:

Clean Architecture

Clean architecture sounds pretty simple – you have specific layers that do only a specific job that should be done only at the specific layer (too much specific I know). Google recommends the following structure, though does not name it "clean" but "modern":

presentation
domain (optional in Google's opinion)
data

The presentation layer is responsible for your UI, and ideally, its only role is to communicate between the user (who interacts with the UI) and the domain model. The domain layer handles business logic, while the data layer deals with low-level operations like reading and writing to a database.

Sounds simple, right? However, within this structure lies a big question: According to Google's recommended architecture for apps, why is the domain layer optional? Where is the business logic supposed to go then?

This idea comes from Google's stance that the domain layer can be skipped in certain cases. In simpler applications, you might find examples where the business logic is placed in the ViewModel (part of the presentation layer). So, what’s the problem with this approach?

The issue lies in the MVVM/MVI/MVP patterns and the role of the presentation layer. The presentation layer should only handle the integration with platform details and UI-related tasks. In this context, it’s crucial to keep the presentation layer — whether it's using MVVM or any other pattern — free of business logic. The only logic it should contain is related to platform-specific requirements.

Why? In Clean Architecture, each layer has a specific responsibility to ensure separation of concerns and maintainable code. The presentation layer's job is to interact with the user through the UI and manage platform-related operations like rendering views or handling input. It’s not meant to contain business logic because that belongs to the domain layer, where the core rules and decision-making are centralized.

The concept is to separate platform-specific considerations in the presentation layer, making it possible to change or adjust the user interface or platform without impacting the business rules and other code. For instance, if you wanted to transition from an Android to an iOS app, you would only need to rework the UI, while preserving the domain logic, which is particularly beneficial in the context of Kotlin. 😋

Most of the misunderstanding comes from not understanding what business logic is, where it should be located, and the nature of certain examples.

So, to address other issues, let's talk more about the domain layer, specifically about DDD:

Domain-driven Design

Domain-driven design (DDD) revolves around structuring the application to reflect the core business domain. But simply – what code should be written and in what way?

You surely already know about Repositories or UseCases and some of you might think that UseCases are part of it. But the most important part is not UseCases or Repositories (I overall consider them not a part of a domain), but domain objects around which your domain logic lives.

Domain objects in the DDD realm are essential objects that reflect the business problem you're addressing. They are not just regular DTOs or POJOs as commonly used in many beginner projects. Instead, in DDD, domain objects encapsulate both data and behavior (that includes, for example, validation). They are designed to represent real-world concepts and processes, and they embody the rules and logic that govern those concepts. But what is the simple advice that comes from it?

There are 3 types of domain objects within DDD, so let's talk about them.

Value objects

A value object is an immutable domain concept that has no identity of its own.

It never exists independently — it only makes sense as part of something larger, usually an entity or an aggregate.

Value objects can range from:

a simple wrapper around a single value
to a richer structure composed of multiple fields

As long as they are immutable and identity-less, they qualify.

Identity, identity.. but what does it truly mean? In practice, it means that two value objects are considered the same if their data is the same. There is no external identifier to compare — only the values they contain.

In Kotlin, this maps naturally to a data class, where equality is derived from all properties:

data class Money(
    val amount: BigDecimal,
    val currency: Currency,
) {
    operator fun minus(other: Money) {...}
    // other functionality
}

Here, Money(10, EUR) is indistinguishable from another Money(10, EUR).

There is no concept of "which one" — only "what value".

Another powerful use of value objects is semantic typing — replacing raw primitives with meaningful domain types:

@JvmInline
public value class EmailAddress private constructor(public val rawString: String) {
    public companion object {
        public val LENGTH_RANGE: IntRange = 5..200

        public val EMAIL_PATTERN: Regex = Regex(
            buildString {
                append("[a-zA-Z0-9\\+\\.\\_\\%\\-\\+]{1,256}")
                append("\\@")
                append("[a-zA-Z0-9][a-zA-Z0-9\\-]{0,64}")
                append("(")
                append("\\.")
                append("[a-zA-Z0-9][a-zA-Z0-9\\-]{0,25}")
                append(")+")
            }
        )

        public fun create(value: String): Result<EmailAddress> {
            return when {
                value.size !in LENGTH_RANGE -> Result.failure(...)
                !value.matches(EMAIL_PATTERN) -> Result.failure(...)
                else -> EmailAddress(value)
            }
        }
    }
}

You can read more about semantic typing in my article — Semantic Typing We Ignore.

In short, my general advice would be to avoid using raw types such as String, Int, Long, etc. directly in your domain model (Boolean is often the only reasonable exception).

Instead, introduce semantic value objects that:

are self-documenting
encapsulate validation
localize domain logic
centralize terminology
decouple the domain from accidental representations

But what if my business object has a stable identity? That's where domain entities comes into play.

Domain entities

A domain entity represents a business concept that has a stable identity over time.

Unlike value objects, an entity is not defined by its attributes, but by who it is. Its properties may change, but its identity must remain the same.

An example of it can be, for example, UserProfile:

class UserProfile(
    val id: UserProfileId,
    val displayName: DisplayName,
    val email: EmailAddress,
) {
    fun changeDisplayName(
        newDisplayName: DisplayName,
    ): UserProfile =
        UserProfile(
            id = id,
            displayName = newDisplayName,
            email = email,        
        )

    fun changeEmail(
        newEmail: EmailAddress,
    ): UserProfile =
        UserProfile(
            id = id,
            displayName = displayName,
            email = newEmail,
        )
}

No matter whether we change the email or the display name, the user is still the same. The identity of the entity does not depend on its attributes — it is anchored in the id, which remains constant even as other properties evolve. This makes it clear that an entity is about who it is, not what it currently has.

Even though this version of UserProfile is immutable, it still preserves its identity through the id. Each "change" produces a new instance, representing the same entity at a different point in time.

In Classic DDD entities are mutable, and many implementations rely on this for convenience. I prefer keeping my code immutable whenever possible, because it makes reasoning about state, testing, and concurrency much safer, while still respecting the core DDD principle that an entity is defined by its stable identity rather than its attributes.

And onto our "composer" — Aggregate.

Aggregate

In DDD, an aggregate is a cluster of domain objects — usually entities and value objects — that are treated as a single consistency boundary. The aggregate ensures that the rules and invariants of the domain are upheld whenever its internal state changes.

An invariant is a business rule that must always hold true for an entity or aggregate. While value objects can enforce rules for their own data (for example, an EmailAddress ensures it has a valid format), an aggregate can enforce higher-level rules that involve multiple entities or value objects together. In other words, the data might be valid individually, but not consistent in the context of the aggregate.

class User private constructor(
    val id: UserId,
    val profile: UserProfile,
    val isAdmin: Boolean,
) {

    companion object {
        // enforce invariant at creation
        fun create(
            id: UserId,
            profile: UserProfile,
            isAdmin: Boolean
        ): UserCreationResult {
            if (isAdmin && !profile.email.value.contains("@business_email.com"))
                return UserCreationResult.InvalidAdminEmail

            return UserCreationResult.Success(
                User(id, profile, isAdmin)
            )
        }
    }

    // command within the aggregate
    fun promoteToAdmin(newEmail: EmailAddress? = null): UserPromotionResult {
        val email = newEmail ?: profile.email
        val updatedProfile = profile.changeEmail(email)

        if (!updatedProfile.email.value.contains("@business_email.com"))
            return UserPromotionResult.InvalidAdminEmail

        return UserPromotionResult.Success(
            User(
                id = id,
                profile = updatedProfile,
                isAdmin = true,
            )
        )
    }
}

sealed interface UserCreationResult {
    data class Success(val user: User) : UserCreationResult
    object InvalidAdminEmail : UserCreationResult
}

sealed interface UserPromotionResult {
    data class Success(val user: User) : UserPromotionResult
    object InvalidAdminEmail : UserPromotionResult
}

In this example, all creation and state changes go through type-safe factories and commands, ensuring that invariants are never bypassed. It's very important that our domain maintains consistency and data stay valid throughout its entire lifecycle.

The sealed result types make it explicit and self-documentable which outcomes are possible, allowing the compiler to enforce handling of both success and failure cases. Instantiation of User directly is prevented by the private constructor, so every instance must pass through the validation logic in create or promoteToAdmin.

Aggregates themselves also have boundaries we need to respect. You can’t just embed one aggregate inside another, because each aggregate is responsible for its own invariants and consistency rules. For example, a Team aggregate can’t hold User aggregates directly; it only keeps references to their IDs.

class Team private constructor(
    val id: TeamId,
    val name: TeamName,
    val memberIds: Set<UserId> // references to User aggregates by ID
) {
    companion object {
        fun create(
            id: TeamId,
            name: TeamName,
            memberIds: Set<UserId>
        ): Team {
            // can be more robust validation
            require(memberIds.isNotEmpty()) { "Team must have at least one member" }
            return Team(id, name, memberIds)
        }
    }

    fun addMember(userId: UserId): Team =
        Team(id, name, memberIds + userId)

    fun removeMember(userId: UserId): Team =
        Team(id, name, memberIds - userId)
}

This keeps the rules clear: Team enforces its own invariants, while User enforces its own, and they interact safely through IDs rather than mixing their internal states. It’s like giving each aggregate its own workspace — they can collaborate, but never step on each other’s toes.

Apart from Aggregates, Domain entities and Value objects, sometimes you might see the domain layer's service classes. They're used for the logic that usually cannot be put on the aggregates, but still a kind of business one. For example:

class ShippingService {
    fun calculatePrice(
        order: Order, 
        shippingAddress: ShippingAddress, 
        shippingOption: ShippingOption,
    ): Price {
        return if (order.product.country == shippingAddress.country)
            order.price
        else order.price + someFee
    }
}

We won't discuss the usefulness or effectiveness of domain-level services or aggregators at this point. Just keep it in mind until we come to the point where we'll combine these approaches into one piece.

But it's pretty much everything – the implementation may vary from project to project, and the only thing I use as a rule for anything – is immutability whenever possible.

Problems

Anemic Domain Entities

The Anemic Domain Model is a common anti-pattern in Domain-Driven Design (DDD) where the domain objects — entities and value objects — are reduced to passive data containers that lack behavior and only contain getters and setters (if it applies) for their properties. This model is considered "anemic" because it fails to encapsulate the business logic that is supposed to live within the domain itself. Instead, this logic is often pushed into separate service classes, which leads to several problems in the overall design.

To understand this problem more, what particularly is bad about Anemic Domain Entities? Let's review:

Possible complexity while understanding what domain entity is capable of: When logic is spread across controllers or UseCases, it's harder to track the responsibilities of the entity, slowing down understanding and debugging (also, take into account that apart from IDE it's hard to look up the business logic that you put on some kind of controllers or UseCases, it makes code review much harder).
Encapsulation is broken: Entities hold only data without behavior, pushing the business logic into services, making the structure harder to maintain. It means that you should align logic across the UseCases/Controllers/so on and make sure that business logic is actually changed to the right one.
Harder to test: When behavior is scattered, testing individual features gets harder because logic isn’t grouped inside the entity itself.
Repetition of logic: Business rules often get repeated across services/usecases, leading to unnecessary repetition and higher maintenance costs.

An example of a bad business entity:

sealed interface TimerState : State<TimerEvent> {
    override val alive: Duration
    override val publishTime: UnixTime

    data class Paused(
        override val publishTime: UnixTime,
        override val alive: Duration = 15.minutes,
    ) : TimerState {
        override val key: State.Key<*> get() = Key

        companion object Key : State.Key<Paused>
    }

    data class ConfirmationWaiting(
        override val publishTime: UnixTime,
        override val alive: Duration,
    ) : TimerState {
        override val key: State.Key<*> get() = Key

        companion object Key : State.Key<ConfirmationWaiting>
    }

    data class Inactive(
        override val publishTime: UnixTime,
    ) : TimerState {
        override val alive: Duration = Duration.INFINITE

        override val key: State.Key<*> get() = Key

        companion object Key : State.Key<Inactive>
    }

    data class Running(
        override val publishTime: UnixTime,
        override val alive: Duration,
    ) : TimerState {
        override val key: State.Key<*> get() = Key

        companion object Key : State.Key<Running>
    }

    data class Rest(
        override val publishTime: UnixTime,
        override val alive: Duration,
    ) : TimerState {
        override val key: State.Key<*> get() = Key

        companion object Key : State.Key<Rest>
    }
}

These are simply containers with data about TimeMates states. The question is: how can we transform this anemic domain entity into a rich one?

In this case, for states, I had a different controller that was handling all transitions and events:

class TimersStateMachine(
    timers: TimersRepository,
    sessions: TimerSessionRepository,
    storage: StateStorage<TimerId, TimerState, TimerEvent>,
    timeProvider: TimeProvider,
    coroutineScope: CoroutineScope,
) : StateMachine<TimerId, TimerEvent, TimerState> by stateMachineController({
    initial { TimerState.Inactive(timeProvider.provide()) }

    state(TimerState.Inactive, TimerState.Paused, TimerState.Rest) {
        onEvent { timerId, state, event ->
            // ...
        }

        onTimeout { timerId, state ->
            // ...
        }
    // ...
}

Besides its good look, it violates the DDD principles – domain object should represent not only data but also behavior. The entity should be like this:

sealed interface TimerState : State<TimerEvent> {
    override val alive: Duration
    override val publishTime: UnixTime

    // Now business entity can react to events by itself;
    // This functions are 'aggregates' from DDD;
    fun onEvent(event: TimerEvent, settings: TimerSettings): TimerState
    fun onTimeout(
        settings: TimerSettings, 
        currentTime: UnixTime,
    ): TimerState

    data class Paused(
        override val publishTime: UnixTime,
        override val alive: Duration = 15.minutes,
    ) : TimerState {
        override val key: State.Key<*> get() = Key

        companion object Key : State.Key<Paused>

        override fun onEvent(
            event: TimerEvent, 
            settings: TimerSettings,
        ): TimerState {
            return when (event) {
                TimerEvent.Start -> if (settings.isConfirmationRequired) {
                    TimerState.ConfirmationWaiting(publishTime, 30.seconds)
                } else {
                    TimerState.Running(publishTime, settings.workTime)
                }

                else -> this
            }
        }

        override fun onTimeout(
            settings: TimerSettings, 
            currentTime: UnixTime,
        ): TimerState {
            return Inactive(currentTime)
        }
    }

    // ...
}

Note: Sometimes some logic is put into UseCases and it might be less obvious than in this particular case.

By looking at such an entity you understand faster what it does, how it reacts to the domain events, and other things that may happen.

But, as for business objects, sometimes you may feel that it does not have any behavior that you may add/move to them. Here's my example of such an object:

data class User(
    val id: UserId,
    val name: UserName,
    val emailAddress: EmailAddress?,
    val description: UserDescription?,
    val avatar: Avatar?,
) {
    data class Patch(
        val name: UserName? = null,
        val description: UserDescription? = null,
        val avatar: Avatar?,
    )
}

Interesting note: It's an actual code from my user's domain with such a problem.

The potential problem is that User and Patch are data containers without business logic. First of all, I use Patch only at the UseCases, which means that it should be put where it's needed. Use this rule for everything – declaration without usage on the layer which defines it, means that you do something wrong.

As for User, there's no need to create aggregate functions – Kotlin's auto-generated copy method is more than enough as value-objects are already validated and there's no custom logic for that for the entire entity.

To learn more about this problem, you may reference, for example, this article.

I'd add that you should try to avoid anemic domain entities, but at the same time do not force yourself to – if there is nothing to aggregate, do not add aggregates. Don't invent a behavior if there's nothing to be added – KISS still applies.

Ignoring Ubiquitous Language

Ubiquitous Language, a key concept in DDD, is often ignored. The domain model and code should use the same language as the business stakeholders to reduce misunderstandings. Failing to align the code with the language of the domain experts results in a disconnect between the business logic and the actual implementation.

In simple terms, names should be easy to understand even for non-programmers. This is especially helpful for large projects involving multiple teams with varying knowledge, skills, and responsibilities.

That's something small to follow, but very important. I'd add that the same concepts shouldn't have different names across different domains – it's confusing even within one team.

Now, let's move on to another approach I'm using in my projects – Hexagonal Architecture:

Hexagonal Architecture

Hexagonal Architecture, also known as Ports and Adapters, takes a different angle on structuring applications compared to traditional approaches. It's all about isolating the core domain logic from external systems — so that the core business logic isn't dependent on frameworks, databases, or other infrastructure concerns. This approach promotes testability and maintainability, and it aligns well with DDD in that the focus remains on the business logic.

There're two types of Ports – Inbound and Outbound.

Inbound ports are about defining the operations that the outside world can perform on the core domain.

Outbound ports are about defining the services that the domain needs from the outside world.

The difference between DDD and Hexagonal architecture in isolation strategy is conceptually the same, but the second one takes it to the next level. Hexagonal Architecture defines how you should communicate with your domain model.

So, for example, if you need to access an external service or feature to do something in your domain, you do the following:

interface GetCurrentUserPort {
    suspend fun execute(): Result<User>
}

class TransferMoneyUseCase(
    private val balanceRepository: BalanceRepository,
    private val getCurrentUser: GetCurrentUserPort
) {
    suspend fun execute(): ... {
        val currentUser = getCurrentUser.execute()
        val availableAmount = balanceRepository.getCurrentBalance(user.id)
        // ... transfer logic
    }

    // ...
}

UseCases are typically considered inbound ports since they represent operations or interactions initiated by the external world. However, the naming and implementation may vary.

In my projects, I prefer not to introduce another terminology and usually I just create an interface of Repository that I need from outside:

interface UserRepository {
    suspend fun getCurrentUser(): Result<User>
    // ... other methods
}

I consolidate everything into a single repository to avoid unnecessary class creation, providing a clearer abstraction for most people familiar with the concept of a repository.

It may not always be the case that you need to call a repository from another feature or system. Sometimes, you may want to call a different business logic that handles what you need (what can be much better), known as UseCases. In this scenario, it's common to have a distinct interface from the first example.

Here's the visualization:

Note: By the way, the other terminology for 'feature' is the 'bounded context' from the DDD. They pretty much mean the same.

The example of defining and using ports that follows the schema above:

// FEATURE «A»

// Outbound port to get the user from another feature (bounded context)
interface GetUserPort {
    fun getUserById(userId: UserId): User
}

class TransferMoneyUseCase(private val getUserPort: GetUserPort) : TransferService {
    override suspend fun transfer(
        val userId: UserId, val amount: USDAmount
    ): Boolean {
        val user = getUserPort.getUserById(request.userId)
        if (user.balance >= request.amount) {
            println("Transferring ${request.amount} to ${user.name}")
            return true
        }
        println("Insufficient balance for ${user.name}")
        return false
    }
}

Implementation of ports is done through Adapters – they're basically just linkage that implements your interface to work with an external system. The naming of such layer may vary – from simple data or integration to straightforward adapters. They are pretty interchangeable and up to specific project naming conventions. This layer usually implements other domains and uses other Ports to achieve what it needs.

Here's example of GetUserPort implementation:

// UserService is the Service from another feature (B)
// Adapters are usually in separate module because they're dependent on
// another domain, to avoid straight coupling.
class GetUserAdapter(private val getUserUseCase: GetUserUseCase) : GetUserPort {
    override fun getUserById(userId: String): User? {
        return userService.findUserById(userId)
    }
}

So, features are only coupled at the data/adapters level. The advantage of it is that your domain logic remains unchanged no matter what happens to the external system. That's another reason why the domain's ports actually shouldn't comply with everything that the external system wants – it's the Adapter's responsibility to deal with it. By that, I mean that, for example, the function signature might be different from the one that is used in the external system as long as it makes it possible to play around, of course.

Another thing is that it's important to consider how to handle domain types. Features are rarely completely isolated from other types of features. For instance, if we have a business object called User and a value object UserId, we often need to reuse the user's ID to store information related to the user. This creates a need to find a way to reuse this type in different parts of the system.

In an ideal Hexagonal architecture, different domains should exist independently. This means that each domain should have its specific definitions of the types they use. In simpler terms, it requires you to redeclare these types every time you need them.

It creates a lot of duplication, boilerplate while converting each type between separate domains, problems with validation (especially if requirements change over time, you might overlook something), and just a great pain in any developer's life.

The advice is that you shouldn't follow all of those rules as long as you don't see the benefit. Look for a happy medium while dealing with it, how I dealt with that we will discuss in the following part.

Problems

Incorrect mental model

As for mistakes I see the most – developers don't understand that the Domain & Application layers is not just about a physical division, but about the correct mental model. Let me explain:

Mental model is a conceptual representation of the work or structure of various parts of the system that interact with each other (simply, how the code is perceived by those who use it). It differs from a physical model in that a physical model involves physical interaction - for example, calling a specific function or implementing a module, i.e. anything that is done by hand.

A common issue in software design is allowing the domain/application layer to be aware of data storage or sourcing, which violates the separation of concerns principle. The domain's focus should remain on business logic, independent of data sources. However, you might encounter examples like LocalUsersRepository or RemoteUsersRepository, and corresponding use cases such as GetCachedUserUseCase or GetRemoteUserUseCase in application layer (in case if repositories put in domain, I usually put them in place where I use them — in application layer, but problem remains). While this may solve a specific problem, it violates the domain's mental model, which should remain agnostic to the source of the data.

The same applies to the DAOs in the context of frameworks like androidx.room. They're not only violating the rule of saying about the data source, but in addition, violate the rule of independence of any frameworks.

Your repositories/usecases should stay away from the source of data, even though it might seem to be okay in situations when implementation is not directly in the domain/application layer.

My implementation

After finishing the explanation of the approaches that I use, I'd like to proceed to my actual implementation and how I dealt with reducing unnecessary boilerplate and abstractions.

Let's start by defining the key ideas of each approach we discussed:

Clean Architecture: divide your code into different layers by their responsibility (domain, data, presentation)
Domain-driven Design: The domain should contain only a business logic, all types should be consistent and valid across all of its lifecycle.
Hexagonal Architecture: Strict rules about accessing Domain and from Domain.

They perfectly match each other for the most part, which makes it a key to writing good code.

The structure of TimeMates features (different domains) is following:

domain
data (Implements everything that is related to storage or network management, including submodules with DataSources)
- database (integration with SQLDelight, auto-generated DataSources)
- network (actually, I don't have it in TimeMates, because it's replaced with TimeMates SDK, but if it is not, I would add it)
dependencies (Integration layer with Koin)
presentation (UI with Compose and MVI)

I like this structure so far, but you might want to distinguish the UI from ViewModels to be able to use different UI frameworks per platform, I am not planning to, so I leave it as it is. But if I face such a challenge in the future, it's not hard for me as I am not dependent on the Compose in the ViewModels.

The main problem I experienced was the boilerplate that I had while implementing Hexagonal Architecture – I copied and pasted types that made me wonder 'Do I need it much'? So, I came up with the following rules:

I have common core types that are reused among different systems, it's a kind of combined domain of most needed types.
The type can be only common if it's used among most of the domains, has a problem with duplication of the validation, and is not a complex structure (sometimes there are exceptions, but usually there are not a lot) at all.

What do I mean under 'complex structure'? Usually, your domain that demands another domain's type, don't actually need everything that's described in the given type. For example, you might want to share 'User' type, among with its value objects, but for the most part, other domains do not need all from User type and might want, for example, only name and the id. I am trying to avoid such situations and even if something is already in the core domain types, I would rather create distinct type with information that my certain domain need. But as for validation, I share almost all semantic value objects.

You may extend this idea for bigger projects by creating not just common core types, but types for specific areas where some group of your subdomains (bounded contexts) works.

To sum up, I am reusing value objects that have the same validation rules in one common module; I am trying not to make my common core types module too big with everything. There should be always a happy medium.

In addition, in my projects I don't have 'Inbound Ports' as term in my projects. I replace them fully with UseCases:

class GetTimersUseCase(
    private val timers: TimersRepository,
    private val fsm: TimersStateMachine,
) {
    suspend fun execute(
        auth: Authorized<TimersScope.Read>,
        pageToken: PageToken?,
        pageSize: PageSize,
    ): Result {
        val infos = timers.getTimersInformation(
            auth.userId, pageToken, pageSize,
        )

        val ids = infos.map(TimersRepository.TimerInformation::id)
        val states = ids.map { id -> fsm.getCurrentState(id) }

        return Result.Success(
            infos.mapIndexed { index, information ->
                information.toTimer(
                    states.value[index]
                )
            },
        )
    }

    sealed interface Result {
        data class Success(
            val page: Page<Timer>,
        ) : Result
    }
}

Note: it's an example from the TimeMates Backend

It does not violate Hexagonal Architecture or DDD which makes it a good way to define how the external world accesses your domain. It has the same meaning and behavior as an inbound port.

As for outbound ports, I made the same as I provided earlier in examples.

Conclusion

In my projects, I prefer to keep things practical. While theory and abstraction are useful, they can overcomplicate simple things. That’s why I combine the strengths of Clean Architecture, DDD, and Hexagonal Architecture without being overly strict about following them to the letter. Use critical thinking to determine what you actually need and why it benefits your project, rather than blindly following recommendations.

Bonus

If you liked the article, I suggest you checking my other socials, where I share my thoughts, articles, and overall updates:

Kotlin Multiplatform is now stable – What's the Impact?

Vadym Yaroshchuk — Wed, 01 Nov 2023 21:35:13 +0000

In the latest Kotlin release, version 1.9.20, a significant milestone has been achieved with the stabilization of Kotlin Multiplatform technology. This marks a pivotal moment in Kotlin's development, as Multiplatform support has transitioned from its beta phase, which began in version 1.7.20, to a stable and reliable feature in the Kotlin ecosystem.

For those who doesn't know what is Kotlin Multiplatform, I will explain it in brief:

❓ Explanation
Kotlin Multiplatform – is Kotlin technologies that leverages language ability to be compiled in different environments and languages, such as JVM (+Android), Web (via JavaScript or WebAssembly; in addition WASM can be used for other targets within its technology) and Native (iOS through Objective-C and Desktop using C++). Using it, you can write common and reusable code between different platforms only using Kotlin.

Game changer

Now that it's stable, let's highlight its advantages:

Easier to sell: When technology reaches such state, it's much easier to push it towards your managers and overall business to use this technology that was not that reliable before.
Stable API: Stable APIs guarantee consistent performance, easing developers' concerns about future compatibility and making it an appealing option for long-term projects.
- Library Reliability: Library authors benefit from stable Kotlin Multiplatform, ensuring their creations remain compatible and trustworthy, encouraging wider adoption.
- Effortless Upgrades: Smooth transitions between versions simplify the update process, providing businesses and developers a hassle-free experience.

Moreover, the stabilization of Kotlin Multiplatform opens up new opportunities for collaboration and innovation within the Kotlin community. With a stable foundation in place, developers can explore creative solutions and build versatile applications that cater to a wider audience. This shift from beta to stable empowers developers to pursue ambitious projects, knowing they have a reliable framework to support their endeavors.

📝 Note
It's important to clarify that while Kotlin Multiplatform has reached overall stability, this doesn't necessarily extend to specific targets. For instance, the WebAssembly (WASM) target remains experimental, and some native targets might still be in the experimental phase. This means developers should exercise caution and check the stability status of individual targets before incorporating them into their projects. But for those that is using it for Android / iOS / Desktop it's already stable.

My opinion

I've been using this technology for 1.5 years, and the shift towards stability in Kotlin Multiplatform brings a sense of optimism about Kotlin's future. However, it's important to note that while the overall framework is stable, specific technologies like Compose/Multiplatform might not be production-ready yet. For instance, Compose's web and iOS targets are still experimental.

However, for tasks that don't involve building common UI components, Kotlin Multiplatform is highly valuable. One of the most notable use cases is, for example, in network communication. Developers can create shared networking code using Kotlin Multiplatform, which can be utilized across platforms, both in Kotlin and native languages specific to each platform. This versatility makes it a powerful tool for enhancing productivity and code reusability in multi-platform projects.

Conclusion

In summary, the stable release of Kotlin Multiplatform in version 1.9.20 signifies a pivotal moment in the evolution of Kotlin. Developers can now harness the power of Kotlin Multiplatform with confidence, knowing that it offers a reliable and efficient way to create cross-platform applications. This development not only simplifies the development process but also fosters a collaborative and innovative environment within the Kotlin community, paving the way for a future of diverse and dynamic cross-platform applications.

Finding the Right Balance in Gradle Dependency Strategy

Vadym Yaroshchuk — Wed, 25 Oct 2023 20:27:22 +0000

Introduction

In the dynamic field of software engineering, mastering dependency management is essential. With Gradle, developers have numerous strategies to declare dependencies, plugins, and versions. We will explore these methods and dissect the reasons for choosing each approach, delving into their merits and pitfalls.

Why?

Before diving into methods, understanding the significance of well-structured dependencies is crucial. What potential issues can arise in the future, and what problems should proper structuring solve? Let's explore.

Updating your dependencies

In multi-module projects, updating dependencies like Kotlin versions or library versions can quickly become a daunting task. Imagine having to navigate through every build.gradle.kts file, locating the plugins block, and modifying the version function for each dependency or plugin. The real challenge emerges when you're dealing with a significant number of modules. It's incredibly easy to overlook a specific dependency, leading to version conflicts or, in cases like Jetpack Compose, running into issues with unstable APIs tightly bound to specific Kotlin compiler versions (that can easily make your build broken with unexpected errors). You don't want to run into hours of debugging, because of simple mistakes, am I right?

Security vulnerabilities

In the realm of software security, vulnerabilities in your code can pose significant risks. Many vulnerability scanners, however, struggle with dependencies that are partially defined in other files than build.gradle.kts (for example, versions in properties files). It's crucial to adopt practices that align with security systems, ensuring your code remains robust and safe.

Lack of Centralization

In smaller projects, managing dependencies manually might seem feasible. However, as the project and team expand, this approach quickly becomes a challenge. It's far more efficient to spot issues within a specific file(s) rather than sifting through numerous configuration files, attempting to identify potential problems.

Centralizing dependency management enhances documentation. It allows specific decisions, like version choices, to be documented clearly. This centralized approach simplifies leaving notes or todos for reviews or impacting dependencies. Consistent formatting minimizes confusion and enhances readability, fostering a shared understanding of the project's dependencies. This creates a more efficient collaborative environment for the team.

Lastly, a centralized approach offers consistency in the definition style. When everyone adheres to a standardized format and structure, it minimizes confusion and enhances readability. It fosters a cohesive understanding of the project's dependencies, making collaboration smoother and more effective.

Overall, declaring your methods centralized makes your build configuration more clean, understandable and maintainable by newcomers.

Solutions

Now, we've already discussed possible problems, so let's define our main goals:

Simple
Secure
Maintainable

Now, we will come up with the solutions discussing their problems and advantages. Let's start from the simplest.

Properties as versions container

In the ever-evolving landscape of Gradle build management, the use of .properties files as version containers remains a prevalent approach. This method centralizes dependency versions, ensuring project-wide consistency.

For example, you can add your versions to gradle.properties:

kotlinVersion=1.9.20-RC
coroutinesVersion=1.7.3

And access it in your build.gradle.kts:

// ... plugins, repositories

val coroutinesVersion by project // it will auto-resolve property by name

dependencies {
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:$coroutinesVersion")
}

But, it has obvious disadvantages:

Lack of plugins support: As plugins evaluates before any other code in the build.gradle.kts and has restrictions on operations inside, you can't use properties to provide versions to your build.
Boilerplate: It adds a lot of boilerplate code (if we have more than one dependency that is obviously always a case) that clutters other logic and makes it less maintainable and understandable.

One of the advantages is that you can override properties on the Gradle Build stage, but you'll probably never need it.

In some cases, you can combine such an approach with another if you really need it, but for most projects, it's a bad idea.

Dependencies as constants

As Gradle supports composite builds and buildSrc convention module (note: it's also treated as composite built, but implicitly), you can simply create using Kotlin / Java / Groovy language singleton with constants that have dependencies & versions definition and use it directly in your builds in the next way:

object Deps {
    object Libs {
        object Kotlinx {
            const val Coroutines = "org.jetbrains.kotlinx:kotlinx-coroutines-core:${Versions.coroutines}"
        }
    }

    object Versions {
        const val kotlin = "1.9.20-RC"
        const val coroutines = "1.7.3"
    }

    object Plugins {
        object Kotlin {
            // let's take jvm plugin just for example
            const val Id = "org.jetbrains.kotlin.jvm"
        }
    }
}

In the case of buildSrc it's always in your Gradle Build configurations classpath (context) and all code from src/main/kotlin (or any other if applicable) is accessible in every build.gradle.kts within a project. For composite builds, you should register Gradle plugin and define it in the desired module (we won't discuss it in this specific article, it's just for you to know).

Even in this solution, we have multiple variants of how we can use such an approach in the end, but let's use the best one in my opinion. In your root gradle project build.gradle.kts file, you can make next:

plugins {
    // we should do this for each plugin we use in modules
    // it will affect classpath and make us free of specifying version
    // every time
    id(Deps.Plugins.Kotlin.Id) version (Deps.Versions.kotlin) apply false
}

❓ Explanation
In Gradle, the root module sets the tone for a multi-module project. Configurations, plugins, and dependencies defined in the root module automatically extend to all submodules. This ensures a uniform build environment across the project. The hierarchical structure simplifies management, allowing common settings at the root, with flexibility for customization in individual submodules.

In our modules we can use this plugin and our dependency in the following way:

plugins {
    // now we don't need to specify version, it's already on a classpath
    id(Deps.Plugins.Kotlin.Id)
}

// ... repositories

dependencies {
    implementation(Deps.Libs.kotlinxCoroutines)
}

What is the advantages?

Accessibility in code: In the case of composite builds, we can use it as usual code without any problems from other composite builds (my example) or even inside our code. As for version catalogs that we're going to discuss next, you can't use them as regular code in composite builds (important note: you can't use it inside src/main/kotlin, but inside its configuration, you can) without hacks (also, it's possible only within right context).
Better navigation and refactor: Utilizing the same mechanism throughout your code improves IDE support, making navigation and refactoring more efficient. This built-in consistency enhances the overall development experience.

Now, let's talk about the disadvantages of this method:

Lack of standardization: As it's not recommended by Gradle and not that common practice in the community, it makes your build logic more complex and less understandable.
Security Scans: Almost all security scanners (except scanners that work as gradle plugins) don't support this method (for example, related issue in Dependabot), removing entirely the effectiveness of security analysis in the project.
Auto-updating: Such a method does not have any support in IDE auto-updating / migrating feature (and as was mentioned before, same for the Dependabot)

Certain issues with dependency management methods can indeed be addressed (or ignored as unimportant for certain projects), although not without their trade-offs.

In summary, this method isn't the most maintainable or secure, lacking integration with powerful tools like Dependabot. They are relatively straightforward but have such limitations. In the future it might be resolved, but for now, it's a big problem if you want to use Dependabot.

📝 Note
This also applies to the other variants, for example, dependencies.gradle files written in Groovy that provide constants for your build scripts – it's not checked by most of the scanners.

💡 Bonus
Regarding buildSrc, it also poses challenges. Using it can hinder reusability, add complexity, and complicate gradual project migrations. It might even lead to classpath issues and performance problems in complex usage scenarios. Consequently, I avoid using buildSrc in my projects due to these potential complications. For composite builds it's not always the case, but anyway makes your build configuration less understandable.

Version catalogs

Now let's discuss a relatively recent innovation in Gradle – Version catalogs. What is version catalogs?

❓ Definition
Version catalog – it's a centralized file (in TOML format) in a Gradle project containing structured version information for libraries and plugins (usually located in gradle/libs.versions.toml).

Here's an example of such a definition:

[versions]
kotlin = "1.9.20-RC"
coroutines = "1.7.3"

[libraries]
kotlinx-coroutines = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-core", version.ref = "coroutines" }

[plugins]
kotlin-jvm = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin" }

Inside build.gradle.kts:

plugins {
    // there's special function for version catalog definition
    alias(libs.plugins.kotlin.jvm)
}

dependencies {
    implementation(libs.kotlinx.coroutines)
}

📝 Note
You can create multiple TOML definition files, for details please refer to the official manual.

Why version catalogs?

Standardization and Familiarity: Version catalogs are recommended by Gradle, which makes them widely understood by developers. Their structured approach simplifies dependency management, making it accessible to a broad audience.
Dependabot Compatibility: Version catalogs seamlessly integrate with tools like Dependabot, ensuring that your project stays up-to-date with the latest library versions. This compatibility streamlines the process of managing dependencies and addressing security vulnerabilities.
IDE Support: IDEs like IntelliJ IDEA provide built-in support for version catalogs. Developers can conveniently search for updates directly within the IDE, enhancing the development workflow and promoting efficient dependency management.

📝 Note
There're multiple ways of defining version catalogs, but, for example, Dependabot supports only reading from a file (it's worth mentioning that it will cover most of the cases). But, it might be resolved in future.

Disadvantages:

Limitation in Composite Builds: Version catalogs struggle with integrating generated code in composite builds code. This constraint hampers the flexibility of using generated code as regular components, requiring additional effort and workarounds in composite build (and not only) scenarios.
Refactoring: If you want to change names or path of your dependencies, you will need to change it in your build configurations by hands as there's no builtin support of it within IDE (at least, at the moment when this article was written).

Overall, I am choosing this method for all my new projects as it's already a standard.

Classpath

There're several ways how you can provide versions of your plugins by propagating it through classpath.

BuildScript

In older versions of Gradle, specifying plugin versions directly in the buildscript block was a common practice. It allowed developers to define the version of a plugin explicitly. Here's how it was typically done:

buildscript { 
    repositories { 
        mavenCentral() 
    } 

    dependencies { 
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.20-RC") 
    } 
}

In this approach, the version of the Kotlin Gradle plugin (1.9.20-RC in this example) is declared in the buildscript block. This version constraint ensures that the project uses the specified version of the plugin (but, it can be overwritten by submodules with special efforts).

Once the plugin version is specified in the buildscript block, applying the plugin becomes simplified. Developers can apply the plugin without explicitly specifying its version:

plugins {
    kotlin("jvm")
}

In this snippet, the kotlin("jvm") plugin is applied without mentioning the version. Gradle automatically refers to the version specified in the buildscript (to be more clear, buildscript evaluates before any other block in your script and adds specified dependencies in the classpath that is always used to resolve plugins and dependencies without a version specified; also it enforces specific version to be used as you cannot have the same plugin, but with different versions) block.

Pros:

Explicit Versioning: The version constraint is clearly defined in the build script, ensuring that the project uses a specific version of the plugin.
Consistent Versions: All modules in the project automatically use the specified version, promoting consistency.
Auto-updating: Intellij Idea (and Android Studio as well) supports auto-migration on such declarations.

Cons:

Maintenance Overhead: Manually updating the version in the buildscript block for every plugin can be tedious, especially in large projects with numerous plugins.
Less Concise Build Scripts: The buildscript block adds verbosity to the build script, potentially making it harder to read and maintain, especially as the number of plugins increases.
Security scanners compatibility: Dependabot does not support vulnerability checks on such declarations.

While this method was widely used in the past, it's now considered less recommended due to the maintenance overhead and verbosity it introduces.

❓ Explanation
Modern Gradle practices discourage specifying plugin versions directly in the buildscript block for practical reasons. Instead, it's recommended to centralize version management using the version catalogs or pluginManagement (we will discuss it lower). Plugin management approach enables, for example, dynamic version resolution, simplifying build scripts and preventing unnecessary clutter.

`pluginManagement`

As was discussed before, it's a modern way to declare your plugin's version, repositories and resolution rules. Example:

pluginManagement {
    repositories {
        gradlePluginPortal()
        mavenCentral()
        google()
    }
    plugins {
        id("org.jetbrains.kotlin.jvm") version "1.9.20-RC"
    }
}

Additionally, you can enforce specific versions using resolutionStrategy:

pluginManagement {
    repositories {
        mavenCentral()
    }
    resolutionStrategy {
        eachPlugin {
            if (requested.id.namespace == "com.example") {
                useVersion("1.2.3") // Specify the desired version here
            }
        }
    }
}

Pros of `pluginManagement`:

Lack of constraint syntax: You can use versions from properties or any other supported source. You couldn't do the same with plugins, because plugins block always evaluated separately from other part of the build script.
Dynamic Version Resolution: You can replace versions or entire plugins source using resolutionStrategy

Cons of `pluginManagement`:

Potential Complexity:
- Con: Overuse (or usage without real need) might lead to complex and harder-to-maintain scripts.
Security scanners compatibility: Dependabot does not support vulnerability checks on such declarations.

Overall, this feature should be used only if you have a special need, consider using simpler variants if all you need is the version controlling.

BOM

A BOM (Bill of Materials) in Gradle is a central version management tool for multiple dependencies. It's a file that lists compatible versions of libraries and their dependencies. Importing a BOM ensures consistent versions, minimizing conflicts in complex projects. BOMs simplify version control, providing stability and coherence across the project.

Here is the example of a BOM declaration:

javaPlatform {
    allowDependencies()
}

dependencies {
    constraints {
        api("org.slf4j:slf4j-api:2.0.9") 
        api("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3")
        // ...
    }
}

And how to use it:

dependencies {
    implementation(enforcedPlatform(project(":some-bom")))
}

How exactly it help with project organizing?

Prevents Conflicts: Ensures modules use compatible versions, avoiding conflicts.
Publishable: You can easily publish your BOM to the Maven, for example, for your library consumers; you can't do the same with version catalogs (with the same simplicity), properties, etc.
Scanners compatibility: .pom format that is used for BOMs that are published is easily recognized by most of the scanners (important note: that scan maven, Dependabot does not support it directly; but you always can use it all together with version catalogs, for example).

It's especially useful in cases where your libraries are tightly bound to specific versions of other libraries, compiler APIs, etc.

The main drawback is the possibility that you might not need this level of dependency declaration and might prefer simpler options like version catalogs.

Conclusion

We have explored various methods of defining dependencies and managing plugins and their versions. It's crucial to emphasize that your choice should align with the specific requirements of your project. For instance, the pluginManagement block can handle plugin versions, but it might unnecessarily complicate your build configuration without providing substantial benefits. Similarly, opting for constants in composite builds or buildSrc should be a decision based on actual necessity, considering both advantages and potential drawbacks. Always assess the real needs of your project before making these choices.

Gradle: from Newbie to Strong fundamentals

Vadym Yaroshchuk — Thu, 07 Sep 2023 18:32:37 +0000

When developing on Kotlin, every beginner faces the problem of not understanding the appropriate tooling for working with the programming language. That's what this article was created for - to explain the work of Gradle for Kotlin and on Kotlin. Let's go!

❓ Definition
Gradle is a system for automating the assembly, including building and compilation. It’s designed for complex build flows, where the task is not only to execute the code, but to create custom build logic, handle multi-module projects, and integrate with continuous integration systems.

But let's start with something simple - how to create our first project using Gradle?

Project

Let's start with the basic concept that exists in the application building system - Project.

❓ Definitions
Project is an independent unit of application organization as a set of dependent modules and rules for them.

Module is an independent unit of code organization that has a certain set of rules (how it is built, etc.). Exists for the same purpose as packages in Kotlin — to divide the code into logical blocks in order to improve the quality of the source code (reuse of code, both in one project and in others).

What rules am I talking about? In fact, everything is very simple - we describe how our project will be built (description of technical features), for which platform (for example, Android or iOS), in which language, and with which means (project dependencies).

Structure

Let's create an example project structure:

P.S: The names in the example have no special sense, they're just terminology from Foobar.

All modules are required to have build.gradle.kts in order to work. It's important to note that modules cannot exist on their own and they only work if we include them to our project explicitly via settings.gradle.kts

As you can see, we have a kind of "chief supervisor", who determines which modules will be in our project and how they will work, and "local supervisors" who set rules only for the code subordinate to them (modules), but, it's worth noting that Project has more priority than modules when it comes to rules (but it isn't something that we will cover in this particular article).

What rules are there? In fact, there are many of them - it all depends on what you do, but the basic ones are, for example:

Project name, version, group (an identifier that is a kinda package from Kotlin)
Programming language (Java / Scala / Groovy / Kotlin / etc)
Platform (Only relevant for Kotlin, to be more clear, for Kotlin Multiplatform plugin)
Dependencies (libraries or frameworks used in the code)

Modules

Let's consider the modules: how and with what they are eaten. Let me remind you what a module is:

❓ Definition
Module is an independent unit of code organization that has a certain set of formal rules that define the module's behavior.

For an example, let's take foo module:

To create a module, first of all, we create the directories of this module. After that, we create a file with the name build.gradle.kts (or build.gradle if you use Groovy as script language, no other way), where we will already prescribe what our module can do.

`build.gradle.kts`

Our settings file has the following structure:

Don't be afraid! Even if it looks quite complicated. 😄

The main component in any build.gradle.kts is the Plugins block. Dependencies and Repositories blocks are independent of Plugins block, but without it, they're like comedians telling jokes in an empty theater – they may have some great material, but there's no stage, no audience, and no laughter to be heard.

Plugins that are applied to your module usually consume what you've specified in the Dependencies block. So, dependencies without plugins that will use it are useless, that's why dependencies has a connection with plugins in our scheme.

Repositories are not dependent on plugins per se, but you always need them in place to apply any dependencies or plugins to your project. Therefore, without plugins or dependencies, it makes no sense to exist. So, using our previous analogy, it's akin to having a theater full of people without any comedians on stage.

Tasks are also a fundamental thing in your Gradle configuration files. They're always provided by plugins that you're applying to your module. In an empty module without any plugin, you will not have any tasks. However, there are some basic tasks that are available on a project level:

tasks (returns list of available tasks across the project: name, on which tasks task is dependent, etc.).
dependencies (prints a report of the project's dependencies, showing which dependencies are used and their versions)
help (returns list of available tasks across the project with a brief description).
model (provides a detailed report of your project's structure, tasks, etc.; helping you understand and debug your Gradle build)
etc.

💡 Bonus
Tasks can be dependent on other tasks, it's especially useful when you're needed in the result of other task's execution.

Example

Now, let's consider an example. For instance, let's create a Kotlin/JVM project with kotlinx.coroutines library as a dependency.

Firstly, we need to create our project configuration file – settings.gradle.kts in the root of our project:

rootProject.name = "our-first-project"

To make it work, you should run gradle sync inside your IDE:

You can either create a new folder for a new module or utilize the root folder as a module in the same way by simply adding a build.gradle.kts file in the root directory (our-first-project/build.gradle.kts).

❗️ Important
When we use root folder as a module we don't need to explicitly add it to our project configuration file, but for any new modules we should declare it by using the include function – for example, include(":foo") (for nested folders use include(":foo:bar"))

Let's start with plugins:

plugins {
    id("org.jetbrains.kotlin.jvm") version "1.9.0"
}

💡 Bonus
We can simplify the declaration of Kotlin plugins (such as jvm, android, js, multiplatform) using kotlin function: id("org.jetbrains.kotlin.jvm") -> kotlin("jvm").
It automatically appends org.jetbrains.kotlin at the start.

Now, let's come to the Dependencies:

dependencies {
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3")
}

Our Kotlin/JVM plugin provides a useful for us function – implementation. Without it, we would have to write explicitly a configuration name (identifier for plugin) that will consume our dependencies. As you can remember, dependencies do not live on their own. So, to be more clear, Dependencies block provides only the basic ability to add and consume added dependencies. We could add our dependency in the next way (but we still need a plugin that will consume it):

dependencies {
    add(configurationName = "implementation", "org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3")
}

configurationName stands for dividing dependencies with different target plugins (plugins that are consuming our dependencies).

But, if we try to build our module, we will have the next problem:

Could not resolve all dependencies for configuration ':compileClasspath'. > Could not find org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3.

To resolve this issue, we need to specify the repository from which we want to implement our dependency. Let's look at the example:

repositories {
    // builtins:
    mavenCentral()
    mavenLocal()
    google()

    // or specify exact link to repository:
    maven("https://maven.y9vad9.com")
}

❓ Definition
Maven repositories – are like online stores or libraries for code. They are collections of pre-built software libraries and dependencies that you can easily access and use in your projects. These repositories provide a centralized and organized way to share and distribute code.

Also, it's important to notice, that Maven is another build tool with built-in support from Gradle.

But, for our case, we're only needed in mavenCentral(). So, our resulting build.gradle.kts is next:

plugins {
    kotlin("jvm") version "1.9.0"
}

repositories {
    mavenCentral()
}

dependencies {
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3")
}

For such an example, we don't need to touch any tasks. But it would be good to mention that our Kotlin plugin provides the following tasks:

compileKotlin
compileJava
etc

But, usually, you don't need to call these tasks directly, unless you're developing your own plugin that is dependent on results/outputs from these tasks.

💡 Bonus
You can run gradle tasks either by using command line or through IDE:

As an example I took gradle build task.

We will skip for now a full explanation of tasks and how they can be used. I will cover it in the next articles.

Now, let's finally come to how and where can we write our code.

Source sets

We figured out how to create a project and modules, but where should we write the code? In Gradle projects, there is a concept of different sets of source code (Source sets) - a kind of separation of code for different needs. For example, the following sets exist by default for our previous example:

main – The name says ifself, it's main place where code should be placed.
test – Used for code that are related to testing. It's dependent on main source set and has all dependencies / code you have written in main.

💡 Bonus
But it's not always the case, for instance, Kotlin/Multiplatform projects have dedicated source sets for every platform you're writing for (basically, the plugin creates a set of source sets for all the platforms we need). So, it's important to mention that it always depends on the plugins you're applying to the module and on your configuration. It's not a constant.

main

To start coding we need to create a folder for our programming language, for Kotlin it's src/main/kotlin folder. So, from now on, we can simply create our 'Hello, World!' project. Let's create Main.kt in our recently created folder:

fun main() = println("Hello, Kotlin!")

You can run it using IDE, it will automatically handle the Gradle Building process.

test

As I've previously told you, this source set is used for testing purposes. But it's important to mention that it has its own dependencies (but it also forks it from main source-set). So, you can implement dependencies that will be available in this source-set. For example, let's implement kotlin.test library:

dependencies {
    // ...
    testImplementation(kotlin("test"))
}

You can refer to full tutorial in Kotlin documentation of how you can test your code using kotlin.test.

Multi-module projects

The creation of different modules creates the need for their interaction with each other. Also, let's analyze the types of interaction, how you can't or shouldn't do it, and what's the point. Let's start!

If you remember our initial project structure it has a few modules:

foo
bar
qux

Let's consider foo as the main module where we have our entry point to application (Main.kt file). Let's begin with creating a configuration for all three modules (it will be simple without any dependencies):

plugins {
    kotlin("jvm") version ("1.9.0")
}

repositories {
    mavenCentral()
}

To make it work, let's add our modules to settings.gradle.kts:

rootProject.name = "example"

include(":foo", ":bar", ":qux")

Then, let's make foo dependent on bar module:

// File: /foo/build.gradle.kts

dependencies {
    implementation(project(":bar"))
}

❗️ Important
To implement a module from your project, you should specify it using project function. When implementing modules or specifying it somewhere else, we use special notation where / is replaced with the : symbol.

And bonus: to implement the root module, just use implementation(project(":")).

From now, we can use any function or class from the bar inside the foo module (of course, if the visibility of these declarations allows it). For example, let's create a file in foo module:

package com.my.project

fun printMeow() = println("Meow!")

And we can use it in foo module:

import com.my.project.printMeow

fun main() = printMeow()

But, can't use it from qux module. Moreover, if we try to implement foo module, bar will still stay inaccessible. Module's dependencies are not exposed to other modules by default.

💡 Bonus
We can share dependencies for modules that implement our particular module using api function instead of implementation. In this way, for example, qux module can access bar module functions/classes/etc by implementing foo without explicit dependence on the bar module.

Limitations

Imagine that after the previous example, you need to get any class/function/etc. inside bar from foo module. If you will try to do this, you will have the next problem:

Circular dependency between the following tasks:
:bar:classes
\--- :bar:compileJava
     +--- :bar:compileKotlin
     |    \--- :foo:jar
     |         +--- :foo:classes
     |         |    \--- :foo:compileJava
     |         |         +--- :bar:jar
     |         |         |    +--- :bar:classes (*)
     |         |         |    +--- :bar:compileJava (*)
     |         |         |    \--- :bar:compileKotlin (*)
     |         |         \--- :foo:compileKotlin
     |         |              \--- :bar:jar (*)
     |         +--- :foo:compileJava (*)
     |         \--- :foo:compileKotlin (*)
     \--- :foo:jar (*)

What is it all about? Everything is simple – you cannot create circular dependencies.

Circular dependencies in Gradle are like a never-ending loop that makes your build process stuck because tasks keep waiting for each other to finish, which never happens. It's essential to avoid them to ensure your build runs smoothly. Furthermore, it's always about violating Dependency Inversion Principle that is not good practice.

You can refer to this discussion to read about it more.

👨🏻‍🏫 Bonus for experienced
Usually, if we talk about, for example, mobile applications, we use Three-Tier Architecture. So, it's a good idea to divide it into different modules to enforce architectural rules:

It makes, for example, our domain layer not to be dependent on data layer – it's literally impossible as there will be a circular dependency problem.

Conclusion

It's not just another coffee brewing method; it's a powerful build automation tool that simplifies your software development process. With Gradle, you can manage dependencies, automate tasks, and keep your projects well-organized. It's like having a trusty assistant who takes care of the nitty-gritty, so you can focus on writing awesome code!

Kotlin Coroutines are not just about concurrency

Vadym Yaroshchuk — Fri, 01 Sep 2023 17:16:50 +0000

Every time you hear about Kotlin Coroutines, you probably think about an easy, concise, and performant solution for handling asynchronous tasks like, for example, network requests. But is that their only purpose? Let's consider the usages of Kotlin Coroutines beyond concurrency.

Kotlin Coroutines Primitives

Let's start by understanding, how Coroutines underlying mechanism works. If we take a look at Kotlin Coroutines Primitives, it's only about a few classes and functions:

Continuation
CoroutineContext
suspendCoroutine
createCoroutine
startCoroutine

That's all that we have in our kotlin-stdlib. But what are they used for? Let's dive deeper into how Kotlin Coroutines are designed to work.

`Continuation`

Continuation is just an interface with two members: context and resumeWith:

public interface Continuation<in T> {
    public val context: CoroutineContext
    public fun resumeWith(result: Result<T>)
}

What does it do and what its purpose? Continuation – is literally Coroutine in primary. It's like a buffed callback with ability to propagate additional information and provide useful result of execution to coroutine.

We haven't talked about CoroutineContext yet, let's consider only resumeWith for now.

`resumeWith`

Like any other callback, this is a function that is called when coroutine finishes its work. It uses kotlin.Result to propagate any exceptions that occur inside coroutine in a safe way.

So, we can literally create our concurrency logic using Continuation in the next way:

suspend fun executeNetworkRequest(): String = 
    suspendCoroutine { continuation ->
        thread {
            continuation.resumeWith(someBlockingRequest())
        }
    }

suspendCoroutine – is a bridge between kotlin coroutines code and non-coroutine-based code.

Or use existing asynchronous (pseudo-code):

suspend fun executeNetworkRequest(): String =
    suspendCoroutine { continuation ->
        apiService.getSomething()
            // onSuccess & onFailure is a callback
            .onSuccess(continuation::resume)
            .onFailure(continuation::resumeWithException)
            .executeAsync()
    }

Continuation<in T>.resume(..) is the extension to avoid passing kotlin.Result every time.

So, we can not only implement our concurrency logic but use existing and make it work with Kotlin Coroutines.

`startCoroutine`

Also, we can start suspend functions from non-suspend contexts using startCoroutine. In Kotlin it's always used in the end if your main function is suspend.

kotlinx.coroutines also uses it to run coroutines, but the mechanism there is much harder, of course.

import kotlin.coroutines.*

fun main() {
    val operation: suspend () -> Unit = ::a
    operation.startCoroutine(
        object : Continuation<Unit> {
            // we will talk about it lower
            override val coroutineContext = EmptyCoroutineContext

            // called when coroutine finished its work
            override fun resumeWith(result: Result<Unit>) {
                println(
                    if(result.isSuccess) 
                        "Successfully done" 
                    else "Error happenned: ${result.exceptionOrNull()}"
                )
            }
        }
    )
}

suspend fun a() {...}

But, of course, you can't just call suspend functions from kotlinx.coroutines when executing coroutines in such way.

`CoroutineContext`

Now we came to another member of Continuation – CoroutineContext. What is it for?

CoroutineContext is a provider that propagates needed data to the coroutine. In the real world, it's usually about passing parameters across complex chain of coroutines.

To be more clear, CoroutineContext in kotlinx.coroutines stands for structured concurrency.

Simple example

Let's create from our previous example for startCoroutine code with the ability to retrieve values from CoroutineContext:

import kotlin.coroutines.*

// define our container for data we need inside coroutine
// it should always inherit 'CoroutineContext.Element'
data class ExecutionContext(val someInt: Int) : CoroutineContext.Element {
    override val key = EXECUTION_CONTEXT_KEY
}

// define type-safe key using which we will get our value
val EXECUTION_CONTEXT_KEY = object : CoroutineContext.Key<ExecutionContext> {}

// define coroutine context that we will pass into Continuation
private val myCoroutineContext = object : CoroutineContext {
    private val values = mapOf<CoroutineContext.Key<*>, CoroutineContext.Element>(
        EXECUTION_CONTEXT_KEY to ExecutionContext(10000)
    )

    override operator fun <E : CoroutineContext.Element> get(key: CoroutineContext.Key<E>): E? {
        return values[key] as? E
    }

    // .. we omit other functions for simplicity
}

suspend fun a() {
    // here we retrieve value from coroutine context
    // coroutineContext is compiler intrinsic, can be called
    // only from suspend world
    val executionContext = coroutineContext[EXECUTION_CONTEXT_KEY]!!
    println(executionContext.someInt!!)
}

fun main() {
    val operation: suspend () -> Unit = ::a
    operation.startCoroutine(
        object : Continuation<Unit> {
            override val context: CoroutineContext = myCoroutineContext

            override fun resumeWith(result: Result<Unit>) {
                println(
                    if(result.isSuccess) 
                        "Successfully done" 
                    else "Error happenned: ${result.exceptionOrNull()}"
                )
            }
        }
    )
}

CoroutineContext.Element – is the abstract that is used for storing elements inside CoroutineContext

CoroutineContext.Key – is the identifier of CoroutineContext.Element.

You can play around with this code here.

Real-project example

Let's imagine that we have our API service. Usually, we need to have some layer of authorization, so let's consider next example (as for such, I took gRPC):

// let's define an element that will persist in `CoroutineContext`
data class AuthorizationContext(
    val accessHash: String?,
    val provider: AuthorizationProvider,
) : CoroutineContext.Element {
    companion object Key : CoroutineContext.Key<AuthorizationContext>

    override val key: CoroutineContext.Key<*> = Key
}

// now we define our interceptor
class AuthorizationInterceptor(
    private val authorizationProvider: AuthorizationProvider,
) : CoroutineContextServerInterceptor() {
    companion object {
        private val ACCESS_TOKEN_METADATA_KEY: Metadata.Key<String> =
            Metadata.Key.of("access-token", Metadata.ASCII_STRING_MARSHALLER)
    }

    override fun coroutineContext(call: ServerCall<*, *>, headers: Metadata): CoroutineContext {
        return AuthorizationContext(
            accessHash = headers.get(ACCESS_TOKEN_METADATA_KEY),
            provider = authorizationProvider,
        )
    }
}

CoroutineContext in kotlinx.coroutines is literally just a Map<K : CoroutineContext.Key, V : CoroutineContext.Element> (to be more accurate, it's ConcurrentHashMap on JVM, for example), same as it was in our example above. But, if we talk about kotlinx.coroutines, it's propagated to all children coroutines within the desired coroutine (we didn't have such a mechanism).

So, now we can get it in children coroutines:

suspend inline fun provideAuthorization(block: (UserId) -> Unit) {
    val authContext = coroutineContext[AuthorizationContext]
    authContext.accessHash ?: throw StatusException(Status.UNAUTHORIZED)

    val userId = authContext.provider.provide(authContext.accessHash)
    return block(userId)
}

Interesting fact: coroutineContext is the only property in Kotlin that has suspend modifier. 👀

For gRPC, we also need to register our Interceptor and write our RPCs. But the idea of this solution for gRPC is simple – decouple logic and simplify developer experience.

For Java, gRPC uses ThreadLocal, so we can also consider CoroutineContext as an alternative to ThreadLocal. We cannot use ThreadLocal within coroutines, because usually coroutine is not linked to a specific thread (especially, when we talk about withContext). Coroutines are more likely to be resumed on another thread (in addition, different coroutines can run on a single thread).

But, doesn't it mean that the only reason why coroutines exist – is concurrency? Let me explain.

`Sequence`

One of the most common-place examples is the – kotlin.sequences.Sequence<T>. In brief, it's a lazy collection that iterates only when you start consuming elements. You can read about them more here.

If you ever looked at SequenceScope sources, it uses suspend functions under the hood:

@RestrictSuspension
public abstract class SequenceScope<in T> internal constructor() {
    /**
     * Yields a value to the [Iterator] being built and suspends
     * until the next value is requested.
     */
    public abstract suspend fun yield(value: T)

    // ... other
}

@RestrictSuspension disallows consumers from calling non-members suspend functions.

So, the idea is elements are consumed lazily. You can use them as regular collections and take advantage of lazy iteration.

But how does it work under the hood? Let's take a look at implementation sources:

private typealias State = Int  

private const val State_NotReady: State = 0  
private const val State_ManyNotReady: State = 1  
private const val State_ManyReady: State = 2  
private const val State_Ready: State = 3  
private const val State_Done: State = 4  
private const val State_Failed: State = 5  

private class SequenceBuilderIterator<T> : SequenceScope<T>(), Iterator<T>, Continuation<Unit> {  
    private var state = State_NotReady  
    private var nextValue: T? = null  
    private var nextIterator: Iterator<T>? = null  
    var nextStep: Continuation<Unit>? = null  

    override fun hasNext(): Boolean {  
        while (true) {  
            when (state) {  
                State_NotReady -> {}  
                State_ManyNotReady ->  
                if (nextIterator!!.hasNext()) {  
                    state = State_ManyReady  
                    return true  
                } else {  
                    nextIterator = null  
                }  
                State_Done -> return false  
                State_Ready, State_ManyReady -> return true  
                else -> throw exceptionalState()  
            }  

            state = State_Failed  
            val step = nextStep!!  
            nextStep = null  
            step.resume(Unit) // IMPORTANT: it starts executing next yield 
        }  
    }  

    override fun next(): T {  
        when (state) {  
            State_NotReady, State_ManyNotReady -> return nextNotReady()  
            State_ManyReady -> {  
                state = State_ManyNotReady  
                return nextIterator!!.next()  
            }  
            State_Ready -> {  
                state = State_NotReady  
                @Suppress("UNCHECKED_CAST")  
                val result = nextValue as T  
                nextValue = null  
                return result  
            }  
            else -> throw exceptionalState()  
        }  
    }  

    private fun nextNotReady(): T {  
        if (!hasNext()) throw NoSuchElementException() else return next()  
    }  

    private fun exceptionalState(): Throwable = when (state) {  
        State_Done -> NoSuchElementException()  
        State_Failed -> IllegalStateException("Iterator has failed.")  
        else -> IllegalStateException("Unexpected state of the iterator: $state")  
    }  


    override suspend fun yield(value: T) {  
        nextValue = value  
        state = State_Ready  
        return suspendCoroutineUninterceptedOrReturn { c ->  
            nextStep = c  
            COROUTINE_SUSPENDED  
        }  
    }    
    override fun resumeWith(result: Result<Unit>) {  
        result.getOrThrow() // just rethrow exception if it is there  
        state = State_Done  
    }  

    override val context: CoroutineContext  
        get() = EmptyCoroutineContext  
}

COROUTINE_SUSPENDED is a special constant used internally by the Kotlin compiler to manage coroutine suspension and resumption. It's not something developers typically interact with directly, but rather, it serves as an internal signal within the coroutine machinery.

Looks a bit hard to read, isn't it? Let's go step by step:

First, we start with states. We have next states, let's talk about them in brief:
- State_NotReady: The iterator is not ready to provide an item right now. It might be waiting for an operation or further processing to make an item available.
- State_ManyNotReady: The iterator is prepared to provide multiple items, but they aren't ready immediately. It's waiting for a signal that items are ready for consumption (basically, waits for terminal operator).
- State_ManyReady: The iterator is ready to provide multiple items right now. It can immediately give the next item from the sequence.
- State_Ready: The iterator has a single item ready to be provided. It's set to immediately give the item when asked.
- State_Done: The iterator has no more items to provide. It has completed its job of producing elements from the sequence. We reach this state when we leave SequenceBuilder
- State_Failed: Something unexpected happened, and the iterator encountered an issue. Usually, this should not happen.
hasNext based on state, returns a value or set of values when it's ready to consume. Moreover, it starts execution of sequence on every iteration inside while. So, if there's State_NotReady, it makes it ready by executing next yields.
The next function retrieves the next item from the iterator based on its current state (same to hasNext). If next was called without hasNext, you can reach nextNotReady(). In other situations, it will simply return value.
yield function just changes states of sequence iterator implementation. When new elements added it changes to State_Ready. Using suspendCoroutineUninterceptedOrReturn suspends the coroutine (execution) and resumes it later. It will be started when previous coroutine (suspend point) will be finished.

To finish my explanation, let's just end with how could we make the same functionality just by using callbacks:
val sequence = sequence {
    yield(1) {
        yield(2) {
            yield(3) { /* ... */ }
        }
    }
}
kotlin

But, it looks a bit hard to read, isn't it? That's why coroutines are useful in this particular situation.

In the end, it doesn't look that complex, am I right?

`DeepRecursiveScope`

Now, let's discuss another case for Kotlin Coroutines – DeepRecursiveScope. As you probably know, usually when specific function call itself, we have a probability of running into StackOverflowError as every call contributes it to our stack.

For the same purpose, for example, also exists tailrec language construction. The difference is that tailrec cannot have branching (conditional checks) with calls to other functions.

You can read about that more here.

So, DeepRecursiveScope doesn't rely on traditional stack flow, but uses all the features Coroutines offer. To understand it more, let's consider classic example with fibonacci numbers:

val fibonacci = DeepRecursiveFunction<Int, Int> { x ->
    when {
        x < 0 -> 0
        x == 1 -> 1
        else -> callRecursive(x - 1) + callRecursive(x - 2)
    }
}

println(fibonacci(12)) // output: 144

For more complex example, you can refer to the kdoc.

We won't stop on exact implementation details of DeepRecursiveScope (you can take a look at it here) as it has the same idea to Sequence with additional behaviour to support mechanisms that is provided, but let's discuss how Kotlin Coroutines solves this particular problem. Furthermore, there's very good article about it from Roman Elizarov.

Coroutines internally

How exactly it solves the problem? As I mentioned before, Coroutines are inspired by CPS (Continuation Passing Style), but it's not exactly what Kotlin Compiler does to handle coroutines that efficiently.

Kotlin Compiler uses a combination of optimizations to manage coroutines stack and execution efficiently. Let's check what exactly it does:

Compiler transformations: Kotlin Compiler generates State Machine, same to what we saw in the implementation details of Sequences. It doesn't get rid of all stack calls but reduces it enough to not run into StackOverflowError.
Heap-Allocation of Continuations: In a traditional callback chain, each function call pushes data onto the call stack. If the chain is deep, this can consume a lot of stack space. In the coroutine approach, when a coroutine is suspended, its continuation is stored on the heap as an object. This continuation object holds the necessary information (stack, dispatcher, etc) to resume the coroutine's execution. This heap storage allows for a much greater capacity to handle deep call chains without risking stack overflow.

The exact mechanism of coroutines is next:

Serialization: Suspended coroutine's stack state is saved in a heap-allocated continuation object.
Resumption: When ready to resume, the framework sets up a native stack to mimic captured state.
Memory Copy: Serialized stack state is copied from the continuation object to the native stack.
Context Configuration: Execution context is configured to match original state.
Program Counter: Program counter is set to saved value for correct instruction.
Invocation: Continuation code is invoked using CPS, resuming execution.

Stack restoring also helps us with resuming on different threads as they don't know anything about our coroutine's stack.

So, from now we can understand how coroutines internally work. Let's move on to other examples where Kotlin coroutines are used beyond concurrency.

Jetpack Compose

If you ever worked with Compose and, for example, handling pointer events, you have probably noticed that there're some hacks used from Coroutines for listening to updates:

@RestrictsSuspension // <---
@JvmDefaultWithCompatibility
interface AwaitPointerEventScope : Density {
    // ...

    suspend fun awaitPointerEvent(
        pass: PointerEventPass = PointerEventPass.Main
    ): PointerEvent

    suspend fun <T> withTimeoutOrNull(
        timeMillis: Long,
        block: suspend AwaitPointerEventScope.() -> T
    ): T? = block()

    suspend fun <T> withTimeout(
        timeMillis: Long,
        block: suspend AwaitPointerEventScope.() -> T
    ): T = block()

    // ...
}

So, as you see, scope that is used to handle pointer events is marked with @RestrictsSuspension. If we come to the documentation provided, we'll see next:

This is a restricted suspension scope. Code in this scope is
always called un-dispatched and may only suspend for calls 
to [awaitPointerEvent]. These functions resume synchronously and the caller may mutate the result
**before** the next await call to affect the next stage of the input processing pipeline.

awaitPointerEvent is handled using kotlin primitives, without kotlinx.coroutines. As in such situation we don't need any kotlinx.coroutines logic (it's fairly just a callback that is called from Main-looper thread after user's action).

Conclusion

In conclusion, this article has explored various facets of Kotlin Coroutines, emphasizing their versatility beyond traditional concurrency tasks. We've delved into the inner workings of coroutines primitives, discussed their use in Sequences and complex problem-solving scenarios like deep recursion, and examined real-world examples that showcase their broad applicability. The title, "Coroutines are not just about concurrency," aptly reflects the diverse capabilities that Kotlin coroutines offer in modern software development.

Feel free to casually drop your expertise in the water cooler chat!

Extension-Oriented Design in Kotlin

Vadym Yaroshchuk — Fri, 04 Aug 2023 15:50:47 +0000

As programming evolved, so did the ways we structure code. Early programs were simple straight-line sequences of instructions, with reuse achieved mainly through copy-and-paste. Over time, this led to the introduction of abstractions such as subroutines, procedures, and functions, and later to higher-level approaches like object-oriented programming.

Progress doesn’t stop, and each language comes with its own conventions that shape how code is written and read. Today, we’ll discuss Extension-Oriented Design in Kotlin — what it is, and why extensions are more than just a workaround for classes you don’t own.

Extensions in Kotlin

Let’s start with a quick introduction for readers who are new to Kotlin — or don’t use it daily but are still curious.

A Kotlin extension is a language feature that lets you add new behavior to an existing type without modifying it or inheriting from it.

In most object-oriented languages, the classic way to extend functionality is through inheritance. This works well until you don’t own the class or inheritance is not an option — for example, when a type is a primitive, final, sealed, or already has too many implementations to reasonably extend.

In Java, this limitation is usually handled by introducing so-called helper or utils classes (the naming varies, the idea does not). For instance, adding a function to find the maximum element in a list often looks like this:

public final class ListUtils {
    private ListUtils() {}

    public static Integer max(List<Integer> values) {
        if (values == null || values.isEmpty()) {
            return null;
        }

        int max = values.get(0);

        for (int i = 1; i < values.size(); i++) {
            int value = values.get(i);
            if (value > max) {
                max = value;
            }
        }

        return max;
    }
}

Technically, one could wrap a List in another class to provide additional functionality using the delegation pattern. In practice, this is rarely done. Imagine creating a list with List.of(...) and then wrapping it again in FooList<E> just to gain a single extra operation — this introduces unnecessary ceremony and often extra allocations for very little benefit. As a result, static utility methods remain the dominant approach. That works, but comes with trade-offs.

You must know that ListUtils exists, remember its name, and hope it follows a predictable naming convention. In real codebases, these classes tend to grow large, multiply over time, and fragment into several variants. Finding an existing helper function often turns into a search problem, and duplicate implementations are common simply because someone didn’t know the functionality already existed.

Kotlin addresses this with extension functions. Instead of searching for a helper class, you look for behavior defined on the type itself:

fun Iterable<T : Comparable<T>>.max(): T { /* ... */}

This makes discovery significantly easier. The functionality is expressed in the vocabulary of the type it belongs to, rather than being hidden behind an arbitrary utility class name.

That said, Kotlin extensions are sometimes perceived merely as a way to work around language limitations. A common example is the inability to declare a final member in an interface, even though some functions are inherently final by nature — such as those relying on reified type parameters:

interface Serializer {
  fun <T> encode(kClass: KClass<T>, value: T): String
}

inline fun <reified T> Serializer.encode(value: T): String {
  return encode(T::class, value)
}

Here, the inline extension is meant to delegate to the underlying function, without adding new behavior. Its purpose is purely to provide a more convenient call-site usage, not to change what the original function does. Even if the language allowed overriding it, doing so would be inappropriate, because it could break this delegation and expected contract if somebody would override it in an unexpected way.

But is it only use of extensions? Not really.

Separating Core from Capability

Now to the most interesting part — how extensions help beyond working around language restrictions? But let's start with some kind of definition:

Extension-Oriented Design is an approach where a type’s core capabilities are kept minimal and stable, while derived, combinational, or convenience behavior is expressed via extensions — regardless of whether the type is owned or not.

While extensions are often used for classes we don’t own, ownership is not the point. The point is separating what a type is from what can be done with it.

A good example is Flow<T> in kotlinx.coroutines. The Flow interface is intentionally minimal and is built around a single core capability: collect. Everything else is derived from it.

Conceptually, the interface boils down to:

public interface Flow<out T> {
    suspend fun collect(collector: FlowCollector<T>)
}

All higher-level operations — map, filter, combine, flatMapLatest, and many others are implemented as extensions that reuse this single primitive rather than expanding the interface.

For example, map is essentially defined as:

public inline fun <T, R> Flow<T>.map(
    crossinline transform: suspend (T) -> R
): Flow<R> =
    flow {
        collect { value ->
            emit(transform(value))
        }
    }

Extension-oriented design makes this structure explicit. The core stays small and readable; derived behavior is clearly layered on top. This, in turn, simplifies understanding the codebase and reasoning about the abstraction.

It also addresses a broader problem that abstractions often introduce: uncontrolled inheritance. When behavior is expressed through overridable members, it becomes harder to reason about what actually happens at runtime. A bug often turns into a guessing game in the code of endless chain of inheritence — what could have been overridden, and where?

Extensions avoid this class of problems by design. They cannot be overridden, and therefore cannot silently alter behavior. This is not a limitation, but an intentional property: contracts remain stable, derived behavior stays predictable, and the set of things that can influence execution is reduced.

As a result, extensions not only help structure code — they help preserve trust in the abstraction itself.

And this is not a library-only technique — you can apply the same approach in your own code. A few general guidelines:

Define a small, stable core capability.
Express everything else as extensions built on top of it.
Let behavior grow without inflating the core abstraction.

In this model, extensions are not “extra helpers”. They are the primary way behavior is composed, while the core remains minimal and explicit.

If you're curious about other examples of this approach you can also go through kotlin.Result and Ktor sources. In general, all Standard Library, kotlinx.coroutines, Ktor and other official libraries use this approach. Great source of inspiration!

Into the Deep End

Let’s try to build something ourselves to really fixate this idea. Imagine you need to build a small and simple caching library. How would you approach it with extension-oriented design in mind?

First, we need to identify the core functionality — the minimal set of operations that any cache must support. At its heart, a cache does two things:

Retrieve a value by a key.
Store a value under a key.

Everything else is just convenience layered on top. That gives us a clear, minimal interface:

interface Cache<K : Any, V : Any> {
    operator fun get(key: K): V?
    // Assigns [value] to a [key]. 
    // If [value] is nulls — removes it from cache
    operator fun set(key: K, value: V?): Boolean
}

This interface captures the core capabilities: get and set. It is small, stable, and predictable. Nothing else needs to live here, because everything additional can be expressed via extensions.

Next, let’s think about the consumer experience. In real-world usage, you often want to read a value or compute and store it if absent. That’s a very common pattern:

val cachedValue = if (cache[key] != null) {
    cache[key]!!
} else {
    val value = computeValue()
    cache[key] = value
    value
}

Writing it every time we work with cache is quite inconvenient, isn't it? We can encapsulate this pattern in a single extension, leaving the core interface untouched:

fun <K : Any, V : Any> Cache<K, V>.getOrAssign(key: K, block: () -> V): V {
    return get(key) ?: block().also { set(key, it) }
}

Notice how this works: the interface itself stays tiny — just get and set. Everything else lives in extensions. Here, getOrAssign is exactly that kind of extension: it doesn’t change how the cache works, it just adds a clear, convenient way to use it.

At the call-site it reads almost like plain language: cache.getOrAssign(key) { expensiveComputation() }. You immediately know what’s happening: if the value is there, use it; otherwise, compute it and store it. The name getOrAssign is chosen deliberately — we want it to be explicit about what this extension does, not leave anyone guessing.

The beauty of this approach is that we can keep the core stable while layering on behavior in ways that are predictable and composable, keeping things small, clear, and lets the functionality grow naturally.

Later on, you could add something like invalidate(key: K) as an extension — all without touching the original interface. It makes the API feel cleaner than relying on set(key, null) — which works, but feels a bit technical and not immediately obvious to someone using the cache.

Conclusion

We use extension functions for many reasons: to work around technical limitations (for example, when a class is unavailable for modification or when certain features, such as inline functions, cannot be used directly), and to structure code in a way that improves understanding.

Extensions are not a silver bullet, especially in context of namespace pollution problem, and they shouldn’t be applied mechanically. Overengineering is easy, but ignoring this approach altogether often leads to bloated abstractions and poor discoverability.

Used deliberately, extension-oriented design helps keep core abstractions small while allowing behavior to grow in a controlled and readable way.

In the end, I also highly recommend Roman Elizarov’s article on the same topic.

DEV Community: Vadym Yaroshchuk

UI shouldn't think about validation

Failures we don't model correctly

What is a Contract?

Types of contract violation

User Input

Programmer Error

Environmental failure

How to handle contract violations?

How is it handled in code we use?

Standard library

kotlinx.coroutines

Reality

User Input

Internal Input

Uncontrolled Input

False Safety

Catch.. less

Failure has destination

Bonus

Final thoughts

Semantic Typing We Ignore

What is semantic typing?

Why?

Compile-time safety

Documentation

Validation

When to use it?

Application code

Library code

Real-world examples

Standard library

Android Views vs Jetpack Compose

When not to use it?

Modeling inputs

Modeling outputs

Conclusion

Package naming nobody cares about (but should)

What is a Package, Really?

Packages as Folders

Packages as Namespaces

What deserves a namespace?

.common / .core packages

Bonus way of thinking

Namespacing on macro level

Naming a namespace (package)

Make the correct focus

Conclusion

Finding the Right Balance Between DDD, Clean and Hexagonal Architectures

Smart terminology

Clean Architecture

Domain-driven Design

Value objects

Domain entities

Aggregate

Problems

Anemic Domain Entities

Ignoring Ubiquitous Language

Hexagonal Architecture

Problems

Incorrect mental model

My implementation

Conclusion

Bonus

Kotlin Multiplatform is now stable – What's the Impact?

Game changer

My opinion

Conclusion

Finding the Right Balance in Gradle Dependency Strategy

Introduction

Why?

Updating your dependencies

Security vulnerabilities

Lack of Centralization

Solutions

Properties as versions container

Dependencies as constants

Version catalogs

Classpath

BuildScript

`.common` / `.core` packages

`pluginManagement`

Pros of `pluginManagement`:

Cons of `pluginManagement`:

`build.gradle.kts`

`Continuation`

`resumeWith`

`startCoroutine`

`CoroutineContext`

`Sequence`

`DeepRecursiveScope`