Add comments and public annotations, fix promise

Author: hsubox76

common/api-review/util.api.md

@@ -195,21 +195,16 @@ export class FirebaseError extends Error {
 // @public
 export type FirebaseSignInProvider = 'custom' | 'email' | 'password' | 'phone' | 'anonymous' | 'google.com' | 'facebook.com' | 'github.com' | 'twitter.com' | 'microsoft.com' | 'apple.com';
 
-// Warning: (ae-missing-release-tag) "getDefaultAppConfig" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export const getDefaultAppConfig: () => Record<string, string> | undefined;
 
-// Warning: (ae-missing-release-tag) "getDefaultEmulatorHost" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
-export const getDefaultEmulatorHost: (name: string) => string | undefined;
+// @public
+export const getDefaultEmulatorHost: (productName: string) => string | undefined;
 
 // Warning: (ae-forgotten-export) The symbol "ExperimentalKey" needs to be exported by the entry point index.d.ts
 // Warning: (ae-forgotten-export) The symbol "FirebaseDefaults" needs to be exported by the entry point index.d.ts
-// Warning: (ae-missing-release-tag) "getExperimentalSetting" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
-// @public (undocumented)
+// @public
 export const getExperimentalSetting: <T extends ExperimentalKey>(name: T) => FirebaseDefaults[`_${T}`];
 
 // Warning: (ae-missing-release-tag) "getGlobal" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)

packages/auth/src/platform_browser/index.ts

@@ -89,9 +89,7 @@ export function getAuth(app: FirebaseApp = getApp()): Auth {
   const authTokenSyncUrl = getExperimentalSetting('authTokenSyncURL');
   if (authTokenSyncUrl) {
     const mintCookie = mintCookieFactory(authTokenSyncUrl);
-    beforeAuthStateChanged(auth, mintCookie, () => {
-      void mintCookie(auth.currentUser);
-    });
+    beforeAuthStateChanged(auth, mintCookie, () => mintCookie(auth.currentUser));
     onIdTokenChanged(auth, user => mintCookie(user));
   }
 

packages/util/src/defaults.ts

@@ -18,9 +18,23 @@
 import { base64Decode } from './crypt';
 import { getGlobal } from './environment';
 
-type ExperimentalKey = 'authTokenSyncURL' | 'authIdTokenMaxAge';
+/**
+ * Keys for experimental properties on the `FirebaseDefaults` object.
+ * @public
+ */
+export type ExperimentalKey = 'authTokenSyncURL' | 'authIdTokenMaxAge';
 
-interface FirebaseDefaults {
+/**
+ * An object that can be injected into the environment as __FIREBASE_DEFAULTS__,
+ * either as a property of globalThis, a shell environment variable, or a
+ * cookie.
+ * 
+ * This object can be used to automatically configure and initialize
+ * a Firebase app as well as any emulators.
+ * 
+ * @public
+ */
+export interface FirebaseDefaults {
   config?: Record<string, string>;
   emulatorHosts?: Record<string, string>;
   _authTokenSyncURL?: string;
@@ -81,17 +95,37 @@ const getDefaultsFromCookie = (): FirebaseDefaults | undefined => {
   return decoded && JSON.parse(decoded);
 };
 
+/**
+ * Get the __FIREBASE_DEFAULTS__ object. It checks in order:
+ * (1) if such an object exists as a property of `globalThis`
+ * (2) if such an object was provided on a shell environment variable
+ * (3) if such an object exists in a cookie
+ */
 const getDefaults = (): FirebaseDefaults | undefined =>
   getDefaultsFromGlobal() ||
   getDefaultsFromEnvVariable() ||
   getDefaultsFromCookie();
 
-export const getDefaultEmulatorHost = (name: string): string | undefined =>
-  getDefaults()?.emulatorHosts?.[name];
+/**
+ * Returns emulator host stored in the __FIREBASE_DEFAULTS__ object
+ * for the given product.
+ * @public
+ */
+export const getDefaultEmulatorHost = (productName: string): string | undefined =>
+  getDefaults()?.emulatorHosts?.[productName];
 
+/**
+ * Returns Firebase app config stored in the __FIREBASE_DEFAULTS__ object.
+ * @public
+ */
 export const getDefaultAppConfig = (): Record<string, string> | undefined =>
   getDefaults()?.config;
 
+/**
+ * Returns an experimental setting on the __FIREBASE_DEFAULTS__ object (properties
+ * prefixed by "_")
+ * @public
+ */
 export const getExperimentalSetting = <T extends ExperimentalKey>(
   name: T
 ): FirebaseDefaults[`_${T}`] =>