streamrouter: implement across storage

lib/storage/bucket.js

@@ -38,6 +38,12 @@ var Acl = require('./acl.js');
  */
 var File = require('./file.js');
 
+/**
+ * @type {module:common/streamrouter}
+ * @private
+ */
+var streamRouter = require('../common/stream-router.js');
+
 /**
  * @type {module:common/util}
  * @private
@@ -378,6 +384,18 @@ Bucket.prototype.file = function(name, options) {
  * }, function(err, files, nextQuery, apiResponse) {
  *   // Each file is scoped to its generation.
  * });
+ *
+ * //-
+ * // Get the files from your bucket as a readable object stream.
+ * //-
+ * bucket.getFiles()
+ *   .on('error', console.error)
+ *   .on('data', function(file) {
+ *     // file is a File object.
+ *   })
+ *   .on('end', function() {
+ *     // All files retrieved.
+ *   });
  */
 Bucket.prototype.getFiles = function(query, callback) {
   var self = this;
@@ -933,4 +951,11 @@ Bucket.prototype.makeReq_ = function(method, path, query, body, callback) {
   this.storage.makeAuthorizedRequest_(reqOpts, callback);
 };
 
+/*! Developer Documentation
+ *
+ * This method can be used with either a callback or as a readable object
+ * stream. `streamRouter` is used to add this dual behavior.
+ */
+streamRouter.extend(Bucket, 'getFiles');
+
 module.exports = Bucket;

lib/storage/index.js

@@ -28,6 +28,12 @@ var extend = require('extend');
  */
 var Bucket = require('./bucket.js');
 
+/**
+ * @type {module:common/streamrouter}
+ * @private
+ */
+var streamRouter = require('../common/stream-router.js');
+
 /**
  * @type {module:common/util}
  * @private
@@ -272,6 +278,18 @@ Storage.prototype.createBucket = function(name, metadata, callback) {
  * gcs.getBuckets({
  *   maxResults: 5
  * }, function(err, buckets, nextQuery, apiResponse) {});
+ *
+ * //-
+ * // Get the buckets from your project as a readable object stream.
+ * //-
+ * gcs.getBuckets()
+ *   .on('error', console.error)
+ *   .on('data', function(bucket) {
+ *     // bucket is a Bucket object.
+ *   })
+ *   .on('end', function() {
+ *     // All buckets retrieved.
+ *   });
  */
 Storage.prototype.getBuckets = function(query, callback) {
   var that = this;
@@ -324,4 +342,11 @@ Storage.prototype.makeReq_ = function(method, path, query, body, callback) {
   this.makeAuthorizedRequest_(reqOpts, callback);
 };
 
+/*! Developer Documentation
+ *
+ * This method can be used with either a callback or as a readable object
+ * stream. `streamRouter` is used to add this dual behavior.
+ */
+streamRouter.extend(Storage, 'getBuckets');
+
 module.exports = Storage;

system-test/storage.js

@@ -18,12 +18,14 @@
 
 var assert = require('assert');
 var async = require('async');
+var Bucket = require('../lib/storage/bucket.js');
 var crypto = require('crypto');
+var File = require('../lib/storage/file.js');
 var fs = require('fs');
 var request = require('request');
 var through = require('through2');
 var tmp = require('tmp');
-var util = require('../lib/common/util');
+var util = require('../lib/common/util.js');
 var uuid = require('node-uuid');
 
 var prop = util.prop;
@@ -440,6 +442,20 @@ describe('storage', function() {
         done();
       }
     });
+
+    it('should get buckets as a stream', function(done) {
+      var bucketEmitted = false;
+
+      storage.getBuckets()
+        .on('error', done)
+        .on('data', function(bucket) {
+          bucketEmitted = bucket instanceof Bucket;
+        })
+        .on('end', function() {
+          assert.strictEqual(bucketEmitted, true);
+          done();
+        });
+    });
   });
 
   describe('bucket metadata', function() {
@@ -720,6 +736,20 @@ describe('storage', function() {
       });
     });
 
+    it('should get files as a stream', function(done) {
+      var fileEmitted = false;
+
+      bucket.getFiles()
+        .on('error', done)
+        .on('data', function(file) {
+          fileEmitted = file instanceof File;
+        })
+        .on('end', function() {
+          assert.strictEqual(fileEmitted, true);
+          done();
+        });
+    });
+
     it('should paginate the list', function(done) {
       var query = { maxResults: filenames.length - 1 };
       bucket.getFiles(query, function(err, files, nextQuery) {

test/storage/bucket.js

@@ -63,6 +63,20 @@ fakeAsync.eachLimit = function() {
   (eachLimit_Override || async.eachLimit).apply(null, arguments);
 };
 
+var extended = false;
+var fakeStreamRouter = {
+  extend: function(Class, methods) {
+    if (Class.name !== 'Bucket') {
+      return;
+    }
+
+    methods = util.arrayize(methods);
+    assert.equal(Class.name, 'Bucket');
+    assert.deepEqual(methods, ['getFiles']);
+    extended = true;
+  }
+};
+
 describe('Bucket', function() {
   var Bucket;
   var BUCKET_NAME = 'test-bucket';
@@ -75,6 +89,7 @@ describe('Bucket', function() {
 
   before(function() {
     mockery.registerMock('./file.js', FakeFile);
+    mockery.registerMock('../common/stream-router.js', fakeStreamRouter);
     mockery.registerMock('async', fakeAsync);
     mockery.registerMock('request', fakeRequest);
     mockery.enable({
@@ -95,7 +110,11 @@ describe('Bucket', function() {
     bucket = new Bucket(options, BUCKET_NAME);
   });
 
-  describe('initialization', function() {
+  describe('instantiation', function() {
+    it('should extend the correct methods', function() {
+      assert(extended); // See `fakeStreamRouter.extend`
+    });
+
     it('should re-use provided connection', function() {
       assert.deepEqual(bucket.authorizeReq_, options.authorizeReq_);
     });

test/storage/index.js

@@ -14,24 +14,63 @@
  * limitations under the License.
  */
 
-/*global describe, it, beforeEach */
-
 'use strict';
 
+// If we don't stub see4_crc32 and use mockery, we get "Module did not self-
+// register".
+var crc = require('sse4_crc32');
+
 var assert = require('assert');
-var Bucket = require('../../lib/storage/bucket.js');
 var extend = require('extend');
-var Storage = require('../../lib/storage');
+var mockery = require('mockery');
+
 var util = require('../../lib/common/util.js');
 
+var extended = false;
+var fakeStreamRouter = {
+  extend: function(Class, methods) {
+    if (Class.name !== 'Storage') {
+      return;
+    }
+
+    methods = util.arrayize(methods);
+    assert.equal(Class.name, 'Storage');
+    assert.deepEqual(methods, ['getBuckets']);
+    extended = true;
+  }
+};
+
 describe('Storage', function() {
+  var Storage;
   var storage;
+  var Bucket;
+
+  before(function() {
+    mockery.registerMock('sse4_crc32', crc);
+    mockery.registerMock('../common/stream-router.js', fakeStreamRouter);
+    mockery.enable({
+      useCleanCache: true,
+      warnOnUnregistered: false
+    });
+
+    Bucket = require('../../lib/storage/bucket.js');
+    Storage = require('../../lib/storage');
+  });
+
+  after(function() {
+    mockery.deregisterAll();
+    mockery.disable();
+  });
 
   beforeEach(function() {
     storage = new Storage({ projectId: 'project-id' });
   });
 
   describe('instantiation', function() {
+    it('should extend the correct methods', function() {
+      assert(extended); // See `fakeStreamRouter.extend`
+    });
+
     it('should throw if a projectId is not specified', function() {
       assert.throws(function() {
         new Storage();