kmpworker

0.1.0-beta06indexed

Reliability-first background-task API offering scheduling, retries, SQL-persistence, offline queue with replay, task chaining, tag-based cancellation, state flows and test fakes.

AndroidNative·neuralheads/kmpworker

Stars

—

Used by

dependents

—

Health

/ 100

KMPWorker

A reliability-first Kotlin Multiplatform background task library for Android & iOS.

Features

One-time, periodic, exact-time & windowed background tasks
Exponential / linear retry policies with public RetryEngine
Task state monitoring via Flow with 10 extension operators
Progress reporting from within task handlers
Task chaining with crash-safe resume + builder DSL
Task dependency graph (DAG) with parallel execution
Chain policies (KEEP / REPLACE / ALLOW_DUPLICATE)
Batch operations (enqueueBatch / cancelBatch)
Rate limiting with coroutine Semaphore
SQLDelight-backed persistence (survives app restarts)
Execution history & telemetry
Offline queue with automatic replay on network restore
HTTP download & upload (resume, SHA-256 checksum, progress)
Group cancellation via tags
Content URI triggers (Android)
Full constraint support (network, charging, battery, device idle)
Foreground service configuration (Android)
Swift interop helpers (FlowWrapper, TaskStateObserver)
Testing utilities — FakeKmpWorker, FakeNetworkMonitor, FakeTaskRepository
Android test rule — KmpWorkerTestRule for JUnit4
No Ktor dependency — pure platform APIs
ProGuard/R8 consumer rules included

Installation

// build.gradle.kts (KMP shared module)
kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("com.neuralheads:kmpworker:0.1.0-beta06")
        }
        // Android platform worker (required for androidMain)
        androidMain.dependencies {
            implementation("com.neuralheads:kmpworker-android:0.1.0-beta06")
        }
    }
}

Optional modules

// HTTP transfers (download/upload with resume & checksum)
implementation("com.neuralheads:kmpworker-transfer:0.1.0-beta06")

// Compose Live Inspector (v0.1.0-beta06+)
implementation("com.neuralheads:kmpworker-inspector:0.1.0-beta06")

// Testing (FakeKmpWorker + KmpWorkerTestRule)
testImplementation("com.neuralheads:kmpworker-testing:0.1.0-beta06")

Package Names

All classes live under io.neuralheads.kmpworker.*:

Quick Start

// 1. Register handler
kmpWorker.register("sync-users") {
    repository.syncUsers()
}

// 2. Schedule
kmpWorker.enqueue(
    TaskRequest(
        id = "sync-users",
        type = TaskType.OneTime,
        constraints = Constraints(requiresInternet = true),
        retryPolicy = RetryPolicy.Exponential(initialDelayMillis = 5_000, maxRetries = 3)
    )
)

// 3. Observe
kmpWorker.observe("sync-users")
    .onRunning  { showSpinner() }
    .onProgress { progress, msg -> updateBar(progress) }
    .onSuccess  { hideSpinner() }
    .onFailed   { error -> showError(error.throwable.message) }
    .collect()

DSL shortcuts

kmpWorker.oneTime(id = "upload", retryPolicy = exponentialRetry(5.seconds, maxRetries = 3)) {
    uploader.upload()
}

kmpWorker.periodic(id = "sync", repeatInterval = 6.hours) {
    repository.sync()
}

Android Setup

class MyApp : Application() {
    val kmpWorker: KmpWorker by lazy {
        KmpWorkerBuilder(
            AndroidKmpWorker(
                context = this,
                telemetry = SqlDelightTelemetryCollector(database),  // optional
                foregroundConfig = ForegroundConfig(                  // optional
                    notificationTitle = "Syncing..."
                )
            )
        )
        .configure {
            logLevel = KmpWorkerLogger.Level.DEBUG
            logger = KmpWorkerAndroidLogger
        }
        .task("sync") { repository.sync() }
        .build()
    }
}

WorkManager is initialized automatically via Jetpack App Startup.

iOS Setup

let kmpWorker = IOSKmpWorker()

func application(_ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]) ->  {
    kmpWorker.register(taskId: ) {  }
    kmpWorker.initialize()
     
}

Info.plist:

<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
    <string>sync</string>
</array>

Swift Flow observation

let observer = TaskStateObserver(flow: kmpWorker.observe(taskId: "sync"))
observer.onStateChange { state in
    print("State: \(state)")
}
observer.stop()

Task Types

TaskType.OneTime                                        // run once ASAP
TaskType.Periodic(repeatIntervalMillis = 900_000)       // every 15 min
TaskType.ExactTime(runAtMillis = epochMs)                // at specific time
TaskType.Windowed(earliestMillis = t1, latestMillis = t2) // within a window

Constraints

Constraints(
    requiresInternet = true,
    requiresCharging = false,
    batteryNotLow = true,
    requiresUnmeteredNetwork = true,                      // Wi-Fi only (v0.1.0-beta06+)
    requiresNonRoamingNetwork = true,                     // Non-roaming only (v0.1.0-beta06+)
    requiresDeviceIdle = false,                           // Android only
    contentUris = listOf("content://media/external/images") // Android only
)

Task Chaining

Constructor API

val chain = TaskChain(
    id = "onboarding",
    steps = listOf(
        TaskRequest(id = "fetch-profile", type = TaskType.OneTime),
        TaskRequest(id = "upload-avatar", type = TaskType.OneTime),
        TaskRequest(id = "notify-server", type = TaskType.OneTime)
    )
)
kmpWorker.enqueueChain(chain, ChainPolicy.REPLACE)

Builder DSL

kmpWorker.chain("onboarding", policy = ChainPolicy.REPLACE) {
    beginWith("fetch-profile")
    then("upload-avatar") {
        constraints = Constraints(requiresInternet = true)
    }
    then("notify-server") {
        retryPolicy = RetryPolicy.Exponential(5_000, 3)
    }
}

Chain Policies

Policy	Behavior
`KEEP`	Skip if chain ID already running
`REPLACE`

Task Dependency Graph (DAG)

Execute tasks with complex dependencies — independent nodes run in parallel:

@OptIn(ExperimentalKmpWorkerApi::class)
kmpWorker.graph("pipeline") {
    val fetch = task("fetch-data")
    val process = task("process")
    val validate = task("validate")
    val upload = task("upload")

    fetch then process      // process depends on fetch
    fetch then validate     // validate runs PARALLEL with process
    process then upload     // upload waits for BOTH
    validate then upload
}

Progress Reporting

kmpWorker.registerWithContext("upload") {
    for (i in 0..100 step 10) {
        reportProgress(i / 100f, "Uploading chunk $i")
        delay(500)
    }
}

kmpWorker.observe("upload")
    .onProgress { progress, message -> updateBar(progress) }
    .collect()

Batch Operations

kmpWorker.enqueueBatch(listOf(
    TaskRequest("task-1", TaskType.OneTime),
    TaskRequest("task-2", TaskType.OneTime),
    TaskRequest("task-3", TaskType.OneTime)
))

kmpWorker.cancelBatch(listOf("task-1", "task-2", "task-3"))

Rate Limiting

@OptIn(ExperimentalKmpWorkerApi::class)
val limiter = RateLimiter(maxConcurrent = 3)

limiter.withPermit {
    // At most 3 tasks execute concurrently
    doHeavyWork()
}

Execution History & Telemetry

val worker = AndroidKmpWorker(
    context = this,
    telemetry = SqlDelightTelemetryCollector(database)
)

// Query history
val records = worker.getExecutionHistory(limit = 50)
records.forEach { println("${it.taskId}: ${it.state} (${it.durationMs}ms)") }

// Clear
worker.clearExecutionHistory()

Compose Live Inspector

KMPWorker includes a gorgeous, reactive live inspector dashboard built with Compose Multiplatform to monitor and simulate task execution in real-time.

// Host the inspector screen inside a ComposeView or Composable tree
KmpWorkerInspectorScreen(kmpWorker = kmpWorker)

The inspector provides:

Real-Time Metrics Grid: View active task counts, success rate, and error/timeout counters.
Registered Handlers: Displays all registered handlers in with individual buttons to trigger them.

HTTP Transfers

No Ktor required — uses HttpURLConnection (Android) and NSURLSession (iOS):

val manager = AndroidTransferManager() // or IOSTransferManager()

manager.download(DownloadRequest(
    id = "large-file",
    url = "https://example.com/file.zip",
    savePath = "/downloads/file.zip",
    expectedChecksum = "sha256:abc123...",
    resumable = true
))

manager.observeProgress("large-file").collect { progress ->
    println("${progress.percentComplete}%")
}

manager.upload(UploadRequest(
    id = "backup",
    url = "https://api.example.com/upload",
    filePath = "/data/backup.zip"
))

Offline Queue

val queue = OfflineQueue(
    worker = kmpWorker,
    repository = SqlDelightTaskRepository(database),
    networkMonitor = AndroidNetworkMonitor(context) // or IOSNetworkMonitor()
)
queue.start()

queue.enqueue(request)
// Online: executes immediately
// Offline: persists, replays on reconnect

Testing

// Unit tests with FakeKmpWorker
 fake = FakeKmpWorker()
fake.register() { repository.sync() }
fake.enqueue(TaskRequest(, TaskType.OneTime))
assertEquals(TaskState.Success, fake.lastStateFor())


fake.failureCount[] =   


  {
    
     rule = KmpWorkerTestRule()

    
     = runTest {
        rule.worker.register() {  }
        rule.worker.enqueue(TaskRequest(, TaskType.OneTime))
        assertEquals(TaskState.Success, rule.worker.lastStateFor())
    }
}

Flow Extensions

Published Modules

Requirements

Tool	Version
Kotlin

License

Copyright 2026 NeuralHeads
Licensed under the Apache License, Version 2.0

Related libraries

Surfaced from shared tags and platforms — no rankings paid for.

Kotlin-BLE-Library★ 515

nordicsemiSimplifies Bluetooth Low Energy usage with coroutine-based asynchronous APIs: scanning, connecting (autoConnect), GATT reads/writes, MTU/PHY management, notifications, and mock environments for testing.Shared: wrapper, sdk, kotlin-flow

kmpworkmanager★ 197

brewkitsA Kotlin Multiplatform library for managing background work and scheduling. It provides a unified API similar to Android Jetpack WorkManager, supporting Android, iOS, and Desktop targets.Shared: work-manager, scheduling, bgtaskscheduler

konnection★ 170

TM-AppsLibrary emits network connection status, offers immediate connection state checks, IP info retrieval, and network state observation. Supports customizable instance creation and includes default IP resolvers.Shared: sdk, kotlin-flow, kotlin-coroutines

meeseeks★ 130

matt-ramotarMeeseeks is a Kotlin Multiplatform library for scheduling and managing background tasks across Android, JVM, native (iOS), and JS (Web). Whether your tasks are simple or complex, for one user or hundreds of millions, Meeseeks can help.Shared: work-manager, bgtaskscheduler, background-synchronization

powersync-kotlin★ 118

powersync-jaSync engine enhances local-first apps with responsive UI/UX and seamless state transfer, connecting client-side SQLite to server-side databases like Postgres, MongoDB, or MySQL. Features demo projects and Supabase integration.Shared: sqldelight, sdk, background-synchronization

fakt★ 55

rsicarelliGenerates compile-time type-safe test fakes with zero runtime overhead, no reflection, thread-safe call tracking, smart defaults and compiler-plugin code generation for comprehensive test doubles.Shared: test, kotlin-flow, kotlin-coroutines

`KmpWorker`, `TaskRequest`, `TaskState`, `TaskType`	`io.neuralheads.kmpworker.core`
`RetryPolicy`, `RetryEngine`, `Constraints`	`io.neuralheads.kmpworker.core`
`TaskChain`, `TaskChainBuilder`, `ChainPolicy`	`io.neuralheads.kmpworker.core`
`TaskGraph`, `TaskGraphBuilder`, `TaskGraphExecutor`	`io.neuralheads.kmpworker.core`
`RateLimiter`, `TelemetryCollector`, `ExecutionRecord`	`io.neuralheads.kmpworker.core`
`AndroidKmpWorker`, `ForegroundConfig`	`io.neuralheads.kmpworker.android`
`IOSKmpWorker`, `FlowWrapper`, `TaskStateObserver`	`io.neuralheads.kmpworker.ios`
`OfflineQueue`, `NetworkMonitor`	`io.neuralheads.kmpworker.queue`
`TransferManager`, `DownloadRequest`, `UploadRequest`	`io.neuralheads.kmpworker.transfer`
`FakeKmpWorker`, `KmpWorkerTestRule`	`io.neuralheads.kmpworker.testing`

`.onRunning { }`	Task is executing
`.onSuccess { }`	Task completed
`.onFailed { error -> }`	Task failed
`.onCancelled { }`	Task was cancelled
`.onTimedOut { timeout -> }`	Task exceeded timeout
`.onTerminal { state -> }`	Any terminal state
`.onProgress { progress, msg -> }`	Progress reported
`.terminalStates()`	Filter to terminal only
`.failures()`	Filter to `Failed` only
`.successes()`	Filter to `Success` only
`.progressUpdates()`	Filter to `Running` with progress

`kmpworker`	Umbrella — includes everything
`kmpworker-core`	Core API, models, retry, chains, DAG
`kmpworker-android`	WorkManager integration
`kmpworker-persistence`	SQLDelight storage + telemetry
`kmpworker-queue`	Offline queue + network monitors
`kmpworker-transfer`	HTTP download/upload (no Ktor)
`kmpworker-inspector`	Compose Multiplatform Live Inspector UI
`kmpworker-testing`	FakeKmpWorker + test rule
`kmpworker-scheduler`	TaskScheduler interface