add download() method

Hi,
I spent few hours looking into the code, but didn't find the solution.
What am i suppose to do in order to load the content of a file from a createReadStream into a variable ?
In the example there is only a read-to-pipe-to-write example.

I just want to do something like

var streamPointer = cloudstorage.createReadStream(myTextFile)
    streamPointer.on('complete', function(res) {
            myVar = res
        })

@ryanseys

Sorry, it appears our docs are lacking on showing how to simply download a file. Here's the current way to get a file's contents:

var gcloud = require("gcloud")({ /* credentials. */ });
var cloudstorage = gcloud.storage();
var myTextFile = cloudstorage.file('your-file.txt');

var fileContents = new Buffer('');

myTextFile.createReadStream()
  .on('data', function(chunk) {
    fileContents = Buffer.concat([fileContents, chunk]);
  })
  .on('complete', function() {
    // `fileContents` is ready
  });

@ryanseys thoughts on adding Bucket#download to make this easier?

@stephenplusplus

@stephenplusplus That sounds like a good idea. I had an idea for a similar thing that would immediately write to a given filename as well for those wanting to just download a bunch of files. Perhaps we could support both of these options either as separate methods or as an option?

Something like:

myBucket.download("my-file.txt", function (err, contents, file) {
  // contents === file's contents
  // file === myBucket.file("my-file.txt")
})

// and...

myBucket.download("my-file.txt", { destination: "/Users/stephen/Desktop/local-copy.txt" }, function (err, contents, file) {
  // contents === file's contents
  // file === myBucket.file("my-file.txt")
})

// and we can support a File object as a source:
myBucket.download(myBucket.file("my-file.txt"), //...

?

I would say both the .read and .download as wraps for the asynchronous readStream and Pipe, would add a really appreciated level of simplification.

Also, just as overall idea, would be nice to align the interface of the CreateReadStream to the standard (fs) one.
Thanks for the answer!

If we are downloading, wouldn't we just download from a Bucket#file instance? And if we just want to immediately write to a file without storing in memory, that'd be cool... I don't know if we should use two separate methods for that or if we can get away with just one like below:

myFile.download('./local/path/image.jpg', function(err, contents) {
  // don't consume memory
  // contents = null
});

myFile.download(function(err, contents) {
  // consume memory
  // contents = contents of file
});