kmp-repositories

KMP Repository Pattern

Implement the repository pattern with shared interfaces in commonMain and platform-specific implementations.

Architecture Overview

Presentation   ViewModels · Composables · SwiftUI
     ↓
Domain         use cases
     ↓
Data           Repository interface        (commonMain)
               Repository implementation   (commonMain: coordinates sources,
                                            caching strategy, error mapping)
               Data sources                Remote (network) · Local (database)
                                           · Memory (cache)

Repository Interface

// commonMain/kotlin/data/repository/UserRepository.kt
interface UserRepository {
    // Single shot
    suspend fun getUser(id: String): Result<User>
    suspend fun getUsers(page: Int): Result<PaginatedResponse<User>>
    suspend fun saveUser(user: User): Result<User>
    suspend fun deleteUser(id: String): Result<Unit>

    // Streams
    fun observeUser(id: String): Flow<Result<User>>
    fun observeUsers(): Flow<Result<List<User>>>

    // Cache control
    suspend fun refreshUser(id: String): Result<User>
    suspend fun refreshAll(): Result<Unit>
    suspend fun clearCache(): Result<Unit>
}

kotlin.Result is an inline value class, and the Kotlin/Native Objective-C export maps inline classes to their underlying type or id — Swift cannot unwrap one. Keep Result inside shared code and convert at the iOS boundary (sealed wrapper, or a shared ViewModel exposing state): see error-handling-result and kmp-ios-integration.

Base Repository

// commonMain/kotlin/data/repository/BaseRepository.kt
abstract class BaseRepository {
    // Execute with error handling.
    // NetworkException/DataException are app-defined error types.
    protected suspend fun <T> execute(
        block: suspend () -> T
    ): Result<T> = try {
        Result.success(block())
    } catch (e: CancellationException) {
        throw e
    } catch (e: NetworkException) {
        Result.failure(e)
    } catch (e: Exception) {
        Result.failure(DataException(cause = e))
    }

    // Wrap a Flow's emissions in Result. Use the .catch operator — a
    // try/catch around collect inside a flow {} builder violates flow
    // exception transparency and can throw IllegalStateException at runtime.
    protected fun <T> flowResult(
        block: () -> Flow<T>
    ): Flow<Result<T>> = block()
        .map { Result.success(it) }
        .catch { e -> emit(Result.failure(e)) }

    // Cache-first strategy: return cache hit, otherwise fetch and persist
    protected suspend fun <T> cacheFirst(
        cacheBlock: suspend () -> T?,
        networkBlock: suspend () -> T,
        saveBlock: suspend (T) -> Unit
    ): Result<T> = execute {
        cacheBlock() ?: networkBlock().also { saveBlock(it) }
    }

    // Network-first strategy: fall back to cache only on network errors
    protected suspend fun <T> networkFirst(
        cacheBlock: suspend () -> T?,
        networkBlock: suspend () -> T
    ): Result<T> = execute {
        try {
            networkBlock()
        } catch (e: NetworkException) {
            cacheBlock() ?: throw e
        }
    }

    // Refresh strategy
    protected suspend fun <T> refresh(
        networkBlock: suspend () -> T,
        cacheBlock: suspend (T) -> Unit
    ): Result<T> = execute {
        val result = networkBlock()
        cacheBlock(result)
        result
    }
}