From acd7b24b87deff9b3fde11348ecd307478aab19d Mon Sep 17 00:00:00 2001 From: Brian Chen Date: Mon, 22 Apr 2019 11:00:36 -0700 Subject: [PATCH 01/13] adding index --- packages/firebase/index.d.ts | 7 +++++++ packages/firestore-types/index.d.ts | 7 +++++++ 2 files changed, 14 insertions(+) diff --git a/packages/firebase/index.d.ts b/packages/firebase/index.d.ts index f5057a27daa..4d4a5a115dd 100644 --- a/packages/firebase/index.d.ts +++ b/packages/firebase/index.d.ts @@ -6060,6 +6060,13 @@ declare namespace firebase.firestore { */ app: firebase.app.App; + /** + * Clears the persistence cache. This can only be called when the client is not running. + * + * @return A promise that is resolved once the persistence has been cleared. + */ + clearPersistence(): Promise; + /** * Re-enables use of the network for this Firestore instance after a prior * call to {@link firebase.firestore.Firestore.disableNetwork diff --git a/packages/firestore-types/index.d.ts b/packages/firestore-types/index.d.ts index d5a1c4e714c..f2a4c3d45fe 100644 --- a/packages/firestore-types/index.d.ts +++ b/packages/firestore-types/index.d.ts @@ -216,6 +216,13 @@ export class FirebaseFirestore { */ app: any; + /** + * Clears the persistence cache. This can only be called when the client is not running. + * + * @return A promise that is resolved once the persistence has been cleared. + */ + clearPersistence(): Promise; + /** * Re-enables use of the network for this Firestore instance after a prior * call to disableNetwork(). From 1f52e4d7759a23541391923d9430f5524edcef52 Mon Sep 17 00:00:00 2001 From: Brian Chen Date: Mon, 22 Apr 2019 15:33:40 -0700 Subject: [PATCH 02/13] comment changes --- packages/firestore-types/index.d.ts | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/packages/firestore-types/index.d.ts b/packages/firestore-types/index.d.ts index f2a4c3d45fe..d05c10a234f 100644 --- a/packages/firestore-types/index.d.ts +++ b/packages/firestore-types/index.d.ts @@ -136,7 +136,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 @@ -217,7 +218,12 @@ export class FirebaseFirestore { app: any; /** - * Clears the persistence cache. This can only be called when the client is not running. + * Clears the persistent storage. + * + * Must be called after the app is shutdown or before other methods (other + * than settings()). If the client is still running, an exception `code` will be thrown. + * + * * failed-precondition: The app is still running in a browser tab. * * @return A promise that is resolved once the persistence has been cleared. */ From 870d4acc47612ec32d22cd653d6ae6bcc64b3f1a Mon Sep 17 00:00:00 2001 From: Brian Chen Date: Mon, 22 Apr 2019 15:33:45 -0700 Subject: [PATCH 03/13] [AUTOMATED]: Prettier Code Styling --- packages/firestore-types/index.d.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/firestore-types/index.d.ts b/packages/firestore-types/index.d.ts index d05c10a234f..8a887f50e9f 100644 --- a/packages/firestore-types/index.d.ts +++ b/packages/firestore-types/index.d.ts @@ -220,7 +220,7 @@ export class FirebaseFirestore { /** * Clears the persistent storage. * - * Must be called after the app is shutdown or before other methods (other + * Must be called after the app is shutdown or before other methods (other * than settings()). If the client is still running, an exception `code` will be thrown. * * * failed-precondition: The app is still running in a browser tab. From 71ce1f491409fd6885de4e824b05a23376efa757 Mon Sep 17 00:00:00 2001 From: Brian Chen Date: Mon, 22 Apr 2019 15:43:28 -0700 Subject: [PATCH 04/13] update comments --- packages/firebase/index.d.ts | 11 +++++++++-- packages/firestore-types/index.d.ts | 3 ++- 2 files changed, 11 insertions(+), 3 deletions(-) diff --git a/packages/firebase/index.d.ts b/packages/firebase/index.d.ts index 4d4a5a115dd..7e9e0385b03 100644 --- a/packages/firebase/index.d.ts +++ b/packages/firebase/index.d.ts @@ -5988,7 +5988,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 @@ -6061,7 +6062,13 @@ declare namespace firebase.firestore { app: firebase.app.App; /** - * Clears the persistence cache. This can only be called when the client is not running. + * Clears the persistent storage. + * + * Must be called after the app is shutdown or before other methods (other + * than settings()) on startup. If the client is still running, an exception + * `code` will be thrown. + * + * * failed-precondition: The app is still running in a browser tab. * * @return A promise that is resolved once the persistence has been cleared. */ diff --git a/packages/firestore-types/index.d.ts b/packages/firestore-types/index.d.ts index 8a887f50e9f..385dcf454ac 100644 --- a/packages/firestore-types/index.d.ts +++ b/packages/firestore-types/index.d.ts @@ -221,7 +221,8 @@ export class FirebaseFirestore { * Clears the persistent storage. * * Must be called after the app is shutdown or before other methods (other - * than settings()). If the client is still running, an exception `code` will be thrown. + * than settings()) on startup. If the client is still running, an exception + * `code` will be thrown. * * * failed-precondition: The app is still running in a browser tab. * From 3497258a8c2bfc14a8f28ebe02eacc52684abe20 Mon Sep 17 00:00:00 2001 From: Brian Chen Date: Mon, 22 Apr 2019 15:57:13 -0700 Subject: [PATCH 05/13] update part 2 --- packages/firebase/index.d.ts | 5 +++-- packages/firestore-types/index.d.ts | 5 +++-- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/packages/firebase/index.d.ts b/packages/firebase/index.d.ts index 7e9e0385b03..541f72cc62e 100644 --- a/packages/firebase/index.d.ts +++ b/packages/firebase/index.d.ts @@ -6068,9 +6068,10 @@ declare namespace firebase.firestore { * than settings()) on startup. If the client is still running, an exception * `code` will be thrown. * - * * failed-precondition: The app is still running in a browser tab. + * * failed-precondition: The client is still running in a browser tab. * - * @return A promise that is resolved once the persistence has been cleared. + * @return A promise that is resolved once the persistent storage has been + * cleared. */ clearPersistence(): Promise; diff --git a/packages/firestore-types/index.d.ts b/packages/firestore-types/index.d.ts index 385dcf454ac..e2830cfb178 100644 --- a/packages/firestore-types/index.d.ts +++ b/packages/firestore-types/index.d.ts @@ -224,9 +224,10 @@ export class FirebaseFirestore { * than settings()) on startup. If the client is still running, an exception * `code` will be thrown. * - * * failed-precondition: The app is still running in a browser tab. + * * failed-precondition: The client is still running in a browser tab. * - * @return A promise that is resolved once the persistence has been cleared. + * @return A promise that is resolved once the persistent storage has been + * cleared. */ clearPersistence(): Promise; From 10857ff64a9eb2662214680ab32bb036127d0523 Mon Sep 17 00:00:00 2001 From: Brian Chen Date: Tue, 23 Apr 2019 10:03:05 -0700 Subject: [PATCH 06/13] calling public API --- packages/firestore/src/api/database.ts | 2 +- packages/firestore/test/integration/api/database.test.ts | 6 +++--- packages/firestore/test/integration/util/helpers.ts | 8 -------- 3 files changed, 4 insertions(+), 12 deletions(-) diff --git a/packages/firestore/src/api/database.ts b/packages/firestore/src/api/database.ts index 23dc8401ab8..e7968f83cf4 100644 --- a/packages/firestore/src/api/database.ts +++ b/packages/firestore/src/api/database.ts @@ -410,7 +410,7 @@ export class Firestore implements firestore.FirebaseFirestore, FirebaseService { ); } - _clearPersistence(): Promise { + clearPersistence(): Promise { if (this.clientRunning) { throw new FirestoreError( Code.FAILED_PRECONDITION, diff --git a/packages/firestore/test/integration/api/database.test.ts b/packages/firestore/test/integration/api/database.test.ts index bc98e7b2ef5..825ddf0ba01 100644 --- a/packages/firestore/test/integration/api/database.test.ts +++ b/packages/firestore/test/integration/api/database.test.ts @@ -29,7 +29,6 @@ import { EventsAccumulator } from '../util/events_accumulator'; import firebase from '../util/firebase_export'; import { apiDescribe, - clearPersistence, withTestCollection, withTestDb, withTestDbs, @@ -953,13 +952,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(); @@ -974,7 +974,7 @@ 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( + await expect(firestore.clearPersistence()).to.eventually.be.rejectedWith( 'Persistence cannot be cleared while the client is running' ); }); diff --git a/packages/firestore/test/integration/util/helpers.ts b/packages/firestore/test/integration/util/helpers.ts index f2f887fa218..8f2bb3d6f64 100644 --- a/packages/firestore/test/integration/util/helpers.ts +++ b/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 { - // 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 From c00cb81e947babff1a7dad0580570e31afe48043 Mon Sep 17 00:00:00 2001 From: Brian Chen Date: Tue, 23 Apr 2019 10:46:58 -0700 Subject: [PATCH 07/13] fix test to pass --- packages/firestore/test/integration/api/database.test.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/firestore/test/integration/api/database.test.ts b/packages/firestore/test/integration/api/database.test.ts index 825ddf0ba01..1a9ffbce31d 100644 --- a/packages/firestore/test/integration/api/database.test.ts +++ b/packages/firestore/test/integration/api/database.test.ts @@ -974,7 +974,7 @@ 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(firestore.clearPersistence()).to.eventually.be.rejectedWith( + await expect(() => firestore.clearPersistence()).to.throw( 'Persistence cannot be cleared while the client is running' ); }); From f24f33f610e030c3df5417610a0ca911f4175433 Mon Sep 17 00:00:00 2001 From: Brian Chen Date: Tue, 23 Apr 2019 15:32:46 -0700 Subject: [PATCH 08/13] resolve gil's comments --- packages/firebase/index.d.ts | 12 ++++++------ packages/firestore-types/index.d.ts | 12 ++++++------ 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/packages/firebase/index.d.ts b/packages/firebase/index.d.ts index 541f72cc62e..661da677c5a 100644 --- a/packages/firebase/index.d.ts +++ b/packages/firebase/index.d.ts @@ -6064,14 +6064,14 @@ declare namespace firebase.firestore { /** * Clears the persistent storage. * - * Must be called after the app is shutdown or before other methods (other - * than settings()) on startup. If the client is still running, an exception - * `code` will be thrown. - * - * * failed-precondition: The client is still running in a browser tab. + * Must be called while the client is not started (after the app is shutdown + * or when the app is first initialized). On startup, this method must called + * before other methods (other than settings()). If the client is still + * running, an exception with the a code of `failed-precondition` will be + * thrown. * * @return A promise that is resolved once the persistent storage has been - * cleared. + * cleared. Otherwise, the promise is rejected with an error. */ clearPersistence(): Promise; diff --git a/packages/firestore-types/index.d.ts b/packages/firestore-types/index.d.ts index e2830cfb178..edd6db0e134 100644 --- a/packages/firestore-types/index.d.ts +++ b/packages/firestore-types/index.d.ts @@ -220,14 +220,14 @@ export class FirebaseFirestore { /** * Clears the persistent storage. * - * Must be called after the app is shutdown or before other methods (other - * than settings()) on startup. If the client is still running, an exception - * `code` will be thrown. - * - * * failed-precondition: The client is still running in a browser tab. + * Must be called while the client is not started (after the app is shutdown + * or when the app is first initialized). On startup, this method must called + * before other methods (other than settings()). If the client is still + * running, an exception with the a code of `failed-precondition` will be + * thrown. * * @return A promise that is resolved once the persistent storage has been - * cleared. + * cleared. Otherwise, the promise rejects with an error. */ clearPersistence(): Promise; From 5615d32dd719c5485c9716323a5ef463369aa75c Mon Sep 17 00:00:00 2001 From: Brian Chen Date: Mon, 29 Apr 2019 15:24:43 -0700 Subject: [PATCH 09/13] fix typos + formatting --- packages/firebase/index.d.ts | 10 +++++----- packages/firestore-types/index.d.ts | 22 +++++++++++----------- 2 files changed, 16 insertions(+), 16 deletions(-) diff --git a/packages/firebase/index.d.ts b/packages/firebase/index.d.ts index 661da677c5a..931e35be45b 100644 --- a/packages/firebase/index.d.ts +++ b/packages/firebase/index.d.ts @@ -6064,11 +6064,11 @@ declare namespace firebase.firestore { /** * Clears the persistent storage. * - * Must be called while the client is not started (after the app is shutdown - * or when the app is first initialized). On startup, this method must called - * before other methods (other than settings()). If the client is still - * running, an exception with the a code of `failed-precondition` will be - * thrown. + * Must be called while the client 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 + * client is still running, an exception with a code of `failed-precondition` + * will be thrown. * * @return A promise that is resolved once the persistent storage has been * cleared. Otherwise, the promise is rejected with an error. diff --git a/packages/firestore-types/index.d.ts b/packages/firestore-types/index.d.ts index edd6db0e134..b73030604dd 100644 --- a/packages/firestore-types/index.d.ts +++ b/packages/firestore-types/index.d.ts @@ -218,17 +218,17 @@ export class FirebaseFirestore { app: any; /** - * Clears the persistent storage. - * - * Must be called while the client is not started (after the app is shutdown - * or when the app is first initialized). On startup, this method must called - * before other methods (other than settings()). If the client is still - * running, an exception with the a code of `failed-precondition` will be - * thrown. - * - * @return A promise that is resolved once the persistent storage has been - * cleared. Otherwise, the promise rejects with an error. - */ + * Clears the persistent storage. + * + * Must be called while the client 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 + * client is still running, an exception with a code of `failed-precondition` + * will be thrown. + * + * @return A promise that is resolved once the persistent storage has been + * cleared. Otherwise, the promise is rejected with an error. + */ clearPersistence(): Promise; /** From 00351a90619ef5b8a34527f8a88b9fd3e39b1443 Mon Sep 17 00:00:00 2001 From: Brian Chen Date: Mon, 29 Apr 2019 15:24:51 -0700 Subject: [PATCH 10/13] [AUTOMATED]: Prettier Code Styling --- packages/firestore-types/index.d.ts | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/packages/firestore-types/index.d.ts b/packages/firestore-types/index.d.ts index b73030604dd..b9c093aeec8 100644 --- a/packages/firestore-types/index.d.ts +++ b/packages/firestore-types/index.d.ts @@ -218,17 +218,17 @@ export class FirebaseFirestore { app: any; /** - * Clears the persistent storage. - * - * Must be called while the client 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 - * client is still running, an exception with a code of `failed-precondition` - * will be thrown. - * - * @return A promise that is resolved once the persistent storage has been - * cleared. Otherwise, the promise is rejected with an error. - */ + * Clears the persistent storage. + * + * Must be called while the client 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 + * client is still running, an exception with a code of `failed-precondition` + * will be thrown. + * + * @return A promise that is resolved once the persistent storage has been + * cleared. Otherwise, the promise is rejected with an error. + */ clearPersistence(): Promise; /** From b8bb8f146e3b09e068f55651f7e39e51f3bb279a Mon Sep 17 00:00:00 2001 From: Brian Chen Date: Tue, 4 Jun 2019 17:35:20 -0700 Subject: [PATCH 11/13] update method comment to api proposal one --- packages/firebase/index.d.ts | 16 ++++++++++++---- packages/firestore-types/index.d.ts | 16 ++++++++++++---- 2 files changed, 24 insertions(+), 8 deletions(-) diff --git a/packages/firebase/index.d.ts b/packages/firebase/index.d.ts index 8b1623adc7c..d109ef4318e 100644 --- a/packages/firebase/index.d.ts +++ b/packages/firebase/index.d.ts @@ -6180,13 +6180,21 @@ declare namespace firebase.firestore { app: firebase.app.App; /** - * Clears the persistent storage. + * Clears the persistent storage. This includes pending writes and cached + * documents. * - * Must be called while the client is not started (after the app is + * 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 - * client is still running, an exception with a code of `failed-precondition` - * will be thrown. + * 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. diff --git a/packages/firestore-types/index.d.ts b/packages/firestore-types/index.d.ts index 1114bc8b51d..b3249028ea6 100644 --- a/packages/firestore-types/index.d.ts +++ b/packages/firestore-types/index.d.ts @@ -237,13 +237,21 @@ export class FirebaseFirestore { app: any; /** - * Clears the persistent storage. + * Clears the persistent storage. This includes pending writes and cached + * documents. * - * Must be called while the client is not started (after the app is + * 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 - * client is still running, an exception with a code of `failed-precondition` - * will be thrown. + * 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. From 47e5fc72a9645d96a1e27223123717ad54987399 Mon Sep 17 00:00:00 2001 From: Brian Chen Date: Tue, 4 Jun 2019 18:44:39 -0700 Subject: [PATCH 12/13] added changelog --- packages/firestore/CHANGELOG.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/packages/firestore/CHANGELOG.md b/packages/firestore/CHANGELOG.md index 51eae881d24..2c7b17161f4 100644 --- a/packages/firestore/CHANGELOG.md +++ b/packages/firestore/CHANGELOG.md @@ -2,6 +2,11 @@ # Unreleased - [changed] Firestore now recovers more quickly after network connectivity changes (airplane mode, Wi-Fi availability, etc.). +- [feature] Added `clearPersistence()`, clears the persistent storage + including pending writes and cached tests. This is intended to help + write reliable tests. For applications sensitive to disclosure of cache data + in between user sessions, we strongly recommend not to enable persistence + in the first place. # 1.3.0 - [changed] Deprecated the `experimentalTabSynchronization` setting in favor of From 0a17d5033167900f646f303dd3d4b95df37ba9ff Mon Sep 17 00:00:00 2001 From: Brian Chen Date: Wed, 5 Jun 2019 10:41:13 -0700 Subject: [PATCH 13/13] update changelog --- packages/firestore/CHANGELOG.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/packages/firestore/CHANGELOG.md b/packages/firestore/CHANGELOG.md index 2c7b17161f4..b37c4818b99 100644 --- a/packages/firestore/CHANGELOG.md +++ b/packages/firestore/CHANGELOG.md @@ -1,12 +1,12 @@ # 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.). -- [feature] Added `clearPersistence()`, clears the persistent storage - including pending writes and cached tests. This is intended to help - write reliable tests. For applications sensitive to disclosure of cache data - in between user sessions, we strongly recommend not to enable persistence - in the first place. # 1.3.0 - [changed] Deprecated the `experimentalTabSynchronization` setting in favor of