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

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

@@ -7,11 +7,19 @@ import { StorageAction } from '@aws-amplify/core/internals/utils';
 import {
 	ListAllInput,
 	ListAllOutput,
+	ListAllWithPathInput,
+	ListAllWithPathOutput,
 	ListOutputItem,
+	ListOutputItemWithPath,
 	ListPaginateInput,
 	ListPaginateOutput,
+	ListPaginateWithPathInput,
+	ListPaginateWithPathOutput,
 } from '../../types';
-import { resolveS3ConfigAndInput } from '../../utils';
+import {
+	resolveS3ConfigAndInput,
+	validateStorageOperationInputWithPrefix,
+} from '../../utils';
 import { ResolvedS3Config } from '../../types/options';
 import {
 	ListObjectsV2Input,
@@ -20,25 +28,43 @@ import {
 } from '../../utils/client';
 import { getStorageUserAgentValue } from '../../utils/userAgent';
 import { logger } from '../../../../utils';
+import { STORAGE_INPUT_PREFIX } from '../../utils/constants';
 
 const MAX_PAGE_SIZE = 1000;
 
 interface ListInputArgs {
 	s3Config: ResolvedS3Config;
 	listParams: ListObjectsV2Input;
-	prefix: string;
+	generatedPrefix?: string;
 }
 
 export const list = async (
 	amplify: AmplifyClassV6,
-	input?: ListAllInput | ListPaginateInput,
-): Promise<ListAllOutput | ListPaginateOutput> => {
-	const { options = {}, prefix: path = '' } = input ?? {};
+	input:
+		| ListAllInput
+		| ListPaginateInput
+		| ListAllWithPathInput
+		| ListPaginateWithPathInput,
+): Promise<
+	| ListAllOutput
+	| ListPaginateOutput
+	| ListAllWithPathOutput
+	| ListPaginateWithPathOutput
+> => {
+	const { options = {} } = input;
 	const {
 		s3Config,
 		bucket,
-		keyPrefix: prefix,
+		keyPrefix: generatedPrefix,
+		identityId,
 	} = await resolveS3ConfigAndInput(amplify, options);
+
+	const { inputType, objectKey } = validateStorageOperationInputWithPrefix(
+		input,
+		identityId,
+	);
+	const isInputWithPrefix = inputType === STORAGE_INPUT_PREFIX;
+
 	// @ts-expect-error pageSize and nextToken should not coexist with listAll
 	if (options?.listAll && (options?.pageSize || options?.nextToken)) {
 		const anyOptions = options as any;
@@ -50,34 +76,53 @@ export const list = async (
 	}
 	const listParams = {
 		Bucket: bucket,
-		Prefix: `${prefix}${path}`,
+		Prefix: isInputWithPrefix ? `${generatedPrefix}${objectKey}` : objectKey,
 		MaxKeys: options?.listAll ? undefined : options?.pageSize,
 		ContinuationToken: options?.listAll ? undefined : options?.nextToken,
 	};
 	logger.debug(`listing items from "${listParams.Prefix}"`);
 
-	return options.listAll
-		? _listAll({ s3Config, listParams, prefix })
-		: _list({ s3Config, listParams, prefix });
+	const listInputArgs: ListInputArgs = {
+		s3Config,
+		listParams,
+	};
+	if (options.listAll) {
+		if (isInputWithPrefix) {
+			return _listAllWithPrefix({
+				...listInputArgs,
+				generatedPrefix,
+			});
+		} else {
+			return _listAllWithPath(listInputArgs);
+		}
+	} else {
+		if (isInputWithPrefix) {
+			return _listWithPrefix({ ...listInputArgs, generatedPrefix });
+		} else {
+			return _listWithPath(listInputArgs);
+		}
+	}
 };
 
-const _listAll = async ({
+/** @deprecated Use {@link _listAllWithPath} instead. */
+const _listAllWithPrefix = async ({
 	s3Config,
 	listParams,
-	prefix,
+	generatedPrefix,
 }: ListInputArgs): Promise<ListAllOutput> => {
 	const listResult: ListOutputItem[] = [];
 	let continuationToken = listParams.ContinuationToken;
 	do {
-		const { items: pageResults, nextToken: pageNextToken } = await _list({
-			prefix,
-			s3Config,
-			listParams: {
-				...listParams,
-				ContinuationToken: continuationToken,
-				MaxKeys: MAX_PAGE_SIZE,
-			},
-		});
+		const { items: pageResults, nextToken: pageNextToken } =
+			await _listWithPrefix({
+				generatedPrefix,
+				s3Config,
+				listParams: {
+					...listParams,
+					ContinuationToken: continuationToken,
+					MaxKeys: MAX_PAGE_SIZE,
+				},
+			});
 		listResult.push(...pageResults);
 		continuationToken = pageNextToken;
 	} while (continuationToken);
@@ -87,10 +132,11 @@ const _listAll = async ({
 	};
 };
 
-const _list = async ({
+/** @deprecated Use {@link _listWithPath} instead. */
+const _listWithPrefix = async ({
 	s3Config,
 	listParams,
-	prefix,
+	generatedPrefix,
 }: ListInputArgs): Promise<ListPaginateOutput> => {
 	const listParamsClone = { ...listParams };
 	if (!listParamsClone.MaxKeys || listParamsClone.MaxKeys > MAX_PAGE_SIZE) {
@@ -112,15 +158,75 @@ const _list = async ({
 		};
 	}
 
-	const listResult = response.Contents.map(item => ({
-		key: item.Key!.substring(prefix.length),
-		eTag: item.ETag,
-		lastModified: item.LastModified,
-		size: item.Size,
-	}));
+	return {
+		items: response.Contents.map(item => ({
+			key: generatedPrefix
+				? item.Key!.substring(generatedPrefix.length)
+				: item.Key!,
+			eTag: item.ETag,
+			lastModified: item.LastModified,
+			size: item.Size,
+		})),
+		nextToken: response.NextContinuationToken,
+	};
+};
+
+const _listAllWithPath = async ({
+	s3Config,
+	listParams,
+}: ListInputArgs): Promise<ListAllWithPathOutput> => {
+	const listResult: ListOutputItemWithPath[] = [];
+	let continuationToken = listParams.ContinuationToken;
+	do {
+		const { items: pageResults, nextToken: pageNextToken } =
+			await _listWithPath({
+				s3Config,
+				listParams: {
+					...listParams,
+					ContinuationToken: continuationToken,
+					MaxKeys: MAX_PAGE_SIZE,
+				},
+			});
+		listResult.push(...pageResults);
+		continuationToken = pageNextToken;
+	} while (continuationToken);
 
 	return {
 		items: listResult,
+	};
+};
+
+const _listWithPath = async ({
+	s3Config,
+	listParams,
+}: ListInputArgs): Promise<ListPaginateWithPathOutput> => {
+	const listParamsClone = { ...listParams };
+	if (!listParamsClone.MaxKeys || listParamsClone.MaxKeys > MAX_PAGE_SIZE) {
+		logger.debug(`defaulting pageSize to ${MAX_PAGE_SIZE}.`);
+		listParamsClone.MaxKeys = MAX_PAGE_SIZE;
+	}
+
+	const response: ListObjectsV2Output = await listObjectsV2(
+		{
+			...s3Config,
+			userAgentValue: getStorageUserAgentValue(StorageAction.List),
+		},
+		listParamsClone,
+	);
+
+	if (!response?.Contents) {
+		return {
+			items: [],
+		};
+	}
+
+	return {
+		items: response.Contents.map(item => ({
+			path: item.Key!,
+			eTag: item.ETag,
+			lastModified: item.LastModified,
+			size: item.Size,
+		})),
 		nextToken: response.NextContinuationToken,
 	};
 };

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

@@ -4,24 +4,43 @@
 import { AmplifyClassV6 } from '@aws-amplify/core';
 import { StorageAction } from '@aws-amplify/core/internals/utils';
 
-import { RemoveInput, RemoveOutput } from '../../types';
-import { resolveS3ConfigAndInput } from '../../utils';
+import {
+	RemoveInput,
+	RemoveOutput,
+	RemoveWithPathInput,
+	RemoveWithPathOutput,
+} from '../../types';
+import {
+	resolveS3ConfigAndInput,
+	validateStorageOperationInput,
+} from '../../utils';
 import { deleteObject } from '../../utils/client';
 import { getStorageUserAgentValue } from '../../utils/userAgent';
 import { logger } from '../../../../utils';
+import { STORAGE_INPUT_KEY } from '../../utils/constants';
 
 export const remove = async (
 	amplify: AmplifyClassV6,
-	input: RemoveInput,
-): Promise<RemoveOutput> => {
-	const { key, options = {} } = input;
-	const { s3Config, keyPrefix, bucket } = await resolveS3ConfigAndInput(
-		amplify,
-		options,
+	input: RemoveInput | RemoveWithPathInput,
+): Promise<RemoveOutput | RemoveWithPathOutput> => {
+	const { options = {} } = input ?? {};
+	const { s3Config, keyPrefix, bucket, identityId } =
+		await resolveS3ConfigAndInput(amplify, options);
+
+	const { inputType, objectKey } = validateStorageOperationInput(
+		input,
+		identityId,
 	);
 
-	const finalKey = `${keyPrefix}${key}`;
-	logger.debug(`remove "${key}" from "${finalKey}".`);
+	let finalKey;
+	if (inputType === STORAGE_INPUT_KEY) {
+		finalKey = `${keyPrefix}${objectKey}`;
+		logger.debug(`remove "${objectKey}" from "${finalKey}".`);
+	} else {
+		finalKey = objectKey;
+		logger.debug(`removing object in path "${finalKey}"`);
+	}
+
 	await deleteObject(
 		{
 			...s3Config,
@@ -33,7 +52,11 @@ export const remove = async (
 		},
 	);
 
-	return {
-		key,
-	};
+	return inputType === STORAGE_INPUT_KEY
+		? {
+				key: objectKey,
+			}
+		: {
+				path: objectKey,
+			};
 };

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

@@ -1,41 +1,69 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
-
 import { Amplify } from '@aws-amplify/core';
 
 import {
 	ListAllInput,
 	ListAllOutput,
+	ListAllWithPathInput,
+	ListAllWithPathOutput,
 	ListPaginateInput,
 	ListPaginateOutput,
-	S3Exception,
+	ListPaginateWithPathInput,
+	ListPaginateWithPathOutput,
 } from '../types';
-import { StorageValidationErrorCode } from '../../../errors/types/validation';
 
 import { list as listInternal } from './internal/list';
 
-interface 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 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 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
-	 */
-	(input?: ListAllInput): Promise<ListAllOutput>;
-}
+/**
+ * List files in pages with the given `path`.
+ * `pageSize` is defaulted to 1000. Additionally, the result will include a `nextToken` if there are more items to retrieve.
+ * @param input - The `ListPaginateWithPathInput` object.
+ * @returns A list of objects with path and metadata
+ * @throws service: `S3Exception` - S3 service errors thrown when checking for existence of bucket
+ * @throws validation: `StorageValidationErrorCode` - thrown when there are issues with credentials
+ */
+export function list(
+	input: ListPaginateWithPathInput,
+): Promise<ListPaginateWithPathOutput>;
+/**
+ * List all files from S3 for a given `path`. You can set `listAll` to true in `options` to get all the files from S3.
+ * @param input - The `ListAllWithPathInput` object.
+ * @returns A list of all objects with path and metadata
+ * @throws service: `S3Exception` - S3 service errors thrown when checking for existence of bucket
+ * @throws validation: `StorageValidationErrorCode`  - thrown when there are issues with credentials
+ */
+export function list(
+	input: ListAllWithPathInput,
+): Promise<ListAllWithPathOutput>;
+/**
+ * @deprecated The `prefix` 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/list | path} instead.
+ * List files in pages with the given `prefix`.
+ * `pageSize` is defaulted to 1000. Additionally, the result will include a `nextToken` if there are more items to retrieve.
+ * @param input - The `ListPaginateInput` object.
+ * @returns A list of objects with key and metadata
+ * @throws service: `S3Exception` - S3 service errors thrown when checking for existence of bucket
+ * @throws validation: `StorageValidationErrorCode` - thrown when there are issues with credentials
+ */
+export function list(input?: ListPaginateInput): Promise<ListPaginateOutput>;
+/**
+ * @deprecated The `prefix` 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/list | path} instead.
+ * List all files from S3 for a given `prefix`. You can set `listAll` to true in `options` to get all the files from S3.
+ * @param input - The `ListAllInput` object.
+ * @returns A list of all objects with key and metadata
+ * @throws service: `S3Exception` - S3 service errors thrown when checking for existence of bucket
+ * @throws validation: `StorageValidationErrorCode`  - thrown when there are issues with credentials
+ */
+export function list(input?: ListAllInput): Promise<ListAllOutput>;
 
-export const list: ListApi = (
-	input?: ListAllInput | ListPaginateInput,
-): Promise<ListAllOutput | ListPaginateOutput> => {
+export function list(
+	input?:
+		| ListAllInput
+		| ListPaginateInput
+		| ListAllWithPathInput
+		| ListPaginateWithPathInput,
+) {
 	return listInternal(Amplify, input ?? {});
-};
+}

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

@@ -3,18 +3,39 @@
 
 import { Amplify } from '@aws-amplify/core';
 
-import { RemoveInput, RemoveOutput, S3Exception } from '../types';
-import { StorageValidationErrorCode } from '../../../errors/types/validation';
+import {
+	RemoveInput,
+	RemoveOutput,
+	RemoveWithPathInput,
+	RemoveWithPathOutput,
+} from '../types';
 
 import { remove as removeInternal } from './internal/remove';
 
 /**
  * Remove a file from your S3 bucket.
- * @param input - The RemoveInput object.
+ * @param input - The `RemoveWithPathInput` object.
+ * @return Output containing the removed object path.
+ * @throws service: `S3Exception` - S3 service errors thrown while while removing the object.
+ * @throws validation: `StorageValidationErrorCode` - Validation errors thrown
+ * when there is no path or path is empty or path has a leading slash.
+ */
+export function remove(
+	input: RemoveWithPathInput,
+): Promise<RemoveWithPathOutput>;
+/**
+ * @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/remove | path} instead.
+ *
+ * Remove a file from your S3 bucket.
+ * @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
+ * @throws service: `S3Exception` - S3 service errors thrown while while removing the object
+ * @throws validation: `StorageValidationErrorCode` - Validation errors thrown
+ * when there is no key or its empty.
  */
-export const remove = (input: RemoveInput): Promise<RemoveOutput> => {
+export function remove(input: RemoveInput): Promise<RemoveOutput>;
+
+export function remove(input: RemoveInput | RemoveWithPathInput) {
 	return removeInternal(Amplify, input);
-};
+}

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

@@ -1,17 +1,54 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
-
 import {
 	AmplifyServer,
 	getAmplifyServerContext,
 } from '@aws-amplify/core/internals/adapter-core';
 
-import { CopyInput, CopyOutput } from '../../types';
+import {
+	CopyInput,
+	CopyOutput,
+	CopyWithPathInput,
+	CopyWithPathOutput,
+} from '../../types';
 import { copy as copyInternal } from '../internal/copy';
 
-export const copy = async (
+/**
+ * Copy an object from a source to a destination object within the same bucket.
+ *
+ * @param contextSpec - The isolated server context.
+ * @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 function copy(
+	contextSpec: AmplifyServer.ContextSpec,
+	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 contextSpec - The isolated server context.
+ * @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(
 	contextSpec: AmplifyServer.ContextSpec,
 	input: CopyInput,
-): Promise<CopyOutput> => {
+): Promise<CopyOutput>;
+
+export function copy(
+	contextSpec: AmplifyServer.ContextSpec,
+	input: CopyInput | CopyWithPathInput,
+) {
 	return copyInternal(getAmplifyServerContext(contextSpec).amplify, input);
-};
+}

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

@@ -6,15 +6,52 @@ import {
 	getAmplifyServerContext,
 } from '@aws-amplify/core/internals/adapter-core';
 
-import { GetPropertiesInput, GetPropertiesOutput } from '../../types';
+import {
+	GetPropertiesInput,
+	GetPropertiesOutput,
+	GetPropertiesWithPathInput,
+	GetPropertiesWithPathOutput,
+} from '../../types';
 import { getProperties as getPropertiesInternal } from '../internal/getProperties';
 
-export const 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 contextSpec - The isolated server context.
+ * @param input - The `GetPropertiesWithPathInput` 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(
+	contextSpec: AmplifyServer.ContextSpec,
+	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 contextSpec - The isolated server context.
+ * @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(
 	contextSpec: AmplifyServer.ContextSpec,
 	input: GetPropertiesInput,
-): Promise<GetPropertiesOutput> => {
+): Promise<GetPropertiesOutput>;
+
+export function getProperties(
+	contextSpec: AmplifyServer.ContextSpec,
+	input: GetPropertiesInput | GetPropertiesWithPathInput,
+) {
 	return getPropertiesInternal(
 		getAmplifyServerContext(contextSpec).amplify,
 		input,
 	);
-};
+}

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

@@ -6,12 +6,63 @@ import {
 	getAmplifyServerContext,
 } from '@aws-amplify/core/internals/adapter-core';
 
-import { GetUrlInput, GetUrlOutput } from '../../types';
+import {
+	GetUrlInput,
+	GetUrlOutput,
+	GetUrlWithPathInput,
+	GetUrlWithPathOutput,
+} from '../../types';
 import { getUrl as getUrlInternal } from '../internal/getUrl';
 
-export const getUrl = async (
+/**
+ * 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 contextSpec - The isolated server context.
+ * @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 function getUrl(
+	contextSpec: AmplifyServer.ContextSpec,
+	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 contextSpec - The isolated server context.
+ * @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(
 	contextSpec: AmplifyServer.ContextSpec,
 	input: GetUrlInput,
-): Promise<GetUrlOutput> => {
+): Promise<GetUrlOutput>;
+
+export function getUrl(
+	contextSpec: AmplifyServer.ContextSpec,
+	input: GetUrlInput | GetUrlWithPathInput,
+) {
 	return getUrlInternal(getAmplifyServerContext(contextSpec).amplify, input);
-};
+}