added GeoPoints, serialize DocumentReference natively, fix Timestamp extensions, improve debugging

Author: vasyl-pidlisniak

README.md

@@ -88,6 +88,7 @@ db.collection("cities").document("LA").set(City.serializer(), city, encodeDefaul
 ```
 
 The `encodeDefaults` parameter is optional and defaults to `true`, set this to false to omit writing optional properties if they are equal to theirs default values.
+Using [@EncodeDefault](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-encode-default/) on properties is a recommended way to locally override the behavior set with `encodeDefaults`.
 
 You can also omit the serializer but this is discouraged due to a [current limitation on Kotlin/JS and Kotlin/Native](https://github.com/Kotlin/kotlinx.serialization/issues/1116#issuecomment-704342452)
 
@@ -110,6 +111,21 @@ data class Post(
 )
 ```
 
+In addition `firebase-firestore` provides [GeoPoint] and [DocumentReference] classes which allow persisting
+geo points and document references in a native way:
+
+```kotlin
+@Serializable
+data class PointOfInterest(
+    val reference: DocumentReference, 
+    val location: GeoPoint
+)
+val document = PointOfInterest(
+    reference = Firebase.firestore.collection("foo").document("bar"),
+    location = GeoPoint(51.939, 4.506)
+)
+```
+
 <h4>Polymorphic serialization (sealed classes)</h4>
 
 This sdk will handle polymorphic serialization automatically if you have a sealed class and its children marked as `Serializable`. It will include a `type` property that will be used to discriminate which child class is the serialized.

firebase-common/src/jsMain/kotlin/dev/gitlive/firebase/externals.kt

@@ -453,6 +453,8 @@ external object firebase {
             fun update(field: FieldPath, value: Any?, vararg moreFieldsAndValues: Any?): Promise<Unit>
             fun delete(): Promise<Unit>
             fun onSnapshot(next: (snapshot: DocumentSnapshot) -> Unit, error: (error: Error) -> Unit): ()->Unit
+
+            fun isEqual(other: DocumentReference): Boolean
         }
 
         open class WriteBatch {
@@ -477,6 +479,8 @@ external object firebase {
             companion object {
                 val documentId: FieldPath
             }
+
+            fun isEqual(other: FieldPath): Boolean
         }
 
         abstract class FieldValue {
@@ -490,6 +494,13 @@ external object firebase {
 
             fun isEqual(other: FieldValue): Boolean
         }
+
+        open class GeoPoint(latitude: Double, longitude: Double) {
+            val latitude: Double
+            val longitude: Double
+
+            fun isEqual(other: GeoPoint): Boolean
+        }
     }
 
     fun remoteConfig(app: App? = definedExternally): remoteConfig.RemoteConfig

firebase-firestore/src/androidAndroidTest/kotlin/dev/gitlive/firebase/firestore/firestore.kt

@@ -14,3 +14,8 @@ actual val emulatorHost: String = "10.0.2.2"
 actual val context: Any = InstrumentationRegistry.getInstrumentation().targetContext
 
 actual fun runTest(test: suspend CoroutineScope.() -> Unit) = runBlocking { test() }
+
+@Suppress("UNCHECKED_CAST")
+actual fun encodedAsMap(encoded: Any?): Map<String, Any?> = encoded as Map<String, Any?>
+
+actual fun Map<String, Any?>.asEncoded(): Any = this

firebase-firestore/src/androidMain/kotlin/dev/gitlive/firebase/firestore/GeoPoint.kt

@@ -0,0 +1,19 @@
+package dev.gitlive.firebase.firestore
+
+import kotlinx.serialization.Serializable
+
+/** A class representing a platform specific Firebase GeoPoint. */
+actual typealias NativeGeoPoint = com.google.firebase.firestore.GeoPoint
+
+/** A class representing a Firebase GeoPoint. */
+@Serializable(with = GeoPointSerializer::class)
+actual class GeoPoint internal actual constructor(internal actual val nativeValue: NativeGeoPoint) {
+    actual constructor(latitude: Double, longitude: Double) : this(NativeGeoPoint(latitude, longitude))
+    actual val latitude: Double = nativeValue.latitude
+    actual val longitude: Double = nativeValue.longitude
+
+    override fun equals(other: Any?): Boolean =
+        this === other || other is GeoPoint && nativeValue == other.nativeValue
+    override fun hashCode(): Int = nativeValue.hashCode()
+    override fun toString(): String = nativeValue.toString()
+}

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

@@ -196,8 +196,12 @@ actual class Transaction(val android: com.google.firebase.firestore.Transaction)
         DocumentSnapshot(android.get(documentRef.android))
 }
 
-actual class DocumentReference(val android: com.google.firebase.firestore.DocumentReference) {
+/** A class representing a platform specific Firebase DocumentReference. */
+actual typealias NativeDocumentReference = com.google.firebase.firestore.DocumentReference
 
+@Serializable(with = DocumentReferenceSerializer::class)
+actual class DocumentReference actual constructor(internal actual val nativeValue: NativeDocumentReference) {
+    val android: NativeDocumentReference by ::nativeValue
     actual val id: String
         get() = android.id
 
@@ -270,6 +274,10 @@ actual class DocumentReference(val android: com.google.firebase.firestore.Docume
         }
         awaitClose { listener.remove() }
     }
+    override fun equals(other: Any?): Boolean =
+        this === other || other is DocumentReference && nativeValue == other.nativeValue
+    override fun hashCode(): Int = nativeValue.hashCode()
+    override fun toString(): String = nativeValue.toString()
 }
 
 actual open class Query(open val android: com.google.firebase.firestore.Query) {
@@ -432,6 +440,10 @@ actual class SnapshotMetadata(val android: com.google.firebase.firestore.Snapsho
 actual class FieldPath private constructor(val android: com.google.firebase.firestore.FieldPath) {
     actual constructor(vararg fieldNames: String) : this(com.google.firebase.firestore.FieldPath.of(*fieldNames))
     actual val documentId: FieldPath get() = FieldPath(com.google.firebase.firestore.FieldPath.documentId())
+
+    override fun equals(other: Any?): Boolean = other is FieldPath && android == other.android
+    override fun hashCode(): Int = android.hashCode()
+    override fun toString(): String = android.toString()
 }
 
 /** Represents a platform specific Firebase FieldValue. */

firebase-firestore/src/commonMain/kotlin/dev/gitlive/firebase/firestore/GeoPoint.kt

@@ -0,0 +1,29 @@
+package dev.gitlive.firebase.firestore
+
+import dev.gitlive.firebase.SpecialValueSerializer
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.SerializationException
+
+/** A class representing a platform specific Firebase GeoPoint. */
+expect class NativeGeoPoint
+
+/** A class representing a Firebase GeoPoint. */
+@Serializable(with = GeoPointSerializer::class)
+expect class GeoPoint internal constructor(nativeValue: NativeGeoPoint) {
+    constructor(latitude: Double, longitude: Double)
+    val latitude: Double
+    val longitude: Double
+    internal val nativeValue: NativeGeoPoint
+}
+
+/** Serializer for [GeoPoint]. If used with [FirebaseEncoder] performs serialization using native Firebase mechanisms. */
+object GeoPointSerializer : SpecialValueSerializer<GeoPoint>(
+    serialName = "GeoPoint",
+    toNativeValue = GeoPoint::nativeValue,
+    fromNativeValue = { value ->
+        when (value) {
+            is NativeGeoPoint -> GeoPoint(value)
+            else -> throw SerializationException("Cannot deserialize $value")
+        }
+    }
+)

firebase-firestore/src/commonMain/kotlin/dev/gitlive/firebase/firestore/Timestamp.kt

@@ -32,8 +32,8 @@ expect class Timestamp internal constructor(nativeValue: NativeTimestamp): BaseT
 }
 
 fun Timestamp.Companion.fromMilliseconds(milliseconds: Double): Timestamp =
-    Timestamp((milliseconds / 1000).toLong(), (milliseconds * 1000).toInt() % 1000000)
-fun Timestamp.toMilliseconds(): Double = seconds * 1000 + (nanoseconds / 1000.0)
+    Timestamp((milliseconds / 1000).toLong(), ((milliseconds % 1000) * 1000000).toInt())
+fun Timestamp.toMilliseconds(): Double = seconds * 1000 + nanoseconds / 1000000.0
 
 /** A serializer for [BaseTimestamp]. If used with [FirebaseEncoder] performs serialization using native Firebase mechanisms. */
 object BaseTimestampSerializer : SpecialValueSerializer<BaseTimestamp>(

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

@@ -79,27 +79,35 @@ expect open class Query {
     internal fun _endAt(vararg fieldValues: Any): Query
 }
 
-fun Query.where(field: String, equalTo: Any?) = _where(field, equalTo)
-fun Query.where(path: FieldPath, equalTo: Any?) = _where(path, equalTo)
-fun Query.where(field: String, equalTo: DocumentReference) = _where(field, equalTo)
-fun Query.where(path: FieldPath, equalTo: DocumentReference) = _where(path, equalTo)
-fun Query.where(field: String, lessThan: Any? = null, greaterThan: Any? = null, arrayContains: Any? = null) = _where(field, lessThan, greaterThan, arrayContains)
-fun Query.where(path: FieldPath, lessThan: Any? = null, greaterThan: Any? = null, arrayContains: Any? = null) = _where(path, lessThan, greaterThan, arrayContains)
-fun Query.where(field: String, inArray: List<Any>? = null, arrayContainsAny: List<Any>? = null) = _where(field, inArray, arrayContainsAny)
-fun Query.where(path: FieldPath, inArray: List<Any>? = null, arrayContainsAny: List<Any>? = null) = _where(path, inArray, arrayContainsAny)
+/** @return a native value of a wrapper or self. */
+private val Any.value get() = when (this) {
+    is Timestamp -> nativeValue
+    is GeoPoint -> nativeValue
+    is DocumentReference -> nativeValue
+    else -> this
+}
+
+fun Query.where(field: String, equalTo: Any?) = _where(field, equalTo,value)
+fun Query.where(path: FieldPath, equalTo: Any?) = _where(path, equalTo?.value)
+fun Query.where(field: String, equalTo: DocumentReference) = _where(field, equalTo.value)
+fun Query.where(path: FieldPath, equalTo: DocumentReference) = _where(path, equalTo.value)
+fun Query.where(field: String, lessThan: Any? = null, greaterThan: Any? = null, arrayContains: Any? = null) = _where(field, lessThan?.value, greaterThan?.value, arrayContains?.value)
+fun Query.where(path: FieldPath, lessThan: Any? = null, greaterThan: Any? = null, arrayContains: Any? = null) = _where(path, lessThan?.value, greaterThan?.value, arrayContains?.value)
+fun Query.where(field: String, inArray: List<Any>? = null, arrayContainsAny: List<Any>? = null) = _where(field, inArray?.value, arrayContainsAny?.value)
+fun Query.where(path: FieldPath, inArray: List<Any>? = null, arrayContainsAny: List<Any>? = null) = _where(path, inArray?.value, arrayContainsAny?.value)
 
 fun Query.orderBy(field: String, direction: Direction = Direction.ASCENDING) = _orderBy(field, direction)
 fun Query.orderBy(field: FieldPath, direction: Direction = Direction.ASCENDING) = _orderBy(field, direction)
 
 fun Query.startAfter(document: DocumentSnapshot) = _startAfter(document)
-fun Query.startAfter(vararg fieldValues: Any) = _startAfter(*fieldValues)
+fun Query.startAfter(vararg fieldValues: Any) = _startAfter(*(fieldValues.map { it.value }.toTypedArray()))
 fun Query.startAt(document: DocumentSnapshot) = _startAt(document)
-fun Query.startAt(vararg fieldValues: Any) = _startAt(*fieldValues)
+fun Query.startAt(vararg fieldValues: Any) = _startAt(*(fieldValues.map { it.value }.toTypedArray()))
 
 fun Query.endBefore(document: DocumentSnapshot) = _endBefore(document)
-fun Query.endBefore(vararg fieldValues: Any) = _endBefore(*fieldValues)
+fun Query.endBefore(vararg fieldValues: Any) = _endBefore(*(fieldValues.map { it.value }.toTypedArray()))
 fun Query.endAt(document: DocumentSnapshot) = _endAt(document)
-fun Query.endAt(vararg fieldValues: Any) = _endAt(*fieldValues)
+fun Query.endAt(vararg fieldValues: Any) = _endAt(*(fieldValues.map { it.value }.toTypedArray()))
 
 expect class WriteBatch {
     inline fun <reified T> set(documentRef: DocumentReference, data: T, encodeDefaults: Boolean = true, merge: Boolean = false): WriteBatch
@@ -120,7 +128,13 @@ expect class WriteBatch {
     suspend fun commit()
 }
 
-expect class DocumentReference {
+/** A class representing a platform specific Firebase DocumentReference. */
+expect class NativeDocumentReference
+
+/** A class representing a Firebase DocumentReference. */
+@Serializable(with = DocumentReferenceSerializer::class)
+expect class DocumentReference internal constructor(nativeValue: NativeDocumentReference) {
+    internal val nativeValue: NativeDocumentReference
 
     val id: String
     val path: String
@@ -147,6 +161,20 @@ expect class DocumentReference {
     suspend fun delete()
 }
 
+/**
+ * A serializer for [DocumentReference]. If used with [FirebaseEncoder] performs serialization using native Firebase mechanisms.
+ */
+object DocumentReferenceSerializer : SpecialValueSerializer<DocumentReference>(
+    serialName = "DocumentReference",
+    toNativeValue = DocumentReference::nativeValue,
+    fromNativeValue = { value ->
+        when (value) {
+            is NativeDocumentReference -> DocumentReference(value)
+            else -> throw SerializationException("Cannot deserialize $value")
+        }
+    }
+)
+
 expect class CollectionReference : Query {
     val path: String
     val document: DocumentReference

firebase-firestore/src/commonTest/kotlin/dev/gitlive/firebase/firestore/GeoPointTests.kt

@@ -0,0 +1,40 @@
+package dev.gitlive.firebase.firestore
+
+import dev.gitlive.firebase.decode
+import dev.gitlive.firebase.encode
+import kotlinx.serialization.Serializable
+import kotlin.test.Test
+import kotlin.test.assertEquals
+
+@Serializable
+data class TestDataWithGeoPoint(
+    val uid: String,
+    val location: GeoPoint
+)
+
+@Suppress("UNCHECKED_CAST")
+class GeoPointTests {
+
+    @Test
+    fun encodeGeoPointObject() = runTest {
+        val geoPoint = GeoPoint(12.3, 45.6)
+        val item = TestDataWithGeoPoint("123", geoPoint)
+        val encoded = encodedAsMap(encode(item, shouldEncodeElementDefault = false))
+        assertEquals("123", encoded["uid"])
+        // check GeoPoint is encoded to a platform representation
+        assertEquals(geoPoint.nativeValue, encoded["location"])
+    }
+
+    @Test
+    fun decodeGeoPointObject() = runTest {
+        val geoPoint = GeoPoint(12.3, 45.6)
+        val obj = mapOf(
+            "uid" to "123",
+            "location" to geoPoint.nativeValue
+        ).asEncoded()
+        val decoded: TestDataWithGeoPoint = decode(obj)
+        assertEquals("123", decoded.uid)
+        // check a platform GeoPoint is properly wrapped
+        assertEquals(geoPoint, decoded.location)
+    }
+}