@firebase/firestore 3.11.0 → 3.12.0-20230511201449

package/dist/lite/packages/firestore/src/api/long_polling_options.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @license
+ * Copyright 2023 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.
+ */
+/**
+ * Options that configure the SDK’s underlying network transport (WebChannel)
+ * when long-polling is used.
+ *
+ * Note: This interface is "experimental" and is subject to change.
+ *
+ * See `FirestoreSettings.experimentalAutoDetectLongPolling`,
+ * `FirestoreSettings.experimentalForceLongPolling`, and
+ * `FirestoreSettings.experimentalLongPollingOptions`.
+ */
+export interface ExperimentalLongPollingOptions {
+    /**
+     * The desired maximum timeout interval, in seconds, to complete a
+     * long-polling GET response. Valid values are between 5 and 30, inclusive.
+     * Floating point values are allowed and will be rounded to the nearest
+     * millisecond.
+     *
+     * By default, when long-polling is used the "hanging GET" request sent by
+     * the client times out after 30 seconds. To request a different timeout
+     * from the server, set this setting with the desired timeout.
+     *
+     * Changing the default timeout may be useful, for example, if the buffering
+     * proxy that necessitated enabling long-polling in the first place has a
+     * shorter timeout for hanging GET requests, in which case setting the
+     * long-polling timeout to a shorter value, such as 25 seconds, may fix
+     * prematurely-closed hanging GET requests.
+     * For example, see https://github.com/firebase/firebase-js-sdk/issues/6987.
+     */
+    timeoutSeconds?: number;
+}
+/**
+ * Compares two `ExperimentalLongPollingOptions` objects for equality.
+ */
+export declare function longPollingOptionsEqual(options1: ExperimentalLongPollingOptions, options2: ExperimentalLongPollingOptions): boolean;
+/**
+ * Creates and returns a new `ExperimentalLongPollingOptions` with the same
+ * option values as the given instance.
+ */
+export declare function cloneLongPollingOptions(options: ExperimentalLongPollingOptions): ExperimentalLongPollingOptions;

package/dist/lite/packages/firestore/src/api/settings.d.ts

@@ -16,6 +16,7 @@
  */
 import { FirestoreSettings as LiteSettings } from '../lite-api/settings';
 import { FirestoreLocalCache } from './cache_config';
+import { ExperimentalLongPollingOptions } from './long_polling_options';
 export { DEFAULT_HOST } from '../lite-api/settings';
 /**
  * Settings that can be passed to `enableIndexedDbPersistence()` to configure
@@ -80,8 +81,21 @@ export interface FirestoreSettings extends LiteSettings {
      * detect if long-polling should be used. This is very similar to
      * `experimentalForceLongPolling`, but only uses long-polling if required.
      *
-     * This setting will likely be enabled by default in future releases and
-     * cannot be combined with `experimentalForceLongPolling`.
+     * After having had a default value of `false` since its inception in 2019,
+     * the default value of this setting was changed in mid-2023 to `true`. That
+     * is, auto-detection of long polling is now enabled by default. To disable
+     * it, set this setting to `false`, and please open a GitHub issue to share
+     * the problems that motivated you disabling long-polling auto-detection.
      */
     experimentalAutoDetectLongPolling?: boolean;
+    /**
+     * Options that configure the SDK’s underlying network transport (WebChannel)
+     * when long-polling is used.
+     *
+     * These options are only used if `experimentalForceLongPolling` is true or if
+     * `experimentalAutoDetectLongPolling` is true and the auto-detection
+     * determined that long-polling was needed. Otherwise, these options have no
+     * effect.
+     */
+    experimentalLongPollingOptions?: ExperimentalLongPollingOptions;
 }

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

@@ -21,6 +21,7 @@ export { documentId, FieldPath } from './api/field_path';
 export { clearIndexedDbPersistence, connectFirestoreEmulator, disableNetwork, EmulatorMockTokenOptions, enableIndexedDbPersistence, enableMultiTabIndexedDbPersistence, enableNetwork, ensureFirestoreConfigured, Firestore, getFirestore, initializeFirestore, loadBundle, namedQuery, terminate, waitForPendingWrites } from './api/database';
 export { LoadBundleTask, LoadBundleTaskProgress, TaskState } from './api/bundle';
 export { FirestoreSettings, PersistenceSettings } from './api/settings';
+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';

package/dist/lite/packages/firestore/src/core/database_info.d.ts

@@ -1,4 +1,5 @@
 import { FirebaseApp } from '@firebase/app';
+import { ExperimentalLongPollingOptions } from '../api/long_polling_options';
 /**
  * @license
  * Copyright 2017 Google LLC
@@ -23,6 +24,7 @@ export declare class DatabaseInfo {
     readonly ssl: boolean;
     readonly forceLongPolling: boolean;
     readonly autoDetectLongPolling: boolean;
+    readonly longPollingOptions: ExperimentalLongPollingOptions;
     readonly useFetchStreams: boolean;
     /**
      * Constructs a DatabaseInfo using the provided host, databaseId and
@@ -38,10 +40,11 @@ export declare class DatabaseInfo {
      * when using WebChannel as the network transport.
      * @param autoDetectLongPolling - Whether to use the detectBufferingProxy
      * option when using WebChannel as the network transport.
+     * @param longPollingOptions Options that configure long-polling.
      * @param useFetchStreams Whether to use the Fetch API instead of
      * XMLHTTPRequest
      */
-    constructor(databaseId: DatabaseId, appId: string, persistenceKey: string, host: string, ssl: boolean, forceLongPolling: boolean, autoDetectLongPolling: boolean, useFetchStreams: boolean);
+    constructor(databaseId: DatabaseId, appId: string, persistenceKey: string, host: string, ssl: boolean, forceLongPolling: boolean, autoDetectLongPolling: boolean, longPollingOptions: ExperimentalLongPollingOptions, useFetchStreams: boolean);
 }
 /** The default database name for a project. */
 export declare const DEFAULT_DATABASE_NAME = "(default)";

package/dist/lite/packages/firestore/src/lite-api/settings.d.ts

@@ -16,6 +16,7 @@
  */
 import { FirestoreLocalCache } from '../api/cache_config';
 import { CredentialsSettings } from '../api/credentials';
+import { ExperimentalLongPollingOptions } from '../api/long_polling_options';
 export declare const DEFAULT_HOST = "firestore.googleapis.com";
 export declare const DEFAULT_SSL = true;
 /**
@@ -41,6 +42,7 @@ export interface PrivateSettings extends FirestoreSettings {
     cacheSizeBytes?: number;
     experimentalForceLongPolling?: boolean;
     experimentalAutoDetectLongPolling?: boolean;
+    experimentalLongPollingOptions?: ExperimentalLongPollingOptions;
     useFetchStreams?: boolean;
     localCache?: FirestoreLocalCache;
 }
@@ -57,6 +59,7 @@ export declare class FirestoreSettingsImpl {
     readonly cacheSizeBytes: number;
     readonly experimentalForceLongPolling: boolean;
     readonly experimentalAutoDetectLongPolling: boolean;
+    readonly experimentalLongPollingOptions: ExperimentalLongPollingOptions;
     readonly ignoreUndefinedProperties: boolean;
     readonly useFetchStreams: boolean;
     readonly cache?: FirestoreLocalCache;

package/dist/lite/packages/firestore/src/platform/browser/webchannel_connection.d.ts

@@ -23,6 +23,7 @@ export declare class WebChannelConnection extends RestConnection {
     private readonly forceLongPolling;
     private readonly autoDetectLongPolling;
     private readonly useFetchStreams;
+    private readonly longPollingOptions;
     constructor(info: DatabaseInfo);
     protected performRPCRequest<Req, Resp>(rpcName: string, url: string, headers: StringMap, body: Req): Promise<Resp>;
     openStream<Req, Resp>(rpcName: string, authToken: Token | null, appCheckToken: Token | null): Stream<Req, Resp>;

package/dist/lite/packages/firestore/test/unit/api/long_polling_options.test.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @license
+ * Copyright 2023 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/lite/private.d.ts

@@ -666,6 +666,7 @@ declare class DatabaseInfo {
     readonly ssl: boolean;
     readonly forceLongPolling: boolean;
     readonly autoDetectLongPolling: boolean;
+    readonly longPollingOptions: ExperimentalLongPollingOptions;
     readonly useFetchStreams: boolean;
     /**
      * Constructs a DatabaseInfo using the provided host, databaseId and
@@ -681,10 +682,11 @@ declare class DatabaseInfo {
      * when using WebChannel as the network transport.
      * @param autoDetectLongPolling - Whether to use the detectBufferingProxy
      * option when using WebChannel as the network transport.
+     * @param longPollingOptions Options that configure long-polling.
      * @param useFetchStreams Whether to use the Fetch API instead of
      * XMLHTTPRequest
      */
-    constructor(databaseId: DatabaseId, appId: string, persistenceKey: string, host: string, ssl: boolean, forceLongPolling: boolean, autoDetectLongPolling: boolean, useFetchStreams: boolean);
+    constructor(databaseId: DatabaseId, appId: string, persistenceKey: string, host: string, ssl: boolean, forceLongPolling: boolean, autoDetectLongPolling: boolean, longPollingOptions: ExperimentalLongPollingOptions, useFetchStreams: boolean);
 }
 
 /**
@@ -1184,6 +1186,53 @@ declare interface EventManager {
     onUnlisten?: (query: Query_2) => Promise<void>;
 }
 
+/**
+ * @license
+ * Copyright 2023 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.
+ */
+/**
+ * Options that configure the SDK’s underlying network transport (WebChannel)
+ * when long-polling is used.
+ *
+ * Note: This interface is "experimental" and is subject to change.
+ *
+ * See `FirestoreSettings.experimentalAutoDetectLongPolling`,
+ * `FirestoreSettings.experimentalForceLongPolling`, and
+ * `FirestoreSettings.experimentalLongPollingOptions`.
+ */
+declare interface ExperimentalLongPollingOptions {
+    /**
+     * The desired maximum timeout interval, in seconds, to complete a
+     * long-polling GET response. Valid values are between 5 and 30, inclusive.
+     * Floating point values are allowed and will be rounded to the nearest
+     * millisecond.
+     *
+     * By default, when long-polling is used the "hanging GET" request sent by
+     * the client times out after 30 seconds. To request a different timeout
+     * from the server, set this setting with the desired timeout.
+     *
+     * Changing the default timeout may be useful, for example, if the buffering
+     * proxy that necessitated enabling long-polling in the first place has a
+     * shorter timeout for hanging GET requests, in which case setting the
+     * long-polling timeout to a shorter value, such as 25 seconds, may fix
+     * prematurely-closed hanging GET requests.
+     * For example, see https://github.com/firebase/firebase-js-sdk/issues/6987.
+     */
+    timeoutSeconds?: number;
+}
+
 declare class FieldFilter extends Filter {
     readonly field: FieldPath_2;
     readonly op: Operator;
@@ -1548,6 +1597,7 @@ declare class FirestoreSettingsImpl {
     readonly cacheSizeBytes: number;
     readonly experimentalForceLongPolling: boolean;
     readonly experimentalAutoDetectLongPolling: boolean;
+    readonly experimentalLongPollingOptions: ExperimentalLongPollingOptions;
     readonly ignoreUndefinedProperties: boolean;
     readonly useFetchStreams: boolean;
     readonly cache?: FirestoreLocalCache;
@@ -3488,6 +3538,7 @@ declare interface PrivateSettings extends Settings {
     cacheSizeBytes?: number;
     experimentalForceLongPolling?: boolean;
     experimentalAutoDetectLongPolling?: boolean;
+    experimentalLongPollingOptions?: ExperimentalLongPollingOptions;
     useFetchStreams?: boolean;
     localCache?: FirestoreLocalCache;
 }