feat(storage-manager): add prefix prop to support gen2 use cases (aws-amplify#5176)

* feat(storage-manager): add prefix prop to support gen2 use cases

Author: zchenwei

.changeset/fair-tips-deliver.md

@@ -0,0 +1,6 @@
+---
+"@aws-amplify/ui-react-storage": minor
+"@aws-amplify/ui-react": patch
+---
+
+feat(storage-manager): add the `prefix` prop to support gen2 use cases

packages/react-storage/package.json

@@ -58,7 +58,7 @@
       "name": "StorageManager",
       "path": "dist/esm/index.mjs",
       "import": "{ StorageManager }",
-      "limit": "25 kB"
+      "limit": "25.2 kB"
     }
   ]
 }

packages/react-storage/src/components/StorageManager/StorageManager.tsx

@@ -1,10 +1,16 @@
 import * as React from 'react';
 
-import { UploadDataOutput } from 'aws-amplify/storage';
+import {
+  UploadDataOutput,
+  UploadDataWithPathOutput,
+} from 'aws-amplify/storage';
 import { getLogger, ComponentClassName } from '@aws-amplify/ui';
 import { VisuallyHidden } from '@aws-amplify/ui-react';
 import { useSetUserAgent } from '@aws-amplify/ui-react-core';
-import { useDropZone } from '@aws-amplify/ui-react/internal';
+import {
+  useDropZone,
+  useDeprecationWarning,
+} from '@aws-amplify/ui-react/internal';
 
 import { useStorageManager, useUploadFiles } from './hooks';
 import { FileStatus, StorageManagerProps, StorageManagerHandle } from './types';
@@ -43,11 +49,39 @@ function StorageManagerBase(
     processFile,
     components,
     path,
+    prefix,
   }: StorageManagerProps,
   ref: React.ForwardedRef<StorageManagerHandle>
 ): JSX.Element {
-  if (!accessLevel || !maxFileCount) {
-    logger.warn('StorageManager requires accessLevel and maxFileCount props');
+  useDeprecationWarning({
+    message:
+      'The `accessLevel` and `path` props have been deprecated in favor of the `prefix` prop.',
+    shouldWarn: Boolean(accessLevel ?? path),
+  });
+
+  if (!maxFileCount) {
+    logger.warn(
+      '`StorageManager` requires the `maxFileCount` prop to be specified'
+    );
+  }
+
+  if (!prefix && !accessLevel) {
+    // set accessLevel to private to respect the default before adding the `prefix` prop
+    accessLevel = 'private';
+    // accessLevel has been depreacted so only guide the user to pass the `prefix` prop
+    logger.warn('`StorageManager` requires the `prefix` prop to be specified');
+  }
+
+  if (prefix && accessLevel) {
+    throw new Error(
+      'The `prefix` and `accessLevel` props cannot be specified at the same time. Prefer usage of `prefix` as `accessLevel` has been deprecated and will be removed in a future major version'
+    );
+  }
+
+  if (prefix && path) {
+    throw new Error(
+      'The `prefix` and `path` props cannot be specified at the same time. Prefer usage of `prefix` as `path` has been deprecated and will be removed in a future major version'
+    );
   }
 
   const Components = {
@@ -127,6 +161,7 @@ function StorageManagerBase(
     setUploadSuccess,
     processFile,
     path,
+    prefix,
   });
 
   const onFilePickerChange = (event: React.ChangeEvent<HTMLInputElement>) => {
@@ -155,7 +190,7 @@ function StorageManagerBase(
     uploadTask,
   }: {
     id: string;
-    uploadTask: UploadDataOutput;
+    uploadTask: UploadDataOutput | UploadDataWithPathOutput;
   }) => {
     uploadTask.pause();
     setUploadPaused({ id });
@@ -166,7 +201,7 @@ function StorageManagerBase(
     uploadTask,
   }: {
     id: string;
-    uploadTask: UploadDataOutput;
+    uploadTask: UploadDataOutput | UploadDataWithPathOutput;
   }) => {
     uploadTask.resume();
     setUploadResumed({ id });
@@ -177,7 +212,7 @@ function StorageManagerBase(
     uploadTask,
   }: {
     id: string;
-    uploadTask: UploadDataOutput;
+    uploadTask: UploadDataOutput | UploadDataWithPathOutput;
   }) => {
     // At this time we don't know if the delete
     // permissions are enabled (required to cancel upload),

packages/react-storage/src/components/StorageManager/__tests__/StorageManager.test.tsx

@@ -14,6 +14,7 @@ import {
 import { defaultStorageManagerDisplayText } from '../utils';
 
 const warnSpy = jest.spyOn(console, 'warn').mockImplementation();
+const errorSpy = jest.spyOn(console, 'error').mockImplementation();
 
 const uploadDataSpy = jest
   .spyOn(Storage, 'uploadData')
@@ -71,7 +72,8 @@ describe('StorageManager', () => {
       getByText(defaultStorageManagerDisplayText.dropFilesText)
     ).toBeVisible();
 
-    expect(warnSpy).not.toHaveBeenCalled();
+    // acceessLevel prop deprecation warning
+    expect(warnSpy).toHaveBeenCalledTimes(1);
   });
 
   it('renders as expected with autoUpload turned off', () => {
@@ -215,7 +217,8 @@ describe('StorageManager', () => {
   it('renders a warning if maxFileCount is zero', () => {
     render(<StorageManager {...storeManagerProps} maxFileCount={0} />);
 
-    expect(warnSpy).toHaveBeenCalledTimes(1);
+    // missing maxFileCount prop + accessLevel prop deprecation = 2
+    expect(warnSpy).toHaveBeenCalledTimes(2);
   });
 
   it('should trigger hidden input onChange', async () => {
@@ -286,4 +289,38 @@ describe('StorageManager', () => {
     expect(mockClearFiles).toHaveBeenCalledTimes(1);
     expect(mockClearFiles).toHaveBeenCalledWith();
   });
+
+  it('should set accessLevel to private if neither prefix nor accessLevel is specified', () => {
+    const mockUseUploadFiles = jest.fn();
+    jest
+      .spyOn(StorageHooks, 'useUploadFiles')
+      .mockImplementationOnce(mockUseUploadFiles);
+
+    render(<StorageManager maxFileCount={1} />);
+
+    expect(warnSpy).toHaveBeenCalled();
+    expect(mockUseUploadFiles).toHaveBeenCalledWith(
+      expect.objectContaining({ accessLevel: 'private' })
+    );
+  });
+
+  it('should throw an error if both prefix and accessLevel are specified', () => {
+    expect(() =>
+      render(
+        <StorageManager
+          prefix="prefix/"
+          accessLevel="private"
+          maxFileCount={1}
+        />
+      )
+    ).toThrow();
+    expect(errorSpy).toHaveBeenCalled();
+  });
+
+  it('should throw an error if both prefix and path are specified', () => {
+    expect(() =>
+      render(<StorageManager prefix="prefix/" path="path/" maxFileCount={1} />)
+    ).toThrow();
+    expect(errorSpy).toHaveBeenCalled();
+  });
 });

packages/react-storage/src/components/StorageManager/hooks/useStorageManager/actions.ts

@@ -1,4 +1,7 @@
-import { UploadDataOutput } from 'aws-amplify/storage';
+import {
+  UploadDataOutput,
+  UploadDataWithPathOutput,
+} from 'aws-amplify/storage';
 
 import { FileStatus } from '../../types';
 
@@ -38,7 +41,7 @@ export const setUploadingFileAction = ({
   uploadTask,
 }: {
   id: string;
-  uploadTask: UploadDataOutput | undefined;
+  uploadTask: UploadDataOutput | UploadDataWithPathOutput | undefined;
 }): Action => {
   return {
     type: StorageManagerActionTypes.SET_STATUS_UPLOADING,

packages/react-storage/src/components/StorageManager/hooks/useStorageManager/reducer.ts

@@ -73,7 +73,7 @@ export function storageManagerStateReducer(
               ...currentFile,
               status: FileStatus.UPLOADING,
               progress: 0,
-              uploadTask: uploadTask ? uploadTask : undefined,
+              uploadTask,
             },
           ];
         }

packages/react-storage/src/components/StorageManager/hooks/useStorageManager/types.ts

@@ -1,4 +1,7 @@
-import { UploadDataOutput } from 'aws-amplify/storage';
+import {
+  UploadDataOutput,
+  UploadDataWithPathOutput,
+} from 'aws-amplify/storage';
 
 import { FileStatus, StorageFiles } from '../../types';
 
@@ -39,7 +42,7 @@ export type Action =
   | {
       type: StorageManagerActionTypes.SET_STATUS_UPLOADING;
       id: string;
-      uploadTask?: UploadDataOutput;
+      uploadTask?: UploadDataOutput | UploadDataWithPathOutput;
     }
   | {
       type: StorageManagerActionTypes.SET_UPLOAD_PROGRESS;

packages/react-storage/src/components/StorageManager/hooks/useStorageManager/useStorageManager.tsx

@@ -1,6 +1,9 @@
 import React from 'react';
 
-import { UploadDataOutput } from 'aws-amplify/storage';
+import {
+  UploadDataOutput,
+  UploadDataWithPathOutput,
+} from 'aws-amplify/storage';
 import { isObject } from '@aws-amplify/ui';
 
 import { StorageFiles, FileStatus, DefaultFile } from '../../types';
@@ -26,7 +29,7 @@ export interface UseStorageManager {
   queueFiles: () => void;
   setUploadingFile: (params: {
     id: string;
-    uploadTask?: UploadDataOutput;
+    uploadTask?: UploadDataOutput | UploadDataWithPathOutput;
   }) => void;
   setUploadProgress: (params: { id: string; progress: number }) => void;
   setUploadSuccess: (params: { id: string }) => void;

packages/react-storage/src/components/StorageManager/hooks/useUploadFiles/__tests__/useUploadFiles.spec.ts

@@ -14,7 +14,10 @@ const uploadDataSpy = jest
       pause: jest.fn(),
       resume: jest.fn(),
       state: 'SUCCESS',
-      result: Promise.resolve({ key: input.key, data: input.data }),
+      result: Promise.resolve({
+        key: input.key,
+        data: input.data,
+      }),
     };
   });
 
@@ -212,4 +215,29 @@ describe('useUploadFiles', () => {
       );
     });
   });
+
+  it('prepends valid provided `prefix` to `processedKey`', async () => {
+    const prefix = 'test-prefix/';
+    const { waitForNextUpdate } = renderHook(() =>
+      useUploadFiles({
+        ...props,
+        isResumable: true,
+        files: [mockQueuedFile],
+        prefix,
+        accessLevel: undefined,
+      })
+    );
+
+    waitForNextUpdate();
+
+    await waitFor(() => {
+      expect(mockOnUploadStart).toHaveBeenCalledWith({
+        key: `${prefix}${mockQueuedFile.key}`,
+      });
+      expect(uploadDataSpy).toHaveBeenCalledTimes(1);
+      expect(uploadDataSpy).toHaveBeenCalledWith(
+        expect.objectContaining({ path: `${prefix}${mockQueuedFile.key}` })
+      );
+    });
+  });
 });

packages/react-storage/src/components/StorageManager/hooks/useUploadFiles/useUploadFiles.ts

@@ -1,7 +1,7 @@
 import * as React from 'react';
 
 import { TransferProgressEvent } from 'aws-amplify/storage';
-import { isFunction, isString } from '@aws-amplify/ui';
+import { isFunction } from '@aws-amplify/ui';
 
 import { uploadFile } from '../../utils/uploadFile';
 import { FileStatus } from '../../types';
@@ -20,6 +20,7 @@ export interface UseUploadFilesProps
       | 'maxFileCount'
       | 'processFile'
       | 'path'
+      | 'prefix'
     >,
     Pick<
       UseStorageManager,
@@ -39,6 +40,7 @@ export function useUploadFiles({
   maxFileCount,
   processFile,
   path,
+  prefix,
 }: UseUploadFilesProps): void {
   React.useEffect(() => {
     const filesReadyToUpload = files.filter(
@@ -72,18 +74,19 @@ export function useUploadFiles({
       if (file) {
         resolveFile({ processFile, file, key }).then(
           ({ key: processedKey, ...rest }) => {
-            // prepend `path` to `processedKey`
-            const resolvedKey = isString(path)
-              ? `${path}${processedKey}`
-              : processedKey;
+            // prepend `prefix` or `path` to `processedKey`
+            // TODO: path will be deprecated in the future
+            const resolvedKey = `${prefix ?? path ?? ''}${processedKey}`;
 
             if (isFunction(onUploadStart)) {
               onUploadStart({ key: resolvedKey });
             }
 
             const uploadTask = uploadFile({
               ...rest,
+              // key will be deprecated in the future
               key: resolvedKey,
+              path: resolvedKey,
               level: accessLevel,
               progressCallback: onProgress,
               errorCallback: (error: string) => {
@@ -112,5 +115,6 @@ export function useUploadFiles({
     setUploadSuccess,
     processFile,
     path,
+    prefix,
   ]);
 }

packages/react-storage/src/components/StorageManager/types.ts

@@ -1,6 +1,9 @@
 import * as React from 'react';
 
-import type { UploadDataOutput } from 'aws-amplify/storage';
+import type {
+  UploadDataOutput,
+  UploadDataWithPathOutput,
+} from 'aws-amplify/storage';
 import type { StorageAccessLevel } from '@aws-amplify/core';
 
 import {
@@ -27,7 +30,7 @@ export interface StorageFile {
   file?: File;
   status: FileStatus;
   progress: number;
-  uploadTask?: UploadDataOutput;
+  uploadTask?: UploadDataOutput | UploadDataWithPathOutput;
   key: string;
   error: string;
   isImage: boolean;
@@ -55,10 +58,10 @@ export interface StorageManagerProps {
    */
   acceptedFileTypes?: string[];
   /**
-   * Access level for file uploads
-   * @see https://docs.amplify.aws/lib/storage/configureaccess/q/platform/js/
+   * @deprecated
+   * `accessLevel` has been deprecated in favor of `prefix` and will be removed in a future major version
    */
-  accessLevel: StorageAccessLevel;
+  accessLevel?: StorageAccessLevel;
 
   /**
    * Determines if the upload will automatically start after a file is selected, default value: true
@@ -120,9 +123,12 @@ export interface StorageManagerProps {
    */
   showThumbnails?: boolean;
   /**
-   * A path to put files in the s3 bucket.
-   * This will be prepended to the key sent to
-   * s3 for each file.
+   * @deprecated
+   * `path` has been deprecated in favor of `prefix` and will be removed in a future major version
    */
   path?: string;
+  /**
+   * A string prefixed to the key of each file
+   */
+  prefix?: string;
 }