core/io.neuralheads.kmpworker.core

Package-level declarations

Types

Policy for handling duplicate chain IDs when enqueueing a TaskChain.

data class ChainProgress(val chainId: String, val stepsJson: String, val currentStep: Int, val totalSteps: Int, val status: String, val updatedAt: Long)

Snapshot of a chain's current state.

ChainRepository

interface ChainRepository

Persistent store for TaskChain progress.

Constraints

@Serializable

data class Constraints(val requiresInternet: Boolean = false, val requiresCharging: Boolean = false, val batteryNotLow: Boolean = false, val requiresDeviceIdle: Boolean = false, val contentUris: List<String> = emptyList())

Platform conditions that must be satisfied before a task can execute.

EventStore

interface EventStore

Persists task completion events to durable storage so they survive app termination.

ExecutionRecord

data class ExecutionRecord(val taskId: String, val startedAt: Long, val completedAt: Long, val durationMs: Long, val state: String, val retryCount: Int, val error: String?)

A single execution record for telemetry and analytics.

ExperimentalKmpWorkerApi

@Target(allowedTargets = [AnnotationTarget.CLASS, AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY, AnnotationTarget.TYPEALIAS])

annotation class ExperimentalKmpWorkerApi

Marks an API as experimental in KMPWorker.

KmpWorker

interface KmpWorker

Main entry point for KMPWorker.

KmpWorkerBuilder

class KmpWorkerBuilder(worker: KmpWorker)

Fluent builder for constructing a configured KmpWorker instance.

KmpWorkerConfig

data class KmpWorkerConfig(val maxRetries: Int = 10, val logLevel: KmpWorkerLogger.Level = KmpWorkerLogger.Level.INFO, val logger: KmpWorkerLogger.Logger? = null, val taskTimeout: Duration? = null)

Global configuration for KMPWorker behaviour.

KmpWorkerException

sealed class KmpWorkerException : RuntimeException

Base class for all exceptions thrown by KMPWorker.

KmpWorkerLogger

object KmpWorkerLogger

Pluggable logging interface for KMPWorker.

RateLimiter

class RateLimiter(val maxConcurrent: Int)

Rate limiter for controlling concurrent task execution.

RetryEngine

object RetryEngine

Pure retry delay calculator. Stateless — no side effects.

RetryPolicy

@Serializable

sealed class RetryPolicy

Defines how a failed task should be retried.

TaskChain

data class TaskChain(val id: String, val steps: List<TaskRequest>)

Defines a sequential chain of background tasks where each step must succeed before the next one begins. Progress is persisted at every step boundary, so if the app is killed mid-chain (e.g., iOS 30-second limit), execution resumes from the correct step on next launch.

TaskChainBuilder

class TaskChainBuilder(chainId: String)

Fluent DSL builder for constructing TaskChains.

TaskChainExecutor

class TaskChainExecutor(worker: KmpWorker, chainRepository: ChainRepository, scope: CoroutineScope = CoroutineScope(Dispatchers.Default + SupervisorJob()))

Drives the execution of a TaskChain by observing TaskMonitor and advancing the chain one step at a time.

TaskExecutionContext

data class TaskExecutionContext(val taskId: String, val retryCount: Int = 0, val payload: String? = null, val tags: Set<String> = emptySet())

Context provided to a task handler at execution time.

TaskGraph

data class TaskGraph(val id: String, val nodes: List<TaskRequest>, val edges: List<TaskGraph.Edge>)

A directed acyclic graph (DAG) of tasks with dependency edges.

TaskGraphBuilder

class TaskGraphBuilder(graphId: String)

DSL builder for TaskGraph.

TaskGraphExecutor

class TaskGraphExecutor(worker: KmpWorker, scope: CoroutineScope = CoroutineScope(Dispatchers.Default))

Executes a TaskGraph respecting dependency ordering.

TaskMonitor

object TaskMonitor

Broadcasts task state changes across the application.

TaskPriority

enum TaskPriority : Enum<TaskPriority>

Task execution priority hint.

TaskRegistry

object TaskRegistry

Thread-safe global registry mapping task IDs to their suspend handler functions.

TaskRequest

@Serializable

data class TaskRequest(val id: String, val type: TaskType, val constraints: Constraints = Constraints(), val retryPolicy: RetryPolicy = RetryPolicy.None, val priority: TaskPriority = TaskPriority.NORMAL, val tags: Set<String> = emptySet(), val payload: String? = null, val label: String? = null)

Describes a background task to be scheduled.

TaskRequestBuilder

class TaskRequestBuilder(taskId: String)

Builder for configuring individual TaskRequests within a chain DSL.

TaskState

sealed class TaskState

Represents the current lifecycle state of a background task.

TaskType

@Serializable

sealed class TaskType

Defines how a task is scheduled.

TelemetryCollector

interface TelemetryCollector

Collects execution metrics for background tasks.

Properties

KmpWorkerJson

val KmpWorkerJson: Json

Default Json instance used by KMPWorker for typed payload encoding/decoding.

Functions

chain

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

Builds and enqueues a TaskChain using a fluent DSL.

decodeAsPayload

inline fun <T> String?.decodeAsPayload(): T?

Decodes a raw JSON string into a strongly-typed object. Useful when you have the payload String directly (e.g., from logging or testing).

decodePayload

inline fun <T> TaskExecutionContext.decodePayload(): T?

Decodes the payload of this TaskExecutionContext into a strongly-typed object.

decodeStepIds

fun ChainProgress.decodeStepIds(): List<String>

Returns the step IDs decoded from a ChainProgress.stepsJson.

exponentialRetry

fun exponentialRetry(initialDelay: Duration, maxRetries: Int = KmpWorkerConfig.current().maxRetries): RetryPolicy.Exponential

Enqueues a task with exponential backoff using Duration-based delay.

failures

fun Flow<TaskState>.failures(): Flow<TaskState.Failed>

Filters to only TaskState.Failed states.

graph

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

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

linearRetry

fun linearRetry(delay: Duration): RetryPolicy.Linear

Enqueues a task with linear retry using Duration-based delay.

onCancelled

fun Flow<TaskState>.onCancelled(action: suspend () -> Unit): Flow<TaskState>

Invokes action when the task reaches TaskState.Cancelled.

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.

onFailed

fun Flow<TaskState>.onFailed(action: suspend (TaskState.Failed) -> Unit): Flow<TaskState>

Invokes action when the task reaches TaskState.Failed.

onProgress

fun Flow<TaskState>.onProgress(action: suspend (progress: Float, message: String?) -> Unit): Flow<TaskState>

Invokes action whenever progress is reported via TaskState.Running with non-null progress.

onRunning

fun Flow<TaskState>.onRunning(action: suspend () -> Unit): Flow<TaskState>

Invokes action whenever the task enters TaskState.Running.

onSuccess

fun Flow<TaskState>.onSuccess(action: suspend () -> Unit): Flow<TaskState>

Invokes action when the task reaches TaskState.Success.

onTerminal

fun Flow<TaskState>.onTerminal(action: suspend (TaskState) -> Unit): Flow<TaskState>

Invokes action when the task reaches any terminal state.

onTimedOut

fun Flow<TaskState>.onTimedOut(action: suspend (TaskState.TimedOut) -> Unit): Flow<TaskState>

Invokes action when the task is stopped due to timeout.

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.

progressUpdates

fun Flow<TaskState>.progressUpdates(): Flow<TaskState.Running>

Filters to only TaskState.Running states that carry progress info.

successes

fun Flow<TaskState>.successes(): Flow<TaskState.Success>

Filters to only TaskState.Success states.

terminalStates

fun Flow<TaskState>.terminalStates(): Flow<TaskState>

Filters to only terminal states.

withPayload

inline fun <T> TaskRequest.withPayload(data: T): TaskRequest

Encodes data as JSON and attaches it as the payload for this TaskRequest.