storage: add download() method

lib/storage/file.js

@@ -25,6 +25,7 @@ var ConfigStore = require('configstore');
 var crc = require('fast-crc32c');
 var crypto = require('crypto');
 var duplexify = require('duplexify');
+var fs = require('fs');
 var request = require('request');
 var streamEvents = require('stream-events');
 var through = require('through2');
@@ -619,6 +620,59 @@ File.prototype.delete = function(callback) {
   }.bind(this));
 };
 
+/**
+ * Convenience method to download a file into memory or to a local destination.
+ *
+ * @param {object=} options - Optional configuration. The arguments match those
+ *     passed to {module:storage/file#createReadStream}.
+ * @param {string} options.destination - Local file path to write the file's
+ *     contents to.
+ * @param {function} callback - The callback function.
+ *
+ * @example
+ * //-
+ * // Download a file into memory.
+ * //-
+ * file.download(function(err, contents) {});
+ *
+ * //-
+ * // Download a file to a local destination.
+ * //-
+ * file.download({
+ *   destination: '/Users/stephen/Desktop/file-backup.txt'
+ * }, function(err) {});
+ */
+File.prototype.download = function(options, callback) {
+  if (util.is(options, 'function')) {
+    callback = options;
+    options = {};
+  }
+
+  var destination = options.destination;
+  delete options.destination;
+
+  var fileStream = this.createReadStream(options);
+
+  if (destination) {
+    fileStream
+      .on('error', callback)
+      .pipe(fs.createWriteStream(destination))
+      .on('error', callback)
+      .on('finish', callback);
+  } else {
+    var fileContents = new Buffer('');
+
+    fileStream
+      .on('error', callback)
+      .on('data', function(chunk) {
+        fileContents = Buffer.concat([fileContents, chunk]);
+      })
+      .on('complete', function() {
+        callback(null, fileContents);
+      });
+  }
+};
+
 /**
  * Get the file's metadata.
  *

regression/storage.js

@@ -362,6 +362,20 @@ describe('storage', function() {
       });
     });
 
+    it('should download a file to memory', function(done) {
+      var fileContents = fs.readFileSync(files.big.path);
+
+      bucket.upload(files.big.path, function(err, file) {
+        assert.ifError(err);
+
+        file.download(function(err, remoteContents) {
+          assert.ifError();
+          assert.equal(fileContents, remoteContents);
+          done();
+        });
+      });
+    });
+
     describe('stream write', function() {
       it('should stream write, then remove file (3mb)', function(done) {
         var file = bucket.file('LargeFile');

test/storage/file.js

@@ -24,11 +24,13 @@ var crc = require('fast-crc32c');
 var crypto = require('crypto');
 var duplexify = require('duplexify');
 var extend = require('extend');
+var fs = require('fs');
 var mockery = require('mockery');
 var nodeutil = require('util');
 var request = require('request');
 var stream = require('stream');
 var through = require('through2');
+var tmp = require('tmp');
 var url = require('url');
 var util = require('../../lib/common/util');
 
@@ -741,6 +743,129 @@ describe('File', function() {
     });
   });
 
+  describe('download', function() {
+    var fileReadStream;
+
+    beforeEach(function() {
+      fileReadStream = new stream.Readable();
+      fileReadStream._read = util.noop;
+
+      fileReadStream.on('end', function() {
+        fileReadStream.emit('complete');
+      });
+
+      file.createReadStream = function() {
+        return fileReadStream;
+      };
+    });
+
+    it('should accept just a callback', function(done) {
+      fileReadStream._read = function() {
+        done();
+      };
+
+      file.download(assert.ifError);
+    });
+
+    it('should accept an options object and callback', function(done) {
+      fileReadStream._read = function() {
+        done();
+      };
+
+      file.download({}, assert.ifError);
+    });
+
+    it('should pass the provided options to createReadStream', function(done) {
+      var readOptions = { start: 100, end: 200 };
+
+      file.createReadStream = function(options) {
+        assert.deepEqual(options, readOptions);
+        done();
+        return fileReadStream;
+      };
+
+      file.download(readOptions, assert.ifError);
+    });
+
+    describe('into memory', function() {
+      it('should buffer a file into memory if no destination', function(done) {
+        var fileContents = 'abcdefghijklmnopqrstuvwxyz';
+
+        fileReadStream._read = function() {
+          this.push(fileContents);
+          this.push(null);
+        };
+
+        file.download(function(err, remoteFileContents) {
+          assert.ifError(err);
+
+          assert.equal(fileContents, remoteFileContents);
+          done();
+        });
+      });
+
+      it('execute callback with error', function(done) {
+        var error = new Error('Error.');
+
+        fileReadStream._read = function() {
+          this.emit('error', error);
+        };
+
+        file.download(function(err) {
+          assert.equal(err, error);
+          done();
+        });
+      });
+    });
+
+    describe('with destination', function() {
+      it('should write the file to a destination if provided', function(done) {
+        tmp.setGracefulCleanup();
+        tmp.file(function _tempFileCreated(err, tmpFilePath) {
+          assert.ifError(err);
+
+          var fileContents = 'abcdefghijklmnopqrstuvwxyz';
+
+          fileReadStream._read = function() {
+            this.push(fileContents);
+            this.push(null);
+          };
+
+          file.download({ destination: tmpFilePath }, function(err) {
+            assert.ifError(err);
+
+            fs.readFile(tmpFilePath, function(err, tmpFileContents) {
+              assert.ifError(err);
+
+              assert.equal(fileContents, tmpFileContents);
+              done();
+            });
+          });
+        });
+      });
+
+      it('should execute callback with error', function(done) {
+        var opts = { destination: '/not/real/location' };
+
+        tmp.setGracefulCleanup();
+        tmp.file(function _tempFileCreated(err, tmpFilePath) {
+          assert.ifError(err);
+
+          var error = new Error('Error.');
+
+          fileReadStream._read = function() {
+            this.emit('error', error);
+          };
+
+          file.download({ destination: tmpFilePath }, function(err) {
+            assert.equal(err, error);
+            done();
+          });
+        });
+      });
+    });
+  });
+
   describe('getMetadata', function() {
     var metadata = { a: 'b', c: 'd' };