@aws-amplify/storage 6.0.1-preview-testing.64b45b1.0 → 6.0.1-preview-testing.ddb17c0.0

package/src/providers/s3/apis/list.ts

@@ -14,16 +14,16 @@ type ListApi = {
 	/**
 	 * 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 {ListPaginateInput} The input object
-	 * @return {Promise<ListPaginateOutput>} - Promise resolves to list of keys and metadata with
+	 * @param input - The ListPaginateInput object.
+	 * @returns A list of keys and metadata with
 	 * @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
 	 */
 	(input?: ListPaginateInput): Promise<ListPaginateOutput>;
 	/**
 	 * List all files from S3. You can set `listAll` to true in `options` to get all the files from S3.
-	 * @param {ListAllInput} The input object
-	 * @return {Promise<ListAllOutput>} - Promise resolves to list of keys and metadata for all objects in path
+	 * @param input - The ListAllInput object.
+	 * @returns A list of keys and metadata for all objects in path
 	 * @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
 	 */

package/src/providers/s3/apis/remove.ts

@@ -7,8 +7,8 @@ import { remove as removeInternal } from './internal/remove';
 
 /**
  * Remove a file from your S3 bucket.
- * @param {RemoveInput} The input object
- * @return {Promise<RemoveOutput>} - Promise resolves upon successful removal of the object
+ * @param input - The RemoveInput object.
+ * @return Output containing the removed object key
  * @throws service: {@link S3Exception} - S3 service errors thrown while getting properties
  * @throws validation: {@link StorageValidationErrorCode } - Validation errors thrown
  */

package/src/providers/s3/apis/uploadData/index.ts

@@ -1,7 +1,7 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-import { UploadDataInput, UploadDataOutput } from '../../types';
+import { UploadDataInput, UploadDataOutput, S3Exception } from '../../types';
 import { createUploadTask } from '../../utils';
 import { assertValidationError } from '../../../../errors/utils/assertValidationError';
 import { StorageValidationErrorCode } from '../../../../errors/types/validation';
@@ -18,9 +18,8 @@ import { getMultipartUploadHandlers } from './multipart';
  * * Maximum object size is 5TB.
  * * Maximum object size if the size cannot be determined before upload is 50GB.
  *
- * @param {UploadDataInput} The input parameters that are passed to the
- * 	uploadData operation.
- * @returns {UploadDataOutput} Cancelable and Resumable task exposing result promise from `result`
+ * @param input - The UploadDataInput object.
+ * @returns A cancelable and resumable task exposing result promise from `result`
  * 	property.
  * @throws service: {@link S3Exception} - thrown when checking for existence of the object
  * @throws validation: {@link StorageValidationErrorCode } - Validation errors.

package/src/providers/s3/types/index.ts

@@ -9,6 +9,8 @@ export {
 	ListPaginateOptions,
 	RemoveOptions,
 	DownloadDataOptions,
+	CopyDestinationOptions,
+	CopySourceOptions,
 } from './options';
 export {
 	DownloadDataOutput,

package/src/providers/s3/types/inputs.ts

@@ -18,21 +18,51 @@ import {
 	RemoveOptions,
 	DownloadDataOptions,
 	UploadDataOptions,
+	CopyDestinationOptions,
+	CopySourceOptions,
 } from '../types';
 
-export type CopyInput = StorageCopyInput;
+// TODO: support use accelerate endpoint option
+/**
+ * Input type for S3 copy API.
+ */
+export type CopyInput = StorageCopyInput<
+	CopySourceOptions,
+	CopyDestinationOptions
+>;
 
+/**
+ * Input type for S3 getProperties API.
+ */
 export type GetPropertiesInput =
 	StorageGetPropertiesInput<GetPropertiesOptions>;
 
+/**
+ * Input type for S3 getUrl API.
+ */
 export type GetUrlInput = StorageGetUrlInput<GetUrlOptions>;
 
+/**
+ * Input type for S3 list API. Lists all bucket objects.
+ */
 export type ListAllInput = StorageListInput<ListAllOptions>;
 
+/**
+ * Input type for S3 list API. Lists bucket objects with pagination.
+ */
 export type ListPaginateInput = StorageListInput<ListPaginateOptions>;
 
+/**
+ * Input type for S3 remove API.
+ */
 export type RemoveInput = StorageRemoveInput<RemoveOptions>;
 
+/**
+ * Input type for S3 downloadData API.
+ */
 export type DownloadDataInput = StorageDownloadDataInput<DownloadDataOptions>;
 
+/**
+ * Input type for S3 uploadData API.
+ */
 export type UploadDataInput = StorageUploadDataInput<UploadDataOptions>;

package/src/providers/s3/types/options.ts

@@ -1,20 +1,17 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
+import { StorageAccessLevel } from '@aws-amplify/core';
 // TODO(ashwinkumar6) this uses V5 Credentials, update to V6.
 import { Credentials } from '@aws-sdk/types';
 
 import { TransferProgressEvent } from '../../../types';
 import {
-	StorageOptions,
 	StorageListAllOptions,
 	StorageListPaginateOptions,
 } from '../../../types/options';
 
-/**
- * Input options type for S3 Storage operations.
- */
-export type Options = StorageOptions & {
+type CommonOptions = {
 	/**
 	 * Whether to use accelerate endpoint.
 	 * @default false
@@ -22,68 +19,101 @@ export type Options = StorageOptions & {
 	useAccelerateEndpoint?: boolean;
 };
 
+type ReadOptions =
+	| { accessLevel?: 'guest' | 'private' }
+	| { accessLevel: 'protected'; targetIdentityId?: string };
+
+type WriteOptions = {
+	accessLevel?: StorageAccessLevel;
+};
+
+/**
+ * Transfer-related options type for S3 downloadData, uploadData APIs.
+ */
+type TransferOptions = {
+	/**
+	 * Callback function tracking the upload/download progress.
+	 */
+	onProgress?: (event: TransferProgressEvent) => void;
+};
+
 /**
  * Input options type for S3 getProperties API.
  */
-export type GetPropertiesOptions = Options;
+export type GetPropertiesOptions = ReadOptions & CommonOptions;
 
 /**
  * Input options type for S3 getProperties API.
  */
-export type RemoveOptions = Options;
+export type RemoveOptions = WriteOptions & CommonOptions;
 
 /**
  * Input options type for S3 list API.
  */
-export type ListAllOptions = StorageListAllOptions;
+export type ListAllOptions = StorageListAllOptions &
+	ReadOptions &
+	CommonOptions;
 
 /**
  * Input options type for S3 list API.
  */
-export type ListPaginateOptions = StorageListPaginateOptions;
+export type ListPaginateOptions = StorageListPaginateOptions &
+	ReadOptions &
+	CommonOptions;
 
 /**
- * Input options type for S3 downloadData API.
+ * Input options type for S3 getUrl API.
  */
-export type DownloadDataOptions = TransferOptions;
+export type GetUrlOptions = ReadOptions &
+	CommonOptions & {
+		/**
+		 * Whether to head object to make sure the object existence before downloading.
+		 * @default false
+		 */
+		validateObjectExistence?: boolean;
+		/**
+		 * Number of seconds till the URL expires.
+		 * @default 900 (15 minutes)
+		 */
+		expiresIn?: number;
+	};
 
 /**
- * Input options type for S3 getUrl API.
+ * Input options type for S3 downloadData API.
  */
-export type GetUrlOptions = Options & {
-	/**
-	 * Whether to head object to make sure the object existence before downloading.
-	 * @default false
-	 */
-	validateObjectExistence?: boolean;
-	/**
-	 * Number of seconds till the URL expires.
-	 * @default 900 (15 minutes)
-	 */
-	expiresIn?: number;
+export type DownloadDataOptions = ReadOptions & CommonOptions & TransferOptions;
+
+export type UploadDataOptions = WriteOptions &
+	CommonOptions &
+	TransferOptions & {
+		/**
+		 * The default content-disposition header value of the file when downloading it.
+		 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition
+		 */
+		contentDisposition?: string;
+		/**
+		 * The default content-encoding header value of the file when downloading it.
+		 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding
+		 */
+		contentEncoding?: string;
+		/**
+		 * The default content-type header value of the file when downloading it.
+		 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type
+		 */
+		contentType?: string;
+		/**
+		 * The user-defined metadata for the object uploaded to S3.
+		 * @see https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingMetadata.html#UserMetadata
+		 */
+		metadata?: Record<string, string>;
+	};
+
+export type CopySourceOptions = ReadOptions & {
+	key: string;
 };
 
-export type UploadDataOptions = Omit<TransferOptions, 'targetIdentityId'> & {
-	/**
-	 * The default content-disposition header value of the file when downloading it.
-	 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition
-	 */
-	contentDisposition?: string;
-	/**
-	 * The default content-encoding header value of the file when downloading it.
-	 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding
-	 */
-	contentEncoding?: string;
-	/**
-	 * The default content-type header value of the file when downloading it.
-	 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type
-	 */
-	contentType?: string;
-	/**
-	 * The user-defined metadata for the object uploaded to S3.
-	 * @see https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingMetadata.html#UserMetadata
-	 */
-	metadata?: Record<string, string>;
+export type CopyDestinationOptions = WriteOptions & {
+	key: string;
 };
 
 /**
@@ -98,12 +128,3 @@ export type ResolvedS3Config = {
 	forcePathStyle?: boolean;
 	useAccelerateEndpoint?: boolean;
 };
-/**
- * Input options type for S3 downloadData, uploadData APIs.
- */
-type TransferOptions = Options & {
-	/**
-	 * Callback function tracking the upload/download progress.
-	 */
-	onProgress?: (event: TransferProgressEvent) => void;
-};

package/src/providers/s3/types/outputs.ts

@@ -10,6 +10,9 @@ import {
 	UploadTask,
 } from '../../../types';
 
+/**
+ * type for S3 item.
+ */
 export interface Item extends StorageItem {
 	/**
 	 * VersionId used to reference a specific version of the object.
@@ -21,22 +24,49 @@ export interface Item extends StorageItem {
 	contentType?: string;
 }
 
+/**
+ * type for S3 list item.
+ */
+export type ListOutputItem = Omit<StorageItem, 'metadata'>;
+
+/**
+ * Output type for S3 downloadData API.
+ */
 export type DownloadDataOutput = DownloadTask<StorageDownloadDataOutput<Item>>;
 
+/**
+ * Output type for S3 getUrl API.
+ */
 export type GetUrlOutput = StorageGetUrlOutput;
 
+/**
+ * Output type for S3 uploadData API.
+ */
 export type UploadDataOutput = UploadTask<Item>;
 
+/**
+ * Output type for S3 getProperties API.
+ */
 export type GetPropertiesOutput = Item;
 
-export type ListOutputItem = Omit<StorageItem, 'metadata'>;
-
+/**
+ * Output type for S3 list API. Lists all bucket objects.
+ */
 export type ListAllOutput = StorageListOutput<ListOutputItem>;
 
+/**
+ * Output type for S3 list API. Lists bucket objects with pagination.
+ */
 export type ListPaginateOutput = StorageListOutput<ListOutputItem> & {
 	nextToken?: string;
 };
 
-// TODO: expose more properties if required
+/**
+ * Output type for S3 copy API.
+ */
 export type CopyOutput = Pick<Item, 'key'>;
+
+/**
+ * Output type for S3 remove API.
+ */
 export type RemoveOutput = Pick<Item, 'key'>;

package/src/providers/s3/utils/transferTask.ts

@@ -19,20 +19,16 @@ const createCancellableTask = <Result>({
 	job,
 	onCancel,
 }: CreateCancellableTaskOptions<Result>): CancellableTask<Result> => {
-	const state = TransferTaskState.IN_PROGRESS;
+	const state = 'IN_PROGRESS' as TransferTaskState;
 	let abortErrorOverwriteRecord: Error | undefined = undefined;
 	const cancelableTask = {
 		cancel: (abortErrorOverwrite?: Error) => {
 			abortErrorOverwriteRecord = abortErrorOverwrite;
 			const { state } = cancelableTask;
-			if (
-				state === TransferTaskState.CANCELED ||
-				state === TransferTaskState.ERROR ||
-				state === TransferTaskState.SUCCESS
-			) {
+			if (state === 'CANCELED' || state === 'ERROR' || state === 'SUCCESS') {
 				return;
 			}
-			cancelableTask.state = TransferTaskState.CANCELED;
+			cancelableTask.state = 'CANCELED';
 			onCancel(abortErrorOverwrite);
 		},
 		state,
@@ -41,14 +37,14 @@ const createCancellableTask = <Result>({
 	const wrappedJobPromise = (async () => {
 		try {
 			const result = await job();
-			cancelableTask.state = TransferTaskState.SUCCESS;
+			cancelableTask.state = 'SUCCESS';
 			return result;
 		} catch (e) {
 			if (isCancelError(e)) {
-				cancelableTask.state = TransferTaskState.CANCELED;
+				cancelableTask.state = 'CANCELED';
 				throw abortErrorOverwriteRecord ?? e;
 			}
-			cancelableTask.state = TransferTaskState.ERROR;
+			cancelableTask.state = 'ERROR';
 			throw e;
 		}
 	})();
@@ -83,20 +79,20 @@ export const createUploadTask = <Result>({
 	const uploadTask = Object.assign(cancellableTask, {
 		pause: () => {
 			const { state } = uploadTask;
-			if (!isMultipartUpload || state !== TransferTaskState.IN_PROGRESS) {
+			if (!isMultipartUpload || state !== 'IN_PROGRESS') {
 				return;
 			}
 			// @ts-ignore
-			uploadTask.state = TransferTaskState.PAUSED;
+			uploadTask.state = 'PAUSED';
 			onPause?.();
 		},
 		resume: () => {
 			const { state } = uploadTask;
-			if (!isMultipartUpload || state !== TransferTaskState.PAUSED) {
+			if (!isMultipartUpload || state !== 'PAUSED') {
 				return;
 			}
 			// @ts-ignore
-			uploadTask.state = TransferTaskState.IN_PROGRESS;
+			uploadTask.state = 'IN_PROGRESS';
 			onResume?.();
 		},
 	});

package/src/types/common.ts

@@ -1,13 +1,12 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-export enum TransferTaskState {
-	IN_PROGRESS = 'IN_PROGRESS',
-	PAUSED = 'PAUSED',
-	CANCELED = 'CANCELED',
-	SUCCESS = 'SUCCESS',
-	ERROR = 'ERROR',
-}
+export type TransferTaskState =
+	| 'IN_PROGRESS'
+	| 'PAUSED'
+	| 'CANCELED'
+	| 'SUCCESS'
+	| 'ERROR';
 
 export type TransferProgressEvent = {
 	transferredBytes: number;

package/src/types/index.ts

@@ -23,8 +23,6 @@ export {
 	StorageRemoveOptions,
 	StorageListAllOptions,
 	StorageListPaginateOptions,
-	StorageCopySourceOptions,
-	StorageCopyDestinationOptions,
 } from './options';
 export {
 	StorageItem,

package/src/types/inputs.ts

@@ -5,8 +5,6 @@ import {
 	StorageOptions,
 	StorageListAllOptions,
 	StorageListPaginateOptions,
-	StorageCopySourceOptions,
-	StorageCopyDestinationOptions,
 } from './options';
 
 export type StorageOperationInput<Options extends StorageOptions> = {
@@ -17,8 +15,10 @@ export type StorageOperationInput<Options extends StorageOptions> = {
 export type StorageGetPropertiesInput<Options extends StorageOptions> =
 	StorageOperationInput<Options>;
 
-export type StorageRemoveInput<Options extends StorageOptions> =
-	StorageOperationInput<Options>;
+export type StorageRemoveInput<Options extends StorageOptions> = {
+	key: string;
+	options?: Options;
+};
 
 export type StorageListInput<
 	Options extends StorageListAllOptions | StorageListPaginateOptions
@@ -38,9 +38,12 @@ export type StorageUploadDataInput<Options extends StorageOptions> =
 		data: StorageUploadDataPayload;
 	};
 
-export type StorageCopyInput = {
-	source: StorageCopySourceOptions;
-	destination: StorageCopyDestinationOptions;
+export type StorageCopyInput<
+	SourceOptions extends StorageOptions,
+	DestinationOptions extends StorageOptions
+> = {
+	source: SourceOptions;
+	destination: DestinationOptions;
 };
 
 /**

package/src/types/options.ts

@@ -3,12 +3,9 @@
 
 import { StorageAccessLevel } from '@aws-amplify/core';
 
-export type StorageOptions =
-	| { accessLevel?: 'guest' | 'private' }
-	| {
-			accessLevel: 'protected';
-			targetIdentityId?: string;
-	  };
+export type StorageOptions = {
+	accessLevel?: StorageAccessLevel;
+};
 
 export type StorageListAllOptions = StorageOptions & {
 	listAll: true;
@@ -20,13 +17,4 @@ export type StorageListPaginateOptions = StorageOptions & {
 	nextToken?: string;
 };
 
-export type StorageRemoveOptions = Omit<StorageOptions, 'targetIdentityId'>;
-
-export type StorageCopySourceOptions = {
-	key: string;
-} & StorageOptions;
-
-export type StorageCopyDestinationOptions = {
-	key: string;
-	accessLevel?: StorageAccessLevel;
-};
+export type StorageRemoveOptions = StorageOptions;