@aws-amplify/storage 6.0.28 → 6.0.29-gen2-storage.e54bfa9.0

package/src/index.ts

@@ -13,24 +13,40 @@ export {
 
 export {
 	UploadDataInput,
+	UploadDataWithPathInput,
 	DownloadDataInput,
+	DownloadDataWithPathInput,
 	RemoveInput,
+	RemoveWithPathInput,
 	ListAllInput,
+	ListAllWithPathInput,
 	ListPaginateInput,
+	ListPaginateWithPathInput,
 	GetPropertiesInput,
+	GetPropertiesWithPathInput,
 	CopyInput,
+	CopyWithPathInput,
 	GetUrlInput,
+	GetUrlWithPathInput,
 } from './providers/s3/types/inputs';
 
 export {
 	UploadDataOutput,
+	UploadDataWithPathOutput,
 	DownloadDataOutput,
+	DownloadDataWithPathOutput,
 	RemoveOutput,
+	RemoveWithPathOutput,
 	ListAllOutput,
+	ListAllWithPathOutput,
 	ListPaginateOutput,
+	ListPaginateWithPathOutput,
 	GetPropertiesOutput,
+	GetPropertiesWithPathOutput,
 	CopyOutput,
+	CopyWithPathOutput,
 	GetUrlOutput,
+	GetUrlWithPathOutput,
 } from './providers/s3/types/outputs';
 
 export { TransferProgressEvent } from './types';

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

@@ -3,21 +3,40 @@
 
 import { Amplify } from '@aws-amplify/core';
 
-import { CopyInput, CopyOutput, S3Exception } from '../types';
-import { StorageValidationErrorCode } from '../../../errors/types/validation';
+import {
+	CopyInput,
+	CopyOutput,
+	CopyWithPathInput,
+	CopyWithPathOutput,
+} from '../types';
 
 import { copy as copyInternal } from './internal/copy';
 
 /**
- * Copy an object from a source object to a new object within the same bucket. Can optionally copy files across
- * different level or identityId (if source object's level is 'protected').
+ * Copy an object from a source to a destination object within the same bucket.
  *
- * @param input - The CopyInput object.
- * @returns Output containing the destination key.
- * @throws service: {@link S3Exception} - Thrown when checking for existence of the object
- * @throws validation: {@link StorageValidationErrorCode } - Thrown when
- * source or destination key are not defined.
+ * @param input - The `CopyWithPathInput` object.
+ * @returns Output containing the destination object path.
+ * @throws service: `S3Exception` - Thrown when checking for existence of the object
+ * @throws validation: `StorageValidationErrorCode` - Thrown when
+ * source or destination path is not defined.
  */
-export const copy = async (input: CopyInput): Promise<CopyOutput> => {
+export function copy(input: CopyWithPathInput): Promise<CopyWithPathOutput>;
+/**
+ * @deprecated The `key` and `accessLevel` parameters are deprecated and may be removed in the next major version.
+ * Please use {@link https://docs.amplify.aws/react/build-a-backend/storage/copy | path} instead.
+ *
+ * Copy an object from a source to a destination object within the same bucket. Can optionally copy files across
+ * different accessLevel or identityId (if source object's accessLevel is 'protected').
+ *
+ * @param input - The `CopyInput` object.
+ * @returns Output containing the destination object key.
+ * @throws service: `S3Exception` - Thrown when checking for existence of the object
+ * @throws validation: `StorageValidationErrorCode` - Thrown when
+ * source or destination key is not defined.
+ */
+export function copy(input: CopyInput): Promise<CopyOutput>;
+
+export function copy(input: CopyInput | CopyWithPathInput) {
 	return copyInternal(Amplify, input);
-};
+}

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

@@ -4,33 +4,43 @@
 import { Amplify } from '@aws-amplify/core';
 import { StorageAction } from '@aws-amplify/core/internals/utils';
 
-import { DownloadDataInput, DownloadDataOutput, S3Exception } from '../types';
+import {
+	DownloadDataInput,
+	DownloadDataOutput,
+	DownloadDataWithPathInput,
+	DownloadDataWithPathOutput,
+} from '../types';
 import { resolveS3ConfigAndInput } from '../utils/resolveS3ConfigAndInput';
-import { StorageValidationErrorCode } from '../../../errors/types/validation';
-import { createDownloadTask } from '../utils';
+import { createDownloadTask, validateStorageOperationInput } from '../utils';
 import { getObject } from '../utils/client';
 import { getStorageUserAgentValue } from '../utils/userAgent';
 import { logger } from '../../../utils';
+import {
+	StorageDownloadDataOutput,
+	StorageItemWithKey,
+	StorageItemWithPath,
+} from '../../../types';
+import { STORAGE_INPUT_KEY } from '../utils/constants';
 
 /**
  * Download S3 object data to memory
  *
- * @param input - The DownloadDataInput object.
+ * @param input - The `DownloadDataWithPathInput` object.
  * @returns A cancelable 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
+ * @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({ key, data: file, options: {
+ * const { body, eTag } = await downloadData({ path, options: {
  *   onProgress, // Optional progress callback.
  * } }).result;
  * ```
  * @example
  * ```ts
  * // Cancel a task
- * const downloadTask = downloadData({ key, data: file });
+ * const downloadTask = downloadData({ path });
  * //...
  * downloadTask.cancel();
  * try {
@@ -42,7 +52,47 @@ import { logger } from '../../../utils';
  * }
  *```
  */
-export const downloadData = (input: DownloadDataInput): DownloadDataOutput => {
+export function downloadData(
+	input: DownloadDataWithPathInput,
+): DownloadDataWithPathOutput;
+/**
+ * @deprecated The `key` and `accessLevel` parameters are deprecated and may be removed in the next major version.
+ * Please use {@link https://docs.amplify.aws/react/build-a-backend/storage/download/#downloaddata | path} instead.
+ *
+ * Download S3 object data to memory
+ *
+ * @param input - The `DownloadDataInput` 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({ key, options: {
+ *   onProgress, // Optional progress callback.
+ * } }).result;
+ * ```
+ * @example
+ * ```ts
+ * // Cancel a task
+ * const downloadTask = downloadData({ key });
+ * //...
+ * downloadTask.cancel();
+ * try {
+ * 	await downloadTask.result;
+ * } catch (error) {
+ * 	if(isCancelError(error)) {
+ *    // Handle error thrown by task cancelation.
+ * 	}
+ * }
+ *```
+ */
+export function downloadData(input: DownloadDataInput): DownloadDataOutput;
+
+export function downloadData(
+	input: DownloadDataInput | DownloadDataWithPathInput,
+) {
 	const abortController = new AbortController();
 
 	const downloadTask = createDownloadTask({
@@ -53,21 +103,27 @@ export const downloadData = (input: DownloadDataInput): DownloadDataOutput => {
 	});
 
 	return downloadTask;
-};
+}
 
 const downloadDataJob =
 	(
-		{ options: downloadDataOptions, key }: DownloadDataInput,
+		downloadDataInput: DownloadDataInput | DownloadDataWithPathInput,
 		abortSignal: AbortSignal,
 	) =>
-	async () => {
-		const { bucket, keyPrefix, s3Config } = await resolveS3ConfigAndInput(
-			Amplify,
-			downloadDataOptions,
+	async (): Promise<
+		StorageDownloadDataOutput<StorageItemWithKey | StorageItemWithPath>
+	> => {
+		const { options: downloadDataOptions } = downloadDataInput;
+		const { bucket, keyPrefix, s3Config, identityId } =
+			await resolveS3ConfigAndInput(Amplify, downloadDataOptions);
+		const { inputType, objectKey } = validateStorageOperationInput(
+			downloadDataInput,
+			identityId,
 		);
-		const finalKey = keyPrefix + key;
+		const finalKey =
+			inputType === STORAGE_INPUT_KEY ? keyPrefix + objectKey : objectKey;
 
-		logger.debug(`download ${key} from ${finalKey}.`);
+		logger.debug(`download ${objectKey} from ${finalKey}.`);
 
 		const {
 			Body: body,
@@ -93,8 +149,7 @@ const downloadDataJob =
 			},
 		);
 
-		return {
-			key,
+		const result = {
 			body,
 			lastModified,
 			size,
@@ -103,4 +158,8 @@ const downloadDataJob =
 			metadata,
 			versionId,
 		};
+
+		return inputType === STORAGE_INPUT_KEY
+			? { key: objectKey, ...result }
+			: { path: objectKey, ...result };
 	};

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

@@ -3,8 +3,12 @@
 
 import { Amplify } from '@aws-amplify/core';
 
-import { GetPropertiesInput, GetPropertiesOutput, S3Exception } from '../types';
-import { StorageValidationErrorCode } from '../../../errors/types/validation';
+import {
+	GetPropertiesInput,
+	GetPropertiesOutput,
+	GetPropertiesWithPathInput,
+	GetPropertiesWithPathOutput,
+} from '../types';
 
 import { getProperties as getPropertiesInternal } from './internal/getProperties';
 
@@ -12,13 +16,32 @@ import { getProperties as getPropertiesInternal } from './internal/getProperties
  * Gets the properties of a file. The properties include S3 system metadata and
  * the user metadata that was provided when uploading the file.
  *
- * @param input - The GetPropertiesInput object.
+ * @param input - The `GetPropertiesWithPathInput` object.
  * @returns Requested object properties.
- * @throws A {@link S3Exception} when the underlying S3 service returned error.
- * @throws A {@link StorageValidationErrorCode} when API call parameters are invalid.
+ * @throws An `S3Exception` when the underlying S3 service returned error.
+ * @throws A `StorageValidationErrorCode` when API call parameters are invalid.
  */
-export const getProperties = (
+export function getProperties(
+	input: GetPropertiesWithPathInput,
+): Promise<GetPropertiesWithPathOutput>;
+/**
+ * @deprecated The `key` and `accessLevel` parameters are deprecated and may be removed in the next major version.
+ * Please use {@link https://docs.amplify.aws/javascript/build-a-backend/storage/get-properties/ | path} instead.
+ *
+ * Gets the properties of a file. The properties include S3 system metadata and
+ * the user metadata that was provided when uploading the file.
+ *
+ * @param input - The `GetPropertiesInput` object.
+ * @returns Requested object properties.
+ * @throws An `S3Exception` when the underlying S3 service returned error.
+ * @throws A `StorageValidationErrorCode` when API call parameters are invalid.
+ */
+export function getProperties(
 	input: GetPropertiesInput,
-): Promise<GetPropertiesOutput> => {
+): Promise<GetPropertiesOutput>;
+
+export function getProperties(
+	input: GetPropertiesInput | GetPropertiesWithPathInput,
+) {
 	return getPropertiesInternal(Amplify, input);
-};
+}

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

@@ -3,9 +3,12 @@
 
 import { Amplify } from '@aws-amplify/core';
 
-import { StorageValidationErrorCode } from '../../../errors/types/validation';
-import { GetUrlInput, GetUrlOutput, S3Exception } from '../types';
-import { StorageError } from '../../../errors/StorageError';
+import {
+	GetUrlInput,
+	GetUrlOutput,
+	GetUrlWithPathInput,
+	GetUrlWithPathOutput,
+} from '../types';
 
 import { getUrl as getUrlInternal } from './internal/getUrl';
 
@@ -16,15 +19,39 @@ import { getUrl as getUrlInternal } from './internal/getUrl';
  *
  * 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.
+ * URL, and will throw `StorageError` if the object does not exist.
  *
- * @param input - The GetUrlInput object.
- * @returns Presigned URL and timestamp when the URL MAY expire.
- * @throws service: {@link S3Exception} - thrown when checking for existence of the object
- * @throws validation: {@link StorageValidationErrorCode } - Validation errors
+ * @param input - The `GetUrlWithPathInput` object.
+ * @returns Presigned URL and timestamp when the URL may expire.
+ * @throws service: `S3Exception` - thrown when checking for existence of the object
+ * @throws validation: `StorageValidationErrorCode` - Validation errors
  * thrown either username or key are not defined.
  *
  */
-export const getUrl = (input: GetUrlInput): Promise<GetUrlOutput> => {
+export function getUrl(
+	input: GetUrlWithPathInput,
+): Promise<GetUrlWithPathOutput>;
+/**
+ * @deprecated The `key` and `accessLevel` parameters are deprecated and may be removed in the next major version.
+ * Please use {@link https://docs.amplify.aws/javascript/build-a-backend/storage/download/#generate-a-download-url | path} instead.
+ *
+ * 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 `StorageError` if the object does not exist.
+ *
+ * @param input - The `GetUrlInput` object.
+ * @returns Presigned URL and timestamp when the URL may expire.
+ * @throws service: `S3Exception` - thrown when checking for existence of the object
+ * @throws validation: `StorageValidationErrorCode` - Validation errors
+ * thrown either username or key are not defined.
+ *
+ */
+export function getUrl(input: GetUrlInput): Promise<GetUrlOutput>;
+
+export function getUrl(input: GetUrlInput | GetUrlWithPathInput) {
 	return getUrlInternal(Amplify, input);
-};
+}

package/src/providers/s3/apis/internal/copy.ts

@@ -4,15 +4,76 @@
 import { AmplifyClassV6 } from '@aws-amplify/core';
 import { StorageAction } from '@aws-amplify/core/internals/utils';
 
-import { CopyInput, CopyOutput } from '../../types';
-import { resolveS3ConfigAndInput } from '../../utils';
+import {
+	CopyInput,
+	CopyOutput,
+	CopyWithPathInput,
+	CopyWithPathOutput,
+} from '../../types';
+import { ResolvedS3Config } from '../../types/options';
+import {
+	isInputWithPath,
+	resolveS3ConfigAndInput,
+	validateStorageOperationInput,
+} from '../../utils';
 import { StorageValidationErrorCode } from '../../../../errors/types/validation';
 import { assertValidationError } from '../../../../errors/utils/assertValidationError';
 import { copyObject } from '../../utils/client';
 import { getStorageUserAgentValue } from '../../utils/userAgent';
 import { logger } from '../../../../utils';
 
+const isCopyInputWithPath = (
+	input: CopyInput | CopyWithPathInput,
+): input is CopyWithPathInput => isInputWithPath(input.source);
+
 export const copy = async (
+	amplify: AmplifyClassV6,
+	input: CopyInput | CopyWithPathInput,
+): Promise<CopyOutput | CopyWithPathOutput> => {
+	return isCopyInputWithPath(input)
+		? copyWithPath(amplify, input)
+		: copyWithKey(amplify, input);
+};
+
+const copyWithPath = async (
+	amplify: AmplifyClassV6,
+	input: CopyWithPathInput,
+): Promise<CopyWithPathOutput> => {
+	const { source, destination } = input;
+	const { s3Config, bucket, identityId } =
+		await resolveS3ConfigAndInput(amplify);
+
+	assertValidationError(!!source.path, StorageValidationErrorCode.NoSourcePath);
+	assertValidationError(
+		!!destination.path,
+		StorageValidationErrorCode.NoDestinationPath,
+	);
+
+	const { objectKey: sourcePath } = validateStorageOperationInput(
+		source,
+		identityId,
+	);
+	const { objectKey: destinationPath } = validateStorageOperationInput(
+		destination,
+		identityId,
+	);
+
+	const finalCopySource = `${bucket}/${sourcePath}`;
+	const finalCopyDestination = destinationPath;
+	logger.debug(`copying "${finalCopySource}" to "${finalCopyDestination}".`);
+
+	await serviceCopy({
+		source: finalCopySource,
+		destination: finalCopyDestination,
+		bucket,
+		s3Config,
+	});
+
+	return { path: finalCopyDestination };
+};
+
+/** @deprecated Use {@link copyWithPath} instead. */
+export const copyWithKey = async (
 	amplify: AmplifyClassV6,
 	input: CopyInput,
 ): Promise<CopyOutput> => {
@@ -41,6 +102,30 @@ export const copy = async (
 	const finalCopySource = `${bucket}/${sourceKeyPrefix}${sourceKey}`;
 	const finalCopyDestination = `${destinationKeyPrefix}${destinationKey}`;
 	logger.debug(`copying "${finalCopySource}" to "${finalCopyDestination}".`);
+
+	await serviceCopy({
+		source: finalCopySource,
+		destination: finalCopyDestination,
+		bucket,
+		s3Config,
+	});
+
+	return {
+		key: destinationKey,
+	};
+};
+
+const serviceCopy = async ({
+	source,
+	destination,
+	bucket,
+	s3Config,
+}: {
+	source: string;
+	destination: string;
+	bucket: string;
+	s3Config: ResolvedS3Config;
+}) => {
 	await copyObject(
 		{
 			...s3Config,
@@ -48,13 +133,9 @@ export const copy = async (
 		},
 		{
 			Bucket: bucket,
-			CopySource: finalCopySource,
-			Key: finalCopyDestination,
+			CopySource: source,
+			Key: destination,
 			MetadataDirective: 'COPY', // Copies over metadata like contentType as well
 		},
 	);
-
-	return {
-		key: destinationKey,
-	};
 };

package/src/providers/s3/apis/internal/getProperties.ts

@@ -4,25 +4,37 @@
 import { AmplifyClassV6 } from '@aws-amplify/core';
 import { StorageAction } from '@aws-amplify/core/internals/utils';
 
-import { GetPropertiesInput, GetPropertiesOutput } from '../../types';
-import { resolveS3ConfigAndInput } from '../../utils';
+import {
+	GetPropertiesInput,
+	GetPropertiesOutput,
+	GetPropertiesWithPathInput,
+	GetPropertiesWithPathOutput,
+} from '../../types';
+import {
+	resolveS3ConfigAndInput,
+	validateStorageOperationInput,
+} from '../../utils';
 import { headObject } from '../../utils/client';
 import { getStorageUserAgentValue } from '../../utils/userAgent';
 import { logger } from '../../../../utils';
+import { STORAGE_INPUT_KEY } from '../../utils/constants';
 
 export const getProperties = async (
 	amplify: AmplifyClassV6,
-	input: GetPropertiesInput,
+	input: GetPropertiesInput | GetPropertiesWithPathInput,
 	action?: StorageAction,
-): Promise<GetPropertiesOutput> => {
-	const { key, options } = input;
-	const { s3Config, bucket, keyPrefix } = await resolveS3ConfigAndInput(
-		amplify,
-		options,
+): Promise<GetPropertiesOutput | GetPropertiesWithPathOutput> => {
+	const { options: getPropertiesOptions } = input;
+	const { s3Config, bucket, keyPrefix, identityId } =
+		await resolveS3ConfigAndInput(amplify, getPropertiesOptions);
+	const { inputType, objectKey } = validateStorageOperationInput(
+		input,
+		identityId,
 	);
-	const finalKey = `${keyPrefix}${key}`;
+	const finalKey =
+		inputType === STORAGE_INPUT_KEY ? keyPrefix + objectKey : objectKey;
 
-	logger.debug(`get properties of ${key} from ${finalKey}`);
+	logger.debug(`get properties of ${objectKey} from ${finalKey}`);
 	const response = await headObject(
 		{
 			...s3Config,
@@ -36,8 +48,7 @@ export const getProperties = async (
 		},
 	);
 
-	return {
-		key,
+	const result = {
 		contentType: response.ContentType,
 		size: response.ContentLength,
 		eTag: response.ETag,
@@ -45,4 +56,8 @@ export const getProperties = async (
 		metadata: response.Metadata,
 		versionId: response.VersionId,
 	};
+
+	return inputType === STORAGE_INPUT_KEY
+		? { key: objectKey, ...result }
+		: { path: objectKey, ...result };
 };

package/src/providers/s3/apis/internal/getUrl.ts

@@ -4,34 +4,48 @@
 import { AmplifyClassV6 } from '@aws-amplify/core';
 import { StorageAction } from '@aws-amplify/core/internals/utils';
 
-import { GetUrlInput, GetUrlOutput } from '../../types';
+import {
+	GetUrlInput,
+	GetUrlOutput,
+	GetUrlWithPathInput,
+	GetUrlWithPathOutput,
+} from '../../types';
 import { StorageValidationErrorCode } from '../../../../errors/types/validation';
 import { getPresignedGetObjectUrl } from '../../utils/client';
-import { resolveS3ConfigAndInput } from '../../utils';
+import {
+	resolveS3ConfigAndInput,
+	validateStorageOperationInput,
+} from '../../utils';
 import { assertValidationError } from '../../../../errors/utils/assertValidationError';
 import {
 	DEFAULT_PRESIGN_EXPIRATION,
 	MAX_URL_EXPIRATION,
+	STORAGE_INPUT_KEY,
 } from '../../utils/constants';
 
 import { getProperties } from './getProperties';
 
 export const getUrl = async (
 	amplify: AmplifyClassV6,
-	input: GetUrlInput,
-): Promise<GetUrlOutput> => {
-	const { key, options } = input;
+	input: GetUrlInput | GetUrlWithPathInput,
+): Promise<GetUrlOutput | GetUrlWithPathOutput> => {
+	const { options: getUrlOptions } = input;
+	const { s3Config, keyPrefix, bucket, identityId } =
+		await resolveS3ConfigAndInput(amplify, getUrlOptions);
+	const { inputType, objectKey } = validateStorageOperationInput(
+		input,
+		identityId,
+	);
 
-	if (options?.validateObjectExistence) {
-		await getProperties(amplify, { key, options }, StorageAction.GetUrl);
-	}
+	const finalKey =
+		inputType === STORAGE_INPUT_KEY ? keyPrefix + objectKey : objectKey;
 
-	const { s3Config, keyPrefix, bucket } = await resolveS3ConfigAndInput(
-		amplify,
-		options,
-	);
+	if (getUrlOptions?.validateObjectExistence) {
+		await getProperties(amplify, input, StorageAction.GetUrl);
+	}
 
-	let urlExpirationInSec = options?.expiresIn ?? DEFAULT_PRESIGN_EXPIRATION;
+	let urlExpirationInSec =
+		getUrlOptions?.expiresIn ?? DEFAULT_PRESIGN_EXPIRATION;
 	const awsCredExpiration = s3Config.credentials?.expiration;
 	if (awsCredExpiration) {
 		const awsCredExpirationInSec = Math.floor(
@@ -54,7 +68,7 @@ export const getUrl = async (
 			},
 			{
 				Bucket: bucket,
-				Key: `${keyPrefix}${key}`,
+				Key: finalKey,
 			},
 		),
 		expiresAt: new Date(Date.now() + urlExpirationInSec * 1000),