Add useFirestoreEmulator

Author: schmidt-sebastian

common/api-review/firestore-exp.api.md

@@ -521,6 +521,9 @@ export function updateDoc(reference: DocumentReference<unknown>, data: UpdateDat
 // @public
 export function updateDoc(reference: DocumentReference<unknown>, field: string | FieldPath, value: unknown, ...moreFieldsAndValues: unknown[]): Promise<void>;
 
+// @public
+export function useFirestoreEmulator(firestore: FirebaseFirestore_2, host: string, port: number): void;
+
 // @public
 export function waitForPendingWrites(firestore: FirebaseFirestore): Promise<void>;
 

common/api-review/firestore-lite.api.md

@@ -427,6 +427,9 @@ export function updateDoc(reference: DocumentReference<unknown>, data: UpdateDat
 // @public
 export function updateDoc(reference: DocumentReference<unknown>, field: string | FieldPath, value: unknown, ...moreFieldsAndValues: unknown[]): Promise<void>;
 
+// @public
+export function useFirestoreEmulator(firestore: FirebaseFirestore, host: string, port: number): void;
+
 // @public
 export function where(fieldPath: string | FieldPath, opStr: WhereFilterOp, value: unknown): QueryConstraint;
 

packages/firestore/exp/index.ts

@@ -33,7 +33,8 @@ export {
   enableNetwork,
   terminate,
   Settings,
-  PersistenceSettings
+  PersistenceSettings,
+  useFirestoreEmulator
 } from './src/api/database';
 
 export {

packages/firestore/exp/src/api/database.ts

@@ -54,6 +54,8 @@ import {
 } from '../../../src/local/indexeddb_persistence';
 import { cast } from '../../../src/util/input_validation';
 
+export { useFirestoreEmulator } from '../../../lite/src/api/database';
+
 /** DOMException error code constants. */
 const DOM_EXCEPTION_INVALID_STATE = 11;
 const DOM_EXCEPTION_ABORTED = 20;

packages/firestore/lite/index.ts

@@ -24,7 +24,8 @@ export {
   FirebaseFirestore,
   initializeFirestore,
   getFirestore,
-  terminate
+  terminate,
+  useFirestoreEmulator
 } from './src/api/database';
 
 export {

packages/firestore/lite/src/api/database.ts

@@ -39,6 +39,7 @@ import {
   cast,
   validateIsNotUsedTogether
 } from '../../../src/util/input_validation';
+import { logWarn } from '../../../src/util/log';
 
 declare module '@firebase/component' {
   interface NameServiceMapping {
@@ -300,6 +301,38 @@ export function getFirestore(app: FirebaseApp): FirebaseFirestore {
   ).getImmediate() as FirebaseFirestore;
 }
 
+/**
+ * Modify this instance to communicate with the Cloud Firestore emulator.
+ *
+ * Note: This must be called before this instance has been used to do any
+ * operations.
+ *
+ * @param firestore - The Firestore instance to configure to connect to the
+ * emulator.
+ * @param host - the emulator host (ex: localhost).
+ * @param port - the emulator port (ex: 9000).
+ */
+export function useFirestoreEmulator(
+  firestore: FirebaseFirestore,
+  host: string,
+  port: number
+): void {
+  firestore = cast(firestore, FirebaseFirestore);
+
+  if (firestore._getSettings().host !== DEFAULT_HOST) {
+    logWarn(
+      'Host has been set in both settings() and useEmulator(), emulator host ' +
+        'will be used'
+    );
+  }
+
+  firestore._setSettings({
+    ...firestore._getSettings(),
+    host: `${host}:${port}`,
+    ssl: false
+  });
+}
+
 /**
  * Terminates the provided Firestore instance.
  *
@@ -316,6 +349,7 @@ export function getFirestore(app: FirebaseApp): FirebaseFirestore {
  * its resources or in combination with {@link clearIndexedDbPersistence} to
  * ensure that all local state is destroyed between test runs.
  *
+ * @param firestore - The Firestore instance to terminate.
  * @returns A promise that is resolved when the instance has been successfully
  * terminated.
  */

packages/firestore/src/api/database.ts

@@ -32,7 +32,7 @@ import {
   validateIsNotUsedTogether,
   validateSetOptions
 } from '../util/input_validation';
-import { logWarn, setLogLevel as setClientLogLevel } from '../util/log';
+import { setLogLevel as setClientLogLevel } from '../util/log';
 import { FieldPath as ExpFieldPath } from '../../lite/src/api/field_path';
 import {
   CompleteFn,
@@ -52,6 +52,7 @@ import {
   enableNetwork,
   FirebaseFirestore,
   FirebaseFirestore as ExpFirebaseFirestore,
+  useFirestoreEmulator,
   waitForPendingWrites
 } from '../../exp/src/api/database';
 import {
@@ -96,7 +97,6 @@ import { LRU_COLLECTION_DISABLED } from '../local/lru_garbage_collector';
 import { Compat } from '../compat/compat';
 import { ApiLoadBundleTask, LoadBundleTask } from './bundle';
 import { makeDatabaseInfo } from '../../lite/src/api/database';
-import { DEFAULT_HOST } from '../../lite/src/api/components';
 import { WriteBatch as ExpWriteBatch } from '../../exp/src/api/write_batch';
 import {
   runTransaction,
@@ -241,17 +241,7 @@ export class Firestore
   }
 
   useEmulator(host: string, port: number): void {
-    if (this._delegate._getSettings().host !== DEFAULT_HOST) {
-      logWarn(
-        'Host has been set in both settings() and useEmulator(), emulator host will be used'
-      );
-    }
-
-    this.settings({
-      host: `${host}:${port}`,
-      ssl: false,
-      merge: true
-    });
+    useFirestoreEmulator(this._delegate, host, port);
   }
 
   enableNetwork(): Promise<void> {