core/io.neuralheads.kmpworker.core/KmpWorker

KmpWorker

Main entry point for KMPWorker.

Platform-specific implementations:

Android: io.neuralheads.kmpworker.android.AndroidKmpWorker
iOS: io.neuralheads.kmpworker.ios.IOSKmpWorker

Quick start:

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

// Or register with execution context (taskId, retryCount, payload)
kmpWorker.register("upload") { ctx ->
    if (ctx.isRetry) logger.warn("Retrying upload, attempt ${ctx.retryCount}")
    uploader.upload(ctx.payload)
}

// Enqueue
kmpWorker.enqueue(TaskRequest(id = "sync-users", type = TaskType.OneTime))

// Observe
kmpWorker.observe("sync-users").collect { state -> println(state) }

Functions

cancel

abstract suspend fun cancel(taskId: String)

Cancels a previously scheduled task by its ID. Emits TaskState.Cancelled to any active observers.

cancelBatch

open suspend fun cancelBatch(taskIds: List<String>)

Cancels multiple tasks by their IDs.

cancelByTag

abstract suspend fun cancelByTag(tag: String)

Cancels all tasks matching the given tag. Useful for cancelling groups of related tasks at once.

chain

suspend fun KmpWorker.chain(chainId: String, policy: ChainPolicy = ChainPolicy.ALLOW_DUPLICATE, block: TaskChainBuilder.() -> Unit)

Builds and enqueues a TaskChain using a fluent DSL.

clearExecutionHistory

open suspend fun clearExecutionHistory()

Clears all execution history records.

enqueue

abstract suspend fun enqueue(request: TaskRequest)

Schedules a background task. The task handler must be registered via register before calling enqueue.

enqueueBatch

open suspend fun enqueueBatch(requests: List<TaskRequest>)

Enqueues multiple tasks atomically. On Android, maps to WorkManager.enqueue(List<WorkRequest>).

enqueueChain

open suspend fun enqueueChain(chain: TaskChain)

Enqueues a TaskChain for sequential execution.

abstract suspend fun enqueueChain(chain: TaskChain, policy: ChainPolicy)

Enqueues a TaskChain with a ChainPolicy to handle duplicate chain IDs.

getExecutionHistory

open suspend fun getExecutionHistory(limit: Int = 100): List<ExecutionRecord>

Returns execution history records for telemetry and analytics. Requires a TelemetryCollector to be installed.

graph

suspend fun KmpWorker.graph(graphId: String, block: TaskGraphBuilder.() -> Unit)

Builds and executes a TaskGraph (DAG) using a fluent DSL.

observe

abstract fun observe(taskId: String): Flow<TaskState>

Returns a Flow of TaskState updates for the given task ID. Emits: Scheduled → Running → Success | Failed | Cancelled

observeAll

abstract fun observeAll(): Flow<Pair<String, TaskState>>

Returns a Flow emitting Pair of (taskId, TaskState) for all tasks. Useful for global task dashboards or monitoring screens.

observeChain

abstract fun observeChain(chainId: String): Flow<TaskState>

Returns a Flow of TaskState updates for the chain as a whole. Emits TaskState.Success when ALL steps complete, or TaskState.Failed if any step fails.

oneTime

suspend fun KmpWorker.oneTime(id: String, constraints: Constraints = Constraints(), retryPolicy: RetryPolicy = RetryPolicy.None, payload: String? = null, block: suspend () -> Unit)

Registers and enqueues a one-time task in a single call.

periodic

suspend fun KmpWorker.periodic(id: String, repeatInterval: Duration, constraints: Constraints = Constraints(), retryPolicy: RetryPolicy = RetryPolicy.None, block: suspend () -> Unit)

Registers and enqueues a periodic task using a Duration interval.

abstract fun register(taskId: String, block: suspend () -> Unit)

Registers a no-context suspend handler for the given task ID. Must be called before enqueue.

registerWithContext

abstract fun registerWithContext(taskId: String, block: suspend TaskExecutionContext.() -> Unit)

Registers a handler that receives a TaskExecutionContext with the task ID, retry count, payload, and tags at execution time.