simplify_sparql_results: make results minimization of single var resu…

…lts optional

docs/simplify_sparql_results.md

@@ -58,10 +58,13 @@ With [SPARQL queries](sparql_query.md) such as [this one](https://github.com/max
   }
 ]
 ```
-That's still hairy, because we requested 3 variables, but this gets even simpler if there is only one variable!
-Say instead of `"vars" : [ "author", "authorLabel", "birth" ]`, we only ask for `"vars" : [ "author" ]`, the output of `simplify.sparqlResults` will be:
-```json
-["Q3731207"]
+That's still hairy, because we requested 3 variables, but that can get even simpler if there is only one variable!
+Say instead of `"vars" : [ "author", "authorLabel", "birth" ]`, we only ask for `"vars" : [ "author" ]`:
+```js
+simplify.sparqlResults(results)
+// => [ { "author": "Q3731207" } ]
+simplify.sparqlResults(results, { minimize: true })
+// => [ "Q3731207" ]
 ```
 And then to make it even more simpler, we can... hum no, that's all we got.
 
@@ -80,3 +83,17 @@ promiseRequest(url)
 .then(wdk.simplify.sparqlResults)
 .then(simplifiedResults => { // do awesome stuffs here })
 ```
+
+## options
+
+### minimize
+> Default: `false`
+
+When only one variable is requested, set minimize to `true`, the simplified results will consist of an array of this variable values, instead of an array of objects.
+```js
+wdk.simplify.sparqlResults(results, { minimize: true })
+// => [ "Q112983", "Q185598", "Q3879286" ]
+
+wdk.simplify.sparqlResults(results, { minimize: false })
+// => [ { item: "Q112983" }, { item: "Q185598" }, { item: "Q3879286" } ]
+```

lib/helpers/simplify_sparql_results.js

@@ -1,10 +1,10 @@
-module.exports = function (input) {
+module.exports = function (input, options = {}) {
   if (typeof input === 'string') input = JSON.parse(input)
 
   const { vars } = input.head
   const results = input.results.bindings
 
-  if (vars.length === 1) {
+  if (vars.length === 1 && options.minimize === true) {
     const varName = vars[0]
     return results
     .map(result => parseValue(result[varName]))

test/simplify_sparql_results.js

@@ -9,7 +9,6 @@ const sparqlResultsWithOptionalValues = require('./data/sparql_results_with_opti
 const sparqlResultsWithStatements = require('./data/sparql_results_with_statements.json')
 const resultsWithLabelsDescriptionsAndAliases = require('./data/results_with_labels_descriptions_and_aliases.json')
 const { cloneDeep } = require('lodash')
-const guidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
 
 describe('wikidata simplify SPARQL results', function () {
   describe('common', function () {
@@ -28,35 +27,43 @@ describe('wikidata simplify SPARQL results', function () {
     })
   })
 
-  describe('single var', function () {
-    it('should return an array of results values, filtering out blank nodes', function (done) {
-      const output = simplify(singleVarData)
-      output[0].should.equal('Q112983')
-      output.forEach(result => helpers.isEntityId(result).should.be.true())
-      done()
-    })
+  it('should return an array of results objects', function (done) {
+    const output = simplify(multiVarsData)
+    output[0].should.be.an.Object()
+    output[0].entity.value.should.equal('Q3731207')
+    output[0].entity.label.should.equal('Ercole Patti')
+    output[0].year.should.equal(1903)
+    done()
   })
 
-  describe('multi vars', function () {
-    it('should return an array of results objects', function (done) {
-      const output = simplify(multiVarsData)
-      output[0].should.be.an.Object()
-      output[0].entity.value.should.equal('Q3731207')
-      output[0].entity.label.should.equal('Ercole Patti')
-      output[0].year.should.equal(1903)
-      done()
-    })
+  it('should not throw when the datatype is missing', function (done) {
+    const output = simplify(noDatatypeData)
+    output[0].year.should.equal('1937')
+    done()
+  })
 
-    it('should not throw when the datatype is missing', function (done) {
-      const output = simplify(noDatatypeData)
-      output[0].year.should.equal('1937')
+  it('should not throw when an optional variable has no result', function (done) {
+    const result = simplify(sparqlResultsWithOptionalValues)[0]
+    result.composer.should.be.an.Object()
+    should(result.genre).not.be.ok()
+    done()
+  })
+
+  describe('minimize', function () {
+    it('should return an array of results values, filtering out blank nodes', function (done) {
+      const output = simplify(singleVarData, { minimize: true })
+      output[0].should.equal('Q112983')
+      output.forEach(result => helpers.isEntityId(result).should.be.true())
       done()
     })
 
-    it('should not throw when an optional variable has no result', function (done) {
-      const result = simplify(sparqlResultsWithOptionalValues)[0]
-      result.composer.should.be.an.Object()
-      should(result.genre).not.be.ok()
+    it('should return an array of results value object', function (done) {
+      const output = simplify(singleVarData, { minimize: false })
+      output[0].should.deepEqual({ genre: 'Q112983' })
+      output.forEach(result => {
+        result.should.be.an.Object()
+        if (result.genre) helpers.isEntityId(result.genre).should.be.true()
+      })
       done()
     })
   })
@@ -116,12 +123,8 @@ describe('wikidata simplify SPARQL results', function () {
   describe('statements', function () {
     it('should convert statement URIs into claims GUIDs', done => {
       const rawResults = cloneDeep(sparqlResultsWithStatements)
-      const results = simplify(rawResults)
-      results.forEach(result => {
-        const [ qid, rest ] = result.split('$')
-        helpers.isItemId(qid.toUpperCase()).should.be.true()
-        guidPattern.test(rest.toLowerCase()).should.be.true()
-      })
+      const results = simplify(rawResults, { minimize: true })
+      results.forEach(result => helpers.isGuid(result).should.be.true())
       done()
     })
   })