Refactor types, add doc comments.

Author: hsubox76

packages/app-types/index.d.ts

@@ -14,6 +14,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+import { LogCallback, LogLevelString, LogOptions } from '@firebase/logger';
 
 export type FirebaseOptions = {
   apiKey?: string;
@@ -31,25 +32,6 @@ export interface FirebaseAppConfig {
   automaticDataCollectionEnabled?: boolean;
 }
 
-export type LogLevelString =
-  | 'debug'
-  | 'verbose'
-  | 'info'
-  | 'warn'
-  | 'error'
-  | 'silent';
-
-export interface LogOptions {
-  level: LogLevelString;
-}
-
-export type LogCallback = (callbackParams: {
-  level: LogLevelString;
-  message: string;
-  args: unknown[];
-  type: string;
-}) => void;
-
 export class FirebaseApp {
   /**
    * The (read-only) name (identifier) for this App. '[DEFAULT]' is the default

packages/firebase/index.d.ts

@@ -78,6 +78,15 @@ declare namespace firebase {
     complete: CompleteFn;
   }
 
+  /**
+   * The JS SDK supports 5 log levels and also allows a user the ability to
+   * silence the logs altogether.
+   *
+   * The order is as follows:
+   * debug < verbose < info < warn < error
+   */
+  type LogLevel = 'debug' | 'verbose' | 'info' | 'warn' | 'error' | 'silent';
+
   /**
    * The current SDK version.
    */
@@ -95,6 +104,49 @@ declare namespace firebase {
     variant?: string
   ): void;
 
+  /**
+   * Sets log level for all Firebase packages.
+   *
+   * All of the log types above the current log level will be captured (i.e. if
+   * you set the log level to `info`, errors will still be logged, but `debug` and
+   * `verbose` logs will not)
+   */
+  function setLogLevel(logLevel: LogLevel): void;
+
+  /**
+   * Sets log handler for all Firebase packages.
+   * @param logCallback An optional custom log handler that will execute user code whenever
+   * the Firebase SDK makes a logging call.
+   */
+  function onLog(
+    logCallback: (callbackParams: {
+      /**
+       * Level of event logged.
+       */
+      level: LogLevel;
+      /**
+       * Any text from logged arguments joined into one string.
+       */
+      message: string;
+      /**
+       * The raw arguments passed to the log call.
+       */
+      args: unknown[];
+      /**
+       * A string indicating the source of the log call, usually a package name
+       * such as `@firebase/firestore`.
+       */
+      type: string;
+    }) => void,
+    options: {
+      /**
+       * Threshhold log level. Only logs at or above this level will trigger the `logCallback`
+       * passed to `onLog`.
+       */
+      level: LogLevel;
+    }
+  ): void;
+
   /**
    * @hidden
    */

packages/logger/index.ts

@@ -20,5 +20,8 @@ export {
   Logger,
   LogLevel,
   LogHandler,
-  setUserLogHandler
+  setUserLogHandler,
+  LogCallback,
+  LogLevelString,
+  LogOptions
 } from './src/logger';

packages/logger/src/logger.ts

@@ -15,7 +15,24 @@
  * limitations under the License.
  */
 
-import { LogCallback, LogLevelString, LogOptions } from '@firebase/app-types';
+export type LogLevelString =
+  | 'debug'
+  | 'verbose'
+  | 'info'
+  | 'warn'
+  | 'error'
+  | 'silent';
+
+export interface LogOptions {
+  level: LogLevelString;
+}
+
+export type LogCallback = (callbackParams: {
+  level: LogLevelString;
+  message: string;
+  args: unknown[];
+  type: string;
+}) => void;
 
 /**
  * A container for all of the Logger instances
@@ -196,9 +213,8 @@ export function setUserLogHandler(
   logCallback: LogCallback | null,
   options: LogOptions
 ): void {
-  if (typeof logCallback !== 'function') {
-    console.warn('First argument to `onLog` must be a function.');
-    return;
+  if (logCallback !== null && typeof logCallback !== 'function') {
+    throw new TypeError('First argument to `onLog` must be null or a function.');
   }
   for (const instance of instances) {
     let threshhold = instance.logLevel;
@@ -213,7 +229,25 @@ export function setUserLogHandler(
         level: LogLevel,
         ...args: unknown[]
       ) => {
-        const message = args.map(arg => (arg as object).toString()).join(' ');
+        const message = args.map(arg => {
+          if (arg == null) {
+            return null;
+          } else if (typeof arg === 'string') {
+            return arg;
+          } else if (typeof arg === 'number' || typeof arg === 'boolean') {
+            return arg.toString();
+          } else if (arg instanceof Error) {
+            return arg.message;
+          } else {
+            try {
+              return JSON.stringify(arg);
+            } catch(ignored) {
+              return null;
+            }
+          }
+        })
+        .filter(arg => arg)
+        .join(' ');
         if (level >= threshhold) {
           logCallback({
             level: LogLevel[level].toLowerCase() as LogLevelString,