From 0e70a01e9195de13e93fe51d560cad2f1ca32910 Mon Sep 17 00:00:00 2001 From: Tyler Stark Date: Mon, 9 May 2022 12:00:21 -0500 Subject: [PATCH 1/7] Update pubsub docs Update pubsub docs, clearing out existing warnings --- src/providers/pubsub.ts | 26 +++++++++++++------------- src/v2/providers/pubsub.ts | 18 +++++++++++------- 2 files changed, 24 insertions(+), 20 deletions(-) diff --git a/src/providers/pubsub.ts b/src/providers/pubsub.ts index 9cd88bd86..f5d683fc1 100644 --- a/src/providers/pubsub.ts +++ b/src/providers/pubsub.ts @@ -30,23 +30,23 @@ import { ScheduleRetryConfig, } from '../function-configuration'; -/** @hidden */ +/** @internal */ export const provider = 'google.pubsub'; -/** @hidden */ +/** @internal */ export const service = 'pubsub.googleapis.com'; /** * Registers a Cloud Function triggered when a Google Cloud Pub/Sub message * is sent to a specified topic. * - * @param topic The Pub/Sub topic to watch for message events. - * @return Pub/Sub topic builder interface. + * @param topic - The Pub/Sub topic to watch for message events. + * @returns Pub/Sub topic builder interface. */ export function topic(topic: string) { return _topicWithOptions(topic, {}); } -/** @hidden */ +/** @internal */ export function _topicWithOptions( topic: string, options: DeploymentOptions @@ -69,7 +69,7 @@ export function _topicWithOptions( * Access via [`functions.pubsub.topic()`](providers_pubsub_.html#topic). */ export class TopicBuilder { - /** @hidden */ + /** @internal */ constructor( private triggerResource: () => string, private options: DeploymentOptions @@ -79,7 +79,7 @@ export class TopicBuilder { * Event handler that fires every time a Cloud Pub/Sub message is * published. * - * @param handler Event handler that runs every time a Cloud Pub/Sub message + * @param handler - Event handler that runs every time a Cloud Pub/Sub message * is published. * @return A Cloud Function that you can export and deploy. */ @@ -101,14 +101,14 @@ export class TopicBuilder { /** * Registers a Cloud Function to run at specified times. * - * @param schedule The schedule, in Unix Crontab or AppEngine syntax. + * @param schedule - The schedule, in Unix Crontab or AppEngine syntax. * @return ScheduleBuilder interface. */ export function schedule(schedule: string): ScheduleBuilder { return _scheduleWithOptions(schedule, {}); } -/** @hidden */ +/** @internal */ export function _scheduleWithOptions( schedule: string, options: DeploymentOptions @@ -136,7 +136,7 @@ export function _scheduleWithOptions( * Access via [`functions.pubsub.schedule()`](providers_pubsub_.html#schedule). */ export class ScheduleBuilder { - /** @hidden */ + /** @internal */ constructor( private triggerResource: () => string, private options: DeploymentOptions @@ -156,7 +156,7 @@ export class ScheduleBuilder { * Event handler for scheduled functions. Triggered whenever the associated * scheduler job sends a Pub/Sub message. * - * @param handler Handler that fires whenever the associated + * @param handler - Handler that fires whenever the associated * scheduler job sends a Pub/Sub message. * @return A Cloud Function that you can export and deploy. */ @@ -177,7 +177,7 @@ export class ScheduleBuilder { /** * Interface representing a Google Cloud Pub/Sub message. * - * @param data Payload of a Pub/Sub message. + * @param data - Payload of a Pub/Sub message. */ export class Message { /** @@ -190,7 +190,7 @@ export class Message { */ readonly attributes: { [key: string]: string }; - /** @hidden */ + /** @internal */ private _json: any; constructor(data: any) { diff --git a/src/v2/providers/pubsub.ts b/src/v2/providers/pubsub.ts index 62a5ba4a1..21c31f695 100644 --- a/src/v2/providers/pubsub.ts +++ b/src/v2/providers/pubsub.ts @@ -6,7 +6,8 @@ import * as options from '../options'; /** * Interface representing a Google Cloud Pub/Sub message. * - * @param data Payload of a Pub/Sub message. + * @param data - Payload of a Pub/Sub message. + * @beta */ export class Message { /** @@ -34,7 +35,7 @@ export class Message { */ readonly orderingKey: string; - /** @hidden */ + /** @internal */ private _json: T; constructor(data: any) { @@ -48,6 +49,7 @@ export class Message { /** * The JSON data payload of this message object, if any. + * @beta */ get json(): T { if (typeof this._json === 'undefined') { @@ -68,7 +70,8 @@ export class Message { /** * Returns a JSON-serializable representation of this object. * - * @return A JSON-serializable representation of this object. + * @returns A JSON-serializable representation of this object. + * @beta */ toJSON(): any { const json: Record = { @@ -86,29 +89,30 @@ export class Message { } } -/** The interface published in a Pub/Sub publish subscription. */ +/** @beta The interface published in a Pub/Sub publish subscription. */ export interface MessagePublishedData { readonly message: Message; readonly subscription: string; } -/** PubSubOptions extend EventHandlerOptions but must include a topic. */ +/** @beta PubSubOptions extend EventHandlerOptions but must include a topic. */ export interface PubSubOptions extends options.EventHandlerOptions { topic: string; } -/** Handle a message being published to a Pub/Sub topic. */ +/** @beta Handle a message being published to a Pub/Sub topic. */ export function onMessagePublished( topic: string, handler: (event: CloudEvent>) => any | Promise ): CloudFunction>>; -/** Handle a message being published to a Pub/Sub topic. */ +/** @beta Handle a message being published to a Pub/Sub topic. */ export function onMessagePublished( options: PubSubOptions, handler: (event: CloudEvent>) => any | Promise ): CloudFunction>>; +/** @beta Handle a message being published to a Pub/Sub topic. */ export function onMessagePublished( topicOrOptions: string | PubSubOptions, handler: (event: CloudEvent>) => any | Promise From d1ba8ab54c21c21f300175c02f388e840e74e828 Mon Sep 17 00:00:00 2001 From: Tyler Stark Date: Mon, 9 May 2022 12:38:17 -0500 Subject: [PATCH 2/7] Update internal -> hidden --- src/providers/pubsub.ts | 14 +++++++------- src/v2/providers/pubsub.ts | 2 +- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/src/providers/pubsub.ts b/src/providers/pubsub.ts index f5d683fc1..18517bee0 100644 --- a/src/providers/pubsub.ts +++ b/src/providers/pubsub.ts @@ -30,9 +30,9 @@ import { ScheduleRetryConfig, } from '../function-configuration'; -/** @internal */ +/** @hidden */ export const provider = 'google.pubsub'; -/** @internal */ +/** @hidden */ export const service = 'pubsub.googleapis.com'; /** @@ -46,7 +46,7 @@ export function topic(topic: string) { return _topicWithOptions(topic, {}); } -/** @internal */ +/** @hidden */ export function _topicWithOptions( topic: string, options: DeploymentOptions @@ -69,7 +69,7 @@ export function _topicWithOptions( * Access via [`functions.pubsub.topic()`](providers_pubsub_.html#topic). */ export class TopicBuilder { - /** @internal */ + /** @hidden */ constructor( private triggerResource: () => string, private options: DeploymentOptions @@ -108,7 +108,7 @@ export function schedule(schedule: string): ScheduleBuilder { return _scheduleWithOptions(schedule, {}); } -/** @internal */ +/** @hidden */ export function _scheduleWithOptions( schedule: string, options: DeploymentOptions @@ -136,7 +136,7 @@ export function _scheduleWithOptions( * Access via [`functions.pubsub.schedule()`](providers_pubsub_.html#schedule). */ export class ScheduleBuilder { - /** @internal */ + /** @hidden */ constructor( private triggerResource: () => string, private options: DeploymentOptions @@ -190,7 +190,7 @@ export class Message { */ readonly attributes: { [key: string]: string }; - /** @internal */ + /** @hidden */ private _json: any; constructor(data: any) { diff --git a/src/v2/providers/pubsub.ts b/src/v2/providers/pubsub.ts index 21c31f695..2a1bd34e9 100644 --- a/src/v2/providers/pubsub.ts +++ b/src/v2/providers/pubsub.ts @@ -35,7 +35,7 @@ export class Message { */ readonly orderingKey: string; - /** @internal */ + /** @hidden */ private _json: T; constructor(data: any) { From c0a8916f594931c314ffa83ad8c2b02b69e72d7c Mon Sep 17 00:00:00 2001 From: Tyler Stark Date: Mon, 9 May 2022 14:39:56 -0500 Subject: [PATCH 3/7] Update docs --- src/v2/providers/pubsub.ts | 33 +++++++++++++++++++++++++-------- 1 file changed, 25 insertions(+), 8 deletions(-) diff --git a/src/v2/providers/pubsub.ts b/src/v2/providers/pubsub.ts index 2a1bd34e9..d3c9a0198 100644 --- a/src/v2/providers/pubsub.ts +++ b/src/v2/providers/pubsub.ts @@ -7,7 +7,7 @@ import * as options from '../options'; * Interface representing a Google Cloud Pub/Sub message. * * @param data - Payload of a Pub/Sub message. - * @beta + * @param T - Type representing `Message.data`'s json format */ export class Message { /** @@ -49,7 +49,6 @@ export class Message { /** * The JSON data payload of this message object, if any. - * @beta */ get json(): T { if (typeof this._json === 'undefined') { @@ -71,7 +70,6 @@ export class Message { * Returns a JSON-serializable representation of this object. * * @returns A JSON-serializable representation of this object. - * @beta */ toJSON(): any { const json: Record = { @@ -89,30 +87,49 @@ export class Message { } } -/** @beta The interface published in a Pub/Sub publish subscription. */ +/** + * The interface published in a Pub/Sub publish subscription. + * @param T - Type representing `Message.data`'s json format + */ export interface MessagePublishedData { + /** Google Cloud Pub/Sub message. */ readonly message: Message; readonly subscription: string; } -/** @beta PubSubOptions extend EventHandlerOptions but must include a topic. */ +/** PubSubOptions extend EventHandlerOptions but must include a topic. */ export interface PubSubOptions extends options.EventHandlerOptions { topic: string; } -/** @beta Handle a message being published to a Pub/Sub topic. */ +/** + * Handle a message being published to a Pub/Sub topic. + * @param topic - The Pub/Sub topic to watch for message events. + * @param handler - fires whenever the associated scheduler job sends a Pub/Sub message. + * @param T - Type representing `Message.data`'s json format + */ export function onMessagePublished( topic: string, handler: (event: CloudEvent>) => any | Promise ): CloudFunction>>; -/** @beta Handle a message being published to a Pub/Sub topic. */ +/** + * Handle a message being published to a Pub/Sub topic. + * @param options - Option containing information (topic) for event + * @param handler - fires whenever the associated scheduler job sends a Pub/Sub message. + * @param T - Type representing `Message.data`'s json format + */ export function onMessagePublished( options: PubSubOptions, handler: (event: CloudEvent>) => any | Promise ): CloudFunction>>; -/** @beta Handle a message being published to a Pub/Sub topic. */ +/** + * Handle a message being published to a Pub/Sub topic. + * @param topicOrOptions - A string representing the PubSub topic or an option (which contains the topic) + * @param handler - fires whenever the associated scheduler job sends a Pub/Sub message. + * @param T - Type representing `Message.data`'s json format + */ export function onMessagePublished( topicOrOptions: string | PubSubOptions, handler: (event: CloudEvent>) => any | Promise From d5b9f36f87372884afc301d5c206d4a9761ea9e9 Mon Sep 17 00:00:00 2001 From: Tyler Stark Date: Mon, 9 May 2022 14:45:31 -0500 Subject: [PATCH 4/7] Moar update docs --- src/v2/providers/pubsub.ts | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/v2/providers/pubsub.ts b/src/v2/providers/pubsub.ts index d3c9a0198..49ccc4cc0 100644 --- a/src/v2/providers/pubsub.ts +++ b/src/v2/providers/pubsub.ts @@ -94,11 +94,13 @@ export class Message { export interface MessagePublishedData { /** Google Cloud Pub/Sub message. */ readonly message: Message; + /** A subscription resource. */ readonly subscription: string; } /** PubSubOptions extend EventHandlerOptions but must include a topic. */ export interface PubSubOptions extends options.EventHandlerOptions { + /** The Pub/Sub topic to watch for message events */ topic: string; } From 8a04c9c89af08c9bf7a9300111c738541972b5b7 Mon Sep 17 00:00:00 2001 From: Tyler Stark Date: Mon, 9 May 2022 15:03:39 -0500 Subject: [PATCH 5/7] Maybe upgrad docs further --- src/v2/providers/pubsub.ts | 24 ++++++++++++++++++++---- 1 file changed, 20 insertions(+), 4 deletions(-) diff --git a/src/v2/providers/pubsub.ts b/src/v2/providers/pubsub.ts index 49ccc4cc0..c493a0ddd 100644 --- a/src/v2/providers/pubsub.ts +++ b/src/v2/providers/pubsub.ts @@ -3,6 +3,22 @@ import { ManifestEndpoint } from '../../runtime/manifest'; import { CloudEvent, CloudFunction } from '../core'; import * as options from '../options'; +/** + * A PubSub Topic is: + *
    + * A resource that you can publish messages to and then consume those messages via subscriptions. + * An isolated data stream for pubsub messages. + * Messages are published to a topic. + * Messages are listened to via a subscription. + * Each subscription listens to the messages published to exactly one topic. + */ +export type PubSubTopic = string; + +/** + * Resource that listens to the messages published by exactly one topic. + */ +export type PubSubSubscription = string; + /** * Interface representing a Google Cloud Pub/Sub message. * @@ -95,13 +111,13 @@ export interface MessagePublishedData { /** Google Cloud Pub/Sub message. */ readonly message: Message; /** A subscription resource. */ - readonly subscription: string; + readonly subscription: PubSubSubscription; } /** PubSubOptions extend EventHandlerOptions but must include a topic. */ export interface PubSubOptions extends options.EventHandlerOptions { /** The Pub/Sub topic to watch for message events */ - topic: string; + topic: PubSubTopic; } /** @@ -111,7 +127,7 @@ export interface PubSubOptions extends options.EventHandlerOptions { * @param T - Type representing `Message.data`'s json format */ export function onMessagePublished( - topic: string, + topic: PubSubTopic, handler: (event: CloudEvent>) => any | Promise ): CloudFunction>>; @@ -150,7 +166,7 @@ export function onMessagePublished( const func = (raw: CloudEvent) => { const messagePublishedData = raw.data as { message: unknown; - subscription: string; + subscription: PubSubSubscription; }; messagePublishedData.message = new Message(messagePublishedData.message); return handler(raw as CloudEvent>); From 00aeffbe55dad1e4af27d8b9819c31c3b1bb8a52 Mon Sep 17 00:00:00 2001 From: Tyler Stark Date: Mon, 9 May 2022 15:31:15 -0500 Subject: [PATCH 6/7] Update docs on handler (incorrect messagiging in previous commit) --- src/v2/providers/pubsub.ts | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/v2/providers/pubsub.ts b/src/v2/providers/pubsub.ts index c493a0ddd..66d49300c 100644 --- a/src/v2/providers/pubsub.ts +++ b/src/v2/providers/pubsub.ts @@ -123,7 +123,7 @@ export interface PubSubOptions extends options.EventHandlerOptions { /** * Handle a message being published to a Pub/Sub topic. * @param topic - The Pub/Sub topic to watch for message events. - * @param handler - fires whenever the associated scheduler job sends a Pub/Sub message. + * @param handler - runs every time a Cloud Pub/Sub message is published * @param T - Type representing `Message.data`'s json format */ export function onMessagePublished( @@ -134,7 +134,7 @@ export function onMessagePublished( /** * Handle a message being published to a Pub/Sub topic. * @param options - Option containing information (topic) for event - * @param handler - fires whenever the associated scheduler job sends a Pub/Sub message. + * @param handler - runs every time a Cloud Pub/Sub message is published * @param T - Type representing `Message.data`'s json format */ export function onMessagePublished( @@ -145,7 +145,7 @@ export function onMessagePublished( /** * Handle a message being published to a Pub/Sub topic. * @param topicOrOptions - A string representing the PubSub topic or an option (which contains the topic) - * @param handler - fires whenever the associated scheduler job sends a Pub/Sub message. + * @param handler - runs every time a Cloud Pub/Sub message is published * @param T - Type representing `Message.data`'s json format */ export function onMessagePublished( From 2946a9384c1b826be61d81601a57cc5f0c7b0dfa Mon Sep 17 00:00:00 2001 From: Tyler Stark Date: Tue, 10 May 2022 10:11:42 -0500 Subject: [PATCH 7/7] Updating docs per feedback from pr review --- src/v2/providers/pubsub.ts | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/src/v2/providers/pubsub.ts b/src/v2/providers/pubsub.ts index 66d49300c..137d0fd73 100644 --- a/src/v2/providers/pubsub.ts +++ b/src/v2/providers/pubsub.ts @@ -6,11 +6,11 @@ import * as options from '../options'; /** * A PubSub Topic is: *
      - * A resource that you can publish messages to and then consume those messages via subscriptions. - * An isolated data stream for pubsub messages. - * Messages are published to a topic. - * Messages are listened to via a subscription. - * Each subscription listens to the messages published to exactly one topic. + *
    • A resource that you can publish messages to and then consume those messages via subscriptions. + *
    • An isolated data stream for Pub/Sub messages. + *
    • Messages are published to a topic. + *
    • Messages are listened to via a subscription. + *
    • Each subscription listens to the messages published to exactly one topic. */ export type PubSubTopic = string; @@ -23,7 +23,7 @@ export type PubSubSubscription = string; * Interface representing a Google Cloud Pub/Sub message. * * @param data - Payload of a Pub/Sub message. - * @param T - Type representing `Message.data`'s json format + * @typeParam T - Type representing `Message.data`'s JSON format */ export class Message { /** @@ -105,7 +105,7 @@ export class Message { /** * The interface published in a Pub/Sub publish subscription. - * @param T - Type representing `Message.data`'s json format + * @typeParam T - Type representing `Message.data`'s JSON format */ export interface MessagePublishedData { /** Google Cloud Pub/Sub message. */ @@ -124,7 +124,7 @@ export interface PubSubOptions extends options.EventHandlerOptions { * Handle a message being published to a Pub/Sub topic. * @param topic - The Pub/Sub topic to watch for message events. * @param handler - runs every time a Cloud Pub/Sub message is published - * @param T - Type representing `Message.data`'s json format + * @typeParam T - Type representing `Message.data`'s JSON format */ export function onMessagePublished( topic: PubSubTopic, @@ -135,7 +135,7 @@ export function onMessagePublished( * Handle a message being published to a Pub/Sub topic. * @param options - Option containing information (topic) for event * @param handler - runs every time a Cloud Pub/Sub message is published - * @param T - Type representing `Message.data`'s json format + * @typeParam T - Type representing `Message.data`'s JSON format */ export function onMessagePublished( options: PubSubOptions, @@ -146,7 +146,7 @@ export function onMessagePublished( * Handle a message being published to a Pub/Sub topic. * @param topicOrOptions - A string representing the PubSub topic or an option (which contains the topic) * @param handler - runs every time a Cloud Pub/Sub message is published - * @param T - Type representing `Message.data`'s json format + * @typeParam T - Type representing `Message.data`'s JSON format */ export function onMessagePublished( topicOrOptions: string | PubSubOptions,