feat(listBuckets): Add support for returning partial success

samples/listBucketsPartialSuccess.js

@@ -0,0 +1,50 @@
+/**
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+function main() {
+  // [START storage_list_buckets_partial_success]
+  // Imports the Google Cloud client library
+  const {Storage} = require('@google-cloud/storage');
+
+  // Creates a client
+  const storage = new Storage();
+
+  async function listBucketsPartialSuccess() {
+    const option = {
+      returnPartialSuccess: true,
+    };
+    const result = await storage.getBuckets(option);
+    const buckets = result[0]; // Extract the list of successfully retrieved Bucket objects.
+    const unreachable = result[3]; // Extract the list of unreachable buckets.
+
+    console.log('Buckets:');
+    buckets.forEach(bucket => {
+      console.log(bucket.name);
+    });
+
+    if (unreachable && unreachable.length > 0) {
+      console.log('Unreachable Buckets:');
+      unreachable.forEach(item => {
+        console.log(item);
+      });
+    }
+  }
+
+  listBucketsPartialSuccess().catch(console.error);
+  // [END storage_list_buckets_partial_success]
+}
+
+main(...process.argv.slice(2));

src/storage.ts

@@ -170,13 +170,16 @@ export interface BucketCallback {
   (err: Error | null, bucket?: Bucket | null, apiResponse?: unknown): void;
 }
 
-export type GetBucketsResponse = [Bucket[], {}, unknown];
+export type GetBucketsResponse =
+  | [Bucket[], {}, unknown]
+  | [Bucket[], {}, unknown, string[]];
 export interface GetBucketsCallback {
   (
     err: Error | null,
     buckets: Bucket[],
     nextQuery?: {},
-    apiResponse?: unknown
+    apiResponse?: unknown,
+    unreachable?: string[]
   ): void;
 }
 export interface GetBucketsRequest {
@@ -189,6 +192,7 @@ export interface GetBucketsRequest {
   userProject?: string;
   softDeleted?: boolean;
   generation?: number;
+  returnPartialSuccess?: boolean;
 }
 
 export interface HmacKeyResourceResponse {
@@ -1325,6 +1329,7 @@ export class Storage extends Service {
       cb
     );
     options.project = options.project || this.projectId;
+    const returnPartialSuccess = options.returnPartialSuccess || false;
 
     this.request(
       {
@@ -1338,6 +1343,8 @@ export class Storage extends Service {
         }
 
         const itemsArray = resp.items ? resp.items : [];
+        const unreachableBuckets = resp.unreachable ? resp.unreachable : [];
+
         const buckets = itemsArray.map((bucket: BucketMetadata) => {
           const bucketInstance = this.bucket(bucket.id!);
           bucketInstance.metadata = bucket;
@@ -1348,6 +1355,10 @@ export class Storage extends Service {
           ? Object.assign({}, options, {pageToken: resp.nextPageToken})
           : null;
 
+        if (returnPartialSuccess && unreachableBuckets.length > 0) {
+          callback(null, buckets, nextQuery, resp, unreachableBuckets);
+          return;
+        }
         callback(null, buckets, nextQuery, resp);
       }
     );

test/index.ts

@@ -1177,6 +1177,133 @@ describe('Storage', () => {
         done();
       });
     });
+
+    it('should return unreachable when returnPartialSuccess is true', done => {
+      const unreachableList = [
+        'projects/_/buckets/fail-bucket1',
+        'projects/_/buckets/fail-bucket2',
+      ];
+      const itemsList = [{id: 'fake-bucket-name'}];
+      const resp = {items: itemsList, unreachable: unreachableList};
+
+      storage.request = (
+        reqOpts: DecorateRequestOptions,
+        callback: Function
+      ) => {
+        assert.strictEqual(reqOpts.qs.returnPartialSuccess, true);
+        callback(null, resp);
+      };
+
+      storage.getBuckets(
+        {returnPartialSuccess: true},
+        (
+          err: Error,
+          buckets: Bucket[],
+          nextQuery: {},
+          apiResponse: {},
+          unreachable: string[]
+        ) => {
+          assert.ifError(err);
+          assert.strictEqual(buckets.length, 1);
+          assert.deepStrictEqual(unreachable, unreachableList);
+          assert.deepStrictEqual(apiResponse, resp);
+          done();
+        }
+      );
+    });
+
+    it('should not return unreachable when returnPartialSuccess is false and unreachable items exist', done => {
+      const unreachableList = ['projects/_/buckets/fail-bucket1'];
+      const itemsList = [{id: 'fake-bucket-name'}];
+      const resp = {items: itemsList, unreachable: unreachableList};
+
+      storage.request = (
+        reqOpts: DecorateRequestOptions,
+        callback: Function
+      ) => {
+        assert.strictEqual(reqOpts.qs.returnPartialSuccess, false);
+        callback(null, resp);
+      };
+
+      storage.getBuckets(
+        {returnPartialSuccess: false},
+        (
+          err: Error,
+          buckets: Bucket[],
+          nextQuery: {},
+          apiResponse: {},
+          unreachable: string[]
+        ) => {
+          assert.ifError(err);
+          assert.strictEqual(unreachable, undefined);
+          assert.deepStrictEqual(
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            (apiResponse as any).unreachable,
+            unreachableList
+          );
+          done();
+        }
+      );
+    });
+
+    it('should handle partial failure with zero reachable buckets', done => {
+      const unreachableList = ['projects/_/buckets/fail-bucket1'];
+      const resp = {items: [], unreachable: unreachableList};
+
+      storage.request = (
+        reqOpts: DecorateRequestOptions,
+        callback: Function
+      ) => {
+        callback(null, resp);
+      };
+
+      storage.getBuckets(
+        {returnPartialSuccess: true},
+        (
+          err: Error,
+          buckets: Bucket[],
+          nextQuery: {},
+          resp: unknown,
+          unreachable: string[]
+        ) => {
+          assert.ifError(err);
+          assert.strictEqual(buckets.length, 0);
+          assert.deepStrictEqual(unreachable, unreachableList);
+          done();
+        }
+      );
+    });
+
+    it('should handle API success where zero items and zero unreachable items are returned', done => {
+      const resp = {items: [], unreachable: []};
+
+      storage.request = (
+        reqOpts: DecorateRequestOptions,
+        callback: Function
+      ) => {
+        if (reqOpts.qs.returnPartialSuccess !== undefined) {
+          assert.strictEqual(reqOpts.qs.returnPartialSuccess, true);
+        }
+        callback(null, resp);
+      };
+
+      storage.getBuckets(
+        {returnPartialSuccess: true},
+        (
+          err: Error,
+          buckets: Bucket[],
+          nextQuery: {},
+          apiResponse: {},
+          unreachable: string[]
+        ) => {
+          assert.ifError(err);
+          assert.strictEqual(buckets.length, 0);
+          assert.strictEqual(unreachable, undefined);
+          assert.deepStrictEqual(apiResponse, resp);
+          done();
+        }
+      );
+    });
   });
 
   describe('getHmacKeys', () => {