Merge branch 'master' into publish_maven_central

Author: nbransby

README.md

@@ -1,46 +1,129 @@
-<h1 align="left">Firebase Kotlin SDK <img alt="GitHub last commit" src="https://img.shields.io/github/last-commit/teamhubapp/firebase-kotlin-sdk?style=flat-square"></h1>
+<h1 align="left">Firebase Kotlin SDK <img alt="GitHub last commit" src="https://img.shields.io/github/last-commit/gitliveapp/firebase-kotlin-sdk?style=flat-square"></h1>
 <img align="left" width="75px" src="https://avatars2.githubusercontent.com/u/42865805?s=200&v=4"> 
   <b>Built and maintained with 🧡 by <a href="https://teamhub.dev">TeamHub</a></b><br/>
   <i>Real-time code collaboration inside any IDE</i><br/>
   🔓 <a href="https://teamhub.typeform.com/to/uSS8cv">Request Early Access</a>
 <h4></h4>
 
-The Firebase Kotlin SDK is a Kotlin-first SDK for Firebase. It's API is similar to the [Firebase Android SDK Kotlin Extensions](https://firebase.github.io/firebase-android-sdk/reference/kotlin/firebase-ktx/) but it also supports multiplatform projects, enabling you to use Firebase directly from your common source targeting *iOS*, *Android* or *JS*.
-
-## Kotlin-first design
-
+The Firebase Kotlin SDK is a Kotlin-first SDK for Firebase. It's API is similar to the [Firebase Android SDK Kotlin Extensions](https://firebase.github.io/firebase-android-sdk/reference/kotlin/firebase-ktx/) but also supports multiplatform projects, enabling you to use Firebase directly from your common source targeting *iOS*, *Android* or *JS*.
 
 ## Available libraries
 
 The following libraries are available for the various Firebase products.
 
 | Service or Product	                                                                 | Gradle Dependency                                                                                                                   | API Coverage                                                                                                                                                                                                               |
 | ------------------------------------------------------------------------------------ | :-----------------------------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [Authentication](https://firebase.google.com/docs/auth#kotlin-android)               | [`dev.teamhub.firebase:firebase-auth:0.1.0`](https://mvnrepository.com/artifact/dev.teamhub.firebase/firebase-auth/0.1.0)           | [![0-50%](https://img.shields.io/badge/-0--50%25-red?style=flat-square)](/firebase-auth/src/commonMain/kotlin/dev/teamhub/firebase/auth/auth.kt) [![Android: 50%](https://img.shields.io/badge/Android-50%25-green?style=flat-square)](/firebase-auth/src/androidMain/kotlin/dev/teamhub/firebase/auth/auth.kt) [![JS: 50%](https://img.shields.io/badge/Web-50%25-red?style=flat-square)](/firebase-auth/src/jsMain/kotlin/dev/teamhub/firebase/auth/auth.kt) [![iOS: 0%](https://img.shields.io/badge/iOS-0%25-blue?style=flat-square)](/firebase-auth/src/iosMain/kotlin/dev/teamhub/firebase/auth/auth.kt) |
-| [Realtime Database](https://firebase.google.com/docs/database#kotlin-android)        | [`dev.teamhub.firebase:firebase-database:0.1.0`](https://mvnrepository.com/artifact/dev.teamhub.firebase/firebase-database/0.1.0)   | [![0-50%](https://img.shields.io/badge/-0--50%25-red?style=flat-square)](/firebase-database/src/commonMain/kotlin/dev/teamhub/firebase/auth/database.kt) [![Android: 50%](https://img.shields.io/badge/Android-50%25-green?style=flat-square)](/firebase-database/src/androidMain/kotlin/dev/teamhub/firebase/database/database.kt) [![JS: 50%](https://img.shields.io/badge/Web-50%25-red?style=flat-square)](/firebase-database/src/jsMain/kotlin/dev/teamhub/firebase/database/database.kt) [![iOS: 0%](https://img.shields.io/badge/iOS-0%25-blue?style=flat-square)](/firebase-database/src/iosMain/kotlin/dev/teamhub/firebase/database/database.kt) |
-| [Cloud Firestore](https://firebase.google.com/docs/firestore#kotlin-android)         | [`dev.teamhub.firebase:firebase-firestore:0.1.0`](https://mvnrepository.com/artifact/dev.teamhub.firebase/firebase-firestore/0.1.0) | [![0-50%](https://img.shields.io/badge/-0--50%25-red?style=flat-square)](/firebase-firestore/src/commonMain/kotlin/dev/teamhub/firebase/firestore/firestore.kt) [![Android: 50%](https://img.shields.io/badge/Android-50%25-green?style=flat-square)](/firebase-auth/src/androidMain/kotlin/dev/teamhub/firebase/firestore/firestore.kt) [![JS: 50%](https://img.shields.io/badge/Web-50%25-red?style=flat-square)](/firebase-firestore/src/jsMain/kotlin/dev/teamhub/firebase/firestore/firestore.kt) [![iOS: 0%](https://img.shields.io/badge/iOS-0%25-blue?style=flat-square)](/firebase-firestore/src/iosMain/kotlin/dev/teamhub/firebase/firestore/firestore.kt) |
-| [Cloud Functions](https://firebase.google.com/docs/functions/callable#kotlin-android)| [`dev.teamhub.firebase:firebase-functions:0.1.0`](https://mvnrepository.com/artifact/dev.teamhub.firebase/firebase-functions/0.1.0) | [![0-50%](https://img.shields.io/badge/-0--50%25-orange?style=flat-square)](/firebase-functions/src/commonMain/kotlin/dev/teamhub/firebase/functions/functions.kt) [![Android: 50%](https://img.shields.io/badge/Android-50%25-green?style=flat-square)](/firebase-functions/src/androidMain/kotlin/dev/teamhub/firebase/functions/functions.kt) [![JS: 50%](https://img.shields.io/badge/Web-50%25-red?style=flat-square)](/firebase-functions/src/jsMain/kotlin/dev/teamhub/firebase/functions/functions.kt) [![iOS: 0%](https://img.shields.io/badge/iOS-0%25-blue?style=flat-square)](/firebase-functions/src/iosMain/kotlin/dev/teamhub/firebase/functions/functions.kt) |
-| [Cloud Messaging](https://firebase.google.com/docs/messaging#kotlin-android)         | [`dev.teamhub.firebase:firebase-messaging:0.1.0`](https://mvnrepository.com/artifact/dev.teamhub.firebase/firebase-messaging/0.1.0) | ![0%](https://img.shields.io/badge/-0%25-lightgrey?style=flat-square) |
-| [Cloud Storage](https://firebase.google.com/docs/storage#kotlin-android)             | [`dev.teamhub.firebase:firebase-storage:0.1.0`](https://mvnrepository.com/artifact/dev.teamhub.firebase/firebase-storage/0.1.0)     | ![0%](https://img.shields.io/badge/-0%25-lightgrey?style=flat-square) |
+| [Authentication](https://firebase.google.com/docs/auth#kotlin-android)               | [`dev.gitlive.firebase:firebase-auth:0.1.0`](https://mvnrepository.com/artifact/dev.teamhub.firebase/firebase-auth/0.1.0)           | [![40%](https://img.shields.io/badge/-40%25-red?style=flat-square)](/firebase-auth/src/commonMain/kotlin/dev/teamhub/firebase/auth/auth.kt) |
+| [Realtime Database](https://firebase.google.com/docs/database#kotlin-android)        | [`dev.gitlive.firebase:firebase-database:0.1.0`](https://mvnrepository.com/artifact/dev.teamhub.firebase/firebase-database/0.1.0)   | [![70%](https://img.shields.io/badge/-70%25-orange?style=flat-square)](/firebase-database/src/commonMain/kotlin/dev/teamhub/firebase/auth/database.kt) |
+| [Cloud Firestore](https://firebase.google.com/docs/firestore#kotlin-android)         | [`dev.gitlive.firebase:firebase-firestore:0.1.0`](https://mvnrepository.com/artifact/dev.teamhub.firebase/firebase-firestore/0.1.0) | [![60%](https://img.shields.io/badge/-60%25-orange?style=flat-square)](/firebase-firestore/src/commonMain/kotlin/dev/teamhub/firebase/firestore/firestore.kt) |
+| [Cloud Functions](https://firebase.google.com/docs/functions/callable#kotlin-android)| [`dev.gitlive.firebase:firebase-functions:0.1.0`](https://mvnrepository.com/artifact/dev.teamhub.firebase/firebase-functions/0.1.0) | [![80%](https://img.shields.io/badge/-80%25-green?style=flat-square)](/firebase-functions/src/commonMain/kotlin/dev/teamhub/firebase/functions/functions.kt) |
+| [Cloud Messaging](https://firebase.google.com/docs/messaging#kotlin-android)         | [`dev.gitlive.firebase:firebase-messaging:0.1.0`](https://mvnrepository.com/artifact/dev.teamhub.firebase/firebase-messaging/0.1.0) | ![0%](https://img.shields.io/badge/-0%25-lightgrey?style=flat-square) |
+| [Cloud Storage](https://firebase.google.com/docs/storage#kotlin-android)             | [`dev.gitlive.firebase:firebase-storage:0.1.0`](https://mvnrepository.com/artifact/dev.teamhub.firebase/firebase-storage/0.1.0)     | ![0%](https://img.shields.io/badge/-0%25-lightgrey?style=flat-square) |
+
+Is the Firebase library or API you need missing? [Create an issue](https://github.com/GitLiveApp/firebase-kotlin-sdk/issues/new?labels=API+coverage&template=increase-api-coverage.md&title=Add+%5Bclass+name%5D.%5Bfunction+name%5D+to+%5Blibrary+name%5D+for+%5Bplatform+names%5D) to request additional API coverage or be awesome and [submit a PR](https://github.com/GitLiveApp/firebase-kotlin-sdk/fork)
+
+## Kotlin-first design
 
-Is the Firebase library or API you need missing? [Create an issue](https://github.com/TeamHubApp/firebase-kotlin-sdk/issues/new?labels=API+coverage&template=increase-api-coverage.md&title=Add+%5Bclass+name%5D.%5Bfunction+name%5D+to+%5Blibrary+name%5D+for+%5Bplatform+names%5D) to request additional API coverage or be awesome and [submit a PR](https://github.com/TeamHubApp/firebase-kotlin-sdk/fork)
+Unlike the Kotlin Extensions for the Firebase Android SDK this project does not extend a Java based SDK so we get the full power of Kotlin including coroutines and serialization!
 
-## Getting started
+<h3><a href="https://kotlinlang.org/docs/tutorials/coroutines/async-programming.html#coroutines">Suspending functions</a></h3>
 
-### New to Firebase?
+Asynchronous operations that return a single or no value are represented by suspending functions in the SDK instead of callbacks, listeners or OS specific types such as [Task](https://developer.android.com/reference/com/google/android/play/core/tasks/Task), for example:
 
-Head over to the main Firebase documentation and follow the steps 
+```kotlin
+suspend fun signInWithCustomToken(token: String): AuthResult
+```
+
+It is important to remember that unlike a callback based API, wating for suspending functions to complete is implicit and so if you don't want to wait for the result you can `launch` a new coroutine:
 
-### Configure Firebase
+```kotlin
+//TODO don't use GlobalScope
+GlobalScope.launch {
+  Firebase.auth.signOut()
+}
+```
 
-Since you most likely want to share your firebase configuration across platforms you should configure Firebase programatically in your common source instead of a platform-specific configuration file.
+<h3><a href="https://kotlinlang.org/docs/reference/coroutines/flow.html">Flows</a></h3>
 
-You can do this as follows:
+Asynchronous streams of values are represented by Flows in the SDK instead of repeatedly invoked callbacks or listeners, for example:
 
 ```kotlin
-val options = FirebaseOptions.Builder()
-        .setApplicationId("1:27992087142:android:ce3b6448250083d1") // Required for Analytics.
-        .setApiKey("AIzaSyADUe90ULnQDuGShD9W23RDP0xmeDc6Mvw") // Required for Auth.
-        .setDatabaseUrl("https://myproject.firebaseio.com") // Required for RTDB.
-        .build()
+val snapshots: Flow<DocumentSnapshot>
 ```
+
+The flows are cold, which means a new listener is added every time a terminal operator is applied to the resulting flow. A buffer with the [default size](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.channels/-channel/-b-u-f-f-e-r-e-d.html) is used to buffer values received from the listener, use the [`buffer` operator](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/buffer.html) on the flow to specify a user-defined value and to control what happens when data is produced faster than consumed, i.e. to control the back-pressure behavior. Often you are only interested in the latest value received, in this case you can use the [`conflate` operator](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/conflate.html) to disable buffering.
+
+The listener is removed once the flow [completes](https://kotlinlang.org/docs/reference/coroutines/flow.html#flow-completion) or is [cancelled](https://kotlinlang.org/docs/reference/coroutines/flow.html#flow-cancellation).
+
+<h3><a href="https://github.com/Kotlin/kotlinx.serialization">Serialization</a></h3>
+
+The official Firebase SDKs use different platform-specific ways to support writing data with and without custom classes in [Cloud Firestore](https://firebase.google.com/docs/firestore/manage-data/add-data#custom_objects), [Realtime Database](https://firebase.google.com/docs/database/android/read-and-write#basic_write) and [Functions](https://firebase.google.com/docs/functions/callable).
+
+The Firebase Kotlin SDK uses Kotlin serialization to read and write custom classes to Firebase. To use Kotlin serialization in your project add the plugin to your gradle file:
+
+```groovy
+plugins {
+    kotlin("multiplatform") // or kotlin("jvm") or any other kotlin plugin
+    kotlin("plugin.serialization") version "1.3.70"
+}
+```
+
+Then mark you custom classes `@Serializable`:
+
+```kotlin
+@Serializable
+data class City(val name: String)
+```
+
+Instances of these classes can now be passed [along with their serializer](https://github.com/Kotlin/kotlinx.serialization/blob/master/docs/runtime_usage.md#obtaining-serializers) to the SDK:
+
+```kotlin
+db.collection("cities").document("LA").set(City.serializer(), city)
+```
+
+You can also omit the serializer for classes that does not have generic type arguments, these functions are marked [`@ImplicitReflectionSerializer`](https://github.com/Kotlin/kotlinx.serialization/blob/master/docs/runtime_usage.md#implicit-reflection-serializers) and their usage is discouraged in general because it is implicit and uses reflection (and therefore not working on Kotlin/Native), but may be useful shorthand in some cases.
+
+<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 query operators use named arguments:
+
+```kotlin
+citiesRef.whereEqualTo("state", "CA")
+citiesRef.whereArrayContains("regions", "west_coast")
+//...becomes...
+citiesRef.where("state", equalTo = "CA")
+citiesRef.where("regions", arrayContains = "west_coast")
+````
+
+## Multiplatform
+
+The Firebase Kotlin SDK provides a common API to access Firebase for projects targeting *iOS*, *Android* and *JS* meaning you can use Firebase directly in your common code. Under the hood, the SDK achieves this by binding to the respective official Firebase SDK for each supported platform.
+
+### Accessing the underlying Firebase SDK
+
+In some cases you might want to access the underlying official Firebase SDK in platform specific code, for example when the common API is missing the functionality you need. For this purpose each class in the SDK has `android`, `ios` and `js` properties which holds the  equivalent object of the underlying official Firebase SDK. 
+
+These properties are only accessible from the equivalent target's source set. For example to disable persistence in Cloud Firestore on Android you can write the following in your Android specific code (e.g. `androidMain` or `androidTest`):
+
+```kotlin
+  Firebase.firestore.android.firestoreSettings = FirebaseFirestoreSettings.Builder(Firebase.firestore.android.firestoreSettings)
+          .setPersistenceEnabled(false)
+          .build()
+```
+
+### NPM modules
+
+If you are building a Kotlin multiplatform library which will be consumed from JS code you may need to include the SDK in your `package.json`, you can do it as follows:
+
+```json
+"dependencies": {
+  "@gitlive/firebase-auth": "0.1.0",
+  "@gitlive/firebase-database": "0.1.0",
+  "@gitlive/firebase-firestore": "0.1.0",
+  "@gitlive/firebase-functions": "0.1.0",
+  "@gitlive/firebase-storage": "0.1.0",
+  "@gitlive/firebase-messaging": "0.1.0"
+}
+```
+
+

firebase-common/src/iosMain/kotlin/dev/teamhub/firebase/_decoders.kt

@@ -6,7 +6,7 @@ import kotlinx.serialization.SerialDescriptor
 import kotlinx.serialization.StructureKind
 
 actual fun FirebaseDecoder.structureDecoder(desc: SerialDescriptor, vararg typeParams: KSerializer<*>): CompositeDecoder = when(desc.kind as StructureKind) {
-        StructureKind.CLASS -> (value as Map<*, *>).let { map ->
+        StructureKind.CLASS, StructureKind.OBJECT -> (value as Map<*, *>).let { map ->
             FirebaseClassDecoder(map.size, { map.containsKey(it) }) { desc, index -> map[desc.getElementName(index)] }
         }
         StructureKind.LIST -> (value as List<*>).let {

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

@@ -11,7 +11,10 @@ import dev.teamhub.firebase.database.ChildEvent.Type
 import dev.teamhub.firebase.decode
 import kotlinx.coroutines.channels.awaitClose
 import kotlinx.coroutines.coroutineScope
+import kotlinx.coroutines.flow.Flow
 import kotlinx.coroutines.flow.callbackFlow
+import kotlinx.coroutines.flow.filter
+import kotlinx.coroutines.flow.produceIn
 import kotlinx.coroutines.selects.select
 import kotlinx.coroutines.tasks.asDeferred
 import kotlinx.coroutines.tasks.await

firebase-database/src/iosMain/kotlin/dev/teamhub/firebase/database/database.kt

@@ -11,6 +11,8 @@ import kotlinx.coroutines.CompletableDeferred
 import kotlinx.coroutines.channels.awaitClose
 import kotlinx.coroutines.coroutineScope
 import kotlinx.coroutines.flow.callbackFlow
+import kotlinx.coroutines.flow.filter
+import kotlinx.coroutines.flow.produceIn
 import kotlinx.coroutines.selects.select
 import kotlinx.serialization.DeserializationStrategy
 import kotlinx.serialization.SerializationStrategy

firebase-firestore/src/iosMain/kotlin/dev/teamhub/firebase/firestore/firestore.kt

@@ -1,6 +1,7 @@
 package dev.teamhub.firebase.firestore
 
 import cocoapods.FirebaseFirestore.*
+import dev.teamhub.firebase.*
 import kotlinx.cinterop.*
 import kotlinx.coroutines.CompletableDeferred
 import kotlinx.coroutines.channels.awaitClose

gradle.properties

@@ -1,2 +1,4 @@
 kotlin.code.style=official
 kotlin.js.experimental.generateKotlinExternals=true
+org.gradle.daemon=true
+org.gradle.jvmargs=-Xmx2560m