snapshot listeners source from cache

.changeset/smart-games-cheer.md

@@ -0,0 +1,5 @@
+---
+'@firebase/firestore': minor
+'firebase': minor
+---
+Enable snapshot listeners to source from local cache.

common/api-review/firestore.api.md

@@ -350,6 +350,12 @@ export function limit(limit: number): QueryLimitConstraint;
 // @public
 export function limitToLast(limit: number): QueryLimitConstraint;
 
+// @public
+export const enum ListenSource {
+    Cache = 1,
+    Default = 0
+}
+
 // @public
 export function loadBundle(firestore: Firestore, bundleData: ReadableStream<Uint8Array> | ArrayBuffer | string): LoadBundleTask;
 
@@ -651,6 +657,7 @@ export function snapshotEqual<AppModelType, DbModelType extends DocumentData>(le
 // @public
 export interface SnapshotListenOptions {
     readonly includeMetadataChanges?: boolean;
+    readonly source?: ListenSource;
 }
 
 // @public

docs-devsite/firestore_.md

@@ -157,6 +157,12 @@ https://github.com/firebase/firebase-js-sdk
 |  [Transaction](./firestore_.transaction.md#transaction_class) | A reference to a transaction.<!-- -->The <code>Transaction</code> object passed to a transaction's <code>updateFunction</code> provides the methods to read and write data within the transaction context. See [runTransaction()](./firestore_.md#runtransaction_6f03ec4)<!-- -->. |
 |  [WriteBatch](./firestore_.writebatch.md#writebatch_class) | A write batch, used to perform multiple writes as a single atomic unit.<!-- -->A <code>WriteBatch</code> object can be acquired by calling [writeBatch()](./firestore_.md#writebatch_231a8e0)<!-- -->. It provides methods for adding writes to the write batch. None of the writes will be committed (or visible locally) until [WriteBatch.commit()](./firestore_.writebatch.md#writebatchcommit) is called. |
 
+## Enumerations
+
+|  Enumeration | Description |
+|  --- | --- |
+|  [ListenSource](./firestore_.md#listensource) | Describe the source a query listens to. |
+
 ## Interfaces
 
 |  Interface | Description |
@@ -2716,3 +2722,21 @@ export declare type WithFieldValue<T> = T | (T extends Primitive ? T : T extends
     [K in keyof T]: WithFieldValue<T[K]> | FieldValue;
 } : never);
 ```
+
+## ListenSource
+
+Describe the source a query listens to.
+
+<b>Signature:</b>
+
+```typescript
+export declare const enum ListenSource 
+```
+
+## Enumeration Members
+
+|  Member | Value | Description |
+|  --- | --- | --- |
+|  Cache | <code>1</code> | Listen to changes in cache only |
+|  Default | <code>0</code> | Listen to both cache and server changes |
+

docs-devsite/firestore_.snapshotlistenoptions.md

@@ -23,6 +23,7 @@ export declare interface SnapshotListenOptions
 |  Property | Type | Description |
 |  --- | --- | --- |
 |  [includeMetadataChanges](./firestore_.snapshotlistenoptions.md#snapshotlistenoptionsincludemetadatachanges) | boolean | Include a change even if only the metadata of the query or of a document changed. Default is false. |
+|  [source](./firestore_.snapshotlistenoptions.md#snapshotlistenoptionssource) | [ListenSource](./firestore_.md#listensource) | Set the source the query listens to. Default to ListenSource.Default, which listens to both cache and server. |
 
 ## SnapshotListenOptions.includeMetadataChanges
 
@@ -33,3 +34,13 @@ Include a change even if only the metadata of the query or of a document changed
 ```typescript
 readonly includeMetadataChanges?: boolean;
 ```
+
+## SnapshotListenOptions.source
+
+Set the source the query listens to. Default to ListenSource.Default, which listens to both cache and server.
+
+<b>Signature:</b>
+
+```typescript
+readonly source?: ListenSource;
+```

packages/firestore/src/api.ts

@@ -139,7 +139,11 @@ export {
   WhereFilterOp
 } from './api/filter';
 
-export { SnapshotListenOptions, Unsubscribe } from './api/reference_impl';
+export {
+  ListenSource,
+  SnapshotListenOptions,
+  Unsubscribe
+} from './api/reference_impl';
 
 export { TransactionOptions } from './api/transaction_options';
 

packages/firestore/src/api/reference_impl.ts

@@ -78,6 +78,21 @@ export interface SnapshotListenOptions {
    * changed. Default is false.
    */
   readonly includeMetadataChanges?: boolean;
+
+  /**
+   * Set the source the query listens to. Default to ListenSource.Default, which
+   * listens to both cache and server.
+   */
+  readonly source?: ListenSource;
+}
+
+/** Describe the source a query listens to. */
+export const enum ListenSource {
+  /** Listen to both cache and server changes */
+  Default,
+
+  /** Listen to changes in cache only */
+  Cache
 }
 
 /**
@@ -668,7 +683,8 @@ export function onSnapshot<AppModelType, DbModelType extends DocumentData>(
   reference = getModularInstance(reference);
 
   let options: SnapshotListenOptions = {
-    includeMetadataChanges: false
+    includeMetadataChanges: false,
+    source: ListenSource.Default
   };
   let currArg = 0;
   if (typeof args[currArg] === 'object' && !isPartialObserver(args[currArg])) {
@@ -677,7 +693,8 @@ export function onSnapshot<AppModelType, DbModelType extends DocumentData>(
   }
 
   const internalOptions = {
-    includeMetadataChanges: options.includeMetadataChanges
+    includeMetadataChanges: options.includeMetadataChanges,
+    source: options.source
   };
 
   if (isPartialObserver(args[currArg])) {

packages/firestore/src/core/event_manager.ts

@@ -15,6 +15,7 @@
  * limitations under the License.
  */
 
+import { ListenSource } from '../api/reference_impl';
 import { debugAssert, debugCast } from '../util/assert';
 import { wrapInUserErrorIfRecoverable } from '../util/async_queue';
 import { FirestoreError } from '../util/error';
@@ -32,6 +33,11 @@ import { ChangeType, DocumentViewChange, ViewSnapshot } from './view_snapshot';
 class QueryListenersInfo {
   viewSnap: ViewSnapshot | undefined = undefined;
   listeners: QueryListener[] = [];
+
+  // Helper methods that checks if the query has listeners that listening to remote store
+  hasRemoteListeners(): boolean {
+    return this.listeners.some(listener => listener.listensToRemoteStore());
+  }
 }
 
 /**
@@ -52,8 +58,13 @@ export interface Observer<T> {
  * allows users to tree-shake the Watch logic.
  */
 export interface EventManager {
-  onListen?: (query: Query) => Promise<ViewSnapshot>;
-  onUnlisten?: (query: Query) => Promise<void>;
+  onListen?: (
+    query: Query,
+    enableRemoteListen: boolean
+  ) => Promise<ViewSnapshot>;
+  onUnlisten?: (query: Query, disableRemoteListen: boolean) => Promise<void>;
+  onFirstRemoteStoreListen?: (query: Query) => Promise<void>;
+  onLastRemoteStoreUnlisten?: (query: Query) => Promise<void>;
 }
 
 export function newEventManager(): EventManager {
@@ -71,38 +82,101 @@ export class EventManagerImpl implements EventManager {
   snapshotsInSyncListeners: Set<Observer<void>> = new Set();
 
   /** Callback invoked when a Query is first listen to. */
-  onListen?: (query: Query) => Promise<ViewSnapshot>;
+  onListen?: (
+    query: Query,
+    enableRemoteListen: boolean
+  ) => Promise<ViewSnapshot>;
   /** Callback invoked once all listeners to a Query are removed. */
-  onUnlisten?: (query: Query) => Promise<void>;
+  onUnlisten?: (query: Query, disableRemoteListen: boolean) => Promise<void>;
+
+  /**
+   * Callback invoked when a Query starts listening to the remote store, while
+   * already listening to the cache.
+   */
+  onFirstRemoteStoreListen?: (query: Query) => Promise<void>;
+  /**
+   * Callback invoked when a Query stops listening to the remote store, while
+   * still listening to the cache.
+   */
+  onLastRemoteStoreUnlisten?: (query: Query) => Promise<void>;
+}
+
+function validateEventManager(eventManagerImpl: EventManagerImpl): void {
+  debugAssert(!!eventManagerImpl.onListen, 'onListen not set');
+  debugAssert(
+    !!eventManagerImpl.onFirstRemoteStoreListen,
+    'onFirstRemoteStoreListen not set'
+  );
+  debugAssert(!!eventManagerImpl.onUnlisten, 'onUnlisten not set');
+  debugAssert(
+    !!eventManagerImpl.onLastRemoteStoreUnlisten,
+    'onLastRemoteStoreUnlisten not set'
+  );
+}
+
+const enum ListenerSetupAction {
+  InitializeLocalListenAndRequireWatchConnection,
+  InitializeLocalListenOnly,
+  RequireWatchConnectionOnly,
+  NoActionRequired
+}
+
+const enum ListenerRemovalAction {
+  TerminateLocalListenAndRequireWatchDisconnection,
+  TerminateLocalListenOnly,
+  RequireWatchDisconnectionOnly,
+  NoActionRequired
 }
 
 export async function eventManagerListen(
   eventManager: EventManager,
   listener: QueryListener
 ): Promise<void> {
   const eventManagerImpl = debugCast(eventManager, EventManagerImpl);
+  validateEventManager(eventManagerImpl);
+
+  let listenerAction = ListenerSetupAction.NoActionRequired;
 
-  debugAssert(!!eventManagerImpl.onListen, 'onListen not set');
   const query = listener.query;
-  let firstListen = false;
 
   let queryInfo = eventManagerImpl.queries.get(query);
   if (!queryInfo) {
-    firstListen = true;
     queryInfo = new QueryListenersInfo();
+    listenerAction = listener.listensToRemoteStore()
+      ? ListenerSetupAction.InitializeLocalListenAndRequireWatchConnection
+      : ListenerSetupAction.InitializeLocalListenOnly;
+  } else if (listener.listensToRemoteStore()) {
+    // Query has been listening to local cache, and tries to add a new listener sourced from watch.
+    listenerAction = ListenerSetupAction.RequireWatchConnectionOnly;
   }
 
-  if (firstListen) {
-    try {
-      queryInfo.viewSnap = await eventManagerImpl.onListen(query);
-    } catch (e) {
-      const firestoreError = wrapInUserErrorIfRecoverable(
-        e as Error,
-        `Initialization of query '${stringifyQuery(listener.query)}' failed`
-      );
-      listener.onError(firestoreError);
-      return;
+  try {
+    switch (listenerAction) {
+      case ListenerSetupAction.InitializeLocalListenAndRequireWatchConnection:
+        queryInfo.viewSnap = await eventManagerImpl.onListen!(
+          query,
+          /** enableRemoteListen= */ true
+        );
+        break;
+      case ListenerSetupAction.InitializeLocalListenOnly:
+        queryInfo.viewSnap = await eventManagerImpl.onListen!(
+          query,
+          /** enableRemoteListen= */ false
+        );
+        break;
+      case ListenerSetupAction.RequireWatchConnectionOnly:
+        await eventManagerImpl.onFirstRemoteStoreListen!(query);
+        break;
+      default:
+        break;
     }
+  } catch (e) {
+    const firestoreError = wrapInUserErrorIfRecoverable(
+      e as Error,
+      `Initialization of query '${stringifyQuery(listener.query)}' failed`
+    );
+    listener.onError(firestoreError);
+    return;
   }
 
   eventManagerImpl.queries.set(query, queryInfo);
@@ -130,23 +204,47 @@ export async function eventManagerUnlisten(
   listener: QueryListener
 ): Promise<void> {
   const eventManagerImpl = debugCast(eventManager, EventManagerImpl);
+  validateEventManager(eventManagerImpl);
 
-  debugAssert(!!eventManagerImpl.onUnlisten, 'onUnlisten not set');
   const query = listener.query;
-  let lastListen = false;
+  let listenerAction = ListenerRemovalAction.NoActionRequired;
 
   const queryInfo = eventManagerImpl.queries.get(query);
   if (queryInfo) {
     const i = queryInfo.listeners.indexOf(listener);
     if (i >= 0) {
       queryInfo.listeners.splice(i, 1);
-      lastListen = queryInfo.listeners.length === 0;
+
+      if (queryInfo.listeners.length === 0) {
+        listenerAction = listener.listensToRemoteStore()
+          ? ListenerRemovalAction.TerminateLocalListenAndRequireWatchDisconnection
+          : ListenerRemovalAction.TerminateLocalListenOnly;
+      } else if (
+        !queryInfo.hasRemoteListeners() &&
+        listener.listensToRemoteStore()
+      ) {
+        // The removed listener is the last one that sourced from watch.
+        listenerAction = ListenerRemovalAction.RequireWatchDisconnectionOnly;
+      }
     }
   }
-
-  if (lastListen) {
-    eventManagerImpl.queries.delete(query);
-    return eventManagerImpl.onUnlisten(query);
+  switch (listenerAction) {
+    case ListenerRemovalAction.TerminateLocalListenAndRequireWatchDisconnection:
+      eventManagerImpl.queries.delete(query);
+      return eventManagerImpl.onUnlisten!(
+        query,
+        /** disableRemoteListen= */ true
+      );
+    case ListenerRemovalAction.TerminateLocalListenOnly:
+      eventManagerImpl.queries.delete(query);
+      return eventManagerImpl.onUnlisten!(
+        query,
+        /** disableRemoteListen= */ false
+      );
+    case ListenerRemovalAction.RequireWatchDisconnectionOnly:
+      return eventManagerImpl.onLastRemoteStoreUnlisten!(query);
+    default:
+      return;
   }
 }
 
@@ -250,6 +348,9 @@ export interface ListenOptions {
    * offline.
    */
   readonly waitForSyncWhenOnline?: boolean;
+
+  /** Set the source events raised from. */
+  readonly source?: ListenSource;
 }
 
 /**
@@ -359,6 +460,11 @@ export class QueryListener {
       return true;
     }
 
+    // Always raise event if listening to cache
+    if (!this.listensToRemoteStore()) {
+      return true;
+    }
+
     // NOTE: We consider OnlineState.Unknown as online (it should become Offline
     // or Online if we wait long enough).
     const maybeOnline = onlineState !== OnlineState.Offline;
@@ -417,4 +523,8 @@ export class QueryListener {
     this.raisedInitialEvent = true;
     this.queryObserver.next(snap);
   }
+
+  listensToRemoteStore(): boolean {
+    return this.options.source !== ListenSource.Cache;
+  }
 }