diff --git a/src/v2/providers/storage.ts b/src/v2/providers/storage.ts index cc6f0a5ec..27e6d01dc 100644 --- a/src/v2/providers/storage.ts +++ b/src/v2/providers/storage.ts @@ -192,107 +192,257 @@ export const metadataUpdatedEvent = /** StorageOptions extend EventHandlerOptions with a bucket name */ export interface StorageOptions extends options.EventHandlerOptions { + /** The name of the bucket containing this object. */ bucket?: string; } -/** 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; +/** + * 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; +/** + * 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 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; +/** + * 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 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); } -/** 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; +/** + * 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; +/** + * 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 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; +/** + * 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 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); } -/** 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; +/** + * 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; +/** + * 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 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; +/** + * 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 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); } -/** Handle a storage object metadata updated */ +/** + * Event handler which fires every time the metadata of an existing object + * changes. + * + * @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( handler: (event: StorageEvent) => any | Promise ): CloudFunction; +/** + * 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; +/** + * 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 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; +/** + * Event handler which fires every time the metadata of an existing object + * changes. + * + * @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 */