Offline Queue

The offline queue buffers mutating requests (create, update, delete) when the device is offline and replays them in order when connectivity is restored.

Reads (list, get) are not queued — they need fresh data from the server.

Setup

Enable auto-flush on app launch. The queue uses ConnectivityManager.NetworkCallback to detect when the network becomes reachable.

// Application.onCreate (recommended) or Activity.onCreate
client.offlineQueue.startMonitoring(applicationContext)

Requires ACCESS_NETWORK_STATE permission — already declared in the SDK’s manifest, so no extra setup needed in your app.

Enqueue a mutation

Enqueue a mutation when you detect the device is offline:

try {
    posts.create(newPost)
} catch (e: BunBaseError.NetworkError) {
    client.offlineQueue.enqueue("POST", "/api/v1/posts", body = newPost)
}

Object body (serialised to JSON)

data class NewPost(val title: String, val body: String)
client.offlineQueue.enqueue("POST", "/api/v1/posts", body = NewPost("Hello", "World"))

Raw JSON string

val json = """{"title":"Hello","body":"World"}"""
client.offlineQueue.enqueue("POST", "/api/v1/posts", bodyJson = json)

Delete / patch

client.offlineQueue.enqueue("DELETE", "/api/v1/posts/${post.id}")
client.offlineQueue.enqueue("PATCH",  "/api/v1/posts/${post.id}", body = mapOf("title" to "Updated"))

Flush results

Listen for per-item results after a flush:

client.offlineQueue.onFlushResult = { id, error ->
    if (error != null) {
        Log.e("BunBase", "[$id] failed: $error")
    } else {
        Log.d("BunBase", "[$id] replayed successfully")
    }
}

Flush behaviour by response:

Server response	Result
2xx	Item removed from queue, onFlushResult(id, null)
4xx	Item removed (permanent failure), onFlushResult(id, error)
5xx / network	Item kept, onFlushResult(id, error) — will retry next flush

Manual flush

lifecycleScope.launch {
    client.offlineQueue.flush()
}

Inspect the queue

val count = client.offlineQueue.pendingCount        // Int
val pending = client.offlineQueue.items             // List<QueuedMutation>

Clear the queue

Discards all pending mutations without replaying them.

client.offlineQueue.clear()

Stop monitoring

client.offlineQueue.stopMonitoring()

Persistence

The queue is persisted to SharedPreferences as JSON and survives process death. Auth tokens are refreshed automatically during replay — no extra setup needed.

ViewModel pattern

class PostViewModel : ViewModel() {
    fun createPost(title: String, body: String) {
        viewModelScope.launch {
            try {
                client.collection("posts", Post::class.java)
                    .create(Post(title, body))
            } catch (e: BunBaseError.NetworkError) {
                // Queue the write — it will replay when online
                client.offlineQueue.enqueue(
                    method = "POST",
                    path = "/api/v1/posts",
                    body = Post(title, body),
                )
                // Optimistically update local UI here
            }
        }
    }
}