From d3bde7bd9f44f9e16cdbc507525e1f928c2323e7 Mon Sep 17 00:00:00 2001 From: Venkata Ramyasri Kota <34170013+kvramyasri7@users.noreply.github.com> Date: Thu, 7 Sep 2023 13:08:45 -0700 Subject: [PATCH] chore(storage): add clear documentation to storage apis (#11982) chore(storage): add clear documentation to storage apis --------- Co-authored-by: AllanZhengYP --- packages/storage/src/providers/s3/apis/getUrl.ts | 9 ++++++--- packages/storage/src/providers/s3/apis/list.ts | 6 +++--- packages/storage/src/providers/s3/apis/remove.ts | 2 +- 3 files changed, 10 insertions(+), 7 deletions(-) diff --git a/packages/storage/src/providers/s3/apis/getUrl.ts b/packages/storage/src/providers/s3/apis/getUrl.ts index 64d8394a2e4..9c87b12a467 100644 --- a/packages/storage/src/providers/s3/apis/getUrl.ts +++ b/packages/storage/src/providers/s3/apis/getUrl.ts @@ -7,7 +7,12 @@ import { S3GetUrlOptions, S3GetUrlResult } from '../types'; import { getUrl as getUrlInternal } from './internal/getUrl'; /** - * Get Presigned url of the object + * Get a temporary presigned URL to download the specified S3 object. + * The presigned URL expires when the associated role used to sign the request expires or + * the option `expiresIn` is reached. The `expiresAt` property in the output object indicates when the URL MAY expire. + * By default, it will not validate the object that exists in S3. If you set the `options.validateObjectExistence` + * to true, this method will verify the given object already exists in S3 before returning a presigned + * URL, and will throw {@link StorageError} if the object does not exist. * * @param {StorageDownloadDataRequest} The request object * @return {Promise} url of the object @@ -15,8 +20,6 @@ import { getUrl as getUrlInternal } from './internal/getUrl'; * @throws validation: {@link StorageValidationErrorCode } - Validation errors * thrown either username or key are not defined. * - * TODO: add config errors - * */ export const getUrl = ( req: StorageDownloadDataRequest diff --git a/packages/storage/src/providers/s3/apis/list.ts b/packages/storage/src/providers/s3/apis/list.ts index 32ed1b83996..f54f78f0678 100644 --- a/packages/storage/src/providers/s3/apis/list.ts +++ b/packages/storage/src/providers/s3/apis/list.ts @@ -12,10 +12,10 @@ import { list as listInternal } from './internal/list'; type S3ListApi = { /** - * Lists bucket objects with pagination. + * List files with given prefix in pages + * pageSize defaulted to 1000. Additionally, the result will include a nextToken if there are more items to retrieve. * @param {StorageListRequest} req - The request object * @return {Promise} - Promise resolves to list of keys and metadata with - * pageSize defaulting to 1000. Additionally the result will include a nextToken if there are more items to retrieve * @throws service: {@link S3Exception} - S3 service errors thrown when checking for existence of bucket * @throws validation: {@link StorageValidationErrorCode } - thrown when there are issues with credentials */ @@ -23,7 +23,7 @@ type S3ListApi = { req?: StorageListRequest ): Promise; /** - * Lists all bucket objects. + * List all files from S3. You can set `listAll` to true in `options` to get all the files from S3. * @param {StorageListRequest} req - The request object * @return {Promise} - Promise resolves to list of keys and metadata for all objects in path * @throws service: {@link S3Exception} - S3 service errors thrown when checking for existence of bucket diff --git a/packages/storage/src/providers/s3/apis/remove.ts b/packages/storage/src/providers/s3/apis/remove.ts index c0bf4ed1938..76d0a75b3a2 100644 --- a/packages/storage/src/providers/s3/apis/remove.ts +++ b/packages/storage/src/providers/s3/apis/remove.ts @@ -10,7 +10,7 @@ import { import { remove as removeInternal } from './internal/remove'; /** - * Remove the object that is specified by the `req`. + * Remove a file from your S3 bucket. * @param {StorageOperationRequest} req - The request object * @return {Promise} - Promise resolves upon successful removal of the object * @throws service: {@link S3Exception} - S3 service errors thrown while getting properties