Rename multi-tab setting to synchronizeTabs (#1728)

* Rename multi-tab setting to synchronizeTabs

* [AUTOMATED]: Prettier Code Styling

* Update error message

Author: schmidt-sebastian

packages/firebase/index.d.ts

@@ -5903,11 +5903,20 @@ declare namespace firebase.firestore {
      * shared execution of queries and latency-compensated local document updates
      * across all connected instances.
      *
-     * To enable this mode, `experimentalTabSynchronization:true` needs to be set
-     * globally in all active tabs. If omitted or set to 'false',
-     * `enablePersistence()` will fail in all but the first tab.
+     * To enable this mode, `synchronizeTabs:true` needs to be set globally in all
+     * active tabs. If omitted or set to 'false', `enablePersistence()` will fail
+     * in all but the first tab.
+     */
+    synchronizeTabs?: boolean;
+
+    /**
+     * Whether to synchronize the in-memory state of multiple tabs. Setting this
+     * to 'true' in all open tabs enables shared access to local persistence,
+     * shared execution of queries and latency-compensated local document updates
+     * across all connected instances.
      *
-     * NOTE: This mode is not yet recommended for production use.
+     * @deprecated This setting is deprecated. To enabled synchronization between
+     * multiple tabs, please use `synchronizeTabs: true` instead.
      */
     experimentalTabSynchronization?: boolean;
   }

packages/firestore-types/index.d.ts

@@ -106,11 +106,20 @@ export interface PersistenceSettings {
    * shared execution of queries and latency-compensated local document updates
    * across all connected instances.
    *
-   * To enable this mode, `experimentalTabSynchronization:true` needs to be set
-   * globally in all active tabs. If omitted or set to 'false',
-   * `enablePersistence()` will fail in all but the first tab.
+   * To enable this mode, `synchronizeTabs:true` needs to be set globally in all
+   * active tabs. If omitted or set to 'false', `enablePersistence()` will fail
+   * in all but the first tab.
+   */
+  synchronizeTabs?: boolean;
+
+  /**
+   * Whether to synchronize the in-memory state of multiple tabs. Setting this
+   * to 'true' in all open tabs enables shared access to local persistence,
+   * shared execution of queries and latency-compensated local document updates
+   * across all connected instances.
    *
-   * NOTE: This mode is not yet recommended for production use.
+   * @deprecated This setting is deprecated. To enabled synchronization between
+   * multiple tabs, please use `synchronizeTabs: true` instead.
    */
   experimentalTabSynchronization?: boolean;
 }

packages/firestore/CHANGELOG.md

@@ -1,6 +1,11 @@
-# Unreleased (I/O)
+
+# Unreleased
+- [changed] Deprecated the `experimentalTabSynchronization` setting in favor of 
+  `synchronizeTabs`. If you use multi-tab synchronization, it is recommended
+  that you update your call to `enablePersistence()`. Firestore logs an error
+  if you continue to use `experimentalTabSynchronization`.
 - [feature] You can now query across all collections in your database with a
-given collection ID using the `FirebaseFirestore.collectionGroup()` method.
+  given collection ID using the `FirebaseFirestore.collectionGroup()` method.
 
 # 1.1.4
 - [feature] Added an `experimentalForceLongPolling` setting that that can be

packages/firestore/src/api/database.ts

@@ -398,14 +398,30 @@ export class Firestore implements firestore.FirebaseFirestore, FirebaseService {
           'any other methods on a Firestore object.'
       );
     }
+
+    let synchronizeTabs = false;
+
+    if (settings) {
+      if (settings.experimentalTabSynchronization !== undefined) {
+        log.error(
+          "The 'experimentalTabSynchronization' setting has been renamed to " +
+            "'synchronizeTabs'. In a future release, the setting will be removed " +
+            'and it is recommended that you update your ' +
+            "firestore.enablePersistence() call to use 'synchronizeTabs'."
+        );
+      }
+      synchronizeTabs = objUtils.defaulted(
+        settings.synchronizeTabs !== undefined
+          ? settings.synchronizeTabs
+          : settings.experimentalTabSynchronization,
+        DEFAULT_SYNCHRONIZE_TABS
+      );
+    }
+
     return this.configureClient(
       new IndexedDbPersistenceSettings(
         this._config.settings.cacheSizeBytes,
-        settings !== undefined &&
-          objUtils.defaulted(
-            settings.experimentalTabSynchronization,
-            DEFAULT_SYNCHRONIZE_TABS
-          )
+        synchronizeTabs
       )
     );
   }

packages/firestore/src/core/firestore_client.ts

@@ -74,7 +74,7 @@ const DOM_EXCEPTION_QUOTA_EXCEEDED = 22;
 export class IndexedDbPersistenceSettings {
   constructor(
     readonly cacheSizeBytes: number,
-    readonly experimentalTabSynchronization: boolean
+    readonly synchronizeTabs: boolean
   ) {}
 
   lruParams(): LruParams {
@@ -334,7 +334,7 @@ export class FirestoreClient {
 
     return Promise.resolve().then(async () => {
       if (
-        settings.experimentalTabSynchronization &&
+        settings.synchronizeTabs &&
         !WebStorageSharedClientState.isAvailable(this.platform)
       ) {
         throw new FirestoreError(
@@ -345,7 +345,7 @@ export class FirestoreClient {
 
       let persistence: IndexedDbPersistence;
       const lruParams = settings.lruParams();
-      if (settings.experimentalTabSynchronization) {
+      if (settings.synchronizeTabs) {
         this.sharedClientState = new WebStorageSharedClientState(
           this.asyncQueue,
           this.platform,

packages/firestore/src/local/indexeddb_persistence.ts

@@ -103,7 +103,7 @@ const PRIMARY_LEASE_LOST_ERROR_MSG =
 const PRIMARY_LEASE_EXCLUSIVE_ERROR_MSG =
   'Another tab has exclusive access to the persistence layer. ' +
   'To allow shared access, make sure to invoke ' +
-  '`enablePersistence()` with `experimentalTabSynchronization:true` in all tabs.';
+  '`enablePersistence()` with `synchronizeTabs:true` in all tabs.';
 const UNSUPPORTED_PLATFORM_ERROR_MSG =
   'This platform is either missing' +
   ' IndexedDB or is known to have an incomplete implementation. Offline' +
@@ -130,7 +130,7 @@ export class IndexedDbTransaction extends PersistenceTransaction {
  * layer. This allows multiple browser tabs to read and write to IndexedDb and
  * to synchronize state even without network connectivity. Shared access is
  * currently optional and not enabled unless all clients invoke
- * `enablePersistence()` with `{experimentalTabSynchronization:true}`.
+ * `enablePersistence()` with `{synchronizeTabs:true}`.
  *
  * In multi-tab mode, if multiple clients are active at the same time, the SDK
  * will designate one client as the “primary client”. An effort is made to pick
@@ -165,8 +165,8 @@ export class IndexedDbTransaction extends PersistenceTransaction {
  * LocalStorage which acts as an indicator that another tab should go ahead and
  * take the primary lease immediately regardless of the current lease timestamp.
  *
- * TODO(b/114226234): Remove `experimentalTabSynchronization` section when
- * multi-tab is no longer optional.
+ * TODO(b/114226234): Remove `synchronizeTabs` section when multi-tab is no
+ * longer optional.
  */
 export type MultiClientParams = {
   sequenceNumberSyncer: SequenceNumberSyncer;