Specify folder parameter for folder-based filter

lib/storage/bucket.js

@@ -226,6 +226,8 @@ Bucket.prototype.file = function(name) {
  *     return.
  * @param {string} query.pageToken - A previously-returned page token
  *     representing part of the larger set of results to view.
+ * @param {string} query.folder - Filter results to objects that are contained
+ *     within the given folder. Results will also include the folder itself.
  * @param {function} callback - The callback function.
  *
  * @example
@@ -235,6 +237,11 @@ Bucket.prototype.file = function(name) {
  *     bucket.getFiles(nextQuery, function(err, files, nextQuery) {});
  *   }
  *
+ *   // The prefixes property contains any prefixes returned in the response.
+ *   // This will only be populated when your request contains the 'folder' or
+ *   // 'delimiter' property.
+ *   files.prefixes;
+ *
  *   // The `metadata` property is populated for you with the metadata at the
  *   // time of fetching.
  *   files[0].metadata;
@@ -250,13 +257,26 @@ Bucket.prototype.file = function(name) {
  * bucket.getFiles({
  *   maxResults: 5
  * }, function(err, files, nextQuery) {});
+ *
+ * //-
+ * // Fetch results within the folder 'hello/world'.
+ * // This is the same as specifying delimiter: '/', prefix: 'hello/world/'.
+ * //-
+ * bucket.getFiles({
+ *   folder: 'hello/world'
+ * }, function(err, files, nextQuery) {});
  */
 Bucket.prototype.getFiles = function(query, callback) {
   var that = this;
   if (!callback) {
     callback = query;
     query = {};
   }
+  if (query.folder) {
+    query.delimiter = '/';
+    query.prefix = query.folder + '/';
+    delete query.folder;
+  }
   this.makeReq_('GET', '/o', query, true, function(err, resp) {
     if (err) {
       callback(err);
@@ -267,6 +287,9 @@ Bucket.prototype.getFiles = function(query, callback) {
       file.metadata = item;
       return file;
     });
+    if (resp.prefixes) {
+      files.prefixes = resp.prefixes; // bad idea?
+    }
     var nextQuery = null;
     if (resp.nextPageToken) {
       nextQuery = extend({}, query, { pageToken: resp.nextPageToken });

test/storage/bucket.js

@@ -152,6 +152,26 @@ describe('Bucket', function() {
       bucket.getFiles({ maxResults: 5, pageToken: token }, util.noop);
     });
 
+    it('should get files based on folder', function(done) {
+      var folder = 'hello/world';
+      bucket.makeReq_ = function(method, path, query, body, callback) {
+        assert.deepEqual(query, { delimiter: '/', prefix: 'hello/world/' });
+        callback(null, { items: [] });
+      };
+      bucket.getFiles({ folder: folder }, done);
+    });
+
+    it('should return prefixes value', function(done) {
+      var prefixes = [ 'hello', 'world' ];
+      bucket.makeReq_ = function(method, path, query, body, callback) {
+        callback(null, { items: [], prefixes: prefixes });
+      };
+      bucket.getFiles({ delimiter: '/' }, function(err, files) {
+        assert.deepEqual(files.prefixes, prefixes);
+        done();
+      });
+    });
+
     it('should return nextQuery if more results exist', function() {
       var token = 'next-page-token';
       bucket.makeReq_ = function(method, path, query, body, callback) {