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

…2521)

* feature added

* fix

* Added system test and sample test cases

* copyright fix

* build: fix path-to-regexp to older version due to node 14 requirement

* 🦉 Updates from OwlBot post-processor

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

* Remove unnecessary sample code

* Manually modify README regards remove unnecessary sample code

---------

Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>

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"

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 = (