New way to config Firestore SDK Cache.

.changeset/brown-beers-tease.md

@@ -0,0 +1,6 @@
+---
+"@firebase/firestore": minor
+"firebase-repo-scripts-prune-dts": minor
+---
+
+Introduces a new way to config Firestore SDK Cache.

common/api-review/firestore.api.md

@@ -216,8 +216,12 @@ 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 | IndexedDbLocalCache;
+
 // @public
 export interface FirestoreSettings {
+    cache?: FirestoreLocalCache;
     cacheSizeBytes?: number;
     experimentalAutoDetectLongPolling?: boolean;
     experimentalForceLongPolling?: boolean;
@@ -285,6 +289,47 @@ export interface IndexConfiguration {
     readonly indexes?: Index[];
 }
 
+// @public
+export interface IndexedDbLocalCache {
+    // (undocumented)
+    kind: 'indexeddb';
+}
+
+// @public
+export function indexedDbLocalCache(settings?: IndexedDbSettings): IndexedDbLocalCache;
+
+// @public
+export interface IndexedDbMultipleTabManager {
+    // (undocumented)
+    kind: 'IndexedDbMultipleTab';
+}
+
+// @public
+export function indexedDbMultipleTabManager(): IndexedDbMultipleTabManager;
+
+// @public
+export interface IndexedDbSettings {
+    cacheSizeBytes?: number;
+    tabManager?: IndexedDbTabManager;
+}
+
+// @public
+export interface IndexedDbSingleTabManager {
+    // (undocumented)
+    kind: 'indexedDbSingleTab';
+}
+
+// @public
+export function indexedDbSingleTabManager(settings: IndexedDbSingleTabManagerSettings | undefined): IndexedDbSingleTabManager;
+
+// @public
+export interface IndexedDbSingleTabManagerSettings {
+    forceOwnership?: boolean;
+}
+
+// @public
+export type IndexedDbTabManager = IndexedDbSingleTabManager | IndexedDbMultipleTabManager;
+
 // @beta
 export interface IndexField {
     // (undocumented)
@@ -324,6 +369,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>;
 

packages/firestore/src/api.ts

@@ -30,13 +30,15 @@ export {
 
 export {
   FirestoreLocalCache,
-  MemoryLocalCache,
   IndexedDbLocalCache,
   IndexedDbMultipleTabManager,
   indexedDbLocalCache,
   indexedDbMultipleTabManager,
+  IndexedDbSettings,
   indexedDbSingleTabManager,
   IndexedDbSingleTabManager,
+  IndexedDbSingleTabManagerSettings,
+  MemoryLocalCache,
   memoryLocalCache,
   IndexedDbTabManager
 } from './api/cache_config';

packages/firestore/src/api/cache_config.ts

@@ -23,86 +23,185 @@ import {
   OnlineComponentProvider
 } from '../core/component_provider';
 
-export interface MemoryLocalCache {
+/* eslint @typescript-eslint/consistent-type-definitions: ["error", "type"] */
+/**
+ * Provides a in-memory cache to the SDK. This is the default cache unless explicitly
+ * specified otherwise.
+ *
+ * To use, create an instance using the factory function `memoryLocalCache()`, then
+ * set the instance to `FirestoreSettings.cache` and call `initializeFirestore` using
+ * the settings object.
+ */
+export type MemoryLocalCache = {
   kind: 'memory';
+  /**
+   * @internal
+   */
   _onlineComponentProvider: OnlineComponentProvider;
+  /**
+   * @internal
+   */
   _offlineComponentProvider: MemoryOfflineComponentProvider;
-}
+};
 
 class MemoryLocalCacheImpl implements MemoryLocalCache {
   kind: 'memory' = 'memory';
+  /**
+   * @internal
+   */
   _onlineComponentProvider: OnlineComponentProvider;
+  /**
+   * @internal
+   */
   _offlineComponentProvider: MemoryOfflineComponentProvider;
 
   constructor() {
     this._onlineComponentProvider = new OnlineComponentProvider();
     this._offlineComponentProvider = new MemoryOfflineComponentProvider();
   }
+
+  toJSON(): {} {
+    return { kind: this.kind };
+  }
 }
 
-export interface IndexedDbLocalCache {
+/**
+ * Provides a cache backed by IndexedDb to the SDK.
+ *
+ * To use, create an instance using the factory function `indexedDbLocalCache()`, then
+ * set the instance to `FirestoreSettings.cache` and call `initializeFirestore` using
+ * the settings object.
+ */
+export type IndexedDbLocalCache = {
   kind: 'indexeddb';
+  /**
+   * @internal
+   */
   _onlineComponentProvider: OnlineComponentProvider;
+  /**
+   * @internal
+   */
   _offlineComponentProvider: OfflineComponentProvider;
-}
+};
 
 class IndexedDbLocalCacheImpl implements IndexedDbLocalCache {
   kind: 'indexeddb' = 'indexeddb';
+  /**
+   * @internal
+   */
   _onlineComponentProvider: OnlineComponentProvider;
+  /**
+   * @internal
+   */
   _offlineComponentProvider: OfflineComponentProvider;
 
   constructor(settings: IndexedDbSettings | undefined) {
     let tabManager: IndexedDbTabManager;
     if (settings?.tabManager) {
-      settings.tabManager.initialize(settings);
+      settings.tabManager._initialize(settings);
       tabManager = settings.tabManager;
     } else {
       tabManager = indexedDbSingleTabManager(undefined);
-      tabManager.initialize(settings);
+      tabManager._initialize(settings);
     }
     this._onlineComponentProvider = tabManager._onlineComponentProvider!;
     this._offlineComponentProvider = tabManager._offlineComponentProvider!;
   }
+
+  toJSON(): {} {
+    return { kind: this.kind };
+  }
 }
 
+/**
+ * Union type from all supported SDK cache layer.
+ */
 export type FirestoreLocalCache = MemoryLocalCache | IndexedDbLocalCache;
 
-// Factory function
+/**
+ * Creates an instance of `MemoryLocalCache`. The instance can be set to
+ * `FirestoreSettings.cache` to tell the SDK what cache layer to use.
+ */
 export function memoryLocalCache(): MemoryLocalCache {
   return new MemoryLocalCacheImpl();
 }
 
-export interface IndexedDbSettings {
+/**
+ * An settings object to configure an `IndexedDbLocalCache` instance.
+ */
+export type IndexedDbSettings = {
+  /**
+   * 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.
+   */
   cacheSizeBytes?: number;
-  // default to singleTabManager({forceOwnership: false})
+
+  /**
+   * Specifies how multiple tabs/windows will be managed by the SDK.
+   */
   tabManager?: IndexedDbTabManager;
-}
+};
 
-// Factory function
+/**
+ * Creates an instance of `IndexedDbLocalCache`. The instance can be set to
+ * `FirestoreSettings.cache` to tell the SDK what cache layer to use.
+ */
 export function indexedDbLocalCache(
   settings?: IndexedDbSettings
 ): IndexedDbLocalCache {
   return new IndexedDbLocalCacheImpl(settings);
 }
 
-export interface IndexedDbSingleTabManager {
+/**
+ * A tab manager supportting only one tab, no synchronization will be
+ * performed across tabs.
+ */
+export type IndexedDbSingleTabManager = {
   kind: 'indexedDbSingleTab';
-  initialize: (
+  /**
+   * @internal
+   */
+  _initialize: (
     settings: Omit<IndexedDbSettings, 'tabManager'> | undefined
   ) => void;
+  /**
+   * @internal
+   */
   _onlineComponentProvider?: OnlineComponentProvider;
+  /**
+   * @internal
+   */
   _offlineComponentProvider?: OfflineComponentProvider;
-}
+};
 
 class SingleTabManagerImpl implements IndexedDbSingleTabManager {
   kind: 'indexedDbSingleTab' = 'indexedDbSingleTab';
 
+  /**
+   * @internal
+   */
   _onlineComponentProvider?: OnlineComponentProvider;
+  /**
+   * @internal
+   */
   _offlineComponentProvider?: OfflineComponentProvider;
 
   constructor(private forceOwnership?: boolean) {}
 
-  initialize(
+  toJSON(): {} {
+    return { kind: this.kind };
+  }
+
+  /**
+   * @internal
+   */
+  _initialize(
     settings: Omit<IndexedDbSettings, 'tabManager'> | undefined
   ): void {
     this._onlineComponentProvider = new OnlineComponentProvider();
@@ -114,20 +213,47 @@ class SingleTabManagerImpl implements IndexedDbSingleTabManager {
   }
 }
 
-export interface IndexedDbMultipleTabManager {
+/**
+ * A tab manager supportting multiple tabs. SDK will synchronize queries and
+ * mutations done across all tabs using the SDK.
+ */
+export type IndexedDbMultipleTabManager = {
   kind: 'IndexedDbMultipleTab';
-  initialize: (settings: Omit<IndexedDbSettings, 'tabManager'>) => void;
+  /**
+   * @internal
+   */
+  _initialize: (settings: Omit<IndexedDbSettings, 'tabManager'>) => void;
+  /**
+   * @internal
+   */
   _onlineComponentProvider?: OnlineComponentProvider;
+  /**
+   * @internal
+   */
+
   _offlineComponentProvider?: OfflineComponentProvider;
-}
+};
 
 class MultiTabManagerImpl implements IndexedDbMultipleTabManager {
   kind: 'IndexedDbMultipleTab' = 'IndexedDbMultipleTab';
 
+  /**
+   * @internal
+   */
   _onlineComponentProvider?: OnlineComponentProvider;
+  /**
+   * @internal
+   */
   _offlineComponentProvider?: OfflineComponentProvider;
 
-  initialize(
+  toJSON(): {} {
+    return { kind: this.kind };
+  }
+
+  /**
+   * @internal
+   */
+  _initialize(
     settings: Omit<IndexedDbSettings, 'tabManager'> | undefined
   ): void {
     this._onlineComponentProvider = new OnlineComponentProvider();
@@ -138,15 +264,39 @@ class MultiTabManagerImpl implements IndexedDbMultipleTabManager {
   }
 }
 
+/**
+ * A union of all avaialbe tab managers.
+ */
 export type IndexedDbTabManager =
   | IndexedDbSingleTabManager
   | IndexedDbMultipleTabManager;
 
+/**
+ * Type to configure an `IndexedDbSingleTabManager` instace.
+ */
+export type IndexedDbSingleTabManagerSettings = {
+  /**
+   * Whether to force enable indexeddb cache for the client. This cannot be used
+   * with multi-tab synchronization and is primarily intended for use with Web
+   * Workers. Setting this to `true` will enable indexeddb, but cause other
+   * tabs using indexeddb cache to fail.
+   */
+  forceOwnership?: boolean;
+};
+/**
+ * Creates an instance of `IndexedDbSingleTabManager`.
+ *
+ * @param settings Configures the created tab manager.
+ */
 export function indexedDbSingleTabManager(
-  settings: { forceOwnership?: boolean } | undefined
+  settings: IndexedDbSingleTabManagerSettings | undefined
 ): IndexedDbSingleTabManager {
   return new SingleTabManagerImpl(settings?.forceOwnership);
 }
+
+/**
+ * Creates an instance of `IndexedDbMultipleTabManager`.
+ */
 export function indexedDbMultipleTabManager(): IndexedDbMultipleTabManager {
   return new MultiTabManagerImpl();
 }