offline-first

Offline-First Architecture Patterns

NetworkBoundResource Pattern

The core abstraction that coordinates cache and network data sources.

inline fun <ResultType, RequestType> networkBoundResource(
    crossinline query: () -> Flow<ResultType>,
    crossinline fetch: suspend () -> RequestType,
    crossinline saveFetchResult: suspend (RequestType) -> Unit,
    crossinline shouldFetch: (ResultType) -> Boolean = { true },
    crossinline onFetchFailed: (Throwable) -> Unit = { }
): Flow<Resource<ResultType>> = flow {
    val cachedData = query().first()

    val result = if (shouldFetch(cachedData)) {
        emit(Resource.Loading(cachedData))
        try {
            saveFetchResult(fetch())
            query().map { Resource.Success(it) }
        } catch (e: Exception) {
            if (e is CancellationException) throw e // never swallow cancellation
            onFetchFailed(e)
            // Surface the failure to the UI while still serving cached data
            query().map { Resource.Error(e.message ?: "Fetch failed", it) }
        }
    } else {
        query().map { Resource.Success(it) }
    }

    emitAll(result)
}

Resource Wrapper

sealed class Resource<out T> {
    data class Success<T>(val data: T) : Resource<T>()
    data class Loading<T>(val data: T? = null) : Resource<T>()
    data class Error<T>(val message: String, val data: T? = null) : Resource<T>()
}

Usage in Repository

class ArticleRepository(
    private val api: ArticleApi,
    private val dao: ArticleDao,
    private val cachePolicy: CachePolicy
) {
    fun getArticles(): Flow<Resource<List<Article>>> = networkBoundResource(
        query = { dao.observeAll() },
        fetch = { api.getArticles() },
        saveFetchResult = { articles ->
            // Room @Transaction DAO method (deleteAll + insertAll atomically);
            // in SQLDelight wrap in queries.transaction { }
            dao.replaceAll(articles.map { it.toEntity() })
            // Stamp freshness only after a successful write, or isExpired() stays true
            // forever and every collection refetches.
            cachePolicy.markFresh("articles")
        },
        shouldFetch = { cachedArticles ->
            cachedArticles.isEmpty() || cachePolicy.isExpired("articles")
        }
    )
}