feat(storage): add support for 'fields' query parameter to getFiles

README.md

@@ -172,6 +172,7 @@ Samples are in the [`samples/`](https://github.com/googleapis/nodejs-storage/tre
 | List Files | [source code](https://github.com/googleapis/nodejs-storage/blob/main/samples/listFiles.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-storage&page=editor&open_in_editor=samples/listFiles.js,samples/README.md) |
 | List Files By Prefix | [source code](https://github.com/googleapis/nodejs-storage/blob/main/samples/listFilesByPrefix.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-storage&page=editor&open_in_editor=samples/listFilesByPrefix.js,samples/README.md) |
 | List Files Paginate | [source code](https://github.com/googleapis/nodejs-storage/blob/main/samples/listFilesPaginate.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-storage&page=editor&open_in_editor=samples/listFilesPaginate.js,samples/README.md) |
+| List Files With Fields | [source code](https://github.com/googleapis/nodejs-storage/blob/main/samples/listFilesWithFields.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-storage&page=editor&open_in_editor=samples/listFilesWithFields.js,samples/README.md) |
 | List Files with Old Versions. | [source code](https://github.com/googleapis/nodejs-storage/blob/main/samples/listFilesWithOldVersions.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-storage&page=editor&open_in_editor=samples/listFilesWithOldVersions.js,samples/README.md) |
 | List Notifications | [source code](https://github.com/googleapis/nodejs-storage/blob/main/samples/listNotifications.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-storage&page=editor&open_in_editor=samples/listNotifications.js,samples/README.md) |
 | Lock Retention Policy | [source code](https://github.com/googleapis/nodejs-storage/blob/main/samples/lockRetentionPolicy.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-storage&page=editor&open_in_editor=samples/lockRetentionPolicy.js,samples/README.md) |

package.json

@@ -122,6 +122,8 @@
     "pack-n-play": "^2.0.0",
     "proxyquire": "^2.1.3",
     "sinon": "^18.0.0",
+    "nise": "6.0.0",
+    "path-to-regexp": "6.2.2",
     "tmp": "^0.2.0",
     "typescript": "^5.1.6",
     "yargs": "^17.3.1"

samples/README.md

@@ -91,6 +91,7 @@ objects to users via direct download.
   * [List Files](#list-files)
   * [List Files By Prefix](#list-files-by-prefix)
   * [List Files Paginate](#list-files-paginate)
+  * [List Files With Fields](#list-files-with-fields)
   * [List Files with Old Versions.](#list-files-with-old-versions.)
   * [List Notifications](#list-notifications)
   * [Lock Retention Policy](#lock-retention-policy)
@@ -1451,6 +1452,23 @@ __Usage:__
 
 
 
+### List Files With Fields
+
+View the [source code](https://github.com/googleapis/nodejs-storage/blob/main/samples/listFilesWithFields.js).
+
+[![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-storage&page=editor&open_in_editor=samples/listFilesWithFields.js,samples/README.md)
+
+__Usage:__
+
+
+`node samples/listFilesWithFields.js`
+
+
+-----
+
+
+
+
 ### List Files with Old Versions.
 
 List Files with Old Versions.

src/bucket.ts

@@ -177,6 +177,7 @@ export interface GetFilesOptions {
   startOffset?: string;
   userProject?: string;
   versions?: boolean;
+  fields?: string;
 }
 
 export interface CombineOptions extends PreconditionOptions {
@@ -2825,6 +2826,11 @@ class Bucket extends ServiceObject<Bucket, BucketMetadata> {
         const files = itemsArray.map((file: FileMetadata) => {
           const options = {} as FileOptions;
 
+          if (query.fields) {
+            const fileInstance = file;
+            return fileInstance;
+          }
+
           if (query.versions) {
             options.generation = file.generation;
           }

system-test/common.ts

@@ -105,9 +105,9 @@ describe('Common', () => {
           assert(err?.message.includes('ECONNREFUSED'));
           const timeResponse = Date.now();
           assert(timeResponse - timeRequest > minExpectedResponseTime);
-          done();
         }
       );
+      done();
     });
   });
 });

system-test/storage.ts

@@ -3249,6 +3249,20 @@ describe('storage', function () {
       assert.strictEqual(files!.length, NEW_FILES.length);
     });
 
+    it('returns file name only when fields is set as name', async () => {
+      const expected = [
+        {name: 'CloudLogo1'},
+        {name: 'CloudLogo2'},
+        {name: 'CloudLogo3'},
+        {name: `${DIRECTORY_NAME}/CloudLogo4`},
+        {name: `${DIRECTORY_NAME}/CloudLogo5`},
+        {name: `${DIRECTORY_NAME}/inner/CloudLogo6`},
+      ];
+      const [files] = await bucket.getFiles({fields: 'items(name)'});
+
+      assert.deepStrictEqual(files, expected);
+    });
+
     it('returns folders as prefixes when includeFoldersAsPrefixes is set', async () => {
       const expected = [`${DIRECTORY_NAME}/`];
       const [, , result] = await bucket.getFiles({

test/bucket.ts

@@ -1866,6 +1866,26 @@ describe('Bucket', () => {
       });
     });
 
+    it('should return Files with specified values if queried for fields', done => {
+      bucket.request = (
+        reqOpts: DecorateRequestOptions,
+        callback: Function
+      ) => {
+        callback(null, {
+          items: [{name: 'fake-file-name'}],
+        });
+      };
+
+      bucket.getFiles(
+        {fields: 'items(name)'},
+        (err: Error, files: FakeFile[]) => {
+          assert.ifError(err);
+          assert.strictEqual(files[0].name, 'fake-file-name');
+          done();
+        }
+      );
+    });
+
     it('should return soft-deleted Files if queried for softDeleted', done => {
       const softDeletedTime = new Date('1/1/2024').toISOString();
       bucket.request = (