@firebase/firestore 4.4.3-canary.6d487d7de → 4.4.3-canary.ce88e71e7

package/dist/firestore/src/api/reference_impl.d.ts

@@ -34,7 +34,19 @@ export interface SnapshotListenOptions {
      * changed. Default is false.
      */
     readonly includeMetadataChanges?: boolean;
+    /**
+     * Set the source the query listens to. Default to "default", which
+     * listens to both cache and server.
+     */
+    readonly source?: ListenSource;
 }
+/**
+ * Describe the source a query listens to.
+ *
+ * Set to `default` to listen to both cache and server changes. Set to `cache`
+ * to listen to changes in cache only.
+ */
+export declare type ListenSource = 'default' | 'cache';
 /**
  * Reads the document referred to by this `DocumentReference`.
  *

package/dist/firestore/src/api.d.ts

@@ -26,7 +26,7 @@ export { ExperimentalLongPollingOptions } from './api/long_polling_options';
 export { DocumentChange, DocumentChangeType, DocumentSnapshot, FirestoreDataConverter, QueryDocumentSnapshot, QuerySnapshot, snapshotEqual, SnapshotMetadata, SnapshotOptions } from './api/snapshot';
 export { collection, collectionGroup, CollectionReference, doc, DocumentData, DocumentReference, PartialWithFieldValue, Query, queryEqual, refEqual, SetOptions, UpdateData, WithFieldValue } from './api/reference';
 export { and, endAt, endBefore, limit, limitToLast, or, orderBy, OrderByDirection, query, QueryCompositeFilterConstraint, QueryConstraint, QueryConstraintType, QueryEndAtConstraint, QueryFieldFilterConstraint, QueryFilterConstraint, QueryLimitConstraint, QueryNonFilterConstraint, QueryOrderByConstraint, QueryStartAtConstraint, startAfter, startAt, where, 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';
 export { runTransaction, Transaction } from './api/transaction';
 export { addDoc, deleteDoc, executeWrite, getDoc, getDocFromCache, getDocFromServer, getDocs, getDocsFromCache, getDocsFromServer, onSnapshot, onSnapshotsInSync, setDoc, updateDoc } from './api/reference_impl';

package/dist/firestore/src/core/event_manager.d.ts

@@ -27,6 +27,7 @@ import { ViewSnapshot } from './view_snapshot';
 declare class QueryListenersInfo {
     viewSnap: ViewSnapshot | undefined;
     listeners: QueryListener[];
+    hasRemoteListeners(): boolean;
 }
 /**
  * Interface for handling events from the EventManager.
@@ -45,8 +46,10 @@ 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 declare function newEventManager(): EventManager;
 export declare class EventManagerImpl implements EventManager {
@@ -54,9 +57,19 @@ export declare class EventManagerImpl implements EventManager {
     onlineState: OnlineState;
     snapshotsInSyncListeners: Set<Observer<void>>;
     /** 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>;
 }
 export declare function eventManagerListen(eventManager: EventManager, listener: QueryListener): Promise<void>;
 export declare function eventManagerUnlisten(eventManager: EventManager, listener: QueryListener): Promise<void>;
@@ -65,6 +78,12 @@ export declare function eventManagerOnWatchError(eventManager: EventManager, que
 export declare function eventManagerOnOnlineStateChange(eventManager: EventManager, onlineState: OnlineState): void;
 export declare function addSnapshotsInSyncListener(eventManager: EventManager, observer: Observer<void>): void;
 export declare function removeSnapshotsInSyncListener(eventManager: EventManager, observer: Observer<void>): void;
+export declare enum ListenerDataSource {
+    /** Listen to both cache and server changes */
+    Default = "default",
+    /** Listen to changes in cache only */
+    Cache = "cache"
+}
 export interface ListenOptions {
     /** Raise events even when only the metadata changes */
     readonly includeMetadataChanges?: boolean;
@@ -73,6 +92,8 @@ export interface ListenOptions {
      * offline.
      */
     readonly waitForSyncWhenOnline?: boolean;
+    /** Set the source events raised from. */
+    readonly source?: ListenerDataSource;
 }
 /**
  * QueryListener takes a series of internal view snapshots and determines
@@ -105,5 +126,6 @@ export declare class QueryListener {
     private shouldRaiseInitialEvent;
     private shouldRaiseEvent;
     private raiseInitialEvent;
+    listensToRemoteStore(): boolean;
 }
 export {};

package/dist/firestore/src/core/sync_engine_impl.d.ts

@@ -174,9 +174,13 @@ export declare function newSyncEngine(localStore: LocalStore, remoteStore: Remot
  * server. All the subsequent view snapshots or errors are sent to the
  * subscribed handlers. Returns the initial snapshot.
  */
-export declare function syncEngineListen(syncEngine: SyncEngine, query: Query): Promise<ViewSnapshot>;
+export declare function syncEngineListen(syncEngine: SyncEngine, query: Query, shouldListenToRemote?: boolean): Promise<ViewSnapshot>;
+/** Query has been listening to the cache, and tries to initiate the remote store listen */
+export declare function triggerRemoteStoreListen(syncEngine: SyncEngine, query: Query): Promise<void>;
 /** Stops listening to the query. */
-export declare function syncEngineUnlisten(syncEngine: SyncEngine, query: Query): Promise<void>;
+export declare function syncEngineUnlisten(syncEngine: SyncEngine, query: Query, shouldUnlistenToRemote: boolean): Promise<void>;
+/** Unlistens to the remote store while still listening to the cache. */
+export declare function triggerRemoteStoreUnlisten(syncEngine: SyncEngine, query: Query): Promise<void>;
 /**
  * Initiates the write of local mutation batch which involves adding the
  * writes to the mutation queue, notifying the remote store about new

package/dist/firestore/src/global_index.d.ts

@@ -5380,8 +5380,10 @@ declare class AutoId {
  * allows users to tree-shake the Watch logic.
  */
 interface EventManager {
-    onListen?: (query: Query$1) => Promise<ViewSnapshot>;
-    onUnlisten?: (query: Query$1) => Promise<void>;
+    onListen?: (query: Query$1, enableRemoteListen: boolean) => Promise<ViewSnapshot>;
+    onUnlisten?: (query: Query$1, disableRemoteListen: boolean) => Promise<void>;
+    onFirstRemoteStoreListen?: (query: Query$1) => Promise<void>;
+    onLastRemoteStoreUnlisten?: (query: Query$1) => Promise<void>;
 }
 
 /**
@@ -7594,7 +7596,19 @@ interface SnapshotListenOptions {
      * changed. Default is false.
      */
     readonly includeMetadataChanges?: boolean;
+    /**
+     * Set the source the query listens to. Default to "default", which
+     * listens to both cache and server.
+     */
+    readonly source?: ListenSource;
 }
+/**
+ * Describe the source a query listens to.
+ *
+ * Set to `default` to listen to both cache and server changes. Set to `cache`
+ * to listen to changes in cache only.
+ */
+declare type ListenSource = 'default' | 'cache';
 /**
  * Reads the document referred to by this `DocumentReference`.
  *
@@ -9616,4 +9630,4 @@ declare module '@firebase/component' {
     }
 }
 
-export { AbstractUserDataWriter, AddPrefixToKeys, AggregateField, AggregateFieldType, AggregateQuerySnapshot, AggregateSpec, AggregateSpecData, AggregateType, AuthTokenFactory, Bytes, CACHE_SIZE_UNLIMITED, ChildUpdateFields, CollectionReference, DocumentChange, DocumentChangeType, DocumentData, DocumentReference, DocumentSnapshot, EmulatorMockTokenOptions, ExperimentalLongPollingOptions, FieldPath, FieldValue, Firestore, FirestoreDataConverter, FirestoreError, FirestoreErrorCode, FirestoreLocalCache, FirestoreSettings, FirstPartyCredentialsSettings, GeoPoint, Index, IndexConfiguration, IndexField, LoadBundleTask, LoadBundleTaskProgress, LogLevelString as LogLevel, MemoryCacheSettings, MemoryEagerGarbageCollector, MemoryGarbageCollector, MemoryLocalCache, MemoryLruGarbageCollector, NestedUpdateFields, OrderByDirection, PartialWithFieldValue, PersistenceSettings, PersistentCacheIndexManager, PersistentCacheSettings, PersistentLocalCache, PersistentMultipleTabManager, PersistentSingleTabManager, PersistentSingleTabManagerSettings, PersistentTabManager, Primitive, PrivateSettings, Query, QueryCompositeFilterConstraint, QueryConstraint, QueryConstraintType, QueryDocumentSnapshot, QueryEndAtConstraint, QueryFieldFilterConstraint, QueryFilterConstraint, QueryLimitConstraint, QueryNonFilterConstraint, QueryOrderByConstraint, QuerySnapshot, QueryStartAtConstraint, SetOptions, SnapshotListenOptions, SnapshotMetadata, SnapshotOptions, TaskState, Timestamp$1 as Timestamp, Transaction, TransactionOptions, UnionToIntersection, Unsubscribe, UpdateData, WhereFilterOp, WithFieldValue, WriteBatch, AutoId as _AutoId, ByteString as _ByteString, DatabaseId as _DatabaseId, DocumentKey as _DocumentKey, EmptyAppCheckTokenProvider as _EmptyAppCheckTokenProvider, EmptyAuthCredentialsProvider as _EmptyAuthCredentialsProvider, FieldPath$1 as _FieldPath, ResourcePath as _ResourcePath, TestingHooks as _TestingHooks, ExistenceFilterMismatchCallback as _TestingHooksExistenceFilterMismatchCallback, ExistenceFilterMismatchInfo as _TestingHooksExistenceFilterMismatchInfo, cast as _cast, debugAssert as _debugAssert, isBase64Available as _isBase64Available, logWarn as _logWarn, validateIsNotUsedTogether as _validateIsNotUsedTogether, addDoc, aggregateFieldEqual, aggregateQuerySnapshotEqual, and, arrayRemove, arrayUnion, average, clearIndexedDbPersistence, collection, collectionGroup, connectFirestoreEmulator, count, deleteAllPersistentCacheIndexes, deleteDoc, deleteField, disableNetwork, disablePersistentCacheIndexAutoCreation, doc, documentId, enableIndexedDbPersistence, enableMultiTabIndexedDbPersistence, enableNetwork, enablePersistentCacheIndexAutoCreation, endAt, endBefore, ensureFirestoreConfigured, executeWrite, getAggregateFromServer, getCountFromServer, getDoc, getDocFromCache, getDocFromServer, getDocs, getDocsFromCache, getDocsFromServer, getFirestore, getPersistentCacheIndexManager, increment, initializeFirestore, limit, limitToLast, loadBundle, memoryEagerGarbageCollector, memoryLocalCache, memoryLruGarbageCollector, namedQuery, onSnapshot, onSnapshotsInSync, or, orderBy, persistentLocalCache, persistentMultipleTabManager, persistentSingleTabManager, query, queryEqual, refEqual, runTransaction, serverTimestamp, setDoc, setIndexConfiguration, setLogLevel, snapshotEqual, startAfter, startAt, sum, terminate, updateDoc, waitForPendingWrites, where, writeBatch };
+export { AbstractUserDataWriter, AddPrefixToKeys, AggregateField, AggregateFieldType, AggregateQuerySnapshot, AggregateSpec, AggregateSpecData, AggregateType, AuthTokenFactory, Bytes, CACHE_SIZE_UNLIMITED, ChildUpdateFields, CollectionReference, DocumentChange, DocumentChangeType, DocumentData, DocumentReference, DocumentSnapshot, EmulatorMockTokenOptions, ExperimentalLongPollingOptions, FieldPath, FieldValue, Firestore, FirestoreDataConverter, FirestoreError, FirestoreErrorCode, FirestoreLocalCache, FirestoreSettings, FirstPartyCredentialsSettings, GeoPoint, Index, IndexConfiguration, IndexField, ListenSource, LoadBundleTask, LoadBundleTaskProgress, LogLevelString as LogLevel, MemoryCacheSettings, MemoryEagerGarbageCollector, MemoryGarbageCollector, MemoryLocalCache, MemoryLruGarbageCollector, NestedUpdateFields, OrderByDirection, PartialWithFieldValue, PersistenceSettings, PersistentCacheIndexManager, PersistentCacheSettings, PersistentLocalCache, PersistentMultipleTabManager, PersistentSingleTabManager, PersistentSingleTabManagerSettings, PersistentTabManager, Primitive, PrivateSettings, Query, QueryCompositeFilterConstraint, QueryConstraint, QueryConstraintType, QueryDocumentSnapshot, QueryEndAtConstraint, QueryFieldFilterConstraint, QueryFilterConstraint, QueryLimitConstraint, QueryNonFilterConstraint, QueryOrderByConstraint, QuerySnapshot, QueryStartAtConstraint, SetOptions, SnapshotListenOptions, SnapshotMetadata, SnapshotOptions, TaskState, Timestamp$1 as Timestamp, Transaction, TransactionOptions, UnionToIntersection, Unsubscribe, UpdateData, WhereFilterOp, WithFieldValue, WriteBatch, AutoId as _AutoId, ByteString as _ByteString, DatabaseId as _DatabaseId, DocumentKey as _DocumentKey, EmptyAppCheckTokenProvider as _EmptyAppCheckTokenProvider, EmptyAuthCredentialsProvider as _EmptyAuthCredentialsProvider, FieldPath$1 as _FieldPath, ResourcePath as _ResourcePath, TestingHooks as _TestingHooks, ExistenceFilterMismatchCallback as _TestingHooksExistenceFilterMismatchCallback, ExistenceFilterMismatchInfo as _TestingHooksExistenceFilterMismatchInfo, cast as _cast, debugAssert as _debugAssert, isBase64Available as _isBase64Available, logWarn as _logWarn, validateIsNotUsedTogether as _validateIsNotUsedTogether, addDoc, aggregateFieldEqual, aggregateQuerySnapshotEqual, and, arrayRemove, arrayUnion, average, clearIndexedDbPersistence, collection, collectionGroup, connectFirestoreEmulator, count, deleteAllPersistentCacheIndexes, deleteDoc, deleteField, disableNetwork, disablePersistentCacheIndexAutoCreation, doc, documentId, enableIndexedDbPersistence, enableMultiTabIndexedDbPersistence, enableNetwork, enablePersistentCacheIndexAutoCreation, endAt, endBefore, ensureFirestoreConfigured, executeWrite, getAggregateFromServer, getCountFromServer, getDoc, getDocFromCache, getDocFromServer, getDocs, getDocsFromCache, getDocsFromServer, getFirestore, getPersistentCacheIndexManager, increment, initializeFirestore, limit, limitToLast, loadBundle, memoryEagerGarbageCollector, memoryLocalCache, memoryLruGarbageCollector, namedQuery, onSnapshot, onSnapshotsInSync, or, orderBy, persistentLocalCache, persistentMultipleTabManager, persistentSingleTabManager, query, queryEqual, refEqual, runTransaction, serverTimestamp, setDoc, setIndexConfiguration, setLogLevel, snapshotEqual, startAfter, startAt, sum, terminate, updateDoc, waitForPendingWrites, where, writeBatch };

package/dist/firestore/src/local/shared_client_state.d.ts

@@ -153,7 +153,7 @@ export declare class QueryTargetMetadata {
 }
 /**
  * Metadata state of a single client denoting the query targets it is actively
- * listening to.
+ * listening to the watch.
  */
 export interface ClientState {
     readonly activeTargetIds: TargetIdSet;

package/dist/firestore/test/integration/api/query.test.d.ts

@@ -14,4 +14,5 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-export {};
+import { DocumentChange, DocumentChangeType } from '../util/firebase_export';
+export declare function verifyDocumentChange<T>(change: DocumentChange<T>, id: string, oldIndex: number, newIndex: number, type: DocumentChangeType): void;

package/dist/firestore/test/integration/api/snasphot_listener_source.test.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export {};

package/dist/firestore/test/unit/specs/bundle_spec.test.d.ts

@@ -14,4 +14,23 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+import { Query } from '../../../src/core/query';
+import { DocumentKey } from '../../../src/model/document_key';
+import { JsonObject } from '../../../src/model/object_value';
+import { LimitType } from '../../../src/protos/firestore_bundle_proto';
+import { TestSnapshotVersion } from '../../util/helpers';
+interface TestBundleDocument {
+    key: DocumentKey;
+    readTime: TestSnapshotVersion;
+    createTime?: TestSnapshotVersion;
+    updateTime?: TestSnapshotVersion;
+    content?: JsonObject<unknown>;
+}
+interface TestBundledQuery {
+    name: string;
+    readTime: TestSnapshotVersion;
+    query: Query;
+    limitType?: LimitType;
+}
+export declare function bundleWithDocumentAndQuery(testDoc: TestBundleDocument, testQuery?: TestBundledQuery): string;
 export {};

package/dist/firestore/test/unit/specs/listen_source_spec.test.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export {};

package/dist/firestore/test/unit/specs/spec_builder.d.ts

@@ -108,13 +108,16 @@ export declare class SpecBuilder {
     runAsTest(name: string, tags: string[], usePersistence: boolean): Promise<void>;
     ensureManualLruGC(): this;
     withMaxConcurrentLimboResolutions(value?: number): this;
+    private addUserListenStep;
     userListens(query: Query, resume?: ResumeSpec): this;
+    userListensToCache(query: Query, resume?: ResumeSpec): this;
     /**
      * Registers a previously active target with the test expectations after a
      * stream disconnect.
      */
     restoreListen(query: Query, resumeToken: string, expectedCount?: number): this;
-    userUnlistens(query: Query): this;
+    userUnlistens(query: Query, shouldRemoveWatchTarget?: boolean): this;
+    userUnlistensToCache(query: Query): this;
     userSets(key: string, value: JsonObject<unknown>): this;
     userPatches(key: string, value: JsonObject<unknown>): this;
     userDeletes(key: string): this;
@@ -218,10 +221,16 @@ export declare class SpecBuilder {
         metadata?: Document[];
         errorCode?: Code;
     }): this;
+    private registerQuery;
     /** Registers a query that is active in another tab. */
     expectListen(query: Query, resume?: ResumeSpec): this;
+    /** Registers a query that is listening to cache and active in another tab. */
+    expectListenToCache(query: Query, resume?: ResumeSpec): this;
+    removeQuery(query: Query, shouldRemoveWatchTarget?: boolean): this;
     /** Removes a query that is no longer active in any tab. */
     expectUnlisten(query: Query): this;
+    /** Removes a query that is listening to cache and no longer active in any tab. */
+    expectUnlistenToCache(query: Query): this;
     /**
      * Verifies the total number of requests sent to the write backend since test
      * initialization.

package/dist/firestore/test/unit/specs/spec_test_runner.d.ts

@@ -15,6 +15,7 @@
  * limitations under the License.
  */
 import { IndexConfiguration } from '../../../src/api/index_configuration';
+import { ListenOptions } from '../../../src/core/event_manager';
 import { Query } from '../../../src/core/query';
 import { TargetId } from '../../../src/core/types';
 import { FieldIndex } from '../../../src/model/field_index';
@@ -152,6 +153,7 @@ export interface SpecStep {
 export interface SpecUserListen {
     targetId: TargetId;
     query: string | SpecQuery;
+    options?: ListenOptions;
 }
 /** [<target-id>, <query-path>] */
 export declare type SpecUserUnlisten = [TargetId, string | SpecQuery];