feat: add JsonParam sealed class to provide type safety

Author: DominicGBauer

core/src/commonMain/kotlin/com/powersync/PowerSyncDatabase.kt

@@ -5,6 +5,8 @@ import com.powersync.db.Queries
 import com.powersync.db.crud.CrudBatch
 import com.powersync.db.crud.CrudTransaction
 import com.powersync.sync.SyncStatus
+import com.powersync.utils.JsonParam
+import com.powersync.utils.toJsonParam
 
 /**
  * A PowerSync managed database.
@@ -27,18 +29,35 @@ public interface PowerSyncDatabase : Queries {
      *
      *  The connection is automatically re-opened if it fails for any reason.
      *
+     *  Use @param [connector] to specify the [PowerSyncBackendConnector].
      *  Use @param [crudThrottleMs] to specify the time between CRUD operations. Defaults to 1000ms.
      *  Use @param [retryDelayMs] to specify the delay between retries after failure. Defaults to 5000ms.
-     *  Use @param [params] to specify sync parameters from the client
+     *  Use @param [params] to specify sync parameters from the client. Can be constructed using [toJsonParam].
      *
+     *  Example usage:
+     *  ```
+     *  val params = mapOf(
+     *      "name" to "John",
+     *      "age" to 30,
+     *      "isStudent" to false,
+     *      "grades" to listOf(85, 90, 78)
+     *   ).mapValues { it.value.toJsonParam() }
+     *
+     *  connect(
+     *      connector = connector,
+     *      crudThrottleMs = 2000L,
+     *      retryDelayMs = 10000L,
+     *      params = params
+     *  )
+     *  ```
      *  TODO: Internal Team - Status changes are reported on [statusStream].
      */
 
     public suspend fun connect(
         connector: PowerSyncBackendConnector,
         crudThrottleMs: Long = 1000L,
         retryDelayMs: Long = 5000L,
-        params: Map<String, Any>? = null
+        params: Map<String, JsonParam?>? = null
     )
 
 

core/src/commonMain/kotlin/com/powersync/db/PowerSyncDatabaseImpl.kt

@@ -20,6 +20,7 @@ import com.powersync.db.internal.PowerSyncTransaction
 import com.powersync.db.schema.Schema
 import com.powersync.sync.SyncStatus
 import com.powersync.sync.SyncStream
+import com.powersync.utils.JsonParam
 import com.powersync.utils.JsonUtil
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.FlowPreview
@@ -88,7 +89,7 @@ internal class PowerSyncDatabaseImpl(
         connector: PowerSyncBackendConnector,
         crudThrottleMs: Long,
         retryDelayMs: Long,
-        params: Map<String, Any>?)
+        params: Map<String, JsonParam?>?)
     {
         // close connection if one is open
         disconnect()

core/src/commonMain/kotlin/com/powersync/sync/StreamingSyncRequest.kt

@@ -10,7 +10,7 @@ internal data class StreamingSyncRequest(
     val buckets: List<BucketRequest>,
     @SerialName("include_checksum") val includeChecksum: Boolean = true,
     @SerialName("client_id") val clientId: String,
-    val parameters: JsonObject = JsonObject(mapOf())
+    val parameters: JsonObject? = JsonObject(mapOf())
 ) {
     @SerialName("raw_data") private val rawData: Boolean = true
 }

core/src/commonMain/kotlin/com/powersync/sync/SyncStream.kt

@@ -8,8 +8,9 @@ import com.powersync.bucket.Checkpoint
 import com.powersync.bucket.WriteCheckpointResponse
 import co.touchlab.stately.concurrency.AtomicBoolean
 import com.powersync.connectors.PowerSyncBackendConnector
+import com.powersync.utils.JsonParam
 import com.powersync.utils.JsonUtil
-import com.powersync.utils.convertMapToJson
+import com.powersync.utils.toJsonObject
 import io.ktor.client.HttpClient
 import io.ktor.client.call.body
 import io.ktor.client.plugins.HttpTimeout
@@ -43,7 +44,7 @@ internal class SyncStream(
     private val uploadCrud: suspend () -> Unit,
     private val retryDelayMs: Long = 5000L,
     private val logger: Logger,
-    private val params: Map<String, Any>?
+    private val params: Map<String, JsonParam?>?
 ) {
     private var isUploadingCrud = AtomicBoolean(false)
 
@@ -248,7 +249,7 @@ internal class SyncStream(
         val req = StreamingSyncRequest(
             buckets = initialBuckets.map { (bucket, after) -> BucketRequest(bucket, after) },
             clientId = clientId!!,
-            parameters = convertMapToJson(params)
+            parameters = params?.toJsonObject()
         )
 
         streamingSyncRequest(req).collect { value ->

core/src/commonMain/kotlin/com/powersync/utils/Json.kt

@@ -17,32 +17,41 @@ internal object JsonUtil {
     }
 }
 
-internal fun convertMapToJson(map: Map<String, Any?>?): JsonObject {
-    if (map == null) return JsonObject(emptyMap())
+public sealed class JsonParam {
+    public data class Number(val value: kotlin.Number) : JsonParam()
+    public data class String(val value: kotlin.String) : JsonParam()
+    public data class Boolean(val value: kotlin.Boolean) : JsonParam()
+    public data class Map(val value: kotlin.collections.Map<kotlin.String, JsonParam>) : JsonParam()
+    public data class Collection(val value: kotlin.collections.Collection<JsonParam>) : JsonParam()
+    public data class JsonElement(val value: kotlinx.serialization.json.JsonElement) : JsonParam()
+    public data object Null : JsonParam()
 
-    val result = map.mapValues { (_, value) ->
-        convertToJsonElement(value)
+    internal fun toJsonElement(): kotlinx.serialization.json.JsonElement = when (this) {
+        is Number -> JsonPrimitive(value)
+        is String -> JsonPrimitive(value)
+        is Boolean -> JsonPrimitive(value)
+        is Map -> JsonObject(value.mapValues { it.value.toJsonElement() })
+        is Collection -> JsonArray(value.map { it.toJsonElement() })
+        is JsonElement -> value
+        Null -> JsonNull
     }
-    return JsonObject(result)
 }
 
-
-internal fun convertToJsonElement(value: Any?): JsonElement {
-    return when (value) {
-        null -> JsonNull
-        is Int -> JsonPrimitive(value)
-        is Long -> JsonPrimitive(value)
-        is Double -> JsonPrimitive(value)
-        is Float -> JsonPrimitive(value)
-        is Boolean -> JsonPrimitive(value)
-        is String -> JsonPrimitive(value)
-        is Map<*, *> -> convertMapToJson(value as Map<String, Any?>)
-        is List<*> -> convertListToJsonArray(value)
-        is Array<*> -> convertListToJsonArray(value.toList())
-        else -> JsonNull
-    }
+public fun Any?.toJsonParam(): JsonParam = when (this) {
+    is Number -> JsonParam.Number(this)
+    is String -> JsonParam.String(this)
+    is Boolean -> JsonParam.Boolean(this)
+    is Map<*, *> -> JsonParam.Map(this.mapKeys { it.key.toString() }
+        .mapValues { it.value.toJsonParam() })
+    is List<*> -> JsonParam.Collection(this.map { it.toJsonParam() })
+    is Array<*> -> JsonParam.Collection(this.map { it.toJsonParam() })
+    is JsonElement -> JsonParam.JsonElement(this)
+    null -> JsonParam.Null
+    else -> throw IllegalArgumentException("Unsupported type for JsonParam: $this")
 }
 
-internal fun convertListToJsonArray(list: List<Any?>): JsonArray {
-    return JsonArray(list.map { convertToJsonElement(it) })
+public fun Map<String, JsonParam?>.toJsonObject(): JsonObject {
+    return JsonObject(this.mapValues { (_, value) ->
+        value?.toJsonElement() ?: JsonNull
+    })
 }