add a bucket#getDirectories() helper method

From @esprehn on September 5, 2017 21:1

Environment details

• OS: OS X
• Node.js version: v6.10.3
• npm version: 3.10.10
• google-cloud-node version: 1.2.1

Steps to reproduce

1. require google-cloud

bucket.getFiles({ delimiter: '/' }, function(err, files, nextQuery, api) {
  console.log(err, files, nextQuery, api);
});

Will print null [] undefined undefined.

This is very confusing, it seems you need to pass autoPaginate: false to get the api response back.

Looking at the code I don’t know where this happens, the code does:

    var nextQuery = null;
    if (resp.nextPageToken) {
      nextQuery = extend({}, query, {
        pageToken: resp.nextPageToken
      });
    }

    callback(null, files, nextQuery, resp);

And if you console.log(resp) here it’s non-undefined, but by the time it gets to your callback it’s undefined. Where did the extra arguments end up?

Note also that while other apis return the ApiResponse in the second position of the array, getFiles does’t so you can’t do:

const [files, api] = await bucket.getFiles({ delimiter: '/' });
console.log(api.prefixes);

and instead you must pass a callback.

Copied from original issue: GoogleCloudPlatform/google-cloud-node#2594

[lukesneeringer]

From @stephenplusplus on September 5, 2017 21:14

The apiResponse pattern is library-wide and could certainly be re-opened for discussion. Many of our API calls are not autopagination methods, and because of this, it’s easy to return our simplified response alongside the raw API response. However, the autopagination methods involve multiple raw API responses, which is why we didn’t include them; it wouldn’t be clear which of many objects were relevant to the user.

Do you think we should return an array of responses?

A couple notes;

For list operations, we assign the relevant section of the raw API response to our custom object that’s returned. E.g., for storage.getFiles, each returned File object has a metadata property that includes many details from the API response. I’m pointing this out just to note that we don’t discard the entire API response, just the outer shell.

The other way to fix this problem (and ones like it) is to add a new method to get what you’re after, e.g. storage.getDirectories()

@callmehiphop @lukesneeringer for thoughts.

[stephenplusplus]

I sent a PR to accept a directory option to getFiles(): #162

At this point, it’s basically just an alias for prefix. I wasn’t sure what would be the most useful way to add the concept of a directory, so feel free to comment with suggestions. Thanks!