Allow retrieving metadata with queries #1154

Author: EddyVerbruggen

.travis.yml

@@ -29,8 +29,8 @@ matrix:
     - os: osx
       env:
         - BuildiOS="12"
-        - Xcode="10.0"
-      osx_image: xcode10.0
+        - Xcode="10.2"
+      osx_image: "xcode10.2"
       language: node_js
       node_js: "8"
       jdk: oraclejdk8

demo-ng/app/tabs/firestore/firestore.component.ts

@@ -263,25 +263,38 @@ export class FirestoreComponent {
   firestoreDocumentObservable(): void {
     this.myCity$ = Observable.create(subscriber => {
       const docRef: firestore.DocumentReference = firebase.firestore().collection("cities").doc("SF");
-      docRef.onSnapshot((doc: firestore.DocumentSnapshot) => {
-        this.zone.run(() => {
-          this.city = <City>doc.data();
-          subscriber.next(this.city);
-        });
-      });
+      docRef.onSnapshot(
+          {includeMetadataChanges: true},
+          (doc: firestore.DocumentSnapshot) => {
+
+            const source = doc.metadata.fromCache ? "local cache" : "server";
+            console.log("Data came from " + source);
+            console.log("Has pending writes? " + doc.metadata.hasPendingWrites);
+
+            this.zone.run(() => {
+              this.city = <City>doc.data();
+              subscriber.next(this.city);
+            });
+          });
     });
   }
 
   firestoreCollectionObservable(): void {
     this.myCities$ = Observable.create(subscriber => {
       const colRef: firestore.CollectionReference = firebase.firestore().collection("cities");
-      colRef.onSnapshot((snapshot: firestore.QuerySnapshot) => {
-        this.zone.run(() => {
-          this.cities = [];
-          snapshot.forEach(docSnap => this.cities.push(<City>docSnap.data()));
-          subscriber.next(this.cities);
-        });
-      });
+      colRef.onSnapshot(
+          {includeMetadataChanges: true},
+          (snapshot: firestore.QuerySnapshot) => {
+            const source = snapshot.metadata.fromCache ? "local cache" : "server";
+            console.log("Data came from " + source);
+            console.log("Has pending writes? " + snapshot.metadata.hasPendingWrites);
+
+            this.zone.run(() => {
+              this.cities = [];
+              snapshot.forEach(docSnap => this.cities.push(<City>docSnap.data()));
+              subscriber.next(this.cities);
+            });
+          });
     });
   }
 

docs/FIRESTORE.md

@@ -64,17 +64,21 @@ unsubscribe();
 
 > Using **Observables**? [Check the example in the demo app](https://github.com/EddyVerbruggen/nativescript-plugin-firebase/blob/f6972433dea48bf1d342a6e4ef7f955dff341837/demo-ng/app/item/items.component.ts#L187-L198).
 
-#### Determine if results are from cache or not
-If persistence is enabled, query results will first be returned from the local cache if available, and then from network. To determine if a document has been returned from the cache or not, pass the includeMetadataChanges parameter and inspect the metadata:
+#### Snapshot metadata (for queries and documents)
+Firestore can return metadata when passing the `includeMetadataChanges` boolean property. This can be used for:
+
+- `snapshot.metadata.fromCache`: True if the snapshot was created from cached data rather than guaranteed up-to-date server data.
+- `snapshot.metadata.hasPendingWrites`: True if the snapshot contains the result of local writes that have not yet been committed to the backend.
 
 ```typescript
+import { firestore } from "nativescript-plugin-firebase";
 const citiesCollection = firebase.firestore().collection("cities");
 
 const unsubscribe = citiesCollection.onSnapshot(({ includeMetadataChanges: true }, snapshot: firestore.QuerySnapshot) => {
   snapshot.forEach(city => console.log(city.data()));
 
-  const source = snapshot.metadata.fromCache ? "local cache" : "server";
-  console.log("Data came from " + source);
+  console.log("Data came from " + (snapshot.metadata.fromCache ? "local cache" : "server"));
+  console.log("Has pending writes? " + snapshot.metadata.hasPendingWrites);
 });
 
 // then after a while, to detach the listener:

src/firebase.android.ts

@@ -3,7 +3,9 @@ import { AndroidActivityResultEventData } from "tns-core-modules/application";
 import lazy from "tns-core-modules/utils/lazy";
 import { ad as AndroidUtils } from "tns-core-modules/utils/utils";
 import {
-  DataSnapshot, FBData, FBDataSingleEvent, FBErrorData, FirebaseQueryResult,
+  DataSnapshot,
+  FBDataSingleEvent,
+  FBErrorData,
   firestore,
   GetAuthTokenOptions,
   GetAuthTokenResult,
@@ -27,6 +29,11 @@ const gmsTasks = (<any>com.google.android.gms).tasks;
 class DocumentSnapshot extends DocumentSnapshotBase {
   android: com.google.firebase.firestore.DocumentSnapshot;
 
+  metadata = {
+    fromCache: this.snapshot.getMetadata().isFromCache(),
+    hasPendingWrites: this.snapshot.getMetadata().hasPendingWrites()
+  };
+
   constructor(public snapshot: com.google.firebase.firestore.DocumentSnapshot) {
     super(snapshot ? snapshot.getId() : null, snapshot.exists(), firebase.toJsObject(snapshot.getData()), convertDocRef(snapshot.getReference()));
     this.android = snapshot;
@@ -2229,7 +2236,7 @@ firebase.firestore.collection = (collectionPath: string): firestore.CollectionRe
       where: (fieldPath: string, opStr: firestore.WhereFilterOp, value: any) => firebase.firestore.where(collectionPath, fieldPath, opStr, value),
       orderBy: (fieldPath: string, directionStr: firestore.OrderByDirection): firestore.Query => firebase.firestore.orderBy(collectionPath, fieldPath, directionStr, collectionRef),
       limit: (limit: number): firestore.Query => firebase.firestore.limit(collectionPath, limit, collectionRef),
-      onSnapshot: (optionsOrCallback: any, callback?: (snapshot: QuerySnapshot) => void) => firebase.firestore.onCollectionSnapshot(collectionRef, optionsOrCallback, callback),
+      onSnapshot: (optionsOrCallback: firestore.SnapshotListenOptions | ((snapshot: QuerySnapshot) => void), callback?: (snapshot: QuerySnapshot) => void) => firebase.firestore.onCollectionSnapshot(collectionRef, optionsOrCallback, callback),
       startAfter: (snapshot: DocumentSnapshot): firestore.Query => firebase.firestore.startAfter(collectionPath, snapshot, collectionRef),
       startAt: (snapshot: DocumentSnapshot): firestore.Query => firebase.firestore.startAt(collectionPath, snapshot, collectionRef),
       endAt: (snapshot: DocumentSnapshot): firestore.Query => firebase.firestore.endAt(collectionPath, snapshot, collectionRef),
@@ -2242,9 +2249,16 @@ firebase.firestore.collection = (collectionPath: string): firestore.CollectionRe
   }
 };
 
-firebase.firestore.onDocumentSnapshot = (docRef: com.google.firebase.firestore.DocumentReference, callback: (doc: DocumentSnapshot) => void): () => void => {
-  const listener = docRef.addSnapshotListener(new com.google.firebase.firestore.EventListener({
-        onEvent: ((snapshot: com.google.firebase.firestore.DocumentSnapshot, exception) => {
+firebase.firestore.onDocumentSnapshot = (docRef: com.google.firebase.firestore.DocumentReference, optionsOrCallback: firestore.SnapshotListenOptions | ((snapshot: DocumentSnapshot) => void), callback: (doc: DocumentSnapshot) => void): () => void => {
+  let options = com.google.firebase.firestore.MetadataChanges.EXCLUDE;
+  if ((typeof optionsOrCallback) === "function") {
+    callback = <(snapshot: DocumentSnapshot) => void>optionsOrCallback;
+  } else if ((<firestore.SnapshotListenOptions>optionsOrCallback).includeMetadataChanges) {
+    options = com.google.firebase.firestore.MetadataChanges.INCLUDE;
+  }
+
+  const listener = docRef.addSnapshotListener(options, new com.google.firebase.firestore.EventListener({
+        onEvent: ((snapshot: com.google.firebase.firestore.DocumentSnapshot, exception: com.google.firebase.firestore.FirebaseFirestoreException) => {
           if (exception === null) {
             callback(new DocumentSnapshot(snapshot));
           }
@@ -2255,11 +2269,11 @@ firebase.firestore.onDocumentSnapshot = (docRef: com.google.firebase.firestore.D
   return () => listener.remove();
 };
 
-firebase.firestore.onCollectionSnapshot = (colRef: com.google.firebase.firestore.CollectionReference, optionsOrCallback: any, callback: (snapshot: QuerySnapshot) => void): () => void => {
+firebase.firestore.onCollectionSnapshot = (colRef: com.google.firebase.firestore.CollectionReference, optionsOrCallback: firestore.SnapshotListenOptions | ((snapshot: QuerySnapshot) => void), callback: (snapshot: QuerySnapshot) => void): () => void => {
   let options = com.google.firebase.firestore.MetadataChanges.EXCLUDE;
-  if ((typeof optionsOrCallback) === 'function') {
-    callback = optionsOrCallback;
-  } else if (optionsOrCallback.includeMetadataChanges) {
+  if ((typeof optionsOrCallback) === "function") {
+    callback = <(snapshot: QuerySnapshot) => void>optionsOrCallback;
+  } else if ((<firestore.SnapshotListenOptions>optionsOrCallback).includeMetadataChanges) {
     options = com.google.firebase.firestore.MetadataChanges.INCLUDE;
   }
 
@@ -2288,7 +2302,7 @@ firebase.firestore._getDocumentReference = (javaObj: JDocumentReference, collect
     get: () => firebase.firestore.getDocument(collectionPath, javaObj.getId()),
     update: (data: any) => firebase.firestore.update(collectionPath, javaObj.getId(), data),
     delete: () => firebase.firestore.delete(collectionPath, javaObj.getId()),
-    onSnapshot: (callback: (doc: DocumentSnapshot) => void) => firebase.firestore.onDocumentSnapshot(javaObj, callback),
+    onSnapshot: (optionsOrCallback: firestore.SnapshotListenOptions | ((snapshot: DocumentSnapshot) => void), callback: (doc: DocumentSnapshot) => void) => firebase.firestore.onDocumentSnapshot(javaObj, optionsOrCallback, callback),
     android: javaObj
   };
 };
@@ -2349,7 +2363,7 @@ firebase.firestore.add = (collectionPath: string, document: any): Promise<firest
             get: () => firebase.firestore.getDocument(collectionPath, docRef.getId()),
             update: (data: any) => firebase.firestore.update(collectionPath, docRef.getId(), data),
             delete: () => firebase.firestore.delete(collectionPath, docRef.getId()),
-            onSnapshot: (callback: (doc: DocumentSnapshot) => void) => firebase.firestore.onDocumentSnapshot(docRef, callback)
+            onSnapshot: (optionsOrCallback: firestore.SnapshotListenOptions | ((snapshot: DocumentSnapshot) => void), callback: (doc: DocumentSnapshot) => void) => firebase.firestore.onDocumentSnapshot(docRef, optionsOrCallback, callback)
           });
         }
       });
@@ -2565,7 +2579,7 @@ firebase.firestore._getQuery = (collectionPath: string, query: com.google.fireba
     where: (fp: string, os: firestore.WhereFilterOp, v: any): firestore.Query => firebase.firestore.where(collectionPath, fp, os, v, query),
     orderBy: (fp: string, directionStr: firestore.OrderByDirection): firestore.Query => firebase.firestore.orderBy(collectionPath, fp, directionStr, query),
     limit: (limit: number): firestore.Query => firebase.firestore.limit(collectionPath, limit, query),
-    onSnapshot: (optionsOrCallback: any, callback?: (snapshot: QuerySnapshot) => void) => firebase.firestore.onCollectionSnapshot(query, optionsOrCallback, callback),
+    onSnapshot: (optionsOrCallback: firestore.SnapshotListenOptions | ((snapshot: QuerySnapshot) => void), callback?: (snapshot: QuerySnapshot) => void) => firebase.firestore.onCollectionSnapshot(query, optionsOrCallback, callback),
     startAfter: (snapshot: DocumentSnapshot) => firebase.firestore.startAfter(collectionPath, snapshot, query),
     startAt: (snapshot: DocumentSnapshot) => firebase.firestore.startAt(collectionPath, snapshot, query),
     endAt: (snapshot: DocumentSnapshot) => firebase.firestore.endAt(collectionPath, snapshot, query),
@@ -2649,7 +2663,7 @@ function convertDocRef(docRef: JDocumentReference): firestore.DocumentReference
     get: () => firebase.firestore.getDocument(collectionPath, docRef.getId()),
     update: (data: any) => firebase.firestore.update(collectionPath, docRef.getId(), data),
     delete: () => firebase.firestore.delete(collectionPath, docRef.getId()),
-    onSnapshot: (callback: (doc: DocumentSnapshot) => void) => firebase.firestore.onDocumentSnapshot(docRef, callback),
+    onSnapshot: (optionsOrCallback: firestore.SnapshotListenOptions | ((doc: DocumentSnapshot) => void), callback: (doc: DocumentSnapshot) => void) => firebase.firestore.onDocumentSnapshot(docRef, optionsOrCallback, callback),
     android: docRef
   };
 }
@@ -2679,6 +2693,7 @@ export class QuerySnapshot implements firestore.QuerySnapshot {
 
   metadata = {
     fromCache: this.snapshot.getMetadata().isFromCache(),
+    hasPendingWrites: this.snapshot.getMetadata().hasPendingWrites()
   };
 
   get docs(): firestore.QueryDocumentSnapshot[] {

src/firebase.d.ts

@@ -679,6 +679,27 @@ export namespace firestore {
     merge?: boolean;
   }
 
+  export interface SnapshotMetadata {
+    /**
+     * True if the snapshot contains the result of local writes (e.g. set() or
+     * update() calls) that have not yet been committed to the backend.
+     * If your listener has opted into metadata updates (via
+     * `DocumentListenOptions` or `QueryListenOptions`) you will receive another
+     * snapshot with `hasPendingWrites` equal to false once the writes have been
+     * committed to the backend.
+     */
+    readonly hasPendingWrites: boolean;
+
+    /**
+     * True if the snapshot was created from cached data rather than
+     * guaranteed up-to-date server data. If your listener has opted into
+     * metadata updates (via `DocumentListenOptions` or `QueryListenOptions`)
+     * you will receive another snapshot with `fromCache` equal to false once
+     * the client has received up-to-date data from the backend.
+     */
+    readonly fromCache: boolean;
+  }
+
   export interface DocumentSnapshot {
     ios?: any;
     /* FIRDocumentSnapshot */
@@ -688,9 +709,22 @@ export namespace firestore {
     exists: boolean;
     ref: DocumentReference;
 
+    /**
+     * Included when includeMetadataChanges is true.
+     */
+    readonly metadata?: SnapshotMetadata;
+
     data(): DocumentData;
   }
 
+  export interface SnapshotListenOptions {
+    /**
+     * Include a change even if only the metadata of the query or of a document changed.
+     * Default false.
+     */
+    readonly includeMetadataChanges?: boolean;
+  }
+
   export interface DocumentReference {
     discriminator: "docRef";
     id: string;
@@ -701,7 +735,7 @@ export namespace firestore {
     update: (document: any) => Promise<void>;
     delete: () => Promise<void>;
 
-    onSnapshot(callback: (doc: DocumentSnapshot) => void): () => void;
+    onSnapshot(optionsOrCallback: SnapshotListenOptions | ((snapshot: DocumentSnapshot) => void), callback?: (snapshot: DocumentSnapshot) => void): () => void;
 
     android?: any;
     ios?: any;
@@ -716,7 +750,7 @@ export namespace firestore {
 
     limit(limit: number): Query;
 
-    onSnapshot(callback: (snapshot: QuerySnapshot) => void): () => void;
+    onSnapshot(optionsOrCallback: SnapshotListenOptions | ((snapshot: QuerySnapshot) => void), callback?: (snapshot: QuerySnapshot) => void): () => void;
 
     startAt(snapshot: DocumentSnapshot): Query;
 
@@ -855,6 +889,11 @@ export namespace firestore {
     docSnapshots: firestore.DocumentSnapshot[];
     docs: firestore.QueryDocumentSnapshot[];
 
+    /**
+     * Included when includeMetadataChanges is true.
+     */
+    readonly metadata: SnapshotMetadata;
+
     docChanges(options?: SnapshotListenOptions): DocumentChange[];
 
     forEach(callback: (result: DocumentSnapshot) => void, thisArg?: any): void;