New way to config Firestore SDK Cache. (#7015)

* New way to config Firestore SDK Cache.

* fixups

* Fix some test failures

* Fixing dts file

* Add public comments

* API report

* Create brown-beers-tease.md

* warning messages and more tests

* Addressing comments

* Update API reports

* Fix provider test failure for node w/o indexeddb

* Fix node memory test

* rename cache to localCache

* Update API reports

* Tech writer review

* yarn docgen

* auth change

* Update API reports

* docgen devsite

* Fix changeset

* Another auth change

* more devsite fix

* Update API reports

* Rename indexeddb to persistent

---------

Co-authored-by: wu-hui <[email protected]>

Author: wu-hui

.changeset/brown-beers-tease.md

@@ -0,0 +1,5 @@
+---
+"@firebase/firestore": minor
+---
+
+Introduces a new way to config Firestore SDK Cache.

common/api-review/firestore.api.md

@@ -163,10 +163,10 @@ export class DocumentSnapshot<T = DocumentData> {
 
 export { EmulatorMockTokenOptions }
 
-// @public
+// @public @deprecated
 export function enableIndexedDbPersistence(firestore: Firestore, persistenceSettings?: PersistenceSettings): Promise<void>;
 
-// @public
+// @public @deprecated
 export function enableMultiTabIndexedDbPersistence(firestore: Firestore): Promise<void>;
 
 // @public
@@ -219,13 +219,17 @@ export class FirestoreError extends FirebaseError {
 // @public
 export type FirestoreErrorCode = 'cancelled' | 'unknown' | 'invalid-argument' | 'deadline-exceeded' | 'not-found' | 'already-exists' | 'permission-denied' | 'resource-exhausted' | 'failed-precondition' | 'aborted' | 'out-of-range' | 'unimplemented' | 'internal' | 'unavailable' | 'data-loss' | 'unauthenticated';
 
+// @public
+export type FirestoreLocalCache = MemoryLocalCache | PersistentLocalCache;
+
 // @public
 export interface FirestoreSettings {
     cacheSizeBytes?: number;
     experimentalAutoDetectLongPolling?: boolean;
     experimentalForceLongPolling?: boolean;
     host?: string;
     ignoreUndefinedProperties?: boolean;
+    localCache?: FirestoreLocalCache;
     ssl?: boolean;
 }
 
@@ -327,6 +331,15 @@ export interface LoadBundleTaskProgress {
 
 export { LogLevel }
 
+// @public
+export interface MemoryLocalCache {
+    // (undocumented)
+    kind: 'memory';
+}
+
+// @public
+export function memoryLocalCache(): MemoryLocalCache;
+
 // @public
 export function namedQuery(firestore: Firestore, name: string): Promise<Query | null>;
 
@@ -404,6 +417,47 @@ export interface PersistenceSettings {
     forceOwnership?: boolean;
 }
 
+// @public
+export interface PersistentCacheSettings {
+    cacheSizeBytes?: number;
+    tabManager?: PersistentTabManager;
+}
+
+// @public
+export interface PersistentLocalCache {
+    // (undocumented)
+    kind: 'persistent';
+}
+
+// @public
+export function persistentLocalCache(settings?: PersistentCacheSettings): PersistentLocalCache;
+
+// @public
+export interface PersistentMultipleTabManager {
+    // (undocumented)
+    kind: 'PersistentMultipleTab';
+}
+
+// @public
+export function persistentMultipleTabManager(): PersistentMultipleTabManager;
+
+// @public
+export interface PersistentSingleTabManager {
+    // (undocumented)
+    kind: 'persistentSingleTab';
+}
+
+// @public
+export function persistentSingleTabManager(settings: PersistentSingleTabManagerSettings | undefined): PersistentSingleTabManager;
+
+// @public
+export interface PersistentSingleTabManagerSettings {
+    forceOwnership?: boolean;
+}
+
+// @public
+export type PersistentTabManager = PersistentSingleTabManager | PersistentMultipleTabManager;
+
 // @public
 export type Primitive = string | number | boolean | undefined | null;
 

docs-devsite/firestore_.firestoresettings.md

@@ -22,15 +22,18 @@ export declare interface FirestoreSettings
 
 |  Property | Type | Description |
 |  --- | --- | --- |
-|  [cacheSizeBytes](./firestore_.firestoresettings.md#firestoresettingscachesizebytes) | number | An approximate cache size threshold for the on-disk data. If the cache grows beyond this size, Firestore will start removing data that hasn't been recently used. The size is not a guarantee that the cache will stay below that size, only that if the cache exceeds the given size, cleanup will be attempted.<!-- -->The default value is 40 MB. The threshold must be set to at least 1 MB, and can be set to <code>CACHE_SIZE_UNLIMITED</code> to disable garbage collection. |
+|  [cacheSizeBytes](./firestore_.firestoresettings.md#firestoresettingscachesizebytes) | number | NOTE: This field will be deprecated in a future major release. Use <code>cache</code> field instead to specify cache size, and other cache configurations.<!-- -->An approximate cache size threshold for the on-disk data. If the cache grows beyond this size, Firestore will start removing data that hasn't been recently used. The size is not a guarantee that the cache will stay below that size, only that if the cache exceeds the given size, cleanup will be attempted.<!-- -->The default value is 40 MB. The threshold must be set to at least 1 MB, and can be set to <code>CACHE_SIZE_UNLIMITED</code> to disable garbage collection. |
 |  [experimentalAutoDetectLongPolling](./firestore_.firestoresettings.md#firestoresettingsexperimentalautodetectlongpolling) | boolean | Configures the SDK's underlying transport (WebChannel) to automatically detect if long-polling should be used. This is very similar to <code>experimentalForceLongPolling</code>, but only uses long-polling if required.<!-- -->This setting will likely be enabled by default in future releases and cannot be combined with <code>experimentalForceLongPolling</code>. |
 |  [experimentalForceLongPolling](./firestore_.firestoresettings.md#firestoresettingsexperimentalforcelongpolling) | boolean | Forces the SDK’s underlying network transport (WebChannel) to use long-polling. Each response from the backend will be closed immediately after the backend sends data (by default responses are kept open in case the backend has more data to send). This avoids incompatibility issues with certain proxies, antivirus software, etc. that incorrectly buffer traffic indefinitely. Use of this option will cause some performance degradation though.<!-- -->This setting cannot be used with <code>experimentalAutoDetectLongPolling</code> and may be removed in a future release. If you find yourself using it to work around a specific network reliability issue, please tell us about it in https://github.com/firebase/firebase-js-sdk/issues/1674. |
 |  [host](./firestore_.firestoresettings.md#firestoresettingshost) | string | The hostname to connect to. |
 |  [ignoreUndefinedProperties](./firestore_.firestoresettings.md#firestoresettingsignoreundefinedproperties) | boolean | Whether to skip nested properties that are set to <code>undefined</code> during object serialization. If set to <code>true</code>, these properties are skipped and not written to Firestore. If set to <code>false</code> or omitted, the SDK throws an exception when it encounters properties of type <code>undefined</code>. |
+|  [localCache](./firestore_.firestoresettings.md#firestoresettingslocalcache) | [FirestoreLocalCache](./firestore_.md#firestorelocalcache) | Specifies the cache used by the SDK. Availabe options are <code>MemoryLocalCache</code> and <code>IndexedDbLocalCache</code>, each with different configuration options.<!-- -->When unspecified, <code>MemoryLocalCache</code> will be used by default.<!-- -->NOTE: setting this field and <code>cacheSizeBytes</code> at the same time will throw exception during SDK initialization. Instead, using the configuration in the <code>FirestoreLocalCache</code> object to specify the cache size. |
 |  [ssl](./firestore_.firestoresettings.md#firestoresettingsssl) | boolean | Whether to use SSL when connecting. |
 
 ## FirestoreSettings.cacheSizeBytes
 
+NOTE: This field will be deprecated in a future major release. Use `cache` field instead to specify cache size, and other cache configurations.
+
 An approximate cache size threshold for the on-disk data. If the cache grows beyond this size, Firestore will start removing data that hasn't been recently used. The size is not a guarantee that the cache will stay below that size, only that if the cache exceeds the given size, cleanup will be attempted.
 
 The default value is 40 MB. The threshold must be set to at least 1 MB, and can be set to `CACHE_SIZE_UNLIMITED` to disable garbage collection.
@@ -85,6 +88,20 @@ Whether to skip nested properties that are set to `undefined` during object seri
 ignoreUndefinedProperties?: boolean;
 ```
 
+## FirestoreSettings.localCache
+
+Specifies the cache used by the SDK. Availabe options are `MemoryLocalCache` and `IndexedDbLocalCache`<!-- -->, each with different configuration options.
+
+When unspecified, `MemoryLocalCache` will be used by default.
+
+NOTE: setting this field and `cacheSizeBytes` at the same time will throw exception during SDK initialization. Instead, using the configuration in the `FirestoreLocalCache` object to specify the cache size.
+
+<b>Signature:</b>
+
+```typescript
+localCache?: FirestoreLocalCache;
+```
+
 ## FirestoreSettings.ssl
 
 Whether to use SSL when connecting.