From af8299a2cbf0529d378b14a799ceb61ae37c25ae Mon Sep 17 00:00:00 2001 From: Stephen Sawchuk Date: Tue, 30 Jun 2015 12:28:31 -0400 Subject: [PATCH] streamrouter: document methods to instruct user on how to exit early --- lib/bigquery/index.js | 40 +++++++++++++++++++++++++++++++-------- lib/bigquery/table.js | 19 +++++++++++++++---- lib/pubsub/index.js | 18 ++++++++++++++++++ lib/pubsub/topic.js | 9 +++++++++ lib/search/index-class.js | 9 +++++++++ lib/search/index.js | 9 +++++++++ lib/storage/bucket.js | 9 +++++++++ lib/storage/index.js | 9 +++++++++ 8 files changed, 110 insertions(+), 12 deletions(-) diff --git a/lib/bigquery/index.js b/lib/bigquery/index.js index 9df378425de..306f6b44aba 100644 --- a/lib/bigquery/index.js +++ b/lib/bigquery/index.js @@ -168,9 +168,14 @@ BigQuery.prototype.dataset = function(id) { * @param {function} callback - The callback function. * * @example - * bigquery.getDatasets(function(err, datasets, nextQuery, apiResponse) { - * // If `nextQuery` is non-null, there are more results to fetch. - * }); + * var callback = function(err, datasets, nextQuery, apiResponse) { + * if (nextQuery) { + * // More results exist. + * bigquery.getDatasets(nextQuery, callback); + * } + * }; + * + * bigquery.getDatasets(callback); * * //- * // Get the datasets from your project as a readable object stream. @@ -183,6 +188,15 @@ BigQuery.prototype.dataset = function(id) { * .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; @@ -250,6 +264,15 @@ BigQuery.prototype.getDatasets = function(query, callback) { * .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; @@ -330,14 +353,15 @@ BigQuery.prototype.job = function(id) { * //- * // You can run a query against your data in a serial manner. * //- - * bigquery.query(query, function(err, rows, nextQuery, apiResponse) { + * var callback = function(err, rows, nextQuery, apiResponse) { * // Handle results here. + * * if (nextQuery) { - * bigquery.query(nextQuery, function(err, rows, nextQuery, apiResponse) { - * // Handle more results here. - * }); + * bigquery.query(nextQuery, callback); * } - * }); + * }; + * + * bigquery.query(query, callback); * * //- * // You can also use the `query` method as a readable object stream by diff --git a/lib/bigquery/table.js b/lib/bigquery/table.js index 814cc0bdacb..627036bb395 100644 --- a/lib/bigquery/table.js +++ b/lib/bigquery/table.js @@ -491,12 +491,14 @@ Table.prototype.getMetadata = function(callback) { * maxResults: 100 * }; * - * table.getRows(options, function(err, rows, nextQuery, apiResponse) { - * // If `nextQuery` is non-null, there are more results to fetch. + * var callback = function(err, rows, nextQuery, apiResponse) { * if (nextQuery) { - * table.getRows(nextQuery, function(err, rows, nextQuery, apiResponse) {}); + * // More results exist. + * table.getRows(nextQuery, callback); * } - * }); + * }; + * + * table.getRows(options, callback); * * //- * // Get the rows as a readable object stream. @@ -507,6 +509,15 @@ Table.prototype.getMetadata = function(callback) { * .on('end', function() { * // All rows have been retrieved. * }); + * + * //- + * // If you anticipate many results, you can end a stream early to prevent + * // unnecessary processing and API requests. + * //- + * table.getRows() + * .on('data', function(row) { + * this.end(); + * }); */ Table.prototype.getRows = function(options, callback) { var that = this; diff --git a/lib/pubsub/index.js b/lib/pubsub/index.js index 5c5ac1026f5..fcdd1f0a781 100644 --- a/lib/pubsub/index.js +++ b/lib/pubsub/index.js @@ -139,6 +139,15 @@ function PubSub(options) { * .on('end', function() { * // All topics retrieved. * }); + * + * //- + * // If you anticipate many results, you can end a stream early to prevent + * // unnecessary processing and API requests. + * //- + * pubsub.getTopics() + * .on('data', function(topic) { + * this.end(); + * }); */ PubSub.prototype.getTopics = function(query, callback) { var self = this; @@ -440,6 +449,15 @@ PubSub.prototype.topic = function(name, options) { * .on('end', function() { * // All subscriptions retrieved. * }); + * + * //- + * // If you anticipate many results, you can end a stream early to prevent + * // unnecessary processing and API requests. + * //- + * pubsub.getSubscriptions() + * .on('data', function(topic) { + * this.end(); + * }); */ PubSub.prototype.getSubscriptions = function(options, callback) { var self = this; diff --git a/lib/pubsub/topic.js b/lib/pubsub/topic.js index cdb9732d43a..602ce68f810 100644 --- a/lib/pubsub/topic.js +++ b/lib/pubsub/topic.js @@ -218,6 +218,15 @@ Topic.prototype.delete = function(callback) { * .on('end', function() { * // All subscriptions retrieved. * }); + * + * //- + * // If you anticipate many results, you can end a stream early to prevent + * // unnecessary processing and API requests. + * //- + * topic.getSubscriptions() + * .on('data', function(subscription) { + * this.end(); + * }); */ Topic.prototype.getSubscriptions = function(options, callback) { if (util.is(options, 'function')) { diff --git a/lib/search/index-class.js b/lib/search/index-class.js index 3226e075489..90cd318df2f 100644 --- a/lib/search/index-class.js +++ b/lib/search/index-class.js @@ -190,6 +190,15 @@ Index.prototype.document = function(id) { * .on('end', function() { * // All documents retrieved. * }); + * + * //- + * // If you anticipate many results, you can end a stream early to prevent + * // unnecessary processing and API requests. + * //- + * index.getDocuments() + * .on('data', function(document) { + * this.end(); + * }); */ Index.prototype.getDocuments = function(query, callback) { var self = this; diff --git a/lib/search/index.js b/lib/search/index.js index 15e16f3ab71..0e59745b256 100644 --- a/lib/search/index.js +++ b/lib/search/index.js @@ -138,6 +138,15 @@ function Search(options) { * .on('end', function() { * // All indexes retrieved. * }); + * + * //- + * // If you anticipate many results, you can end a stream early to prevent + * // unnecessary processing and API requests. + * //- + * search.getIndexes() + * .on('data', function(index) { + * this.end(); + * }); */ Search.prototype.getIndexes = function(query, callback) { var self = this; diff --git a/lib/storage/bucket.js b/lib/storage/bucket.js index ad6d47f16b0..69ecf1d69e6 100644 --- a/lib/storage/bucket.js +++ b/lib/storage/bucket.js @@ -514,6 +514,15 @@ Bucket.prototype.file = function(name, options) { * .on('end', function() { * // All files retrieved. * }); + * + * //- + * // If you anticipate many results, you can end a stream early to prevent + * // unnecessary processing and API requests. + * //- + * bucket.getFiles() + * .on('data', function(file) { + * this.end(); + * }); */ Bucket.prototype.getFiles = function(query, callback) { var self = this; diff --git a/lib/storage/index.js b/lib/storage/index.js index ebd2812d3a9..2100e231121 100644 --- a/lib/storage/index.js +++ b/lib/storage/index.js @@ -290,6 +290,15 @@ Storage.prototype.createBucket = function(name, metadata, callback) { * .on('end', function() { * // All buckets retrieved. * }); + * + * //- + * // If you anticipate many results, you can end a stream early to prevent + * // unnecessary processing and API requests. + * //- + * gcs.getBuckets() + * .on('data', function(bucket) { + * this.end(); + * }); */ Storage.prototype.getBuckets = function(query, callback) { var that = this;