From fc8e734c6916d3cb77446140d79e38a3dc1c63ce Mon Sep 17 00:00:00 2001 From: Tyler Stark Date: Mon, 9 May 2022 11:32:18 -0500 Subject: [PATCH 1/4] Update docs for v2 storage --- src/v2/providers/storage.ts | 26 ++++++++++++++++++++------ 1 file changed, 20 insertions(+), 6 deletions(-) diff --git a/src/v2/providers/storage.ts b/src/v2/providers/storage.ts index cc6f0a5ec..e4bda0c69 100644 --- a/src/v2/providers/storage.ts +++ b/src/v2/providers/storage.ts @@ -29,6 +29,7 @@ import * as options from '../options'; /** * An object within Google Cloud Storage. * Ref: https://github.com/googleapis/google-cloudevents-nodejs/blob/main/cloud/storage/v1/StorageObjectData.ts + * @beta */ export interface StorageObjectData { /** @@ -162,6 +163,7 @@ export interface StorageObjectData { /** * Metadata of customer-supplied encryption key, if the object is encrypted by * such a key. + * @beta */ export interface CustomerEncryption { /** @@ -174,7 +176,7 @@ export interface CustomerEncryption { keySha256?: string; } -/** A CloudEvent that contains StorageObjectData */ +/** @beta A CloudEvent that contains StorageObjectData */ export interface StorageEvent extends CloudEvent { /** The name of the bucket containing this object. */ bucket: string; @@ -190,26 +192,29 @@ export const deletedEvent = 'google.cloud.storage.object.v1.deleted'; export const metadataUpdatedEvent = 'google.cloud.storage.object.v1.metadataUpdated'; -/** StorageOptions extend EventHandlerOptions with a bucket name */ +/** @beta StorageOptions extend EventHandlerOptions with a bucket name */ export interface StorageOptions extends options.EventHandlerOptions { bucket?: string; } -/** Handle a storage object archived */ +/** @beta Handle a storage object archived */ export function onObjectArchived( handler: (event: StorageEvent) => any | Promise ): CloudFunction; +/** @beta Handle a storage object archived */ export function onObjectArchived( bucket: string, handler: (event: StorageEvent) => any | Promise ): CloudFunction; +/** @beta Handle a storage object archived */ export function onObjectArchived( opts: StorageOptions, handler: (event: StorageEvent) => any | Promise ): CloudFunction; +/** @beta Handle a storage object archived */ export function onObjectArchived( buketOrOptsOrHandler: | string @@ -220,21 +225,24 @@ export function onObjectArchived( return onOperation(archivedEvent, buketOrOptsOrHandler, handler); } -/** Handle a storage object finalized */ +/** @beta Handle a storage object finalized */ export function onObjectFinalized( handler: (event: StorageEvent) => any | Promise ): CloudFunction; +/** @beta Handle a storage object finalized */ export function onObjectFinalized( bucket: string, handler: (event: StorageEvent) => any | Promise ): CloudFunction; +/** @beta Handle a storage object finalized */ export function onObjectFinalized( opts: StorageOptions, handler: (event: StorageEvent) => any | Promise ): CloudFunction; +/** @beta Handle a storage object finalized */ export function onObjectFinalized( buketOrOptsOrHandler: | string @@ -245,21 +253,24 @@ export function onObjectFinalized( return onOperation(finalizedEvent, buketOrOptsOrHandler, handler); } -/** Handle a storage object deleted */ +/** @beta Handle a storage object deleted */ export function onObjectDeleted( handler: (event: StorageEvent) => any | Promise ): CloudFunction; +/** @beta Handle a storage object deleted */ export function onObjectDeleted( bucket: string, handler: (event: StorageEvent) => any | Promise ): CloudFunction; +/** @beta Handle a storage object deleted */ export function onObjectDeleted( opts: StorageOptions, handler: (event: StorageEvent) => any | Promise ): CloudFunction; +/** @beta Handle a storage object deleted */ export function onObjectDeleted( buketOrOptsOrHandler: | string @@ -270,21 +281,24 @@ export function onObjectDeleted( return onOperation(deletedEvent, buketOrOptsOrHandler, handler); } -/** Handle a storage object metadata updated */ +/** @beta Handle a storage object metadata updated */ export function onObjectMetadataUpdated( handler: (event: StorageEvent) => any | Promise ): CloudFunction; +/** @beta Handle a storage object metadata updated */ export function onObjectMetadataUpdated( bucket: string, handler: (event: StorageEvent) => any | Promise ): CloudFunction; +/** @beta Handle a storage object metadata updated */ export function onObjectMetadataUpdated( opts: StorageOptions, handler: (event: StorageEvent) => any | Promise ): CloudFunction; +/** @beta Handle a storage object metadata updated */ export function onObjectMetadataUpdated( buketOrOptsOrHandler: | string From 06a93e8bc89ee49e51060c79af2881ab2ab2881e Mon Sep 17 00:00:00 2001 From: Tyler Stark Date: Mon, 9 May 2022 14:21:39 -0500 Subject: [PATCH 2/4] Update docs to define args --- src/v2/providers/storage.ts | 176 ++++++++++++++++++++++++++++++++---- 1 file changed, 156 insertions(+), 20 deletions(-) diff --git a/src/v2/providers/storage.ts b/src/v2/providers/storage.ts index e4bda0c69..8849a6de4 100644 --- a/src/v2/providers/storage.ts +++ b/src/v2/providers/storage.ts @@ -29,7 +29,6 @@ import * as options from '../options'; /** * An object within Google Cloud Storage. * Ref: https://github.com/googleapis/google-cloudevents-nodejs/blob/main/cloud/storage/v1/StorageObjectData.ts - * @beta */ export interface StorageObjectData { /** @@ -163,7 +162,6 @@ export interface StorageObjectData { /** * Metadata of customer-supplied encryption key, if the object is encrypted by * such a key. - * @beta */ export interface CustomerEncryption { /** @@ -176,7 +174,7 @@ export interface CustomerEncryption { keySha256?: string; } -/** @beta A CloudEvent that contains StorageObjectData */ +/** A CloudEvent that contains StorageObjectData */ export interface StorageEvent extends CloudEvent { /** The name of the bucket containing this object. */ bucket: string; @@ -192,29 +190,61 @@ export const deletedEvent = 'google.cloud.storage.object.v1.deleted'; export const metadataUpdatedEvent = 'google.cloud.storage.object.v1.metadataUpdated'; -/** @beta StorageOptions extend EventHandlerOptions with a bucket name */ +/** StorageOptions extend EventHandlerOptions with a bucket name */ export interface StorageOptions extends options.EventHandlerOptions { + /** The name of the bucket containing this object. */ bucket?: string; } -/** @beta Handle a storage object archived */ +/** + * Event handler sent only when a bucket has enabled object versioning. + * This event indicates that the live version of an object has become an + * archived version, either because it was archived or because it was + * overwritten by the upload of an object of the same name. + * + * @param handler - Event handler which is run every time a Google Cloud Storage archival occurs. + */ export function onObjectArchived( handler: (event: StorageEvent) => any | Promise ): CloudFunction; -/** @beta Handle a storage object archived */ +/** + * Event handler sent only when a bucket has enabled object versioning. + * This event indicates that the live version of an object has become an + * archived version, either because it was archived or because it was + * overwritten by the upload of an object of the same name. + * + * @param bucket - The name of the bucket containing this object. + * @param handler - Event handler which is run every time a Google Cloud Storage archival occurs. + */ export function onObjectArchived( bucket: string, handler: (event: StorageEvent) => any | Promise ): CloudFunction; -/** @beta Handle a storage object archived */ +/** + * Event handler sent only when a bucket has enabled object versioning. + * This event indicates that the live version of an object has become an + * archived version, either because it was archived or because it was + * overwritten by the upload of an object of the same name. + * + * @param opts - Options that can be set on an individual event-handling Cloud Function. + * @param handler - Event handler which is run every time a Google Cloud Storage archival occurs. + */ export function onObjectArchived( opts: StorageOptions, handler: (event: StorageEvent) => any | Promise ): CloudFunction; -/** @beta Handle a storage object archived */ +/** + * Event handler sent only when a bucket has enabled object versioning. + * This event indicates that the live version of an object has become an + * archived version, either because it was archived or because it was + * overwritten by the upload of an object of the same name. + * + * @param buketOrOptsOrHandler - Options or string that may (or may not) define the bucket to be used. + * @param handler - Event handler which is run every time a Google Cloud Storage archival occurs. + */ export function onObjectArchived( buketOrOptsOrHandler: | string @@ -225,24 +255,63 @@ export function onObjectArchived( return onOperation(archivedEvent, buketOrOptsOrHandler, handler); } -/** @beta Handle a storage object finalized */ +/** + * Event handler which fires every time a Google Cloud Storage object + * creation occurs. + * + * Sent when a new object (or a new generation of an existing object) + * is successfully created in the bucket. This includes copying or rewriting + * an existing object. A failed upload does not trigger this event. + * + * @param handler - Event handler which is run every time a Google Cloud Storage object creation occurs. + */ export function onObjectFinalized( handler: (event: StorageEvent) => any | Promise ): CloudFunction; -/** @beta Handle a storage object finalized */ +/** + * Event handler which fires every time a Google Cloud Storage object + * creation occurs. + * + * Sent when a new object (or a new generation of an existing object) + * is successfully created in the bucket. This includes copying or rewriting + * an existing object. A failed upload does not trigger this event. + * + * @param bucket - The name of the bucket containing this object. + * @param handler - Event handler which is run every time a Google Cloud Storage object creation occurs. + */ export function onObjectFinalized( bucket: string, handler: (event: StorageEvent) => any | Promise ): CloudFunction; -/** @beta Handle a storage object finalized */ +/** + * Event handler which fires every time a Google Cloud Storage object + * creation occurs. + * + * Sent when a new object (or a new generation of an existing object) + * is successfully created in the bucket. This includes copying or rewriting + * an existing object. A failed upload does not trigger this event. + * + * @param opts - Options that can be set on an individual event-handling Cloud Function. + * @param handler - Event handler which is run every time a Google Cloud Storage object creation occurs. + */ export function onObjectFinalized( opts: StorageOptions, handler: (event: StorageEvent) => any | Promise ): CloudFunction; -/** @beta Handle a storage object finalized */ +/** + * Event handler which fires every time a Google Cloud Storage object + * creation occurs. + * + * Sent when a new object (or a new generation of an existing object) + * is successfully created in the bucket. This includes copying or rewriting + * an existing object. A failed upload does not trigger this event. + * + * @param buketOrOptsOrHandler - Options or string that may (or may not) define the bucket to be used. + * @param handler - Event handler which is run every time a Google Cloud Storage object creation occurs. + */ export function onObjectFinalized( buketOrOptsOrHandler: | string @@ -253,24 +322,67 @@ export function onObjectFinalized( return onOperation(finalizedEvent, buketOrOptsOrHandler, handler); } -/** @beta Handle a storage object deleted */ +/** + * Event handler which fires every time a Google Cloud Storage deletion occurs. + * + * Sent when an object has been permanently deleted. This includes objects + * that are overwritten or are deleted as part of the bucket's lifecycle + * configuration. For buckets with object versioning enabled, this is not + * sent when an object is archived, even if archival occurs + * via the `storage.objects.delete` method. + * + * @param handler - Event handler which is run every time a Google Cloud Storage object deletion occurs. + */ export function onObjectDeleted( handler: (event: StorageEvent) => any | Promise ): CloudFunction; -/** @beta Handle a storage object deleted */ +/** + * Event handler which fires every time a Google Cloud Storage deletion occurs. + * + * Sent when an object has been permanently deleted. This includes objects + * that are overwritten or are deleted as part of the bucket's lifecycle + * configuration. For buckets with object versioning enabled, this is not + * sent when an object is archived, even if archival occurs + * via the `storage.objects.delete` method. + * + * @param bucket - The name of the bucket containing this object. + * @param handler - Event handler which is run every time a Google Cloud Storage object deletion occurs. + */ export function onObjectDeleted( bucket: string, handler: (event: StorageEvent) => any | Promise ): CloudFunction; -/** @beta Handle a storage object deleted */ +/** + * Event handler which fires every time a Google Cloud Storage deletion occurs. + * + * Sent when an object has been permanently deleted. This includes objects + * that are overwritten or are deleted as part of the bucket's lifecycle + * configuration. For buckets with object versioning enabled, this is not + * sent when an object is archived, even if archival occurs + * via the `storage.objects.delete` method. + * + * @param opts - Options that can be set on an individual event-handling Cloud Function. + * @param handler - Event handler which is run every time a Google Cloud Storage object deletion occurs. + */ export function onObjectDeleted( opts: StorageOptions, handler: (event: StorageEvent) => any | Promise ): CloudFunction; -/** @beta Handle a storage object deleted */ +/** + * Event handler which fires every time a Google Cloud Storage deletion occurs. + * + * Sent when an object has been permanently deleted. This includes objects + * that are overwritten or are deleted as part of the bucket's lifecycle + * configuration. For buckets with object versioning enabled, this is not + * sent when an object is archived, even if archival occurs + * via the `storage.objects.delete` method. + * + * @param buketOrOptsOrHandler - Options or string that may (or may not) define the bucket to be used. + * @param handler - Event handler which is run every time a Google Cloud Storage object deletion occurs. + */ export function onObjectDeleted( buketOrOptsOrHandler: | string @@ -281,24 +393,48 @@ export function onObjectDeleted( return onOperation(deletedEvent, buketOrOptsOrHandler, handler); } -/** @beta Handle a storage object metadata updated */ +/** + * Event handler which fires every time the metadata of an existing object + * changes. + * + * @param buketOrOptsOrHandler - Options or string that may (or may not) define the bucket to be used. + * @param handler - Event handler which is run every time a Google Cloud Storage object metadata update occurs. + */ export function onObjectMetadataUpdated( handler: (event: StorageEvent) => any | Promise ): CloudFunction; -/** @beta Handle a storage object metadata updated */ +/** + * Event handler which fires every time the metadata of an existing object + * changes. + * + * @param bucket - The name of the bucket containing this object. + * @param handler - Event handler which is run every time a Google Cloud Storage object metadata update occurs. + */ export function onObjectMetadataUpdated( bucket: string, handler: (event: StorageEvent) => any | Promise ): CloudFunction; -/** @beta Handle a storage object metadata updated */ +/** + * Event handler which fires every time the metadata of an existing object + * changes. + * + * @param opts - Options that can be set on an individual event-handling Cloud Function. + * @param handler - Event handler which is run every time a Google Cloud Storage object metadata update occurs. + */ export function onObjectMetadataUpdated( opts: StorageOptions, handler: (event: StorageEvent) => any | Promise ): CloudFunction; -/** @beta Handle a storage object metadata updated */ +/** + * Event handler which fires every time the metadata of an existing object + * changes. + * + * @param buketOrOptsOrHandler - Options or string that may (or may not) define the bucket to be used. + * @param handler - Event handler which is run every time a Google Cloud Storage object metadata update occurs. + */ export function onObjectMetadataUpdated( buketOrOptsOrHandler: | string From ec94ff890fa8d1085d03743e2ad2776ef8efa77b Mon Sep 17 00:00:00 2001 From: Tyler Stark Date: Tue, 10 May 2022 10:00:04 -0500 Subject: [PATCH 3/4] Fix Typo Buket -> Bucket --- src/v2/providers/storage.ts | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/src/v2/providers/storage.ts b/src/v2/providers/storage.ts index 8849a6de4..62c4c49ea 100644 --- a/src/v2/providers/storage.ts +++ b/src/v2/providers/storage.ts @@ -242,17 +242,17 @@ export function onObjectArchived( * archived version, either because it was archived or because it was * overwritten by the upload of an object of the same name. * - * @param buketOrOptsOrHandler - Options or string that may (or may not) define the bucket to be used. + * @param bucketOrOptsOrHandler - Options or string that may (or may not) define the bucket to be used. * @param handler - Event handler which is run every time a Google Cloud Storage archival occurs. */ export function onObjectArchived( - buketOrOptsOrHandler: + bucketOrOptsOrHandler: | string | StorageOptions | ((event: StorageEvent) => any | Promise), handler?: (event: StorageEvent) => any | Promise ): CloudFunction { - return onOperation(archivedEvent, buketOrOptsOrHandler, handler); + return onOperation(archivedEvent, bucketOrOptsOrHandler, handler); } /** @@ -309,17 +309,17 @@ export function onObjectFinalized( * is successfully created in the bucket. This includes copying or rewriting * an existing object. A failed upload does not trigger this event. * - * @param buketOrOptsOrHandler - Options or string that may (or may not) define the bucket to be used. + * @param bucketOrOptsOrHandler - Options or string that may (or may not) define the bucket to be used. * @param handler - Event handler which is run every time a Google Cloud Storage object creation occurs. */ export function onObjectFinalized( - buketOrOptsOrHandler: + bucketOrOptsOrHandler: | string | StorageOptions | ((event: StorageEvent) => any | Promise), handler?: (event: StorageEvent) => any | Promise ): CloudFunction { - return onOperation(finalizedEvent, buketOrOptsOrHandler, handler); + return onOperation(finalizedEvent, bucketOrOptsOrHandler, handler); } /** @@ -380,24 +380,24 @@ export function onObjectDeleted( * sent when an object is archived, even if archival occurs * via the `storage.objects.delete` method. * - * @param buketOrOptsOrHandler - Options or string that may (or may not) define the bucket to be used. + * @param bucketOrOptsOrHandler - Options or string that may (or may not) define the bucket to be used. * @param handler - Event handler which is run every time a Google Cloud Storage object deletion occurs. */ export function onObjectDeleted( - buketOrOptsOrHandler: + bucketOrOptsOrHandler: | string | StorageOptions | ((event: StorageEvent) => any | Promise), handler?: (event: StorageEvent) => any | Promise ): CloudFunction { - return onOperation(deletedEvent, buketOrOptsOrHandler, handler); + return onOperation(deletedEvent, bucketOrOptsOrHandler, handler); } /** * Event handler which fires every time the metadata of an existing object * changes. * - * @param buketOrOptsOrHandler - Options or string that may (or may not) define the bucket to be used. + * @param bucketOrOptsOrHandler - Options or string that may (or may not) define the bucket to be used. * @param handler - Event handler which is run every time a Google Cloud Storage object metadata update occurs. */ export function onObjectMetadataUpdated( @@ -432,17 +432,17 @@ export function onObjectMetadataUpdated( * Event handler which fires every time the metadata of an existing object * changes. * - * @param buketOrOptsOrHandler - Options or string that may (or may not) define the bucket to be used. + * @param bucketOrOptsOrHandler - Options or string that may (or may not) define the bucket to be used. * @param handler - Event handler which is run every time a Google Cloud Storage object metadata update occurs. */ export function onObjectMetadataUpdated( - buketOrOptsOrHandler: + bucketOrOptsOrHandler: | string | StorageOptions | ((event: StorageEvent) => any | Promise), handler?: (event: StorageEvent) => any | Promise ): CloudFunction { - return onOperation(metadataUpdatedEvent, buketOrOptsOrHandler, handler); + return onOperation(metadataUpdatedEvent, bucketOrOptsOrHandler, handler); } /** @internal */ From 34a9e0cd788616b55a20715cea2e2b6272528eec Mon Sep 17 00:00:00 2001 From: Tyler Stark Date: Tue, 10 May 2022 10:02:01 -0500 Subject: [PATCH 4/4] Update comments per pr feedback --- src/v2/providers/storage.ts | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/v2/providers/storage.ts b/src/v2/providers/storage.ts index 62c4c49ea..27e6d01dc 100644 --- a/src/v2/providers/storage.ts +++ b/src/v2/providers/storage.ts @@ -228,7 +228,7 @@ export function onObjectArchived( * archived version, either because it was archived or because it was * overwritten by the upload of an object of the same name. * - * @param opts - Options that can be set on an individual event-handling Cloud Function. + * @param opts - Options that can be set on an individual event-handling function. * @param handler - Event handler which is run every time a Google Cloud Storage archival occurs. */ export function onObjectArchived( @@ -293,7 +293,7 @@ export function onObjectFinalized( * is successfully created in the bucket. This includes copying or rewriting * an existing object. A failed upload does not trigger this event. * - * @param opts - Options that can be set on an individual event-handling Cloud Function. + * @param opts - Options that can be set on an individual event-handling function. * @param handler - Event handler which is run every time a Google Cloud Storage object creation occurs. */ export function onObjectFinalized( @@ -363,7 +363,7 @@ export function onObjectDeleted( * sent when an object is archived, even if archival occurs * via the `storage.objects.delete` method. * - * @param opts - Options that can be set on an individual event-handling Cloud Function. + * @param opts - Options that can be set on an individual event-handling function. * @param handler - Event handler which is run every time a Google Cloud Storage object deletion occurs. */ export function onObjectDeleted( @@ -420,7 +420,7 @@ export function onObjectMetadataUpdated( * Event handler which fires every time the metadata of an existing object * changes. * - * @param opts - Options that can be set on an individual event-handling Cloud Function. + * @param opts - Options that can be set on an individual event-handling function. * @param handler - Event handler which is run every time a Google Cloud Storage object metadata update occurs. */ export function onObjectMetadataUpdated(