feat(rtdb, firestore): create values() and dataObjects() Flows (#4804)

Author: thatfiredev

firebase-database/CHANGELOG.md

@@ -1,4 +1,11 @@
 # Unreleased
+* [unchanged] Updated to accommodate the release of the updated
+  [database] Kotlin extensions library.
+
+## Kotlin
+* [feature] Added
+  [`Query.values<T>()`](/docs/reference/kotlin/com/google/firebase/database/ktx/package-summary#values)
+  Kotlin Flows to listen for realtime updates and convert its values to a specific type.
 
 # 20.1.0
 * [unchanged] Updated to accommodate the release of the updated

firebase-database/ktx/api.txt

@@ -54,6 +54,7 @@ package com.google.firebase.database.ktx {
     method @NonNull public static kotlinx.coroutines.flow.Flow<com.google.firebase.database.DataSnapshot> getSnapshots(@NonNull com.google.firebase.database.Query);
     method public static inline <reified T> T getValue(@NonNull com.google.firebase.database.DataSnapshot);
     method public static inline <reified T> T getValue(@NonNull com.google.firebase.database.MutableData);
+    method public static inline <reified T> kotlinx.coroutines.flow.Flow<? extends T> values(@NonNull com.google.firebase.database.Query);
   }
 
 }

firebase-database/ktx/src/main/kotlin/com/google/firebase/database/ktx/Database.kt

@@ -31,7 +31,9 @@ import com.google.firebase.platforminfo.LibraryVersionComponent
 import kotlinx.coroutines.cancel
 import kotlinx.coroutines.channels.awaitClose
 import kotlinx.coroutines.channels.trySendBlocking
+import kotlinx.coroutines.flow.Flow
 import kotlinx.coroutines.flow.callbackFlow
+import kotlinx.coroutines.flow.map
 
 /** Returns the [FirebaseDatabase] instance of the default [FirebaseApp]. */
 val Firebase.database: FirebaseDatabase
@@ -127,6 +129,16 @@ val Query.childEvents
       awaitClose { removeEventListener(listener) }
     }
 
+/**
+ * Starts listening to this query and emits its values converted to a POJO via a [Flow].
+ *
+ * - When the returned flow starts being collected, a [ValueEventListener] will be attached.
+ * - When the flow completes, the listener will be removed.
+ */
+inline fun <reified T : Any> Query.values(): Flow<T?> {
+  return snapshots.map { it.getValue(T::class.java) }
+}
+
 internal const val LIBRARY_NAME: String = "fire-db-ktx"
 
 /** @suppress */

firebase-firestore/CHANGELOG.md

@@ -1,11 +1,30 @@
 # Unreleased
-* [feature] Add support for disjunctions in queries (`OR` queries).
 * [fixed] Fixed stack overflow caused by deeply nested server timestamps (#4702).
 
+## Kotlin
+* [feature] Added
+  [`Query.dataObjects<T>()`](/docs/reference/kotlin/com/google/firebase/firestore/ktx/package-summary#dataObjects)
+  and
+  [`DocumentReference.dataObjects<T>()`](/docs/reference/kotlin/com/google/firebase/firestore/ktx/package-summary#dataObjects_1)
+  Kotlin Flows to listen for realtime updates and convert its values to a specific type.
+
+# 24.4.5
+* [feature] Add support for disjunctions in queries (`OR` queries).
+
+## Kotlin
+The Kotlin extensions library transitively includes the updated
+`firebase-firestore` library. The Kotlin extensions library has no additional
+updates.
+
 # 24.4.4
 * [changed] Relaxed certain query validations performed by the SDK (#4231).
 * [changed] Updated grpc to 1.52.1 and javalite, protoc, protobufjavautil to 3.21.11.
 
+## Kotlin
+The Kotlin extensions library transitively includes the updated
+`firebase-firestore` library. The Kotlin extensions library has no additional
+updates.
+
 # 24.4.3
 * [fixed] Fixed a potential high-memory usage issue.
 * [fixed] Fixed an issue that stopped some performance optimization from being

firebase-firestore/ktx/api.txt

@@ -2,6 +2,8 @@
 package com.google.firebase.firestore.ktx {
 
   public final class FirestoreKt {
+    method public static inline <reified T> kotlinx.coroutines.flow.Flow<? extends T> dataObjects(@NonNull com.google.firebase.firestore.DocumentReference, @NonNull com.google.firebase.firestore.MetadataChanges metadataChanges = com.google.firebase.firestore.MetadataChanges.EXCLUDE);
+    method public static inline <reified T> kotlinx.coroutines.flow.Flow<? extends java.util.List<? extends T>> dataObjects(@NonNull com.google.firebase.firestore.Query, @NonNull com.google.firebase.firestore.MetadataChanges metadataChanges = com.google.firebase.firestore.MetadataChanges.EXCLUDE);
     method @NonNull public static com.google.firebase.firestore.FirebaseFirestore firestore(@NonNull com.google.firebase.ktx.Firebase, @NonNull com.google.firebase.FirebaseApp app);
     method @NonNull public static com.google.firebase.firestore.FirebaseFirestoreSettings firestoreSettings(@NonNull kotlin.jvm.functions.Function1<? super com.google.firebase.firestore.FirebaseFirestoreSettings.Builder,kotlin.Unit> init);
     method public static inline <reified T> T getField(@NonNull com.google.firebase.firestore.DocumentSnapshot, @NonNull String field);

firebase-firestore/ktx/src/main/kotlin/com/google/firebase/firestore/ktx/Firestore.kt

@@ -35,6 +35,7 @@ import kotlinx.coroutines.channels.awaitClose
 import kotlinx.coroutines.channels.trySendBlocking
 import kotlinx.coroutines.flow.Flow
 import kotlinx.coroutines.flow.callbackFlow
+import kotlinx.coroutines.flow.map
 
 /** Returns the [FirebaseFirestore] instance of the default [FirebaseApp]. */
 val Firebase.firestore: FirebaseFirestore
@@ -240,3 +241,31 @@ fun Query.snapshots(
     awaitClose { registration.remove() }
   }
 }
+
+/**
+ * Starts listening to this query with the given options and emits its values converted to a POJO
+ * via a [Flow].
+ *
+ * - When the returned flow starts being collected, an [EventListener] will be attached.
+ * - When the flow completes, the listener will be removed.
+ *
+ * @param metadataChanges controls metadata-only changes. Default: [MetadataChanges.EXCLUDE]
+ * @param T The type of the object to convert to.
+ */
+inline fun <reified T : Any> Query.dataObjects(
+  metadataChanges: MetadataChanges = MetadataChanges.EXCLUDE
+): Flow<List<T>> = snapshots(metadataChanges).map { it.toObjects(T::class.java) }
+
+/**
+ * Starts listening to the document referenced by this `DocumentReference` with the given options
+ * and emits its values converted to a POJO via a [Flow].
+ *
+ * - When the returned flow starts being collected, an [EventListener] will be attached.
+ * - When the flow completes, the listener will be removed.
+ *
+ * @param metadataChanges controls metadata-only changes. Default: [MetadataChanges.EXCLUDE]
+ * @param T The type of the object to convert to.
+ */
+inline fun <reified T : Any> DocumentReference.dataObjects(
+  metadataChanges: MetadataChanges = MetadataChanges.EXCLUDE
+): Flow<T?> = snapshots(metadataChanges).map { it.toObject(T::class.java) }