GetOptions for controlling offline behaviour (#463)

Add option to allow the user to control where DocumentReference.get()
and Query.get() fetches from. By default, it fetches from the server (if
possible) and falls back to the local cache.  It's now possible to
alternatively fetch from the local cache only, or to fetch from the
server only (though in the server only case, latency compensation is
still enabled).

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-types/index.d.ts

@@ -494,6 +494,37 @@ export interface SetOptions {
   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
@@ -595,14 +626,16 @@ export class DocumentReference {
   /**
    * 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
@@ -976,9 +1009,15 @@ export class Query {
   /**
    * 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/CHANGELOG.md

@@ -10,6 +10,10 @@
   `FirestoreSettings` to `true`. Note that the current behavior
   (`DocumentSnapshot`s returning JS Date objects) will be removed in a future
   release. `Timestamp` supports higher precision than JS Date.
+- [feature] Added ability to control whether DocumentReference.get() and
+  Query.get() should fetch from server only, (by passing { source: 'server' }),
+  cache only (by passing { source: 'cache' }), or attempt server and fall back
+  to the cache (which was the only option previously, and is now the default).
 
 # 0.3.6
 - [fixed] Fixed a regression in the Firebase JS release 4.11.0 that could

packages/firestore/src/api/database.ts

@@ -1000,43 +1000,91 @@ export class DocumentReference implements firestore.DocumentReference {
     };
   }
 
-  get(): Promise<firestore.DocumentSnapshot> {
-    validateExactNumberOfArgs('DocumentReference.get', arguments, 0);
+  get(options?: firestore.GetOptions): Promise<firestore.DocumentSnapshot> {
+    validateOptionNames('DocumentReference.get', options, ['source']);
+    if (options) {
+      validateNamedOptionalPropertyEquals(
+        'DocumentReference.get',
+        'options',
+        'source',
+        options.source,
+        ['default', 'server', 'cache']
+      );
+    }
     return new Promise(
       (resolve: Resolver<firestore.DocumentSnapshot>, reject: Rejecter) => {
-        const unlisten = this.onSnapshotInternal(
-          {
-            includeQueryMetadataChanges: true,
-            includeDocumentMetadataChanges: true,
-            waitForSyncWhenOnline: true
-          },
-          {
-            next: (snap: firestore.DocumentSnapshot) => {
-              // Remove query first before passing event to user to avoid
-              // user actions affecting the now stale query.
-              unlisten();
-
-              if (!snap.exists && snap.metadata.fromCache) {
-                // TODO(dimond): If we're online and the document doesn't
-                // exist then we resolve with a doc.exists set to false. If
-                // we're offline however, we reject the Promise in this
-                // case. Two options: 1) Cache the negative response from
-                // the server so we can deliver that even when you're
-                // offline 2) Actually reject the Promise in the online case
-                // if the document doesn't exist.
-                reject(
-                  new FirestoreError(
-                    Code.ABORTED,
-                    'Failed to get document because the client is ' + 'offline.'
-                  )
-                );
-              } else {
-                resolve(snap);
-              }
-            },
-            error: reject
+        if (options && options.source === 'cache') {
+          this.firestore
+            .ensureClientConfigured()
+            .getDocumentFromLocalCache(this._key)
+            .then((doc: Document) => {
+              resolve(
+                new DocumentSnapshot(
+                  this.firestore,
+                  this._key,
+                  doc,
+                  /*fromCache=*/ true
+                )
+              );
+            }, reject);
+        } else {
+          this.getViaSnapshotListener(resolve, reject, options);
+        }
+      }
+    );
+  }
+
+  private getViaSnapshotListener(
+    resolve: Resolver<firestore.DocumentSnapshot>,
+    reject: Rejecter,
+    options?: firestore.GetOptions
+  ): void {
+    const unlisten = this.onSnapshotInternal(
+      {
+        includeQueryMetadataChanges: true,
+        includeDocumentMetadataChanges: true,
+        waitForSyncWhenOnline: true
+      },
+      {
+        next: (snap: firestore.DocumentSnapshot) => {
+          // Remove query first before passing event to user to avoid
+          // user actions affecting the now stale query.
+          unlisten();
+
+          if (!snap.exists && snap.metadata.fromCache) {
+            // TODO(dimond): If we're online and the document doesn't
+            // exist then we resolve with a doc.exists set to false. If
+            // we're offline however, we reject the Promise in this
+            // case. Two options: 1) Cache the negative response from
+            // the server so we can deliver that even when you're
+            // offline 2) Actually reject the Promise in the online case
+            // if the document doesn't exist.
+            reject(
+              new FirestoreError(
+                Code.UNAVAILABLE,
+                'Failed to get document because the client is ' + 'offline.'
+              )
+            );
+          } else if (
+            snap.exists &&
+            snap.metadata.fromCache &&
+            options &&
+            options.source === 'server'
+          ) {
+            reject(
+              new FirestoreError(
+                Code.UNAVAILABLE,
+                'Failed to get document from server. (However, this ' +
+                  'document does exist in the local cache. Run again ' +
+                  'without setting source to "server" to ' +
+                  'retrieve the cached document.)'
+              )
+            );
+          } else {
+            resolve(snap);
           }
-        );
+        },
+        error: reject
       }
     );
   }
@@ -1619,27 +1667,60 @@ export class Query implements firestore.Query {
     };
   }
 
-  get(): Promise<firestore.QuerySnapshot> {
-    validateExactNumberOfArgs('Query.get', arguments, 0);
+  get(options?: firestore.GetOptions): Promise<firestore.QuerySnapshot> {
+    validateBetweenNumberOfArgs('Query.get', arguments, 0, 1);
     return new Promise(
       (resolve: Resolver<firestore.QuerySnapshot>, reject: Rejecter) => {
-        const unlisten = this.onSnapshotInternal(
-          {
-            includeDocumentMetadataChanges: false,
-            includeQueryMetadataChanges: true,
-            waitForSyncWhenOnline: true
-          },
-          {
-            next: (result: firestore.QuerySnapshot) => {
-              // Remove query first before passing event to user to avoid
-              // user actions affecting the now stale query.
-              unlisten();
-
-              resolve(result);
-            },
-            error: reject
+        if (options && options.source === 'cache') {
+          this.firestore
+            .ensureClientConfigured()
+            .getDocumentsFromLocalCache(this._query)
+            .then((viewSnap: ViewSnapshot) => {
+              resolve(new QuerySnapshot(this.firestore, this._query, viewSnap));
+            }, reject);
+        } else {
+          this.getViaSnapshotListener(resolve, reject, options);
+        }
+      }
+    );
+  }
+
+  private getViaSnapshotListener(
+    resolve: Resolver<firestore.QuerySnapshot>,
+    reject: Rejecter,
+    options?: firestore.GetOptions
+  ): void {
+    const unlisten = this.onSnapshotInternal(
+      {
+        includeDocumentMetadataChanges: false,
+        includeQueryMetadataChanges: true,
+        waitForSyncWhenOnline: true
+      },
+      {
+        next: (result: firestore.QuerySnapshot) => {
+          // Remove query first before passing event to user to avoid
+          // user actions affecting the now stale query.
+          unlisten();
+
+          if (
+            result.metadata.fromCache &&
+            options &&
+            options.source === 'server'
+          ) {
+            reject(
+              new FirestoreError(
+                Code.UNAVAILABLE,
+                'Failed to get documents from server. (However, these ' +
+                  'documents may exist in the local cache. Run again ' +
+                  'without setting source to "server" to ' +
+                  'retrieve the cached documents.)'
+              )
+            );
+          } else {
+            resolve(result);
           }
-        );
+        },
+        error: reject
       }
     );
   }