core: created streaming methods

package.json

@@ -31,6 +31,7 @@
   },
   "scripts": {
     "postinstall": "node ./scripts/install.js",
+    "link-common": "node ./scripts/link-common.js",
     "update-deps": "node ./scripts/update-deps.js",
     "docs": "node ./scripts/docs/packages.js",
     "bundle": "node ./scripts/docs/bundle.js",

packages/bigquery/src/dataset.js

@@ -288,25 +288,6 @@ Dataset.prototype.delete = function(options, callback) {
  * dataset.getTables(function(err, tables, nextQuery, apiResponse) {
  *   // If `nextQuery` is non-null, there are more results to fetch.
  * });
- *
- * //-
- * // Get the tables as a readable object stream. `table` is a Table object
- * //-
- * dataset.getTables()
- *   .on('error', console.error)
- *   .on('data', function(table) {})
- *   .on('end', function() {
- *     // All tables have been retrieved
- *   });
- *
- * //-
- * // If you anticipate many results, you can end a stream early to prevent
- * // unnecessary processing and API requests.
- * //-
- * dataset.getTables()
- *   .on('data', function(table) {
- *     this.end();
- *   });
  */
 Dataset.prototype.getTables = function(query, callback) {
   var that = this;
@@ -344,6 +325,32 @@ Dataset.prototype.getTables = function(query, callback) {
   });
 };
 
+/**
+ * List all or some of the tables in your project as a readable object stream.
+ *
+ * @param {object=} query - Configuration object. See
+ *     {module:bigquery/dataset#getTables} for a complete list of options.
+ * @return {stream}
+ *
+ * @example
+ * dataset.getTableStream()
+ *   .on('error', console.error)
+ *   .on('data', function(table) {})
+ *   .on('end', function() {
+ *     // All tables have been retrieved
+ *   });
+ *
+ * //-
+ * // If you anticipate many results, you can end a stream early to prevent
+ * // unnecessary processing and API requests.
+ * //-
+ * dataset.getTableStream()
+ *   .on('data', function(table) {
+ *     this.end();
+ *   });
+ */
+Dataset.prototype.getTableStream = common.paginator.streamify('getTables');
+
 /**
  * Run a query scoped to your dataset.
  *
@@ -365,6 +372,28 @@ Dataset.prototype.query = function(options, callback) {
   return this.bigQuery.query(options, callback);
 };
 
+/**
+ * Run a query scoped to your dataset as a readable object stream.
+ *
+ * See {module:bigquery#createQueryStream} for full documentation of this
+ * method.
+ */
+Dataset.prototype.createQueryStream = function(options) {
+  if (is.string(options)) {
+    options = {
+      query: options
+    };
+  }
+
+  options = extend(true, {}, options, {
+    defaultDataset: {
+      datasetId: this.id
+    }
+  });
+
+  return this.bigQuery.createQueryStream(options);
+};
+
 /**
  * Create a Table object.
  *
@@ -380,9 +409,8 @@ Dataset.prototype.table = function(id) {
 
 /*! Developer Documentation
  *
- * These methods can be used with either a callback or as a readable object
- * stream. `streamRouter` is used to add this dual behavior.
+ * These methods can be auto-paginated.
  */
-common.streamRouter.extend(Dataset, ['getTables']);
+common.paginator.extend(Dataset, ['getTables']);
 
 module.exports = Dataset;

packages/bigquery/src/index.js

@@ -146,7 +146,7 @@ BigQuery.prototype.dataset = function(id) {
  * @param {number} query.maxResults - Maximum number of results to return.
  * @param {string} query.pageToken - Token returned from a previous call, to
  *     request the next page of results.
- * @param {function=} callback - The callback function.
+ * @param {function} callback - The callback function.
  * @param {?error} callback.err - An error returned while making this request
  * @param {module:bigquery/dataset[]} callback.datasets - The list of datasets
  *     in your project.
@@ -173,27 +173,6 @@ BigQuery.prototype.dataset = function(id) {
  * bigquery.getDatasets({
  *   autoPaginate: false
  * }, callback);
- *
- * //-
- * // Get the datasets from your project as a readable object stream.
- * //-
- * bigquery.getDatasets()
- *   .on('error', console.error)
- *   .on('data', function(dataset) {
- *     // dataset is a Dataset object.
- *   })
- *   .on('end', function() {
- *     // All datasets retrieved.
- *   });
- *
- * //-
- * // If you anticipate many results, you can end a stream early to prevent
- * // unnecessary processing and API requests.
- * //-
- * bigquery.getDatasets()
- *   .on('data', function(dataset) {
- *     this.end();
- *   });
  */
 BigQuery.prototype.getDatasets = function(query, callback) {
   var that = this;
@@ -232,6 +211,34 @@ BigQuery.prototype.getDatasets = function(query, callback) {
   });
 };
 
+/**
+ * List all or some of the datasets in your project as a readable object stream.
+ *
+ * @param {object=} query - Configuration object. See
+ *     {module:bigquery#getDatasets} for a complete list of options.
+ * @return {stream}
+ *
+ * @example
+ * bigquery.getDatasetStream()
+ *   .on('error', console.error)
+ *   .on('data', function(dataset) {
+ *     // dataset is a Dataset object.
+ *   })
+ *   .on('end', function() {
+ *     // All datasets retrieved.
+ *   });
+ *
+ * //-
+ * // If you anticipate many results, you can end a stream early to prevent
+ * // unnecessary processing and API requests.
+ * //-
+ * bigquery.getDatasetStream()
+ *   .on('data', function(dataset) {
+ *     this.end();
+ *   });
+ */
+BigQuery.prototype.getDatasetStream = common.paginator.streamify('getDatasets');
+
 /**
  * Get all of the jobs from your project.
  *
@@ -251,7 +258,7 @@ BigQuery.prototype.getDatasets = function(query, callback) {
  *     "minimal", to not include the job configuration.
  * @param {string=} options.stateFilter - Filter for job state. Acceptable
  *     values are "done", "pending", and "running".
- * @param {function=} callback - The callback function.
+ * @param {function} callback - The callback function.
  * @param {?error} callback.err - An error returned while making this request
  * @param {module:bigquery/job[]} callback.jobs - The list of jobs in your
  *     project.
@@ -278,27 +285,6 @@ BigQuery.prototype.getDatasets = function(query, callback) {
  * bigquery.getJobs({
  *   autoPaginate: false
  * }, callback);
- *
- * //-
- * // Get the jobs from your project as a readable object stream.
- * //-
- * bigquery.getJobs()
- *   .on('error', console.error)
- *   .on('data', function(job) {
- *     // job is a Job object.
- *   })
- *   .on('end', function() {
- *     // All jobs retrieved.
- *   });
- *
- * //-
- * // If you anticipate many results, you can end a stream early to prevent
- * // unnecessary processing and API requests.
- * //-
- * bigquery.getJobs()
- *   .on('data', function(job) {
- *     this.end();
- *   });
  */
 BigQuery.prototype.getJobs = function(options, callback) {
   var that = this;
@@ -337,6 +323,34 @@ BigQuery.prototype.getJobs = function(options, callback) {
   });
 };
 
+/**
+ * List all or some of the jobs in your project as a readable object stream.
+ *
+ * @param {object=} query - Configuration object. See
+ *     {module:bigquery#getJobs} for a complete list of options.
+ * @return {stream}
+ *
+ * @example
+ * bigquery.getJobStream()
+ *   .on('error', console.error)
+ *   .on('data', function(job) {
+ *     // job is a Job object.
+ *   })
+ *   .on('end', function() {
+ *     // All jobs retrieved.
+ *   });
+ *
+ * //-
+ * // If you anticipate many results, you can end a stream early to prevent
+ * // unnecessary processing and API requests.
+ * //-
+ * bigquery.getJobStream()
+ *   .on('data', function(job) {
+ *     this.end();
+ *   });
+ */
+BigQuery.prototype.getJobStream = common.paginator.streamify('getJobs');
+
 /**
  * Create a reference to an existing job.
  *
@@ -353,8 +367,6 @@ BigQuery.prototype.job = function(id) {
 /**
  * Run a query scoped to your project.
  *
- * This method also runs as a readable stream if you do not provide a callback.
- *
  * @resource [Jobs: query API Documentation]{@link https://cloud.google.com/bigquery/docs/reference/v2/jobs/query}
  *
  * @param {string|object} options - A string SQL query or configuration object.
@@ -370,7 +382,7 @@ BigQuery.prototype.job = function(id) {
  *     complete, in milliseconds, before returning. Default is to return
  *     immediately. If the timeout passes before the job completes, the request
  *     will fail with a `TIMEOUT` error.
- * @param {function=} callback - The callback function.
+ * @param {function} callback - The callback function.
  * @param {?error} callback.err - An error returned while making this request
  * @param {array} callback.rows - The list of results from your query.
  * @param {object} callback.apiResponse - The full API response.
@@ -398,28 +410,6 @@ BigQuery.prototype.job = function(id) {
  *   query: query,
  *   autoPaginate: false
  * }, callback);
- *
- * //-
- * // You can also use the `query` method as a readable object stream by
- * // omitting the callback.
- * //-
- * bigquery.query(query)
- *   .on('error', console.error)
- *   .on('data', function(row) {
- *     // row is a result from your query.
- *   })
- *   .on('end', function() {
- *     // All rows retrieved.
- *   });
- *
- * //-
- * // If you anticipate many results, you can end a stream early to prevent
- * // unnecessary processing and API requests.
- * //-
- * bigquery.query(query)
- *   .on('data', function(row) {
- *     this.end();
- *   });
  */
 BigQuery.prototype.query = function(options, callback) {
   var self = this;
@@ -482,6 +472,34 @@ BigQuery.prototype.query = function(options, callback) {
   }
 };
 
+/**
+ * Run a query scoped to your project as a readable object stream.
+ *
+ * @param {object=} query - Configuration object. See
+ *     {module:bigquery#query} for a complete list of options.
+ * @return {stream}
+ *
+ * @example
+ * bigquery.createQueryStream(query)
+ *   .on('error', console.error)
+ *   .on('data', function(row) {
+ *     // row is a result from your query.
+ *   })
+ *   .on('end', function() {
+ *     // All rows retrieved.
+ *   });
+ *
+ * //-
+ * // If you anticipate many results, you can end a stream early to prevent
+ * // unnecessary processing and API requests.
+ * //-
+ * bigquery.createQueryStream(query)
+ *   .on('data', function(row) {
+ *     this.end();
+ *   });
+ */
+BigQuery.prototype.createQueryStream = common.paginator.streamify('query');
+
 /**
  * Run a query as a job. No results are immediately returned. Instead, your
  * callback will be executed with a {module:bigquery/job} object that you must
@@ -590,10 +608,9 @@ BigQuery.prototype.startQuery = function(options, callback) {
 
 /*! Developer Documentation
  *
- * These methods can be used with either a callback or as a readable object
- * stream. `streamRouter` is used to add this dual behavior.
+ * These methods can be auto-paginated.
  */
-common.streamRouter.extend(BigQuery, ['getDatasets', 'getJobs', 'query']);
+common.paginator.extend(BigQuery, ['getDatasets', 'getJobs', 'query']);
 
 BigQuery.Dataset = Dataset;
 BigQuery.Job = Job;

packages/bigquery/src/job.js

@@ -238,29 +238,41 @@ Job.prototype.cancel = function(callback) {
  * job.getQueryResults({
  *   autoPaginate: false
  * }, callback);
+ */
+Job.prototype.getQueryResults = function(options, callback) {
+  if (is.fn(options)) {
+    callback = options;
+    options = {};
+  }
+
+  options = options || {};
+  options.job = this;
+  this.bigQuery.query(options, callback);
+};
+
+/**
+ * Get the results of a job as a readable object stream.
  *
- * //-
- * // Consume the results from the query as a readable object stream.
- * //-
+ * @param {object=} options - Configuration object. See
+ *     {module:bigquery/job#getQueryResults} for a complete list of options.
+ * @return {stream}
+ *
+ * @example
  * var through2 = require('through2');
  * var fs = require('fs');
  *
- * job.getQueryResults()
+ * job.getQueryResultStream()
  *   .pipe(through2.obj(function (row, enc, next) {
  *     this.push(JSON.stringify(row) + '\n');
  *     next();
  *   }))
  *   .pipe(fs.createWriteStream('./test/testdata/testfile.json'));
  */
-Job.prototype.getQueryResults = function(options, callback) {
-  if (is.fn(options)) {
-    callback = options;
-    options = {};
-  }
-
+Job.prototype.getQueryResultStream = function(options) {
   options = options || {};
   options.job = this;
-  return this.bigQuery.query(options, callback);
+
+  return this.bigQuery.createQueryStream(options);
 };
 
 /**