Implement useEmulator for Database

.changeset/bright-ducks-jump.md

@@ -0,0 +1,7 @@
+---
+'firebase': minor
+'@firebase/database': minor
+'@firebase/database-types': minor
+---
+
+Add a useEmulator(host, port) method to Realtime Database

packages/database-types/index.d.ts

@@ -34,6 +34,7 @@ export interface DataSnapshot {
 
 export interface Database {
   app: FirebaseApp;
+  useEmulator(host: string, port: number): void;
   goOffline(): void;
   goOnline(): void;
   ref(path?: string | Reference): Reference;
@@ -43,6 +44,7 @@ export interface Database {
 export class FirebaseDatabase implements Database {
   private constructor();
   app: FirebaseApp;
+  useEmulator(host: string, port: number): void;
   goOffline(): void;
   goOnline(): void;
   ref(path?: string | Reference): Reference;

packages/database/src/api/Database.ts

@@ -33,8 +33,11 @@ import { FirebaseDatabase } from '@firebase/database-types';
  * @implements {FirebaseService}
  */
 export class Database implements FirebaseService {
-  INTERNAL: DatabaseInternals;
-  private root_: Reference;
+  /** Track if the instance has been used (root or repo accessed) */
+  private instanceStarted_: boolean = false;
+
+  /** Backing state for root_ */
+  private rootInternal_?: Reference;
 
   static readonly ServerValue = {
     TIMESTAMP: {
@@ -51,25 +54,66 @@ export class Database implements FirebaseService {
 
   /**
    * The constructor should not be called by users of our public API.
-   * @param {!Repo} repo_
+   * @param {!Repo} repoInternal_
    */
-  constructor(private repo_: Repo) {
-    if (!(repo_ instanceof Repo)) {
+  constructor(private repoInternal_: Repo) {
+    if (!(repoInternal_ instanceof Repo)) {
       fatal(
         "Don't call new Database() directly - please use firebase.database()."
       );
     }
+  }
 
-    /** @type {Reference} */
-    this.root_ = new Reference(repo_, Path.Empty);
+  INTERNAL = {
+    delete: async () => {
+      this.checkDeleted_('delete');
+      RepoManager.getInstance().deleteRepo(this.repo_);
+      this.repoInternal_ = null;
+      this.rootInternal_ = null;
+    }
+  };
 
-    this.INTERNAL = new DatabaseInternals(this);
+  private get repo_(): Repo {
+    this.instanceStarted_ = true;
+    return this.repoInternal_;
+  }
+
+  get root_(): Reference {
+    if (!this.rootInternal_) {
+      this.rootInternal_ = new Reference(this.repo_, Path.Empty);
+    }
+
+    return this.rootInternal_;
   }
 
   get app(): FirebaseApp {
     return this.repo_.app;
   }
 
+  /**
+   * Modify this instance to communicate with the Realtime Database emulator.
+   *
+   * <p>Note: This method must be called before performing any other operation.
+   *
+   * @param host the emulator host (ex: localhost)
+   * @param port the emulator port (ex: 8080)
+   */
+  useEmulator(host: string, port: number): void {
+    if (this.instanceStarted_) {
+      fatal(
+        'Cannot call useEmulator() after instance has already been initialized.'
+      );
+      return;
+    }
+
+    // Modify the repo to apply emulator settings
+    RepoManager.getInstance().applyEmulatorSettings(
+      this.repoInternal_,
+      host,
+      port
+    );
+  }
+
   /**
    * Returns a reference to the root or to the path specified in the provided
    * argument.
@@ -146,22 +190,3 @@ export class Database implements FirebaseService {
     this.repo_.resume();
   }
 }
-
-export class DatabaseInternals {
-  /** @param {!Database} database */
-  constructor(public database: Database) {}
-
-  /** @return {Promise<void>} */
-  async delete(): Promise<void> {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    (this.database as any).checkDeleted_('delete');
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    RepoManager.getInstance().deleteRepo((this.database as any).repo_ as Repo);
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    (this.database as any).repo_ = null;
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    (this.database as any).root_ = null;
-    this.database.INTERNAL = null;
-    this.database = null;
-  }
-}

packages/database/src/core/Repo.ts

@@ -54,6 +54,9 @@ const INTERRUPT_REASON = 'repo_interrupt';
  * A connection to a single data repository.
  */
 export class Repo {
+  /** Key for uniquely identifying this repo, used in RepoManager */
+  readonly key: string;
+
   dataUpdateCount = 0;
   private infoSyncTree_: SyncTree;
   private serverSyncTree_: SyncTree;
@@ -83,7 +86,7 @@ export class Repo {
     public repoInfo_: RepoInfo,
     forceRestClient: boolean,
     public app: FirebaseApp,
-    authTokenProvider: AuthTokenProvider
+    public authTokenProvider: AuthTokenProvider
   ) {
     this.stats_ = StatsManager.getCollection(repoInfo_);
 
@@ -174,6 +177,9 @@ export class Repo {
         this.server_.unlisten(query, tag);
       }
     });
+
+    // This key is intentionally not updated if RepoInfo is later changed or replaced
+    this.key = this.repoInfo_.toURLString();
   }
 
   /**

packages/database/src/core/RepoManager.ts

@@ -87,6 +87,23 @@ export class RepoManager {
     }
   }
 
+  /**
+   * Update an existing repo in place to point to a new host/port.
+   */
+  applyEmulatorSettings(repo: Repo, host: string, port: number): void {
+    const url = `http://${host}:${port}?ns=${repo.repoInfo_.namespace}`;
+
+    const nodeAdmin = repo.repoInfo_.nodeAdmin;
+    const authTokenProvider = nodeAdmin
+      ? new EmulatorAdminTokenProvider()
+      : repo.authTokenProvider;
+
+    // Update the repo in-place
+    const { repoInfo } = parseRepoInfo(url, nodeAdmin);
+    repo.repoInfo_ = repoInfo;
+    repo.authTokenProvider = authTokenProvider;
+  }
+
   /**
    * This function should only ever be called to CREATE a new database instance.
    *
@@ -157,13 +174,13 @@ export class RepoManager {
   deleteRepo(repo: Repo) {
     const appRepos = safeGet(this.repos_, repo.app.name);
     // This should never happen...
-    if (!appRepos || safeGet(appRepos, repo.repoInfo_.toURLString()) !== repo) {
+    if (!appRepos || safeGet(appRepos, repo.key) !== repo) {
       fatal(
         `Database ${repo.app.name}(${repo.repoInfo_}) has already been deleted.`
       );
     }
     repo.interrupt();
-    delete appRepos[repo.repoInfo_.toURLString()];
+    delete appRepos[repo.key];
   }
 
   /**

packages/database/test/database.test.ts

@@ -260,4 +260,22 @@ describe('Database Tests', () => {
       const ref = (db as any).refFromURL();
     }).to.throw(/Expects at least 1/);
   });
+
+  it('can call useEmulator before use', () => {
+    const db = (firebase as any).database();
+    db.useEmulator('localhost', 1234);
+    expect(db.ref().toString()).to.equal('http://localhost:1234/');
+  });
+
+  it('cannot call useEmulator after use', () => {
+    const db = (firebase as any).database();
+
+    db.ref().set({
+      hello: 'world'
+    });
+
+    expect(() => {
+      db.useEmulator('localhost', 1234);
+    }).to.throw(/Cannot call useEmulator/);
+  });
 });

packages/firebase/index.d.ts

@@ -5647,6 +5647,15 @@ declare namespace firebase.database {
      * ```
      */
     app: firebase.app.App;
+    /**
+     * Modify this instance to communicate with the Realtime Database emulator.
+     *
+     * <p>Note: This method must be called before performing any other operation.
+     *
+     * @param host the emulator host (ex: localhost)
+     * @param port the emulator port (ex: 8080)
+     */
+    useEmulator(host: string, port: number): void;
     /**
      * Disconnects from the server (all Database operations will be completed
      * offline).