DEV Community: Tom Horvat

Make illegal states unrepresentable, until you have to explain them

Tom Horvat — Sun, 30 Aug 2026 20:34:13 +0000

How to decide which constraints belong in your types and which belong in your validator.

A config file with eight things wrong with it

A config file lands with eight things wrong with it. Your loader is built by the
book, every constraint in the type system, so it stops on the first one and
throws. The person who wrote the config fixes that, re-uploads, and meets the
second. Six more after that.

Fail fast, fail loud. Your loader did both, eight times, one at a time.

"Make illegal states unrepresentable" optimizes for preventing bad states,
but some systems have to explain them, and those two goals pull your type
design in opposite directions.

Every principle has a range

Parse, don't validate.
Make illegal states unrepresentable. Encode your invariants in the type system,
and once a value exists it is valid by construction. Push the mess to the
boundary and let the core trust what it is handed. A NonEmptyList can't be
empty. A sealed Payment can't be Cash and
Card at once. Whole categories of defensive checks disappear, and the bugs that
hid in them go too.

Fail fast, fail loud has its own time and place. Early on, when the shape of the
thing is still moving and you are the only person who will ever read the error,
stopping at the first problem is the cheapest feedback there is. You read the
trace, you fix it, you move on.

It stops fitting the moment the values are entered by someone else and have to
agree with each other. From their side, submitting is one step. Fail fast answers
it eight separate times, and never once says how many are left.

The requirement that breaks it

Take for example the loader I've been building in Kotlin. It reads campaign
configs: a date window, a target segment, a discount, localized copy per market.
It has one hard rule: when a config is invalid, it must report every
violation in a single pass, each as a stable (code, path) pair, rather than
failing on the first one it finds. The result type is literally shaped for it:

data class ValidationError(
    val code: ValidationCode,
    val path: String,
    val message: String? = null,
)

sealed interface ValidationResult {
    data object Valid : ValidationResult
    data class Invalid(val errors: List<ValidationError>) : ValidationResult
}

That requirement hits a wall:

Unrepresentable means fail-fast, by construction.

If you cannot construct the invalid value, you cannot hold it, and if you
can't hold it you can't inspect it for all eight of its faults. A type that
refuses the first mistake has, in the same motion, made the other seven
unreportable in the same pass. The very property that makes "unrepresentable"
safe, that the value never comes into being, is the property that makes
accumulating errors impossible.

So an error-accumulating validator is not a failure to apply the principle. It's
a requirement the principle cannot express.

The split

The resolution is to stop treating "type-level" versus "runtime check" as a
purity contest and treat it as a routing decision. Every constraint goes to one
of two places, by a rule you can state in one line:

Forbid by construction what is total and local. Forbid by validator what is
contextual or user-facing.

Routing this way also gives each layer a job it can actually do. The input form
stops you typing letters into a number field. The type system stops you writing
down a shape that has no meaning. The validator answers the only question left,
which is whether a well-formed config makes sense as a whole. That last one is
the only guarantee of the three: the form is one input path among several, and the
validator has to hold whether the config arrived through your UI, a file, or
somebody's script.

The two halves of the rule overlap, and the overlap is deliberate. A bounds check
on a single field is total and local, so the first half claims it. If that bound
is something a person has to be told about, the second half takes it anyway. When
both apply, reporting wins.

Forbid by construction: total and local

When a constraint is about a single field or a closed set of shapes, the type
system is exactly right, and you should use it. Case in point, the discount is a
sealed hierarchy:

@Serializable
@JsonClassDiscriminator("type")
sealed interface Discount {
    @Serializable
    @SerialName("PERCENTAGE")
    data class Percentage(val percent: UInt, /* ... */) : Discount

    @Serializable
    @SerialName("FIXED")
    data class Fixed(val amountMinor: Long, val currency: String, /* ... */) : Discount
}

A currency (a FIXED concept) on a PERCENTAGE discount is not something the
validator rejects. It is something you cannot write down. There is no
validation rule for it, because there is no invalid state to catch. This is the
principle working perfectly, and I lean on it hard: whenever a shape has disjoint
fields keyed by a discriminator, it becomes a sealed hierarchy, precisely so that
mismatched combinations never exist.

Forbid by validator: contextual or user-facing

The other place is for constraints that no local type can hold, or that must be
reported rather than prevented. Two flavors:

Contextual (cross-entity) constraints. A localized copy entry names a market,
but it's only valid if that market is actually covered by the audience segment
this campaign targets. That's a fact about three entities at once (the copy
entry, the campaign that holds it, and the segment it targets). No field type on
the copy entry can encode "a market that exists somewhere else in the graph." So
it's a validator rule, running inside the accumulator where add appends to the
error list and index is a prebuilt lookup:

val markets = index.marketIdsBySegment[campaign.segmentId]
if (markets != null) {
    campaign.copy.forEach {
        if (it.marketId !in markets)
            add(
                ValidationError(
                    ValidationCode.UNTARGETED_COPY_MARKET,
                    "campaign[${campaign.id}].copy[${it.marketId}]"
                )
            )
    }
}

Deliberately permissive fields. Some fields are left looser than the domain
allows, on purpose, so the violation has a name. Percentage.percent is a
UInt, and the type happily permits 120u. The domain caps it at 100, but
instead of reaching for a
Percent value class, I let
the value exist and let a validator rule name it:

if (discount is Discount.Percentage && discount.percent > 100u)
    add(
        ValidationError(
            ValidationCode.DISCOUNT_OUT_OF_RANGE,
            "campaign[${campaign.id}].discount.percent"
        )
    )

The permissiveness is the point. A value that can exist can be pointed at, and
a value that can be pointed at can produce DISCOUNT_OUT_OF_RANGE at path
campaign[...].discount.percent, which the form can render next to the offending
field. An unconstructable value can't be pointed at; it can only crash the
decoder.

What the split buys you

This produces a clean two-phase ingestion:

Decode: structural only. kotlinx.serialization against a strict codec: unknown keys rejected, no lenient coercion, no special float values. This phase answers "is this the right shape?"
Validate: semantic, accumulating. The validation rules run over the decoded graph and collect every (code, path). This phase answers "does this shape make sense?"

Each phase has exactly one job, and the payoffs compound:

The types stay simple. Flat data classes, no wrapper types, no hand-written invariants buried in init {} blocks. That matters extra here because these same types are the wire format. Every constructor you'd add for safety is a serialization edge case you'd owe forever.
Errors become a product surface. Each ValidationCode plus its path is enough to drive field-level highlighting in the form. The validator isn't a gate that says "no"; it's a function that says "here are all eight things to fix, and where each one is."

That last part is not a figure of speech. Here is that eight-mistake config,
uploaded on 14 April against a segment covering de-DE, en-GB, en-US and es-ES:

{
  "id": "promo-spring",
  "window": { "start": "2026-04-01", "end": "2026-03-25" },
  "segmentId": "seg-eu-shoppers",
  "discount": { "type": "PERCENTAGE", "percent": 120 },
  "copy": [
    { "marketId": "fr-FR", "headline": "Offre de printemps" },
    { "marketId": "en-GB", "headline": "Spring offer" },
    { "marketId": "en-GB", "headline": "Spring sale" },
    { "marketId": "en-US", "headline": "" }
  ]
}

And here is what comes back:

WINDOW_ENDS_BEFORE_START   campaign[promo-spring].window
WINDOW_ALREADY_ELAPSED     campaign[promo-spring].window
DISCOUNT_OUT_OF_RANGE      campaign[promo-spring].discount.percent
UNTARGETED_COPY_MARKET     campaign[promo-spring].copy[fr-FR]
MISSING_COPY_FOR_MARKET    campaign[promo-spring].copy[de-DE]
MISSING_COPY_FOR_MARKET    campaign[promo-spring].copy[es-ES]
DUPLICATE_COPY_MARKET      campaign[promo-spring].copy[en-GB]
EMPTY_COPY_HEADLINE        campaign[promo-spring].copy[en-US].headline

One upload, one pass, eight rows. Note that the code alone isn't the identity:
MISSING_COPY_FOR_MARKET shows up twice, and two different rules land on
.window. The pair is what points at a field, which is why the pair is what the
validator returns.

The cost, honestly

This isn't free, and pretending otherwise would undercut the point.

The core now trusts a type that can hold a semantically-invalid value in the
window between decode and validate. percent really can be 120u in a decoded
Campaign object. So you need one piece of discipline: nothing downstream of
validation runs on an Invalid result. The validate() call is the gate; past
it, the graph is trusted (and the config is frozen once the campaign goes live,
so it can't drift back into invalidity).

The other cost is judgment: the rule doesn't apply itself. Forbid by validator
only when the constraint is contextual or must be reported. If a constraint is
total, local, and you never need to accumulate, if one violation is genuinely
catastrophic to even hold in memory, then reach for the sealed type or the value
class. Don't make something permissive just because you can. Make it permissive
when the error needs a name.

So where's the line?

"Make illegal states unrepresentable" is not wrong. It's a tool with a blast
radius. Applied to a total, local constraint, it deletes bugs for free. Applied to
a constraint your users need explained, it turns an eight-item fix-it list into
eight round-trips.

Both ideas are correct at once: some states should be unrepresentable, and some
error sets must be reported whole. The skill is not picking a side. It's knowing which
constraint belongs on which side of the decode/validate line.

Self-Referential Generics in Kotlin: When Type Safety Requires Talking to Yourself

Tom Horvat — Wed, 01 Apr 2026 23:09:37 +0000

Kotlin's type system is expressive enough to let you write code that is simultaneously statically typed, runtime validated, and ergonomic at the call site. That combination usually requires some machinery — and understanding why the machinery exists, rather than just how to copy it, is the difference between architecture and cargo-culting.

For reference, we will use the RandomPokemon repo.

The BaseViewModel in this codebase is a clean example of a pattern where self-referential generics, reified type parameters, and a sealed class hierarchy solve a real problem at a boundary where compile-time types naturally blur.

An implementation like this enforces a single, standardized way to consume use case output that makes type mismatches observable before they reach production.

The Problem at the UI/Domain Boundary

ViewModels sit at a boundary between two distinct type worlds. The domain layer produces ResultState — a sealed class that carries either a message, an error, or a payload typed as Any?:

sealed class ResultState {
    data class Running(val message: String? = null) : ResultState()
    data class Error(val error: Throwable? = null) : ResultState()
    data class Complete<out O>(val data: O?) : ResultState()
}

The UseCase<in O> abstraction wraps this in a StateFlow<ResultState?>, where O is the expected output type:

abstract class UseCase<in O>(private val logger: Logger? = null) {

    abstract val name: String    
    private val _state = MutableStateFlow<ResultState?>(null)
    val state: StateFlow<ResultState?> = _state

    protected fun running(message: String? = null) {
        logger?.d("Running $name: $message")
        _state.value = ResultState.Running(message = message)
    }

    protected fun Throwable?.update() {
        logger?.e(this ?: Throwable(), "Error in $name")
        _state.value = ResultState.Error(error = this)
    }

    protected fun O?.update() {
        logger?.d("Completed $name: $this")
        _state.value = ResultState.Complete<O>(data = this)
    }
    // ...
}

The variance declarations here are intentional and worth noting: Complete<out O> is covariant because ResultState produces values of type O (you read .data out of it), while UseCase<in O> is contravariant because a use case consumes O to update its state (via protected fun O?.update()) — it never hands O back to a caller. If you try to implement this pattern and swap the variance annotations, the compiler will tell you exactly where the flow of data breaks.

Notice that O is a contravariant input type parameter (used only in protected fun O?.update()), but the exposed StateFlow is typed to ResultState? — the O is erased at the boundary. By the time the ViewModel receives useCase.state, it has no compile-time knowledge of what type is inside ResultState.Complete.

This is inherent to the architecture. Use cases communicate via a shared ResultState channel, which must be typed to the sealed class rather than each use case's specific output type. You can't parameterize StateFlow over a generic that varies per use case if the ViewModel holds multiple use cases simultaneously.

So, where do you recover type safety, and at what cost?

The ViewModel's Generic Parameter

BaseViewModel is generic over its own state model:

open class BaseViewModel<M : ViewModelState>(initialState: M) : ViewModel(), KoinComponent {
    private val _state: MutableStateFlow<M> = MutableStateFlow(initialState)
    val state: StateFlow<M> = _state.asStateFlow()

    protected fun updateState(transform: (M) -> M) {
        _state.update(transform)
    }
}

The M : ViewModelState bound means the ViewModel's own state (the UI state model) is typed. This is the self-referential part: HomeViewModel extends BaseViewModel<HomeState>, binding M to HomeState. The updateState lambda then gives subclasses a type-safe transformation — transform: (HomeState) -> HomeState — rather than an untyped mutation.

This is a well-understood pattern. The interesting part is how collectUseCase operates across both generic contexts — and what it enforces.

Two Generics, One Function

protected inline fun <reified O> UseCase<O>.collectUseCase(
    crossinline onRunning: (String?) -> Unit = {},
    crossinline onError: (Throwable?) -> Unit = { e -> onUseCaseError(e) },
    crossinline onDone: suspend (O?) -> Unit = {}
) = viewModelScope.launch {
    this@collectUseCase.state.collect {
        it?.let {
            it.parse<O>(
                onError = { e -> onError(e) },
                onRunning = { m -> onRunning(m) },
            ) { result -> onDone(result) }
        }
    }
}

This extension function on UseCase<O> is declared inside BaseViewModel<M>. It introduces its own generic parameter O (reified), independent of the class-level M. The function has access to viewModelScope (from the enclosing BaseViewModel context) while O is the expected output type of the specific use case being collected.

The call site looks like this:

getPokemon.collectUseCase<PokemonDetails>(
    onRunning = { updateState { it.copy(loading = true) } },
    onError   = { e -> updateState { it.copy(error = e) } }
) { details -> updateState { it.copy(pokemon = details) } }

The compiler infers O = PokemonDetails from the reified type parameter. Inside onDone, result is PokemonDetails? — statically typed. No cast at the call site.

The type recovery happens inside ResultState.parse<O>:

inline fun <reified O> parse(
    onRunning: (String?) -> Unit = {},
    onError: (Throwable?) -> Unit = {},
    onComplete: (O?) -> Unit = {},
) {
    when (this) {
        is Running -> onRunning(this.message)
        is Error   -> onError(this.error)
        is Complete<*> -> this.data?.let {
            it.takeIf { it is O }
                ?.let { result -> onComplete(result as O?) }
                ?: run { onError(IllegalArgumentException(
                    "Expected output of type ${O::class.simpleName}; got ${data?.let { data::class.simpleName }}"
                )) }
        } ?: run { onComplete(null) }
    }
}

The Complete<*> star projection in the when branch is not stylistic — it's required by the JVM's type erasure. Writing is Complete<O> is illegal at runtime because the generic parameter is erased; the JVM only sees Complete, not Complete<PokemonDetails>. The star projection is an honest acknowledgment of that: "I know this is a Complete, but I can't assert what it contains yet." The payload type is recovered one step later, inside the branch, where takeIf { it is O } uses the reified type token to perform the actual check. This two-step dance — structural match via star projection, then type recovery via reification — is the idiomatic Kotlin solution to the erasure problem at sealed class boundaries.

If the data is the expected type, the cast is safe, and onComplete receives a typed value. If not, the mismatch is routed to onError as an IllegalArgumentException with a diagnostic message naming both the expected and actual type.

A Single Entry Point as a Standard

Before examining the type mechanics in detail, it's worth stepping back and recognizing what collectUseCase is doing at the team level: it is the only sanctioned way to consume a use case in this codebase.

That's not a coincidence, and it's not just ergonomics. Every developer writing a new ViewModel hits the same function, receives the same structure, and is guided towards the same three concerns: what happens while loading, what happens on failure, and what happens on success. There is no alternative path — no way to collect { state -> ... } raw ResultState directly in a ViewModel without bypassing the base class entirely or going through the ceremony of exposing the use case state for collection within a viewModelScope.launch block. This meta-contract is strictly a team-level decision, and is by no means religiously enforced. Rather, it is the teams' agreed-upon convention aimed at readability, convenience, and standardization across potential verticals.

This matters for code review and maintenance in a way that documentation never can. You can write a coding standard that says "always handle the running and error states." You can also write collectUseCase, which makes not handling them an active decision that requires extra effort. The default onError implementation is:

crossinline onError: (Throwable?) -> Unit = { e -> onUseCaseError(e) }

onUseCaseError logs the throwable. A developer who forgets to pass an onError handler doesn't silently swallow failures — the fallback ensures breakage is still observed, just in logcat rather than the UI. Omitting error handling is now a deliberate downgrade, not an oversight.

The explicit type annotation at the call site — collectUseCase<PokemonDetails> — is also load-bearing as communication. It's documentation that can't become stale: whoever reads this call knows exactly what the ViewModel expects this use case to produce, without navigating to the use case's definition. It turns a consumption pattern into a declaration of intent.

What "Reified as a Bridge" Means in Practice

Reified type parameters exist specifically to recover type information that is erased at runtime. Kotlin erases generic types — a List<String> and a List<Int> are the same List at runtime. Reification retains the type token, making O::class and is O valid at runtime in inline functions.

The pattern here uses reification to bridge two type worlds:

Compile-time world: UseCase<PokemonDetails> — the use case is typed to its output.
Runtime world: StateFlow<ResultState?> — type information is erased at the shared channel level.
Recovery point: parse<O>() — reification reconstructs the type token at the collection site.

This bridge appears at the UI/domain boundary because that's where the erasure is intentional. The ResultState channel should be untyped at the ViewModel level — you want to collect multiple use cases with different output types through a single mechanism. Reification lets you express "I expect this to be of type O" at the point where you actually consume the value, without forcing every use case through a differently-typed channel.

The Path of Breakage

This is where the pattern earns most of its justification, and it's worth being precise about.

Consider what happens without parse<O>(). The raw alternative at the ViewModel collection site would look something like:

useCase.state.collect { state ->
    when (state) {
        is ResultState.Complete<*> -> {
            val data = state.data as? PokemonDetails  // as? cast
            if (data != null) updateState { it.copy(pokemon = data) }
        }
        // ...
    }
}

The as? cast is the failure mode. If state.data is actually a PokemonDto — because a mapping step was accidentally skipped somewhere in the call chain — the cast returns null silently. The UI receives a copy(pokemon = null). Nothing renders. There is no error. No log. No stack trace. A developer debugging this sees a blank screen and starts at square one.

The parse<O>() approach routes that same mismatch differently:

it.takeIf { it is O }
    ?.let { result -> onComplete(result as O?) }
    ?: run { onError(IllegalArgumentException(
        "Expected output of type ${O::class.simpleName}; got ${data?.let { data::class.simpleName }}"
    )) }

The same scenario — PokemonDto where PokemonDetails was expected — now produces an IllegalArgumentException with the message: "Expected output of type PokemonDetails; got PokemonDto." That exception is passed to onError, which routes it to the ViewModel's error state, which renders an error in the UI.

The difference in diagnosability is significant. In QA or during local testing, a visible error with a type name in the message points immediately to the mapping layer. The developer knows which use case is involved (they called getPokemon.collectUseCase<PokemonDetails>), what was expected (PokemonDetails), and what was actually received (PokemonDto). The breakage surface is named, localized, and actionable before the code ever reaches a release branch.

This is the pattern's core value proposition: type mismatches that would silently corrupt state instead generate observable, diagnosable failures during development. The system doesn't prevent the upstream bug — a wrong mapping is still a wrong mapping — but it ensures the downstream symptom is never a mystery. There's a clear and consistent path from breakage to identification.

It also means the pattern scales with the codebase. As more use cases are added, each one follows the same contract. A refactor that changes GetPokemon to return PokemonSummary instead of PokemonDetails doesn't silently break the ViewModel — it loudly breaks at runtime the first time the use case is collected, with a message that names exactly what changed. The type annotation at the call site becomes a lightweight contract test.

The Residual Cost

Naming these benefits doesn't erase the genuine trade-offs.

The type check remains runtime, not compile-time. The compiler cannot catch a mismatch between UseCase<PokemonDto> emitting into collectUseCase<PokemonDetails>. The type guard catches it, but during testing, not during compilation. If your test coverage of the happy-path data flow is thin, the mismatch can reach a release build.

The inline declaration has a direct impact on unit testing. Because collectUseCase is inline, MockK and Mockito cannot mock or spy on it at the function level — you can't assert "was collectUseCase called with the right type." In practice, this turns out to be a non-issue, and arguably a nudge in the right direction: you test the ViewModel by emitting ResultState values from a fake UseCase.state flow and asserting on the resulting ViewModel.state. Since state is a plain StateFlow<ResultState?>, wiring a test double is straightforward — every { useCase.state } returns MutableStateFlow(ResultState.Complete(pokemonDetails)) — and testing the output rather than the wiring is a more meaningful assertion anyway. The one place this becomes relevant is verifying error routing: emitting a ResultState.Complete containing the wrong type (e.g., PokemonDto instead of PokemonDetails) in a test will confirm that onError is invoked with the IllegalArgumentException, giving you a concrete test for the contract the pattern promises.

Inline functions with crossinline lambdas have constraints. The crossinline onDone parameter cannot use non-local returns or call suspend functions directly without explicit suspend on the lambda type. The signature accounts for this — onDone: suspend (O?) -> Unit — but it's a constraint the caller must be aware of.

Three simultaneous generic contexts add cognitive load. A HomeViewModel calling getPokemon.collectUseCase<PokemonDetails> is in BaseViewModel<HomeState> (class generic), calling an extension on UseCase<PokemonDetails> (receiver generic), with its own reified O = PokemonDetails (function generic). That's a lot to hold at once for someone unfamiliar with the pattern.

These costs are real. They're also bounded: the cognitive overhead is paid once when learning the pattern, the compile-time limitation is mitigated by the runtime guard, and the crossinline constraints are surfaced immediately by the compiler when you try to violate them.

When This Pattern Earns Its Complexity

The pattern is justified when all three of the following are true:

You have a shared communication channel that must erase type information (a StateFlow<SealedBase?>).
Consumers need typed access to the payload on the other side (arguably the most important constraint).
Silent type failures are unacceptable — mismatches should be observable and diagnosable (Also, just good practice).

If your use cases emit a different sealed class per output type, you don't need this — the types are preserved all the way to the consumer. If as?-with-null is an acceptable failure mode, you don't need the runtime guard. If the team is small enough that shared conventions can be maintained by proximity, the enforced entry point is just overhead.

But if you're building a ViewModel layer that will be extended by multiple developers across a growing feature set — where the distance between "use case author" and "ViewModel author" creates risk — the combination of a single enforced collection mechanism + explicit type declaration + diagnostic failure routing is a structural answer to a coordination problem. It turns what could be a verbal convention ("always annotate the expected type," "always handle errors") into something the codebase enforces on its own.

Type safety through a type-erased channel isn't a contradiction. It's a deliberate choice about where to bear the cost of erasure, made in favor of visibility over silence.

Lean Caching - A Custom NetworkBoundResource in Kotlin

Tom Horvat — Thu, 26 Mar 2026 16:57:33 +0000

Orchestrating data between a remote API and a local database is a foundational problem in mobile development. While the industry consensus rightly leans toward the Single Source of Truth pattern, the implementation often degrades into massive, fragile repository classes littered with boilerplate try-catch blocks and manual thread switching.

Solving this does not require a heavy, third-party state-management library. A clean, generic networkBoundResource built with Kotlin Flows and Coroutines is highly effective, provided you leverage Kotlin's advanced language features correctly.

Let me explain by demonstrating this pattern in my RandomPokemon project. By focusing on reified generics, inline functions, and structured concurrency, I’ve created a highly fault-tolerant data layer that I drop into my projects to handle caching without the bloat.

State Representation: Rethinking ResultState

Orchestrating complex data flows requires a strict contract for state representation. A standard sealed class handles the basic loading, success, and error states, but the mechanism used to unwrap that state dictates the cleanliness of the presentation layer. The versatility of the ResultState lends itself well to be used in API call returns, I/O operations, or for use cases being observed by the ViewModel.

sealed class ResultState {
    data class Complete<out O>(val data: O?) : ResultState()
    data class Running(val message: String? = null) : ResultState()
    data class Error(val error: Throwable? = null) : ResultState()

    inline fun <reified O> parse(
        onRunning: (String?) -> Unit = {},
        onError: (Throwable?) -> Unit = {},
        onComplete: (O?) -> Unit = {},
    ) {
        when (this) {
            is Running -> onRunning(this.message)
            is Error -> onError(this.error)
            is Complete<*> -> this.data?.let {
                it.takeIf { it is O }?.let { result -> onComplete(result as O?) }
                    ?: run { onError(IllegalArgumentException("Expected output of type ${O::class.simpleName}; got ${data?.let { data::class.simpleName }}")) }
            } ?: run { onComplete(null) }
        }
    }
}

Standard state implementations often force the caller to write repetitive when statements and perform unsafe casts in the UI or ViewModel. I intentionally avoid this by relying on the inline fun parse function to safely handle type checking and casting at runtime. If the type does not match, it gracefully routes to the onError block, preventing an abrupt ClassCastException and keeping the app's crash-free rate intact.

The Orchestrator: networkBoundResource

My core orchestrator is a single, highly optimized function. Relying heavily on inline and crossinline, it eliminates the runtime overhead associated with the higher-order functions passed into it.

inline fun <reified DomainType, reified DtoType> networkBoundResource(
    crossinline query: () -> Flow<ResultState>,
    crossinline fetch: suspend () -> ResultState,
    crossinline saveFetchResult: suspend (DtoType) -> Unit,
    crossinline shouldFetch: (DomainType?) -> Boolean = { it == null },
    crossinline mapDtoToDomain: (DtoType) -> DomainType,
    crossinline onCachePresent: () -> Unit = {}
) = flow {
    emit(ResultState.Running("Checking cache..."))
    val cachedDataResult = query().last()

    var cachedData: DomainType? = null
    cachedDataResult.parse<DomainType>(
        onError = { Timber.w(it, "Cache returned an error.") }
    ) { cachedData = it }

    if (shouldFetch(cachedData)) {
        emit(ResultState.Running("Cache miss. Fetching from remote..."))

        when (val remoteResult = fetch()) {
            is ResultState.Complete<*> -> {
                val dto = remoteResult.data as? DtoType

                if (dto != null) {
                    emit(ResultState.Complete(mapDtoToDomain(dto)))

                    supervisorScope {
                        launch {
                            try {
                                saveFetchResult(dto)
                            } catch (e: Exception) {
                                Timber.e(e, "Failed to save network resource to cache.")
                            }
                        }
                    }
                } else {
                    emit(ResultState.Error(IllegalStateException("Type mismatch: Remote fetch did not return the expected DTO.")))
                }
            }
            is ResultState.Error -> emit(remoteResult)
            is ResultState.Running -> emit(remoteResult)
        }
    } else {
        onCachePresent()
        emit(ResultState.Complete(cachedData!!))
    }
}

Two specific architectural decisions drive this implementation, focusing on performance and fault tolerance:

Immediate UI Emissions: When the remote fetch succeeds, the code emits the Complete state before initiating the database save. Disk I/O is slow. Forcing the UI to wait for Room to finish inserting records is an unnecessary bottleneck. The user gets the mapped domain model instantly.
Detached Caching: Launching saveFetchResult inside a supervisorScope acts as a defensive shield. If the database insertion fails due to a constraint violation or disk issue, the exception is caught and logged by Timber. The overarching coroutine running the Flow does not crash, and the UI retains the successfully fetched in-memory data.

Implementation: Concurrent Caching

An abstraction is only as effective as its call site. Integrating this into my PokemonRepoImpl demonstrates how I handle complex, relational data saving without blocking the thread.

class PokemonRepoImpl(
    private val remote: PokemonRepo.Remote,
    private val local: PokemonRepo.Local,
    private val dispatchers: DispatcherProvider
) : PokemonRepo {
    override fun getPokemonById(id: Long) = networkBoundResource<PokemonDetails, PokemonDto>(
        query = { local.getPokemonById(id) },
        fetch = { remote.getPokemonById(id).last() },
        saveFetchResult = { dto -> cacheRemotePokemon(dto.toDomainModel()) },
        mapDtoToDomain = { dto -> dto.toDomainModel() }
    )

    private suspend fun cacheRemotePokemon(details: PokemonDetails) {
        supervisorScope {
            val saveOperations: List<Pair<String, suspend () -> Unit>> = listOf(
                "pokemon" to { local.savePokemon(details.pokemon) },
                "cries" to { local.saveCries(details.cries) },
                "sprites" to { local.saveSprites(details.sprites) },
                "abilities" to { local.saveAbilities(details.abilities) }
            )

            saveOperations.forEach { (name, action) ->
                launch(dispatchers.io) {
                    try {
                        action()
                    } catch (e: Exception) {
                        Timber.e(e, "Error caching $name")
                    }
                }
            }
        }
    }
}

Mapping a large API payload to a relational database requires splitting the data into multiple tables. Executing these inserts sequentially scales poorly.

By wrapping the inserts in a supervisorScope and iterating through a list of saveOperations with launch(dispatchers.io), this repository performs concurrent database inserts. More importantly, the supervisorScope ensures fault isolation. If the API returns a malformed URL for a sprite that violates a database constraint, that specific coroutine fails and logs an error, but the parent scope remains active, allowing the pokemon, cries, and abilities to be cached successfully.

Final Thoughts

This implementation is my take on a pragmatic approach to Android architecture. Combining reified generics for type safety, inline functions for zero-overhead abstractions, and structured concurrency for fault-tolerant caching - yields a repository layer that is highly readable and extremely resilient. It solves a universal problem by leaning on the language, entirely avoiding the need for bloated external dependencies.

Stop Copying Gradle Code

Tom Horvat — Wed, 25 Mar 2026 20:32:55 +0000

If you've worked on a multi-module Android project, you know the pain: build.gradle.kts files multiplying like rabbits, each containing the exact same Android compileSdk, Kotlin compiler options, and Compose configurations. When you need to bump a version or change a compiler flag, you end up doing a massive "Find and Replace" across 20 different modules.

We know we shouldn't copy and paste application code, yet we routinely accept copy-pasting our build configuration.

It's time to stop. In this article, we'll explore how to use a build-logic module to create custom Gradle convention plugins. By moving boilerplate out of your module-level build files, you can enforce consistency across your entire project and make maintaining your build system a breeze.

To demonstrate, we will reference a real-world implementation from the RandomPokemon repository.

The "After" Picture: A Clean `app/build.gradle.kts`

Before we look at how to build convention plugins, let's look at why we want them.

Here is what the final app/build.gradle.kts looks like after migrating to convention plugins:

plugins {
    // Plugins
    id("myapp.android.application")
    id("myapp.android.compose")
}

dependencies {
    // Modules
    implementation(project(":core"))
    implementation(project(":common"))
    implementation(project(":navigation"))
    implementation(project(":landing"))
    // Module specific dependencies
    implementation(libs.koin)
    implementation(libs.voyager.navigator)
    implementation(libs.timber)
}

NOTE: Starting with Gradle 9, significant changes have been introduced in the way how application and library modules get configured

Notice what’s missing: No compileSdk, no minSdk, no buildFeatures { compose = true }, no Kotlin compiler arguments, and no core Compose dependencies. All of that complex boilerplate is completely hidden behind our custom plugins. The app-level build file is now strictly concerned with things specific to the app module.

Setting Up the `build-logic` Module

To achieve this, we create a completely separate, standalone Gradle build inside our main project directory called build-logic. As with any new module you want to add to your project, for Gradle to know it exists, you must add it to the project level settings.gradle.kts. The only difference is, since this is a build folder, the keyword is different:

// Pre Gradle 9

includeBuild("build-logic") // <-- add this before all other inclusions
include(":app")
...

// Gradle 9
pluginManagement {
    repositories {
        google {
            content {
                includeGroupByRegex("com\\.android.*")
                includeGroupByRegex("com\\.google.*")
                includeGroupByRegex("androidx.*")
            }
        }
        mavenCentral()
        gradlePluginPortal()
    }
    includeBuild("build-logic") // <-- the includeBuild instruction gets moved to the pluginManagement block
}

Because it's an isolated build, Gradle doesn't automatically know about our primary project's version catalog (libs.versions.toml). We need to explicitly link it. Also, add entries into the catalog so that the Gradle script can reach them:

// Pre Gradle 9
[versions]
agp = "8.13.2"
kotlin = "2.3.20"
room = "2.8.4"
...
[libraries]
android-gradle = { group = "com.android.tools.build", name = "gradle", version.ref = "agp" }
kotlin-gradle = { group = "org.jetbrains.kotlin", name = "kotlin-gradle-plugin", version.ref = "kotlin" }
room-gradle = { group = "androidx.room", name = "room-gradle-plugin", version.ref = "room" }
...

// Gradle 9 introduces builtIn Kotlin so we need to remove it from the plugins block

[versions]
# Gradle & Kotlin
agp = "9.1.0"
kotlin = "2.3.20"
ksp = "2.3.6"

# Data
room = "2.8.4"
...

[libraries]
# Gradle & Kotlin Plugins
android-gradle = { group = "com.android.tools.build", name = "gradle", version.ref = "agp" }
kotlin-gradle = { group = "org.jetbrains.kotlin", name = "kotlin-gradle-plugin", version.ref = "kotlin" }
room-gradle = { group = "androidx.room", name = "room-gradle-plugin", version.ref = "room" }
...

[plugins]
android-application = { id = "com.android.application", version.ref = "agp" }
android-library = { id = "com.android.library", version.ref = "agp" }
kotlin-compose = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }
ksp = { id = "com.google.devtools.ksp", version.ref = "ksp" }
room = { id = "androidx.room", version.ref = "room" }
// the kotlin-android plugin has been removed
// kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }

NOTE: gradle.properties will also be edited when you migrate from Gradle 8 to 9, feel free to clean up everything you do not need or use. I am still dependent on the newDsl = false flag since the official protobuf plugin that I am using is not compatible with Gradle 9 features

Gradle 9 only

The kotlin.android plugin needs to be removed from your project level gradle.build.kt .

1. Linking the Version Catalog (`build-logic/settings.gradle.kts`)

Create a settings.gradle.kts file inside your new build-logic directory. We need to tell this separate build where to find our shared versions and dependencies:

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
    versionCatalogs {
        create("libs") {
            from(files("../gradle/libs.versions.toml")) // <-- This points to your version catalog
        }
    }
}

2. Configuring Dependencies (`build-logic/build.gradle.kts`)

Next, inside build-logic/build.gradle.kts, we define the dependencies that our plugins will need to compile. We use compileOnly so we don't force our plugin's AGP/Kotlin versions onto the project that consumes this plugin.

This is also where we register our plugins so Gradle knows what ID maps to which class:

plugins {
    `kotlin-dsl`
}

dependencies {
    compileOnly(libs.android.gradle)
    compileOnly(libs.kotlin.gradle)
    compileOnly(libs.room.gradle)
}

gradlePlugin {
    plugins {
        register("myapp.android.library") {
            id = "myapp.android.library"
            implementationClass = "AndroidLibraryConventionPlugin"
        }

        register("myapp.android.application") {
            id = "myapp.android.application"
            implementationClass = "AndroidApplicationConventionPlugin"
        }

        register("myapp.android.compose") {
            id = "myapp.android.compose"
            implementationClass = "AndroidComposeConventionPlugin"
        }
    }
}

Creating the Plugins

Now for the fun part: writing the actual plugins. In build-logic/src/main/kotlin/, we write standard Kotlin classes that implement Gradle's Plugin<Project> interface.

A Focused, Reusable Plugin: `ProjectPluginExtensions.kt`

First, let's look at how to centralize base Android and Kotlin configuration. The best practice here is to write an extension function that configures the CommonExtension (which both Android Libraries and Android Applications use), and then call that function from a concrete Plugin class.

Here is the setup and the usage example of how it gets applied:

// Pre Gradle 9
internal fun Project.configureKotlinAndroid(
    commonExtension: CommonExtension<*, *, *, *, *, *>,
) {
    commonExtension.apply {
        compileSdk = 36
        defaultConfig {
            minSdk = 31
        }

        compileOptions {
            sourceCompatibility = JavaVersion.VERSION_21
            targetCompatibility = JavaVersion.VERSION_21
        }
    }

    tasks.withType<KotlinCompile>().configureEach {
        compilerOptions {
            jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_21)
        }
    }
}

// Gradle 9:
internal fun Project.configureKotlinAndroid(
    commonExtension: CommonExtension, // <-- CommonExtension does not accept type parameters
) {
    commonExtension.apply {
        compileSdk = 36

        defaultConfig.apply { // <-- change in method of accessing the minSdk property
            minSdk = 31
        }

        compileOptions.apply { // <-- change in method of accessing the compileOptions property
            sourceCompatibility = JavaVersion.VERSION_21
            targetCompatibility = JavaVersion.VERSION_21
        }
    }

    tasks.withType<KotlinCompile>().configureEach {
        compilerOptions {
            jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_21)
        }
    }
}

// Pre Gradle 9
class AndroidLibraryConventionPlugin : Plugin<Project> {
    override fun apply(target: Project) {
        with(target) {
            pluginManager.apply("com.android.library")
            pluginManager.apply("org.jetbrains.kotlin.android")

            extensions.configure<LibraryExtension> {
                configureKotlinAndroid(this) // <-- Use the extension function with the LibraryExtension

                // Set library specific flags, general build type configuration, etc.
            }
        }
    }
}

// Gradle 9
import com.android.build.api.dsl.LibraryExtension // <-- New import for LibraryExtension

class AndroidLibraryConventionPlugin : Plugin<Project> {
    override fun apply(target: Project) {
        with(target) {
            pluginManager.apply("com.android.library")
            // pluginManager.apply("org.jetbrains.kotlin.android") <-- this in not needed anymore

            extensions.configure<LibraryExtension> {
                configureKotlinAndroid(this) // <-- Use the extension function with the LibraryExtension

                // Set library specific flags, general build type configuration, etc.
            }
        }
    }
}

By splitting the logic, an AndroidLibraryConventionPlugin can easily call configureKotlinAndroid(this) on its LibraryExtension, guaranteeing identical setups across your entire project. The same logic applies to a BaseAppModuleExtension:

// Pre Gradle 9
class AndroidApplicationConventionPlugin : Plugin<Project> {
    override fun apply(target: Project) {
        with(target) {
            pluginManager.apply("com.android.application")
            pluginManager.apply("org.jetbrains.kotlin.android")

            extensions.configure<BaseAppModuleExtension> {
                configureKotlinAndroid(this) // <-- Use the extension function with the BaseAppModuleExtension

                // Set app module specific flags
                namespace = "com.example.myapp"

                defaultConfig {
                    applicationId = "com.example.myapp"
                    targetSdk = 36
                    versionCode = 1
                    versionName = "1.0.0"
                }
            }
        }
    }
}

// Gradle 9
import com.android.build.api.dsl.ApplicationExtension

class AndroidApplicationConventionPlugin : Plugin<Project> {
    override fun apply(target: Project) {
        with(target) {
            pluginManager.apply("com.android.application")
            // pluginManager.apply("org.jetbrains.kotlin.android") <-- this in not needed anymore 

            extensions.configure<ApplicationExtension> { // <-- Different extension class
                configureKotlinAndroid(this) // <-- Use the extension function with the BaseAppModuleExtension

                // Set app module specific flags
                namespace = "com.example.myapp"

                defaultConfig {
                    applicationId = "com.example.myapp"
                    targetSdk = 36
                    versionCode = 1
                    versionName = "1.0.0"
                }
            }
        }
    }
}

A Complex Plugin: `AndroidComposeConventionPlugin.kt`

Sometimes a plugin needs to do more than just set flags—it needs to pull in dependencies and configure specific tooling features. Compose is a perfect candidate for this.

Here is an example of a plugin that configures Compose and injects required dependencies directly into the module applying it:

class RandomPokemonAndroidComposeConventionPlugin : Plugin<Project> {
    override fun apply(target: Project) {
        with(target) {
            val libs = extensions.getByType<VersionCatalogsExtension>().named("libs")

            pluginManager.apply("org.jetbrains.kotlin.plugin.compose")

            pluginManager.withPlugin("com.android.application") {
                extensions.configure<ApplicationExtension> {
                    buildFeatures.compose = true
                }
            }
            pluginManager.withPlugin("com.android.library") {
                extensions.configure<LibraryExtension> {
                    buildFeatures.compose = true
                }
            }

            dependencies {
                "implementation"(platform(libs.findLibrary("androidx.compose.bom").get()))
                "implementation"(libs.findLibrary("androidx.ui").get())
                "implementation"(libs.findLibrary("androidx.ui.tooling.preview").get())
                "implementation"(libs.findLibrary("androidx.material3").get())
            }
        }
    }
}

By applying this single plugin, any module in your project that implements this plugin immediately gets Compose enabled, the correct Compose compiler linked, the BOM applied, and the tooling dependencies configured. If you ever need to update the Compose BOM or compiler, you do it centrally in your version catalog. Your feature module is clean and only lists specific flags and dependencies particular to it.

 plugins {
    id("myapp.android.library")
    id("myapp.android.compose")
}

android {
    namespace = "io.bitbot.bemusedbaboon.landing"
}

dependencies {

    implementation(project(":core"))
    implementation(project(":common"))
    implementation(project(":navigation"))

    implementation(libs.timber)

    implementation(libs.koin)
    implementation(libs.koin.compose)

    implementation(libs.voyager.navigator)

    implementation(libs.coil.compose)
    implementation(libs.coil.network)
}

Bonus: Dynamically Generating Library Namespaces

If you want to take your boilerplate reduction a step further, look at how you declare namespaces in your library modules.

Typically, every library's build.gradle.kts requires an android block just to declare a deeply nested namespace:

android { 
    namespace = "com.example.myapp.commons" 
}

Since the base namespace com.example.myapp never changes, repeating it across dozens of modules is prone to typos and adds unnecessary noise. Because our build-logic is written in Kotlin, we can create a simple top-level extension function to handle this for us.

1. The Helper Function (`build-logic/src/man/kotlin/ProjectPluginExtensions.kt` )

Create a new Kotlin file in your convention plugin source directory. We'll define our base namespace as a constant and write an extension function on Project that configures the LibraryExtension:

// Define your single source of truth for the base namespace
private const val BASE_NAMESPACE = "com.example.myapp"

/**
 * Automatically applies the base namespace and appends the provided suffix.
 */
fun Project.libraryNamespace(suffix: String) {
    extensions.configure<LibraryExtension> {
        namespace = "$BASE_NAMESPACE.$suffix"
    }
}

2. The Final Library `build.gradle.kts`

Now, you can completely eliminate the android { ... } block from your library modules. Whenever you create a new library, you simply call your custom function directly in the build script:

plugins {
    id("myapp.android.library")
    id("myapp.android.room")
}

libraryNamespace("commons")

dependencies {
    ...
}

By adding this tiny extension function, your library build scripts become incredibly concise, and your project enforces a strict, typo-free naming convention for all module namespaces.

Conclusion

Migrating your Gradle build configuration to custom convention plugins requires an initial upfront investment, but the ROI is massive:

Readability: Module-level build.gradle.kts files become declarative summaries of what a module is, rather than a script of how it compiles.
Safety: New modules are guaranteed to use the correct compiler flags, Java targets, and core dependencies.
Maintainability: Updating your project to a new Java version, bumping compileSdk, or changing compiler arguments happens in exactly one place.

Stop copying Gradle code. Treat your build configuration with the same architectural respect you give to your application architecture. Your future self—and your team—will thank you.