mcpField
K
kmp-repositories

kmp-repositories

github.com/ahmed3elshaerDevelopment6648 installsUpdated 19w ago
Repository

About kmp-repositories

A repository-pattern guide for Kotlin Multiplatform projects, placing interfaces in commonMain and coordinating remote and local data sources through platform-specific implementations. It also covers use cases, dependency injection, database adaptation, and testing.

Key features

  1. 01Define repository interfaces in commonMain
  2. 02Coordinate remote, local, and memory data sources
  3. 03Wrap error handling with Result
  4. 04Expose state with Flow
  5. 05Use platform-specific database factory patterns

Use cases

  1. 01Build a cross-platform data access layer
  2. 02Combine local and remote data sources
  3. 03Isolate platform-specific database implementations
  4. 04Write unit tests for repositories

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/ahmed3elshaer/everything-claude-code-mobile --skill kmp-repositories

After installing, type/kmp-repositoriesin Claude Code to confirm it loaded.

Details

From the project README

KMP Repository Pattern

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

Architecture Overview

┌─────────────────────────────────────────────────────────┐
│                    Presentation Layer                    │
│              (ViewModels, Composables, SwiftUI)          │
└──────────────────────────┬──────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────┐
│                    Domain Layer                          │
│                    (Use Cases)                           │
└──────────────────────────┬──────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────┐
│                    Data Layer                            │
│  ┌──────────────────────────────────────────────────┐   │
│  │         Repository Interface (commonMain)         │   │
│  └──────────────────────┬───────────────────────────┘   │
│                         │                               │
│  ┌──────────────────────▼───────────────────────────┐   │
│  │      Repository Implementation (commonMain)      │   │
│  │  - Coordinates data sources                      │   │
│  │  - Caching strategy                              │   │
│  │  - Error mapping                                 │   │
│  └──────────────────────┬───────────────────────────┘   │
│                         │                               │
│  ┌──────────────────────▼───────────────────────────┐   │
│  │              Data Sources                        │   │
│  │  ┌────────────┐  ┌────────────┐  ┌───────────┐  │   │
│  │  │   Remote   │  │   Local    │  │   Memory  │  │   │
│  │  │ (Network)  │  │ (Database) │  │  (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>
}

Base Repository

// commonMain/kotlin/data/repository/BaseRepository.kt
abstract class BaseRepository {
    // Execute with error handling
    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))
    }

    // Flow with error handling
    protected fun <T> flowResult(
        block: suspend () -> Flow<T>
    ): Flow<Result<T>> = flow {
        try {
            block().collect { emit(Result.success(it)) }
        } catch (e: CancellationException) {
            throw e
        } catch (e: Exception) {
            emit(Result.failure(e))
        }
    }

    // Cache-first strategy
    protected suspend fun <T> cacheFirst(
        cacheKey: String,
        ttl: Duration,
        cacheBlock: suspend () -> T?,
        networkBlock: suspend () -> T
    ): Result<T> = execute {
        // Try cache
        cacheBlock()?.let { return@execute it }

        // Fetch from network
        val result = networkBlock()

        // Update cache
        // saveToCache(cacheKey, result)

        result
    }

    // Network-first strategy
    protected suspend fun <T> networkFirst(
        cacheKey: String,
        cacheBlock: suspend () -> T?,
        networkBlock: suspend () -> T
    ): Result<T> = execute {
        try {
            // Try network first
            val result = networkBlock()
            // Update cache
            result
        } catch (e: NetworkException) {
            // Fall back to cache
            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
    }
}

Concrete Repository

// commonMain/kotlin/data/repository/UserRepositoryImpl.kt
class UserRepositoryImpl(
    private val remoteDataSource: UserRemoteDataSource,
    private val localDataSource: UserLocalDataSource,
    private val memoryCache: MemoryCache,
    private val dispatcher: CoroutineDispatcher = PlatformDispatchers.io
) : BaseRepository(), UserRepository {

    override suspend fun getUser(id: String): Result<User> =
        networkFirst(
            cacheKey = "user:$id",
            cacheBlock = { localDataSource.getUser(id) },
            networkBlock = { remoteDataSource.getUser(id).also { user ->
                localDataSource.saveUser(user)
                memoryCache.put("user:$id", user)
            }}
        )

    override suspend fun getUsers(page: Int): Result<PaginatedResponse<User>> =
        execute {
            remoteDataSource.getUsers(page).also { response ->
                localDataSource.saveUsers(response.items)
            }
        }

    override suspend fun saveUser(user: User): Result<User> =
        execute {
            remoteDataSource.createUser(user).also { savedUser ->
                localDataSource.saveUser(savedUser)
                memoryCache.put("user:${savedUser.id}", savedUser)
            }
        }

    override suspend fun deleteUser(id: String): Result<Unit> =
        execute {
            remoteDataSource.deleteUser(id).also {
                localDataSource.deleteUser(id)
                memoryCache.remove("user:$id")
            }
        }

    override fun observeUser(id: String): Flow<Result<User>> =
        flowResult {
            localDataSource.observeUser(id)
        }

    override fun observeUsers(): Flow<Result<List<User>>> =
        flowResult {
            localDataSource.observeAllUsers()
        }

    override suspend fun refreshUser(id: String): Result<User> =
        refresh(
            networkBlock = { remoteDataSource.getUser(id) },
            cacheBlock = { user -> localDataSource.saveUser(user) }
        )

    override suspend fun refreshAll(): Result<Unit> =
        execute {
            remoteDataSource.getUsers(page = 1).items.forEach { user ->
                localDataSource.saveUser(user)
            }
        }

    override suspend fun clearCache(): Result<Unit> =
        execute {
            localDataSource.clearAll()
            memoryCache.clear()
        }
}

Data Sources

Remote Data Source
// commonMain/kotlin/data/datasource/remote/UserRemoteDataSource.kt
interface UserRemoteDataSource {
    suspend fun getUser(id: String): User
    suspend fun getUsers(page: Int): PaginatedResponse<User>
    suspend fun createUser(user: User): User
    suspend fun updateUser(id: String, user: User): User
    suspend fun deleteUser(id: String)
}

class UserRemoteDataSourceImpl(
    private val api: UserApi
) : UserRemoteDataSource {
    override suspend fun getUser(id: String): User = api.getUser(id)
    override suspend fun getUsers(page: Int): PaginatedResponse<User> = api.getUsers(page)
    override suspend fun createUser(user: User): User = api.createUser(user)
    override suspend fun updateUser(id: String, user: User): User = api.updateUser(id, user)
    override suspend fun deleteUser(id: String) = api.deleteUser(id)
}
Local Data Source
// commonMain/kotlin/data/datasource/local/UserLocalDataSource.kt
interface UserLocalDataSource {
    suspend fun getUser(id: String): User?
    suspend fun getAllUsers(): List<User>
    suspend fun saveUser(user: User)
    suspend fun saveUsers(users: List<User>)
    suspend fun deleteUser(id: String)
    suspend fun clearAll()
    fun observeUser(id: String): Flow<User>
    fun observeAllUsers(): Flow<List<User>>
}

class UserLocalDataSourceImpl(
    private val database: AppDatabase
) : UserLocalDataSource {
    override suspend fun getUser(id: String): User? =
        database.userQueries().getById(id).executeAsOneOrNull()?.toDomain()

    override suspend fun getAllUsers(): List<User> =
        database.userQueries().getAll().executeAsList().map { it.toDomain() }

    override suspend fun saveUser(user: User) =
        database.userQueries().insert(user.toEntity())

    override suspend fun saveUsers(users: List<User>) =
        database.transaction {
            users.forEach { saveUser(it) }
        }

    override suspend fun deleteUser(id: String) =
        database.userQueries().deleteById(id)

    override suspend fun clearAll() =
        database.userQueries().deleteAll()

    override fun observeUser(id: String): Flow<User> =
        database.userQueries().getById(id).asFlow().map { it.executeAsOneOrNull()?.toDomain() }
        .filterNotNull()

    override fun observeAllUsers(): Flow<List<User>> =
        database.userQueries().getAll().asFlow().map { it.executeAsList().map { entity -> entity.toDomain() } }
}

Use Cases

// commonMain/kotlin/domain/usecase/GetUserUseCase.kt
class GetUserUseCase(
    private val repository: UserRepository
) {
    suspend operator fun invoke(id: String): Result<User> =
        repository.getUser(id)
}

// commonMain/kotlin/domain/usecase/ObserveUserUseCase.kt
class ObserveUserUseCase(
    private val repository: UserRepository
) {
    operator fun invoke(id: String): Flow<Result<User>> =
        repository.observeUser(id)
}

// commonMain/kotlin/domain/usecase/RefreshUserDataUseCase.kt
class RefreshUserDataUseCase(
    private val repository: UserRepository
) {
    suspend operator fun invoke(id: String): Result<User> =
        repository.refreshUser(id)
}

Dependency Injection

// commonMain/kotlin/di/DataModule.kt
val dataModule = module {
    // Data sources
    single { UserApi(get()) }
    single<UserRemoteDataSource> { UserRemoteDataSourceImpl(get()) }

    // Local data source
    single { createDatabase(get()) }
    single<UserLocalDataSource> { UserLocalDataSourceImpl(get()) }

    // Memory cache
    single { MemoryCache() }

    // Repositories
    single<UserRepository> { UserRepositoryImpl(get(), get(), get()) }

    // Use cases
    factory { GetUserUseCase(get()) }
    factory { ObserveUserUseCase(get()) }
    factory { RefreshUserDataUseCase(get()) }
}

Platform-Specific Database

// commonMain/kotlin/database/DatabaseFactory.kt
expect class DatabaseFactory {
    fun create(): AppDatabase
}

// Android implementation
actual class DatabaseFactory(private val context: Context) {
    actual fun create(): AppDatabase =
        Room.databaseBuilder(
            context,
            AppDatabase::class.java,
            "app.db"
        ).build()
}

// iOS implementation
actual class DatabaseFactory {
    actual fun create(): AppDatabase {
        val dbPath = NSSearchPathForDirectoriesInDomains(
            NSDocumentDirectory,
            NSUserDomainMask,
            true
        ).first() as String
        return AppDatabase("$dbPath/app.db")
    }
}

Repository Testing

// commonTest/kotlin/data/repository/UserRepositoryTest.kt
class UserRepositoryTest {
    private lateinit var repository: UserRepository
    private lateinit var mockRemote: UserRemoteDataSource
    private lateinit var mockLocal: UserLocalDataSource

    @BeforeTest
    fun setup() {
        mockRemote = mockk()
        mockLocal = mockk()
        repository = UserRepositoryImpl(
            remoteDataSource = mockRemote,
            localDataSource = mockLocal,
            memoryCache = MemoryCache()
        )
    }

    @Test
    fun `returns cached user when available`() = runTest {
        val cachedUser = User(id = "123", name = "John")
        coEvery { mockLocal.getUser("123") } returns cachedUser

        val result = repository.getUser("123")

        assertTrue(result.isSuccess)
        assertEquals(cachedUser, result.getOrNull())
        coVerify { mockRemote wasNot Called }
    }

    @Test
    fun `fetches from network when cache empty`() = runTest {
        val networkUser = User(id = "123", name = "John")
        coEvery { mockLocal.getUser("123") } returns null
        coEvery { mockRemote.getUser("123") } returns networkUser
        coEvery { mockLocal.saveUser(any()) } just Runs

        val result = repository.getUser("123")

        assertTrue(result.isSuccess)
        assertEquals(networkUser, result.getOrNull())
        coVerify { mockRemote.getUser("123") }
        coVerify { mockLocal.saveUser(networkUser) }
    }
}

Best Practices

✅ DO
// ✅ Define interfaces in commonMain
interface UserRepository { ... }

// ✅ Return Result for error handling
suspend fun getUser(id: String): Result<User>

// ✅ Expose Flow for state
fun observeUser(id: String): Flow<User>

// ✅ Use base repository for common patterns
class UserRepositoryImpl : BaseRepository() { ... }

// ✅ Keep repositories platform-agnostic
// No Android/iOS specific code in repository implementations
❌ DON'T
// ❌ Don't expose platform types
suspend fun getUser(): SQLiteDatabase  // ❌
suspend fun getUser(): User  // ✅

// ❌ Don't put business logic in repositories
if (user.age < 18) throw Exception()  // ❌ belongs in use case

// ❌ Don't make repositories depend on each other
// Use use cases to coordinate

// ❌ Don't use global state
object UserRepository { ... }  // ❌ use DI

Remember: Repositories are your data gatekeepers. Keep them platform-agnostic, testable, and focused on data coordination.

Comments

Markdown supported