Expose clearPersistence() publicly (#1717)

Addresses (#449).

Author: Brian Chen

packages/firebase/index.d.ts

@@ -6086,7 +6086,8 @@ declare namespace firebase.firestore {
     /**
      * Attempts to enable persistent storage, if possible.
      *
-     * Must be called before any other methods (other than settings()).
+     * Must be called before any other methods (other than settings() and
+     * clearPersistence()).
      *
      * If this fails, enablePersistence() will reject the promise it returns.
      * Note that even after this failure, the firestore instance will remain
@@ -6178,6 +6179,28 @@ declare namespace firebase.firestore {
      */
     app: firebase.app.App;
 
+    /**
+     * Clears the persistent storage. This includes pending writes and cached
+     * documents.
+     *
+     * Must be called while the firestore instance is not started (after the app is
+     * shutdown or when the app is first initialized). On startup, this method
+     * must be called before other methods (other than settings()). If the
+     * firestore instance is still running, the promise will be rejected with
+     * the error code of `failed-precondition`.
+     *
+     * Note: clearPersistence() is primarily intended to help write reliable
+     * tests that use Firestore. It uses the most efficient mechanism possible
+     * for dropping existing data but does not attempt to securely overwrite or
+     * otherwise make cached data unrecoverable. For applications that are
+     * sensitive to the disclosure of cache data in between user sessions we
+     * strongly recommend not to enable persistence in the first place.
+     *
+     * @return A promise that is resolved once the persistent storage has been
+     * cleared. Otherwise, the promise is rejected with an error.
+     */
+    clearPersistence(): Promise<void>;
+
     /**
      * Re-enables use of the network for this Firestore instance after a prior
      * call to {@link firebase.firestore.Firestore.disableNetwork

packages/firestore-types/index.d.ts

@@ -145,7 +145,8 @@ export class FirebaseFirestore {
   /**
    * Attempts to enable persistent storage, if possible.
    *
-   * Must be called before any other methods (other than settings()).
+   * Must be called before any other methods (other than settings() and
+   * clearPersistence()).
    *
    * If this fails, enablePersistence() will reject the promise it returns.
    * Note that even after this failure, the firestore instance will remain
@@ -235,6 +236,28 @@ export class FirebaseFirestore {
    */
   app: any;
 
+  /**
+   * Clears the persistent storage. This includes pending writes and cached
+   * documents.
+   *
+   * Must be called while the firestore instance is not started (after the app is
+   * shutdown or when the app is first initialized). On startup, this method
+   * must be called before other methods (other than settings()). If the
+   * firestore instance is still running, the promise will be rejected with
+   * the error code of `failed-precondition`.
+   *
+   * Note: clearPersistence() is primarily intended to help write reliable
+   * tests that use Firestore. It uses the most efficient mechanism possible
+   * for dropping existing data but does not attempt to securely overwrite or
+   * otherwise make cached data unrecoverable. For applications that are
+   * sensitive to the disclosure of cache data in between user sessions we
+   * strongly recommend not to enable persistence in the first place.
+   *
+   * @return A promise that is resolved once the persistent storage has been
+   * cleared. Otherwise, the promise is rejected with an error.
+   */
+  clearPersistence(): Promise<void>;
+
   /**
    * Re-enables use of the network for this Firestore instance after a prior
    * call to disableNetwork().

packages/firestore/CHANGELOG.md

@@ -1,5 +1,10 @@
 
 # Unreleased
+- [feature] Added `clearPersistence()`, which clears the persistent storage
+  including pending writes and cached documents. This is intended to help
+  write reliable tests (#449). 
+
+# 1.3.3
 - [changed] Firestore now recovers more quickly after network connectivity
   changes (airplane mode, Wi-Fi availability, etc.).
 

packages/firestore/src/api/database.ts

@@ -424,7 +424,7 @@ export class Firestore implements firestore.FirebaseFirestore, FirebaseService {
     );
   }
 
-  _clearPersistence(): Promise<void> {
+  clearPersistence(): Promise<void> {
     const persistenceKey = IndexedDbPersistence.buildStoragePrefix(
       this.makeDatabaseInfo()
     );
@@ -437,7 +437,7 @@ export class Firestore implements firestore.FirebaseFirestore, FirebaseService {
         ) {
           throw new FirestoreError(
             Code.FAILED_PRECONDITION,
-            'Persistence cannot be cleared while this firestore instance is running.'
+            'Persistence cannot be cleared after this Firestore instance is initialized.'
           );
         }
         await IndexedDbPersistence.clearPersistence(persistenceKey);

packages/firestore/test/integration/api/database.test.ts

@@ -30,7 +30,6 @@ import { EventsAccumulator } from '../util/events_accumulator';
 import firebase from '../util/firebase_export';
 import {
   apiDescribe,
-  clearPersistence,
   withTestCollection,
   withTestDb,
   withTestDbs,
@@ -954,13 +953,14 @@ apiDescribe('Database', persistence => {
     'can clear persistence if the client has not been initialized',
     async () => {
       await withTestDoc(persistence, async docRef => {
+        const firestore = docRef.firestore;
         await docRef.set({ foo: 'bar' });
         const app = docRef.firestore.app;
         const name = app.name;
         const options = app.options;
 
         await app.delete();
-        await clearPersistence(docRef.firestore);
+        await firestore.clearPersistence();
         const app2 = firebase.initializeApp(options, name);
         const firestore2 = firebase.firestore!(app2);
         await firestore2.enablePersistence();
@@ -984,7 +984,7 @@ apiDescribe('Database', persistence => {
           const firestore = docRef.firestore;
           await firestore.app.delete();
           await expect(
-            clearPersistence(firestore)
+            firestore.clearPersistence()
           ).to.eventually.be.rejectedWith('Failed to delete the database.');
         } finally {
           SimpleDb.delete = oldDelete;
@@ -996,8 +996,8 @@ apiDescribe('Database', persistence => {
   it('can not clear persistence if the client has been initialized', async () => {
     await withTestDoc(persistence, async docRef => {
       const firestore = docRef.firestore;
-      await expect(clearPersistence(firestore)).to.eventually.be.rejectedWith(
-        'Persistence cannot be cleared while this firestore instance is running.'
+      await expect(firestore.clearPersistence()).to.eventually.be.rejectedWith(
+        'Persistence cannot be cleared after this Firestore instance is initialized.'
       );
     });
   });

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

@@ -106,14 +106,6 @@ function apiDescribeInternal(
   }
 }
 
-// TODO(b/131094514): Remove after clearPersistence() is updated in index.d.ts.
-export async function clearPersistence(
-  firestore: firestore.FirebaseFirestore
-): Promise<void> {
-  // tslint:disable-next-line:no-any
-  await (firestore as any)._clearPersistence();
-}
-
 /** Converts the documents in a QuerySnapshot to an array with the data of each document. */
 export function toDataArray(
   docSet: firestore.QuerySnapshot