Multi-Tab Persistence

As per go/multi-tab.

This feature is not yet enabled for third-party users.

Author: schmidt-sebastian

packages/firebase/index.d.ts

@@ -769,6 +769,27 @@ declare namespace firebase.firestore {
     timestampsInSnapshots?: boolean;
   }
 
+  // TODO(multitab): Uncomment when multi-tab is released publicly.
+  // /**
+  //  * Settings that can be passed to Firestore.enablePersistence() to configure
+  //  * Firestore persistence.
+  //  */
+  // export interface PersistenceSettings {
+  //   /**
+  //    * 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.
+  //    *
+  //    * 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.
+  //    *
+  //    * NOTE: This mode is not yet recommended for production use.
+  //    */
+  //   experimentalTabSynchronization?: boolean;
+  // }
+
   export type LogLevel = 'debug' | 'error' | 'silent';
 
   export function setLogLevel(logLevel: LogLevel): void;
@@ -808,6 +829,29 @@ declare namespace firebase.firestore {
      */
     enablePersistence(): Promise<void>;
 
+    // TODO(multitab): Uncomment when multi-tab is released publicly.
+    // /**
+    //  * Attempts to enable persistent storage, if possible.
+    //  *
+    //  * Must be called before any other methods (other than settings()).
+    //  *
+    //  * If this fails, enablePersistence() will reject the promise it returns.
+    //  * Note that even after this failure, the firestore instance will remain
+    //  * usable, however offline persistence will be disabled.
+    //  *
+    //  * There are several reasons why this can fail, which can be identified by
+    //  * the `code` on the error.
+    //  *
+    //  *   * failed-precondition: The app is already open in another browser tab.
+    //  *   * unimplemented: The browser is incompatible with the offline
+    //  *     persistence implementation.
+    //  *
+    //  * @param settings Optional settings object to configure persistence.
+    //  * @return A promise that represents successfully enabling persistent
+    //  * storage.
+    //  */
+    // enablePersistence(settings?: PersistenceSettings): Promise<void>;
+
     /**
      * Gets a `CollectionReference` instance that refers to the collection at
      * the specified path.

packages/firestore-types/index.d.ts

@@ -57,6 +57,27 @@ export interface Settings {
   timestampsInSnapshots?: boolean;
 }
 
+// TODO(multitab): Uncomment when multi-tab is released publicly.
+// /**
+//  * Settings that can be passed to Firestore.enablePersistence() to configure
+//  * Firestore persistence.
+//  */
+// export interface PersistenceSettings {
+//   /**
+//    * 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.
+//    *
+//    * 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.
+//    *
+//    * NOTE: This mode is not yet recommended for production use.
+//    */
+//   experimentalTabSynchronization?: boolean;
+// }
+
 export type LogLevel = 'debug' | 'error' | 'silent';
 
 export function setLogLevel(logLevel: LogLevel): void;
@@ -96,6 +117,29 @@ export class FirebaseFirestore {
    */
   enablePersistence(): Promise<void>;
 
+  // TODO(multitab): Uncomment when multi-tab is released publicly.
+  // /**
+  //  * Attempts to enable persistent storage, if possible.
+  //  *
+  //  * Must be called before any other methods (other than settings()).
+  //  *
+  //  * If this fails, enablePersistence() will reject the promise it returns.
+  //  * Note that even after this failure, the firestore instance will remain
+  //  * usable, however offline persistence will be disabled.
+  //  *
+  //  * There are several reasons why this can fail, which can be identified by
+  //  * the `code` on the error.
+  //  *
+  //  *   * failed-precondition: The app is already open in another browser tab.
+  //  *   * unimplemented: The browser is incompatible with the offline
+  //  *     persistence implementation.
+  //  *
+  //  * @param settings Optional settings object to configure persistence.
+  //  * @return A promise that represents successfully enabling persistent
+  //  * storage.
+  //  */
+  // enablePersistence(settings?: PersistenceSettings): Promise<void>;
+
   /**
    * Gets a `CollectionReference` instance that refers to the collection at
    * the specified path.

packages/firestore/.idea/runConfigurations/All_Tests.xml

@@ -97,10 +97,14 @@ import {
 // underscore to discourage their use.
 // tslint:disable:strip-private-property-underscore
 
+// settings() defaults:
 const DEFAULT_HOST = 'firestore.googleapis.com';
 const DEFAULT_SSL = true;
 const DEFAULT_TIMESTAMPS_IN_SNAPSHOTS = false;
 
+// enablePersistence() defaults:
+const DEFAULT_SYNCHRONIZE_TABS = false;
+
 /** Undocumented, private additional settings not exposed in our public API. */
 interface PrivateSettings extends firestore.Settings {
   // Can be a google-auth-library or gapi client.
@@ -197,6 +201,39 @@ class FirestoreConfig {
   persistence: boolean;
 }
 
+// TODO(multitab): Replace with Firestore.PersistenceSettings
+// tslint:disable-next-line:no-any The definition for these settings is private
+export type _PersistenceSettings = any;
+
+/**
+ * Encapsulates the settings that can be used to configure Firestore
+ * persistence.
+ */
+export class PersistenceSettings {
+  /** Whether to enable multi-tab synchronization. */
+  experimentalTabSynchronization: boolean;
+
+  constructor(readonly enabled: boolean, settings?: _PersistenceSettings) {
+    assert(
+      enabled || !settings,
+      'Can only provide PersistenceSettings with persistence enabled'
+    );
+    settings = settings || {};
+    this.experimentalTabSynchronization = objUtils.defaulted(
+      settings.experimentalTabSynchronization,
+      DEFAULT_SYNCHRONIZE_TABS
+    );
+  }
+
+  isEqual(other: PersistenceSettings): boolean {
+    return (
+      this.enabled === other.enabled &&
+      this.experimentalTabSynchronization ===
+        other.experimentalTabSynchronization
+    );
+  }
+}
+
 /**
  * The root reference to the database.
  */
@@ -290,7 +327,7 @@ export class Firestore implements firestore.FirebaseFirestore, FirebaseService {
     return this._firestoreClient.disableNetwork();
   }
 
-  enablePersistence(): Promise<void> {
+  enablePersistence(settings?: _PersistenceSettings): Promise<void> {
     if (this._firestoreClient) {
       throw new FirestoreError(
         Code.FAILED_PRECONDITION,
@@ -300,19 +337,23 @@ export class Firestore implements firestore.FirebaseFirestore, FirebaseService {
       );
     }
 
-    return this.configureClient(/* persistence= */ true);
+    return this.configureClient(
+      new PersistenceSettings(/* enabled= */ true, settings)
+    );
   }
 
   ensureClientConfigured(): FirestoreClient {
     if (!this._firestoreClient) {
       // Kick off starting the client but don't actually wait for it.
       // tslint:disable-next-line:no-floating-promises
-      this.configureClient(/* persistence= */ false);
+      this.configureClient(new PersistenceSettings(/* enabled= */ false));
     }
     return this._firestoreClient as FirestoreClient;
   }
 
-  private configureClient(persistence: boolean): Promise<void> {
+  private configureClient(
+    persistenceSettings: PersistenceSettings
+  ): Promise<void> {
     assert(
       !!this._config.settings.host,
       'FirestoreSettings.host cannot be falsey'
@@ -378,7 +419,7 @@ follow these steps, YOUR APP MAY BREAK.`);
       this._config.credentials,
       this._queue
     );
-    return this._firestoreClient.start(persistence);
+    return this._firestoreClient.start(persistenceSettings);
   }
 
   private static databaseIdFromApp(app: FirebaseApp): DatabaseId {

packages/firestore/.idea/runConfigurations/Integration_Tests.xml

@@ -15,11 +15,10 @@
  */
 
 import { Query } from './query';
-import { SyncEngine } from './sync_engine';
+import { SyncEngine, SyncEngineListener } from './sync_engine';
 import { OnlineState, TargetId } from './types';
 import { DocumentViewChange } from './view_snapshot';
 import { ChangeType, ViewSnapshot } from './view_snapshot';
-import { DocumentSet } from '../model/document_set';
 import { assert } from '../util/assert';
 import { EventHandler } from '../util/misc';
 import { ObjectMap } from '../util/obj_map';
@@ -47,18 +46,15 @@ export interface Observer<T> {
  * It handles "fan-out". -- Identical queries will re-use the same watch on the
  * backend.
  */
-export class EventManager {
+export class EventManager implements SyncEngineListener {
   private queries = new ObjectMap<Query, QueryListenersInfo>(q =>
     q.canonicalId()
   );
 
   private onlineState: OnlineState = OnlineState.Unknown;
 
   constructor(private syncEngine: SyncEngine) {
-    this.syncEngine.subscribe(
-      this.onChange.bind(this),
-      this.onError.bind(this)
-    );
+    this.syncEngine.subscribe(this);
   }
 
   listen(listener: QueryListener): Promise<TargetId> {
@@ -106,7 +102,7 @@ export class EventManager {
     }
   }
 
-  onChange(viewSnaps: ViewSnapshot[]): void {
+  onWatchChange(viewSnaps: ViewSnapshot[]): void {
     for (const viewSnap of viewSnaps) {
       const query = viewSnap.query;
       const queryInfo = this.queries.get(query);
@@ -119,7 +115,7 @@ export class EventManager {
     }
   }
 
-  onError(query: Query, error: Error): void {
+  onWatchError(query: Query, error: Error): void {
     const queryInfo = this.queries.get(query);
     if (queryInfo) {
       for (const listener of queryInfo.listeners) {
@@ -132,7 +128,7 @@ export class EventManager {
     this.queries.delete(query);
   }
 
-  applyOnlineStateChange(onlineState: OnlineState): void {
+  onOnlineStateChange(onlineState: OnlineState): void {
     this.onlineState = onlineState;
     this.queries.forEach((_, queryInfo) => {
       for (const listener of queryInfo.listeners) {
@@ -289,28 +285,13 @@ export class QueryListener {
       !this.raisedInitialEvent,
       'Trying to raise initial events for second time'
     );
-    snap = new ViewSnapshot(
+    snap = ViewSnapshot.fromInitialDocuments(
       snap.query,
       snap.docs,
-      DocumentSet.emptySet(snap.docs),
-      QueryListener.getInitialViewChanges(snap),
       snap.fromCache,
-      snap.hasPendingWrites,
-      /* syncChangesState= */ true,
-      /* excludesMetadataChanges= */ false
+      snap.hasPendingWrites
     );
     this.raisedInitialEvent = true;
     this.queryObserver.next(snap);
   }
-
-  /** Returns changes as if all documents in the snap were added. */
-  private static getInitialViewChanges(
-    snap: ViewSnapshot
-  ): DocumentViewChange[] {
-    const result: DocumentViewChange[] = [];
-    snap.docs.forEach(doc => {
-      result.push({ type: ChangeType.Added, doc });
-    });
-    return result;
-  }
 }