review feedback

Author: rsgowman

packages/firebase/index.d.ts

@@ -1112,6 +1112,37 @@ declare namespace firebase.firestore {
     readonly merge?: boolean;
   }
 
+  /**
+   * An options object that configures the behavior of `get()` calls on
+   * `DocumentReference` and `Query`. By providing a `GetOptions` object, these
+   * methods can be configured to fetch results only from the server, only from
+   * the local cache or attempt to fetch results from the server and fall back to
+   * the cache (which is the default).
+   */
+  export interface GetOptions {
+    /**
+     * Describes whether we should get from server or cache.
+     *
+     * Setting to 'default' (or not setting at all), causes Firestore to try to
+     * retrieve an up-to-date (server-retrieved) snapshot, but fall back to
+     * returning cached data if the server can't be reached.
+     *
+     * Setting to 'server' causes Firestore to avoid the cache, generating an
+     * error if the server cannot be reached. Note that the cache will still be
+     * updated if the server request succeeds. Also note that latency-compensation
+     * still takes effect, so any pending write operations will be visible in the
+     * returned data (merged into the server-provided data).
+     *
+     * Setting to 'cache' causes Firestore to immediately return a value from the
+     * cache, ignoring the server completely (implying that the returned value
+     * may be stale with respect to the value on the server.) If there is no data
+     * in the cache to satisfy the `get()` call, `DocumentReference.get()` will
+     * return an error and `QuerySnapshot.get()` will return an empty
+     * `QuerySnapshot` with no documents.
+     */
+    readonly source?: 'default' | 'server' | 'cache';
+  }
+
   /**
    * A `DocumentReference` refers to a document location in a Firestore database
    * and can be used to write, read, or listen to the location. The document at
@@ -1213,14 +1244,16 @@ declare namespace firebase.firestore {
     /**
      * Reads the document referred to by this `DocumentReference`.
      *
-     * Note: get() attempts to provide up-to-date data when possible by waiting
-     * for data from the server, but it may return cached data or fail if you
-     * are offline and the server cannot be reached.
+     * Note: By default, get() attempts to provide up-to-date data when possible
+     * by waiting for data from the server, but it may return cached data or fail
+     * if you are offline and the server cannot be reached. This behavior can be
+     * altered via the `GetOptions` parameter.
      *
+     * @param options An object to configure the get behavior.
      * @return A Promise resolved with a DocumentSnapshot containing the
      * current document contents.
      */
-    get(): Promise<DocumentSnapshot>;
+    get(options?: GetOptions): Promise<DocumentSnapshot>;
 
     /**
      * Attaches a listener for DocumentSnapshot events. You may either pass
@@ -1598,9 +1631,15 @@ declare namespace firebase.firestore {
     /**
      * Executes the query and returns the results as a QuerySnapshot.
      *
+     * Note: By default, get() attempts to provide up-to-date data when possible
+     * by waiting for data from the server, but it may return cached data or fail
+     * if you are offline and the server cannot be reached. This behavior can be
+     * altered via the `GetOptions` parameter.
+     *
+     * @param options An object to configure the get behavior.
      * @return A Promise that will be resolved with the results of the Query.
      */
-    get(): Promise<QuerySnapshot>;
+    get(options?: GetOptions): Promise<QuerySnapshot>;
 
     /**
      * Attaches a listener for QuerySnapshot events. You may either pass

packages/firestore/src/api/database.ts

@@ -1028,13 +1028,13 @@ export class DocumentReference implements firestore.DocumentReference {
               );
             }, reject);
         } else {
-          this.getViaSnapshotListener_(resolve, reject, options);
+          this.getViaSnapshotListener(resolve, reject, options);
         }
       }
     );
   }
 
-  private getViaSnapshotListener_(
+  private getViaSnapshotListener(
     resolve: Resolver<firestore.DocumentSnapshot>,
     reject: Rejecter,
     options?: firestore.GetOptions
@@ -1061,7 +1061,7 @@ export class DocumentReference implements firestore.DocumentReference {
             // if the document doesn't exist.
             reject(
               new FirestoreError(
-                Code.ABORTED,
+                Code.UNAVAILABLE,
                 'Failed to get document because the client is ' + 'offline.'
               )
             );
@@ -1076,7 +1076,7 @@ export class DocumentReference implements firestore.DocumentReference {
                 Code.UNAVAILABLE,
                 'Failed to get document from server. (However, this ' +
                   'document does exist in the local cache. Run again ' +
-                  'without setting source to FIRGetSourceServer to ' +
+                  'without setting source to "server" to ' +
                   'retrieve the cached document.)'
               )
             );
@@ -1679,13 +1679,13 @@ export class Query implements firestore.Query {
               resolve(new QuerySnapshot(this.firestore, this._query, viewSnap));
             }, reject);
         } else {
-          this.getViaSnapshotListener_(resolve, reject, options);
+          this.getViaSnapshotListener(resolve, reject, options);
         }
       }
     );
   }
 
-  private getViaSnapshotListener_(
+  private getViaSnapshotListener(
     resolve: Resolver<firestore.QuerySnapshot>,
     reject: Rejecter,
     options?: firestore.GetOptions

packages/firestore/src/core/firestore_client.ts

@@ -49,7 +49,7 @@ import { debug } from '../util/log';
 import { Deferred } from '../util/promise';
 
 import { DatabaseId, DatabaseInfo } from './database_info';
-import { Query as InternalQuery } from './query';
+import { Query } from './query';
 import { Transaction } from './transaction';
 import { OnlineState } from './types';
 import { ViewSnapshot } from './view_snapshot';
@@ -348,7 +348,7 @@ export class FirestoreClient {
   }
 
   listen(
-    query: InternalQuery,
+    query: Query,
     observer: Observer<ViewSnapshot>,
     options: ListenOptions
   ): QueryListener {
@@ -385,7 +385,7 @@ export class FirestoreClient {
       });
   }
 
-  getDocumentsFromLocalCache(query: InternalQuery): Promise<ViewSnapshot> {
+  getDocumentsFromLocalCache(query: Query): Promise<ViewSnapshot> {
     return this.asyncQueue
       .enqueue(() => {
         return this.localStore.executeQuery(query);

packages/firestore/test/integration/util/helpers.ts

@@ -90,7 +90,7 @@ export function toDataArray(
 export function toDataMap(
   docSet: firestore.QuerySnapshot
 ): { [field: string]: firestore.DocumentData } {
-  let docsData = {};
+  const docsData = {};
   docSet.forEach(doc => {
     docsData[doc.id] = doc.data();
   });