Merge branch 'master' into em-pubsub

Author: esmacik

docgen/content-sources/toc.yaml

@@ -12,6 +12,8 @@ toc:
         path: /docs/reference/functions/function_builder_.functionbuilder.html
       - title: 'Change'
         path: /docs/reference/functions/cloud_functions_.change.html
+      - title: 'ChangeJson'
+        path: /docs/reference/functions/cloud_functions_.changejson.html
 
   - title: 'functions.config'
     path: /docs/reference/functions/config_.html

src/cloud-functions.ts

@@ -143,15 +143,19 @@ export interface EventContext {
 }
 
 /**
- * Change describes a change of state - "before" represents the state prior to
- * the event, "after" represents the state after the event.
+ * The Functions interface for events that change state, such as
+ * Realtime Database or Cloud Firestore `onWrite` and `onUpdate`.
+ *
+ * For more information about the format used to construct `Change` objects, see
+ * [`cloud-functions.ChangeJson`](/docs/reference/functions/cloud_functions_.changejson).
+ *
  */
 export class Change<T> {
   constructor(public before: T, public after: T) {}
 }
 
 /**
- * ChangeJson is the JSON format used to construct a Change object.
+ * `ChangeJson` is the JSON format used to construct a Change object.
  */
 export interface ChangeJson {
   /**
@@ -164,17 +168,20 @@ export interface ChangeJson {
    */
   before?: any;
   /**
-   * Comma-separated string that represents names of field that changed.
+   * @hidden
+   * Comma-separated string that represents names of fields that changed.
    */
   fieldMask?: string;
 }
 
 export namespace Change {
+  /** @hidden */
   function reinterpretCast<T>(x: any) {
     return x as T;
   }
 
   /**
+   * @hidden
    * Factory method for creating a Change from a `before` object and an `after`
    * object.
    */
@@ -183,6 +190,7 @@ export namespace Change {
   }
 
   /**
+   * @hidden
    * Factory method for creating a Change from a JSON and an optional customizer
    * function to be applied to both the `before` and the `after` fields.
    */

src/providers/https.ts

@@ -27,6 +27,7 @@ import * as _ from 'lodash';
 import { apps } from '../apps';
 import { HttpsFunction, optionsToTrigger, Runnable } from '../cloud-functions';
 import { DeploymentOptions } from '../function-configuration';
+import { assertNever } from '../utilities/assertions';
 
 export interface Request extends express.Request {
   rawBody: Buffer;
@@ -231,7 +232,7 @@ export class HttpsError extends Error {
         return 500;
       // This should never happen as long as the type system is doing its job.
       default:
-        throw new Error('Invalid error code: ' + this.code);
+        assertNever(this.code);
     }
   }
 

src/providers/remoteConfig.ts

@@ -35,9 +35,13 @@ export const provider = 'google.firebase.remoteconfig';
 export const service = 'firebaseremoteconfig.googleapis.com';
 
 /**
- * Handle all updates (including rollbacks) that affect a Remote Config project.
- * @param handler A function that takes the updated Remote Config template
- * version metadata as an argument.
+ * Registers a function that triggers on Firebase Remote Config template
+ * update events.
+ *
+ * @param handler A function that takes the updated Remote Config
+ *   template version metadata as an argument.
+ *
+ * @return A Cloud Function that you can export and deploy.
  */
 export function onUpdate(
   handler: (
@@ -97,8 +101,8 @@ export class UpdateBuilder {
 }
 
 /**
- * Interface representing a Remote Config template version metadata object that
- * was emitted when the project was updated.
+ * An interface representing a Remote Config template version metadata object
+ * emitted when a project is updated.
  */
 export interface TemplateVersion {
   /** The version number of the updated Remote Config template. */
@@ -107,27 +111,49 @@ export interface TemplateVersion {
   /** When the template was updated in format (ISO8601 timestamp). */
   updateTime: string;
 
-  /** Metadata about the account that performed the update. */
+  /**
+   * Metadata about the account that performed the update, of
+   * type [`RemoteConfigUser`](/docs/reference/remote-config/rest/v1/Version#remoteconfiguser).
+   */
   updateUser: RemoteConfigUser;
 
-  /** A description associated with the particular Remote Config template. */
+  /** A description associated with this Remote Config template version. */
   description: string;
 
-  /** The origin of the caller. */
+  /**
+   * The origin of the caller - either the Firebase console or the Remote Config
+   * REST API. See [`RemoteConfigUpdateOrigin`](/docs/reference/remote-config/rest/v1/Version#remoteconfigupdateorigin)
+   * for valid values.
+   */
   updateOrigin: string;
 
-  /** The type of update action that was performed. */
+  /**
+   * The type of update action that was performed, whether forced,
+   * incremental, or a rollback operation. See
+   * [`RemoteConfigUpdateType`](/docs/reference/remote-config/rest/v1/Version#remoteconfigupdatetype)
+   * for valid values.
+   */
   updateType: string;
 
   /**
-   * The version number of the Remote Config template that was rolled back to,
-   * if the update was a rollback.
+   * The version number of the Remote Config template that this update rolled back to.
+   * Only applies if this update was a rollback.
    */
   rollbackSource?: number;
 }
 
+/**
+ * An interface representing metadata for a Remote Config account
+ * that performed the update. Contains the same fields as
+ * [`RemoteConfigUser`](/docs/reference/remote-config/rest/v1/Version#remoteconfiguser).
+ */
 export interface RemoteConfigUser {
+  /** Name of the Remote Config account that performed the update. */
   name?: string;
+
+  /** Email address of the Remote Config account that performed the update. */
   email: string;
+
+  /** Image URL of the Remote Config account that performed the update. */
   imageUrl?: string;
 }

src/utilities/assertions.ts

@@ -0,0 +1,16 @@
+/**
+ * @file Provides common assertion helpers which can be used to improve
+ * strictness of both type checking and runtime.
+ */
+
+/**
+ * Checks that the given value is of type `never` — the type that’s left after
+ * all other cases have been removed.
+ *
+ * @param x A value of type `never`.
+ */
+export function assertNever(x: never): never {
+  throw new Error(
+    `Unhandled discriminated union member: ${JSON.stringify(x)}.`
+  );
+}