feat(storage): add new internal downloadData api

packages/storage/__tests__/internals/apis/downloadData.test.ts

@@ -0,0 +1,76 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { downloadData as advancedDownloadData } from '../../../src/internals';
+import { downloadData as downloadDataInternal } from '../../../src/providers/s3/apis/internal/downloadData';
+
+jest.mock('../../../src/providers/s3/apis/internal/downloadData');
+const mockedDownloadDataInternal = jest.mocked(downloadDataInternal);
+
+describe('remove (internal)', () => {
+	beforeEach(() => {
+		mockedDownloadDataInternal.mockReturnValue({
+			result: Promise.resolve({
+				path: 'output/path/to/mock/object',
+				body: {
+					blob: () => Promise.resolve(new Blob()),
+					json: () => Promise.resolve(''),
+					text: () => Promise.resolve(''),
+				},
+			}),
+			cancel: jest.fn(),
+			state: 'SUCCESS',
+		});
+	});
+
+	afterEach(() => {
+		jest.clearAllMocks();
+	});
+
+	it('should pass advanced option locationCredentialsProvider to internal downloadData', async () => {
+		const useAccelerateEndpoint = true;
+		const bucket = { bucketName: 'bucket', region: 'us-east-1' };
+		const locationCredentialsProvider = async () => ({
+			credentials: {
+				accessKeyId: 'akid',
+				secretAccessKey: 'secret',
+				sessionToken: 'token',
+				expiration: new Date(),
+			},
+		});
+		const onProgress = jest.fn();
+		const bytesRange = { start: 1024, end: 2048 };
+
+		const output = await advancedDownloadData({
+			path: 'input/path/to/mock/object',
+			options: {
+				useAccelerateEndpoint,
+				bucket,
+				locationCredentialsProvider,
+				onProgress,
+				bytesRange,
+			},
+		});
+
+		expect(mockedDownloadDataInternal).toHaveBeenCalledTimes(1);
+		expect(mockedDownloadDataInternal).toHaveBeenCalledWith({
+			path: 'input/path/to/mock/object',
+			options: {
+				useAccelerateEndpoint,
+				bucket,
+				locationCredentialsProvider,
+				onProgress,
+				bytesRange,
+			},
+		});
+
+		expect(await output.result).toEqual({
+			path: 'output/path/to/mock/object',
+			body: {
+				blob: expect.any(Function),
+				json: expect.any(Function),
+				text: expect.any(Function),
+			},
+		});
+	});
+});

packages/storage/src/internals/apis/downloadData.ts

@@ -0,0 +1,52 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { downloadData as downloadDataInternal } from '../../providers/s3/apis/internal/downloadData';
+import { DownloadDataInput } from '../types/inputs';
+import { DownloadDataOutput } from '../types/outputs';
+
+/**
+ * Download S3 object data to memory
+ *
+ * @param input - The `DownloadDataWithPathInput` object.
+ * @returns A cancelable task exposing result promise from `result` property.
+ * @throws service: `S3Exception` - thrown when checking for existence of the object
+ * @throws validation: `StorageValidationErrorCode` - Validation errors
+ *
+ * @example
+ * ```ts
+ * // Download a file from s3 bucket
+ * const { body, eTag } = await downloadData({ path, options: {
+ *   onProgress, // Optional progress callback.
+ * } }).result;
+ * ```
+ * @example
+ * ```ts
+ * // Cancel a task
+ * const downloadTask = downloadData({ path });
+ * //...
+ * downloadTask.cancel();
+ * try {
+ * 	await downloadTask.result;
+ * } catch (error) {
+ * 	if(isCancelError(error)) {
+ *    // Handle error thrown by task cancelation.
+ * 	}
+ * }
+ *```
+ *
+ * @internal
+ */
+export const downloadData = (input: DownloadDataInput): DownloadDataOutput =>
+	downloadDataInternal({
+		path: input.path,
+		options: {
+			useAccelerateEndpoint: input?.options?.useAccelerateEndpoint,
+			bucket: input?.options?.bucket,
+			locationCredentialsProvider: input?.options?.locationCredentialsProvider,
+			bytesRange: input?.options?.bytesRange,
+			onProgress: input?.options?.onProgress,
+		},
+		// Type casting is necessary because `removeInternal` supports both Gen1 and Gen2 signatures, but here
+		// given in input can only be Gen2 signature, the return can only ben Gen2 signature.
+	}) as DownloadDataOutput;

packages/storage/src/internals/index.ts

@@ -14,18 +14,21 @@ export {
 	GetPropertiesInput,
 	CopyInput,
 	RemoveInput,
+	DownloadDataInput,
 } from './types/inputs';
 export {
 	GetDataAccessOutput,
 	ListCallerAccessGrantsOutput,
 	GetPropertiesOutput,
 	RemoveOutput,
+	DownloadDataOutput,
 } from './types/outputs';
 
 export { getDataAccess } from './apis/getDataAccess';
 export { listCallerAccessGrants } from './apis/listCallerAccessGrants';
 export { getProperties } from './apis/getProperties';
 export { remove } from './apis/remove';
+export { downloadData } from './apis/downloadData';
 
 /*
 CredentialsStore exports

packages/storage/src/internals/types/inputs.ts

@@ -8,6 +8,7 @@ import {
 } from '../../types/inputs';
 import {
 	CopyWithPathInput,
+	DownloadDataWithPathInput,
 	GetPropertiesWithPathInput,
 	RemoveWithPathInput,
 } from '../../providers/s3';
@@ -68,6 +69,16 @@ export type CopyInput = ExtendCopyInputWithAdvancedOptions<
 	}
 >;
 
+/**
+ * @internal
+ */
+export type DownloadDataInput = ExtendInputWithAdvancedOptions<
+	DownloadDataWithPathInput,
+	{
+		locationCredentialsProvider?: CredentialsProvider;
+	}
+>;
+
 /**
  * Generic types that extend the public non-copy API input types with extended
  * options. This is a temporary solution to support advanced options from internal APIs.

packages/storage/src/internals/types/outputs.ts

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import {
+	DownloadDataWithPathOutput,
 	GetPropertiesWithPathOutput,
 	RemoveWithPathOutput,
 } from '../../providers/s3/types';
@@ -27,3 +28,8 @@ export type GetPropertiesOutput = GetPropertiesWithPathOutput;
  * @internal
  */
 export type RemoveOutput = RemoveWithPathOutput;
+
+/**
+ * @internal
+ */
+export type DownloadDataOutput = DownloadDataWithPathOutput;

packages/storage/src/providers/s3/apis/downloadData.ts

@@ -1,26 +1,14 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-import { Amplify } from '@aws-amplify/core';
-import { StorageAction } from '@aws-amplify/core/internals/utils';
-
 import {
 	DownloadDataInput,
 	DownloadDataOutput,
 	DownloadDataWithPathInput,
 	DownloadDataWithPathOutput,
 } from '../types';
-import { resolveS3ConfigAndInput } from '../utils/resolveS3ConfigAndInput';
-import { createDownloadTask, validateStorageOperationInput } from '../utils';
-import { getObject } from '../utils/client/s3data';
-import { getStorageUserAgentValue } from '../utils/userAgent';
-import { logger } from '../../../utils';
-import {
-	StorageDownloadDataOutput,
-	StorageItemWithKey,
-	StorageItemWithPath,
-} from '../../../types';
-import { STORAGE_INPUT_KEY } from '../utils/constants';
+
+import { downloadData as downloadDataInternal } from './internal/downloadData';
 
 /**
  * Download S3 object data to memory
@@ -89,77 +77,8 @@ export function downloadData(
  *```
  */
 export function downloadData(input: DownloadDataInput): DownloadDataOutput;
-
 export function downloadData(
 	input: DownloadDataInput | DownloadDataWithPathInput,
 ) {
-	const abortController = new AbortController();
-
-	const downloadTask = createDownloadTask({
-		job: downloadDataJob(input, abortController.signal),
-		onCancel: (message?: string) => {
-			abortController.abort(message);
-		},
-	});
-
-	return downloadTask;
+	return downloadDataInternal(input);
 }
-
-const downloadDataJob =
-	(
-		downloadDataInput: DownloadDataInput | DownloadDataWithPathInput,
-		abortSignal: AbortSignal,
-	) =>
-	async (): Promise<
-		StorageDownloadDataOutput<StorageItemWithKey | StorageItemWithPath>
-	> => {
-		const { options: downloadDataOptions } = downloadDataInput;
-		const { bucket, keyPrefix, s3Config, identityId } =
-			await resolveS3ConfigAndInput(Amplify, downloadDataInput);
-		const { inputType, objectKey } = validateStorageOperationInput(
-			downloadDataInput,
-			identityId,
-		);
-		const finalKey =
-			inputType === STORAGE_INPUT_KEY ? keyPrefix + objectKey : objectKey;
-
-		logger.debug(`download ${objectKey} from ${finalKey}.`);
-
-		const {
-			Body: body,
-			LastModified: lastModified,
-			ContentLength: size,
-			ETag: eTag,
-			Metadata: metadata,
-			VersionId: versionId,
-			ContentType: contentType,
-		} = await getObject(
-			{
-				...s3Config,
-				abortSignal,
-				onDownloadProgress: downloadDataOptions?.onProgress,
-				userAgentValue: getStorageUserAgentValue(StorageAction.DownloadData),
-			},
-			{
-				Bucket: bucket,
-				Key: finalKey,
-				...(downloadDataOptions?.bytesRange && {
-					Range: `bytes=${downloadDataOptions.bytesRange.start}-${downloadDataOptions.bytesRange.end}`,
-				}),
-			},
-		);
-
-		const result = {
-			body,
-			lastModified,
-			size,
-			contentType,
-			eTag,
-			metadata,
-			versionId,
-		};
-
-		return inputType === STORAGE_INPUT_KEY
-			? { key: objectKey, ...result }
-			: { path: objectKey, ...result };
-	};

packages/storage/src/providers/s3/apis/internal/downloadData.ts

@@ -0,0 +1,90 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { Amplify } from '@aws-amplify/core';
+import { StorageAction } from '@aws-amplify/core/internals/utils';
+
+import { resolveS3ConfigAndInput } from '../../utils/resolveS3ConfigAndInput';
+import { createDownloadTask, validateStorageOperationInput } from '../../utils';
+import { getObject } from '../../utils/client/s3data';
+import { getStorageUserAgentValue } from '../../utils/userAgent';
+import { logger } from '../../../../utils';
+import { DownloadDataInput, DownloadDataWithPathInput } from '../../types';
+import { STORAGE_INPUT_KEY } from '../../utils/constants';
+import {
+	StorageDownloadDataOutput,
+	StorageItemWithKey,
+	StorageItemWithPath,
+} from '../../../../types';
+// TODO: Remove this interface when we move to public advanced APIs.
+import { DownloadDataInput as DownloadDataWithPathInputWithAdvancedOptions } from '../../../../internals/types/inputs';
+
+export const downloadData = (
+	input: DownloadDataInput | DownloadDataWithPathInputWithAdvancedOptions,
+) => {
+	const abortController = new AbortController();
+	const downloadTask = createDownloadTask({
+		job: downloadDataJob(input, abortController.signal),
+		onCancel: (message?: string) => {
+			abortController.abort(message);
+		},
+	});
+
+	return downloadTask;
+};
+
+const downloadDataJob =
+	(
+		downloadDataInput: DownloadDataInput | DownloadDataWithPathInput,
+		abortSignal: AbortSignal,
+	) =>
+	async (): Promise<
+		StorageDownloadDataOutput<StorageItemWithKey | StorageItemWithPath>
+	> => {
+		const { options: downloadDataOptions } = downloadDataInput;
+		const { bucket, keyPrefix, s3Config, identityId } =
+			await resolveS3ConfigAndInput(Amplify, downloadDataInput);
+		const { inputType, objectKey } = validateStorageOperationInput(
+			downloadDataInput,
+			identityId,
+		);
+		const finalKey =
+			inputType === STORAGE_INPUT_KEY ? keyPrefix + objectKey : objectKey;
+		logger.debug(`download ${objectKey} from ${finalKey}.`);
+		const {
+			Body: body,
+			LastModified: lastModified,
+			ContentLength: size,
+			ETag: eTag,
+			Metadata: metadata,
+			VersionId: versionId,
+			ContentType: contentType,
+		} = await getObject(
+			{
+				...s3Config,
+				abortSignal,
+				onDownloadProgress: downloadDataOptions?.onProgress,
+				userAgentValue: getStorageUserAgentValue(StorageAction.DownloadData),
+			},
+			{
+				Bucket: bucket,
+				Key: finalKey,
+				...(downloadDataOptions?.bytesRange && {
+					Range: `bytes=${downloadDataOptions.bytesRange.start}-${downloadDataOptions.bytesRange.end}`,
+				}),
+			},
+		);
+		const result = {
+			body,
+			lastModified,
+			size,
+			contentType,
+			eTag,
+			metadata,
+			versionId,
+		};
+
+		return inputType === STORAGE_INPUT_KEY
+			? { key: objectKey, ...result }
+			: { path: objectKey, ...result };
+	};