Use builders instead

Uses builders instead of named arguments to improve maintainability

Author: Daeda88

README.md

@@ -210,14 +210,6 @@ citiesRef.where {
 }
 ```
 
-<h3><a href="https://kotlinlang.org/docs/reference/functions.html#named-arguments">Named arguments</a></h3>
-
-To improve readability functions such as the Cloud Firestore data encoding/decoding use named arguments:
-
-```kotlin
-documentRef.set(data, encodeDefaults = false, serializersModule = customSerializerModule)
-```
-
 <h3><a href="https://kotlinlang.org/docs/reference/operator-overloading.html">Operator overloading</a></h3>
 
 In cases where it makes sense, such as Firebase Functions HTTPS Callable, operator overloading is used:

firebase-common/src/commonMain/kotlin/dev/gitlive/firebase/EncodeDecodeSettings.kt

@@ -19,15 +19,30 @@ sealed class EncodeDecodeSettings {
  * @property shouldEncodeElementDefault if `true` this will explicitly encode elements even if they are their default value
  * @param serializersModule the [SerializersModule] to use for serialization. This allows for polymorphic serialization on runtime
  */
-data class EncodeSettings(
-    val shouldEncodeElementDefault: Boolean = true,
-    override val serializersModule: SerializersModule = EmptySerializersModule(),
-) : EncodeDecodeSettings()
+data class EncodeSettings internal constructor(
+    val shouldEncodeElementDefault: Boolean,
+    override val serializersModule: SerializersModule,
+) : EncodeDecodeSettings() {
+    class Builder {
+        var shouldEncodeElementDefault: Boolean = true
+        var serializersModule: SerializersModule = EmptySerializersModule()
+
+        @PublishedApi
+        internal fun build() = EncodeSettings(shouldEncodeElementDefault, serializersModule)
+    }
+}
 
 /**
  * [EncodeDecodeSettings] used when decoding an object
  * @param serializersModule the [SerializersModule] to use for deserialization. This allows for polymorphic serialization on runtime
  */
-data class DecodeSettings(
+data class DecodeSettings internal constructor(
     override val serializersModule: SerializersModule = EmptySerializersModule(),
-) : EncodeDecodeSettings()
+) : EncodeDecodeSettings() {
+
+    class Builder {
+        var serializersModule: SerializersModule = EmptySerializersModule()
+
+        internal fun build() = DecodeSettings(serializersModule)
+    }
+}

firebase-common/src/commonMain/kotlin/dev/gitlive/firebase/decoders.kt

@@ -15,13 +15,15 @@ import kotlinx.serialization.modules.EmptySerializersModule
 import kotlinx.serialization.modules.SerializersModule
 import kotlinx.serialization.serializer
 
-inline fun <reified T> decode(value: Any?, serializersModule: SerializersModule = EmptySerializersModule()): T {
+inline fun <reified T> decode(value: Any?): T = decode(value) {}
+inline fun <reified T> decode(value: Any?, noinline buildSettings: DecodeSettings.Builder.() -> Unit): T {
     val strategy = serializer<T>()
-    return decode(strategy as DeserializationStrategy<T>, value, serializersModule)
+    return decode(strategy as DeserializationStrategy<T>, value, buildSettings)
 }
-fun <T> decode(strategy: DeserializationStrategy<T>, value: Any?, serializersModule: SerializersModule = EmptySerializersModule()): T {
+fun <T> decode(strategy: DeserializationStrategy<T>, value: Any?): T = decode(strategy, value) {}
+fun <T> decode(strategy: DeserializationStrategy<T>, value: Any?, buildSettings: DecodeSettings.Builder.() -> Unit): T {
     require(value != null || strategy.descriptor.isNullable) { "Value was null for non-nullable type ${strategy.descriptor.serialName}" }
-    return FirebaseDecoder(value, DecodeSettings(serializersModule)).decodeSerializableValue(strategy)
+    return FirebaseDecoder(value, DecodeSettings.Builder().apply(buildSettings).build()).decodeSerializableValue(strategy)
 }
 expect fun FirebaseDecoder.structureDecoder(descriptor: SerialDescriptor, polymorphicIsNested: Boolean): CompositeDecoder
 expect fun getPolymorphicType(value: Any?, discriminator: String): String

firebase-common/src/commonMain/kotlin/dev/gitlive/firebase/encoders.kt

@@ -7,17 +7,22 @@ package dev.gitlive.firebase
 import kotlinx.serialization.*
 import kotlinx.serialization.descriptors.*
 import kotlinx.serialization.encoding.*
-import kotlinx.serialization.modules.EmptySerializersModule
 import kotlinx.serialization.modules.SerializersModule
 
-fun <T> encode(strategy: SerializationStrategy<T>, value: T, shouldEncodeElementDefault: Boolean, serializersModule: SerializersModule = EmptySerializersModule()): Any? = encode(strategy, value, EncodeSettings(shouldEncodeElementDefault, serializersModule))
+@Deprecated("Deprecated. Use builder instead", replaceWith = ReplaceWith("encode(strategy, value) { this.shouldEncodeElementDefault = shouldEncodeElementDefault }"))
+fun <T> encode(strategy: SerializationStrategy<T>, value: T, shouldEncodeElementDefault: Boolean): Any? = encode(strategy, value) {
+    this.shouldEncodeElementDefault = shouldEncodeElementDefault
+}
 
-fun <T> encode(strategy: SerializationStrategy<T>, value: T, settings: EncodeSettings): Any? =
-    FirebaseEncoder(settings).apply { encodeSerializableValue(strategy, value) }.value
+fun <T> encode(strategy: SerializationStrategy<T>, value: T, buildSettings: EncodeSettings.Builder.() -> Unit): Any? =
+    FirebaseEncoder(EncodeSettings.Builder().apply(buildSettings).build()).apply { encodeSerializableValue(strategy, value) }.value
 
-inline fun <reified T> encode(value: T, shouldEncodeElementDefault: Boolean, serializersModule: SerializersModule = EmptySerializersModule()): Any? = encode(value, EncodeSettings(shouldEncodeElementDefault, serializersModule))
-inline fun <reified T> encode(value: T, settings: EncodeSettings): Any? = value?.let {
-    FirebaseEncoder(settings).apply {
+@Deprecated("Deprecated. Use builder instead", replaceWith = ReplaceWith("encode(value) { this.shouldEncodeElementDefault = shouldEncodeElementDefault }"))
+inline fun <reified T> encode(value: T, shouldEncodeElementDefault: Boolean): Any? = encode(value) {
+    this.shouldEncodeElementDefault = shouldEncodeElementDefault
+}
+inline fun <reified T> encode(value: T, buildSettings: EncodeSettings.Builder.() -> Unit): Any? = value?.let {
+    FirebaseEncoder(EncodeSettings.Builder().apply(buildSettings).build()).apply {
         if (it is ValueWithSerializer<*> && it.value is T) {
             @Suppress("UNCHECKED_CAST")
             (it as ValueWithSerializer<T>).let {
@@ -43,7 +48,9 @@ class FirebaseEncoder(
     internal val settings: EncodeSettings
 ) : Encoder {
 
-    constructor(shouldEncodeElementDefault: Boolean, serializersModule: SerializersModule = EmptySerializersModule()) : this(EncodeSettings(shouldEncodeElementDefault, serializersModule))
+    constructor(shouldEncodeElementDefault: Boolean) : this(
+        EncodeSettings.Builder().apply { this.shouldEncodeElementDefault = shouldEncodeElementDefault }.build()
+    )
 
     var value: Any? = null
 

firebase-common/src/commonTest/kotlin/dev/gitlive/firebase/EncodersTest.kt

@@ -141,11 +141,17 @@ class EncodersTest {
             polymorphic(AbstractClass::class, ImplementedClass::class, ImplementedClass.serializer())
         }
         val abstractClass: AbstractClass = ImplementedClass("value", true)
-        val encoded = encode(AbstractClass.serializer(), abstractClass, EncodeSettings(true, module))
+        val encoded =
+            encode(AbstractClass.serializer(), abstractClass) {
+                shouldEncodeElementDefault = true
+                serializersModule = module
+            }
 
         nativeAssertEquals(nativeMapOf("type" to "implemented", "value" to "value", "otherValue" to true), encoded)
 
-        val decoded = decode(AbstractClass.serializer(), encoded, module)
+        val decoded = decode(AbstractClass.serializer(), encoded) {
+            serializersModule = module
+        }
         assertEquals(abstractClass, decoded)
     }
 
@@ -158,7 +164,10 @@ class EncodersTest {
         val sealedClass: SealedClass = SealedClass.Test("value")
         val abstractClass: AbstractClass = ImplementedClass("value", true)
         val nestedClass = NestedClass(sealedClass, abstractClass, listOf(sealedClass), listOf(abstractClass), mapOf(sealedClass to sealedClass), mapOf(abstractClass to abstractClass))
-        val encoded = encode(NestedClass.serializer(), nestedClass, EncodeSettings(true, module))
+        val encoded = encode(NestedClass.serializer(), nestedClass) {
+            shouldEncodeElementDefault = true
+            serializersModule = module
+        }
 
         val sealedEncoded = nativeMapOf("type" to "test", "value" to "value")
         val abstractEncoded = nativeMapOf("type" to "implemented", "value" to "value", "otherValue" to true)
@@ -174,7 +183,9 @@ class EncodersTest {
             encoded
         )
 
-        val decoded = decode(NestedClass.serializer(), encoded, module)
+        val decoded = decode(NestedClass.serializer(), encoded) {
+            serializersModule = module
+        }
         assertEquals(nestedClass, decoded)
     }
 }

firebase-crashlytics/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gitlive/firebase-crashlytics",
-  "version": "1.11.0",
+  "version": "1.11.4",
   "description": "Wrapper around firebase for usage in Kotlin Multiplatform projects",
   "main": "firebase-crashlytics.js",
   "scripts": {

firebase-database/src/androidMain/kotlin/dev/gitlive/firebase/database/database.kt

@@ -16,7 +16,6 @@ import kotlinx.coroutines.flow.*
 import kotlinx.coroutines.tasks.await
 import kotlinx.serialization.DeserializationStrategy
 import kotlinx.serialization.KSerializer
-import kotlinx.serialization.modules.SerializersModule
 import java.util.*
 import kotlin.time.Duration.Companion.seconds
 
@@ -184,22 +183,22 @@ actual class DatabaseReference internal constructor(
         .run { Unit }
 
     @Suppress("UNCHECKED_CAST")
-    override suspend fun updateChildren(update: Map<String, Any?>, encodeDefaults: Boolean, serializersModule: SerializersModule) =
-        android.updateChildren(encode(update, encodeDefaults, serializersModule) as Map<String, Any?>)
+    override suspend fun updateChildren(update: Map<String, Any?>, buildSettings: EncodeSettings.Builder.() -> Unit) =
+        android.updateChildren(encode(update, buildSettings) as Map<String, Any?>)
             .run { if(persistenceEnabled) await() else awaitWhileOnline(database) }
             .run { Unit }
 
     actual suspend fun removeValue() = android.removeValue()
         .run { if(persistenceEnabled) await() else awaitWhileOnline(database) }
         .run { Unit }
 
-    actual suspend fun <T> runTransaction(strategy: KSerializer<T>, serializersModule: SerializersModule, transactionUpdate: (currentData: T) -> T): DataSnapshot {
+    actual suspend fun <T> runTransaction(strategy: KSerializer<T>, buildSettings: DecodeSettings.Builder.() -> Unit, transactionUpdate: (currentData: T) -> T): DataSnapshot {
         val deferred = CompletableDeferred<DataSnapshot>()
         android.runTransaction(object : Transaction.Handler {
 
             override fun doTransaction(currentData: MutableData): Transaction.Result {
                 currentData.value = currentData.value?.let {
-                    transactionUpdate(decode(strategy, it, serializersModule))
+                    transactionUpdate(decode(strategy, it, buildSettings))
                 }
                 return Transaction.success(currentData)
             }
@@ -237,8 +236,8 @@ actual class DataSnapshot internal constructor(
     actual inline fun <reified T> value() =
         decode<T>(value = android.value)
 
-    actual fun <T> value(strategy: DeserializationStrategy<T>, serializersModule: SerializersModule) =
-        decode(strategy, android.value, serializersModule)
+    actual fun <T> value(strategy: DeserializationStrategy<T>, buildSettings: DecodeSettings.Builder.() -> Unit) =
+        decode(strategy, android.value, buildSettings)
 
     actual fun child(path: String) = DataSnapshot(android.child(path), persistenceEnabled)
     actual val hasChildren get() = android.hasChildren()
@@ -263,8 +262,8 @@ actual class OnDisconnect internal constructor(
             .run { if(persistenceEnabled) await() else awaitWhileOnline(database) }
             .run { Unit }
 
-    override suspend fun updateChildren(update: Map<String, Any?>, encodeDefaults: Boolean, serializersModule: SerializersModule) =
-        android.updateChildren(update.mapValues { (_, it) -> encode(it, encodeDefaults, serializersModule) })
+    override suspend fun updateChildren(update: Map<String, Any?>, buildSettings: EncodeSettings.Builder.() -> Unit) =
+        android.updateChildren(update.mapValues { (_, it) -> encode(it, buildSettings) })
             .run { if(persistenceEnabled) await() else awaitWhileOnline(database) }
             .run { Unit }
 }

firebase-database/src/commonMain/kotlin/dev/gitlive/firebase/database/database.kt

@@ -4,19 +4,16 @@
 
 package dev.gitlive.firebase.database
 
+import dev.gitlive.firebase.DecodeSettings
+import dev.gitlive.firebase.EncodeSettings
 import dev.gitlive.firebase.Firebase
 import dev.gitlive.firebase.FirebaseApp
-import dev.gitlive.firebase.database.ChildEvent.Type.ADDED
-import dev.gitlive.firebase.database.ChildEvent.Type.CHANGED
-import dev.gitlive.firebase.database.ChildEvent.Type.MOVED
-import dev.gitlive.firebase.database.ChildEvent.Type.REMOVED
+import dev.gitlive.firebase.database.ChildEvent.Type.*
 import dev.gitlive.firebase.encode
 import kotlinx.coroutines.flow.Flow
 import kotlinx.serialization.DeserializationStrategy
 import kotlinx.serialization.KSerializer
 import kotlinx.serialization.SerializationStrategy
-import kotlinx.serialization.modules.EmptySerializersModule
-import kotlinx.serialization.modules.SerializersModule
 
 /** Returns the [FirebaseDatabase] instance of the default [FirebaseApp]. */
 expect val Firebase.database: FirebaseDatabase
@@ -73,13 +70,29 @@ expect open class Query internal constructor(nativeQuery: NativeQuery) {
 }
 
 abstract class BaseDatabaseReference internal constructor(nativeQuery: NativeQuery) : Query(nativeQuery) {
-    suspend inline fun <reified T> setValue(value: T?, encodeDefaults: Boolean = true, serializersModule: SerializersModule = EmptySerializersModule()) =
-        setValueEncoded(encode(value, encodeDefaults, serializersModule))
-    suspend fun <T> setValue(strategy: SerializationStrategy<T>, value: T, encodeDefaults: Boolean = true, serializersModule: SerializersModule = EmptySerializersModule()) =
-        setValueEncoded(encode(strategy, value, encodeDefaults, serializersModule))
+
+    @Deprecated("Deprecated. Use builder instead", replaceWith = ReplaceWith("setValue(value) { shouldEncodeElementDefault = encodeDefaults }"))
+    suspend inline fun <reified T> setValue(value: T?, encodeDefaults: Boolean) =
+        setValue(value) {
+            shouldEncodeElementDefault = encodeDefaults
+        }
+    suspend inline fun <reified T> setValue(value: T?, buildSettings: EncodeSettings.Builder.() -> Unit = {}) =
+        setValueEncoded(encode(value, buildSettings))
+
+    @Deprecated("Deprecated. Use builder instead", replaceWith = ReplaceWith("setValue(strategy, value) { shouldEncodeElementDefault = encodeDefaults }"))
+    suspend fun <T> setValue(strategy: SerializationStrategy<T>, value: T, encodeDefaults: Boolean) =
+        setValue(strategy, value) {
+            shouldEncodeElementDefault = encodeDefaults
+        }
+    suspend fun <T> setValue(strategy: SerializationStrategy<T>, value: T, buildSettings: EncodeSettings.Builder.() -> Unit = {}) = setValueEncoded(encode(strategy, value, buildSettings))
 
     abstract suspend fun setValueEncoded(encodedValue: Any?)
-    abstract suspend fun updateChildren(update: Map<String, Any?>, encodeDefaults: Boolean = true, serializersModule: SerializersModule = EmptySerializersModule())
+
+    @Deprecated("Deprecated. Use builder instead", replaceWith = ReplaceWith("updateChildren(update) { shouldEncodeElementDefault = encodeDefaults }"))
+    suspend fun updateChildren(update: Map<String, Any?>, encodeDefaults: Boolean) = updateChildren(update) {
+        shouldEncodeElementDefault = encodeDefaults
+    }
+    abstract suspend fun updateChildren(update: Map<String, Any?>, buildSettings: EncodeSettings.Builder.() -> Unit = {})
 }
 
 expect class DatabaseReference : BaseDatabaseReference {
@@ -90,7 +103,7 @@ expect class DatabaseReference : BaseDatabaseReference {
 
     suspend fun removeValue()
 
-    suspend fun <T> runTransaction(strategy: KSerializer<T>, serializersModule: SerializersModule = EmptySerializersModule(), transactionUpdate: (currentData: T) -> T): DataSnapshot
+    suspend fun <T> runTransaction(strategy: KSerializer<T>, buildSettings: DecodeSettings.Builder.() -> Unit = {}, transactionUpdate: (currentData: T) -> T): DataSnapshot
 }
 
 expect class DataSnapshot {
@@ -99,7 +112,7 @@ expect class DataSnapshot {
     val ref: DatabaseReference
     val value: Any?
     inline fun <reified T> value(): T
-    fun <T> value(strategy: DeserializationStrategy<T>, serializersModule: SerializersModule = EmptySerializersModule()): T
+    fun <T> value(strategy: DeserializationStrategy<T>, buildSettings: DecodeSettings.Builder.() -> Unit = {}): T
     fun child(path: String): DataSnapshot
     val hasChildren: Boolean
     val children: Iterable<DataSnapshot>
@@ -108,13 +121,22 @@ expect class DataSnapshot {
 expect class DatabaseException(message: String?, cause: Throwable?) : RuntimeException
 
 abstract class BaseOnDisconnect internal constructor() {
-    suspend inline fun <reified T> setValue(value: T?, encodeDefaults: Boolean = true, serializersModule: SerializersModule = EmptySerializersModule()) =
-        setValue(encode(value, encodeDefaults, serializersModule))
-    suspend fun <T> setValue(strategy: SerializationStrategy<T>, value: T, encodeDefaults: Boolean = true, serializersModule: SerializersModule = EmptySerializersModule()) =
-        setValue(encode(strategy, value, encodeDefaults, serializersModule))
+    @Deprecated("Deprecated. Use builder instead", replaceWith = ReplaceWith("setValue(value) { shouldEncodeElementDefault = encodeDefaults }"))
+    suspend inline fun <reified T> setValue(value: T?, encodeDefaults: Boolean) =
+        setValue(value) { shouldEncodeElementDefault = encodeDefaults }
+    suspend inline fun <reified T> setValue(value: T?, buildSettings: EncodeSettings.Builder.() -> Unit = {}) =
+        setValue(encode(value, buildSettings))
+    @Deprecated("Deprecated. Use builder instead", replaceWith = ReplaceWith("setValue(strategy, value) { shouldEncodeElementDefault = encodeDefaults }"))
+    suspend fun <T> setValue(strategy: SerializationStrategy<T>, value: T, encodeDefaults: Boolean) =
+        setValue(strategy, value) { shouldEncodeElementDefault = encodeDefaults }
+    suspend fun <T> setValue(strategy: SerializationStrategy<T>, value: T, buildSettings: EncodeSettings.Builder.() -> Unit = {}) = setValue(encode(strategy, value, buildSettings))
     abstract suspend fun setValue(encodedValue: Any?)
 
-    abstract suspend fun updateChildren(update: Map<String, Any?>, encodeDefaults: Boolean = true, serializersModule: SerializersModule = EmptySerializersModule())
+    abstract suspend fun updateChildren(update: Map<String, Any?>, buildSettings: EncodeSettings.Builder.() -> Unit = {})
+    @Deprecated("Deprecated. Use builder instead", replaceWith = ReplaceWith("updateChildren(update) { shouldEncodeElementDefault = encodeDefaults }"))
+    suspend fun updateChildren(update: Map<String, Any?>, encodeDefaults: Boolean) = updateChildren(update) {
+        shouldEncodeElementDefault = encodeDefaults
+    }
 }
 
 expect class OnDisconnect : BaseOnDisconnect {