core: adding promise support (#1670)

packages/bigquery/src/dataset.js

@@ -57,6 +57,14 @@ function Dataset(bigQuery, id) {
      *     // The dataset was created successfully.
      *   }
      * });
+     *
+     * //-
+     * // If the callback is omitted, we'll return a Promise.
+     * //-
+     * dataset.create().then(function(data) {
+     *   var dataset = data[0];
+     *   var apiResponse = data[1];
+     * });
      */
     create: true,
 
@@ -70,6 +78,13 @@ function Dataset(bigQuery, id) {
      *
      * @example
      * dataset.exists(function(err, exists) {});
+     *
+     * //-
+     * // If the callback is omitted, we'll return a Promise.
+     * //-
+     * dataset.exists().then(function(data) {
+     *   var exists = data[0];
+     * });
      */
     exists: true,
 
@@ -91,6 +106,14 @@ function Dataset(bigQuery, id) {
      *     // `dataset.metadata` has been populated.
      *   }
      * });
+     *
+     * //-
+     * // If the callback is omitted, we'll return a Promise.
+     * //-
+     * dataset.get().then(function(data) {
+     *   var dataset = data[0];
+     *   var apiResponse = data[1];
+     * });
      */
     get: true,
 
@@ -107,6 +130,14 @@ function Dataset(bigQuery, id) {
      *
      * @example
      * dataset.getMetadata(function(err, metadata, apiResponse) {});
+     *
+     * //-
+     * // If the callback is omitted, we'll return a Promise.
+     * //-
+     * dataset.getMetadata().then(function(data) {
+     *   var metadata = data[0];
+     *   var apiResponse = data[1];
+     * });
      */
     getMetadata: true,
 
@@ -127,6 +158,13 @@ function Dataset(bigQuery, id) {
      * };
      *
      * dataset.setMetadata(metadata, function(err, apiResponse) {});
+     *
+     * //-
+     * // If the callback is omitted, we'll return a Promise.
+     * //-
+     * dataset.setMetadata(metadata).then(function(data) {
+     *   var apiResponse = data[0];
+     * });
      */
     setMetadata: true
   };
@@ -194,6 +232,14 @@ Dataset.prototype.createQueryStream = function(options) {
  * };
  *
  * dataset.createTable(tableId, options, function(err, table, apiResponse) {});
+ *
+ * //-
+ * // If the callback is omitted, we'll return a Promise.
+ * //-
+ * dataset.createTable(tableId, options).then(function(data) {
+ *   var table = data[0];
+ *   var apiResponse = data[1];
+ * });
  */
 Dataset.prototype.createTable = function(id, options, callback) {
   var self = this;
@@ -270,6 +316,13 @@ Dataset.prototype.createTable = function(id, options, callback) {
  * // Delete the dataset and any tables it contains.
  * //-
  * dataset.delete({ force: true }, function(err, apiResponse) {});
+ *
+ * //-
+ * // If the callback is omitted, we'll return a Promise.
+ * //-
+ * dataset.delete().then(function(data) {
+ *   var apiResponse = data[0];
+ * });
  */
 Dataset.prototype.delete = function(options, callback) {
   if (!callback) {
@@ -310,6 +363,13 @@ Dataset.prototype.delete = function(options, callback) {
  * dataset.getTables(function(err, tables, nextQuery, apiResponse) {
  *   // If `nextQuery` is non-null, there are more results to fetch.
  * });
+ *
+ * //-
+ * // If the callback is omitted, we'll return a Promise.
+ * //-
+ * dataset.getTables().then(function(data) {
+ *   var tables = data[0];
+ * });
  */
 Dataset.prototype.getTables = function(query, callback) {
   var that = this;
@@ -414,4 +474,13 @@ Dataset.prototype.table = function(id) {
  */
 common.paginator.extend(Dataset, ['getTables']);
 
+/*! Developer Documentation
+ *
+ * All async methods (except for streams) will return a Promise in the event
+ * that a callback is omitted.
+ */
+common.util.promisifyAll(Dataset, {
+  exclude: ['table']
+});
+
 module.exports = Dataset;

packages/bigquery/src/index.js

@@ -90,6 +90,14 @@ util.inherits(BigQuery, common.Service);
  *
  * @example
  * bigquery.createDataset('my-dataset', function(err, dataset, apiResponse) {});
+ *
+ * //-
+ * // If the callback is omitted, we'll return a Promise.
+ * //-
+ * bigquery.createDataset('my-dataset').then(function(data) {
+ *   var dataset = data[0];
+ *   var apiResponse = data[1];
+ * });
  */
 BigQuery.prototype.createDataset = function(id, options, callback) {
   var that = this;
@@ -203,6 +211,11 @@ BigQuery.prototype.dataset = function(id) {
  * bigquery.getDatasets({
  *   autoPaginate: false
  * }, callback);
+ *
+ * //-
+ * // If the callback is omitted, we'll return a Promise.
+ * //-
+ * bigquery.getDatasets().then(function(datasets) {});
  */
 BigQuery.prototype.getDatasets = function(query, callback) {
   var that = this;
@@ -317,6 +330,13 @@ BigQuery.prototype.getDatasetsStream =
  * bigquery.getJobs({
  *   autoPaginate: false
  * }, callback);
+ *
+ * //-
+ * // If the callback is omitted, we'll return a Promise.
+ * //-
+ * bigquery.getJobs().then(function(data) {
+ *   var jobs = data[0];
+ * });
  */
 BigQuery.prototype.getJobs = function(options, callback) {
   var that = this;
@@ -443,6 +463,13 @@ BigQuery.prototype.job = function(id) {
  *   query: query,
  *   autoPaginate: false
  * }, callback);
+ *
+ * //-
+ * // If the callback is omitted, we'll return a Promise.
+ * //-
+ * bigquery.query(query).then(function(data) {
+ *   var rows = data[0];
+ * });
  */
 BigQuery.prototype.query = function(options, callback) {
   var self = this;
@@ -558,6 +585,16 @@ BigQuery.prototype.query = function(options, callback) {
  *     job.getQueryResults(function(err, rows, apiResponse) {});
  *   }
  * });
+ *
+ * //-
+ * // If the callback is omitted, we'll return a Promise.
+ * //-
+ * bigquery.startQuery(query).then(function(data) {
+ *   var job = data[0];
+ *   var apiResponse = data[1];
+ *
+ *   return job.getQueryResults();
+ * });
  */
 BigQuery.prototype.startQuery = function(options, callback) {
   var that = this;
@@ -617,6 +654,15 @@ BigQuery.prototype.startQuery = function(options, callback) {
  */
 common.paginator.extend(BigQuery, ['getDatasets', 'getJobs', 'query']);
 
+/*! Developer Documentation
+ *
+ * All async methods (except for streams) will return a Promise in the event
+ * that a callback is omitted.
+ */
+common.util.promisifyAll(BigQuery, {
+  exclude: ['dataset', 'job']
+});
+
 BigQuery.Dataset = Dataset;
 BigQuery.Job = Job;
 BigQuery.Table = Table;

packages/bigquery/src/job.js

@@ -87,6 +87,13 @@ function Job(bigQuery, id) {
      *
      * @example
      * job.exists(function(err, exists) {});
+     *
+     * //-
+     * // If the callback is omitted, we'll return a Promise.
+     * //-
+     * job.exists().then(function(data) {
+     *   var exists = data[0];
+     * });
      */
     exists: true,
 
@@ -99,6 +106,14 @@ function Job(bigQuery, id) {
      *     // `job.metadata` has been populated.
      *   }
      * });
+     *
+     * //-
+     * // If the callback is omitted, we'll return a Promise.
+     * //-
+     * job.get().then(function(data) {
+     *   var job = data[0];
+     *   var apiResponse = data[1];
+     * });
      */
     get: true,
 
@@ -117,6 +132,14 @@ function Job(bigQuery, id) {
      * @example
      * var job = bigquery.job('id');
      * job.getMetadata(function(err, metadata, apiResponse) {});
+     *
+     * //-
+     * // If the callback is omitted, we'll return a Promise.
+     * //-
+     * job.getMetadata().then(function(data) {
+     *   var metadata = data[0];
+     *   var apiResponse = data[1];
+     * });
      */
     getMetadata: true
   };
@@ -168,6 +191,13 @@ modelo.inherits(Job, common.ServiceObject, events.EventEmitter);
  *   job.on('error', function(err) {});
  *   job.on('complete', function(metadata) {});
  * });
+ *
+ * //-
+ * // If the callback is omitted, we'll return a Promise.
+ * //-
+ * job.cancel().then(function(data) {
+ *   var apiResponse = data[0];
+ * });
  */
 Job.prototype.cancel = function(callback) {
   callback = callback || common.util.noop;
@@ -238,6 +268,13 @@ Job.prototype.cancel = function(callback) {
  * job.getQueryResults({
  *   autoPaginate: false
  * }, callback);
+ *
+ * //-
+ * // If the callback is omitted, we'll return a Promise.
+ * //-
+ * job.getQueryResults().then(function(data) {
+ *   var rows = data[0];
+ * });
  */
 Job.prototype.getQueryResults = function(options, callback) {
   if (is.fn(options)) {
@@ -341,4 +378,11 @@ Job.prototype.startPolling_ = function() {
   });
 };
 
+/*! Developer Documentation
+ *
+ * All async methods (except for streams) will return a Promise in the event
+ * that a callback is omitted.
+ */
+common.util.promisifyAll(Job);
+
 module.exports = Job;