Replaced next and links for a res object, updated docs and tests

CHANGELOG.md

@@ -1,3 +1,7 @@
+2.0.0 / 2016-03-04
+------------------
+- provide links, next and more attributes as a single response object, see: https://github.com/jprichardson/node-google/pull/38
+
 1.5.0 / 2016-02-22
 ------------------
 - use https, see: https://github.com/jprichardson/node-google/pull/35

README.md

@@ -33,17 +33,18 @@ var google = require('google')
 google.resultsPerPage = 25
 var nextCounter = 0
 
-google('node.js best practices', function (err, next, links){
+google('node.js best practices', function (err, res){
   if (err) console.error(err)
 
-  for (var i = 0; i < links.length; ++i) {
-    console.log(links[i].title + ' - ' + links[i].link) // link.href is an alias for link.link
-    console.log(links[i].description + "\n")
+  for (var i = 0; i < res.links.length; ++i) {
+    var link = res.links[i];
+    console.log(link.title + ' - ' + link.href)
+    console.log(link.description + "\n")
   }
 
   if (nextCounter < 4) {
     nextCounter += 1
-    if (next) next()
+    if (res.next) res.next()
   }
 })
 ```
@@ -77,7 +78,7 @@ google.lang = 'de'
 google.tld = 'de'
 google.nextText = 'Weiter'
 
-google('node.js best practices', function (err, next, links){
+google('node.js best practices', function (err, res){
   …
 })
 ```
@@ -105,11 +106,42 @@ google.requestOptions = {
   }
 }
 
-google('node.js best practices', function (err, next, links){
+google('node.js best practices', function (err, res){
   …
 })
 ```
 
+The response object
+-------
+
+The provided callback will receive a response object as second argument, it has these properties:
+
+- `url`: The URL requested from Google for this search and page
+- `query`: The search provided on this call
+- `start`: The index of the first link across the links of all pages
+- `links`: An array with all the link objects
+- `body`: The HTML of the loaded page
+- `$`: A cheerio instance of the loaded page
+
+
+Updating from 1.x
+-------
+
+The only backwards-incompatible change from 1.x is that the callback received 3 arguments:
+```js
+google('...', function (err, next, links) {
+  links.forEach(function(link) { ... })
+  if (next) next()
+})
+```
+
+And it now receives a single `res` object. The above code should be rewritten to:
+```js
+google('...', function (err, res) {
+  res.links.forEach(function(link) { ... })
+  if (res.next) res.next()
+})
+```
 
 License
 -------

lib/google.js

@@ -51,7 +51,14 @@ var igoogle = function (query, start, callback) {
   request(requestOptions, function (err, resp, body) {
     if ((err == null) && resp.statusCode === 200) {
       var $ = cheerio.load(body)
-      var links = []
+      var res = {
+        url: newUrl,
+        query: query,
+        start: start,
+        links: [],
+        $: $,
+        body: body
+      }
 
       $(itemSel).each(function (i, elem) {
         var linkElem = $(elem).find(linkSel)
@@ -72,17 +79,16 @@ var igoogle = function (query, start, callback) {
         $(descElem).find('div').remove()
         item.description = $(descElem).text()
 
-        links.push(item)
+        res.links.push(item)
       })
 
-      var nextFunc = null
       if ($(nextSel).last().text() === google.nextText) {
-        nextFunc = function () {
+        res.next = function () {
           igoogle(query, start + google.resultsPerPage, callback)
         }
       }
 
-      callback(null, nextFunc, links)
+      callback(null, res)
     } else {
       callback(new Error('Error on response' + (resp ? ' (' + resp.statusCode + ')' : '') + ':' + err + ' : ' + body), null, null)
     }

test/google.test.js

@@ -42,14 +42,21 @@ describe('+ google()', function () {
       done()
     }
 
-    google(query, function (err, next, links) {
+    google(query, function (err, res) {
       assert.ifError(err)
+      assert.equal(res.query, 'Microsoft')
+      assert.equal(typeof res.$, 'function')
+      assert.equal(typeof res.body, 'string')
+      assert.equal(typeof res.url, 'string')
+      assert.equal(res.start, nextCounter * google.resultsPerPage)
+      assert.equal(typeof res.links, 'object')
+      assert.ok(res.links.length <= google.resultsPerPage)
       // console.log('L: ' + links.length)
-      allLinks = allLinks.concat(links)
+      allLinks = allLinks.concat(res.links)
       if (nextCounter < 2) {
-        if (next) {
+        if (res.next) {
           nextCounter += 1
-          next()
+          res.next()
         } else {
           finished()
         }
@@ -70,9 +77,16 @@ describe('+ google()', function () {
       }
 
       google.resultsPerPage = 100
-      google(query, function (err, next, links) {
+      google(query, function (err, res) {
         assert.ifError(err)
-        allLinks = allLinks.concat(links)
+        assert.equal(res.query, 'Microsoft')
+        assert.equal(typeof res.$, 'function')
+        assert.equal(typeof res.body, 'string')
+        assert.equal(typeof res.url, 'string')
+        assert.equal(res.start, 0)
+        assert.equal(typeof res.links, 'object')
+        assert.ok(res.links.length <= google.resultsPerPage)
+        allLinks = allLinks.concat(res.links)
         // console.log(allLinks.length)
         finished()
       })
@@ -92,9 +106,16 @@ describe('+ google()', function () {
 
       google.resultsPerPage = 10
       google.timeSpan = timeFrame
-      google(query, function (err, next, links) {
+      google(query, function (err, res) {
         assert.ifError(err)
-        allLinks = allLinks.concat(links)
+        assert.equal(res.query, 'Microsoft')
+        assert.equal(typeof res.$, 'function')
+        assert.equal(typeof res.body, 'string')
+        assert.equal(typeof res.url, 'string')
+        assert.equal(res.start, 0)
+        assert.equal(typeof res.links, 'object')
+        assert.ok(res.links.length <= google.resultsPerPage)
+        allLinks = allLinks.concat(res.links)
         finished()
       })
     })
@@ -114,13 +135,13 @@ describe('+ google()', function () {
       google.resultsPerPage = 25
       google.lang = 'it'
       google.nextText = 'Avanti'
-      google(query, function (err, next, links) {
+      google(query, function (err, res) {
         assert.ifError(err)
-        allLinks = allLinks.concat(links)
+        allLinks = allLinks.concat(res.links)
         if (nextCounter < 2) {
-          if (next) {
+          if (res.next) {
             nextCounter += 1
-            next()
+            res.next()
           } else {
             finished()
           }
@@ -144,9 +165,16 @@ describe('+ google()', function () {
 
       google.resultsPerPage = 10
       google.timeSpan = timeFrame
-      google(query, 2, function (err, next, links) {
+      google(query, 2, function (err, res) {
         assert.ifError(err)
-        allLinks = allLinks.concat(links)
+        assert.equal(res.query, 'Microsoft')
+        assert.equal(typeof res.$, 'function')
+        assert.equal(typeof res.body, 'string')
+        assert.equal(typeof res.url, 'string')
+        assert.equal(res.start, 2)
+        assert.equal(typeof res.links, 'object')
+        assert.ok(res.links.length <= google.resultsPerPage)
+        allLinks = allLinks.concat(res.links)
         finished()
       })
     })