A set of solutions for operating on a global cache. Heavily inspired by:

• React Query
• swr-compose.

Platforms: JVM, Android, iOS (x64/arm64/simulator), WASM-JS

CacheOnHand provides the following:

• Modularization that allows for taking ONLY what you need
• No enforcement of UI framework - the barebones are compose agnostic
• A familiar API for users coming from a react query, or SWR like framework
• Transactional optimistic cache updates, that can rollback on error. Allowing for a snappy UI experience
• Tools operating on your cache as a Query, Mutation, InfiniteQuery, or Flow
• Typed refetch() and optimisticUpdater() functions that exist at definition (not at use), and are usable anywhere

• Persisting outside the local cache
• Cache viewer plugin
• Integration with data fetching frameworks

Cache On Hand is split into three modules that build on each other. Use only what you need:

Each module transitively includes its dependencies — adding cacheonhand-compose gives you everything.

// build.gradle.kts
dependencies {
    // Pick one — each includes its dependencies
    implementation("io.github.notoriouscorgi:cacheonhand:<version>")              // cache only
    implementation("io.github.notoriouscorgi:cacheonhand-attendants:<version>")  // cache + operations
    implementation("io.github.notoriouscorgi:cacheonhand-compose:<version>")     // cache + operations + compose
}

// Define a cache key
data class GetUserInput(val userId: String) : CacheableInput.QueryInput {
    override val identifier = "GET /api/users/$userId"
}

// Create a shared cache
val cache = OnHandCache()

// Define a query factory
val getUserFactory = queryFactoryOf<GetUserInput, User, ApiException>(
    cache = cache,
) {
    withContext(Dispatchers.IO) { input ->
        api.getUser(input.userId)
    }
}

// Query your data
val queryAndResult = getUserFactory()

// Start listening to results
queryAndResult.result.collect { ... }

// Fetch your query
viewModelScope.launch {
    queryAndResult.fetch(GetUserInput(1))
}


// Wrap for Compose
val rememberGetUser = composeQueryFactoryOf(getUserFactory)

// Use in a composable
@Composable
fun UserScreen(userId: String) {
    val result = rememberGetUser(input = GetUserInput(userId))

    when (result.fetchState) {
        FetchState.LOADING -> CircularProgressIndicator()
        FetchState.SUCCESS -> Text("Hello, ${result.data?.name}")
        FetchState.ERROR -> Text("Error: ${result.error?.message}")
        FetchState.IDLE -> {}
    }
}

Refresh query data after a mutation by calling refetch in onSuccess:

val mutation = updateUserFactory.create()

mutation.mutate(
    queryInput = UpdateUserInput("123", "New Name"),
    onSuccess = { _ ->
        getUserFactory.refetch(GetUserInput("123"))
        // All active query instances observing this key update automatically
    },
)

// Use launch() for fire-and-forget refetches (e.g., refreshing data not currently on screen)
mutation.mutate(
    queryInput = UpdateUserInput("123", "New Name"),
    onSuccess = { _ ->
        scope.launch { getUserFactory.refetch(GetUserInput("123")) }
    },
)

• Queries — fetch data with automatic caching, TTL, and refetch
• Mutations — write operations with optimistic updates and automatic rollback
• Flows — subscribe to reactive sources (SSE, WebSockets) with cached emissions
• Infinite Queries — paginated data with forward/backward navigation
• Optimistic Updates — instant UI updates that revert on failure
• Stale-While-Revalidate — show cached data while refetching in the background
• TTL Eviction — automatic cache entry expiry
• Thread Safety — per-key mutex locking with deadlock prevention
• Compose Integration — composable hooks with lifecycle-aware scoping
• Type-Safe Errors — generic TError parameter instead of raw Throwable
• Factory Pattern — define once, use everywhere

These assumptions apply across all modules:

• Cache keys must be data classes — the cache uses HashMap internally. Regular classes without proper equals/ hashCode will silently create duplicate entries. Always use data class for your CacheableInput implementations.
• Operations run on Dispatchers.Default — use withContext(Dispatchers.IO) inside your query/mutation/flow lambda for network or disk calls.
• Don't use launch/async without awaiting inside factory lambdas — the operation must complete sequentially so state transitions (LOADING -> SUCCESS/ERROR) are correct. However, launch/async is fine inside onSuccess/ onError callbacks — those run after state transitions are complete.
• refetch() throws on failure — unlike fetch() which catches errors and sets ERROR state, refetch() propagates exceptions to the caller. Wrap in try-catch or scope.launch.
• Null data is not an error — a query or flow returning null sets state to SUCCESS with null data, not ERROR. This is intentional for distinguishing "no data exists" from "fetch failed".

./gradlew build

# All modules
./gradlew cacheonhand:jvmTest cacheonhand-attendants:jvmTest cacheonhand-compose:jvmTest

# Single module
./gradlew cacheonhand:jvmTest
./gradlew cacheonhand-attendants:jvmTest
./gradlew cacheonhand-compose:jvmTest

Create a release and publish to Maven Central:

./scripts/release.sh         # auto-increments minor version (0.1.0 → 0.2.0)
./scripts/release.sh 1.0.0   # explicit version

Or trigger directly from GitHub Actions (Actions -> Publish -> Run workflow) with an optional version input.

The workflow runs tests first, then publishes all three modules to Maven Central.

Generates API documentation from source and READMEs into docs/ for GitHub Pages:

./gradlew :dokkaGenerate

Licensed under the Apache License, Version 2.0