feat(js): list api subpathStrategy parameter

src/pages/[platform]/build-a-backend/storage/list-files/index.mdx

@@ -29,7 +29,7 @@ export function getStaticProps(context) {
   };
 }
 
-You can list files without having to download all the files. You can do this by using the listFile API from the Amplify Library for Storage. You can also get properties individually for a file using the getProperties API.
+You can list files without having to download all the files. You can do this by using the `list` API from the Amplify Library for Storage. You can also get properties individually for a file using the getProperties API.
 
 ## List Files
 
@@ -65,7 +65,16 @@ The format of the response will look similar to the below example:
 }
 ```
 {/* in other files we're referring to paths instead of folders, can we be consistent on terminology? */}
-Manually created folders will show up as files with a `size` of 0, but you can also match keys against a regex like `file.key.match(/\.[0-9a-z]+$/i)` to distinguish files from folders. Since "folders" are a virtual concept in Amazon S3, any file may declare any depth of folder just by having a `/` in its name. If you need to list all the folders, you'll have to parse them accordingly to get an authoritative list of files and folders:
+Manually created folders will show up as files with a `size` of 0, but you can also match keys against a regex like `file.key.match(/\.[0-9a-z]+$/i)` to distinguish files from folders. Since "folders" are a virtual concept in Amazon S3, any file may declare any depth of folder just by having a `/` in its name. 
+
+To access the contents and subpaths of a "folder", you have two options:
+
+1. Request the entire path and parse the contents.
+2. Use the subpathStrategy option to retrieve only the files within the specified path (i.e. exclude files under subpaths).
+
+### Get all nested files within a path
+
+This retrieves all files and folders under a given path. You may need to parse the result to get only the files within the specified path.
 
 ```js
 function processStorageList(response) {
@@ -109,6 +118,61 @@ function processStorageList(response) {
 
 This places each item's data inside a special `__data` key.
 
+### Excluding subpaths
+
+In addition to using the `list` API to get all the contents of a path, you can also use it to get only the files within a path while excluding files under subpaths.
+
+For example, given the following keys in your `path` you may want to return only the jpg object, and not the "vacation" subpath and its contents:
+
+```
+photos/photo1.jpg
+photos/vacation/
+```
+
+This can be accomplished with the `subpathStrategy` option:
+
+```js
+const result = await list({ 
+  path: "photos/",
+  options:{
+    subpathStrategy: { strategy:'exclude' }
+  }
+});
+```
+
+The response will include only the objects within the `photos/` path and will also communicate any excluded subpaths:
+
+```js
+{
+    excludedSubpaths: [
+      'photos/vacation/'
+    ],
+    items: [
+      {
+        path: "photos/photo1.jpg",
+        eTag: "30074401292215403a42b0739f3b5262",
+        lastModified: "Thu Oct 08 2020 23:59:31 GMT+0800 (Singapore Standard Time)",
+        size: 138256
+      },
+    ]
+}
+```
+
+The default delimiter character is '/', but this can be changed by supplying a custom delimiter:
+
+```js
+const result = await list({ 
+  // Path uses '-' character to organize files rather than '/'
+  path: "photos-",
+  options:{
+    subpathStrategy: { 
+      strategy:'exclude',
+      delimiter: '-'
+    }
+  }
+});
+```
+
 ### More `list` options
 
 Option | Type | Description |