Add useFirestoreEmulator

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

@@ -520,6 +520,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

@@ -426,6 +426,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

@@ -31,7 +31,8 @@ export {
   waitForPendingWrites,
   disableNetwork,
   enableNetwork,
-  terminate
+  terminate,
+  useFirestoreEmulator
 } from '../src/exp/database';
 
 export { Settings, PersistenceSettings } from '../src/exp/settings';

packages/firestore/lite/index.ts

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

packages/firestore/src/api/database.ts

@@ -55,6 +55,7 @@ import {
   enableNetwork,
   ensureFirestoreConfigured,
   FirebaseFirestore as ExpFirebaseFirestore,
+  useFirestoreEmulator,
   waitForPendingWrites
 } from '../exp/database';
 import { FieldPath as ExpFieldPath } from '../exp/field_path';
@@ -95,7 +96,6 @@ import {
   updateDoc,
   Unsubscribe
 } from '../exp/reference_impl';
-import { DEFAULT_HOST } from '../exp/settings';
 import {
   DocumentChange as ExpDocumentChange,
   DocumentSnapshot as ExpDocumentSnapshot,
@@ -118,7 +118,7 @@ import {
   validateIsNotUsedTogether,
   validateSetOptions
 } from '../util/input_validation';
-import { logWarn, setLogLevel as setClientLogLevel } from '../util/log';
+import { setLogLevel as setClientLogLevel } from '../util/log';
 
 import { Blob } from './blob';
 import { LoadBundleTask } from './bundle';
@@ -236,17 +236,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> {

packages/firestore/src/exp/database.ts

@@ -53,6 +53,8 @@ import { Deferred } from '../util/promise';
 
 import { PersistenceSettings, Settings } from './settings';
 
+export { useFirestoreEmulator } from '../lite/database';
+
 /** DOMException error code constants. */
 const DOM_EXCEPTION_INVALID_STATE = 11;
 const DOM_EXCEPTION_ABORTED = 20;

packages/firestore/src/lite/database.ts

@@ -30,9 +30,15 @@ import {
 import { DatabaseId } from '../core/database_info';
 import { Code, FirestoreError } from '../util/error';
 import { cast } from '../util/input_validation';
+import { logWarn } from '../util/log';
 
 import { FirestoreService, removeComponents } from './components';
-import { FirestoreSettings, PrivateSettings, Settings } from './settings';
+import {
+  DEFAULT_HOST,
+  FirestoreSettings,
+  PrivateSettings,
+  Settings
+} from './settings';
 
 declare module '@firebase/component' {
   interface NameServiceMapping {
@@ -191,6 +197,39 @@ 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);
+  const settings = firestore._getSettings();
+
+  if (settings.host !== DEFAULT_HOST && settings.host !== host) {
+    logWarn(
+      'Host has been set in both settings() and useEmulator(), emulator host ' +
+        'will be used'
+    );
+  }
+
+  firestore._setSettings({
+    ...settings,
+    host: `${host}:${port}`,
+    ssl: false
+  });
+}
+
 /**
  * Terminates the provided Firestore instance.
  *
@@ -207,6 +246,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.
  */