From 3193eb8c4e068c2bcf4946be23f4803aba828b8d Mon Sep 17 00:00:00 2001 From: Eric Gilmore Date: Wed, 18 Mar 2020 12:37:13 -0700 Subject: [PATCH 1/3] Adding top-level comment and TOC for functions.handler. --- docgen/content-sources/toc.yaml | 6 +++ src/handler-builder.ts | 74 ++++----------------------------- 2 files changed, 14 insertions(+), 66 deletions(-) diff --git a/docgen/content-sources/toc.yaml b/docgen/content-sources/toc.yaml index 378af2eef..35cc6d92a 100644 --- a/docgen/content-sources/toc.yaml +++ b/docgen/content-sources/toc.yaml @@ -116,3 +116,9 @@ toc: path: /docs/reference/functions/providers_storage_.objectbuilder.html - title: 'ObjectMetadata' path: /docs/reference/functions/providers_storage_.objectmetadata.html + + - title: 'functions.handler' + path: /docs/reference/functions/handler_builder_.html + section: + - title: 'HandlerBuilder' + path: /docs/reference/functions/handler_builder_.handlerbuilder.html diff --git a/src/handler-builder.ts b/src/handler-builder.ts index 5d7c122d7..9ce1fa9b1 100644 --- a/src/handler-builder.ts +++ b/src/handler-builder.ts @@ -35,6 +35,14 @@ import * as remoteConfig from './providers/remoteConfig'; import * as storage from './providers/storage'; import * as testLab from './providers/testLab'; +/** + * The `HandlerBuilder` class facilitates the writing of functions by producers + * of Firebase Extensions and developers that want to use gcloud CLI or Cloud Console + * to deploy their functions. + * + * **Do not use `HandlerBuilder` when writing normal functions for deployment via + * Cloud Functions for Firebase.** For normal purposes, use `FunctionBuilder`. + */ export class HandlerBuilder { constructor() {} @@ -52,10 +60,6 @@ export class HandlerBuilder { func.__trigger = {}; return func; }, - /** - * Declares a callable method for clients to call using a Firebase SDK. - * @param handler A method that takes a data and context and returns a value. - */ onCall: ( handler: ( data: any, @@ -71,10 +75,6 @@ export class HandlerBuilder { get database() { return { - /** - * Selects a database instance that will trigger the function. - * If omitted, will pick the default database for your project. - */ get instance() { return { get ref() { @@ -82,29 +82,6 @@ export class HandlerBuilder { }, }; }, - - /** - * Select Firebase Realtime Database Reference to listen to. - * - * This method behaves very similarly to the method of the same name in the - * client and Admin Firebase SDKs. Any change to the Database that affects the - * data at or below the provided `path` will fire an event in Cloud Functions. - * - * There are three important differences between listening to a Realtime - * Database event in Cloud Functions and using the Realtime Database in the - * client and Admin SDKs: - * 1. Cloud Functions allows wildcards in the `path` name. Any `path` component - * in curly brackets (`{}`) is a wildcard that matches all strings. The value - * that matched a certain invocation of a Cloud Function is returned as part - * of the `context.params` object. For example, `ref("messages/{messageId}")` - * matches changes at `/messages/message1` or `/messages/message2`, resulting - * in `context.params.messageId` being set to `"message1"` or `"message2"`, - * respectively. - * 2. Cloud Functions do not fire an event for data that already existed before - * the Cloud Function was deployed. - * 3. Cloud Function events have access to more information, including information - * about the user who triggered the Cloud Function. - */ get ref() { return new database.RefBuilder(apps(), () => null, {}); }, @@ -113,10 +90,6 @@ export class HandlerBuilder { get firestore() { return { - /** - * Listen for events on a Firestore document. A Firestore document contains a set of - * key-value pairs and may contain subcollections and nested objects. - */ get document() { return new firestore.DocumentBuilder(() => null, {}); }, @@ -133,10 +106,6 @@ export class HandlerBuilder { get crashlytics() { return { - /** - * Handle events related to Crashlytics issues. An issue in Crashlytics is an - * aggregation of crashes which have a shared root cause. - */ get issue() { return new crashlytics.IssueBuilder(() => null, {}); }, @@ -145,12 +114,6 @@ export class HandlerBuilder { get remoteConfig() { return { - /** - * 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. - */ onUpdate: ( handler: ( version: remoteConfig.TemplateVersion, @@ -164,9 +127,6 @@ export class HandlerBuilder { get analytics() { return { - /** - * Select analytics events to listen to for events. - */ get event() { return new analytics.AnalyticsEventBuilder(() => null, {}); }, @@ -175,18 +135,10 @@ export class HandlerBuilder { get storage() { return { - /** - * The optional bucket function allows you to choose which buckets' events to handle. - * This step can be bypassed by calling object() directly, which will use the default - * Cloud Storage for Firebase bucket. - */ get bucket() { return new storage.BucketBuilder(() => null, {}).object(); }, - /** - * Handle events related to Cloud Storage objects. - */ get object() { return new storage.ObjectBuilder(() => null, {}); }, @@ -195,15 +147,9 @@ export class HandlerBuilder { get pubsub() { return { - /** - * Select Cloud Pub/Sub topic to listen to. - */ get topic() { return new pubsub.TopicBuilder(() => null, {}); }, - /** - * Handle periodic events triggered by Cloud Scheduler. - */ get schedule() { return new pubsub.ScheduleBuilder(() => null, {}); }, @@ -212,9 +158,6 @@ export class HandlerBuilder { get auth() { return { - /** - * Handle events related to Firebase authentication users. - */ get user() { return new auth.UserBuilder(() => null, {}); }, @@ -222,7 +165,6 @@ export class HandlerBuilder { } get testLab() { - /** Handle events related to Test Lab test matrices. */ return { get testMatrix() { return new testLab.TestMatrixBuilder(() => null, {}); From ada9dba8b947fa5e127bb14390f23177c02ced5d Mon Sep 17 00:00:00 2001 From: Eric Gilmore Date: Fri, 20 Mar 2020 09:30:17 -0700 Subject: [PATCH 2/3] Adding edits from feedback. --- src/handler-builder.ts | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/src/handler-builder.ts b/src/handler-builder.ts index 9ce1fa9b1..e45843cc2 100644 --- a/src/handler-builder.ts +++ b/src/handler-builder.ts @@ -37,11 +37,12 @@ import * as testLab from './providers/testLab'; /** * The `HandlerBuilder` class facilitates the writing of functions by producers - * of Firebase Extensions and developers that want to use gcloud CLI or Cloud Console - * to deploy their functions. + * of Firebase Extensions and developers who want to use the gcloud CLI or + * Google Cloud Console to deploy their functions. * * **Do not use `HandlerBuilder` when writing normal functions for deployment via - * Cloud Functions for Firebase.** For normal purposes, use `FunctionBuilder`. + * Cloud Functions for Firebase.** For normal purposes, use + * [`FunctionBuilder`](/docs/reference/functions/function_builder_.functionbuilder). */ export class HandlerBuilder { constructor() {} From e69ae9c2dd0afa5e3994a77467dd2eb3608bde4a Mon Sep 17 00:00:00 2001 From: Eric Gilmore Date: Fri, 20 Mar 2020 13:34:20 -0700 Subject: [PATCH 3/3] Refer specifically to Firebase CLI. --- src/handler-builder.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/handler-builder.ts b/src/handler-builder.ts index e45843cc2..11a9ee777 100644 --- a/src/handler-builder.ts +++ b/src/handler-builder.ts @@ -41,7 +41,7 @@ import * as testLab from './providers/testLab'; * Google Cloud Console to deploy their functions. * * **Do not use `HandlerBuilder` when writing normal functions for deployment via - * Cloud Functions for Firebase.** For normal purposes, use + * the Firebase CLI.** For normal purposes, use * [`FunctionBuilder`](/docs/reference/functions/function_builder_.functionbuilder). */ export class HandlerBuilder {