KSync

KSync is a robust, offline-first synchronization library for Kotlin Multiplatform. It ensures your client-side actions eventually reach the server by managing a persistent queue with background orchestration and conflict resolution.

Most "offline" apps just cache data. KSync focuses on outgoing actions. Whether it's a "Like", a "Comment", or "Create Post", KSync ensures that even if the user is in a tunnel, on a plane, or has a flaky connection, their intent is preserved persistently and synchronized as soon as possible.

@Serializable
data class CreatePostAction(
    override val id: String, 
    val title: String,
    override val mergeKey: String? = "post-$id"
) : SyncAction

class CreatePostWorker(private val api: MyApi) : SyncWorker<CreatePostAction> {
    override val workerIdentifier = "POST"

    override suspend fun execute(action: CreatePostAction): SyncResult {
        return try {
            api.createPost(action)
            SyncResult.Success
        } catch (e: Exception) {
            SyncResult.Retry // KSync will handle backoff
        }
    }
}

val ksync = KSync.init(context) {
    // Register your workers here
    registerWorker(CreatePostWorker(api))
}

// Type-safe enqueue. KSync knows which worker to use based on action type.
ksync.enqueue(
    action = CreatePostAction(id = "uuid", title = "Hello World")
)

// Observe pending actions
val pendingActions: Flow<List<QueuedAction>> = ksync.observePendingActions()

• Priorities & Dependencies: Define priority and dependsOn directly in your SyncAction.
• Atomic Batching: Group multiple actions via groupId for "all-or-nothing" sequential processing.
• Custom Conflict Resolution: Provide logic to handle duplicate actions with the same mergeKey.
• Multi-User Support: Partition your sync queue with userId for multi-account applications.
• Throttling: Built-in debouncing for high-frequency updates to save battery and database I/O.
• Observability: Real-time SyncStats and SyncObserver for granular monitoring of your sync health.
• Resilient Engine: Exponential backoff, action timeouts, and network constraint awareness.
• Security: Payload encryption for sensitive data stored in SQLite.
• Large Assets: Support for external blob storage for payloads exceeding a configurable size.
• Payload Versioning: Robust support for migrating serialized data when your domain models evolve.
• Auto-Maintenance: Configurable history retention policies (count or time-based) and database compaction.
• Control & Audit: Programmatic global pause/resume and a persistent conflict resolution audit log.
• Multiplatform: Support for Android, iOS, JVM, and soon Kotlin/Wasm.

Apache License 2.0