Merge pull request #170 from olvidalo/feat/query-params

feat: allow to pass parameters when executing query

README.md

@@ -363,7 +363,16 @@ The filename extension that will be used for XQuery result files emitted by
 Type: `string`
 Default: `'xml'`
 
-#### Example
+##### queryParams
+
+Query params passed to the eXist-db XMLRPC API
+(https://exist-db.org/exist/apps/doc/devguide_xmlrpc). Can be used to pass
+query variables (see Example 2).
+
+Type: `Object`
+Default: `{}`
+
+#### Example 1
 
 Upload a collection index configuration file and re-index the collection
 
@@ -411,6 +420,51 @@ function reindex () {
 exports.default = series(deployCollectionXConf, reindex)
 ```
 
+#### Example 2
+
+Pass a variable to the XQuery script.
+
+*scripts/var.xq*
+
+```xquery
+(: optionally declare the variable as external :)
+declare variable $someVariable external;
+
+<result>{ $someVariable }</result>
+```
+
+*gulpfile.js*
+
+```js
+const { src, dest } = require('gulp')
+const { createClient } = require('@existdb/gulp-exist')
+
+// override some default connection options
+const exist = createClient({
+    basic_auth: {
+        user: "admin",
+        pass: ""
+    }
+})
+
+// set `variables` query parameter
+const queryConfig = {
+	queryParams: {
+	    variables: {
+	        someVariable: "some value"
+	    }
+	}
+}
+
+function runQueryWithVariable () {
+	return src('scripts/var.xq', {cwd: '.'})
+		.pipe(exist.query(queryConfig))
+        .pipe(dest('logs'))
+}
+
+exports.default = runQueryWithVarible
+```
+
 ## Define Custom Mime Types
 
 Override the mime type used to store files in exist based on their extension.

index.js

@@ -70,14 +70,16 @@ const defaultUploadOptions = {
  * @typedef {Object} GulpExistQueryOptions
  * @prop {boolean} [printXqlResults] default: true
  * @prop {"xml"|"json"|string} xqlOutputExt the file extension the results are written to
+ * @prop {Object} queryParams query parameters passed to eXist-db
  */
 
 /**
  * @type {GulpExistQueryOptions}
  */
 const defaultQueryOptions = {
   printXqlResults: true,
-  xqlOutputExt: 'xml'
+  xqlOutputExt: 'xml',
+  queryParams: {}
 }
 
 const isWin = os.platform() === 'win32'
@@ -223,7 +225,7 @@ function query (client, options) {
 
     log('Running XQuery on server: ' + file.relative)
 
-    client.queries.readAll(file.contents, {})
+    client.queries.readAll(file.contents, conf.queryParams)
       .then(function (result) {
         const resultBuffer = Buffer.concat(result.pages)
         if (conf.printXqlResults) {

spec/files/test-variables.xql

@@ -0,0 +1,8 @@
+xquery version "3.0";
+
+declare option exist:serialize "method=json media-type=text/javascript";
+
+declare variable $variable external;
+
+(: return value of $variable that should have been set in the query parameters:)
+$variable

spec/query.js

@@ -47,3 +47,25 @@ test('run query, expect json', function (t) {
     .on('error', e => t.fail(e))
     .on('finish', _ => t.end())
 })
+
+test('run query with variables', function (t) {
+  const testClient = createClient(connectionOptions)
+  return src('test-variables.xql', srcOptions)
+    .pipe(testClient.query({
+      target: targetCollection,
+      queryParams: {
+        variables: {
+          variable: 'test'
+        }
+      }
+    }))
+    .on('data', function (d) {
+      const contents = d.contents.toString()
+
+      // inspect the results
+      // result should be the string set by the variables object in the query params
+      t.equal(contents, 'test', 'variable has been set')
+    })
+    .on('error', e => t.fail(e))
+    .on('finish', _ => t.end())
+})