feat(storage): add delimiter support

packages/aws-amplify/package.json

@@ -485,7 +485,7 @@
 			"name": "[Storage] list (S3)",
 			"path": "./dist/esm/storage/index.mjs",
 			"import": "{ list }",
-			"limit": "14.94 kB"
+			"limit": "15.04 kB"
 		},
 		{
 			"name": "[Storage] remove (S3)",

packages/storage/__tests__/providers/s3/apis/list.test.ts

@@ -512,4 +512,110 @@ describe('list API', () => {
 			}
 		});
 	});
+
+	describe('with delimiter', () => {
+		const mockedContents = [
+			{
+				Key: 'photos/',
+				...listObjectClientBaseResultItem,
+			},
+			{
+				Key: 'photos/2023.png',
+				...listObjectClientBaseResultItem,
+			},
+			{
+				Key: 'photos/2024.png',
+				...listObjectClientBaseResultItem,
+			},
+		];
+		const mockedCommonPrefixes = [
+			{ Prefix: 'photos/2023/' },
+			{ Prefix: 'photos/2024/' },
+			{ Prefix: 'photos/2025/' },
+		];
+
+		const mockedPath = 'photos/';
+
+		afterEach(() => {
+			jest.clearAllMocks();
+			mockListObject.mockClear();
+		});
+
+		it('should return subpaths when maxiumDepth is passed in the request', async () => {
+			mockListObject.mockResolvedValueOnce({
+				Contents: mockedContents,
+				CommonPrefixes: mockedCommonPrefixes,
+			});
+			const { items, subpaths } = await list({
+				path: mockedPath,
+				options: {
+					delimiter: '/',
+				},
+			});
+			expect(items).toHaveLength(3);
+			expect(subpaths).toHaveLength(3);
+			expect(listObjectsV2).toHaveBeenCalledTimes(1);
+			await expect(listObjectsV2).toBeLastCalledWithConfigAndInput(
+				listObjectClientConfig,
+				{
+					Bucket: bucket,
+					MaxKeys: 1000,
+					Prefix: mockedPath,
+					Delimiter: '/',
+				},
+			);
+		});
+
+		it('should return subpaths when maxiumDepth and listAll are passed in the request', async () => {
+			mockListObject.mockResolvedValueOnce({
+				Contents: mockedContents,
+				CommonPrefixes: mockedCommonPrefixes,
+			});
+			const { items, subpaths } = await list({
+				path: mockedPath,
+				options: {
+					delimiter: '/',
+					listAll: true,
+				},
+			});
+			expect(items).toHaveLength(3);
+			expect(subpaths).toHaveLength(3);
+			expect(listObjectsV2).toHaveBeenCalledTimes(1);
+			await expect(listObjectsV2).toBeLastCalledWithConfigAndInput(
+				listObjectClientConfig,
+				{
+					Bucket: bucket,
+					MaxKeys: 1000,
+					Prefix: mockedPath,
+					Delimiter: '/',
+				},
+			);
+		});
+
+		it('should return subpaths when maxiumDepth is pageSize are passed in the request', async () => {
+			mockListObject.mockResolvedValueOnce({
+				Contents: mockedContents,
+				CommonPrefixes: mockedCommonPrefixes,
+			});
+			const { items, subpaths } = await list({
+				path: mockedPath,
+				options: {
+					delimiter: '/',
+					pageSize: 3,
+				},
+			});
+			expect(items).toHaveLength(3);
+			expect(subpaths).toHaveLength(3);
+			expect(listObjectsV2).toHaveBeenCalledTimes(1);
+			await expect(listObjectsV2).toBeLastCalledWithConfigAndInput(
+				listObjectClientConfig,
+				{
+					Bucket: bucket,
+					MaxKeys: 3,
+					Prefix: mockedPath,
+					Delimiter: '/',
+				},
+			);
+		});
+	});
 });

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

@@ -29,6 +29,8 @@ import {
 import { getStorageUserAgentValue } from '../../utils/userAgent';
 import { logger } from '../../../../utils';
 import { STORAGE_INPUT_PREFIX } from '../../utils/constants';
+import { Subpath } from '../../../../types';
+import { CommonPrefix } from '../../utils/client/types';
 
 const MAX_PAGE_SIZE = 1000;
 
@@ -79,6 +81,7 @@ export const list = async (
 		Prefix: isInputWithPrefix ? `${generatedPrefix}${objectKey}` : objectKey,
 		MaxKeys: options?.listAll ? undefined : options?.pageSize,
 		ContinuationToken: options?.listAll ? undefined : options?.nextToken,
+		Delimiter: options?.delimiter,
 	};
 	logger.debug(`listing items from "${listParams.Prefix}"`);
 
@@ -176,23 +179,29 @@ const _listAllWithPath = async ({
 	listParams,
 }: ListInputArgs): Promise<ListAllWithPathOutput> => {
 	const listResult: ListOutputItemWithPath[] = [];
+	const subpaths: Subpath[] = [];
 	let continuationToken = listParams.ContinuationToken;
 	do {
-		const { items: pageResults, nextToken: pageNextToken } =
-			await _listWithPath({
-				s3Config,
-				listParams: {
-					...listParams,
-					ContinuationToken: continuationToken,
-					MaxKeys: MAX_PAGE_SIZE,
-				},
-			});
+		const {
+			items: pageResults,
+			subpaths: pageSubpaths,
+			nextToken: pageNextToken,
+		} = await _listWithPath({
+			s3Config,
+			listParams: {
+				...listParams,
+				ContinuationToken: continuationToken,
+				MaxKeys: MAX_PAGE_SIZE,
+			},
+		});
 		listResult.push(...pageResults);
+		subpaths.push(...(pageSubpaths ?? []));
 		continuationToken = pageNextToken;
 	} while (continuationToken);
 
 	return {
 		items: listResult,
+		...getOptionWithSubpaths(subpaths),
 	};
 };
 
@@ -206,27 +215,49 @@ const _listWithPath = async ({
 		listParamsClone.MaxKeys = MAX_PAGE_SIZE;
 	}
 
-	const response: ListObjectsV2Output = await listObjectsV2(
+	const {
+		Contents: contents,
+		NextContinuationToken: nextContinuationToken,
+		CommonPrefixes: commonPrefixes,
+	}: ListObjectsV2Output = (await listObjectsV2(
 		{
 			...s3Config,
 			userAgentValue: getStorageUserAgentValue(StorageAction.List),
 		},
 		listParamsClone,
-	);
+	)) ?? {};
 
-	if (!response?.Contents) {
+	const subpaths = mapCommonPrefixesToSubpaths(commonPrefixes);
+
+	if (!contents) {
 		return {
 			items: [],
+			...getOptionWithSubpaths(subpaths),
 		};
 	}
 
 	return {
-		items: response.Contents.map(item => ({
+		items: contents.map(item => ({
 			path: item.Key!,
 			eTag: item.ETag,
 			lastModified: item.LastModified,
 			size: item.Size,
 		})),
-		nextToken: response.NextContinuationToken,
+		nextToken: nextContinuationToken,
+		...getOptionWithSubpaths(subpaths),
 	};
 };
+
+function mapCommonPrefixesToSubpaths(
+	commonPrefixes?: CommonPrefix[],
+): Subpath[] | undefined {
+	const mappedSubpaths = commonPrefixes?.map(({ Prefix }) => ({
+		path: Prefix,
+	}));
+
+	return mappedSubpaths as Subpath[] | undefined;
+}
+
+function getOptionWithSubpaths(subpaths?: Subpath[]) {
+	return subpaths && subpaths.length > 0 ? { subpaths } : {};
+}

packages/storage/src/types/common.ts

@@ -55,3 +55,11 @@ export type DownloadTask<Result> = Omit<
 >;
 
 export type UploadTask<Result> = TransferTask<Result>;
+
+/**
+ * Subpath between a root path and a depth
+ *
+ */
+export interface Subpath {
+	path: string;
+}

packages/storage/src/types/index.ts

@@ -6,6 +6,7 @@ export {
 	TransferProgressEvent,
 	TransferTaskState,
 	UploadTask,
+	Subpath,
 } from './common';
 export {
 	StorageGetPropertiesInputWithKey,

packages/storage/src/types/options.ts

@@ -10,12 +10,14 @@ export interface StorageOptions {
 
 export type StorageListAllOptions = StorageOptions & {
 	listAll: true;
+	delimiter?: string;
 };
 
 export type StorageListPaginateOptions = StorageOptions & {
 	listAll?: false;
 	pageSize?: number;
 	nextToken?: string;
+	delimiter?: string;
 };
 
 export type StorageRemoveOptions = StorageOptions;

packages/storage/src/types/outputs.ts

@@ -3,6 +3,8 @@
 
 import { ResponseBodyMixin } from '@aws-amplify/core/internals/aws-client-utils';
 
+import { Subpath } from './common';
+
 /**
  * Base type for a storage item.
  */
@@ -70,4 +72,8 @@ export interface StorageListOutput<Item extends StorageItem> {
 	 * List of items returned by the list API.
 	 */
 	items: Item[];
+	/**
+	 * List of subpaths returned by the list API.
+	 */
+	subpaths?: Subpath[];
 }