Merge pull request #1154 from acrollet/master

Allow retrieving metadata with queries

Author: EddyVerbruggen

docs/FIRESTORE.md

@@ -64,6 +64,23 @@ 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:
+
+```typescript
+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);
+});
+
+// then after a while, to detach the listener:
+unsubscribe();
+```
+
 ### `collection.doc()`
 As mentioned, a document lives inside a collection and contains the actual data:
 

src/firebase.android.ts

@@ -2229,7 +2229,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: (callback: (snapshot: QuerySnapshot) => void) => firebase.firestore.onCollectionSnapshot(collectionRef, callback),
+      onSnapshot: (optionsOrCallback: any, 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),
@@ -2255,8 +2255,15 @@ firebase.firestore.onDocumentSnapshot = (docRef: com.google.firebase.firestore.D
   return () => listener.remove();
 };
 
-firebase.firestore.onCollectionSnapshot = (colRef: com.google.firebase.firestore.CollectionReference, callback: (snapshot: QuerySnapshot) => void): () => void => {
-  const listener = colRef.addSnapshotListener(new com.google.firebase.firestore.EventListener({
+firebase.firestore.onCollectionSnapshot = (colRef: com.google.firebase.firestore.CollectionReference, optionsOrCallback: any, callback: (snapshot: QuerySnapshot) => void): () => void => {
+  let options = com.google.firebase.firestore.MetadataChanges.EXCLUDE;
+  if ((typeof optionsOrCallback) === 'function') {
+    callback = optionsOrCallback;
+  } else if (optionsOrCallback.includeMetadataChanges) {
+    options = com.google.firebase.firestore.MetadataChanges.INCLUDE;
+  }
+
+  const listener = colRef.addSnapshotListener(options, new com.google.firebase.firestore.EventListener({
         onEvent: ((snapshot: com.google.firebase.firestore.QuerySnapshot, exception: com.google.firebase.firestore.FirebaseFirestoreException) => {
           if (exception !== null) {
             console.error('onCollectionSnapshot error code: ' + exception.getCode());
@@ -2558,7 +2565,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: (callback: (snapshot: QuerySnapshot) => void) => firebase.firestore.onCollectionSnapshot(query, callback),
+    onSnapshot: (optionsOrCallback: any, 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),
@@ -2670,6 +2677,10 @@ export class QuerySnapshot implements firestore.QuerySnapshot {
   constructor(private snapshot: com.google.firebase.firestore.QuerySnapshot) {
   }
 
+  metadata = {
+    fromCache: this.snapshot.getMetadata().isFromCache(),
+  };
+
   get docs(): firestore.QueryDocumentSnapshot[] {
     const getSnapshots = () => {
       const docSnapshots: firestore.QueryDocumentSnapshot[] = [];

src/firebase.ios.ts

@@ -1879,7 +1879,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, fIRCollectionReference),
       limit: (limit: number): firestore.Query => firebase.firestore.limit(collectionPath, limit, fIRCollectionReference),
-      onSnapshot: (callback: (snapshot: QuerySnapshot) => void) => firebase.firestore.onCollectionSnapshot(fIRCollectionReference, callback),
+      onSnapshot: (optionsOrCallback: any, callback?: (snapshot: QuerySnapshot) => void) => firebase.firestore.onCollectionSnapshot(fIRCollectionReference, optionsOrCallback, callback),
       startAfter: (document: DocumentSnapshot) => firebase.firestore.startAfter(collectionPath, document, fIRCollectionReference),
       startAt: (document: DocumentSnapshot) => firebase.firestore.startAt(collectionPath, document, fIRCollectionReference),
       endAt: (document: DocumentSnapshot) => firebase.firestore.endAt(collectionPath, document, fIRCollectionReference),
@@ -1911,8 +1911,14 @@ firebase.firestore.onDocumentSnapshot = (docRef: FIRDocumentReference, callback:
   }
 };
 
-firebase.firestore.onCollectionSnapshot = (colRef: FIRCollectionReference, callback: (snapshot: QuerySnapshot) => void): () => void => {
-  const listener = colRef.addSnapshotListener((snapshot: FIRQuerySnapshot, error: NSError) => {
+firebase.firestore.onCollectionSnapshot = (colRef: FIRCollectionReference, optionsOrCallback: any, callback: (snapshot: QuerySnapshot) => void): () => void => {
+  var includeMetadataChanges = false;
+  if ((typeof optionsOrCallback) === 'function') {
+    callback = optionsOrCallback;
+  } else if (optionsOrCallback.includeMetadataChanges === true) {
+    includeMetadataChanges = true;
+  }
+  const listener = colRef.addSnapshotListenerWithIncludeMetadataChangesListener(includeMetadataChanges, (snapshot: FIRQuerySnapshot, error: NSError) => {
     if (error || !snapshot) {
       return;
     }
@@ -2219,7 +2225,7 @@ firebase.firestore._getQuery = (collectionPath: string, query: FIRQuery): firest
     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: (callback: (snapshot: QuerySnapshot) => void) => firebase.firestore.onCollectionSnapshot(query, callback),
+    onSnapshot: (optionsOrCallback: any, callback?: (snapshot: QuerySnapshot) => void) => firebase.firestore.onCollectionSnapshot(query, optionsOrCallback, callback),
     startAfter: (document: DocumentSnapshot) => firebase.firestore.startAfter(collectionPath, document, query),
     startAt: (document: DocumentSnapshot) => firebase.firestore.startAt(collectionPath, document, query),
     endAt: (document: DocumentSnapshot) => firebase.firestore.endAt(collectionPath, document, query),
@@ -2372,6 +2378,8 @@ export class QuerySnapshot implements firestore.QuerySnapshot {
   constructor(private snapshot: FIRQuerySnapshot) {
   }
 
+  metadata = this.snapshot.metadata;
+
   get docs(): firestore.QueryDocumentSnapshot[] {
     const getSnapshots = () => {
       const docSnapshots: firestore.QueryDocumentSnapshot[] = [];